From ac449612af9aa0aa1844caf2845fe49a0c52025a Mon Sep 17 00:00:00 2001
From: PrinceThummar011 <princethummar011@gmail.com>
Date: Thu, 1 Oct 2026 17:57:58 +0530
Subject: [PATCH 01/53] fix(mcp): handle expired/unknown OAuth state in
 callback with dedicated expired page (#5598)

---
 routes/mcp/mcp_routes.py |  34 ++++++-
 tests/test_mcp_oauth.py  | 186 +++++++++++++++++++++++++++++++++++++++
 2 files changed, 216 insertions(+), 4 deletions(-)

diff --git a/routes/mcp/mcp_routes.py b/routes/mcp/mcp_routes.py
index 0e2b30276..385cf09e3 100644
--- a/routes/mcp/mcp_routes.py
+++ b/routes/mcp/mcp_routes.py
@@ -487,19 +487,32 @@ def setup_mcp_routes(mcp_manager: McpManager):
             db.close()
 
     @router.get("/oauth/callback")
-    async def oauth_callback(code: str, state: str, request: Request):
+    async def oauth_callback(code: str = "", state: str = "", request: Request = None):
         """Handle OAuth callback. Generic MCP OAuth flows resolve via the
         pending-state registry; Google flows fall through to the legacy path."""
-        require_admin(request)
         from src.mcp_oauth import resolve_pending
-        if resolve_pending(state, code):
+        if state and code and resolve_pending(state, code):
             return HTMLResponse(_oauth_result_page(
                 "Authorization Successful",
                 "The MCP server is connecting. You can close this window and return to Odysseus.",
                 success=True,
             ))
+
         # Legacy Google path: state is the server_id
-        return await _exchange_and_connect(state, code, request)
+        if state:
+            db = SessionLocal()
+            try:
+                srv = db.query(McpServer).filter(McpServer.id == state).first()
+                if srv and srv.oauth_config:
+                    require_admin(request)
+                    return await _exchange_and_connect(state, code, request)
+            finally:
+                db.close()
+
+        return HTMLResponse(_oauth_result_page(
+            "Authorization Expired",
+            "This authorization round has expired. Press Reconnect in Odysseus and try again.",
+        ), status_code=400)
 
     @router.post("/oauth/exchange/{server_id}")
     async def oauth_exchange(server_id: str, request: Request, callback_url: str = Form(...)):
@@ -525,6 +538,19 @@ def setup_mcp_routes(mcp_manager: McpManager):
                 success=True,
             ))
 
+        db = SessionLocal()
+        try:
+            srv = db.query(McpServer).filter(McpServer.id == server_id).first()
+            if not srv:
+                return HTMLResponse(_oauth_result_page("Error", "Server not found."), status_code=404)
+            if not srv.oauth_config:
+                return HTMLResponse(_oauth_result_page(
+                    "Authorization Expired",
+                    "This authorization round has expired. Press Reconnect in Odysseus and try again.",
+                ), status_code=400)
+        finally:
+            db.close()
+
         return await _exchange_and_connect(server_id, code, request)
 
     async def _exchange_and_connect(server_id: str, code: str, request: Request):
diff --git a/tests/test_mcp_oauth.py b/tests/test_mcp_oauth.py
index 6a8e21876..24f52820e 100644
--- a/tests/test_mcp_oauth.py
+++ b/tests/test_mcp_oauth.py
@@ -264,3 +264,189 @@ def test_launchers_export_the_port_they_serve_on():
         text = (_repo_root() / name).read_text(encoding="utf-8")
         assert uvicorn_flag in text, f"{name}: launcher no longer passes {uvicorn_flag}"
         assert export in text, f"{name}: serves on a port the app cannot read back"
+
+
+# ── Callback & Exchange Expired State Handling ───────────────────
+
+def test_oauth_callback_expired_state_returns_dedicated_expired_page(monkeypatch):
+    """An unknown or expired generic MCP OAuth state in the callback must return
+    the dedicated 'Authorization Expired' page instead of a bare 403 'Admin only'
+    or a 404 'Server not found'."""
+    from unittest.mock import MagicMock
+    from fastapi import FastAPI, HTTPException
+    from fastapi.testclient import TestClient
+    from routes.mcp import mcp_routes
+
+    # Simulate unauthenticated request that would fail admin check if invoked
+    def _deny_admin(request):
+        raise HTTPException(403, "Admin only")
+
+    monkeypatch.setattr(mcp_routes, "require_admin", _deny_admin)
+
+    # Empty DB / no matching server
+    class FakeQuery:
+        def filter(self, *a):
+            return self
+
+        def first(self):
+            return None
+
+    class FakeSession:
+        def query(self, *a):
+            return FakeQuery()
+
+        def close(self):
+            pass
+
+    monkeypatch.setattr(mcp_routes, "SessionLocal", lambda: FakeSession())
+
+    app = FastAPI()
+    manager = MagicMock()
+    router = mcp_routes.setup_mcp_routes(manager)
+    app.include_router(router)
+    client = TestClient(app)
+
+    # Both code and state are provided, but state is not in _pending (expired/unknown)
+    resp = client.get("/api/mcp/oauth/callback?code=some-code&state=expired-state-123")
+    assert resp.status_code == 400
+    assert "Authorization Expired" in resp.text
+    assert (
+        "This authorization round has expired. Press Reconnect in Odysseus and try again."
+        in resp.text
+    )
+    # Ensure it did not return the bare 403 "Admin only"
+    assert "Admin only" not in resp.text
+
+
+def test_oauth_callback_active_pending_state_succeeds_without_admin(monkeypatch):
+    """An active pending generic MCP OAuth state resolves without requiring admin auth."""
+    from unittest.mock import MagicMock
+    from fastapi import FastAPI, HTTPException
+    from fastapi.testclient import TestClient
+    from routes.mcp import mcp_routes
+
+    # Admin check fails if invoked
+    def _deny_admin(request):
+        raise HTTPException(403, "Admin only")
+
+    monkeypatch.setattr(mcp_routes, "require_admin", _deny_admin)
+
+    app = FastAPI()
+    manager = MagicMock()
+    router = mcp_routes.setup_mcp_routes(manager)
+    app.include_router(router)
+    client = TestClient(app)
+
+    async def go():
+        fut = mcp_oauth.register_pending("pending-round-1")
+        resp = client.get("/api/mcp/oauth/callback?code=auth-code-xyz&state=pending-round-1")
+        assert resp.status_code == 200
+        assert "Authorization Successful" in resp.text
+        code, state = await asyncio.wait_for(fut, timeout=1)
+        assert code == "auth-code-xyz"
+        assert state == "pending-round-1"
+
+    asyncio.run(go())
+
+
+def test_oauth_callback_legacy_google_server_requires_admin(monkeypatch):
+    """Legacy Google OAuth callbacks (where state is server_id of a server with
+    oauth_config) still enforce require_admin."""
+    import json
+    from unittest.mock import MagicMock
+    from fastapi import FastAPI, HTTPException
+    from fastapi.testclient import TestClient
+    from routes.mcp import mcp_routes
+    from core.database import McpServer
+
+    # Server exists in DB with Google oauth_config
+    google_srv = McpServer(
+        id="google-srv-1",
+        name="Google Workspace",
+        oauth_config=json.dumps({"provider": "google", "keys_file": "k.json", "token_file": "t.json"}),
+    )
+
+    class FakeQuery:
+        def filter(self, *a):
+            return self
+
+        def first(self):
+            return google_srv
+
+    class FakeSession:
+        def query(self, *a):
+            return FakeQuery()
+
+        def close(self):
+            pass
+
+    monkeypatch.setattr(mcp_routes, "SessionLocal", lambda: FakeSession())
+
+    # When require_admin denies, 403 is raised for the legacy Google path
+    def _deny_admin(request):
+        raise HTTPException(403, "Admin only")
+
+    monkeypatch.setattr(mcp_routes, "require_admin", _deny_admin)
+
+    app = FastAPI()
+    manager = MagicMock()
+    router = mcp_routes.setup_mcp_routes(manager)
+    app.include_router(router)
+    client = TestClient(app)
+
+    resp = client.get("/api/mcp/oauth/callback?code=code-123&state=google-srv-1")
+    assert resp.status_code == 403
+    assert "Admin only" in resp.text
+
+
+def test_oauth_exchange_expired_generic_state_returns_expired_page(monkeypatch):
+    """Remote paste-back flow for a generic MCP server returns the dedicated expired
+    page when the state is no longer pending, instead of 'No OAuth config.'."""
+    from unittest.mock import MagicMock
+    from fastapi import FastAPI
+    from fastapi.testclient import TestClient
+    from routes.mcp import mcp_routes
+    from core.database import McpServer
+
+    monkeypatch.setattr(mcp_routes, "require_admin", lambda r: None)
+
+    # Server exists in DB without oauth_config (generic MCP server)
+    generic_srv = McpServer(
+        id="http-srv-1",
+        name="Remote HTTP MCP",
+        oauth_config=None,
+    )
+
+    class FakeQuery:
+        def filter(self, *a):
+            return self
+
+        def first(self):
+            return generic_srv
+
+    class FakeSession:
+        def query(self, *a):
+            return FakeQuery()
+
+        def close(self):
+            pass
+
+    monkeypatch.setattr(mcp_routes, "SessionLocal", lambda: FakeSession())
+
+    app = FastAPI()
+    manager = MagicMock()
+    router = mcp_routes.setup_mcp_routes(manager)
+    app.include_router(router)
+    client = TestClient(app)
+
+    resp = client.post(
+        "/api/mcp/oauth/exchange/http-srv-1",
+        data={"callback_url": "http://localhost:7000/api/mcp/oauth/callback?code=code-1&state=expired-state"},
+    )
+    assert resp.status_code == 400
+    assert "Authorization Expired" in resp.text
+    assert (
+        "This authorization round has expired. Press Reconnect in Odysseus and try again."
+        in resp.text
+    )
+    assert "No OAuth config." not in resp.text

From 35e3b298d8f84a68f147053e8367121b06768b09 Mon Sep 17 00:00:00 2001
From: ShahabAhmed01 <192491541+ShahabAhmed01@users.noreply.github.com>
Date: Sat, 3 Oct 2026 23:23:36 +0500
Subject: [PATCH 02/53] fix(scheduler): fall back to defaults for non-numeric
 research settings
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The scheduled-research task reads research_max_tokens,
research_extraction_timeout_seconds, and research_extraction_concurrency
with bare int() casts and no guard. A hand-edited or agent-written
data/settings.json value like {"research_max_tokens": "invalid"} raised
ValueError and killed every scheduled research run until settings.json was
fixed by hand (#5049). src/research_handler.py already guards the same reads
defensively (_bounded_int); this mirrors that for the scheduler.

Wrap the three reads in try/except (TypeError, ValueError) falling back to
the documented defaults 8192 / 90 / 3. Valid values (numeric strings like
"4096") still parse; the change is limited to the scheduler's reads (agent_loop
sites are tracked separately in #5051).

Child of maintainer subtracker #5335 (RaresKeY) whose acceptance criteria state:
"Non-numeric agent/scheduler settings fall back safely instead of crashing or
silently degrading." Prior PR #5050 attempted the same fix but was closed
unmerged in the 2026-07-23 repo-transfer bulk close and never resubmitted —
redoing it with credit.

Fixes #5049.
---
 src/task_scheduler.py                         | 36 ++++++++-
 .../test_scheduler_research_settings_guard.py | 79 +++++++++++++++++++
 2 files changed, 112 insertions(+), 3 deletions(-)
 create mode 100644 tests/test_scheduler_research_settings_guard.py

diff --git a/src/task_scheduler.py b/src/task_scheduler.py
index f2f59d65e..89c9217fd 100644
--- a/src/task_scheduler.py
+++ b/src/task_scheduler.py
@@ -342,6 +342,36 @@ def _normalize_chat_endpoint(url: str) -> str:
         return url
 
 
+def _resolve_research_settings(get_setting_fn):
+    """Resolve the scheduled-research settings with crash-proof fallbacks.
+
+    A hand-edited or agent-written data/settings.json can hold non-numeric
+    values for the research_* keys; the bare int() reads previously raised
+    inside TaskScheduler._execute_research_task and killed every scheduled
+    research run until settings.json was fixed by hand (#5049).
+    src/research_handler.py already guards the same reads defensively —
+    this mirrors that for the scheduler. Valid values pass through
+    unchanged (numeric strings like "4096" still parse).
+    """
+    try:
+        max_tokens = int(get_setting_fn("research_max_tokens", 8192))
+    except (TypeError, ValueError):
+        max_tokens = 8192
+    try:
+        extraction_timeout = int(
+            get_setting_fn("research_extraction_timeout_seconds", 90) or 90
+        )
+    except (TypeError, ValueError):
+        extraction_timeout = 90
+    try:
+        extraction_concurrency = int(
+            get_setting_fn("research_extraction_concurrency", 3) or 3
+        )
+    except (TypeError, ValueError):
+        extraction_concurrency = 3
+    return max_tokens, extraction_timeout, extraction_concurrency
+
+
 class TaskScheduler:
     def __init__(self, session_manager):
         self._session_manager = session_manager
@@ -2068,9 +2098,9 @@ class TaskScheduler:
         except Exception:
             pass
 
-        max_tokens = int(get_setting("research_max_tokens", 8192))
-        extraction_timeout = int(get_setting("research_extraction_timeout_seconds", 90) or 90)
-        extraction_concurrency = int(get_setting("research_extraction_concurrency", 3) or 3)
+        max_tokens, extraction_timeout, extraction_concurrency = (
+            _resolve_research_settings(get_setting)
+        )
 
         researcher = DeepResearcher(
             llm_endpoint=endpoint_url,
diff --git a/tests/test_scheduler_research_settings_guard.py b/tests/test_scheduler_research_settings_guard.py
new file mode 100644
index 000000000..0cdfa2b87
--- /dev/null
+++ b/tests/test_scheduler_research_settings_guard.py
@@ -0,0 +1,79 @@
+"""Guarded resolution of scheduled-research settings (#5049).
+
+The scheduler reads ``research_max_tokens`` /
+``research_extraction_timeout_seconds`` / ``research_extraction_concurrency``
+from settings.json with bare ``int()`` casts. A hand-edited value like
+``{"research_max_tokens": "invalid"}`` used to raise inside
+``TaskScheduler._execute_research_task`` and kill every scheduled research
+run until settings.json was fixed by hand.
+
+``_resolve_research_settings`` must fall back to the documented defaults
+(8192 / 90 / 3) for non-numeric input while preserving valid-value behavior
+(numeric strings still parse). ``src/research_handler.py`` already guards the
+same reads defensively; this is the scheduler's equivalent.
+"""
+
+from __future__ import annotations
+
+from src.task_scheduler import _resolve_research_settings
+
+
+def _fake_get_setting(values):
+    """A get_setting stand-in backed by a plain dict."""
+
+    def get(key, default=None):
+        return values.get(key, default)
+
+    return get
+
+
+def test_non_numeric_values_fall_back_to_documented_defaults():
+    get = _fake_get_setting(
+        {
+            "research_max_tokens": "invalid",
+            "research_extraction_timeout_seconds": "bogus",
+            "research_extraction_concurrency": "not-a-number",
+        }
+    )
+
+    assert _resolve_research_settings(get) == (8192, 90, 3)
+
+
+def test_none_values_fall_back_to_documented_defaults():
+    get = _fake_get_setting(
+        {
+            "research_max_tokens": None,
+            "research_extraction_timeout_seconds": None,
+            "research_extraction_concurrency": None,
+        }
+    )
+
+    assert _resolve_research_settings(get) == (8192, 90, 3)
+
+
+def test_numeric_strings_still_parse():
+    get = _fake_get_setting(
+        {
+            "research_max_tokens": "4096",
+            "research_extraction_timeout_seconds": "45",
+            "research_extraction_concurrency": "2",
+        }
+    )
+
+    assert _resolve_research_settings(get) == (4096, 45, 2)
+
+
+def test_missing_keys_keep_documented_defaults():
+    assert _resolve_research_settings(_fake_get_setting({})) == (8192, 90, 3)
+
+
+def test_valid_ints_pass_through():
+    get = _fake_get_setting(
+        {
+            "research_max_tokens": 2048,
+            "research_extraction_timeout_seconds": 120,
+            "research_extraction_concurrency": 6,
+        }
+    )
+
+    assert _resolve_research_settings(get) == (2048, 120, 6)

From b49f66cb7a48af8531111fed395867ed8c835ebc Mon Sep 17 00:00:00 2001
From: Boody <69832947+bitboody@users.noreply.github.com>
Date: Mon, 12 Oct 2026 15:03:50 +0300
Subject: [PATCH 03/53] Add community and growth section to README

Updated the README to include community and growth section with Trendshift and star history badges.
---
 README.md | 34 ++++++++++++++++++++++++++--------
 1 file changed, 26 insertions(+), 8 deletions(-)

diff --git a/README.md b/README.md
index 4ec557b11..06d4b5f1e 100644
--- a/README.md
+++ b/README.md
@@ -74,15 +74,33 @@ Odysseus is a self-hosted workspace with powerful local tools. Keep auth enabled
 
 Deployment details are in the [setup guide](website/setup.md#security-notes).
 
-## Star History
+## Community & Growth
 
-<a href="https://star-history.dera.page/#odysseus-dev/odysseus&type=date&legend=top-left">
- <picture>
-   <source media="(prefers-color-scheme: dark)" srcset="https://star-history.dera.page/svg?repos=odysseus-dev/odysseus&type=date&theme=dark&legend=top-left" />
-   <source media="(prefers-color-scheme: light)" srcset="https://star-history.dera.page/svg?repos=odysseus-dev/odysseus&type=date&legend=top-left" />
-   <img alt="Star History Chart" src="https://star-history.dera.page/svg?repos=odysseus-dev/odysseus&type=date&legend=top-left" />
- </picture>
-</a>
+<p align="center">
+  <a href="https://trendshift.io/repositories/43167">
+      <a href="https://trendshift.io/repositories/43167?utm_source=trendshift-badge&amp;utm_medium=badge&amp;utm_campaign=badge-trendshift-43167" target="_blank" rel="noopener noreferrer"><img src="https://trendshift.io/api/badge/trendshift/repositories/43167/monthly" alt="odysseus-dev%2Fodysseus | Trendshift" width="230"/></a>
+  </a>
+</p>
+
+<p align="center">
+  <a href="https://star-history.dera.page/#odysseus-dev/odysseus&type=date&legend=top-left">
+    <picture>
+      <source
+        media="(prefers-color-scheme: dark)"
+        srcset="https://star-history.dera.page/svg?repos=odysseus-dev/odysseus&type=date&theme=dark&legend=top-left"
+      />
+      <source
+        media="(prefers-color-scheme: light)"
+        srcset="https://star-history.dera.page/svg?repos=odysseus-dev/odysseus&type=date&legend=top-left"
+      />
+      <img
+        src="https://star-history.dera.page/svg?repos=odysseus-dev/odysseus&type=date&legend=top-left"
+        alt="Odysseus GitHub star history"
+        width="100%"
+      />
+    </picture>
+  </a>
+</p>
 
 ## License
 

From 8feb50e89468235cd3e0986da80edbd3acaf2c40 Mon Sep 17 00:00:00 2001
From: Beyrem Weslati <74115035+beyremweslati@users.noreply.github.com>
Date: Tue, 13 Oct 2026 18:57:19 +0100
Subject: [PATCH 04/53] feat(notes): attach selected Notes/Todos as Agent
 context (#6495)

* feat: add Notes and Todos as agent chat context

- Send selected Note/Todo IDs from the Notes UI
- Load selected notes with owner scoping in chat routes
- Format note content and checklist items for the model
- Inject selected notes as untrusted chat context
- Add a selected-context indicator beside Shell Access
- Keep selected context associated with the active chat session

* Improved selected notes context handling and discouragin redundant note lookup and permission requests

* Fix selected notes UI when switching chats

* fix(notes): harden selected context lifecycle and validation

---------

Co-authored-by: Alexandre Teixeira <111787685+alteixeira20@users.noreply.github.com>
---
 routes/chat_helpers.py               | 18 ++++++
 routes/chat_routes.py                | 83 +++++++++++++++++++++++++++-
 src/agent_loop.py                    |  4 +-
 static/index.html                    | 15 +++++
 static/js/chat.js                    | 68 +++++++++++++++++++++++
 static/js/notes.js                   | 14 +++++
 static/js/sessions.js                | 15 +++++
 tests/selectedNotesContext.test.mjs  | 81 +++++++++++++++++++++++++++
 tests/test_selected_notes_context.py | 28 ++++++++++
 9 files changed, 324 insertions(+), 2 deletions(-)
 create mode 100644 tests/selectedNotesContext.test.mjs
 create mode 100644 tests/test_selected_notes_context.py

diff --git a/routes/chat_helpers.py b/routes/chat_helpers.py
index 472128eaf..7debf70b6 100644
--- a/routes/chat_helpers.py
+++ b/routes/chat_helpers.py
@@ -1010,6 +1010,7 @@ async def build_chat_context(
     chat_processor,
     message: str,
     session_id: str,
+    selected_notes_context: str | None = None,
     preset_id=None,
     att_ids: list = None,
     use_web=None,
@@ -1182,6 +1183,23 @@ async def build_chat_context(
     if search_context and allow_tool_preprocessing and not casual_low_signal:
         preface.append(untrusted_context_message("prefetched search context", search_context))
 
+    # Inject selected notes as context
+    if selected_notes_context:
+        selected_notes_context = (
+            "The following selected notes and todos are reference context explicitly chosen "
+            "by the user. Use them directly when relevant to the user's request. Do not "
+            "ask for permission to use this context, and do not call note-management "
+            "tools just to retrieve the same notes; use those tools only for a requested "
+            "change or when this context is insufficient.\n\n"
+            + selected_notes_context
+        )
+        preface.append(
+            untrusted_context_message(
+                "Selected notes and todos",
+                selected_notes_context,
+            )
+        )
+
     # YouTube transcripts
     for transcript in preprocessed.youtube_transcripts:
         preface.append(untrusted_context_message("youtube transcript", transcript))
diff --git a/routes/chat_routes.py b/routes/chat_routes.py
index e3f7bfa02..5a42d3351 100644
--- a/routes/chat_routes.py
+++ b/routes/chat_routes.py
@@ -58,7 +58,7 @@ from src.auth_helpers import (
 from routes.session_routes import _verify_session_owner
 from routes.document_helpers import _owner_session_filter
 from core.database import SessionLocal, get_session_mode, set_session_mode
-from core.database import Session as DBSession, ChatMessage as DBChatMessage
+from core.database import Session as DBSession, ChatMessage as DBChatMessage, Note
 from core.database import Document as DBDocument, ModelEndpoint
 from core.log_safety import redact_url
 from routes.research_routes import _resolve_research_endpoint
@@ -2153,6 +2153,68 @@ def _set_user_time_from_request(request: Request) -> None:
     except Exception:
         pass
 
+def _parse_selected_note_ids(raw) -> list[str]:
+    """Validate user-selected Note IDs before passing them to SQLAlchemy."""
+    if raw is None or raw == "":
+        return []
+    if not isinstance(raw, str) or len(raw) > 8192:
+        raise HTTPException(400, "Invalid selected_note_ids payload")
+    try:
+        parsed = json.loads(raw)
+    except (TypeError, ValueError) as exc:
+        raise HTTPException(400, "Invalid selected_note_ids JSON") from exc
+    if (
+        not isinstance(parsed, list)
+        or len(parsed) > 50
+        or any(
+            not isinstance(note_id, str)
+            or not note_id.strip()
+            or len(note_id) > 128
+            for note_id in parsed
+        )
+    ):
+        raise HTTPException(400, "selected_note_ids must be an array of up to 50 non-empty string IDs")
+    return list(dict.fromkeys(parsed))
+
+
+def _format_selected_notes_context(notes) -> str:
+    """Format selected Notes/Todos as reference context for the model."""
+    sections = []
+
+    for index, note in enumerate(notes, start=1):
+        lines = [
+            f"--- Selected Note {index} ---",
+            f"Title: {note.title or '(untitled)'}",
+            f"Type: {note.note_type or 'note'}",
+        ]
+
+        if note.content:
+            lines.extend([
+                "Content:",
+                str(note.content),
+            ])
+
+        if note.items:
+            try:
+                items = json.loads(note.items)
+            except (TypeError, json.JSONDecodeError):
+                items = []
+
+            if isinstance(items, list):
+                lines.append("Items:")
+                for item in items:
+                    if not isinstance(item, dict):
+                        continue
+
+                    status = "done" if item.get("done") else "pending"
+                    text = str(item.get("text") or "").strip()
+
+                    if text:
+                        lines.append(f"- [{status}] {text}")
+
+        sections.append("\n".join(lines))
+
+    return "\n\n".join(sections)
 
 def _resolve_prompt_thinking_mode(explicit_mode, preset_id, preset_manager):
     """Use an explicit request override, then fall back to the active preset."""
@@ -2423,6 +2485,8 @@ def setup_chat_routes(
         form_data = await request.form()
         message = form_data.get("message")
         session = form_data.get("session")
+        selected_note_ids = _parse_selected_note_ids(form_data.get("selected_note_ids"))
+
         attachments = form_data.get("attachments")
         use_web = form_data.get("use_web")
         use_research = form_data.get("use_research")
@@ -2730,6 +2794,22 @@ def setup_chat_routes(
                 current_rejected=workspace_rejected,
             )
             owner = effective_user(request)
+            selected_notes = []
+            if selected_note_ids:
+                notes_db = SessionLocal()
+                try:
+                    selected_notes = (
+                        notes_db.query(Note)
+                        .filter(
+                            Note.id.in_(selected_note_ids),
+                            Note.owner == owner,
+                        )
+                        .all()
+                    )
+                finally:
+                    notes_db.close()
+            selected_notes_context = _format_selected_notes_context(selected_notes)
+
             if tool_approval_id:
                 _reject_delegated_tool_approval(request)
                 from src.agent_runtime.authority import require_user_approval_request
@@ -3001,6 +3081,7 @@ def setup_chat_routes(
             sess, request, chat_handler, chat_processor,
             message=message,
             session_id=session,
+            selected_notes_context=selected_notes_context,
             preset_id=preset_id,
             att_ids=att_ids,
             use_web=use_web,
diff --git a/src/agent_loop.py b/src/agent_loop.py
index f3609b41b..6301e86a5 100644
--- a/src/agent_loop.py
+++ b/src/agent_loop.py
@@ -6933,6 +6933,7 @@ _AGENT_RULES = """\
 - If the user asks for multiple specific emails and you call `read_email` more than once, your final answer MUST include every successfully read email, clearly separated and linked by UID. Do not answer with only the last email you read.
 - Multiple email accounts: if tool output says "Other accounts" or the user asks "my Gmail?", "other inbox?", "work mail?", "custom domain mail?", or names any mailbox/account, DO NOT answer from memory. Call `list_email_accounts` if needed, then call `list_emails`/`read_email`/`bulk_email` with the exact `account` value for that mailbox. Account names are user-defined labels; if the user typo-matches a known account, use the closest listed account instead of claiming it does not exist. NEVER use `app_api` or `/api/email/accounts` to discover email accounts; that route is owner-filtered in tool context and can falsely return empty.
 - User identity facts/preferences ("my name is <name>", "I live in <place>", "I prefer concise replies", "call me <name>") → use `manage_memory` with action=add. NEVER use `manage_contact` for facts about the user unless the user explicitly says to create/update a contact and provides contact details such as an email or phone.
+- When the prompt contains "Selected notes and todos", treat that content as already-provided reference context. Use it directly when it answers the request; do not call `manage_notes` to list/search/view the same notes, and do not ask for permission merely to use the selected context. Call `manage_notes` only when the user requests a note change or the selected context is insufficient and a fresh lookup is needed.
 - "Create/add/write a note" / "notes" / "todos" / "remind me to X at <time>" → use `manage_notes`. Do NOT store notes in `manage_memory`; memory is for persistent facts/preferences about the user, not note content. For reminders, include a `due_date`; for todos, use `note_type=checklist` when appropriate.
 - "Do X every morning / daily / on a schedule / automatically" (e.g. "summarize my inbox every morning") → this is a request to CREATE A SCHEDULED TASK, not to do X once right now. Call `manage_tasks` with action=create (prompt = what to do, schedule + cron/time). Do NOT just perform the action inline this turn — the user wants it to recur. After creating, return a clickable `[Task name](#task-<id>)` link and tell them it'll run on schedule and show in the Tasks panel. If you also want to show a sample of this run, do that AFTER creating the task, not instead of it.
 - There is NO generic sleep / auto-wakeup / resume-after-this-turn primitive. Background jobs and subagent-style work should return a job/task id and notify the session automatically when finished; do not sleep or poll for their progress. If the user explicitly asks you to retry or do something later, call `manage_tasks` with action=create, `task_type=llm`, `schedule=once`, and a self-contained prompt. NEVER claim you will wake up, retry later, or handle something later unless a `manage_tasks` create call succeeds.
@@ -7041,6 +7042,7 @@ _AGENT_RULES = """\
 - After a tool fails, retry with a concrete fix or state what is blocking you.
 - Finish only when the user's concrete request is actually done, or clearly state that you are blocked.
 - User identity facts/preferences ("my name is X", "call me X", "I live in X") use `manage_memory`, not contacts.
+- When the prompt contains "Selected notes and todos", treat that content as already-provided reference context. Use it directly when it answers the request; do not call `manage_notes` to list/search/view the same notes, and do not ask for permission merely to use the selected context. Call `manage_notes` only when the user requests a note change or the selected context is insufficient and a fresh lookup is needed.
 """
 
 _API_AGENT_RULES = """\
@@ -7099,7 +7101,7 @@ _DOMAIN_RULES = {
 - After a successful serve, verify with `list_served_models`; if an external server is running but invisible, use `adopt_served_model`.""",
     "notes_calendar_tasks": """\
 ## Notes/calendar/tasks rules
-- Notes/todos/reminders use `manage_notes`, not memory.
+- Notes/todos/reminders use `manage_notes`, not memory. However, when the prompt contains "Selected notes and todos", those notes are already available as reference context: use them directly and do not list/search/view them again or ask permission to use them. Use `manage_notes` only for a requested change or when a fresh lookup is genuinely needed.
 - Calendar create/update/delete should call `manage_calendar` with `action=list_calendars` first.
 - Recurring/automatic/scheduled requests create a `manage_tasks` task; do not just perform the action once.""",
     "memory": """\
diff --git a/static/index.html b/static/index.html
index 7fb866c68..8557d54af 100644
--- a/static/index.html
+++ b/static/index.html
@@ -1178,6 +1178,21 @@
               <polyline points="4 17 10 11 4 5"/><line x1="12" y1="19" x2="20" y2="19"/>
             </svg>
           </button>
+          <!-- Selected Notes/Todos indicator -->
+          <button
+            type="button"
+            class="input-icon-btn tool-indicator"
+            title="Selected Notes/Todos context — click to clear"
+            id="selected-notes-context-btn"
+            aria-label="Clear selected Notes/Todos context"
+            style="display:none;"
+          >
+            <span id="selected-notes-context-count" style="font-size:11px;margin-left:2px;"></span>
+            <svg class="tool-indicator-x" width="10" height="10" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="3" stroke-linecap="round" aria-hidden="true">
+              <line x1="6" y1="6" x2="18" y2="18"/>
+              <line x1="18" y1="6" x2="6" y2="18"/>
+            </svg>
+          </button>
           <!-- Workspace indicator (hidden until a folder is set) -->
           <button type="button" class="input-icon-btn tool-indicator" title="Workspace - click to clear" id="workspace-indicator-btn" aria-label="Clear workspace" style="display:none;">
             <svg class="workspace-indicator-icon" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M3 7a2 2 0 0 1 2-2h4l2 2h8a2 2 0 0 1 2 2v8a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2z"/></svg>
diff --git a/static/js/chat.js b/static/js/chat.js
index bf779fa00..c42f5382b 100644
--- a/static/js/chat.js
+++ b/static/js/chat.js
@@ -65,6 +65,8 @@ import { invalidateSettings } from './appConfig.js';
   let _contextHeaderAnchorEl = null;
   let _contextHeaderPopupCleanup = null;
   let _pendingToolApproval = null;
+  const _selectedNoteIdsBySession = new Map();
+  let _pendingSelectedNoteIds = [];
   let _lastPrivateBrowserUrl = '';
   function _isPrivateBrowserTool(tool) {
     const name = String(tool || '').toLowerCase();
@@ -240,6 +242,46 @@ import { invalidateSettings } from './appConfig.js';
     _submitToolApprovalWhenIdle(_pendingToolApproval.approval_id);
   });
 
+  window.addEventListener('odysseus:notes-context-selected', (event) => {
+    const noteIds = event.detail?.noteIds;
+    if (!Array.isArray(noteIds) || noteIds.length === 0) return;
+
+    const sessionId = sessionModule.getCurrentSessionId?.();
+    if (!sessionId && !sessionModule.hasPendingChat?.()) {
+      console.warn('Cannot attach Notes context: no active or pending chat');
+      return;
+    }
+
+    if (sessionId) {
+      _selectedNoteIdsBySession.set(sessionId, [...noteIds]);
+    } else {
+      _pendingSelectedNoteIds = [...noteIds];
+    }
+    if (event.detail) event.detail.accepted = true;
+    _renderSelectedNotesIndicator(noteIds);
+  });
+
+  window.addEventListener('odysseus:session-changed', (event) => {
+    const sessionId = event.detail?.sessionId;
+    if (sessionId && event.detail?.materialized && _pendingSelectedNoteIds.length) {
+      _selectedNoteIdsBySession.set(sessionId, _pendingSelectedNoteIds);
+    }
+    _pendingSelectedNoteIds = [];
+    _renderSelectedNotesIndicator(
+      sessionId ? (_selectedNoteIdsBySession.get(sessionId) || []) : []
+    );
+  });
+
+  document.getElementById('selected-notes-context-btn')?.addEventListener('click', () => {
+    const sessionId = sessionModule.getCurrentSessionId?.();
+    if (sessionId) {
+      _selectedNoteIdsBySession.delete(sessionId);
+    } else {
+      _pendingSelectedNoteIds = [];
+    }
+    _renderSelectedNotesIndicator([]);
+  });
+
   function _fmtContextNumber(n) {
     const v = Number(n || 0);
     return v ? v.toLocaleString() : '?';
@@ -290,6 +332,26 @@ import { invalidateSettings } from './appConfig.js';
     return Math.max(50, Math.min(95, Math.round(n)));
   }
 
+  function _renderSelectedNotesIndicator(noteIds){
+    const button = document.getElementById('selected-notes-context-btn');
+    const count = document.getElementById('selected-notes-context-count');
+
+    if (!button || !count) return;
+
+    const total = Array.isArray(noteIds) ? noteIds.length : 0;
+    if(!total){
+      button.style.display = 'none';
+      count.textContent = '';
+      return;
+    }
+    count.textContent = `${total} note${total === 1 ? '' : 's'} selected`;
+    button.style.display = '';
+    button.title = `${total} selected Note/Todo${total === 1 ? '' : 's'} — click to clear`;
+    button.setAttribute(
+      'aria-label',
+      `Clear ${total} selected Note/Todo${total === 1 ? '' : 's'} context`
+    );
+  }
   function _liveSessionModule() {
     return (window.sessionModule && window.sessionModule.getCurrentSessionId)
       ? window.sessionModule
@@ -2497,6 +2559,12 @@ import { invalidateSettings } from './appConfig.js';
       const fd = new FormData();
       fd.append('message', approvalForSend ? '' : _finalMsgWithInject);
       fd.append('session', streamSessionId);
+
+      const selectedNoteIds = _selectedNoteIdsBySession.get(streamSessionId) || [];
+      if(selectedNoteIds.length){
+        fd.append('selected_note_ids', JSON.stringify(selectedNoteIds))
+      }
+
       if (approvalForSend) {
         fd.append('tool_approval_id', approvalForSend.approval_id);
         fd.append('tool_approval_decision', approvalForSend.decision);
diff --git a/static/js/notes.js b/static/js/notes.js
index 885d33198..8db829706 100644
--- a/static/js/notes.js
+++ b/static/js/notes.js
@@ -1230,6 +1230,7 @@ export function openPanel() {
       <label class="memory-bulk-check-all"><input type="checkbox" id="notes-select-all" /> All</label>
       <span id="notes-selected-count">0 Selected</span>
       <span style="flex:1"></span>
+      <button id="notes-send-agent" class="memory-toolbar-btn" disabled><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" style="vertical-align:-2px;margin-right:5px;opacity:0.6"><path d="M14.7 6.3a1 1 0 0 0 0 1.4l1.6 1.6a1 1 0 0 0 1.4 0l3.77-3.77a6 6 0 0 1-7.94 7.94l-6.91 6.91a2.12 2.12 0 0 1-3-3l6.91-6.91a6 6 0 0 1 7.94-7.94l-3.76 3.76z"></path></svg>Send to Agent</button>
       <button id="notes-bulk-archive" class="memory-toolbar-btn" disabled>
         <svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" style="vertical-align:-2px;margin-right:4px;"><rect x="2" y="3" width="20" height="5" rx="1"/><path d="M4 8v11a2 2 0 002 2h12a2 2 0 002-2V8"/><path d="M10 12h4"/></svg>Archive
       </button>
@@ -1379,6 +1380,17 @@ export function openPanel() {
     _renderNotes();
     _updateBulkBar();
   });
+  document.getElementById('notes-send-agent').addEventListener('click', async () => {
+    const ids = [..._selectedIds];
+    if (!ids.length) return;
+    const detail = { noteIds: ids, accepted: false };
+    window.dispatchEvent(new CustomEvent('odysseus:notes-context-selected', { detail }));
+    if (!detail.accepted) {
+      uiModule.showToast('Choose a chat or model before attaching notes');
+      return;
+    }
+    _exitSelectMode();
+  })
   document.getElementById('notes-bulk-archive').addEventListener('click', async () => {
     const ids = [..._selectedIds];
     if (!ids.length) return;
@@ -1511,10 +1523,12 @@ function _exitSelectMode() {
 function _updateBulkBar() {
   const count = _selectedIds.size;
   const countEl = document.getElementById('notes-selected-count');
+  const sendAgentBtn = document.getElementById('notes-send-agent');
   const archiveBtn = document.getElementById('notes-bulk-archive');
   const deleteBtn = document.getElementById('notes-bulk-delete');
   const allEl = document.getElementById('notes-select-all');
   if (countEl) countEl.textContent = `${count} Selected`;
+  if (sendAgentBtn) sendAgentBtn.disabled = count === 0;
   if (archiveBtn) archiveBtn.disabled = count === 0;
   if (deleteBtn) deleteBtn.disabled = count === 0;
   if (allEl) allEl.checked = _notes.length > 0 && _notes.every(n => _selectedIds.has(n.id));
diff --git a/static/js/sessions.js b/static/js/sessions.js
index 68b2a14c4..0a910ef00 100644
--- a/static/js/sessions.js
+++ b/static/js/sessions.js
@@ -351,6 +351,9 @@ let _sessionListFocused = false;
 function _deselectCurrentSession(sid) {
   if (currentSessionId !== sid) return;
   currentSessionId = null;
+  window.dispatchEvent(new CustomEvent('odysseus:session-changed', {
+    detail: { sessionId: null },
+  }));
   uiModule.el('chat-history').innerHTML = '';
   uiModule.el('current-meta').textContent = 'Odysseus Chat';
   Storage.remove('lastSessionId');
@@ -2065,6 +2068,9 @@ export async function selectSession(id, { keepSidebar = false, showLoading = tru
       try { window.documentModule.clearSelection(); } catch {}
     }
     currentSessionId = id;
+    window.dispatchEvent(new CustomEvent('odysseus:session-changed', {
+      detail: { sessionId: id ? id : null },
+    }));
     try { window.__odysseusLastSelectedSessionId = id; } catch (_) {}
     // Identify Assistant / task-output sessions so we don't "trap" the user
     // there on return. Skipped from both `lastSessionId` persistence and the
@@ -2445,6 +2451,9 @@ export function createDirectChat(url, modelId, endpointId, opts = {}) {
   _skipAutoSelect = true;
   _suppressNextSessionLoading = true;
   currentSessionId = null;
+  window.dispatchEvent(new CustomEvent('odysseus:session-changed', {
+    detail: { sessionId: null },
+  }));
   try { window.__odysseusLastSelectedSessionId = ''; } catch (_) {}
   Storage.remove('lastSessionId');
   history.replaceState(null, '', window.location.pathname);
@@ -2555,6 +2564,9 @@ export async function materializePendingSession() {
     }
     _pendingChat = null;
     currentSessionId = payload.id;
+    window.dispatchEvent(new CustomEvent('odysseus:session-changed', {
+      detail: { sessionId: payload.id, materialized: true },
+    }));
     if (!isIncognito) {
       Storage.set('lastSessionId', payload.id);
       history.replaceState(null, '', '#' + payload.id);
@@ -2626,6 +2638,9 @@ export function getCurrentEndpointUrl() {
 export function setCurrentSessionId(id) {
   _sessionNavToken++;
   currentSessionId = id;
+  window.dispatchEvent(new CustomEvent('odysseus:session-changed', {
+    detail: { sessionId: id ? id : null },
+  }));
   try { window.__odysseusLastSelectedSessionId = id || ''; } catch (_) {}
   if (!id) {
     _suppressNextSessionLoading = true;
diff --git a/tests/selectedNotesContext.test.mjs b/tests/selectedNotesContext.test.mjs
new file mode 100644
index 000000000..118f2dd95
--- /dev/null
+++ b/tests/selectedNotesContext.test.mjs
@@ -0,0 +1,81 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { readFileSync } from 'node:fs';
+import vm from 'node:vm';
+
+const chatSource = readFileSync(new URL('../static/js/chat.js', import.meta.url), 'utf8');
+const sessionSource = readFileSync(new URL('../static/js/sessions.js', import.meta.url), 'utf8');
+const notesSource = readFileSync(new URL('../static/js/notes.js', import.meta.url), 'utf8');
+
+function setup() {
+  const start = chatSource.indexOf("  window.addEventListener('odysseus:notes-context-selected'");
+  const end = chatSource.indexOf('  function _fmtContextNumber(n)', start);
+  assert.ok(start !== -1 && end > start, 'production event handlers must exist');
+  const handlers = new Map();
+  const rendered = [];
+  let sessionId = null;
+  let pending = false;
+  let clear;
+  const win = { addEventListener: (name, fn) => handlers.set(name, fn) };
+  const doc = {
+    getElementById: () => ({ addEventListener: (name, fn) => { if (name === 'click') clear = fn; } }),
+  };
+  const sessionModule = {
+    getCurrentSessionId: () => sessionId,
+    hasPendingChat: () => pending,
+  };
+  vm.runInNewContext(
+    `const _selectedNoteIdsBySession = new Map(); let _pendingSelectedNoteIds = [];
+${chatSource.slice(start, end)}`,
+    { window: win, document: doc, sessionModule, console, _renderSelectedNotesIndicator: ids => rendered.push(Array.from(ids)) },
+  );
+  return {
+    setSession(id, isPending = false) { sessionId = id; pending = isPending; },
+    emit(name, detail) { handlers.get(name)({ detail }); },
+    selected(ids) { const detail = { noteIds: ids, accepted: false }; handlers.get('odysseus:notes-context-selected')({ detail }); return detail; },
+    clear() { clear(); },
+    lastRendered() { return rendered.at(-1); },
+  };
+}
+
+test('pending selections transfer only to the materialized chat', () => {
+  const ctx = setup();
+  ctx.setSession(null, true);
+  assert.equal(ctx.selected(['a', 'b']).accepted, true);
+  assert.deepEqual(ctx.lastRendered(), ['a', 'b']);
+  ctx.setSession('new-chat');
+  ctx.emit('odysseus:session-changed', { sessionId: 'new-chat', materialized: true });
+  assert.deepEqual(ctx.lastRendered(), ['a', 'b']);
+  ctx.setSession('other-chat');
+  ctx.emit('odysseus:session-changed', { sessionId: 'other-chat' });
+  assert.deepEqual(ctx.lastRendered(), []);
+  ctx.setSession('new-chat');
+  ctx.emit('odysseus:session-changed', { sessionId: 'new-chat' });
+  assert.deepEqual(ctx.lastRendered(), ['a', 'b']);
+  ctx.clear();
+  assert.deepEqual(ctx.lastRendered(), []);
+});
+
+test('new chat resets old indicator and invalid selection is rejected', () => {
+  const ctx = setup();
+  assert.equal(ctx.selected(['a']).accepted, false);
+  ctx.setSession('old-chat');
+  assert.equal(ctx.selected(['a']).accepted, true);
+  ctx.setSession(null, true);
+  ctx.emit('odysseus:session-changed', { sessionId: null });
+  assert.deepEqual(ctx.lastRendered(), []);
+  assert.equal(ctx.selected(['b']).accepted, true);
+  ctx.emit('odysseus:session-changed', { sessionId: null });
+  assert.deepEqual(ctx.lastRendered(), []);
+  ctx.setSession('fresh');
+  ctx.emit('odysseus:session-changed', { sessionId: 'fresh', materialized: true });
+  assert.deepEqual(ctx.lastRendered(), []);
+});
+
+test('producer events and rejection acknowledgement are wired in source', () => {
+  const create = sessionSource.slice(sessionSource.indexOf('export function createDirectChat'), sessionSource.indexOf('export async function materializePendingSession'));
+  const materialize = sessionSource.slice(sessionSource.indexOf('export async function materializePendingSession'), sessionSource.indexOf('export function preMaterializePendingSession'));
+  assert.match(create, /currentSessionId = null;[\s\S]{0,180}odysseus:session-changed/);
+  assert.match(materialize, /currentSessionId = payload.id;[\s\S]{0,180}odysseus:session-changed/);
+  assert.match(notesSource, /if \(!detail\.accepted\)/);
+});
diff --git a/tests/test_selected_notes_context.py b/tests/test_selected_notes_context.py
new file mode 100644
index 000000000..7d9b0c68b
--- /dev/null
+++ b/tests/test_selected_notes_context.py
@@ -0,0 +1,28 @@
+"""Regression tests for untrusted selected-note ID parsing."""
+import json
+import pytest
+from fastapi import HTTPException
+from routes.chat_routes import _parse_selected_note_ids
+
+
+@pytest.mark.parametrize("raw,expected", [
+    (None, []),
+    ("", []),
+    ("[]", []),
+    ('["one", "two", "one"]', ["one", "two"]),
+])
+def test_selected_note_ids_valid(raw, expected):
+    assert _parse_selected_note_ids(raw) == expected
+
+
+@pytest.mark.parametrize("raw", [
+    "42", "true", "null", '{"id":"a"}',
+    '["one", 5]', '["one", null]', '["one", false]',
+    '[""]', '[" "]', '["one", {}]',
+    "not json", json.dumps(["a"] * 51),
+    json.dumps(["a" * 129]), " " * 8193,
+])
+def test_selected_note_ids_rejected(raw):
+    with pytest.raises(HTTPException) as exc:
+        _parse_selected_note_ids(raw)
+    assert exc.value.status_code == 400

From afecd44ddf5091e1ba9a86730ac6dec66232a4fc Mon Sep 17 00:00:00 2001
From: Grzegorz <gpudlowskidxr@gmail.com>
Date: Tue, 13 Oct 2026 21:16:02 +0200
Subject: [PATCH 05/53] fix(approvals): let "approve once" run ungranted
 bash/python, close skill-test streams (#6635) (#6683)

ToolApprovalStore.create() sealed a process identity only from the request
authority's launch scopes, which exist only for granted bash/python. For an
ungranted call the sealing failed silently, so the approval was created
without a process identity and the executor always refused it ("Approved
action has no sealed process/job identity"). When the authority is not
inherited and has no launch scope for the backend, seal one in the
request's single workspace root at approval time, as filesystem approvals
already do. Inherited authorities still cannot widen.

The skill test run and audit arm left their `async for` over
stream_agent_loop early when an approval was needed, without closing the
generator. asyncio closed it later from another task, so its ContextVar
resets raised "Token ... was created in a different Context". Close the
stream with aclosing, like the scheduler and teacher escalation do.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
---
 routes/skills_routes.py                       | 205 +++++++++---------
 src/tool_approvals.py                         |  19 +-
 .../test_exact_approval_ungranted_process.py  |  81 +++++++
 tests/test_skill_test_stream_closed.py        |  61 ++++++
 4 files changed, 265 insertions(+), 101 deletions(-)
 create mode 100644 tests/test_exact_approval_ungranted_process.py
 create mode 100644 tests/test_skill_test_stream_closed.py

diff --git a/routes/skills_routes.py b/routes/skills_routes.py
index 33b55e3c2..63d723071 100644
--- a/routes/skills_routes.py
+++ b/routes/skills_routes.py
@@ -9,6 +9,7 @@ The on-disk format is SKILL.md (frontmatter + structured body) under
 
 import logging
 import re
+from contextlib import aclosing
 from typing import List, Optional
 
 import httpx
@@ -558,70 +559,74 @@ async def _run_skill_test_job(
 
     messages = list(messages) if isinstance(messages, list) else _skill_test_messages(md, task)
     try:
-        async for chunk in stream_agent_loop(
+        # aclosing: pausing for an approval leaves this loop early, and the
+        # stream's ContextVar cleanup must run in this task, not in asyncio's
+        # finalizer (#6635).
+        async with aclosing(stream_agent_loop(
             url, model, messages, headers=headers,
             temperature=0.3, max_tokens=0, max_rounds=8, owner=owner,
             exact_approval=exact_approval,
             request_authority=(request_authority or (
                 exact_approval.pending.request_authority if exact_approval is not None else None
             ) or RequestAuthority.empty(owner=owner)),
-        ):
-            if not chunk.startswith("data: ") or chunk.strip() == "data: [DONE]":
-                continue
-            try:
-                d = _json.loads(chunk[6:])
-            except Exception:
-                continue
-            if d.get("delta"):
-                say_buf.append(d["delta"]); transcript.append(d["delta"])
-            elif d.get("type") == "tool_start":
-                _flush_say()
-                skill_stats["tool_calls"] += 1
-                cmd = str(d.get("command") or d.get("args") or "")[:300]
-                log.append({"type": "tool_start", "tool": d.get("tool"), "command": cmd})
-                transcript.append(f"\n[tool {d.get('tool')}] {cmd}\n")
-            elif d.get("type") == "tool_output":
-                _flush_say()
-                out = str(d.get("output") or "")[:600]
-                tool_log = {"type": "tool_output", "output": out}
-                approval = d.get("ask_user")
-                if isinstance(approval, dict):
-                    tool_log["ask_user"] = approval
-                log.append(tool_log)
-                transcript.append(f"[output] {out}\n")
-                if (
-                    isinstance(approval, dict)
-                    and approval.get("kind") == "tool_approval"
-                    and approval.get("approval_id")
-                ):
-                    # Manual skill tests have their own polling UI instead of a
-                    # chat session. Pause the run and retain only server-side
-                    # continuation state until the same owner approves/denies
-                    # this exact sealed action.
-                    job["status"] = "awaiting_approval"
-                    job["approval"] = approval
-                    job["_transcript"] = transcript
-                    return
-            elif d.get("type") == "agent_step":
-                _flush_say()
+        )) as stream:
+            async for chunk in stream:
+                if not chunk.startswith("data: ") or chunk.strip() == "data: [DONE]":
+                    continue
                 try:
-                    skill_stats["turns"] = max(skill_stats["turns"], int(d.get("round") or 0))
-                except (TypeError, ValueError):
-                    pass
-                log.append({"type": "agent_step", "round": d.get("round")})
-                transcript.append(f"\n--- round {d.get('round')} ---\n")
-            elif d.get("type") == "metrics":
-                data = d.get("data") or {}
-                try:
-                    skill_stats["turns"] = max(skill_stats["turns"], int(data.get("agent_rounds") or 0))
-                except (TypeError, ValueError):
-                    pass
-                try:
-                    skill_stats["tool_calls"] = max(skill_stats["tool_calls"], int(data.get("tool_calls") or 0))
-                except (TypeError, ValueError):
-                    pass
-            if len(log) > 600:
-                del log[0:len(log) - 600]
+                    d = _json.loads(chunk[6:])
+                except Exception:
+                    continue
+                if d.get("delta"):
+                    say_buf.append(d["delta"]); transcript.append(d["delta"])
+                elif d.get("type") == "tool_start":
+                    _flush_say()
+                    skill_stats["tool_calls"] += 1
+                    cmd = str(d.get("command") or d.get("args") or "")[:300]
+                    log.append({"type": "tool_start", "tool": d.get("tool"), "command": cmd})
+                    transcript.append(f"\n[tool {d.get('tool')}] {cmd}\n")
+                elif d.get("type") == "tool_output":
+                    _flush_say()
+                    out = str(d.get("output") or "")[:600]
+                    tool_log = {"type": "tool_output", "output": out}
+                    approval = d.get("ask_user")
+                    if isinstance(approval, dict):
+                        tool_log["ask_user"] = approval
+                    log.append(tool_log)
+                    transcript.append(f"[output] {out}\n")
+                    if (
+                        isinstance(approval, dict)
+                        and approval.get("kind") == "tool_approval"
+                        and approval.get("approval_id")
+                    ):
+                        # Manual skill tests have their own polling UI instead of a
+                        # chat session. Pause the run and retain only server-side
+                        # continuation state until the same owner approves/denies
+                        # this exact sealed action.
+                        job["status"] = "awaiting_approval"
+                        job["approval"] = approval
+                        job["_transcript"] = transcript
+                        return
+                elif d.get("type") == "agent_step":
+                    _flush_say()
+                    try:
+                        skill_stats["turns"] = max(skill_stats["turns"], int(d.get("round") or 0))
+                    except (TypeError, ValueError):
+                        pass
+                    log.append({"type": "agent_step", "round": d.get("round")})
+                    transcript.append(f"\n--- round {d.get('round')} ---\n")
+                elif d.get("type") == "metrics":
+                    data = d.get("data") or {}
+                    try:
+                        skill_stats["turns"] = max(skill_stats["turns"], int(data.get("agent_rounds") or 0))
+                    except (TypeError, ValueError):
+                        pass
+                    try:
+                        skill_stats["tool_calls"] = max(skill_stats["tool_calls"], int(data.get("tool_calls") or 0))
+                    except (TypeError, ValueError):
+                        pass
+                if len(log) > 600:
+                    del log[0:len(log) - 600]
         _flush_say()
     except Exception as e:
         _flush_say()
@@ -1054,53 +1059,55 @@ async def _run_skill_audit_arm(messages: list[dict], url, model, headers, owner,
         # OpenAI-compat) generate an empty completion, which manifested as
         # the skill test returning nothing while chat (which carries its
         # preset's max_tokens) worked. 4096 matches the chat default.
-        async for chunk in stream_agent_loop(
+        # aclosing: stopping for an approval leaves this loop early (#6635).
+        async with aclosing(stream_agent_loop(
             url, model, messages, headers=headers,
             temperature=0.3, max_tokens=4096, max_rounds=8,
             owner=owner, workload=workload, suppress_skills=True,
             request_authority=(active_request_authority() or RequestAuthority.empty(owner=owner)),
-        ):
-            # Streams can include an SSE event line before the data line,
-            # notably `event: error`. Do not silently discard those failures.
-            payload = next((line[6:] for line in chunk.splitlines() if line.startswith("data: ")), None)
-            if payload is None or payload == "[DONE]":
-                continue
-            try:
-                d = _json.loads(payload)
-            except Exception:
-                continue
-            if d.get("error") or d.get("type") == "error":
-                raise SkillAuditUnavailable(str(d.get("error") or d.get("message") or "Audit stream failed"))
-            if d.get("delta"):
-                transcript.append(d["delta"])
-            elif d.get("type") == "tool_start":
-                stats["tool_calls"] += 1
-                transcript.append(f"\n[tool {d.get('tool')}] {str(d.get('command') or d.get('args') or '')[:300]}\n")
-            elif d.get("type") == "tool_output":
-                transcript.append(f"[output] {str(d.get('output') or '')[:600]}\n")
-                approval = d.get("ask_user")
-                if (
-                    isinstance(approval, dict)
-                    and approval.get("kind") == "tool_approval"
-                ):
-                    approval_required = approval
-                    break
-            elif d.get("type") == "agent_step":
+        )) as stream:
+            async for chunk in stream:
+                # Streams can include an SSE event line before the data line,
+                # notably `event: error`. Do not silently discard those failures.
+                payload = next((line[6:] for line in chunk.splitlines() if line.startswith("data: ")), None)
+                if payload is None or payload == "[DONE]":
+                    continue
                 try:
-                    stats["turns"] = max(stats["turns"], int(d.get("round") or 0))
-                except (TypeError, ValueError):
-                    pass
-                transcript.append(f"\n--- round {d.get('round')} ---\n")
-            elif d.get("type") == "metrics":
-                data = d.get("data") or {}
-                try:
-                    stats["turns"] = max(stats["turns"], int(data.get("agent_rounds") or 0))
-                except (TypeError, ValueError):
-                    pass
-                try:
-                    stats["tool_calls"] = max(stats["tool_calls"], int(data.get("tool_calls") or 0))
-                except (TypeError, ValueError):
-                    pass
+                    d = _json.loads(payload)
+                except Exception:
+                    continue
+                if d.get("error") or d.get("type") == "error":
+                    raise SkillAuditUnavailable(str(d.get("error") or d.get("message") or "Audit stream failed"))
+                if d.get("delta"):
+                    transcript.append(d["delta"])
+                elif d.get("type") == "tool_start":
+                    stats["tool_calls"] += 1
+                    transcript.append(f"\n[tool {d.get('tool')}] {str(d.get('command') or d.get('args') or '')[:300]}\n")
+                elif d.get("type") == "tool_output":
+                    transcript.append(f"[output] {str(d.get('output') or '')[:600]}\n")
+                    approval = d.get("ask_user")
+                    if (
+                        isinstance(approval, dict)
+                        and approval.get("kind") == "tool_approval"
+                    ):
+                        approval_required = approval
+                        break
+                elif d.get("type") == "agent_step":
+                    try:
+                        stats["turns"] = max(stats["turns"], int(d.get("round") or 0))
+                    except (TypeError, ValueError):
+                        pass
+                    transcript.append(f"\n--- round {d.get('round')} ---\n")
+                elif d.get("type") == "metrics":
+                    data = d.get("data") or {}
+                    try:
+                        stats["turns"] = max(stats["turns"], int(data.get("agent_rounds") or 0))
+                    except (TypeError, ValueError):
+                        pass
+                    try:
+                        stats["tool_calls"] = max(stats["tool_calls"], int(data.get("tool_calls") or 0))
+                    except (TypeError, ValueError):
+                        pass
     except SkillAuditUnavailable:
         raise
     except Exception as e:
diff --git a/src/tool_approvals.py b/src/tool_approvals.py
index bf8b7a66a..d68adb82a 100644
--- a/src/tool_approvals.py
+++ b/src/tool_approvals.py
@@ -415,9 +415,24 @@ class ToolApprovalStore:
             backend_operation = BoundBackendOperation(backend,
                 request_authority.request_id if request_authority is not None else "",
                 _normalized_owner(owner), str(session_id or ""), operation.transport_tool, operation.input)
-            from src.agent_runtime.process_resources import needs_process_binding, resolve_process_operation
+            from src.agent_runtime.process_resources import (
+                LAUNCH_TOOLS, needs_process_binding, resolve_process_operation, seal_launch_scope)
             if request_authority is not None and needs_process_binding(operation, backend):
-                process_operation = resolve_process_operation(request_authority, operation, backend)
+                process_authority = request_authority
+                if (not request_authority.inherited and operation.tool in LAUNCH_TOOLS
+                        and not any(s.backend == backend for s in request_authority.launch_scopes)):
+                    # Launch scopes exist only for granted bash/python, but the
+                    # approval exists to admit an ungranted one. Seal its launch
+                    # boundary now, in the request's workspace, the same way an
+                    # ungranted filesystem action gets its root below (#6635).
+                    roots = request_authority.resource_roots
+                    if not roots and workspace:
+                        roots = (FilesystemRoot.seal(workspace, owner=_normalized_owner(owner)),)
+                    if len(roots) == 1:
+                        from dataclasses import replace
+                        process_authority = replace(
+                            request_authority, launch_scopes=(seal_launch_scope(backend, roots[0]),))
+                process_operation = resolve_process_operation(process_authority, operation, backend)
             from src.browser_identity import native_browser, resolve_browser_operation
             if native_browser(operation, backend):
                 if request_authority is None:
diff --git a/tests/test_exact_approval_ungranted_process.py b/tests/test_exact_approval_ungranted_process.py
new file mode 100644
index 000000000..fffb5c011
--- /dev/null
+++ b/tests/test_exact_approval_ungranted_process.py
@@ -0,0 +1,81 @@
+"""An exact approval must be able to run a bash/python call the request did not grant (#6635).
+
+`ToolApprovalStore.create()` sealed the process identity only from the request
+authority's launch scopes, and those exist only for granted bash/python
+backends. For an ungranted call the sealing failed silently, so the approval
+card was created with no process identity and the executor refused it:
+"Approved action has no sealed process/job identity".
+"""
+import pytest
+
+from src.agent_runtime.authority import OperationGrant, RequestAuthority
+from src.tool_approvals import ToolApprovalStore
+from src.tool_capabilities import ToolRunSecurityContext, capabilities_for_action
+from src.tool_types import ToolBlock
+
+
+@pytest.fixture(autouse=True)
+def admin_owner(monkeypatch):
+    from src import tool_execution as execution
+    monkeypatch.setattr(execution, "_owner_is_admin", lambda owner: True)
+
+
+def _authority(workspace, *tools):
+    return RequestAuthority("approval-request", "alice", "s", str(workspace),
+                            tuple(OperationGrant(t) for t in tools))
+
+
+def _approve(authority, tool, content, store=None):
+    store = store or ToolApprovalStore()
+    pending = store.create(owner=authority.owner, session_id=authority.session_id, origin_run_id="run",
+        tool_name=tool, content=content, workspace=authority.workspace, request_authority=authority,
+        external_untrusted_context_seen=True, capabilities=capabilities_for_action(tool, content))
+    return pending, store.consume(pending.approval_id, decision="approve",
+                                  owner=authority.owner, session_id=authority.session_id)
+
+
+async def _dispatch(authority, tool, content, exact):
+    from src import tool_execution as execution
+    return await execution.execute_tool_block(ToolBlock(tool, content), owner=authority.owner,
+        session_id=authority.session_id, workspace=authority.workspace,
+        request_authority=authority, exact_approval=exact,
+        security_context=ToolRunSecurityContext(external_untrusted_context_seen=True))
+
+
+def test_approval_for_ungranted_bash_seals_a_launch_in_the_workspace(tmp_path):
+    authority = _authority(tmp_path, "get_workspace")
+    assert authority.launch_scopes == ()
+
+    pending, _ = _approve(authority, "bash", "printf approved-run")
+
+    bound = pending.process_operation
+    assert bound is not None
+    assert bound.launch is not None
+    assert bound.launch.scope.root.path == str(tmp_path.resolve())
+    assert bound.request_id == authority.request_id
+
+
+async def test_approved_ungranted_bash_runs_once(tmp_path):
+    authority = _authority(tmp_path, "get_workspace")
+    _, exact = _approve(authority, "bash", "printf approved-run")
+
+    description, result = await _dispatch(authority, "bash", "printf approved-run", exact)
+
+    assert result.get("failure_kind") != "resource_identity_denied", result
+    assert result.get("exit_code") == 0, result
+    assert "approved-run" in str(result.get("output", "")) + description
+
+    _, replay = await _dispatch(authority, "bash", "printf approved-run", exact)
+    assert replay.get("blocked") is True, replay
+
+
+async def test_inherited_authority_still_cannot_widen_to_ungranted_bash(tmp_path):
+    # A child (inherited) authority may only narrow its parent, so an approval
+    # it proposes for an ungranted launch must stay unsealed and unrunnable.
+    from dataclasses import replace
+    child = replace(_authority(tmp_path, "get_workspace"), inherited=True)
+    pending, exact = _approve(child, "bash", "printf approved-run")
+
+    assert pending.process_operation is None
+    _, result = await _dispatch(child, "bash", "printf approved-run", exact)
+    assert result.get("blocked") is True
diff --git a/tests/test_skill_test_stream_closed.py b/tests/test_skill_test_stream_closed.py
new file mode 100644
index 000000000..bdaa816c2
--- /dev/null
+++ b/tests/test_skill_test_stream_closed.py
@@ -0,0 +1,61 @@
+"""Skill test runs must close the agent stream in their own task (#6635).
+
+When the agent asks for an exact approval, the skill test pauses by leaving its
+`async for` over `stream_agent_loop`. The abandoned generator was later closed
+by asyncio's finalizer in another task, so the ContextVar resets in its cleanup
+(request_authority, turn_contract, ...) raised "Token ... was created in a
+different Context". The stream must be closed before the run returns.
+"""
+import asyncio
+import json
+from contextvars import ContextVar
+
+import routes.skills_routes as skills_routes
+
+_BOUND: ContextVar = ContextVar("skill_test_bound", default=None)
+
+_APPROVAL = {"kind": "tool_approval", "approval_id": "approval-1", "question": "Allow?"}
+
+
+def _fake_stream(events, closed):
+    async def stream_agent_loop(*args, **kwargs):
+        token = _BOUND.set("bound")
+        try:
+            for event in events:
+                yield "data: " + json.dumps(event) + "\n\n"
+            yield "data: [DONE]\n\n"
+        finally:
+            # Raises ValueError when run from another task's context.
+            _BOUND.reset(token)
+            closed.append(asyncio.current_task())
+    return stream_agent_loop
+
+
+async def test_paused_skill_test_closes_the_agent_stream_in_its_own_task(monkeypatch):
+    closed = []
+    events = [{"type": "tool_output", "output": "blocked", "ask_user": _APPROVAL},
+              {"delta": "never reached"}]
+    monkeypatch.setattr("src.agent_loop.stream_agent_loop", _fake_stream(events, closed))
+    key = ("alice", "demo")
+    skills_routes._skill_test_jobs[key] = {"log": [], "status": "running"}
+    try:
+        await skills_routes._run_skill_test_job(
+            key, "demo", "# skill", "task", "http://model.test", "m", {}, "alice")
+        job = skills_routes._skill_test_jobs[key]
+        assert job["status"] == "awaiting_approval"
+        assert closed == [asyncio.current_task()]
+    finally:
+        skills_routes._skill_test_jobs.pop(key, None)
+
+
+async def test_audit_arm_closes_the_agent_stream_when_it_stops_for_approval(monkeypatch):
+    closed = []
+    events = [{"type": "tool_output", "output": "blocked", "ask_user": _APPROVAL},
+              {"delta": "never reached"}]
+    monkeypatch.setattr("src.agent_loop.stream_agent_loop", _fake_stream(events, closed))
+
+    _, _, approval = await skills_routes._run_skill_audit_arm(
+        [{"role": "user", "content": "task"}], "http://model.test", "m", {}, "alice")
+
+    assert approval == _APPROVAL
+    assert closed == [asyncio.current_task()]

From 0e2c08300efb3c5af412569a71f6674c7da28a36 Mon Sep 17 00:00:00 2001
From: Mark Cockram <mark@cockram.me>
Date: Tue, 13 Oct 2026 22:02:16 +0200
Subject: [PATCH 06/53] feat(settings): opt-in reasoning effort for utility
 model calls (#6572)

* feat(settings): opt-in reasoning effort for utility model calls

Add utility_reasoning_effort (empty = provider default) and let utility
calls inherit a chat session's effort only on that session's matching
endpoint+model route. Explicit caller effort wins; otherwise the utility
setting wins over session inheritance on utility-chain routes. Resolve
the chain and setting per user and validate levels against model evidence.
No-session work uses the setting only, with no chat-effort crossover.

- src/utility_effort.py owns effort_for_call and candidate_effort_factory
- remove global effort fill from llm_call/llm_call_async; utility call
  sites pass effort explicitly, so unrelated calls on the same route do
  not pick it up
- wire auto-title, memory/persona/skill extraction, memory suggest/import/
  audit, compaction, auto-sort, and per-owner background task candidates
- wire no-session email writing-style, summary, and translation calls,
  plus skills evaluation, necessity/retrieval audits, and improvement
- deliberately exclude email replies because thinking_mode='off'
- add the optional candidate_request_factory to llm_call_async_with_fallback
- add sync llm_call reasoning_effort and include it in the cache key
- show the Utility Model effort selector only for advertised levels

Fixes #6569

* fix(utility): exclude email replies and support inherited effort in settings

Pass reasoning_effort='' to task_llm_call_async for scheduled reply drafting to honor the email reply exclusion. In AI settings, resolve the effective Default Chat endpoint and model when Utility is set to 'Same as chat' so supported reasoning effort levels can be selected.

* feat(utility): support same-as-chat effort and session model fallback in compaction

In AI settings, show 'Same as chat' as the default effort option when Utility Model is inherited, and support an explicit 'Provider default' (off) override. Pass the active session fallback in context compaction callers so compaction shares the live chat session's model and reasoning effort for maximum prompt/KV cache affinity.

* fix(settings): clarify chat effort inheritance and keep option visible

Label inherited effort as 'Same as chat (when supported)' and mention
cache affinity and latency speedups in the help text. Ensure the effort
control remains visible when the utility model is set to 'Same as chat'
even if the default chat model lacks advertised reasoning levels, and
populate candidate levels across configured endpoints so the user can
configure effort or keep provider default.

* feat(settings): per-fallback reasoning effort for utility model

Each utility fallback row gets an Effort select, shown only when the
selected model advertises reasoning levels. The choice is stored as
reasoning_effort on the utility_model_fallbacks entry and sent only to
that candidate; an empty value means provider default.

* fix(utility): transmit reasoning effort in non-streaming calls

---------

Co-authored-by: Alexandre Teixeira <111787685+alteixeira20@users.noreply.github.com>
---
 routes/chat_helpers.py                 |   2 +
 routes/email/email_helpers.py          |   3 +
 routes/email/email_pollers.py          |   1 +
 routes/email/email_routes.py           |  11 +-
 routes/history/history_routes.py       |  41 ++-
 routes/memory/memory_routes.py         |   7 +
 routes/session_routes.py               |  16 +-
 routes/skills_routes.py                |  25 +-
 services/memory/memory_extractor.py    |  10 +
 services/memory/skill_extractor.py     |   2 +
 src/context_compactor.py               |  10 +-
 src/llm_core.py                        |  41 ++-
 src/settings.py                        |   5 +
 src/task_endpoint.py                   |   7 +
 src/utility_effort.py                  | 150 ++++++++
 static/css/06-admin-settings.css       |   3 +
 static/css/11-tasks.css                |  14 +-
 static/index.html                      |   6 +
 static/js/settings.js                  | 175 ++++++++-
 tests/test_utility_reasoning_effort.py | 489 +++++++++++++++++++++++++
 20 files changed, 974 insertions(+), 44 deletions(-)
 create mode 100644 src/utility_effort.py
 create mode 100644 tests/test_utility_reasoning_effort.py

diff --git a/routes/chat_helpers.py b/routes/chat_helpers.py
index 7debf70b6..eb0bfc310 100644
--- a/routes/chat_helpers.py
+++ b/routes/chat_helpers.py
@@ -551,6 +551,7 @@ async def auto_name_session(session_manager, sess):
     try:
         from src.llm_core import llm_call_async
         from src.task_endpoint import resolve_task_endpoint
+        from src.utility_effort import effort_for_call
 
         # Find first user message
         first_msg = ""
@@ -603,6 +604,7 @@ async def auto_name_session(session_manager, sess):
             max_tokens=64,
             headers=t_headers,
             timeout=15,
+            reasoning_effort=effort_for_call(t_url, t_model, owner, sess),
         )
 
         title = title.strip().strip('"\'').strip()
diff --git a/routes/email/email_helpers.py b/routes/email/email_helpers.py
index 163132b85..d697b2fe7 100644
--- a/routes/email/email_helpers.py
+++ b/routes/email/email_helpers.py
@@ -443,9 +443,11 @@ async def _generate_email_summary(
     headers: dict | None = None,
     max_tokens: int = 8192,
     timeout: int = 180,
+    owner: str | None = None,
 ) -> str:
     """Generate an interactive email summary through the shared LLM adapter."""
     from src.llm_core import llm_call_async
+    from src.utility_effort import effort_for_call
 
     raw = await llm_call_async(
         url=url,
@@ -456,6 +458,7 @@ async def _generate_email_summary(
         headers=headers,
         timeout=timeout,
         workload="foreground",
+        reasoning_effort=effort_for_call(url, model, owner),
     )
     return _normalize_email_summary(raw)
 
diff --git a/routes/email/email_pollers.py b/routes/email/email_pollers.py
index 9229c0796..ec9d6a8fa 100644
--- a/routes/email/email_pollers.py
+++ b/routes/email/email_pollers.py
@@ -1031,6 +1031,7 @@ async def _auto_summarize_pass_single(days_back: int = 1, account_id: str | None
                             fallback_url=url, fallback_model=model, fallback_headers=headers,
                             owner=account_owner or None,
                             temperature=0.7, max_tokens=1024, timeout=90,
+                            reasoning_effort="",
                         )
                         reply = _apply_email_style_mechanics(_extract_reply(reply or ""))
                         if reply:
diff --git a/routes/email/email_routes.py b/routes/email/email_routes.py
index 0b71116d6..fd6bd2747 100644
--- a/routes/email/email_routes.py
+++ b/routes/email/email_routes.py
@@ -5920,7 +5920,12 @@ def setup_email_routes():
                 },
             ]
 
-            style = await llm_call_async(url, model, messages, headers=headers, max_tokens=2048)
+            from src.utility_effort import effort_for_call
+
+            style = await llm_call_async(
+                url, model, messages, headers=headers, max_tokens=2048,
+                reasoning_effort=effort_for_call(url, model, owner),
+            )
             style = _strip_think(style or "")
             if not style:
                 return {"success": False, "error": "LLM failed to generate style description"}
@@ -6004,6 +6009,7 @@ def setup_email_routes():
                     headers=req_headers,
                     max_tokens=8192,
                     timeout=180,
+                    owner=owner,
                 )
             except Exception as e:
                 logger.warning(
@@ -6125,6 +6131,8 @@ def setup_email_routes():
             if not candidates:
                 return {"success": False, "error": "No LLM endpoint configured"}
 
+            from src.utility_effort import candidate_effort_factory
+
             content = await llm_call_async_with_fallback(
                 candidates,
                 messages=[
@@ -6152,6 +6160,7 @@ def setup_email_routes():
                 temperature=0.2,
                 max_tokens=8192,
                 timeout=180,
+                candidate_request_factory=candidate_effort_factory(owner),
             )
             model = candidates[0][1] if candidates else ""
             content = (content or "").strip()
diff --git a/routes/history/history_routes.py b/routes/history/history_routes.py
index 890927c53..0900a0931 100644
--- a/routes/history/history_routes.py
+++ b/routes/history/history_routes.py
@@ -237,6 +237,18 @@ def _keep_count_before_message(db_messages, before_msg_id: str | None) -> int |
     return None
 
 
+def _effort_mode(model: str, raw_effort: Any) -> str:
+    """Session ``thinking_mode`` for a picked effort: ``effort:<level>`` or ``off``.
+
+    Validated like the chat routes do, so llama-swap advertised efforts persist
+    as well as ChatGPT subscription levels.
+    """
+    from src.chatgpt_subscription import validate_reasoning_effort
+
+    effort = validate_reasoning_effort(model, raw_effort)
+    return f"effort:{effort}" if effort else "off"
+
+
 def setup_history_routes(session_manager, upload_handler=None) -> APIRouter:
     router = APIRouter(
         tags=["history"],
@@ -1031,26 +1043,11 @@ def setup_history_routes(session_manager, upload_handler=None) -> APIRouter:
         mode = getattr(session, "thinking_mode", "off") or "off"
         raw_effort = body.get("reasoning_effort")
         if raw_effort is not None:
-            clean_effort = str(raw_effort).strip().lower()
-            if clean_effort in {"", "default"}:
-                mode = "off"
-            else:
-                from src.chatgpt_subscription import get_chatgpt_model_metadata
-                meta = get_chatgpt_model_metadata(session.model)
-                if meta and clean_effort in [lvl.lower() for lvl in meta.get("supported_reasoning_levels", [])]:
-                    mode = f"effort:{clean_effort}"
-                else:
-                    mode = "off"
+            mode = _effort_mode(session.model, raw_effort)
         elif "thinking_mode" in body:
             raw_mode = str(body.get("thinking_mode") or "").strip().lower()
             if raw_mode.startswith("effort:"):
-                clean_effort = raw_mode[7:].strip()
-                from src.chatgpt_subscription import get_chatgpt_model_metadata
-                meta = get_chatgpt_model_metadata(session.model)
-                if meta and clean_effort in [lvl.lower() for lvl in meta.get("supported_reasoning_levels", [])]:
-                    mode = f"effort:{clean_effort}"
-                else:
-                    mode = "off"
+                mode = _effort_mode(session.model, raw_mode[7:])
             elif raw_mode in {"", "on", "off"}:
                 mode = raw_mode
                 from src.model_profiles import supports_user_thinking_toggle
@@ -1129,7 +1126,14 @@ def setup_history_routes(session_manager, upload_handler=None) -> APIRouter:
             )
 
             # Use utility model if available
-            util_url, util_model, util_headers = resolve_endpoint("utility", owner=owner or None)
+            from src.utility_effort import effort_for_call
+            util_url, util_model, util_headers = resolve_endpoint(
+                "utility",
+                fallback_url=getattr(session, "endpoint_url", None),
+                fallback_model=getattr(session, "model", None),
+                fallback_headers=getattr(session, "headers", None),
+                owner=owner or None,
+            )
             compact_url = util_url or session.endpoint_url
             compact_model = util_model or session.model
             compact_headers = util_headers if util_url else session.headers
@@ -1145,6 +1149,7 @@ def setup_history_routes(session_manager, upload_handler=None) -> APIRouter:
                 ],
                 temperature=0.2, max_tokens=1024,
                 headers=compact_headers, timeout=30,
+                reasoning_effort=effort_for_call(compact_url, compact_model, owner, session),
             )
             summary = normalize_compaction_summary(summary)
 
diff --git a/routes/memory/memory_routes.py b/routes/memory/memory_routes.py
index c4232bec4..7e163433d 100644
--- a/routes/memory/memory_routes.py
+++ b/routes/memory/memory_routes.py
@@ -261,6 +261,8 @@ def setup_memory_routes(memory_manager: MemoryManager, session_manager: SessionM
             sess.endpoint_url, sess.model, sess.headers, owner=_owner(request)
         )
 
+        from src.utility_effort import effort_for_call
+
         try:
             suggestion_text = await llm_call_async(
                 t_url,
@@ -269,6 +271,7 @@ def setup_memory_routes(memory_manager: MemoryManager, session_manager: SessionM
                 temperature=0.2,
                 max_tokens=500,
                 headers=t_headers,
+                reasoning_effort=effort_for_call(t_url, t_model, _owner(request), sess),
             )
             try:
                 suggestions = json.loads(suggestion_text)
@@ -349,6 +352,7 @@ def setup_memory_routes(memory_manager: MemoryManager, session_manager: SessionM
         endpoint_url = None
         model = None
         headers = {}
+        sess = None
 
         user = _owner(request)
 
@@ -453,6 +457,8 @@ def setup_memory_routes(memory_manager: MemoryManager, session_manager: SessionM
             "Return ONLY valid JSON, no markdown fences."
         )
 
+        from src.utility_effort import effort_for_call
+
         try:
             raw = await llm_call_async(
                 endpoint_url,
@@ -464,6 +470,7 @@ def setup_memory_routes(memory_manager: MemoryManager, session_manager: SessionM
                 temperature=0.2,
                 max_tokens=2000,
                 headers=headers,
+                reasoning_effort=effort_for_call(endpoint_url, model, user, sess),
             )
 
             # Parse JSON
diff --git a/routes/session_routes.py b/routes/session_routes.py
index fa687ee14..9f6cc3659 100644
--- a/routes/session_routes.py
+++ b/routes/session_routes.py
@@ -509,6 +509,7 @@ def setup_session_routes(
                     "has_documents": s.id in doc_session_ids,
                     "has_images": s.id in img_session_ids,
                     "mode": s.mode,
+                    "thinking_mode": s.thinking_mode or "off",
                     "message_count": s.message_count or 0,
                 })
         finally:
@@ -1042,6 +1043,7 @@ def setup_session_routes(
                     "id": s.id,
                     "name": s.name,
                     "model": s.model,
+                    "thinking_mode": s.thinking_mode or "off",
                     "message_count": s.message_count or 0,
                     "created_at": s.created_at.isoformat() if s.created_at else None,
                     "updated_at": s.updated_at.isoformat() if s.updated_at else None,
@@ -1238,9 +1240,16 @@ def setup_session_routes(
         from src.context_compactor import SELF_SUMMARY_SYSTEM_PROMPT
         from src.endpoint_resolver import resolve_endpoint
         from src.llm_core import llm_call_async
+        from src.utility_effort import effort_for_call
 
         owner = getattr(session, "owner", None) or effective_user(request)
-        url, model, headers = resolve_endpoint("utility", owner=owner)
+        url, model, headers = resolve_endpoint(
+            "utility",
+            fallback_url=getattr(session, "endpoint_url", None),
+            fallback_model=getattr(session, "model", None),
+            fallback_headers=getattr(session, "headers", None),
+            owner=owner,
+        )
         if not url or not model:
             url, model, headers = session.endpoint_url, session.model, session.headers
         if not url or not model:
@@ -1268,6 +1277,7 @@ def setup_session_routes(
                 max_tokens=1024,
                 headers=headers,
                 timeout=60,
+                reasoning_effort=effort_for_call(url, model, owner, session),
             )
         except Exception as e:
             logger.error("Manual compaction failed: %s", e)
@@ -1311,6 +1321,7 @@ def setup_session_routes(
         users can clean junk without spending tokens.
         """
         from src.llm_core import llm_call
+        from src.utility_effort import effort_for_call
         user = effective_user(request)
         single_user_mode = not user and _auth_disabled()
         user_sessions = session_manager.get_sessions_for_user(user)
@@ -1483,7 +1494,8 @@ def setup_session_routes(
             # reasoning model spends tokens thinking first — 4096 truncated the
             # JSON mid-output, so it never parsed ("invalid JSON for auto-sort").
             raw = llm_call(url, model, [{"role": "user", "content": prompt}],
-                           temperature=0.3, max_tokens=16384, headers=headers, timeout=120)
+                           temperature=0.3, max_tokens=16384, headers=headers, timeout=120,
+                           reasoning_effort=effort_for_call(url, model, user))
             logger.info(f"Auto-sort raw response ({len(raw)} chars): {raw[:300]}")
             # Extract JSON from response — handle markdown fences, leading text,
             # reasoning-model <think> blocks, and trailing commas.
diff --git a/routes/skills_routes.py b/routes/skills_routes.py
index 63d723071..12f7cdd79 100644
--- a/routes/skills_routes.py
+++ b/routes/skills_routes.py
@@ -21,6 +21,7 @@ from services.memory.skills import SkillsManager
 from src.auth_helpers import get_current_user
 from src.prompt_security import untrusted_context_message
 from src.text_helpers import strip_closed_think_blocks
+from src.utility_effort import effort_for_call
 from core.middleware import require_admin
 
 logger = logging.getLogger(__name__)
@@ -170,7 +171,7 @@ async def _eval_skill_run(skill_md: str, task: str, transcript: str,
                           baseline_transcript: str = "",
                           skill_stats: Optional[dict] = None,
                           baseline_stats: Optional[dict] = None,
-                          workload: str = "foreground") -> dict:
+                          workload: str = "foreground", owner: Optional[str] = None) -> dict:
     """LLM-as-judge: grade a skill test run from its transcript. Advisory only.
 
     Robust against local reasoning models (strips <think>, lenient JSON,
@@ -349,6 +350,7 @@ async def _eval_skill_run(skill_md: str, task: str, transcript: str,
                 url, model, msgs,
                 temperature=0.1, max_tokens=32768, headers=headers, timeout=180,
                 workload=workload,
+                reasoning_effort=effort_for_call(url, model, owner),
             )
         except Exception as e:
             # Don't give up on a transient first-attempt error — let the second
@@ -368,7 +370,7 @@ async def _eval_skill_run(skill_md: str, task: str, transcript: str,
 
 async def _eval_skill_necessity(skill_md: str, others: list, url: str, model: str,
                                 headers: Optional[dict],
-                                workload: str = "foreground") -> Optional[dict]:
+                                workload: str = "foreground", owner: Optional[str] = None) -> Optional[dict]:
     """Advisory judge: is this skill worth keeping, or is it redundant / trivially
     unnecessary? Sees the OTHER skills' names+descriptions so it can spot
     duplicates. Returns {necessary, redundant_with, reason} or None. Never acts —
@@ -401,6 +403,7 @@ async def _eval_skill_necessity(skill_md: str, others: list, url: str, model: st
             [{"role": "system", "content": sys_prompt}, {"role": "user", "content": user_msg}],
             temperature=0.1, max_tokens=8192, headers=headers, timeout=120,
             workload=workload,
+            reasoning_effort=effort_for_call(url, model, owner),
         )
     except Exception as e:
         logger.warning(f"Necessity check failed: {e}")
@@ -453,7 +456,7 @@ def _should_check_retrieval_precision(skill: dict) -> bool:
 async def _eval_skill_retrieval_precision(skill_md: str, others: list,
                                           url: str, model: str,
                                           headers: Optional[dict],
-                                          workload: str = "foreground") -> Optional[dict]:
+                                          workload: str = "foreground", owner: Optional[str] = None) -> Optional[dict]:
     """Advisory judge: would this skill's metadata make retrieval over-select it?
 
     This is distinct from "does the procedure work?". It asks whether tags,
@@ -491,6 +494,7 @@ async def _eval_skill_retrieval_precision(skill_md: str, others: list,
             [{"role": "system", "content": sys_prompt}, {"role": "user", "content": user_msg}],
             temperature=0.1, max_tokens=4096, headers=headers, timeout=90,
             workload=workload,
+            reasoning_effort=effort_for_call(url, model, owner),
         )
     except Exception as e:
         logger.warning(f"Retrieval precision check failed: {e}")
@@ -667,6 +671,7 @@ async def _run_skill_test_job(
             baseline_transcript=baseline_transcript,
             skill_stats=skill_stats,
             baseline_stats=baseline_stats,
+            owner=owner,
         )
     except Exception as e:
         job["verdict"] = {"verdict": "unknown", "confidence": 0, "summary": f"Eval failed: {e}", "issues": []}
@@ -1157,12 +1162,13 @@ async def _run_skill_test_once(md: str, task: str, url, model, headers, owner,
         headers,
         skill_stats=stats,
         workload=workload,
+        owner=owner,
     )
     return text, verdict
 
 
 async def _improve_skill_md(skill_md: str, verdict: dict, transcript: str, url, model, headers,
-                            workload: str = "foreground"):
+                            workload: str = "foreground", owner: Optional[str] = None):
     """Have a model rewrite SKILL.md to fix the reviewer's issues. Returns the
     corrected markdown, or None if it couldn't produce a usable change."""
     import re as _re
@@ -1192,7 +1198,8 @@ async def _improve_skill_md(skill_md: str, verdict: dict, transcript: str, url,
                                    [{"role": "system", "content": sys_prompt},
                                     {"role": "user", "content": user_msg}],
                                    temperature=0.2, max_tokens=16384, headers=headers, timeout=180,
-                                   workload=workload)
+                                   workload=workload,
+                                   reasoning_effort=effort_for_call(url, model, owner))
     except Exception as e:
         logger.warning(f"Audit: improve call failed: {e}")
         return None
@@ -1262,6 +1269,7 @@ async def _audit_one_skill(skills_manager, skill, url, model, headers,
         ]
         nec = await _eval_skill_necessity(
             md, others, url, model, headers, workload=workload,
+            owner=owner,
         )
         if nec is not None:
             skills_manager.set_necessity(name, nec.get("necessary", True),
@@ -1278,6 +1286,7 @@ async def _audit_one_skill(skills_manager, skill, url, model, headers,
         if _should_check_retrieval_precision(skill):
             rp = await _eval_skill_retrieval_precision(
                 md, others, url, model, headers, workload=workload,
+                owner=owner,
             )
             if rp and not rp.get("ok"):
                 issues = rp.get("issues") or ["metadata: retrieval: narrow tags and when_to_use to the intended trigger"]
@@ -1288,7 +1297,7 @@ async def _audit_one_skill(skills_manager, skill, url, model, headers,
                     "summary": rp.get("summary") or "Retrieval metadata is too broad.",
                     "issues": issues,
                 }, "Retrieval audit only: the procedure may work, but matching metadata is too broad.",
-                    url, model, headers, workload=workload)
+                    url, model, headers, workload=workload, owner=owner)
                 if fixed and fixed.strip() != md.strip() and _apply_skill_md(skills_manager, name, fixed, owner):
                     md = fixed
                     refreshed = next((s for s in skills_manager.load(owner=owner) if s.get("name") == name), None)
@@ -1364,6 +1373,7 @@ async def _audit_one_skill(skills_manager, skill, url, model, headers,
             skill_stats=skill_stats,
             baseline_stats=baseline_stats,
             workload=workload,
+            owner=owner,
         )
     v = verdict.get("verdict")
     log(f"{name}: verdict = {v} ({verdict.get('summary', '')[:80]})")
@@ -1397,6 +1407,7 @@ async def _audit_one_skill(skills_manager, skill, url, model, headers,
             log(f"{name}: pass, but fixing {len(meta_issues)} metadata issue(s)…")
             fixed = await _improve_skill_md(
                 md, verdict, transcript, url, model, headers, workload=workload,
+                owner=owner,
             )
             if fixed and fixed.strip() != md.strip():
                 _apply_skill_md(skills_manager, name, fixed, owner)
@@ -1430,6 +1441,7 @@ async def _audit_one_skill(skills_manager, skill, url, model, headers,
     log(f"{name}: self-editing to fix issues…")
     new_md = await _improve_skill_md(
         md, verdict, transcript, url, model, headers, workload=workload,
+        owner=owner,
     )
     if new_md and new_md.strip() != md.strip() and _apply_skill_md(skills_manager, name, new_md, owner):
         md = new_md
@@ -1464,6 +1476,7 @@ async def _audit_one_skill(skills_manager, skill, url, model, headers,
         log(f"{name}: teacher {t_model} rewriting the skill…")
         t_md = await _improve_skill_md(
             md, verdict, transcript, t_url, t_model, t_headers, workload=workload,
+            owner=owner,
         )
         if t_md and t_md.strip() != md.strip() and _apply_skill_md(skills_manager, name, t_md, owner):
             md = t_md
diff --git a/services/memory/memory_extractor.py b/services/memory/memory_extractor.py
index 7d056cb40..6b911b4d5 100644
--- a/services/memory/memory_extractor.py
+++ b/services/memory/memory_extractor.py
@@ -331,6 +331,7 @@ async def extract_and_store(
 
     try:
         from src.llm_core import llm_call_async
+        from src.utility_effort import effort_for_call
 
         # Get last N messages from session
         messages = session.get_context_messages()
@@ -404,6 +405,9 @@ async def extract_and_store(
                 # enough once thinking has room.
                 max_tokens=4096,
                 headers=headers,
+                reasoning_effort=effort_for_call(
+                    endpoint_url, model, getattr(session, "owner", None), session
+                ),
             )
 
             # Parse JSON, tolerating reasoning-model noise (<think> blocks, a
@@ -559,6 +563,7 @@ async def update_persona_memory(
 
     try:
         from src.llm_core import llm_call_async
+        from src.utility_effort import effort_for_call
         from src.text_helpers import strip_think
 
         custom = {}
@@ -607,6 +612,9 @@ async def update_persona_memory(
             temperature=0.1,
             max_tokens=1200,
             headers=headers,
+            reasoning_effort=effort_for_call(
+                endpoint_url, model, getattr(session, "owner", None), session
+            ),
         )
 
         updated = strip_think(str(raw or ""), prose=True, prompt_echo=True).strip()
@@ -643,6 +651,7 @@ async def audit_memories(
     """
     try:
         from src.llm_core import llm_call_async
+        from src.utility_effort import effort_for_call
 
         existing = memory_manager.load(owner=owner)
         if not existing:
@@ -691,6 +700,7 @@ async def audit_memories(
             # Bound the call so the Tidy whirlpool can't spin indefinitely on a
             # slow/large generation.
             timeout=120,
+            reasoning_effort=effort_for_call(endpoint_url, model, owner),
         )
 
         # Parse the JSON list, tolerating reasoning-model noise: <think> blocks,
diff --git a/services/memory/skill_extractor.py b/services/memory/skill_extractor.py
index 18cc9014e..49e423706 100644
--- a/services/memory/skill_extractor.py
+++ b/services/memory/skill_extractor.py
@@ -149,6 +149,7 @@ async def maybe_extract_skill(
 
     try:
         from src.llm_core import llm_call_async
+        from src.utility_effort import effort_for_call
 
         # Get recent messages
         history = session.get_context_messages()
@@ -204,6 +205,7 @@ async def maybe_extract_skill(
             ],
             headers=headers,
             timeout=30,
+            reasoning_effort=effort_for_call(endpoint_url, model, owner, session),
         )
         logger.debug(
             "[skill-extract] LLM returned in %.1fs (len=%d, head=%r)",
diff --git a/src/context_compactor.py b/src/context_compactor.py
index 11f450323..05b53ce95 100644
--- a/src/context_compactor.py
+++ b/src/context_compactor.py
@@ -13,6 +13,7 @@ from typing import Any, Dict, List, Optional
 from src.model_context import estimate_text_tokens, get_context_length, estimate_tokens
 from src.llm_core import llm_call_async
 from src.endpoint_resolver import resolve_endpoint
+from src.utility_effort import effort_for_call
 from src.settings import get_setting
 from core.models import ChatMessage
 
@@ -556,7 +557,13 @@ async def maybe_compact(
     )
 
     # Use utility model if configured, otherwise fall back to session model
-    util_url, util_model, util_headers = resolve_endpoint("utility", owner=owner)
+    util_url, util_model, util_headers = resolve_endpoint(
+        "utility",
+        fallback_url=endpoint_url,
+        fallback_model=model,
+        fallback_headers=headers,
+        owner=owner,
+    )
     compact_url = util_url or endpoint_url
     compact_model = util_model or model
     compact_headers = util_headers if util_url else headers
@@ -580,6 +587,7 @@ async def maybe_compact(
             max_tokens=SUMMARY_MAX_TOKENS,
             headers=compact_headers,
             timeout=30,
+            reasoning_effort=effort_for_call(compact_url, compact_model, owner, session),
         )
     except Exception as e:
         logger.error(f"Compaction summary failed: {e}")
diff --git a/src/llm_core.py b/src/llm_core.py
index bdd3a6a44..c56346936 100644
--- a/src/llm_core.py
+++ b/src/llm_core.py
@@ -2268,10 +2268,25 @@ def normalize_model_id(
             return a
     return None
 
+
+def _apply_explicit_nonstream_reasoning_effort(
+    payload: Dict, reasoning_effort: Optional[str]
+) -> None:
+    """Apply explicit effort to an OpenAI-compatible non-streaming request.
+
+    No explicit effort preserves existing provider-specific defaults.
+    Native Ollama, Anthropic and ChatGPT Responses use separate builders.
+    """
+    effort = str(reasoning_effort or "").strip().lower()
+    if effort and effort != "default":
+        payload["reasoning_effort"] = effort
+
+
 def llm_call(url: str, model: str, messages: List[Dict], temperature: float = LLMConfig.DEFAULT_TEMPERATURE,
              max_tokens: int = LLMConfig.DEFAULT_MAX_TOKENS, headers: Optional[Dict] = None,
              timeout: int = LLMConfig.DEFAULT_TIMEOUT, prompt_type: Optional[str] = None,
-             thinking_mode: Optional[str] = None) -> str:
+             thinking_mode: Optional[str] = None,
+             reasoning_effort: Optional[str] = None) -> str:
     """Synchronous LLM call with optional prompt type enhancement."""
     h = _provider_headers(_detect_provider(url))
     # Tolerate headers that arrive as a JSON string (some sessions stored them
@@ -2303,7 +2318,7 @@ def llm_call(url: str, model: str, messages: List[Dict], temperature: float = LL
     provider = _detect_provider(url)
     cache_key = _get_cache_key(
         url, model, messages_copy, temperature, max_tokens, headers=headers,
-        thinking_mode=thinking_mode,
+        thinking_mode=thinking_mode, reasoning_effort=reasoning_effort,
     )
     cached_response = _get_cached_response(cache_key)
     if cached_response:
@@ -2343,6 +2358,7 @@ def llm_call(url: str, model: str, messages: List[Dict], temperature: float = LL
         )
         if provider == "mistral" and _supports_thinking(model):
             payload["reasoning_effort"] = _MISTRAL_REASONING_EFFORT
+        _apply_explicit_nonstream_reasoning_effort(payload, reasoning_effort)
     try:
         note_model_activity(target_url, model)
         r = httpx_post_kimi_aware(target_url, h, json=payload, timeout=timeout)
@@ -2465,14 +2481,30 @@ def llm_call_with_fallback(candidates, messages, **kwargs) -> str:
 
 
 async def llm_call_async_with_fallback(candidates, messages, **kwargs) -> str:
-    """Async variant of `llm_call_with_fallback` — same semantics."""
+    """Async variant of `llm_call_with_fallback` — same semantics.
+
+    An optional ``candidate_request_factory(index, url, model, headers)`` may
+    return ``{"messages": ..., "kwargs": {...}}`` to adjust the request per
+    candidate (same contract as `llm_call_async_with_route_fallback`).
+    """
+    candidate_request_factory = kwargs.pop("candidate_request_factory", None)
     cands = dedupe_model_candidates(candidates)
     if not cands:
         raise HTTPException(503, "No model endpoint configured")
     last_err = None
     for i, (url, model, headers) in enumerate(cands):
         try:
-            return await llm_call_async(url, model, messages, headers=headers, **kwargs)
+            candidate_messages = messages
+            candidate_kwargs = kwargs
+            if candidate_request_factory is not None:
+                request = candidate_request_factory(i, url, model, headers) or {}
+                if hasattr(request, "__await__"):
+                    request = await request
+                candidate_messages = request.get("messages", messages)
+                candidate_kwargs = {**kwargs, **(request.get("kwargs") or {})}
+            return await llm_call_async(
+                url, model, candidate_messages, headers=headers, **candidate_kwargs
+            )
         except Exception as e:
             last_err = e
             tag = "primary" if i == 0 else "candidate"
@@ -2740,6 +2772,7 @@ async def llm_call_async(
         _apply_deepseek_v4_reasoning_defaults(
             payload, target_url, model, thinking_mode
         )
+        _apply_explicit_nonstream_reasoning_effort(payload, reasoning_effort)
 
     if _is_host_dead(target_url):
         raise HTTPException(503, f"Upstream {_host_key(target_url)} marked unreachable (cooldown active)")
diff --git a/src/settings.py b/src/settings.py
index 6c9d81392..202af0156 100644
--- a/src/settings.py
+++ b/src/settings.py
@@ -160,6 +160,10 @@ DEFAULT_SETTINGS = {
     # Ordered fallback chain for the Utility model (summarization, naming,
     # tidy actions, etc.).
     "utility_model_fallbacks": [],
+    # Opt-in reasoning effort for utility/background LLM calls. Empty keeps the
+    # provider default; a value is sent only to utility-chain candidates whose
+    # model advertises that level.
+    "utility_reasoning_effort": "",
     "teacher_model": "",
     "teacher_enabled": False,
     "teacher_tier2_enabled": False,
@@ -290,6 +294,7 @@ _PER_USER_KEYS = {
     # got injected into the chat composer on first open.
     "default_endpoint_id", "default_model",
     "utility_endpoint_id", "utility_model", "utility_model_fallbacks",
+    "utility_reasoning_effort",
     "research_endpoint_id", "research_model",
 }
 
diff --git a/src/task_endpoint.py b/src/task_endpoint.py
index 090c7a4b5..516b50760 100644
--- a/src/task_endpoint.py
+++ b/src/task_endpoint.py
@@ -106,4 +106,11 @@ async def task_llm_call_async(
         raise RuntimeError("No LLM endpoint available for background task")
     await wait_for_interactive_quiet("background task LLM")
     kwargs.setdefault("workload", "background")
+    if kwargs.get("reasoning_effort") is None:
+        kwargs.pop("reasoning_effort", None)
+        from src.utility_effort import candidate_effort_factory
+
+        factory = candidate_effort_factory(owner)
+        if factory is not None:
+            kwargs.setdefault("candidate_request_factory", factory)
     return await llm_call_async_with_fallback(candidates, messages=messages, **kwargs)
diff --git a/src/utility_effort.py b/src/utility_effort.py
new file mode 100644
index 000000000..0270732a5
--- /dev/null
+++ b/src/utility_effort.py
@@ -0,0 +1,150 @@
+"""Reasoning effort for utility-role LLM calls.
+
+One owner for the rule.  Precedence for a utility call:
+
+1. an explicit caller effort (never touched here);
+2. the ``utility_reasoning_effort`` setting, sent only to routes on the
+   utility chain (the Utility endpoint/model plus its fallbacks, matched by
+   ``(url, model)``);
+3. the chat session's own effort (``thinking_mode == "effort:<level>"``), when
+   the call is made for a chat session and its route is that session's route.
+
+Every level is validated against what the model advertises; a model without
+evidence gets nothing.  Calls with no session only ever use (2).
+"""
+from typing import Optional
+
+
+def utility_routes(owner: Optional[str] = None) -> set:
+    """The ``(url, model)`` routes that make up the utility chain."""
+    from src.endpoint_resolver import resolve_endpoint, resolve_utility_fallback_candidates
+
+    return {
+        (url, model)
+        for url, model, _headers in [
+            resolve_endpoint("utility", owner=owner),
+            *resolve_utility_fallback_candidates(owner=owner),
+        ]
+        if url and model
+    }
+
+
+def configured_effort(owner: Optional[str] = None) -> str:
+    """The raw setting, lowercased; empty when unset (the default)."""
+    from src.settings import get_user_setting
+
+    return str(get_user_setting("utility_reasoning_effort", owner or "", "") or "").strip().lower()
+
+
+def fallback_route_efforts(owner: Optional[str] = None) -> dict[tuple[str, str], str]:
+    """Configured effort per fallback candidate in ``utility_model_fallbacks``."""
+    from src.endpoint_resolver import resolve_endpoint_by_id
+    from src.settings import get_user_setting, load_settings
+
+    try:
+        settings = load_settings()
+        chain = get_user_setting(
+            "utility_model_fallbacks",
+            owner or "",
+            settings.get("utility_model_fallbacks") or [],
+        ) or []
+    except Exception:
+        return {}
+
+    res = {}
+    for entry in chain:
+        if not isinstance(entry, dict) or "reasoning_effort" not in entry:
+            continue
+        effort = str(entry.get("reasoning_effort") or "").strip().lower()
+        ep = resolve_endpoint_by_id(
+            entry.get("endpoint_id", ""),
+            entry.get("model", ""),
+            owner=owner,
+        )
+        if ep:
+            url, model, _ = ep
+            if url and model:
+                res[(url, model)] = effort
+    return res
+
+
+def effort_for_route(url: str, model: str, owner: Optional[str] = None) -> Optional[str]:
+    """Validated effort for ``(url, model)``, or None when it must not be sent."""
+    fb_efforts = fallback_route_efforts(owner)
+    if (url, model) in fb_efforts:
+        fb_effort = fb_efforts[(url, model)]
+        if not fb_effort or fb_effort in {"off", "none", "default"}:
+            return None
+        from src.chatgpt_subscription import validate_reasoning_effort
+
+        return validate_reasoning_effort(model, fb_effort)
+
+    effort = configured_effort(owner)
+    if not effort or (url, model) not in utility_routes(owner):
+        return None
+    from src.chatgpt_subscription import validate_reasoning_effort
+
+    return validate_reasoning_effort(model, effort)
+
+
+def session_effort(session) -> Optional[str]:
+    """The raw effort level the chat session is set to, or None."""
+    mode = str(getattr(session, "thinking_mode", "") or "")
+    if not mode.startswith("effort:"):
+        return None
+    return mode[len("effort:"):].strip().lower() or None
+
+
+def _is_session_route(url: str, model: str, session) -> bool:
+    from src.endpoint_resolver import same_endpoint_base
+
+    return bool(
+        model
+        and model == getattr(session, "model", None)
+        and same_endpoint_base(url, getattr(session, "endpoint_url", None))
+    )
+
+
+def effort_for_call(url: str, model: str, owner: Optional[str] = None, session=None) -> Optional[str]:
+    """Effort an owner-aware utility call should send to ``(url, model)``.
+
+    ``session`` is the chat session the call is made for, or None for
+    session-less work (scheduled tasks, pollers, auto-sort).  Never raises:
+    a lookup failure means "send nothing".
+    """
+    try:
+        raw = configured_effort(owner)
+        if raw in {"off", "none", "default"}:
+            return None
+        effort = effort_for_route(url, model, owner)
+        if effort or session is None:
+            return effort
+        level = session_effort(session)
+        if not level or not _is_session_route(url, model, session):
+            return None
+        from src.chatgpt_subscription import validate_reasoning_effort
+
+        return validate_reasoning_effort(model, level)
+    except Exception:
+        return None
+
+
+def candidate_effort_factory(owner=None):
+    """Per-candidate factory for `llm_call_async_with_fallback`.
+
+    Returns None when neither the setting nor any fallback effort is configured.
+    Otherwise a factory sending the effort only to utility-chain candidates
+    (owner-scoped) whose model advertises it.
+    """
+    raw = configured_effort(owner)
+    has_primary = bool(raw and raw not in {"off", "none", "default"})
+    fb_efforts = fallback_route_efforts(owner)
+    has_fb = any(eff and eff not in {"off", "none", "default"} for eff in fb_efforts.values())
+    if not has_primary and not has_fb:
+        return None
+
+    def factory(_index, url, model, _headers):
+        effort = effort_for_route(url, model, owner)
+        return {"kwargs": {"reasoning_effort": effort}} if effort else {}
+
+    return factory
diff --git a/static/css/06-admin-settings.css b/static/css/06-admin-settings.css
index ba1b0f38b..425b9ad6d 100644
--- a/static/css/06-admin-settings.css
+++ b/static/css/06-admin-settings.css
@@ -445,6 +445,7 @@
   flex-shrink: 0; color: var(--fg); opacity: 0.85;
 }
 .adm-provider-logo svg { width: 14px; height: 14px; }
+.adm-model-logo { margin-right: 8px; }
 /* Pull the settings-select 4px closer to its logo chip so the row
    reads as logo+select instead of having an extra gap. */
 .adm-model-logo + .settings-select { margin-left: -4px; }
@@ -454,6 +455,8 @@
    select shrinks to its content and the trash button rides up
    tight to it. */
 .settings-fallback-row > .settings-select { flex: 1 1 0; min-width: 0; }
+.settings-fallback-row > .settings-select:first-of-type { flex: 0 1 128px; max-width: 34%; }
+.settings-fallback-row > .settings-select.settings-fallback-effort { flex: 0 1 130px; max-width: 32%; }
 /* Constrain logo SVGs in settings dropdown chips. Many provider
    icons in providers.js declare only viewBox (no width/height),
    so without this rule the browser falls back to 300x150 and
diff --git a/static/css/11-tasks.css b/static/css/11-tasks.css
index 1ff602fa3..7067c95c9 100644
--- a/static/css/11-tasks.css
+++ b/static/css/11-tasks.css
@@ -989,7 +989,6 @@ a.chat-link[href^="#research-"] {
 .settings-row {
   display: flex;
   align-items: center;
-  gap: 8px;
 }
 .settings-col {
   display: flex;
@@ -998,7 +997,13 @@ a.chat-link[href^="#research-"] {
 }
 .settings-label {
   font-size: 12px;
-  min-width: 70px;
+  min-width: 85px;
+}
+#set-utilityEffortLabel { flex: 0 0 85px; line-height: 1.2; }
+.settings-label-sub {
+  display: block;
+  font-size: 10px;
+  opacity: 0.6;
 }
 .settings-select {
   flex: 1;
@@ -1117,6 +1122,11 @@ input.settings-select::placeholder { color: color-mix(in srgb, var(--fg) 35%, tr
   width: 0;
   max-width: 100%;
 }
+.settings-fallback-row .settings-select.settings-fallback-effort {
+  flex: 0 1 130px;
+  width: 130px;
+  max-width: 32%;
+}
 details.hwfit-serve-advanced > .hwfit-serve-row,
 details.hwfit-serve-advanced > .hwfit-serve-checks,
 details.hwfit-serve-advanced > .hwfit-serve-cmd-wrap,
diff --git a/static/index.html b/static/index.html
index 8557d54af..5fc386a5c 100644
--- a/static/index.html
+++ b/static/index.html
@@ -1612,6 +1612,12 @@
                 <span class="adm-model-logo" id="set-utilityModelSelect-logo" style="display:inline-flex;align-items:center;justify-content:center;width:18px;height:18px;flex-shrink:0;opacity:0.9;color:var(--fg);"></span>
                 <select id="set-utilityModelSelect" class="settings-select"><option value="">—</option></select>
               </div>
+              <div class="settings-row" id="set-utilityEffortRow" style="display:none;">
+                <label class="settings-label" id="set-utilityEffortLabel">Effort<span class="settings-label-sub" id="set-utilityEffortQualifier">(when supported)</span></label>
+                <span class="adm-model-logo" style="display:inline-flex;align-items:center;justify-content:center;width:18px;height:18px;flex-shrink:0;opacity:0.9;color:var(--fg);"></span>
+                <select id="set-utilityEffortSelect" class="settings-select"><option value="">Provider default</option></select>
+              </div>
+              <div class="admin-toggle-sub" id="set-utilityEffortHelp" style="display:none;margin-top:-2px;">Applied to utility and background calls, not chat. Use &ldquo;Same as chat&rdquo; to match active chat effort and potentially ensure cache hits to speed up responses. Reasoning tokens count against each call's output limit, so higher efforts can truncate or empty short outputs such as auto-generated titles.</div>
               <div class="settings-row" style="align-items:flex-start;">
                 <label class="settings-label" style="margin-top:6px;">Fallbacks</label>
                 <div style="flex:1;display:flex;flex-direction:column;gap:6px;">
diff --git a/static/js/settings.js b/static/js/settings.js
index ad4b26da6..dffd466c7 100644
--- a/static/js/settings.js
+++ b/static/js/settings.js
@@ -212,9 +212,11 @@ function _bindFallbackWidget(opts) {
   var endpointsRef = opts.endpoints;       // mutable list reference
   var modelsFilter = opts.modelsFilter || function() { return true; };
   var settingKey = opts.settingKey;
-  var current = opts.initial || [];        // [{endpoint_id, model}]
+  var current = opts.initial || [];        // [{endpoint_id, model, reasoning_effort}]
+  var supportsEffort = Boolean(opts.supportsEffort);
+  var getEffortLevels = opts.getEffortLevels;
 
-  if (!fbContainer || !addBtn) return { setEndpoints: function() {}, setInitial: function() {} };
+  if (!fbContainer || !addBtn) return { setEndpoints: function() {}, setInitial: function() {}, refresh: function() {} };
 
   function enabledEps() { return (endpointsRef() || []).filter(function(e) { return e.is_enabled; }); }
 
@@ -233,8 +235,36 @@ function _bindFallbackWidget(opts) {
     if (selected) selectEl.value = selected;
   }
 
+  function fillEffort(selectEl, epId, modelId, selected) {
+    if (!selectEl) return;
+    while (selectEl.options.length) selectEl.remove(0);
+    var levels = getEffortLevels ? getEffortLevels(epId, modelId) : [];
+    var base = document.createElement('option');
+    base.value = '';
+    base.textContent = 'Provider default';
+    selectEl.appendChild(base);
+    levels.forEach(function(lvl) {
+      var val = typeof lvl === 'string' ? lvl : (lvl && lvl.effort);
+      if (val) {
+        var o = document.createElement('option');
+        o.value = val.toLowerCase();
+        o.textContent = val;
+        selectEl.appendChild(o);
+      }
+    });
+    var validValues = [''].concat(levels.map(function(l) { return (typeof l === 'string' ? l : l.effort).toLowerCase(); }));
+    selectEl.value = validValues.indexOf((selected || '').toLowerCase()) >= 0 ? (selected || '').toLowerCase() : '';
+    selectEl.style.display = levels.length > 0 ? '' : 'none';
+  }
+
   async function save() {
-    var clean = current.filter(function(f) { return f.endpoint_id && f.model; });
+    var clean = current.filter(function(f) { return f.endpoint_id && f.model; }).map(function(f) {
+      var item = { endpoint_id: f.endpoint_id, model: f.model };
+      if (supportsEffort && typeof f.reasoning_effort !== 'undefined') {
+        item.reasoning_effort = f.reasoning_effort || '';
+      }
+      return item;
+    });
     var body = {};
     body[settingKey] = clean;
     try {
@@ -270,13 +300,36 @@ function _bindFallbackWidget(opts) {
       fb.endpoint_id = epS.value;
       fb.model = mS.value;
 
+      var effS = null;
+      if (supportsEffort) {
+        effS = document.createElement('select');
+        effS.className = 'settings-select settings-fallback-effort';
+        fillEffort(effS, epS.value, mS.value, fb.reasoning_effort);
+        fb.reasoning_effort = effS.value;
+        effS.addEventListener('change', function() {
+          fb.reasoning_effort = effS.value;
+          save();
+        });
+      }
+
       epS.addEventListener('change', function() {
         fb.endpoint_id = epS.value;
         fillModels(mS, epS.value, '');
         fb.model = mS.value;
+        if (effS) {
+          fillEffort(effS, epS.value, mS.value, '');
+          fb.reasoning_effort = effS.value;
+        }
+        save();
+      });
+      mS.addEventListener('change', function() {
+        fb.model = mS.value;
+        if (effS) {
+          fillEffort(effS, epS.value, mS.value, fb.reasoning_effort);
+          fb.reasoning_effort = effS.value;
+        }
         save();
       });
-      mS.addEventListener('change', function() { fb.model = mS.value; save(); });
 
       var rm = document.createElement('button');
       rm.type = 'button';
@@ -292,6 +345,7 @@ function _bindFallbackWidget(opts) {
       row.appendChild(num);
       row.appendChild(epS);
       row.appendChild(mS);
+      if (effS) row.appendChild(effS);
       row.appendChild(rm);
       fbContainer.appendChild(row);
     });
@@ -299,7 +353,7 @@ function _bindFallbackWidget(opts) {
 
   addBtn.addEventListener('click', function() {
     var first = enabledEps()[0];
-    current.push({ endpoint_id: first ? first.id : '', model: '' });
+    current.push({ endpoint_id: first ? first.id : '', model: '', reasoning_effort: '' });
     render();
     save();
   });
@@ -371,9 +425,14 @@ async function initDefaultChat() {
 async function initUtilityModel() {
   var epSel = el('set-utilityEpSelect');
   var modelSel = el('set-utilityModelSelect');
+  var effortSel = el('set-utilityEffortSelect');
+  var effortRow = el('set-utilityEffortRow');
+  var effortHelp = el('set-utilityEffortHelp');
+  var effortQualifier = el('set-utilityEffortQualifier');
   var msg = el('set-utilityChatMsg');
   var _endpoints = [];
   var fallbackWidget = null;
+  var _levelsByEndpoint = {};
   if (epSel && epSel.options[0]) epSel.options[0].textContent = 'Same as chat';
   if (modelSel && modelSel.options[0]) modelSel.options[0].textContent = 'Same as chat';
 
@@ -382,24 +441,110 @@ async function initUtilityModel() {
     _fillEndpointSelect(epSel, _endpoints, epSel.value, true);
   } catch (e) { console.warn('Failed to load endpoints for utility model', e); }
 
+  // Effort levels come from /api/models `models_metadata` (same evidence the
+  // chat composer uses); /api/model-endpoints does not carry them.
+  async function loadEffortLevels() {
+    try {
+      var r = await fetch('/api/models', { credentials: 'same-origin' });
+      if (!r.ok) return;
+      var data = await r.json();
+      var items = Array.isArray(data) ? data : (data.models || data.items || []);
+      _levelsByEndpoint = {};
+      items.forEach(function(item) {
+        if (item && item.endpoint_id) _levelsByEndpoint[item.endpoint_id] = item.models_metadata || {};
+      });
+    } catch (e) { console.warn('Failed to load reasoning levels for utility model', e); }
+  }
+
+  function refreshEffort(selected) {
+    if (!effortSel) return;
+    var targetEp = epSel.value;
+    var targetModel = modelSel.value;
+    if (!targetEp) {
+      var defEp = el('set-defaultEpSelect');
+      var defModel = el('set-defaultModelSelect');
+      if (defEp) targetEp = defEp.value;
+      if (defModel) targetModel = defModel.value;
+    }
+    var meta = (_levelsByEndpoint[targetEp] || {})[targetModel] || {};
+    var levels = Array.isArray(meta.supported_reasoning_levels) ? meta.supported_reasoning_levels.slice() : [];
+    var isInherited = !epSel.value;
+    if (isInherited && levels.length === 0) {
+      var allLevels = {};
+      Object.keys(_levelsByEndpoint).forEach(function(epId) {
+        var models = _levelsByEndpoint[epId] || {};
+        Object.keys(models).forEach(function(mId) {
+          var mLevels = (models[mId] || {}).supported_reasoning_levels;
+          if (Array.isArray(mLevels)) {
+            mLevels.forEach(function(lvl) {
+              var val = typeof lvl === 'string' ? lvl : (lvl && lvl.effort);
+              if (val) allLevels[val.toLowerCase()] = true;
+            });
+          }
+        });
+      });
+      levels = Object.keys(allLevels);
+      if (levels.length === 0) {
+        levels = ['low', 'medium', 'high'];
+      }
+    }
+    while (effortSel.options.length) effortSel.remove(0);
+    var base = document.createElement('option');
+    base.value = '';
+    base.textContent = isInherited ? 'Same as chat' : 'Provider default';
+    if (effortQualifier) effortQualifier.style.display = isInherited ? '' : 'none';
+    effortSel.appendChild(base);
+    if (isInherited) {
+      var offOpt = document.createElement('option');
+      offOpt.value = 'off';
+      offOpt.textContent = 'Provider default';
+      effortSel.appendChild(offOpt);
+    }
+    levels.forEach(function(level) {
+      var opt = document.createElement('option');
+      opt.value = level;
+      opt.textContent = level;
+      effortSel.appendChild(opt);
+    });
+    var validValues = [''].concat(isInherited ? ['off'] : []).concat(levels);
+    effortSel.value = validValues.indexOf(selected) >= 0 ? selected : '';
+    var show = isInherited || levels.length > 0;
+    if (effortRow) effortRow.style.display = show ? '' : 'none';
+    if (effortHelp) effortHelp.style.display = show ? '' : 'none';
+  }
+
   function refreshModels(selectedModel) {
     var epId = epSel.value;
     var ep = _endpoints.find(function(e) { return e.id === epId; });
     _fillModelSelect(modelSel, ep ? ep.models : [], selectedModel, true);
   }
 
+  await loadEffortLevels();
+
   try {
     var res = await fetch('/api/auth/settings', { credentials: 'same-origin' });
     var settings = await res.json();
     if (settings.utility_endpoint_id) epSel.value = settings.utility_endpoint_id;
     refreshModels(settings.utility_model || '');
+    refreshEffort(settings.utility_reasoning_effort || '');
     fallbackWidget = _bindFallbackWidget({
       containerId: 'set-utilityFallbacks',
       addBtnId: 'set-utilityAddFallback',
       endpoints: function() { return _endpoints; },
       settingKey: 'utility_model_fallbacks',
+      supportsEffort: true,
+      getEffortLevels: function(epId, modelId) {
+        var meta = (_levelsByEndpoint[epId] || {})[modelId] || {};
+        return Array.isArray(meta.supported_reasoning_levels) ? meta.supported_reasoning_levels : [];
+      },
       initial: Array.isArray(settings.utility_model_fallbacks)
-        ? settings.utility_model_fallbacks.map(function(f) { return { endpoint_id: (f && f.endpoint_id) || '', model: (f && f.model) || '' }; })
+        ? settings.utility_model_fallbacks.map(function(f) {
+            return {
+              endpoint_id: (f && f.endpoint_id) || '',
+              model: (f && f.model) || '',
+              reasoning_effort: (f && f.reasoning_effort) || '',
+            };
+          })
         : [],
     });
   } catch (e) { console.warn('Failed to load utility model settings', e); }
@@ -411,20 +556,30 @@ async function initUtilityModel() {
     try {
       await _postSettings({
         utility_endpoint_id: epSel.value || '',
-        utility_model: modelSel.value || ''
+        utility_model: modelSel.value || '',
+        utility_reasoning_effort: effortSel ? (effortSel.value || '') : ''
       });
       msg.textContent = 'Saved'; msg.style.color = 'var(--fg)';
       setTimeout(function() { msg.textContent = ''; }, 1500);
     } catch (e) { msg.textContent = e.status === 403 ? 'Admin access is required to change these settings.' : 'Failed to save'; msg.style.color = 'var(--red)'; }
   }
 
-  epSel.addEventListener('change', function() { refreshModels(''); saveUtility(); });
-  modelSel.addEventListener('change', saveUtility);
+  // A new endpoint/model may not advertise the saved effort; refreshEffort
+  // resets it to the provider default, and saveUtility persists that.
+  epSel.addEventListener('change', function() { refreshModels(''); refreshEffort(''); saveUtility(); });
+  modelSel.addEventListener('change', function() { refreshEffort(effortSel ? effortSel.value : ''); saveUtility(); });
+  if (effortSel) effortSel.addEventListener('change', saveUtility);
+  var defEp = el('set-defaultEpSelect');
+  var defModel = el('set-defaultModelSelect');
+  if (defEp) defEp.addEventListener('change', function() { if (!epSel.value) refreshEffort(effortSel ? effortSel.value : ''); });
+  if (defModel) defModel.addEventListener('change', function() { if (!epSel.value) refreshEffort(effortSel ? effortSel.value : ''); });
 
-  _registerAiEndpointRefresh(function(endpoints) {
+  _registerAiEndpointRefresh(async function(endpoints) {
     _endpoints = endpoints;
     _fillEndpointSelect(epSel, _endpoints, epSel.value, true);
     refreshModels(modelSel.value);
+    await loadEffortLevels();
+    refreshEffort(effortSel ? effortSel.value : '');
     if (fallbackWidget && fallbackWidget.refresh) fallbackWidget.refresh();
   });
 }
diff --git a/tests/test_utility_reasoning_effort.py b/tests/test_utility_reasoning_effort.py
new file mode 100644
index 000000000..1ed2b115b
--- /dev/null
+++ b/tests/test_utility_reasoning_effort.py
@@ -0,0 +1,489 @@
+"""Opt-in ``utility_reasoning_effort`` for utility/background LLM calls.
+
+The setting is resolved in ``task_llm_call_async`` and sent only to candidates
+on the utility chain whose model advertises the level.  Explicit caller values
+win; with the setting empty nothing changes.
+"""
+import asyncio
+
+import pytest
+
+from src import llm_core, task_endpoint
+from src.chatgpt_subscription import validate_reasoning_effort
+
+UTIL = ("https://api.openai.example/v1", "gpt-5.5", {})
+UTIL_FALLBACK = ("https://fallback.example/v1", "gpt-5.5-mini", {})
+OVERRIDE = ("https://override.example/v1", "gpt-5.5", {})
+NO_EVIDENCE = ("https://local.example/v1", "tiny-local-model", {})
+
+
+def _stub_resolvers(monkeypatch, utility):
+    """Stub the resolvers in both modules that look the utility chain up."""
+    from src import endpoint_resolver
+
+    resolve = lambda prefix, *a, **k: {  # noqa: E731
+        "utility": utility, "task": OVERRIDE, "default": NO_EVIDENCE,
+    }[prefix]
+    fallbacks = lambda owner=None: [UTIL_FALLBACK]  # noqa: E731
+    for mod in (task_endpoint, endpoint_resolver):
+        monkeypatch.setattr(mod, "resolve_endpoint", resolve)
+        monkeypatch.setattr(mod, "resolve_utility_fallback_candidates", fallbacks)
+
+
+@pytest.fixture
+def chain(monkeypatch):
+    """Stub the resolvers and capture what reaches llm_call_async per model."""
+    _stub_resolvers(monkeypatch, UTIL)
+
+    async def _quiet(*_a, **_k):
+        return None
+    monkeypatch.setattr(task_endpoint, "wait_for_interactive_quiet", _quiet)
+
+    calls = {}
+
+    async def fake_call(url, model, messages, **kw):
+        calls[url] = kw.get("reasoning_effort")
+        if url != UTIL_FALLBACK[0]:
+            raise RuntimeError("force walk down the chain")
+        return "ok"
+
+    monkeypatch.setattr(llm_core, "llm_call_async", fake_call)
+    return calls
+
+
+def _set_effort(monkeypatch, value):
+    monkeypatch.setattr(
+        "src.settings.get_user_setting",
+        lambda key, owner="", default=None: value if key == "utility_reasoning_effort" else default,
+    )
+
+
+def _run(**kw):
+    return asyncio.run(task_endpoint.task_llm_call_async(
+        [{"role": "user", "content": "hi"}], **kw,
+    ))
+
+
+def test_setting_applies_only_to_utility_chain(chain, monkeypatch):
+    _set_effort(monkeypatch, "high")
+    _run()
+    # The Background Tasks route shares the model id with the utility model but
+    # is a different (url, model) route, so it gets no effort.
+    assert chain[OVERRIDE[0]] is None
+    assert chain[UTIL[0]] == "high"
+    assert chain[UTIL_FALLBACK[0]] == "high"
+
+
+def test_utility_candidate_gets_validated_effort(chain, monkeypatch):
+    _set_effort(monkeypatch, "HIGH")
+    _run()
+    assert chain[UTIL[0]] == "high"
+
+
+def test_effort_without_evidence_is_dropped(chain, monkeypatch):
+    _set_effort(monkeypatch, "high")
+    _stub_resolvers(monkeypatch, ("https://local.example/v1", "tiny-local-model", {}))
+    _run()
+    assert chain["https://local.example/v1"] is None
+
+
+def test_unsupported_level_is_dropped(chain, monkeypatch):
+    _set_effort(monkeypatch, "bogus")
+    _run()
+    assert chain[UTIL[0]] is None
+
+
+def test_empty_setting_changes_nothing(chain, monkeypatch):
+    _set_effort(monkeypatch, "")
+    _run()
+    assert chain and all(effort is None for effort in chain.values())
+
+
+def test_explicit_caller_effort_wins(chain, monkeypatch):
+    _set_effort(monkeypatch, "high")
+    _run(reasoning_effort="low")
+    assert chain and all(effort == "low" for effort in chain.values())
+
+
+def test_fallback_factory_can_override_messages_and_kwargs(monkeypatch):
+    seen = []
+
+    async def fake_call(url, model, messages, **kw):
+        seen.append((model, messages, kw.get("reasoning_effort"), kw.get("temperature")))
+        if len(seen) == 1:
+            raise RuntimeError("first fails")
+        return "ok"
+
+    monkeypatch.setattr(llm_core, "llm_call_async", fake_call)
+
+    def factory(index, url, model, headers):
+        return {"kwargs": {"reasoning_effort": f"e{index}"}}
+
+    out = asyncio.run(llm_core.llm_call_async_with_fallback(
+        [("http://a/v1", "m1", {}), ("http://b/v1", "m2", {})],
+        [{"role": "user", "content": "x"}],
+        temperature=0.1,
+        candidate_request_factory=factory,
+    ))
+    assert out == "ok"
+    assert [(s[0], s[2], s[3]) for s in seen] == [("m1", "e0", 0.1), ("m2", "e1", 0.1)]
+
+
+def test_validate_reasoning_effort_needs_evidence():
+    assert validate_reasoning_effort("gpt-5.5", "high") == "high"
+    assert validate_reasoning_effort("tiny-local-model", "high") is None
+    assert validate_reasoning_effort("gpt-5.5", "") is None
+
+
+def test_chatgpt_wire_carries_effort_and_default_omits_it():
+    sent = llm_core._build_chatgpt_responses_payload(
+        "gpt-5.5", [{"role": "user", "content": "hi"}], 0.3, 64, reasoning_effort="high",
+    )
+    assert sent["reasoning"] == {"effort": "high"}
+    plain = llm_core._build_chatgpt_responses_payload(
+        "gpt-5.5", [{"role": "user", "content": "hi"}], 0.3, 64,
+    )
+    assert "reasoning" not in plain
+
+
+def test_sync_llm_call_cache_key_includes_effort(monkeypatch):
+    keys = []
+
+    def fake_cached(key):
+        keys.append(key)
+        return "cached"
+
+    monkeypatch.setattr(llm_core, "_get_cached_response", fake_cached)
+    msgs = [{"role": "user", "content": "hi"}]
+    llm_core.llm_call("http://x/v1", "m", msgs)
+    llm_core.llm_call("http://x/v1", "m", msgs, reasoning_effort="high")
+    llm_core.llm_call("http://x/v1", "m", msgs, reasoning_effort="HIGH")
+    assert keys[0] != keys[1]
+    assert keys[1] == keys[2]
+
+
+def test_setting_is_registered_default_and_per_user():
+    from src.settings import DEFAULT_SETTINGS, _PER_USER_KEYS
+
+    assert DEFAULT_SETTINGS["utility_reasoning_effort"] == ""
+    assert "utility_reasoning_effort" in _PER_USER_KEYS
+
+
+# --- effort_for_call: setting, then the chat session's own effort ---
+
+CHAT = ("https://chat.example/v1", "gpt-5.5", {})
+
+
+class _Sess:
+    def __init__(self, thinking_mode="effort:low", url=CHAT[0], model=CHAT[1], owner="alice"):
+        self.thinking_mode = thinking_mode
+        self.endpoint_url = url
+        self.model = model
+        self.owner = owner
+        self.headers = {}
+
+
+@pytest.fixture
+def util(monkeypatch):
+    """Utility chain = {UTIL}; the setting is controlled via ``settings[owner]``."""
+    from src import utility_effort
+
+    settings = {}
+    monkeypatch.setattr(utility_effort, "utility_routes", lambda owner=None: {(UTIL[0], UTIL[1])})
+    monkeypatch.setattr(
+        "src.settings.get_user_setting",
+        lambda key, owner="", default=None: (
+            settings.get(owner, "") if key == "utility_reasoning_effort" else default
+        ),
+    )
+    util_mod = utility_effort
+    util_mod.settings = settings
+    return util_mod
+
+
+def test_setting_applies_to_utility_route_and_wins_over_chat_effort(util):
+    util.settings["alice"] = "medium"
+    assert util.effort_for_call(UTIL[0], UTIL[1], "alice", _Sess("effort:low")) == "medium"
+    assert util.effort_for_call(UTIL[0], UTIL[1], "alice") == "medium"
+
+
+def test_setting_is_per_user(util):
+    util.settings["alice"] = "high"
+    assert util.effort_for_call(UTIL[0], UTIL[1], "alice") == "high"
+    assert util.effort_for_call(UTIL[0], UTIL[1], "bob") is None
+
+
+def test_session_effort_inherited_on_the_session_route(util):
+    assert util.effort_for_call(CHAT[0], CHAT[1], "alice", _Sess("effort:low")) == "low"
+    # Endpoint spelling differences (trailing slash) are still the same route.
+    assert util.effort_for_call(CHAT[0] + "/", CHAT[1], "alice", _Sess("effort:low")) == "low"
+
+
+def test_session_effort_not_inherited_on_another_route(util):
+    assert util.effort_for_call(UTIL[0], UTIL[1], "alice", _Sess("effort:low")) is None
+    assert util.effort_for_call(CHAT[0], "gpt-5.5-mini", "alice", _Sess("effort:low")) is None
+
+
+def test_session_effort_off_or_missing_inherits_nothing(util):
+    assert util.effort_for_call(CHAT[0], CHAT[1], "alice", _Sess("off")) is None
+    assert util.effort_for_call(CHAT[0], CHAT[1], "alice", _Sess("")) is None
+
+
+def test_no_session_means_no_inheritance(util):
+    assert util.effort_for_call(CHAT[0], CHAT[1], "alice") is None
+
+
+def test_explicit_off_setting_blocks_session_effort_inheritance(util):
+    util.settings["alice"] = "off"
+    assert util.effort_for_call(CHAT[0], CHAT[1], "alice", _Sess("effort:low")) is None
+    assert util.candidate_effort_factory("alice") is None
+
+    util.settings["alice"] = "default"
+    assert util.effort_for_call(CHAT[0], CHAT[1], "alice", _Sess("effort:low")) is None
+    assert util.candidate_effort_factory("alice") is None
+
+
+def test_inherited_effort_is_validated_against_the_model(util):
+    assert util.effort_for_call(
+        NO_EVIDENCE[0], NO_EVIDENCE[1], "alice",
+        _Sess("effort:low", url=NO_EVIDENCE[0], model=NO_EVIDENCE[1]),
+    ) is None
+    assert util.effort_for_call(CHAT[0], CHAT[1], "alice", _Sess("effort:bogus")) is None
+
+
+def test_effort_for_call_never_raises(util, monkeypatch):
+    def boom(*_a, **_k):
+        raise RuntimeError("db down")
+
+    monkeypatch.setattr(util, "effort_for_route", boom)
+    assert util.effort_for_call(UTIL[0], UTIL[1], "alice", _Sess()) is None
+
+
+# --- no global fill: callers that are not utility call sites never get an effort ---
+
+def test_llm_call_async_adds_no_default_effort(util, monkeypatch):
+    # The owner-less helpers resolve at global scope; set it there and per user.
+    util.settings[""] = util.settings["alice"] = "high"
+    seen = []
+
+    def fake_key(url, model, messages, temperature, max_tokens, headers=None,
+                 thinking_mode=None, reasoning_effort=None):
+        seen.append(reasoning_effort)
+        return "k"
+
+    monkeypatch.setattr(llm_core, "_get_cache_key", fake_key)
+    monkeypatch.setattr(llm_core, "_get_cached_response", lambda key: "cached")
+    msgs = [{"role": "user", "content": "hi"}]
+    # Same (url, model) as the utility route, but not a utility call site.
+    asyncio.run(llm_core.llm_call_async(UTIL[0], UTIL[1], msgs))
+    llm_core.llm_call(UTIL[0], UTIL[1], msgs)
+    asyncio.run(llm_core.llm_call_async(UTIL[0], UTIL[1], msgs, reasoning_effort="low"))
+    assert seen == [None, None, "low"]
+
+
+# --- call sites pass the effort explicitly ---
+
+def _capture_llm(monkeypatch):
+    sent = []
+
+    async def fake_call(url, model, messages, **kw):
+        sent.append((url, model, kw.get("reasoning_effort")))
+        return "A title"
+
+    monkeypatch.setattr(llm_core, "llm_call_async", fake_call)
+    return sent
+
+
+class _History:
+    role = "user"
+    content = "hello there"
+
+
+def _title_session(**kw):
+    sess = _Sess(**kw)
+    sess.id = "s1"
+    sess.history = [_History()]
+    return sess
+
+
+class _Manager:
+    def update_session_name(self, *_a):
+        pass
+
+
+def test_auto_title_inherits_chat_effort_when_utility_is_blank(util, monkeypatch):
+    from routes import chat_helpers
+
+    sent = _capture_llm(monkeypatch)
+    # Blank utility/task resolves to the session's own route.
+    monkeypatch.setattr(task_endpoint, "resolve_task_endpoint", lambda *a, **k: (CHAT[0], CHAT[1], {}))
+    asyncio.run(chat_helpers.auto_name_session(_Manager(), _title_session()))
+    assert sent == [(CHAT[0], CHAT[1], "low")]
+
+
+def test_auto_title_setting_beats_chat_effort(util, monkeypatch):
+    from routes import chat_helpers
+
+    util.settings["alice"] = "medium"
+    sent = _capture_llm(monkeypatch)
+    monkeypatch.setattr(task_endpoint, "resolve_task_endpoint", lambda *a, **k: (UTIL[0], UTIL[1], {}))
+    asyncio.run(chat_helpers.auto_name_session(_Manager(), _title_session()))
+    assert sent == [(UTIL[0], UTIL[1], "medium")]
+
+
+def test_auto_title_on_a_different_utility_model_gets_no_chat_effort(util, monkeypatch):
+    from routes import chat_helpers
+
+    sent = _capture_llm(monkeypatch)
+    monkeypatch.setattr(task_endpoint, "resolve_task_endpoint", lambda *a, **k: (UTIL[0], UTIL[1], {}))
+    asyncio.run(chat_helpers.auto_name_session(_Manager(), _title_session()))
+    assert sent == [(UTIL[0], UTIL[1], None)]
+
+
+def test_memory_extraction_passes_chat_effort(util, monkeypatch):
+    from services.memory import memory_extractor
+
+    sent = []
+
+    async def fake_call(url, model, messages, **kw):
+        sent.append(kw.get("reasoning_effort"))
+        return "[]"
+
+    monkeypatch.setattr(llm_core, "llm_call_async", fake_call)
+
+    class Sess(_Sess):
+        def get_context_messages(self):
+            return [{"role": "user", "content": "I live in Oslo"},
+                    {"role": "assistant", "content": "Noted"}]
+
+    asyncio.run(memory_extractor.extract_and_store(
+        Sess(), object(), object(), CHAT[0], CHAT[1], {},
+    ))
+    assert sent and sent[0] == "low"
+
+
+def test_email_summary_sends_setting_effort_for_owner_only(util, monkeypatch):
+    from routes.email import email_helpers
+
+    util.settings["alice"] = "medium"
+    sent = []
+
+    async def fake_call(**kw):
+        sent.append(kw.get("reasoning_effort"))
+        return "- point"
+
+    monkeypatch.setattr(llm_core, "llm_call_async", fake_call)
+    for owner in ("alice", "bob", None):
+        asyncio.run(email_helpers._generate_email_summary(
+            UTIL[0], UTIL[1], "a@x", "s", "body", owner=owner,
+        ))
+    assert sent == ["medium", None, None]
+
+
+def test_candidate_effort_factory_scopes_to_utility_route(util):
+    from src.utility_effort import candidate_effort_factory
+
+    assert candidate_effort_factory("alice") is None
+    util.settings["alice"] = "medium"
+    factory = candidate_effort_factory("alice")
+    assert factory(0, UTIL[0], UTIL[1], {}) == {"kwargs": {"reasoning_effort": "medium"}}
+    assert factory(1, NO_EVIDENCE[0], NO_EVIDENCE[1], {}) == {}
+    assert candidate_effort_factory("bob") is None
+
+
+def test_fallback_route_efforts_and_factory(monkeypatch):
+    from src.utility_effort import candidate_effort_factory, effort_for_route
+
+    def fake_resolve_id(ep_id, model, owner=None):
+        if ep_id == "ep-fallback":
+            return ("https://fallback.example/v1", model, {})
+        return None
+
+    monkeypatch.setattr("src.endpoint_resolver.resolve_endpoint_by_id", fake_resolve_id)
+    monkeypatch.setattr(
+        "src.settings.load_settings",
+        lambda: {"utility_model_fallbacks": [{"endpoint_id": "ep-fallback", "model": "gpt-5.5-mini", "reasoning_effort": "low"}]},
+    )
+    monkeypatch.setattr(
+        "src.settings.get_user_setting",
+        lambda key, owner="", default=None: default,
+    )
+
+    factory = candidate_effort_factory("alice")
+    assert factory is not None
+    assert effort_for_route("https://api.openai.example/v1", "gpt-5.5", "alice") is None
+    assert effort_for_route("https://fallback.example/v1", "gpt-5.5-mini", "alice") == "low"
+    assert factory(0, "https://fallback.example/v1", "gpt-5.5-mini", {}) == {"kwargs": {"reasoning_effort": "low"}}
+
+
+def test_sync_openai_compatible_wire_transmits_explicit_effort(monkeypatch):
+    import httpx
+
+    sent = []
+
+    def fake_post(url, headers, **kwargs):
+        sent.append(dict(kwargs["json"]))
+        return httpx.Response(
+            200, json={"choices": [{"message": {"content": "ok"}}]}
+        )
+
+    monkeypatch.setattr(llm_core, "_get_cached_response", lambda *_: None)
+    monkeypatch.setattr(llm_core, "_set_cached_response", lambda *a, **k: None)
+    monkeypatch.setattr(llm_core, "note_model_activity", lambda *a: None)
+    monkeypatch.setattr(llm_core, "httpx_post_kimi_aware", fake_post)
+
+    url = "https://example.test/v1"
+    messages = [{"role": "user", "content": "hi"}]
+
+    llm_core.llm_call(
+        url, "gpt-5.5", messages, max_tokens=64,
+        reasoning_effort="HIGH",
+    )
+    llm_core.llm_call(url, "gpt-5.5", messages, max_tokens=64)
+
+    assert sent[0]["reasoning_effort"] == "high"
+    assert "reasoning_effort" not in sent[1]
+
+
+def test_async_openai_compatible_wire_transmits_explicit_effort(monkeypatch):
+    import asyncio
+    import httpx
+    from contextlib import asynccontextmanager
+
+    sent = []
+
+    @asynccontextmanager
+    async def fake_slot(*args, **kwargs):
+        yield
+
+    async def fake_post(client, url, headers, **kwargs):
+        sent.append(dict(kwargs["json"]))
+        return httpx.Response(
+            200, json={"choices": [{"message": {"content": "ok"}}]}
+        )
+
+    monkeypatch.setattr(llm_core, "_get_cached_response", lambda *_: None)
+    monkeypatch.setattr(llm_core, "_set_cached_response", lambda *a, **k: None)
+    monkeypatch.setattr(llm_core, "_get_http_client", lambda: object())
+    monkeypatch.setattr(llm_core, "_is_host_dead", lambda *_: False)
+    monkeypatch.setattr(llm_core, "_local_model_slot", fake_slot)
+    monkeypatch.setattr(llm_core, "note_model_activity", lambda *a: None)
+    monkeypatch.setattr(llm_core, "httpx_post_kimi_aware_async", fake_post)
+
+    async def exercise():
+        url = "https://example.test/v1"
+        messages = [{"role": "user", "content": "hi"}]
+
+        await llm_core.llm_call_async(
+            url, "gpt-5.5", messages, max_tokens=0,
+            max_retries=1, reasoning_effort="medium",
+        )
+        await llm_core.llm_call_async(
+            url, "gpt-5.5", messages, max_tokens=0,
+            max_retries=1,
+        )
+
+    asyncio.run(exercise())
+
+    assert sent[0]["reasoning_effort"] == "medium"
+    assert "reasoning_effort" not in sent[1]

From b5b76fe46d86ccd9c9079602df272b36dbd91826 Mon Sep 17 00:00:00 2001
From: Harshit Ojha <92013456+harshit-ojha0324@users.noreply.github.com>
Date: Tue, 13 Oct 2026 16:02:23 -0400
Subject: [PATCH 07/53] fix(skills): inject published skills when Auto-approve
 is off (#6643)

With Auto-approve OFF the agent loop asked get_relevant_skills for
min_confidence=2.0, meant as 'published only'. The gate applies the
confidence check to published skills too, and confidence is 0-1, so no
user skill was ever injected, published or not. The explicit-activation
path already treats OFF as status == published.

Add a published_only flag to get_relevant_skills and pass it from both
callers that used the sentinel (relevance injection and the skill
preflight). Auto-approve ON is unchanged: a skill still needs a passing
audit and the confidence threshold.

Fixes #6634
---
 services/memory/skills.py                | 13 ++++++++++---
 src/agent_loop.py                        | 12 ++++++++----
 tests/test_skill_index_toolset_gating.py | 17 +++++++++++++++++
 3 files changed, 35 insertions(+), 7 deletions(-)

diff --git a/services/memory/skills.py b/services/memory/skills.py
index 713ae2199..5bf583389 100644
--- a/services/memory/skills.py
+++ b/services/memory/skills.py
@@ -745,6 +745,7 @@ class SkillsManager:
         min_confidence: float = 0.0,
         available_toolsets: Optional[Iterable[str]] = None,
         platform: Optional[str] = None,
+        published_only: bool = False,
     ) -> List[Dict]:
         if skills is None:
             skills = self.load_all()
@@ -775,9 +776,15 @@ class SkillsManager:
                 if not skill.get("platforms") or platform in skill.get("platforms", [])
             ]
         # Prompt injection is fail-closed for user skills. Built-ins are
-        # shipped procedures; every other skill needs a passing audit and a
-        # confidence score at the user's current threshold.
-        if min_confidence > 0:
+        # shipped procedures. With Auto-approve OFF (published_only), the
+        # user's publish is the approval; otherwise a skill needs a passing
+        # audit and a confidence score at the user's current threshold.
+        if published_only:
+            skills = [
+                s for s in skills
+                if s.get("source") == "builtin" or s.get("status") == "published"
+            ]
+        elif min_confidence > 0:
             def _passes(s):
                 if s.get("source") == "builtin":
                     return True
diff --git a/src/agent_loop.py b/src/agent_loop.py
index 6301e86a5..c7d1f179c 100644
--- a/src/agent_loop.py
+++ b/src/agent_loop.py
@@ -10325,9 +10325,10 @@ def _has_matching_skill_for_turn(
         ))))
         if max_items == 0:
             return False
+        published_only = not prefs.get("auto_approve_skills", True)
         min_confidence = (
-            2.0
-            if not prefs.get("auto_approve_skills", True)
+            0.0
+            if published_only
             else float(prefs.get(
                 "skill_min_confidence",
                 get_setting("skill_autosave_min_confidence", 0.85),
@@ -10344,6 +10345,7 @@ def _has_matching_skill_for_turn(
             threshold=0.25,
             max_items=max_items,
             min_confidence=min_confidence,
+            published_only=published_only,
         ))
     except Exception as exc:
         logger.debug("skill preflight failed (non-fatal): %s", exc)
@@ -14952,8 +14954,9 @@ def _build_system_prompt(
                 # confidence threshold. Approve OFF → published-only (no draft
                 # passes). Approve ON → drafts at/above the chosen confidence
                 # (0 = "All"). Falls back to the global default setting.
-                if not _prefs.get("auto_approve_skills", True):
-                    _skill_min_conf = 2.0  # nothing draft clears it → published only
+                _skill_published_only = not _prefs.get("auto_approve_skills", True)
+                if _skill_published_only:
+                    _skill_min_conf = 0.0  # published_only decides eligibility
                 else:
                     try:
                         _skill_min_conf = float(_prefs.get(
@@ -14976,6 +14979,7 @@ def _build_system_prompt(
                         max_items=_skill_max_injected,
                         min_confidence=_skill_min_conf,
                         available_toolsets=relevant_tools,
+                        published_only=_skill_published_only,
                     ) if _skill_max_injected > 0 else []
                 else:
                     # Explicit client activation chooses which eligible skill
diff --git a/tests/test_skill_index_toolset_gating.py b/tests/test_skill_index_toolset_gating.py
index 92ea8f578..8a93933ae 100644
--- a/tests/test_skill_index_toolset_gating.py
+++ b/tests/test_skill_index_toolset_gating.py
@@ -133,3 +133,20 @@ def test_unaudited_or_below_threshold_published_skill_is_not_injected(tmp_path):
     assert not sm.get_relevant_skills(
         "premature skill", min_confidence=0.80,
     )
+
+
+def test_auto_approve_off_injects_published_skills_without_an_audit(tmp_path):
+    # #6634: OFF used min_confidence=2.0, which no 0-1 confidence clears, so
+    # every user skill was rejected. Publishing is the approval when OFF.
+    (tmp_path / "skills").mkdir()
+    for name, status in (("premature-skill", "published"), ("draft-skill", "draft")):
+        path = _write_skill_md(tmp_path / "skills", name)
+        text = path.read_text(encoding="utf-8").replace("audit_verdict: pass\n", "")
+        path.write_text(text.replace("status: published", f"status: {status}"), encoding="utf-8")
+    sm = SkillsManager(str(tmp_path))
+
+    query = "premature skill draft skill"
+    # threshold=0 isolates the eligibility gate from relevance scoring.
+    assert _names(sm.get_relevant_skills(query, threshold=0.0, published_only=True)) == {"premature-skill"}
+    # Auto-approve ON still needs a passing audit, as before.
+    assert not sm.get_relevant_skills(query, threshold=0.0, min_confidence=0.85)

From 1cc56cb9d78f3e2399d1d61155b71d771a17b85b Mon Sep 17 00:00:00 2001
From: Alexandre Teixeira <111787685+alteixeira20@users.noreply.github.com>
Date: Tue, 13 Oct 2026 21:03:48 +0100
Subject: [PATCH 08/53] refactor(frontend): establish source ownership and
 architecture gates (#6701)

---
 .gitattributes                                |   4 +
 .github/workflows/ci.yml                      |  10 +-
 .../ADR-001-source-and-deployment.md          | 135 ++++++
 docs/frontend-architecture/assessment.md      | 127 +++++
 docs/frontend-architecture/handbook.md        | 223 +++++++++
 docs/frontend-architecture/notes-roadmap.md   | 173 +++++++
 docs/frontend-architecture/validation.md      | 453 ++++++++++++++++++
 frontend/modules.json                         |   9 +
 frontend/src/package.json                     |   4 +
 frontend/src/shared/actionMenuOrder.js        |  29 ++
 package-lock.json                             |  16 +-
 package.json                                  |   3 +-
 scripts/build_frontend.py                     | 148 ++++++
 scripts/check_frontend.mjs                    | 180 +++++++
 scripts/verify_frontend_runtime.py            |  69 +++
 tests/frontendArchitecture.test.mjs           | 142 ++++++
 tests/test_frontend_build.py                  | 170 +++++++
 tests/test_frontend_foundation_offline_js.py  |  63 +++
 18 files changed, 1955 insertions(+), 3 deletions(-)
 create mode 100644 docs/frontend-architecture/ADR-001-source-and-deployment.md
 create mode 100644 docs/frontend-architecture/assessment.md
 create mode 100644 docs/frontend-architecture/handbook.md
 create mode 100644 docs/frontend-architecture/notes-roadmap.md
 create mode 100644 docs/frontend-architecture/validation.md
 create mode 100644 frontend/modules.json
 create mode 100644 frontend/src/package.json
 create mode 100644 frontend/src/shared/actionMenuOrder.js
 create mode 100644 scripts/build_frontend.py
 create mode 100644 scripts/check_frontend.mjs
 create mode 100644 scripts/verify_frontend_runtime.py
 create mode 100644 tests/frontendArchitecture.test.mjs
 create mode 100644 tests/test_frontend_build.py
 create mode 100644 tests/test_frontend_foundation_offline_js.py

diff --git a/.gitattributes b/.gitattributes
index 8681aee12..dd49c4a03 100644
--- a/.gitattributes
+++ b/.gitattributes
@@ -10,6 +10,10 @@
 entrypoint.sh text eol=lf
 docker/entrypoint.sh text eol=lf
 
+# Maintained frontend modules and this lane's byte-identical deployment output.
+frontend/src/** text eol=lf
+static/js/actionMenuOrder.js text eol=lf
+
 # Windows-native scripts stay CRLF.
 *.ps1 text eol=crlf
 *.cmd text eol=crlf
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 51e12d341..42f0651f0 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -81,6 +81,8 @@ jobs:
           python-version: "3.11"
       # Byte-compile sources — catches syntax errors without installing deps.
       - run: python -m compileall -q app.py core routes src services scripts tests
+      - name: Check committed frontend deployment modules
+        run: python scripts/build_frontend.py --check
 
   node-syntax:
     name: JS syntax (node --check)
@@ -92,13 +94,19 @@ jobs:
       - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020  # v7.0.0
         with:
           node-version: "20"
+      - run: npm ci --ignore-scripts --no-audit --no-fund
+      - name: Check frontend architecture
+        run: node scripts/check_frontend.mjs
       # Syntax-check our own JS (skip vendored libs in static/lib).
       - name: node --check
         run: |
           shopt -s globstar nullglob
-          for f in static/app.js static/js/**/*.js; do
+          for f in static/app.js static/js/**/*.js frontend/src/**/*.js; do
             node --check "$f"
           done
+          node --check scripts/check_frontend.mjs
+      - name: Test frontend architecture gates and stateless proof
+        run: node --test tests/frontendArchitecture.test.mjs
 
   python-tests:
     name: Python tests (pytest ${{ matrix.shard }})
diff --git a/docs/frontend-architecture/ADR-001-source-and-deployment.md b/docs/frontend-architecture/ADR-001-source-and-deployment.md
new file mode 100644
index 000000000..cc1eca04e
--- /dev/null
+++ b/docs/frontend-architecture/ADR-001-source-and-deployment.md
@@ -0,0 +1,135 @@
+# ADR 001: Feature-first native ESM with controlled deployment output
+
+Date: 2026-10-13. Status: implemented F1 proof, proposed for maintainer adoption.
+Baseline: official `upstream/dev` at `8feb50e89468235cd3e0986da80edbd3acaf2c40`.
+Scope: source ownership and distribution foundation. Notes implementation is deferred.
+
+## Decision
+
+Maintain migrated JavaScript in `frontend/src/`. Publish native ES modules to
+explicitly registered paths in `static/js/`, and commit source and output together.
+Use `python scripts/build_frontend.py` to copy bytes without rewriting imports,
+bundling, minification, source maps, timestamps or generated headers. A checked-in
+`frontend/modules.json` maps source paths to deployment paths. All other static
+files remain authored legacy modules or deployment assets until a reviewed slice
+transfers their ownership. Do not claim that the whole static tree is generated.
+
+The proof transfers maintenance of the stateless action-menu ordering helper to
+`frontend/src/shared/actionMenuOrder.js`. Its output remains
+`/static/js/actionMenuOrder.js`, with the same three exports and identical bytes.
+All seven current consumers, HTML, service worker and runtime entry points retain
+their existing URLs. There is no wrapper, extra request or second browser module
+instance. The source copy is a development input, not a second runtime entry point.
+
+Use `frontend/src/app/` for composition, `features/<feature>/index.js` for feature
+public APIs, and responsibility directories only when implementation requires
+them. The [handbook](handbook.md) defines dependency, ownership and lifecycle rules.
+F1 creates only the shared proof, without empty application or feature scaffolding.
+
+## Evidence and alternatives
+
+Both options were executed against this helper, rather than assumed to work.
+Measurements are local compatibility observations, not general performance claims.
+
+| Property | Controlled native ESM copy, selected | esbuild 0.25.12 controlled ESM build |
+| --- | --- | --- |
+| Proof output | 1,688 bytes, identical SHA-256 to existing runtime | 1,554 bytes with `--bundle --format=esm --target=es2022 --platform=browser` |
+| Repeatability | Clean temporary publication and idempotent rerun tested | Two independent compiler invocations emitted identical bytes |
+| Runtime contract | Existing exports, imports, cache entry and module identity unchanged | Export names, icon and ordering matched in an executed Node import |
+| Tooling | Python standard library; no production dependency | Compiler and platform binary needed for artifact production |
+| Local cost | Copy check: 0.03 s, 15,596 KB maximum RSS | Cached `npx` ESM transform: 0.58 s, 114,196 KB maximum RSS |
+| Incremental migration | Explicit file ownership, preserved module boundaries | Feasible for the stateless leaf; stateful facade/chunk identity still needs a separate graph spike |
+| Release implications | Commit output; install/startup paths consume existing static assets | Would also need committed or release-produced output plus compiler locking and facade/chunk manifest policy |
+
+The timing rows measure different tool paths, including `npx` overhead. The
+compiler's single-leaf success does not establish stateful graph or lazy chunk
+compatibility. The 134-byte bundle reduction does not justify that additional
+contract in F1. A future compiler adoption requires a new ADR and graph-level
+evidence. React, Vue, TypeScript, a global state library, hashed chunks and a
+development server have no demonstrated necessity here.
+
+Acorn 8.19.0 is added only as an exact, lockfile-pinned development dependency for
+architecture checks. A real JavaScript parser is needed to enforce boundaries
+across multiline imports, re-exports and lazy thunks without treating comments
+and string literals as executable imports. It is MIT licensed, about 568 KB
+unpacked, and contributes no deployed JavaScript or runtime dependency.
+
+## Distribution contract
+
+1. Source and generated output are reviewed and committed together. CI checks
+   byte parity; it does not silently rebuild and accept drift.
+2. Native Python startup continues to use `STATIC_DIR` and `/static`, without
+   invoking the publisher. Native installers already obtain tracked static files.
+3. Docker's current `COPY . .` includes the output. `.dockerignore` excludes
+   `node_modules/`. The Docker runtime and entrypoint require no frontend build.
+4. `Odysseus.spec` and `build-windows-portable.ps1` already include `static/`.
+   The macOS wrapper uses the Python checkout and its static assets. Neither
+   needs the source tree or frontend tooling to serve the proof.
+5. A release producer runs the checks before packaging and distributes the
+   entire matching static graph. The publisher is not a transactional deployment
+   mechanism. Partial copying of a new graph into a live deployment is unsupported.
+6. New output paths must declare LF checkout behavior in `.gitattributes`, as
+   this proof does, so Windows checkout conversion cannot create false byte drift.
+   Before checking parity or writing output, the publisher uses the manifest to
+   require effective `text: set` and `eol: lf` on every source/output path. It asks
+   Git in a temporary repository containing only the applicable repository-owned
+   `.gitattributes` files, including nested rules. Global/local Git overrides
+   cannot supply missing declarations. No blanket legacy-JS rule is introduced.
+   Git is a development/publication prerequisite, not a startup dependency.
+
+An isolated distribution probe executes the real FastAPI lifespan, shell and
+static requests after omitting `frontend/` and `node_modules/` and removing Node
+from the child process search path. It verifies bytes, MIME, CSP, revalidation,
+source-tree 404 behavior and static path confinement. The same probe runs in an existing Docker image
+with networking disabled. This is not a claim that a fresh full Docker image or
+Windows/macOS executable was built; see [validation](validation.md).
+
+## Imports, identity and offline operation
+
+New maintained modules use one unversioned deployment URL. Existing legacy URLs,
+including their version queries, stay unchanged. A copy mapping must preserve
+the resolution of every literal relative import; the architecture checker rejects
+a mapping that changes that resolution. Canonical absolute `/static/js/...`
+imports are also supported. No bare packages or browser imports of `frontend/src`
+are supported. Existing graph and identity guards continue to cover the runtime.
+
+Each registered output joins the exact `PRECACHE` or `PANEL_PRECACHE` array. The
+new checker parses those arrays, rather than accepting a URL mentioned in a
+comment. Installation fetches do not evaluate lazy modules. Import-time DOM work,
+timers, state creation and network I/O must be characterized before changing an
+entry point's load timing. New source dependency cycles are rejected; existing
+legacy cycles are inventoried and remain outside the new rules.
+
+The proof already has its exact precache entry, so no SW cache-name or HTML edit
+is needed. Its first evaluation in a fresh offline browser page passes, and
+importing the panel registry does not evaluate the editor. The current worker's
+`/static/` scope cannot control the SPA root. Open PR #6227 addresses that existing
+limitation; F1 does not fix or mask it. Full root offline reload is not certified.
+
+## Security and compatibility
+
+Keep backend authorization and owner scope authoritative. No agent, database,
+auth, CSP, static mount or API implementation changes belong to this decision.
+The helper remains same-origin ESM without eval, compiler runtime or external
+resources. No new source maps or vendored assets are emitted; existing SRI/CSP
+policy and distribution notices remain unchanged. The publisher validates path
+containment, symlinks, duplicate ownership and unmapped source before writing.
+It never deletes unowned static assets. Deleting or retiring outputs is an
+explicit reviewed migration operation, not automatic cleanup.
+
+## Rollout, rollback and limits
+
+Adopt F1 for controlled, reviewed slices after maintainer review. Leave Notes,
+bootstrap, HTML and service worker unchanged here. Register new files explicitly;
+update offline manifests only when new runtime dependencies are introduced.
+F1 rollback can remove the source manifest, proof tooling, gates and documentation
+without changing runtime bytes. Later rollback restores the complete prior
+source/output/facade/precache set through an authorized follow-up change.
+
+Boundary gates cannot prove semantic purity, owner isolation or correct teardown.
+Domain platform/clock checks are intentionally conservative syntax guards;
+behavior tests still establish those contracts. Worker URLs, styles and vendored
+libraries are outside the maintained-JS import gate and need explicit review if
+a future lane changes them. Legacy exceptions require an exact specifier and a
+module-scoped reason; there are none in F1. New source is not permission to
+grandfather new dependency cycles or to replicate broadly shared mutable state.
diff --git a/docs/frontend-architecture/assessment.md b/docs/frontend-architecture/assessment.md
new file mode 100644
index 000000000..d5c746c7c
--- /dev/null
+++ b/docs/frontend-architecture/assessment.md
@@ -0,0 +1,127 @@
+# F1 runtime and architecture assessment
+
+Assessment date: 2026-10-13. Repository: `odysseus-dev/odysseus`.
+Worktree: `worktrees/architecture/frontend-foundation`.
+Branch: `refactor/frontend-architecture-foundation`.
+HEAD, local `upstream/dev`, and the live GitHub official `dev` commit were all
+`8feb50e89468235cd3e0986da80edbd3acaf2c40`. The initial worktree was clean.
+That commit is the merged PR #6495, selected Notes/Todos agent context.
+`origin` points to the maintainer fork; integration targets official `upstream/dev`.
+
+Inputs read completely: the 2026-10-13 frontend architecture RFC and coding brief
+from Downloads, `specs/frontend.md`, repository instructions and existing tests.
+The current user brief supersedes the coding brief's `origin/dev` wording and
+defines the Notes state/workflow slice before reminders. The design is self-contained
+in this directory and does not require access to Downloads.
+
+Input provenance:
+
+- RFC SHA-256: `11dedcbb9971f4d787f2721b9c27aa43299baba39ca91066d01507d2d69ac4f8`.
+- Coding brief SHA-256: `e4882867617b9c732ce4f445e3bc2da0b4ec1315119f8226c1fd8c1acbacf29d`.
+
+## Module graph and bootstrap
+
+`node scripts/check_frontend.mjs --inventory` reproduces the parser-based inventory.
+It excludes vendored `static/lib/` and committed editor build output. At this base
+it scans 230 JS files, finds 707 static import/re-export edges and 108 literal
+dynamic import edges, and finds no missing targets. No computed dynamic imports
+were found in the original parser audit. The earlier existing-regex scan counted
+814 edges; executable syntax parsing counts 815. Use parser evidence for design
+and retain the existing regression guard unchanged.
+
+| Area | Current boundary and implication |
+| --- | --- |
+| HTML shell | `static/index.html`: nonce-bearing boot scripts, CSS/preloads, direct ESM script tags, then app/init/a11y. Multiple entry roots mean module identity matters. |
+| App composition | `static/app.js`: feature imports, globals, route/sidebar composition, session hydration and auth-fetch wiring. It eagerly imports Notes, Calendar, Chat, Documents and Settings. |
+| Startup | `static/js/startupShell.js`, `sessions.js`, `init.js`: first-paint scheduling, deferred hydration, user-switch storage cleanup and cosmetic permission gates. Preserve boot ordering. |
+| Lazy loading | `static/js/panels.js`: only `editor` is registered. A memoized import thunk shares successful/in-flight promises and retries failed imports. Do not label all panels lazy. |
+| Optional libraries | `markdown.js` lazily loads vendored KaTeX/Mermaid. KaTeX and fonts are precached; Mermaid becomes cached after first use. Pyodide has a CDN dependency. |
+| Feature packages | Settings registry/navigation/finder/lifecycle, Calendar utilities/reminders, Email wrapper/package and editor tools already demonstrate partial decomposition. |
+
+Highest import fan-in: `ui.js` 77, `spinner.js` 55, `editor/state.js` 39,
+`escMenuStack.js` 23, and storage/modal/z-order helpers 17 each. The measured
+static strongly connected components are:
+
+- Theme and UI.
+- Email Inbox, compatibility wrapper, package index, AI reply, attachments,
+  body rendering, menus, reader, settings page and unsubscribe.
+- Cookbook, diagnosis, HW Fit, download, running and serve modules.
+
+These are existing compatibility constraints, not approved patterns for new
+source. Dynamic edges connect more features but do not themselves establish
+initialization cycles. No global legacy dependency rewrite is attempted in F1.
+
+## State, side effects and ownership
+
+| Owner | Evidence and architectural treatment |
+| --- | --- |
+| Shared configuration | `appConfig.js` owns invalidatable settings/tool request promises and consumes a sessionStorage prefetch once. Retain single identity and writer invalidation. |
+| Browser persistence | `storage.js` centralizes keys and safe access; feature files also use direct localStorage. `init.js` cleans storage on user changes. Preferences are not an authorization store. |
+| Feature state | Notes has module variables, selection sets, undo/drafts and reminder state. Email exports a broadly mutable package state object; editor state is imported by 39 modules. Keep ownership explicit; do not expand these into a global store. |
+| Import-time effects | Notes reads storage/window and schedules reminders. Email state reads localStorage. Theme/UI initialize from DOM readiness; modal manager installs global listeners. Chip/mobile helpers bind at startup. Moving an import can change behavior before any exported function is called. |
+| Compatibility globals | App exposes controllers on `window`; Notes exposes `window.notesModule`. They are compatibility bridges, not the new inter-feature API convention. |
+| Async ownership | Session hydration, config invalidation, draft serialized saves and request-generation guards already prevent stale completion. New slices must preserve these rather than only move declarations. |
+
+Good patterns to retain: narrow zero-state leaves, explicit wrapper export lists,
+public API tests, retryable memoized lazy imports, shared config invalidation,
+request-generation checks and source/package-aware regression helpers.
+
+Patterns to avoid: blanket barrels exposing internals, feature imports from
+generic helpers, cycles through coordinators, direct writes to another feature's
+state or DOM, anonymous global listener ownership, import-triggered network/timer
+initialization in new APIs, and helpers grouped by convenience instead of purpose.
+
+## Runtime, assets and distribution
+
+| Contract | Verified source |
+| --- | --- |
+| Static URL and revalidation | `app.py`: `register_static_mime_types`, `_RevalidatingStatic`, `/static` mount. JS MIME is `text/javascript`; JS/CSS/HTML have `Cache-Control: no-cache`. |
+| App paths | `src/constants.py` and `src/runtime_paths.py`: checkout root in native mode, PyInstaller `_MEIPASS` in frozen mode; static assets follow app root, persisted data follows data-directory policy. |
+| CSP | `core/middleware.py`: same-origin scripts, nonce and jsDelivr allowance; `src/app_helpers.py` injects HTML nonces. No CSP relaxation is needed for the proof. |
+| Integrity | No `integrity=` attributes were found in the shell. Proof output is byte-identical and emits no source maps; no existing SRI or vendored artifacts change. |
+| Runtime-generated assets | `/api/generated-image/...` uses a confined data path and owner handling; report/render endpoints, Blob manifests/icons and uploads are runtime concerns outside static source publication. |
+| Docker | `Dockerfile` copies app code and existing static output; `.dockerignore` excludes node_modules. Node/npm in the image support Browser MCP, not frontend startup. |
+| Native installers | `setup.py`, `start-macos.sh`, `launch-windows.ps1`, systemd service: Python dependencies/startup consume the checkout. No frontend build is invoked. |
+| Windows desktop | `Odysseus.spec` and `build-windows-portable.ps1` include the whole static directory. Maintain output here rather than require a new bundle path or compiler. |
+| macOS | `build-macos-app.sh` creates a launcher around the Python checkout. Static serving follows the existing checkout path. Installer execution was not performed on Linux. |
+
+## PWA limitations and test coverage
+
+`static/sw.js` matches exact URLs, including queries. Install fetches each
+precache entry separately and tolerates failed fetches. It does not discover
+transitive dependencies. HTML root and JS/CSS handlers are network-first;
+other static assets are cache-first with background refresh. API and non-GET
+requests bypass caching. Cache updates need explicit version/manifest review.
+The older frontend spec's root stale-while-revalidate description is stale.
+
+Registration in `static/index.html` currently requests no wider scope, so the
+worker controls `/static/`, not `/`. Root offline reload is therefore a known
+pre-existing gap. PR #6227 proposes the scope/header correction. F1 tests actual
+offline ESM loading under the current scope and leaves that separate fix alone.
+Offline APIs, first-use Mermaid and optional CDN runtimes are not certified.
+
+Existing coverage includes runtime graph resolution and version parity; editor
+offline graph coverage and lazy-loader retries; Email API/export/evaluation
+coverage; Notes autosave, XSS, selection/listener and agent-context regressions;
+MIME, nonce and runtime paths. Tests use pytest, Node's built-in runner and existing
+Playwright Chromium. `tests/TESTING_STANDARD.md` requires behavior-first, isolated
+tests. F1 adds real publication failures, architecture violations and an offline
+browser proof. It does not replace existing source-sensitive tests.
+
+## Open PR overlap, checked live on 2026-10-13
+
+The open-PR listing was fetched through all pages; selected PR file lists were
+inspected. Refresh this inventory before any later slice.
+
+| PR | Overlap and disposition |
+| --- | --- |
+| [#6470](https://github.com/odysseus-dev/odysseus/pull/6470) | Theme/sidebar redesign touches HTML, SW, shared UI and CSS. F1 changes none of those assets. Future manifest/UI slices need collision review. |
+| [#6695](https://github.com/odysseus-dev/odysseus/pull/6695) | OXS touches bootstrap, HTML, platform, middleware and other backend boundaries. F1 does not establish an extension API or modify that platform. |
+| [#6227](https://github.com/odysseus-dev/odysseus/pull/6227) | Root SW scope/header fix. Independent follow-up dependency for broader offline certification. |
+| [#6394](https://github.com/odysseus-dev/odysseus/pull/6394) | Older CSS extraction touches legacy style/SW assets; requires separate supersession review. |
+| [#6627](https://github.com/odysseus-dev/odysseus/pull/6627) | npm development-dependency update overlaps package/lock files; reconcile the exact Acorn development entry on integration. |
+| [#6585](https://github.com/odysseus-dev/odysseus/pull/6585), [#6647](https://github.com/odysseus-dev/odysseus/pull/6647), [#6652](https://github.com/odysseus-dev/odysseus/pull/6652) | Notes optional-field persistence and agent routing/dispatch. Future characterization must reflect their merged state; F1 changes no Notes or backend behavior. |
+| [#6594](https://github.com/odysseus-dev/odysseus/pull/6594), [#6152](https://github.com/odysseus-dev/odysseus/pull/6152) | Desktop launcher/build and frozen-runtime packaging work. Existing paths stay stable; packaging still needs platform-owner validation. |
+
+PR titles alone do not establish compatibility. This report records the checked
+file overlap and relevant dependencies, not approval of those implementations.
diff --git a/docs/frontend-architecture/handbook.md b/docs/frontend-architecture/handbook.md
new file mode 100644
index 000000000..103e02ee9
--- /dev/null
+++ b/docs/frontend-architecture/handbook.md
@@ -0,0 +1,223 @@
+# Odysseus frontend architecture handbook
+
+Status: F1 foundation and continuation guide, pending review. The final Notes
+reference case study belongs to the comprehensive Notes draft PR; the recipient
+handoff follows its integration. This document must evolve with reviewed internal
+checkpoints and distinguish executed work from proposals.
+
+Read the [ADR](ADR-001-source-and-deployment.md), [assessment](assessment.md),
+[validation report](validation.md) and [Notes roadmap](notes-roadmap.md).
+The frontend program ends with the Notes reference decomposition and handoff.
+Calendar, Documents, Email, Chat, Skills, Settings and other later decompositions
+belong to the designated frontend maintainer; do not start them automatically.
+
+## Source, ownership and public APIs
+
+`frontend/src/app/` composes public feature APIs and platform ports. Each
+`features/<feature>/index.js` is an intentional API, with explicit named exports
+and a compatibility default only when existing consumers require one. Internals
+live under `domain/`, `application/`, `infrastructure/` or `ui/` as needed. Do not
+create empty directories, boilerplate controllers or a framework by convention.
+Feature names `app` and `shared` are reserved.
+
+Keep pure business rules in domain; transitions and workflows in application;
+HTTP/storage/browser services in infrastructure; DOM rendering and lifecycle in
+UI. The index composes adapters, state and views. Application receives adapters
+as explicit arguments or constructor ports, rather than importing concrete
+infrastructure. Views call application operations; infrastructure does not own
+business decisions. A public API returns data/operations, not mutable stores or
+private DOM nodes. Importing an API should define capabilities; explicit lifecycle
+methods activate them. Legacy side effects remain characterized until a reviewed
+slice safely changes their placement.
+
+Shared code has a named, proven cross-feature responsibility. `shared/domain/`
+holds pure primitives, `shared/platform/` holds narrowly scoped platform adapters,
+and `shared/ui/` holds common DOM capabilities. A named stateless root leaf such
+as `shared/actionMenuOrder.js` is also allowed and receives domain restrictions.
+Do not create a central `utils.js` collection or move feature business rules into
+shared simply to satisfy an import rule.
+
+## Mechanically checked dependency contract
+
+| Importer | Permitted maintained-source targets |
+| --- | --- |
+| App composition | Other app code, shared code, feature `index.js` APIs |
+| Feature index | Its own responsibility modules and shared code; other feature public indexes |
+| Feature domain | Its own domain and shared domain/stateless leaves |
+| Feature application | Its own application/domain, shared domain, other feature public indexes |
+| Feature infrastructure | Its own infrastructure/domain, shared domain/platform |
+| Feature UI | Its own UI/application/domain, shared domain/platform/UI |
+| Shared domain leaf | Shared domain leaves only |
+| Shared platform | Shared platform/domain only |
+| Shared UI | Shared UI/platform/domain only |
+
+No feature imports app composition. No shared code imports a feature. No external
+feature imports private responsibility modules. UI and infrastructure communicate
+with another feature through a supplied application operation/port. Maintained
+source dependency cycles, including literal lazy imports, fail the architecture
+gate. If features need bidirectional coordination, app composition injects a
+callback or adapter instead of creating mutual imports. Prefer this even when a
+one-way public index import would pass the gate.
+
+Cross-feature events must document event name, payload, acknowledgement, owner,
+subscription disposal and delivery timing. Keep them local and specific; F1 adds
+no global event bus. Preserve `odysseus:notes-context-selected` and its synchronous
+`accepted` acknowledgement in future Notes work. The server remains authoritative
+for owner filtering and untrusted selected IDs. Frontend APIs cannot grant access.
+
+The checker parses executable ESM, forbids computed imports in new source,
+requires exact precache entries, rejects unresolved/remapped relative imports,
+and permits only canonical static JS URLs with one unversioned identity for
+maintained modules. Domain code cannot mention known browser/HTTP/timer globals
+or an ambient clock; use `now`/clock inputs. This is a conservative vocabulary
+check, including shadowed names, not a semantic purity proof. Randomness, hidden
+side effects, authorization and lifecycle behavior require behavioral tests.
+
+Legacy imports from new source default to forbidden. If an incremental bridge is
+necessary, declare `legacyImports` on that source's manifest entry as a list of
+`{ "specifier": "/static/js/example.js?v=existing", "reason": "contract, owner and removal slice" }`.
+Only feature composition, infrastructure or UI boundaries may use it. Exact
+specifier/reason and target existence are required; unused exceptions fail.
+Keep the existing query identity. New domain/application modules receive no
+legacy exception. F1 has zero exceptions. Do not use exceptions to invent new
+shared platform dependencies on feature internals.
+
+## State and lifecycle
+
+Each feature has one authoritative mutable application-state owner. A transition
+operation owns writes; UI receives a view/snapshot or subscription. Preserve
+existing objects and initialization timing when extracting a stateful module.
+Do not instantiate a new store in both the legacy facade and the feature API.
+Compatibility facades only forward the same live implementation.
+
+Document lifecycle scopes: page, authenticated user, session, mounted panel and
+editor/draft. Name owners of subscriptions, DOM listeners, timers, observers,
+pending requests and caches. Mounting must be idempotent; disposal releases the
+resources it owns. Background reminders may outlive an open panel. Closing the
+panel must not silently stop those reminders during extraction.
+
+Keep request-generation and selected-session checks around asynchronous
+completions. Serialize writes where the current contract requires it. Dispose
+subscriptions explicitly and prevent late updates to a replaced view. Feature
+state changes on user/session switch must follow current cleanup policy. Browser
+storage is for preferences/drafts/cache state, never a substitute for backend
+authorization, credential storage or owner filtering. Define every storage key's
+owner, retention/reset behavior and compatibility format before moving it.
+
+## Creating a module or introducing a feature
+
+1. Identify responsibility, owner, public consumers, side effects and behavioral
+   evidence before editing. Start with a pure leaf when introducing a feature.
+2. Place only the required source file(s), for example
+   `features/example/domain/calculate.js`. Add an index only when there is a
+   real supported feature API to compose.
+3. Register each source in `frontend/modules.json`. A typical new mapping is
+   `features/example/domain/calculate.js` to
+   `js/features/example/domain/calculate.js`. Preserve the source/deployment
+   relative graph. The proof's legacy URL mapping is an explicit special case.
+4. For an extracted leaf, the legacy feature coordinator may import its output
+   as a temporary composition bridge. New maintained features use public indexes;
+   the legacy tree is not globally forced into the new boundary rules in F1.
+5. Add the exact output URL to the appropriate explicit SW array, retain lazy
+   evaluation timing and bump the cache name when the graph changes. Declare
+   `text eol=lf` for both mapped paths in repository-owned `.gitattributes`
+   files; source-tree or scoped output patterns are allowed. The publisher checks
+   effective Git rules, including nested overrides, and rejects a missing LF rule
+   even if output bytes already match. Do not broaden unrelated legacy checkout
+   rules or automatically rewrite all existing query identities.
+6. Run the publisher, inspect the source/output diff, then run architecture,
+   identity, graph, offline and focused behavior checks. Include both sides of
+   the mapping in review. Retiring output requires a separate reviewed deletion;
+   the publisher does not clean the static tree.
+
+```sh
+python scripts/build_frontend.py
+python scripts/build_frontend.py --check
+npm ci --ignore-scripts --no-audit --no-fund
+node scripts/check_frontend.mjs
+node scripts/check_frontend.mjs --inventory
+node --test tests/frontendArchitecture.test.mjs
+./venv/bin/python -m pytest -q -rs tests/test_frontend_build.py tests/test_frontend_foundation_offline_js.py tests/test_frontend_module_graph.py tests/test_frontend_module_version_parity.py tests/test_panel_loader_js.py
+./venv/bin/python scripts/verify_frontend_runtime.py
+```
+
+Use your actual repository virtualenv path; the F1 environment is recorded in
+validation. Node 20+ follows current CI. Existing Playwright/browser prerequisites
+are documented in `tests/README.md` and `tests/KNOWN_FAILURES.md`. Missing Node can
+skip Python browser wrappers, which is a coverage gap, not a pass. The standalone
+Node gates require locked development dependencies and fail when missing.
+
+The publisher validates all inputs before writing and only overwrites owned
+outputs whose bytes differ. It is idempotent and working-directory independent.
+Git must be available for publication and `--check`; neither runs at application
+startup. Attribute evaluation uses a private temporary Git repository and ignores
+global/local overrides, so checkout consistency is reproducible in CI. It adds
+no runtime configuration or backend imports. CI checks LF attributes, parity and source
+syntax in existing jobs; the Node job also runs architecture self-tests. Existing
+runtime identity tests remain authoritative across legacy imports, HTML and SW.
+The isolated runtime probe is included in the new pytest publication tests.
+
+## Review, release and rollback
+
+Review the source/output mapping and exact exported API, then the owner/dependency
+contract and behavior tests. Check manifests, URL identities, MIME/CSP, load timing,
+storage compatibility and disposal. Reject unexplained feature behavior changes.
+Do not repair unrelated defects under an extraction title.
+
+Release from a validated revision with committed output. Native startup and
+packagers consume static files without a compiler. Run parity before producing a
+Docker or desktop artifact. Test the actual packaged application on its platform;
+Linux contract probes cannot certify macOS/Windows executables. Deploy matching
+shell, facades, graph and manifests as a unit. Keep an authorized path to the last
+complete artifact. Rollback restores the whole matching set, not just an entry
+file or cache version. Do not delete a facade until its public consumers have
+migrated and compatibility tests make that decision reviewable.
+
+## Proposal and PR templates
+
+For a decomposition proposal, record: baseline; responsibility map; current public
+API and consumers; state owner; I/O and lifecycle boundaries; planned slice;
+allowed dependencies/temporary exceptions; preserved behavior; deterministic
+characterization tests; deployment/offline changes; overlapping PRs; rollback;
+explicit non-goals and remaining uncertainties.
+
+For each migration PR, lead with the responsibility moved and resulting boundary.
+Record source/output paths, API compatibility, state/lifecycle ownership,
+characterization results, exact validation commands, platform gaps, exception
+removal plan, upstream dependencies and rollback. Attach a concrete before/after
+example when needed to establish behavioral equivalence. Preserve the repository
+PR template and never claim unexecuted checks.
+
+F1 is an entirely separate foundation-only PR. Deliver the complete Notes
+decomposition, regression tests, compatibility validation and final reference
+case study through one draft PR targeting official `dev`, using one Notes branch
+and worktree after F1 integration. N0 through N6 and the N5 substages are internal
+engineering checkpoints, not independent PRs or merges. Each checkpoint records
+focused tests, review evidence, its validated revision or reproducible snapshot,
+and rollback to the prior matching source/output/facade/precache set. Keep the
+draft open while those checkpoints progress; mark it ready only after the entire
+decomposition passes the [roadmap's acceptance gates](notes-roadmap.md).
+
+Structure the Notes PR description around the final integrated design and link
+each checkpoint's evidence. The receiving maintainer may use smaller independent
+PRs for future frontend features at their discretion; the one-PR Notes decision
+does not impose that delivery size on later work.
+
+## Program backlog and final handoff
+
+Priority order: review/integrate F1; resolve root offline certification with the
+owner of PR #6227; complete the Notes checkpoints and final reference case study
+within one draft PR following the [roadmap](notes-roadmap.md); integrate the
+complete Notes PR after its acceptance gates; finalize the recipient handoff.
+Only then does the receiving maintainer prioritize Calendar, Documents, Email,
+Chat, Skills and Settings against current behavior and risk. Existing partial
+packages and high fan-in helpers need assessment, not automatic replacement.
+
+Final H acceptance requires a designated maintainer, the integrated Notes PR
+revision and its internal checkpoint receipts, the actual public API/state/lifecycle
+map and final reference case study included in that PR, validated deployment/offline
+commands, known exceptions/debt,
+outstanding PR dependencies, rollback evidence and a reproducible independent
+setup by the recipient. F1 provides the handbook structure and contracts; it does
+not claim Notes or the completed handoff have occurred. The initiating architect
+then returns to separately authorized non-frontend architecture work.
diff --git a/docs/frontend-architecture/notes-roadmap.md b/docs/frontend-architecture/notes-roadmap.md
new file mode 100644
index 000000000..6371e9aca
--- /dev/null
+++ b/docs/frontend-architecture/notes-roadmap.md
@@ -0,0 +1,173 @@
+# Notes reference decomposition roadmap
+
+Status: planning only. F1 changes no Notes implementation. Begin after the
+foundation has been reviewed and integrated into official `upstream/dev`.
+The reference program ends after Notes integration and the completed H handoff.
+F1 remains an entirely separate foundation-only PR. The complete Notes
+decomposition, regression tests, compatibility validation and final reference
+case study belong to one comprehensive draft PR targeting official `dev`.
+
+## Verified current responsibility and compatibility map
+
+Baseline: `8feb50e89468235cd3e0986da80edbd3acaf2c40`.
+The module is `static/js/notes.js`, about 5,470 lines, with browser identity
+`/static/js/notes.js?v=20260911notesselectioncancel1`. Preserve that identity across
+the app import, HTML, SW and lazy consumers until a separately reviewed migration
+changes the contract everywhere.
+
+| Responsibility | Current evidence | Intended owner after its reviewed slice |
+| --- | --- | --- |
+| State and CRUD | `_notes`, selection/filter/editing/loading variables, `_undoStack`, `_fetchNotes`, `_saveNote`, `_patchNote`, `_archiveNoteById` | One application state owner and workflow operations; no second reminder/UI copy |
+| Dates and recurrence | `_normalizeRepeat`, `_advanceRecurring`, `_nthWeekdayOfMonth`, `_lastWeekdayOfMonth`, `_toLocalDatetimeStr`, repeat formatting helpers | Pure domain calculations with explicit clock inputs |
+| Network and persistence | Notes CRUD/reorder, upload, reminder firing, draft and reminder localStorage keys | Infrastructure adapters preserving request payloads, credentials and error contracts |
+| Reminders | `_checkReminders`, `_startReminderLoop`, `_initReminders`, notification permission/display and due/fired badge calculations | Application reminder workflow plus injected clock/storage/notification/API ports |
+| Draft autosave | `_draftKey`, `_collectFormDraft`, `_wireDraftAutosave`, `_applyDraftToNote`, `_commitOpenInPlaceEditor` | Draft workflow with editor view/persistence ports and serialized saves |
+| UI | `openPanel`, `closePanel`, `_renderNotes`, forms/cards/checklists, masonry, color/photo/drawing, mobile swipe/reorder | Scoped UI modules with explicit mount/dispose and application operations |
+| Agent context | `#notes-send-agent` handler, selected IDs, `odysseus:notes-context-selected` | Preserve event payload and synchronous acknowledgement; Chat owns attachment/session state |
+| Agent solve action | `_agentSolveNote`: default-chat lookup, session creation and chat stream | Separate existing workflow; do not conflate with selected-note attachment |
+| Compatibility coordinator | Default controller, named aliases, `window.notesModule`, delayed reminder startup | Stable legacy facade/composition bridge until consumers safely migrate |
+
+The default API currently includes `openPanel`, `closePanel`, `togglePanel`,
+`isPanelOpen`, `openNote`, `newNote`, `openNotes`, `closeNotes`, `isNotesOpen` and
+`refreshDueBadge`. Named exports also include `dismissFiredReminderDot` and the
+panel/open aliases. Characterization must pin the complete actual namespace and
+default object separately, including identity of aliases and the window bridge.
+
+Consumers include `static/app.js` sidebar/routes/badge polling,
+`chatStream.js` note tool updates, `chatRenderer.js` note links and
+`document.js` coordination. `static/index.html` and `static/sw.js` are entry/cache
+contracts. The shared UI, confetti, modal, color picker, drag, tiling, docking,
+z-order and Escape helpers are direct dependencies. Those legacy dependencies
+remain in the coordinator until their ownership is reviewed, rather than moving
+all UI coupling into domain modules.
+
+Import-time behavior includes window origin/storage reads and
+`setTimeout(_initReminders, 3000)`. The successful bootstrap loads Notes and starts
+a 30-second reminder interval. App composition separately refreshes the badge
+every five minutes. Panel/editing listeners, draft timers, highlight animations,
+ResizeObserver and drawing/touch handlers have shorter scopes. Record them before
+extraction; do not stop background reminders merely because a panel closes.
+Listener cleanup concerns require characterization, not an unrelated fix hidden
+inside an extraction.
+
+Persistence includes `odysseus-notes-view`, label collapse and hint preferences,
+fired/glowed/pending/active reminder markers, dismissed timestamp, and
+`odysseus-note-draft-<id>` including `__new__`. Current direct APIs include Notes
+CRUD/reorder/fire-reminder and upload, plus default-chat/session/chat-stream for
+the existing solve action. Backend owner isolation and permission handling stay
+authoritative and are outside this frontend decomposition's implementation scope.
+
+## PR #6495 contract that every relevant slice preserves
+
+Notes sends `odysseus:notes-context-selected` with `{ noteIds, accepted: false }`.
+Chat's synchronous listener accepts only a valid active or pending chat, updates
+session/pending selection, sets `accepted`, and updates the context indicator.
+Notes clears select mode only after acceptance. Session lifecycle events
+`odysseus:session-changed` carry session/materialization information. Chat appends
+selected IDs as `selected_note_ids` when sending; server parsing validates IDs,
+filters by owner and treats the resulting prompt context as untrusted.
+
+Keep selection transfer to a materialized chat, reset on a new chat, rejection
+when no chat/model can accept it, aliases and indicator behavior. Do not broaden
+frontend selections into permissions or bypass the backend. See
+`tests/selectedNotesContext.test.mjs`, `tests/test_selected_notes_context.py`,
+`static/js/chat.js` selected-context listeners and send payload, and
+`static/js/sessions.js` lifecycle event producers.
+
+## One Notes branch, worktree and draft PR
+
+After F1 integration and authorization to begin Notes, create one worktree and
+branch, suggested name `refactor/notes-reference-decomposition`, from the latest
+official `upstream/dev`. N0 through N6 are sequential internal engineering
+checkpoints on that same branch. No independent GitHub PR is required for a
+checkpoint or a UI substage. Maintain one draft PR targeting official `dev`, with
+checkpoint evidence linked from its description. Keep it a draft until the
+complete decomposition passes all acceptance gates below.
+
+| Checkpoint | Responsibility | Deliverable and exit evidence |
+| --- | --- | --- |
+| N0 | Characterization | Public API/consumer, responsibility, state, lifecycle and network map; deterministic behavior tests; PR-overlap refresh; no extraction |
+| N1 | Recurrence domain | Only pure date/recurrence rules to `features/notes/domain/recurrence.js`; preserve old wrapper call contracts, time-read position and returned strings; new offline dependency registered |
+| N2 | Infrastructure | HTTP and storage adapters with exact request/error/key contracts; retain state ownership and backend authorization |
+| N3 | Application | Single state owner and CRUD/optimistic/undo workflows; UI/reminders call operations; no competing arrays or stores |
+| N4 | Reminders | Timer/notification/reminder orchestration through explicit ports; characterize startup, catch-up, deduplication, badge and background behavior |
+| N5 | UI substages | Bounded card/panel, editor/draft, checklist, drawing and mobile reviews within the same PR; explicit listener/observer disposal and the same application operations |
+| N6 | Compatibility and reference case study | Reduce coordinator; full API/consumer/lifecycle/offline comparison; retain legacy facade unless removal is proven safe; complete the final reference case study in the same PR |
+
+Do not create the Notes worktree, branch or PR during F1. N5 remains several
+bounded internal reviews rather than a second monolith move. Every checkpoint
+and UI substage must have its own focused tests, review evidence, lessons,
+exceptions and a rollback plan. Record the validated revision or reproducible
+patch/snapshot, prior known-good checkpoint, exact test commands/results and
+how to restore its matching source/output/facade/precache set while preserving
+unrelated work. Checkpoint commits require the applicable maintainer authority;
+no checkpoint or commit is created by this planning document.
+
+Advance only after the current checkpoint's required checks and review findings
+are resolved. A failed checkpoint returns to its prior validated state or receives
+a bounded correction on the same branch; it does not require a separate PR.
+If upstream changes require updating the baseline, update the same Notes branch,
+record that revision and rerun affected checkpoint and compatibility gates.
+
+## Complete Notes PR acceptance gates
+
+Before marking the single draft PR ready for review:
+
+- Complete N0 through N6, including all N5 substages, with their tests, review
+  receipts and reproducible checkpoint/rollback evidence.
+- Pass the required full Notes regression and compatibility checks on the final
+  combined revision, including PR #6495 selection/context behavior, public APIs,
+  module identities, single state ownership, storage formats, timers and teardown.
+- Pass source/output parity, LF attribute, architecture, import graph and exact
+  offline manifest gates; verify current bootstrap/lazy behavior and relevant
+  native/packaging contracts. Record platform limits and distinguish preserved
+  offline module behavior from separately certified root offline reload.
+- Resolve required gate failures and review findings; document unrelated existing
+  failures or coverage gaps explicitly rather than bypassing required checks.
+- Include the final reference case study in this PR: actual before/after APIs,
+  dependency/state/lifecycle maps, stage decisions and lessons, validation recipes,
+  temporary exceptions, known debt and tested rollback/compatibility procedures.
+
+These are readiness gates for the complete PR, not separate stage merges.
+The receiving maintainer may choose smaller independent PRs for future frontend
+features; this one-PR delivery decision applies to the Notes reference program.
+
+## N0 and N1 characterization requirements
+
+Pin recurrence normalization for legacy bare repeat values and explicit values;
+none/unknown/malformed input; daily/weekly/monthly/yearly advancement; month ends,
+leap years, nth/last weekdays including absent fifth occurrences; overdue catch-up
+and the 5,000-step guard; future anchors; local serialization and preserved hours;
+DST gaps/overlaps under explicit time zones. `_advanceRecurring` currently reads
+`Date.now()` after its first step. Inject a clock without changing that ordering.
+Record the existing behavior of invalid dates rather than inventing improvements.
+
+Characterize request error handling, optimistic rollback/undo, archive/delete,
+selection/filter/reset, ordering, uploads and notification permission errors.
+For drafts, preserve synchronous local backup before the 500 ms persistence
+timer, intentional empty text, checklist type fallback, serialized writes,
+failure recovery and refusal to clear a newer draft when an older save finishes.
+
+Use stub clocks/ports and temporary storage for unit behavior; browser tests for
+public namespace evaluation, DOM lifecycle, selected context and actual offline
+loading. Run real modules through their output paths. Do not rewrite source-range
+tests wholesale; migrate each only with its responsible slice and equivalent
+behavioral assertions. Existing source-sensitive Notes autosave tests currently
+read `notes.js`, so extraction has an explicit test-maintenance dependency.
+
+Before a slice, refresh #6585/#6647/#6652 backend behavior and #6470/#6695 shared
+UI/platform overlaps from the [assessment](assessment.md). Existing fixes may
+change characterization inputs, but this program does not merge or silently
+reimplement those PRs. The independent root-SW fix #6227 is required before a
+claim of full SPA offline reload readiness.
+
+## H completion and stopping rule
+
+The final reference case study is completed inside the Notes PR before it becomes
+ready for review. After that PR is integrated, finalize H with the integrated
+revision and checkpoint-to-integration receipts, outstanding dependencies and
+the recipient's independent reproduction. Have the receiving maintainer
+reproduce setup and validation independently and record that receipt. Transfer
+future feature ownership explicitly. Do not automatically begin Calendar,
+Documents, Email, Chat, Skills or Settings; the initiating architect continues
+with separately approved non-frontend monolith work.
diff --git a/docs/frontend-architecture/validation.md b/docs/frontend-architecture/validation.md
new file mode 100644
index 000000000..1e85db081
--- /dev/null
+++ b/docs/frontend-architecture/validation.md
@@ -0,0 +1,453 @@
+# F1 implementation and review report
+
+Date: 2026-10-13. Recommendation: ready for controlled incremental adoption after
+maintainer review, with the platform/offline limits below. The foundation proof
+is implemented and tested; Notes decomposition and the completed H handoff are
+planned only. No commit, push, merge, PR or issue operation was performed.
+
+## Notes delivery documentation correction
+
+The maintainer's final delivery decision is one comprehensive Notes draft PR
+targeting official `dev`, after the separate foundation-only F1 PR is integrated.
+N0 through N6 are internal engineering checkpoints in one Notes worktree and
+branch. The complete decomposition, regression tests, compatibility validation
+and final reference case study belong to that single PR; it stays a draft until
+the complete acceptance gates pass. Each stage retains its own test results,
+review receipts and reproducible rollback/checkpoint strategy, without requiring
+an independent GitHub PR. The receiving maintainer may choose smaller independent
+PRs for future frontend features.
+
+This correction updates only `notes-roadmap.md`, `handbook.md` and this report.
+Implementation and test files retain their pre-correction bytes. All five
+foundation documents passed link, fence, whitespace, no-em-dash and delivery
+wording checks. `git diff --check` and the preserved-runtime diff check passed.
+A before/after snapshot confirmed exactly these three changed documents and
+15 unchanged existing F1 files. The implementation test results below remain
+the previous executed evidence; implementation tests were not rerun in this
+documentation-only pass.
+
+## Independent review correction
+
+The maintainer reports that the independent F1 review found no critical
+architectural defects. This pass preserves the reviewed native ESM architecture
+and scope. Its correction is to turn the documented LF checkout convention into
+a manifest-driven publisher/CI requirement. The full independent review text
+was not supplied; this report records the supplied finding and executed evidence.
+
+The correction changes only `scripts/build_frontend.py`,
+`tests/test_frontend_build.py`, the ADR, the handbook and this report. The
+`.gitattributes` rules, architecture checker, CI workflow, manifest, dependencies
+and stateless source remain as reviewed. The full F1 inventory below still has
+18 files, including `.gitattributes`.
+
+The publisher now evaluates both paths of every manifest entry through Git's
+actual attribute engine before parity evaluation or any deployment write. It
+requires `text: set` and `eol: lf` from applicable repository-owned attribute files,
+including nested overrides. A private temporary repository and isolated Git
+configuration prevent global attributes, local `.git/info/attributes`, templates
+or alternate Git directory settings from masking an omitted declaration. Paths
+are sent through NUL-delimited stdin, preserving spaces and using no shell/path
+quoting assumptions. The working repository's attributes, index and output are
+not changed by this check. Git is a publication/development prerequisite; the
+application does not invoke it to build or check frontend assets at startup.
+
+The production integration diff is the new `check_lf_attributes(root, paths)`
+helper, four standard-library imports, this call, and updated CLI help:
+
+```diff
+@@ synchronize
+     if unlisted:
+         raise ValueError(f"source modules missing from manifest: {sorted(map(str, unlisted))}")
++    check_lf_attributes(root, sources | outputs)
+     stale = []
+```
+
+The tests add fixture LF declarations and 14 cases. Ten parameterized cases
+reject missing LF, CRLF, auto-text and binary-text rules for source/output paths
+in both publish and check modes, even when bytes already match. The other four
+cover a future manifest pair failing before any output is published and passing
+after its LF declaration; nested rules and a spaced path; global/local settings
+failing to mask an omitted repository rule; and clear failure without development
+Git. Existing publication, ownership, confinement, parity and runtime tests remain.
+
+## Exact attributes diff and checkout evidence
+
+`git diff -- .gitattributes` is unchanged from the reviewed F1 diff:
+
+```diff
+diff --git a/.gitattributes b/.gitattributes
+index 8681aee1..dd49c4a0 100644
+--- a/.gitattributes
++++ b/.gitattributes
+@@ -10,6 +10,10 @@
+ entrypoint.sh text eol=lf
+ docker/entrypoint.sh text eol=lf
+
++# Maintained frontend modules and this lane's byte-identical deployment output.
++frontend/src/** text eol=lf
++static/js/actionMenuOrder.js text eol=lf
++
+ # Windows-native scripts stay CRLF.
+ *.ps1 text eol=crlf
+ *.cmd text eol=crlf
+```
+
+Exact command and results:
+
+```text
+$ git check-attr text eol -- frontend/src/shared/actionMenuOrder.js static/js/actionMenuOrder.js
+frontend/src/shared/actionMenuOrder.js: text: set
+frontend/src/shared/actionMenuOrder.js: eol: lf
+static/js/actionMenuOrder.js: text: set
+static/js/actionMenuOrder.js: eol: lf
+```
+
+The sampled legacy contracts were also inspected:
+
+| Path | text | eol |
+| --- | --- | --- |
+| `static/js/notes.js` | auto | unspecified |
+| `static/index.html` | auto | unspecified |
+| `launch-windows.ps1` | set | crlf |
+| `start-macos.sh` | set | lf |
+
+Beyond samples, all 2,479 unrelated tracked paths were compared against HEAD for
+both attributes and matched. The current Git 2.53.0 supports the diagnostic
+`--source=HEAD` option; the publisher uses only the longstanding plain
+`check-attr --stdin` interface, so it does not depend on that newer option.
+The read-only whole-tree comparison command was:
+
+```sh
+python3 - <<'PY'
+import subprocess
+paths = subprocess.check_output(['git', 'ls-files', '-z'])
+def attributes(source):
+    result = subprocess.run(
+        ['git', 'check-attr', *source, '-z', '--stdin', 'text', 'eol'],
+        input=paths, capture_output=True, check=True,
+    )
+    fields = result.stdout.decode().split('\0')[:-1]
+    return {(fields[i], fields[i + 1]): fields[i + 2]
+            for i in range(0, len(fields), 3)}
+before, after = attributes(['--source=HEAD']), attributes([])
+owned = lambda p: p.startswith('frontend/src/') or p == 'static/js/actionMenuOrder.js'
+changes = [(p, a, before[(p, a)], value) for (p, a), value in after.items()
+           if not owned(p) and before[(p, a)] != value]
+assert not changes, changes
+print(len({p for p, a in after if not owned(p)}), 'unrelated tracked paths unchanged')
+PY
+```
+
+## Ownership enforcement after correction
+
+| Contract | Enforcement and CI receipt |
+| --- | --- |
+| Canonical, contained source/output paths and unique ownership | Publisher validates the whole manifest before writing; `python-syntax` runs its `--check` |
+| Every maintained JS source is registered | Publisher rejects unlisted source; duplicate sources/outputs also fail |
+| Reproducible LF checkout of both mapped paths | Publisher queries isolated repository-owned attributes, even for already matching bytes; the same CI `--check` now enforces it |
+| Committed output equals maintained source | Publisher checks byte parity without rebuilding in CI; normal publication writes only stale owned outputs |
+| Feature API/layer direction, no new cycles, stable relative resolution and maintained identities | Existing architecture checker and Node self-tests in `node-syntax`; no checker changes needed |
+| Explicit exact-URL offline coverage | Architecture checker parses the existing SW arrays; real offline browser proof remains green |
+| Legacy runtime graph/URL identity and behavior | Existing focused pytest guards and the full CI pytest jobs remain in place |
+
+These gates enforce the documented maintained-JS contract together. They do not
+retroactively impose source ownership on all legacy static files, clean retired
+outputs or prove semantic state/lifecycle correctness. Those existing limits and
+the independent packaging/offline limitations below remain unchanged.
+
+## Final correction validation
+
+The full focused pytest command printed below was rerun with the same interpreter
+and all listed files: **193 passed, 1 skipped, 1 existing SQLAlchemy warning in
+12.33 s**. It includes all 27 publisher tests and the isolated native startup,
+static traversal and no-Node distribution probe. The new 14 tests account for
+the increase from the initial F1 run's 179 passes. No test failed in this pass.
+
+| Correction check | Actual result |
+| --- | --- |
+| Combined focused pytest command below | 193 passed, 1 unavailable-image skip |
+| `node --test tests/frontendArchitecture.test.mjs` | 10 passed |
+| Notes oracle/autosave/selected-context command below | 11 passed |
+| `python3 scripts/build_frontend.py` | Passed, zero output changes, attributes enforced |
+| `python3 scripts/build_frontend.py --check` | Passed, attributes and byte parity enforced |
+| `node scripts/check_frontend.mjs` | Passed, one maintained module |
+| Helper SHA-256 and `git check-attr` | Identical source/output hash; both text=set, eol=lf |
+| All unrelated tracked attributes versus HEAD | 2,479 paths unchanged |
+| `git diff --check` and preserved-runtime command below | Passed, no runtime/backend/packaging diff |
+| `python -m compileall -q scripts/build_frontend.py tests/test_frontend_build.py` | Passed using the recorded virtualenv interpreter |
+| Isolated Docker runtime command below | Passed, networking disabled; no source tree, node_modules or Node on PATH |
+| Complete inventory, whitespace and documentation links | All 18 changed files matched the inventory; checks passed |
+
+The one skip remains the existing test requiring `odysseus-odysseus:latest`.
+No new skip or waiver was introduced. Windows/macOS executable builds, a fresh
+full Dockerfile build, the full pytest suite, Firefox/WebKit and CI's exact
+Python 3.11/Node 20 versions remain unexecuted locally. Native Git semantics,
+nested overrides, paths with spaces and ignored `core.autocrlf`/global attribute
+settings are covered by executed Linux tests; actual Windows execution remains a
+platform-owner check. The existing `/static/` worker scope still prevents a claim
+of full root offline reload readiness. No service-worker scope change is included.
+
+The earlier local ChromaDB probe incident remains recorded under failures below.
+All runtime checks in this correction pass used the isolated distribution probe
+with reserved non-listening Chroma port and disabled warmups; Docker additionally
+had networking disabled. This pass performed no new unisolated ChromaDB probe and
+no attempt to restore or alter the existing local service's tool index.
+
+## Reviewer-ready PR summary
+
+Suggested title: `Establish frontend source ownership and native ESM deployment contracts`.
+
+Maintain a stateless helper under `frontend/src/` while publishing identical bytes
+at its existing static URL. Add manifest-owned publication, repository-owned LF
+attribute and byte-parity checks, parsed dependency/API/identity/offline gates,
+and a self-contained architecture handbook with the Notes decomposition roadmap.
+Startup and existing feature behavior retain their current runtime contracts.
+
+Validation: 193 focused Python tests passed with one existing Docker-image skip;
+10 architecture and 11 Notes compatibility tests passed; source/output parity,
+LF gates, preserved-runtime diff and isolated native/Docker runtime proofs passed.
+Desktop executable builds and full root offline reload remain explicit limits.
+All 18 files are inventoried below. The working diff is ready for review and is
+uncommitted; commit, push and PR creation require separate authorization.
+
+## Verified repository state
+
+Repository: `odysseus-dev/odysseus`. Branch:
+`refactor/frontend-architecture-foundation`. Worktree:
+`/home/alteixeira20/Projects/Odysseus/worktrees/architecture/frontend-foundation`.
+Initial worktree was clean. HEAD and local official `upstream/dev` are
+`8feb50e89468235cd3e0986da80edbd3acaf2c40`. The live official GitHub `dev` SHA
+matched at both initial and final verification. This is PR #6495's merge commit.
+The `origin` remote is the maintainer fork, not the integration target.
+
+Final changes are uncommitted F1 files only. Runtime JavaScript, Notes, HTML,
+SW, backend, Dockerfile and desktop startup/packaging implementations have no
+diff. The stateless source and existing deployed helper are both 1,688 bytes,
+SHA-256 `e17baec5d6ac381ce6234ab6f028a8208487280dd07d6950a3469f8488809684`.
+The final publisher run reported zero changed output modules.
+
+## Decisions and scope
+
+The [ADR](ADR-001-source-and-deployment.md) compares two executed approaches:
+controlled native ESM copying and esbuild 0.25.12 ESM compilation/bundling.
+Native byte copying wins on existing URL/module/cache compatibility and absence
+of runtime tooling. Commit explicit output beside maintained source, publish
+only manifest-owned modules and enforce parity in CI. Python startup never builds.
+
+The [handbook](handbook.md) defines feature public indexes, responsibility layers,
+state/lifecycle ownership, cross-feature ports/events, shared-code limits, legacy
+coexistence, module creation, validation, rollback and handoff contracts.
+The [assessment](assessment.md) records graph/bootstrap/state/storage/security,
+packaging assumptions and current open-PR overlaps. The
+[Notes roadmap](notes-roadmap.md) defines N0 through N6 as internal checkpoints
+for one comprehensive Notes draft PR, with the final reference case study in
+that PR and H recipient handoff after integration. None is implemented in F1.
+There is one maintained stateless leaf and zero legacy-import
+exceptions, with no empty feature scaffolding.
+
+Acorn 8.19.0 is the sole new, exact-pinned development dependency, used to parse
+architecture edges accurately. It is not loaded or distributed as runtime JS.
+esbuild was a pinned one-off spike and is not a project dependency. Existing
+frameworks, application entry points and backend contracts are unchanged.
+
+## Exact changed files
+
+| File | Change |
+| --- | --- |
+| `.gitattributes` | LF checkout for maintained source and the registered deployed proof |
+| `.github/workflows/ci.yml` | Parity check; locked parser install; source syntax and architecture self-tests |
+| `package.json` | Exact Acorn development dependency |
+| `package-lock.json` | Acorn lock/integrity entry |
+| `frontend/modules.json` | Explicit source/deployment ownership mapping |
+| `frontend/src/package.json` | Native ESM interpretation for source tests, no dependencies |
+| `frontend/src/shared/actionMenuOrder.js` | Authoritative stateless source, copied verbatim from the existing helper |
+| `scripts/build_frontend.py` | Validated source publisher with manifest-driven, repository-owned LF enforcement and non-mutating parity check |
+| `scripts/check_frontend.mjs` | Parsed import/layer/API/cycle/identity/precache guards and graph inventory |
+| `scripts/verify_frontend_runtime.py` | Isolated current-code distribution/runtime compatibility probe |
+| `tests/frontendArchitecture.test.mjs` | Behavioral API equivalence and positive/negative architecture gates |
+| `tests/test_frontend_build.py` | Publication/ownership/drift/runtime coverage plus positive and negative Git attribute enforcement tests |
+| `tests/test_frontend_foundation_offline_js.py` | Real SW precache, offline first evaluation, canonical namespace identity and lazy registry proof |
+| `docs/frontend-architecture/ADR-001-source-and-deployment.md` | Decision, alternatives and distribution/rollback contracts |
+| `docs/frontend-architecture/assessment.md` | Evidence-backed architecture and PR-overlap inventory |
+| `docs/frontend-architecture/handbook.md` | Permanent foundation and maintainer continuation methodology |
+| `docs/frontend-architecture/notes-roadmap.md` | Reference decomposition and final handoff plan |
+| `docs/frontend-architecture/validation.md` | This implementation/review/validation report |
+
+## Initial F1 validation before the review correction
+
+Environment: Linux; native Python 3.14.4; pytest 9.1.1; FastAPI 0.143.0;
+Starlette 1.8.0; Node 22.23.1; Playwright 1.62.1 with installed Chromium.
+CI remains Python 3.11 and Node 20; that exact interpreter pair was not executed
+locally. Use the repository virtualenv, not the system Python missing dependencies.
+The interpreter used here was
+`/home/alteixeira20/.venvs/odysseus-pr-6495/bin/python`.
+
+The historical counts below are coordinator-executed checks in this worktree, excluding
+delegated claims and earlier repeated subsets. Delegation was discontinued on
+user instruction; no delegated implementation was integrated.
+
+| Check | Actual result |
+| --- | --- |
+| Read-only baseline: graph, identity, helper, loader, MIME, nonce, runtime paths | 54 passed, one existing SQLAlchemy deprecation warning |
+| Final combined focused pytest command below | 179 passed, 1 skipped, one existing SQLAlchemy warning, 12.62 s |
+| Final `pytest -q -rs tests/test_frontend_build.py` review rerun | 13 passed, including native startup and encoded static traversal rejection |
+| `node --test tests/frontendArchitecture.test.mjs` | 10 passed, no skips or failures; rerun after final gate review |
+| Notes oracle/autosave/selected-context Node command below | 11 passed, no skips or failures |
+| `python3 scripts/build_frontend.py` and `--check` | Zero output changes; byte parity passed |
+| `node scripts/check_frontend.mjs` | Passed, one maintained module |
+| `node scripts/check_frontend.mjs --inventory` | 230 files, 707 static edges, 108 lazy literal edges, no missing targets, three existing static cyclic components |
+| `npm ci --ignore-scripts --no-audit --no-fund` | Locked development dependency installation succeeded |
+| Native `scripts/verify_frontend_runtime.py` | Real FastAPI lifespan and shell/static assertions passed without maintained source, node_modules or Node on PATH |
+| Docker runtime probe below | Same current-code assertions passed with networking disabled and source mount read-only |
+| esbuild spike | Two identical 1,554-byte bundle outputs; executed exports/icon/ordering equivalence passed |
+| JS syntax checks and Python compileall below | Passed |
+| `git diff --check`, preserved-scope diff check, hash/LF checks | Passed; no runtime/backend/packaging source diff |
+| Foundation documentation links, trailing whitespace and em-dash checks | All five files passed |
+
+The skipped test is
+`tests/test_docker_devops_hardening.py:187`, which requires the unavailable
+`odysseus-odysseus:latest` image. It was not relabeled or bypassed. F1's separate
+Docker runtime probe used the available `odysseus-maintainer-preview-odysseus:latest`,
+image ID `sha256:cc2d47e2327d573af01c6b027f23d2ab0f2ee9b85d658e9eb8065bd02b9c3515`,
+with Python 3.14.7, FastAPI 0.141.1 and Starlette 1.6.0. This proves compatibility
+of current candidate code/assets with that image's runtime dependencies, not a
+fresh build of the full repository Dockerfile or a deployment.
+
+Reproduce the final focused command with the actual tested interpreter:
+
+```sh
+/home/alteixeira20/.venvs/odysseus-pr-6495/bin/python -m pytest -q -rs \
+  tests/test_frontend_build.py tests/test_frontend_foundation_offline_js.py \
+  tests/test_frontend_module_graph.py tests/test_frontend_module_version_parity.py \
+  tests/test_action_menu_order.py tests/test_panel_loader_js.py \
+  tests/test_app_static_mime.py tests/test_serve_html_with_nonce.py \
+  tests/test_runtime_paths.py tests/test_ci_authoritative_validation.py \
+  tests/test_selected_notes_context.py tests/test_email_library_module_graph_js.py \
+  tests/test_settings_module_import_paths.py tests/test_app_config_shared_fetch_js.py \
+  tests/test_markdown_lazy_lib_loading_js.py tests/test_startup_shell_js.py \
+  tests/test_static_stylesheet_manifest.py tests/test_notes_dom_xss_helpers.py \
+  tests/test_notes_reminder_temporal_redos.py tests/test_notes_sidebar_new_note.py \
+  tests/test_notes_mobile_checklist_toggle_static.py \
+  tests/test_notes_document_mutual_minimize.py tests/test_docker_devops_hardening.py
+
+node --test tests/frontendArchitecture.test.mjs
+ENDPOINT_URL=http://127.0.0.1:1 node --test \
+  tests/noteTestOracle.test.mjs tests/notesDraftAutosave.test.mjs \
+  tests/selectedNotesContext.test.mjs
+
+python3 scripts/build_frontend.py --check
+node scripts/check_frontend.mjs
+/home/alteixeira20/.venvs/odysseus-pr-6495/bin/python scripts/verify_frontend_runtime.py
+
+docker run --rm --network none \
+  --mount type=bind,src=/home/alteixeira20/Projects/Odysseus/worktrees/architecture/frontend-foundation,dst=/candidate,readonly \
+  --workdir /candidate --entrypoint python \
+  odysseus-maintainer-preview-odysseus:latest scripts/verify_frontend_runtime.py
+```
+
+`ENDPOINT_URL` satisfies the existing oracle's import-time configuration requirement.
+Its unit-test imports exercise pure exported functions; its network-driving main
+is guarded by the executable-module check and does not run. The closed loopback
+address is not a live model endpoint. No oracle implementation was changed.
+
+Syntax commands executed:
+
+```sh
+bash -c 'shopt -s globstar nullglob; for f in static/app.js static/js/**/*.js frontend/src/**/*.js scripts/check_frontend.mjs tests/frontendArchitecture.test.mjs; do node --check "$f" || exit; done'
+/home/alteixeira20/.venvs/odysseus-pr-6495/bin/python -m compileall -q app.py core routes src services scripts tests
+git diff --check
+git diff --exit-code -- static app.py Dockerfile .dockerignore Odysseus.spec build-macos-app.sh build-windows-portable.ps1 launcher.py core routes src services
+git check-attr text eol -- frontend/src/shared/actionMenuOrder.js static/js/actionMenuOrder.js
+sha256sum frontend/src/shared/actionMenuOrder.js static/js/actionMenuOrder.js
+```
+
+Spike compiler invocation, executed twice with equality and Node import assertions:
+
+```sh
+npx --yes esbuild@0.25.12 frontend/src/shared/actionMenuOrder.js \
+  --bundle --format=esm --target=es2022 --platform=browser --log-level=error
+```
+
+The clean publication proof uses temporary roots in `test_frontend_build.py`,
+including an initially absent output tree. Real-checkout publication is idempotent.
+No emitted JS bytes, URLs, boot scripts or cache manifests changed in this lane.
+
+## Failures encountered and their resolution
+
+- An early architecture self-test expected an identity diagnostic but got an
+  unresolved source path for a query-bearing relative import. The checker now
+  rejects alternate identity before resolving that source path. All final tests
+  pass; no test requirement was weakened.
+- The initial Notes oracle command failed during import because `ENDPOINT_URL`
+  was missing. Inspection established that the unit-test path never runs its
+  endpoint-driving main. The explicit closed-address configuration above passed
+  all 11 tests. This prerequisite is recorded for N0 rather than hidden.
+- The first isolated distribution fixture omitted the existing `companion/`
+  package, so both probes failed with `ModuleNotFoundError`. The fixture now
+  includes that required runtime directory; neither application nor packaging
+  implementation was modified to make the tests pass.
+- The first exploratory native startup check connected to the existing local
+  ChromaDB and refreshed the built-in tool index. That was unintended. Subsequent
+  probes use a private distribution/data directory, a reserved non-listening
+  Chroma port, disabled existing warmup options and no Node on PATH. Docker also
+  disables networking. No attempt was made to overwrite or restore that service's
+  data; the earlier unisolated probe is not the reproducible validation recipe.
+
+## Remaining risks and limits
+
+Root offline reload is not certified: existing SW scope is `/static/`, and open
+[#6227](https://github.com/odysseus-dev/odysseus/pull/6227) proposes the independent
+scope/header correction. F1 preserves and tests actual offline module behavior
+at the current scope. No first-use offline guarantee is claimed for optional
+CDN libraries, Mermaid or server APIs.
+
+Windows/macOS packaged executables, a fresh full Dockerfile build, the full pytest
+suite, Firefox/WebKit offline behavior and CI's exact Python 3.11/Node 20 versions
+were not executed here. Existing packaging paths are inspected and unchanged;
+platform owners should run release validation before broader certification.
+The unavailable-image test remains a coverage gap. Legacy source still has
+cross-feature coupling, global side effects and static cycles. New boundaries
+are enforced on maintained source, not retrospectively on the entire legacy tree.
+
+The publisher intentionally does not clean retired outputs or provide atomic
+multi-file deployment. Review full source/output/facade/manifest changes and
+ship a coherent artifact. Domain syntax checks cannot prove all semantic purity
+or disposal; behavioral characterization remains required. Reconcile the package
+lock with #6627 and refresh all PR overlaps before integration.
+
+## Reviewer checklist
+
+- Verify the base contains #6495 and the official integration target is dev.
+- Confirm the deployed helper hash and runtime-scope diff are unchanged.
+- Review the layer matrix, public API rules, single-state ownership and zero
+  current legacy exceptions; verify negative tests actually reject violations.
+- Review the manifest mapping, byte-parity/LF policy, exact offline precache and
+  source/output relative-resolution guard; verify missing or overridden LF
+  declarations fail publication and CI even when output bytes already match.
+- Reproduce the focused tests and inspect the skipped-image prerequisite.
+- Confirm no frontend compiler/runtime dependency is required at startup and
+  inspect the isolated Python/Docker probe's limits.
+- Review overlap with #6470/#6695/#6227/#6627 and the Notes backend follow-ups.
+- Treat the ADR as awaiting adoption review, and the Notes/H documents as plans.
+- Authorize any commit/push/PR action separately. Do not begin Notes on this branch.
+
+## Required next reviews and continuation
+
+1. Review this F1 working diff. On explicit authorization, commit and submit only
+   the foundation-only F1 PR to official dev using the normal maintainer workflow.
+2. Coordinate the existing #6227 offline fix and platform release validation as
+   separate work. Do not bundle that behavioral change into F1.
+3. After F1 integration and Notes implementation authorization, create one Notes
+   worktree and branch from the latest official dev, preserving any subsequently
+   merged Notes changes. Use one comprehensive draft PR targeting official dev.
+4. Complete N0 through N6 from the [Notes roadmap](notes-roadmap.md) on that same
+   branch, recording tests, review and rollback evidence at each checkpoint. Include
+   the final reference case study in the same PR and keep it a draft until the full
+   decomposition and regression/compatibility acceptance gates pass. Recurrence
+   extraction follows characterization as an internal stage, not another PR.
+5. Complete H only after Notes integration and recipient reproduction. Transfer
+   future frontend work to the designated maintainer and stop this program.
+
+Another maintainer can start at the handbook, run the documented source/parity,
+architecture, runtime and behavior checks, inspect this report and select the
+next authorized slice without relying on unwritten architecture decisions.
diff --git a/frontend/modules.json b/frontend/modules.json
new file mode 100644
index 000000000..0363222b1
--- /dev/null
+++ b/frontend/modules.json
@@ -0,0 +1,9 @@
+{
+  "version": 1,
+  "modules": [
+    {
+      "source": "shared/actionMenuOrder.js",
+      "deployment": "js/actionMenuOrder.js"
+    }
+  ]
+}
diff --git a/frontend/src/package.json b/frontend/src/package.json
new file mode 100644
index 000000000..e986b24bb
--- /dev/null
+++ b/frontend/src/package.json
@@ -0,0 +1,4 @@
+{
+  "private": true,
+  "type": "module"
+}
diff --git a/frontend/src/shared/actionMenuOrder.js b/frontend/src/shared/actionMenuOrder.js
new file mode 100644
index 000000000..f5cd80b9d
--- /dev/null
+++ b/frontend/src/shared/actionMenuOrder.js
@@ -0,0 +1,29 @@
+/** Stable semantic ordering for item-level action menus. */
+const COMMON_ACTION_ORDER = [
+  { rank: 200, pattern: /^(rename|change name)\b/i },
+  { rank: 650, pattern: /^select\b/i },
+  { rank: 400, pattern: /^(favorite|unfavorite|favourite|unfavourite|pin|unpin)\b/i },
+  { rank: 500, pattern: /^(copy|clone|duplicate)\b/i },
+  { rank: 550, pattern: /^(export|download)\b/i },
+  { rank: 900, pattern: /^(delete|remove|hide|dismiss|clear from list|move to trash|move to spam)\b/i },
+  { rank: 700, pattern: /^(move to archive|archive|unarchive|restore)\b/i },
+  { rank: 600, pattern: /^(move(?! to (?:archive|trash|spam)\b)|add to folder)\b/i },
+  { rank: 1000, pattern: /^cancel\b/i },
+];
+
+// Canonical Select glyph for item-level menus. Toolbar toggles may use the
+// smaller version, but dropdown rows should all use this exact SVG.
+export const SELECT_MENU_ICON = '<svg class="memory-select-btn-icon" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><circle cx="12" cy="12" r="10"/><circle cx="12" cy="12" r="3" fill="currentColor" stroke="none"/></svg>';
+
+export function actionMenuRank(item) {
+  if (Number.isFinite(item?.menuOrder)) return item.menuOrder;
+  const value = String(typeof item?.action === 'string' ? item.action : (item?.label || '')).trim();
+  return COMMON_ACTION_ORDER.find(entry => entry.pattern.test(value))?.rank ?? 100;
+}
+
+export function orderActionMenuItems(items) {
+  return items
+    .map((item, index) => ({ item, index, rank: actionMenuRank(item) }))
+    .sort((a, b) => a.rank - b.rank || a.index - b.index)
+    .map(entry => entry.item);
+}
diff --git a/package-lock.json b/package-lock.json
index 4d0b4b8d6..97fb6b572 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -7,7 +7,8 @@
       "name": "odysseus",
       "devDependencies": {
         "@antithesishq/bombadil": "^0.7.0",
-        "@playwright/test": "^1.62.1"
+        "@playwright/test": "^1.62.1",
+        "acorn": "8.19.0"
       }
     },
     "node_modules/@antithesishq/bombadil": {
@@ -36,6 +37,19 @@
         "node": ">=20"
       }
     },
+    "node_modules/acorn": {
+      "version": "8.19.0",
+      "resolved": "https://registry.npmjs.org/acorn/-/acorn-8.19.0.tgz",
+      "integrity": "sha512-oJlA3XiRm7Cyk6qFD2Jn8ak9B7jSy0qy00ADO3+8dpT0LSjFihQYv4C02LFCSYJV3Q37xYwwRy5m+IpIiUzqWw==",
+      "dev": true,
+      "license": "MIT",
+      "bin": {
+        "acorn": "bin/acorn"
+      },
+      "engines": {
+        "node": ">=0.4.0"
+      }
+    },
     "node_modules/fsevents": {
       "version": "2.3.2",
       "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.2.tgz",
diff --git a/package.json b/package.json
index 6f72684c8..aa454e017 100644
--- a/package.json
+++ b/package.json
@@ -13,6 +13,7 @@
   },
   "devDependencies": {
     "@antithesishq/bombadil": "^0.7.0",
-    "@playwright/test": "^1.62.1"
+    "@playwright/test": "^1.62.1",
+    "acorn": "8.19.0"
   }
 }
diff --git a/scripts/build_frontend.py b/scripts/build_frontend.py
new file mode 100644
index 000000000..371715783
--- /dev/null
+++ b/scripts/build_frontend.py
@@ -0,0 +1,148 @@
+#!/usr/bin/env python3
+"""Publish explicitly owned native ES modules; never run at application startup."""
+
+import argparse
+import json
+import os
+from pathlib import Path, PurePosixPath
+import shutil
+import subprocess
+import tempfile
+
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+def module_path(base: Path, relative: str) -> Path:
+    """Accept canonical JS paths only, contained within the declared tree."""
+    if not isinstance(relative, str):
+        raise ValueError("module paths must be strings")
+    parts = PurePosixPath(relative)
+    if (
+        parts.is_absolute()
+        or parts.as_posix() != relative
+        or ".." in parts.parts
+        or "\\" in relative
+        or "?" in relative
+        or "#" in relative
+        or parts.suffix != ".js"
+    ):
+        raise ValueError(f"invalid module path: {relative!r}")
+    path = base / relative
+    if not path.resolve().is_relative_to(base.resolve()):
+        raise ValueError(f"module path escapes its tree: {relative!r}")
+    if any(p.is_symlink() for p in (path, *path.parents)):
+        raise ValueError(f"symlink in module path: {relative!r}")
+    return path
+
+
+def check_lf_attributes(root: Path, paths: set[Path]) -> None:
+    """Require portable, repository-owned LF attributes for every mapped path.
+
+    Ask Git in an isolated temporary repository so global attributes, local
+    info/attributes and alternate Git directories cannot mask missing rules.
+    Copy only attribute files at ancestors of the manifest's source/output paths.
+    """
+    git = shutil.which("git")
+    if git is None:
+        raise ValueError("Git is required for frontend publication attribute checks")
+    attributes = {root / ".gitattributes"}
+    for path in paths:
+        for parent in path.parents:
+            if parent == root:
+                break
+            attributes.add(parent / ".gitattributes")
+    env = {key: value for key, value in os.environ.items() if not key.startswith("GIT_")}
+    env.update(GIT_CONFIG_NOSYSTEM="1", GIT_CONFIG_GLOBAL=os.devnull)
+    relative = sorted(path.relative_to(root).as_posix() for path in paths)
+    with tempfile.TemporaryDirectory(prefix="ody-frontend-attributes-") as directory:
+        target = Path(directory)
+        for attribute in attributes:
+            if attribute.is_symlink():
+                raise ValueError(f"symlink attribute file: {attribute.relative_to(root)}")
+            if attribute.is_file():
+                copy = target / attribute.relative_to(root)
+                copy.parent.mkdir(parents=True, exist_ok=True)
+                copy.write_bytes(attribute.read_bytes())
+        command = [git, "-c", f"core.attributesFile={os.devnull}", "-C", str(target)]
+        try:
+            subprocess.run(command + ["init", "--quiet", "--template="], env=env, check=True, capture_output=True, timeout=15)
+            result = subprocess.run(
+                command + ["check-attr", "-z", "--stdin", "text", "eol"],
+                input=("\0".join(relative) + "\0").encode("utf-8"),
+                env=env, check=True, capture_output=True, timeout=15,
+            )
+        except (subprocess.CalledProcessError, subprocess.TimeoutExpired) as error:
+            raise ValueError("Git frontend attribute check failed") from error
+    fields = result.stdout.decode("utf-8").split("\0")[:-1]
+    effective = {name: {} for name in relative}
+    for index in range(0, len(fields), 3):
+        name, attribute, value = fields[index:index + 3]
+        effective[name][attribute] = value
+    invalid = [
+        f"{name} (text={values.get('text')}, eol={values.get('eol')})"
+        for name, values in effective.items()
+        if values != {"text": "set", "eol": "lf"}
+    ]
+    if invalid:
+        raise ValueError("manifest paths require repository-owned 'text eol=lf' Git attributes: " + ", ".join(invalid))
+
+
+def synchronize(root: Path = ROOT, *, check: bool = False) -> list[str]:
+    """Validate the entire plan before writing. Return stale deployment paths."""
+    root = root.resolve()
+    source_root = root / "frontend" / "src"
+    static_root = root / "static"
+    manifest = json.loads((root / "frontend" / "modules.json").read_text(encoding="utf-8"))
+    if not isinstance(manifest, dict) or manifest.get("version") != 1 or not isinstance(manifest.get("modules"), list):
+        raise ValueError("expected frontend module manifest version 1")
+    if not manifest["modules"]:
+        raise ValueError("module manifest must not be empty")
+    sources, outputs, plan = set(), set(), []
+    for entry in manifest["modules"]:
+        source = module_path(source_root, entry["source"])
+        output = module_path(static_root, entry["deployment"])
+        if not entry["deployment"].startswith("js/"):
+            raise ValueError("deployment modules must be under static/js/")
+        if source in sources or output in outputs:
+            raise ValueError("each source and deployment path must be unique")
+        sources.add(source)
+        outputs.add(output)
+        content = source.read_bytes()
+        if output.exists() and not output.is_file():
+            raise ValueError(f"deployment path is not a file: {output}")
+        plan.append((output, content))
+    unlisted = set(source_root.rglob("*.js")) - sources
+    if unlisted:
+        raise ValueError(f"source modules missing from manifest: {sorted(map(str, unlisted))}")
+    check_lf_attributes(root, sources | outputs)
+    stale = []
+    for output, content in plan:
+        if not output.is_file() or output.read_bytes() != content:
+            stale.append(output.relative_to(root).as_posix())
+    if not check:
+        for output, content in plan:
+            if output.relative_to(root).as_posix() in stale:
+                output.parent.mkdir(parents=True, exist_ok=True)
+                output.write_bytes(content)
+    return stale
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--check", action="store_true", help="fail on invalid attributes or stale output; write no deployment files")
+    args = parser.parse_args()
+    try:
+        stale = synchronize(check=args.check)
+    except (OSError, ValueError, KeyError, TypeError) as error:
+        parser.exit(2, f"frontend: {error}\n")
+    if args.check and stale:
+        print("Stale frontend deployment modules: " + ", ".join(stale))
+        print("Run python scripts/build_frontend.py and include the source and output changes together.")
+        return 1
+    print(f"Frontend {'check passed' if args.check else 'published'} ({len(stale)} changed modules).")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/scripts/check_frontend.mjs b/scripts/check_frontend.mjs
new file mode 100644
index 000000000..d9aa214a7
--- /dev/null
+++ b/scripts/check_frontend.mjs
@@ -0,0 +1,180 @@
+/** Architecture gates for maintained source. Legacy static modules stay under existing guards. */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parse } from 'acorn';
+
+const layers = ['domain', 'application', 'infrastructure', 'ui'];
+const platformIdentifiers = new Set(['window', 'document', 'globalThis', 'navigator', 'localStorage', 'sessionStorage', 'fetch', 'Notification', 'indexedDB', 'WebSocket', 'XMLHttpRequest', 'Worker', 'setTimeout', 'setInterval', 'clearTimeout', 'clearInterval', 'requestAnimationFrame', 'cancelAnimationFrame', 'performance', 'eval', 'Function']);
+
+function ownership(source) {
+  const parts = source.split('/');
+  if (parts[0] === 'app' && parts.length >= 2) return { feature: 'app', layer: 'index' };
+  if (parts[0] === 'shared') {
+    if (parts.length === 2) return { feature: 'shared', layer: 'domain' };
+    const layer = { domain: 'domain', platform: 'infrastructure', ui: 'ui' }[parts[1]];
+    if (layer) return { feature: 'shared', layer };
+  }
+  if (parts[0] === 'features' && parts.length >= 3) {
+    if (['app', 'shared'].includes(parts[1])) throw new Error(`reserved feature name: ${parts[1]}`);
+    if (parts.length === 3 && parts[2] === 'index.js') return { feature: parts[1], layer: 'index' };
+    if (layers.includes(parts[2]) && parts.length >= 4) return { feature: parts[1], layer: parts[2] };
+  }
+  throw new Error(`unsupported source ownership: ${source}`);
+}
+
+export function allowsDependency(from, to) {
+  const a = ownership(from), b = ownership(to);
+  if (b.feature === 'app') return a.feature === 'app';
+  if (a.feature === 'app') return b.feature === 'shared' || b.layer === 'index';
+  if (b.feature === 'shared') {
+    const shared = { domain: ['domain'], application: ['domain'], infrastructure: ['domain', 'infrastructure'], ui: ['domain', 'infrastructure', 'ui'], index: layers };
+    return shared[a.layer].includes(b.layer);
+  }
+  if (a.feature === 'shared') return false;
+  if (a.feature !== b.feature) return ['application', 'index'].includes(a.layer) && b.layer === 'index';
+  const internal = { domain: ['domain'], application: ['domain', 'application'], infrastructure: ['domain', 'infrastructure'], ui: ['domain', 'application', 'ui'], index: layers };
+  return internal[a.layer].includes(b.layer);
+}
+
+export function imports(source, { domain = false } = {}) {
+  const ast = parse(source, { ecmaVersion: 'latest', sourceType: 'module', locations: true });
+  const found = [];
+  function visit(node, parent, field) {
+    if (!node || typeof node !== 'object') return;
+    // Domain modules use explicit values/ports, including an injected clock.
+    // Keep platform vocabulary out even when a local binding shadows a global.
+    const propertyName = parent && !parent.computed && (
+      (parent.type === 'MemberExpression' && field === 'property') ||
+      (['Property', 'MethodDefinition'].includes(parent.type) && field === 'key' && !parent.shorthand)
+    );
+    if (domain && !propertyName && node.type === 'Identifier' && platformIdentifiers.has(node.name)) {
+      throw new Error(`platform identifier in domain at line ${node.loc.start.line}: ${node.name}`);
+    }
+    if (domain && ((node.type === 'MemberExpression' && node.object.name === 'Date' && (node.property.name === 'now' || node.property.value === 'now')) || (['CallExpression', 'NewExpression'].includes(node.type) && node.callee.name === 'Date' && !node.arguments.length))) {
+      throw new Error(`ambient clock in domain at line ${node.loc.start.line}; inject time`);
+    }
+    if (['ImportDeclaration', 'ExportNamedDeclaration', 'ExportAllDeclaration', 'ImportExpression'].includes(node.type) && node.source) {
+      if (node.source.type !== 'Literal' || typeof node.source.value !== 'string') {
+        throw new Error(`computed import at line ${node.loc.start.line}; use explicit import thunks`);
+      }
+      found.push({ specifier: node.source.value, line: node.loc.start.line, dynamic: node.type === 'ImportExpression' });
+    }
+    for (const [key, value] of Object.entries(node)) {
+      if (Array.isArray(value)) value.forEach(item => visit(item, node, key));
+      else if (value && typeof value === 'object' && value.type) visit(value, node, key);
+    }
+  }
+  visit(ast);
+  return found;
+}
+
+export function checkArchitecture(root) {
+  const manifest = JSON.parse(fs.readFileSync(path.join(root, 'frontend/modules.json'), 'utf8'));
+  const bySource = new Map(manifest.modules.map(m => [m.source, m]));
+  const byOutput = new Map(manifest.modules.map(m => [`/static/${m.deployment}`, m.source]));
+  const graph = new Map();
+  const errors = [];
+  const sw = fs.readFileSync(path.join(root, 'static/sw.js'), 'utf8');
+  // Parse the actual manifest arrays, not comments or unrelated strings.
+  const swAst = parse(sw, { ecmaVersion: 'latest', sourceType: 'script' });
+  const precached = new Set();
+  for (const statement of swAst.body) {
+    for (const declaration of statement.declarations || []) {
+      if (['PRECACHE', 'PANEL_PRECACHE'].includes(declaration.id.name)) {
+        for (const item of declaration.init.elements) {
+          if (item?.type === 'Literal' && typeof item.value === 'string') precached.add(item.value);
+        }
+      }
+    }
+  }
+  for (const module of manifest.modules) {
+    try {
+      const owner = ownership(module.source);
+      const deployed = `/static/${module.deployment}`;
+      if (!precached.has(deployed)) throw new Error(`deployment URL absent from explicit precache: ${deployed}`);
+      const dependencies = [];
+      const exceptions = module.legacyImports || [];
+      const used = new Set();
+      for (const { specifier, line } of imports(fs.readFileSync(path.join(root, 'frontend/src', module.source), 'utf8'), { domain: owner.layer === 'domain' })) {
+        const fail = message => { throw new Error(`line ${line}: ${message}: ${specifier}`); };
+        const runtime = new URL(specifier, `https://odysseus.invalid${deployed}`);
+        if (!runtime.pathname.startsWith('/static/js/') || !runtime.pathname.endsWith('.js') || runtime.pathname.includes('%')) fail('runtime imports must name canonical static JS paths');
+        let target;
+        if (specifier.startsWith('.')) {
+          if (runtime.search || runtime.hash) fail('maintained modules use one unversioned URL identity');
+          target = path.posix.normalize(path.posix.join(path.posix.dirname(module.source), specifier));
+          if (!bySource.has(target)) fail('relative import must name maintained source');
+          if (runtime.pathname !== `/static/${bySource.get(target).deployment}`) fail('source and deployment relative paths resolve differently');
+        } else if (specifier.startsWith('/static/')) {
+          target = byOutput.get(runtime.pathname);
+          if (!target) {
+            const exception = exceptions.find(e => e.specifier === specifier && e.reason?.trim());
+            if (!exception || !['index', 'infrastructure', 'ui'].includes(owner.layer) || owner.feature === 'shared') fail('legacy import requires an explicit module-scoped rationale at a composition, infrastructure or UI boundary');
+            if (!fs.statSync(path.join(root, runtime.pathname.slice(1))).isFile()) fail('legacy target does not exist');
+            used.add(exception);
+            continue;
+          }
+        } else fail('bare, external and source-tree runtime imports are unsupported');
+        if (runtime.search || runtime.hash) fail('maintained modules use one unversioned URL identity');
+        if (!allowsDependency(module.source, target)) fail(`forbidden dependency on ${target}`);
+        dependencies.push(target);
+      }
+      if (exceptions.some(e => !used.has(e))) throw new Error('unused legacy import exception');
+      graph.set(module.source, dependencies);
+    } catch (error) { errors.push(`${module.source}: ${error.message}`); }
+  }
+  const visiting = new Set(), visited = new Set();
+  function visit(source, trail = []) {
+    if (visiting.has(source)) throw new Error(`maintained-source dependency cycle: ${[...trail, source].join(' -> ')}`);
+    if (visited.has(source)) return;
+    visiting.add(source);
+    for (const target of graph.get(source) || []) visit(target, [...trail, source]);
+    visiting.delete(source);
+    visited.add(source);
+  }
+  try { for (const source of graph.keys()) visit(source); }
+  catch (error) { errors.push(error.message); }
+  if (errors.length) throw new Error(errors.join('\n'));
+  return graph.size;
+}
+
+export function inventory(root) {
+  const staticRoot = path.join(root, 'static');
+  const files = fs.readdirSync(staticRoot, { recursive: true }).map(p => p.split(path.sep).join('/')).filter(p => p.endsWith('.js') && !p.startsWith('lib/') && !p.startsWith('js/editor/build/')).sort();
+  const graph = new Map(), fan = new Map(), missing = [];
+  let staticImports = 0, dynamicLiteralImports = 0;
+  for (const file of files) {
+    const targets = [];
+    for (const { specifier, dynamic } of imports(fs.readFileSync(path.join(staticRoot, file), 'utf8'))) {
+      if (!specifier.startsWith('.') && !specifier.startsWith('/static/')) continue;
+      const target = new URL(specifier, `https://odysseus.invalid/static/${file}`).pathname.slice('/static/'.length);
+      if (dynamic) dynamicLiteralImports++;
+      else { staticImports++; targets.push(target); }
+      fan.set(target, (fan.get(target) || 0) + 1);
+      if (!fs.existsSync(path.join(staticRoot, target))) missing.push({ file, specifier });
+    }
+    graph.set(file, targets);
+  }
+  const indices = new Map(), low = new Map(), stack = [], active = new Set(), staticCycles = [];
+  function visit(v) {
+    indices.set(v, indices.size); low.set(v, indices.get(v)); stack.push(v); active.add(v);
+    for (const w of graph.get(v) || []) {
+      if (!indices.has(w)) { visit(w); low.set(v, Math.min(low.get(v), low.get(w))); }
+      else if (active.has(w)) low.set(v, Math.min(low.get(v), indices.get(w)));
+    }
+    if (low.get(v) === indices.get(v)) {
+      const component = []; let w;
+      do { w = stack.pop(); active.delete(w); component.push(w); } while (w !== v);
+      if (component.length > 1) staticCycles.push(component.sort());
+    }
+  }
+  for (const file of files) if (!indices.has(file)) visit(file);
+  return { files: files.length, staticImports, dynamicLiteralImports, missing, fanIn: [...fan].sort((a, b) => b[1] - a[1]).slice(0, 8), staticCycles };
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+  try { console.log(process.argv.includes('--inventory') ? JSON.stringify(inventory(root), null, 2) : `Frontend architecture passed (${checkArchitecture(root)} maintained modules).`); }
+  catch (error) { console.error(error.message); process.exitCode = 1; }
+}
diff --git a/scripts/verify_frontend_runtime.py b/scripts/verify_frontend_runtime.py
new file mode 100644
index 000000000..07b0bb3dd
--- /dev/null
+++ b/scripts/verify_frontend_runtime.py
@@ -0,0 +1,69 @@
+#!/usr/bin/env python3
+"""Verify the current Python runtime from an isolated distribution without frontend tooling."""
+import os
+from pathlib import Path
+import shutil
+import socket
+import subprocess
+import sys
+import tempfile
+
+ROOT = Path(__file__).resolve().parents[1]
+
+PROBE = """
+from pathlib import Path
+import shutil
+from starlette.testclient import TestClient
+from app import app
+assert not Path('frontend').exists()
+assert not Path('node_modules').exists()
+assert shutil.which('node') is None
+with TestClient(app) as client:
+    response = client.get('/static/js/actionMenuOrder.js')
+    assert response.status_code == 200, response.status_code
+    assert response.content == Path('static/js/actionMenuOrder.js').read_bytes()
+    assert response.headers['content-type'].startswith('text/javascript'), response.headers
+    assert response.headers['cache-control'] == 'no-cache', response.headers
+    assert "script-src 'self' 'nonce-" in response.headers['content-security-policy'], response.headers
+    assert client.get('/frontend/src/shared/actionMenuOrder.js').status_code == 404
+    assert client.get('/static/%2e%2e/app.py').status_code == 404
+    shell = client.get('/')
+    assert shell.status_code == 200, shell.status_code
+    assert '{{CSP_NONCE}}' not in shell.text
+    assert '/static/app.js' in shell.text
+print('PASS: isolated Python lifespan, shell, deployed bytes, MIME, revalidation, CSP and source-tree 404')
+"""
+
+
+def main() -> int:
+    with tempfile.TemporaryDirectory(prefix="ody-f1-distribution-") as directory, socket.socket() as chroma_guard:
+        target = Path(directory)
+        for name in ("app.py", "HARNESS_VERSION"):
+            shutil.copy2(ROOT / name, target / name)
+        for name in ("core", "routes", "src", "services", "resources", "mcp_servers", "companion", "config", "static", "scripts"):
+            shutil.copytree(ROOT / name, target / name, ignore=shutil.ignore_patterns("__pycache__", "node_modules", ".env", "secrets.env*", "*.db", "*.sqlite*"))
+        # Reserve a non-listening port so initialization cannot reach a real store.
+        chroma_guard.bind(("127.0.0.1", 0))
+        env = dict(os.environ)
+        env.update(
+            ODYSSEUS_DATA_DIR=str(target / "data"),
+            DATABASE_URL="sqlite:///:memory:",
+            AUTH_ENABLED="false",
+            ODYSSEUS_STARTUP_WARMUPS="0",
+            ODYSSEUS_TOOL_INDEX_PREWARM="0",
+            CHROMADB_HOST="127.0.0.1",
+            CHROMADB_PORT=str(chroma_guard.getsockname()[1]),
+            FASTEMBED_CACHE_PATH=str(target / "fastembed"),
+            PATH=str(target / "no-development-tools"),
+        )
+        # A caller's Python search path must not import the original checkout.
+        env.pop("PYTHONPATH", None)
+        result = subprocess.run([sys.executable, "-c", PROBE], cwd=target, env=env, capture_output=True, text=True, timeout=60)
+        print(result.stdout, end="")
+        if result.returncode:
+            print(result.stderr[-8000:], file=sys.stderr)
+        return result.returncode
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/tests/frontendArchitecture.test.mjs b/tests/frontendArchitecture.test.mjs
new file mode 100644
index 000000000..f9af0fbab
--- /dev/null
+++ b/tests/frontendArchitecture.test.mjs
@@ -0,0 +1,142 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import test from 'node:test';
+import { allowsDependency, imports, checkArchitecture, inventory } from '../scripts/check_frontend.mjs';
+import * as source from '../frontend/src/shared/actionMenuOrder.js';
+import * as deployed from '../static/js/actionMenuOrder.js';
+
+test('stateless helper preserves its public API, ordering, references and inputs', () => {
+  for (const module of [source, deployed]) {
+    assert.deepEqual(Object.keys(module).sort(), ['SELECT_MENU_ICON', 'actionMenuRank', 'orderActionMenuItems']);
+    const callback = () => {};
+    const items = ['Delete', 'Select', 'Copy', 'Rename', 'Archive', 'Open', 'Cancel'].map(label => Object.freeze({ label, action: callback }));
+    Object.freeze(items);
+    const sorted = module.orderActionMenuItems(items);
+    assert.deepEqual(sorted.map(i => i.label), ['Open', 'Rename', 'Copy', 'Select', 'Archive', 'Delete', 'Cancel']);
+    assert.ok(sorted.every(i => items.includes(i)));
+    assert.deepEqual(module.orderActionMenuItems([]), []);
+    assert.equal(module.actionMenuRank({ menuOrder: 12, label: 'Delete' }), 12);
+    assert.equal(module.actionMenuRank({ label: 'Unknown' }), 100);
+    const equalRank = [{ label: 'Open first' }, { label: 'Open second' }];
+    assert.deepEqual(module.orderActionMenuItems(equalRank), equalRank);
+  }
+  assert.equal(source.SELECT_MENU_ICON, deployed.SELECT_MENU_ICON);
+});
+
+test('dependency direction separates composition, workflow, adapters and views', () => {
+  const n = name => `features/notes/${name}.js`;
+  const allowed = [
+    ['app/bootstrap.js', n('index')],
+    [n('index'), n('infrastructure/api')],
+    [n('application/crud'), n('domain/recurrence')],
+    [n('infrastructure/api'), 'shared/platform/http.js'],
+    [n('ui/panel'), n('application/crud')],
+    [n('application/reminders'), 'features/calendar/index.js'],
+  ];
+  for (const [from, to] of allowed) assert.ok(allowsDependency(from, to), `${from} -> ${to}`);
+  const forbidden = [
+    [n('domain/recurrence'), n('infrastructure/api')],
+    [n('application/crud'), n('ui/panel')],
+    [n('application/crud'), n('infrastructure/api')],
+    [n('ui/panel'), 'features/calendar/index.js'],
+    [n('application/crud'), 'features/calendar/application/store.js'],
+    ['app/bootstrap.js', n('domain/recurrence')],
+    ['shared/platform/http.js', n('index')],
+    [n('domain/recurrence'), 'app/bootstrap.js'],
+  ];
+  for (const [from, to] of forbidden) assert.equal(allowsDependency(from, to), false, `${from} -> ${to}`);
+});
+
+test('parser sees re-exports, multiline and dynamic imports without comment false positives', () => {
+  const code = `// import './false.js';
+    const text = "import './false.js'";
+    import { a }\n from './a.js';
+    export { b } from './b.js';
+    export * from './c.js';
+    const load = () => import('./d.js');`;
+  assert.deepEqual(imports(code).map(i => i.specifier), ['./a.js', './b.js', './c.js', './d.js']);
+  assert.throws(() => imports('const load = p => import(p);'), /computed import/);
+  assert.throws(() => imports('export const now = () => Date.now();', { domain: true }), /ambient clock/);
+  assert.throws(() => imports('export const load = () => fetch("/api/notes");', { domain: true }), /platform identifier/);
+  assert.doesNotThrow(() => imports('export const day = value => new Date(value);', { domain: true }));
+  assert.doesNotThrow(() => imports('export const copy = value => ({ document: value.document });', { domain: true }));
+});
+
+function fixture(t, modules, { cache = true } = {}) {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'ody-frontend-gates-'));
+  t.after(() => fs.rmSync(root, { recursive: true, force: true }));
+  const entries = Object.entries(modules).map(([name, code]) => {
+    const file = path.join(root, 'frontend/src', name);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, code);
+    return { source: name, deployment: `js/${name}` };
+  });
+  fs.mkdirSync(path.join(root, 'static'), { recursive: true });
+  fs.writeFileSync(path.join(root, 'frontend/modules.json'), JSON.stringify({ version: 1, modules: entries }));
+  const urls = cache ? entries.map(m => `/static/${m.deployment}`) : [];
+  fs.writeFileSync(path.join(root, 'static/sw.js'), `const PRECACHE = ${JSON.stringify(urls)}; const PANEL_PRECACHE = [];`);
+  return root;
+}
+
+test('complete mapped graph and exact precache pass', t => {
+  const root = fixture(t, { 'features/notes/index.js': "export { value } from './domain/value.js';", 'features/notes/domain/value.js': 'export const value = 1;' });
+  assert.equal(checkArchitecture(root), 2);
+});
+
+test('feature-private import fails through the full checker', t => {
+  const root = fixture(t, { 'features/notes/application/a.js': "import '../../calendar/domain/b.js';", 'features/calendar/domain/b.js': 'export const value = 1;' });
+  assert.throws(() => checkArchitecture(root), /forbidden dependency/);
+});
+
+test('undeclared legacy coupling and alternate identities fail', t => {
+  for (const specifier of ['/static/js/notes.js?v=legacy', './b.js?v=other', '/frontend/src/shared/b.js', 'some-package']) {
+    const root = fixture(t, { 'shared/a.js': `import '${specifier}';`, 'shared/b.js': 'export const value = 1;' });
+    assert.throws(() => checkArchitecture(root), /legacy import|one unversioned|unsupported|canonical static/);
+  }
+});
+
+test('a copy mapping cannot silently change relative import resolution', t => {
+  const root = fixture(t, { 'shared/a.js': "import './b.js';", 'shared/b.js': 'export const value = 1;' });
+  const manifest = JSON.parse(fs.readFileSync(path.join(root, 'frontend/modules.json')));
+  manifest.modules[1].deployment = 'js/elsewhere/b.js';
+  fs.writeFileSync(path.join(root, 'frontend/modules.json'), JSON.stringify(manifest));
+  fs.writeFileSync(path.join(root, 'static/sw.js'), "const PRECACHE = ['/static/js/shared/a.js', '/static/js/elsewhere/b.js'];");
+  assert.throws(() => checkArchitecture(root), /resolve differently/);
+});
+
+test('new modules must join exact offline manifests and cannot introduce cycles', t => {
+  const missing = fixture(t, { 'shared/a.js': 'export const a = 1;' }, { cache: false });
+  assert.throws(() => checkArchitecture(missing), /absent from explicit precache/);
+  const cyclic = fixture(t, { 'shared/a.js': "import './b.js';", 'shared/b.js': "import './a.js';" });
+  assert.throws(() => checkArchitecture(cyclic), /dependency cycle/);
+});
+
+test('legacy adapters require exact, used exceptions and reserved names cannot bypass ownership', t => {
+  const root = fixture(t, { 'features/notes/infrastructure/api.js': "import '/static/js/legacy.js?v=existing';" });
+  fs.mkdirSync(path.join(root, 'static/js'), { recursive: true });
+  fs.writeFileSync(path.join(root, 'static/js/legacy.js'), 'export const legacy = true;');
+  const file = path.join(root, 'frontend/modules.json');
+  const manifest = JSON.parse(fs.readFileSync(file));
+  manifest.modules[0].legacyImports = [{ specifier: '/static/js/legacy.js?v=existing', reason: 'Temporary existing transport adapter; remove in N2.' }];
+  fs.writeFileSync(file, JSON.stringify(manifest));
+  assert.equal(checkArchitecture(root), 1);
+  manifest.modules[0].legacyImports.push({ specifier: '/static/js/unused.js', reason: 'stale' });
+  fs.writeFileSync(file, JSON.stringify(manifest));
+  assert.throws(() => checkArchitecture(root), /unused legacy import exception/);
+  assert.throws(() => allowsDependency('features/shared/index.js', 'app/bootstrap.js'), /reserved feature name/);
+});
+
+test('inventory reports executable static cycles and separates dynamic edges', t => {
+  const root = fixture(t, { 'shared/a.js': 'export const a = 1;' });
+  fs.mkdirSync(path.join(root, 'static/js'), { recursive: true });
+  fs.writeFileSync(path.join(root, 'static/js/a.js'), "import './b.js'; const load = () => import('./c.js');");
+  fs.writeFileSync(path.join(root, 'static/js/b.js'), "import './a.js';");
+  fs.writeFileSync(path.join(root, 'static/js/c.js'), 'export const c = 1;');
+  const result = inventory(root);
+  assert.equal(result.staticImports, 2);
+  assert.equal(result.dynamicLiteralImports, 1);
+  assert.deepEqual(result.staticCycles, [['js/a.js', 'js/b.js']]);
+  assert.deepEqual(result.missing, []);
+});
diff --git a/tests/test_frontend_build.py b/tests/test_frontend_build.py
new file mode 100644
index 000000000..cbfd3371b
--- /dev/null
+++ b/tests/test_frontend_build.py
@@ -0,0 +1,170 @@
+"""Exercise publication failure modes without changing the real static tree."""
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+from tests.helpers.cli_loader import load_script
+
+ROOT = Path(__file__).resolve().parents[1]
+build = load_script("build_frontend.py")
+
+
+def project(tmp_path, entries=None):
+    source = tmp_path / "frontend/src/shared/helper.js"
+    source.parent.mkdir(parents=True)
+    source.write_bytes(b"export const value = 1;\n")
+    manifest = {"version": 1, "modules": entries if entries is not None else [
+        {"source": "shared/helper.js", "deployment": "js/helper.js"}
+    ]}
+    (tmp_path / "frontend/modules.json").write_text(json.dumps(manifest), encoding="utf-8")
+    (tmp_path / ".gitattributes").write_text("* text=auto\nfrontend/src/** text eol=lf\nstatic/js/helper.js text eol=lf\n", encoding="utf-8")
+    return source, tmp_path / "static/js/helper.js"
+
+
+def test_check_detects_missing_and_stale_output_without_writing(tmp_path):
+    source, output = project(tmp_path)
+    assert build.synchronize(tmp_path, check=True) == ["static/js/helper.js"]
+    assert not output.exists()
+    assert build.synchronize(tmp_path) == ["static/js/helper.js"]
+    assert output.read_bytes() == source.read_bytes()
+    source.write_bytes(b"export const value = 2;\n")
+    assert build.synchronize(tmp_path, check=True) == ["static/js/helper.js"]
+    assert output.read_bytes() == b"export const value = 1;\n"
+
+
+def test_publication_is_idempotent_and_preserves_unowned_assets(tmp_path):
+    source, output = project(tmp_path)
+    unowned = tmp_path / "static/js/notes.js"
+    unowned.parent.mkdir(parents=True)
+    unowned.write_bytes(b"legacy state owner\n")
+    build.synchronize(tmp_path)
+    timestamp = output.stat().st_mtime_ns
+    assert build.synchronize(tmp_path) == []
+    assert output.stat().st_mtime_ns == timestamp
+    assert unowned.read_bytes() == b"legacy state owner\n"
+    assert output.read_bytes() == source.read_bytes()
+
+
+@pytest.mark.parametrize("bad", ["../outside.js", "/absolute.js", "shared/../helper.js", "shared\\helper.js", "shared/helper.js?v=1", "shared/helper.js#fragment", "shared/helper.ts"])
+def test_invalid_plan_does_not_partially_publish(tmp_path, bad):
+    project(tmp_path, [
+        {"source": "shared/helper.js", "deployment": "js/helper.js"},
+        {"source": bad, "deployment": "js/other.js"},
+    ])
+    with pytest.raises(ValueError, match="invalid module path"):
+        build.synchronize(tmp_path)
+    assert not (tmp_path / "static").exists()
+
+
+def test_duplicate_outputs_and_unmapped_sources_are_rejected(tmp_path):
+    source, output = project(tmp_path)
+    extra = source.with_name("extra.js")
+    extra.write_bytes(b"export const value = 2;\n")
+    with pytest.raises(ValueError, match="missing from manifest"):
+        build.synchronize(tmp_path)
+    manifest_path = tmp_path / "frontend/modules.json"
+    manifest = json.loads(manifest_path.read_text())
+    manifest["modules"].append({"source": "shared/extra.js", "deployment": "js/helper.js"})
+    manifest_path.write_text(json.dumps(manifest))
+    with pytest.raises(ValueError, match="must be unique"):
+        build.synchronize(tmp_path)
+    assert not output.exists()
+
+
+def test_symlink_output_cannot_overwrite_another_file(tmp_path):
+    _, output = project(tmp_path)
+    outside = tmp_path / "outside.js"
+    outside.write_bytes(b"untouched\n")
+    output.parent.mkdir(parents=True)
+    output.symlink_to(outside)
+    with pytest.raises(ValueError, match="escapes|symlink"):
+        build.synchronize(tmp_path)
+    assert outside.read_bytes() == b"untouched\n"
+
+
+def test_real_checkout_check_works_from_another_directory(tmp_path):
+    result = subprocess.run([sys.executable, str(ROOT / "scripts/build_frontend.py"), "--check"], cwd=tmp_path, capture_output=True, text=True, timeout=20)
+    assert result.returncode == 0, result.stdout + result.stderr
+    assert (ROOT / "frontend/src/shared/actionMenuOrder.js").read_bytes() == (ROOT / "static/js/actionMenuOrder.js").read_bytes()
+
+
+def test_isolated_python_distribution_runs_without_source_or_node():
+    result = subprocess.run([sys.executable, str(ROOT / "scripts/verify_frontend_runtime.py")], cwd=ROOT, capture_output=True, text=True, timeout=90)
+    assert result.returncode == 0, result.stdout + result.stderr
+    assert "PASS: isolated Python lifespan" in result.stdout
+
+
+@pytest.mark.parametrize("check", [False, True])
+@pytest.mark.parametrize("path,rule", [
+    ("frontend/src/shared/helper.js", "text"),
+    ("static/js/helper.js", "text"),
+    ("frontend/src/shared/helper.js", "text eol=crlf"),
+    ("static/js/helper.js", "text=auto eol=lf"),
+    ("static/js/helper.js", "-text eol=lf"),
+])
+def test_each_manifest_path_requires_lf_even_when_bytes_already_match(tmp_path, check, path, rule):
+    source, output = project(tmp_path)
+    output.parent.mkdir(parents=True)
+    output.write_bytes(source.read_bytes())
+    other = "static/js/helper.js" if path.startswith("frontend/") else "frontend/src/shared/helper.js"
+    (tmp_path / ".gitattributes").write_text(f"* text=auto\n{other} text eol=lf\n{path} {rule}\n", encoding="utf-8")
+    with pytest.raises(ValueError, match="require repository-owned.*" + path):
+        build.synchronize(tmp_path, check=check)
+    assert output.read_bytes() == source.read_bytes()
+
+
+def test_future_manifest_pair_cannot_publish_without_output_attributes(tmp_path):
+    source, output = project(tmp_path)
+    extra = source.with_name("future.js")
+    extra.write_bytes(b"export const future = true;\n")
+    manifest_file = tmp_path / "frontend/modules.json"
+    manifest = json.loads(manifest_file.read_text())
+    manifest["modules"].append({"source": "shared/future.js", "deployment": "js/future.js"})
+    manifest_file.write_text(json.dumps(manifest))
+    with pytest.raises(ValueError, match="static/js/future.js"):
+        build.synchronize(tmp_path)
+    assert not output.exists()
+    assert not (tmp_path / "static/js/future.js").exists()
+    with (tmp_path / ".gitattributes").open("a", encoding="utf-8") as attributes:
+        attributes.write("static/js/future.js text eol=lf\n")
+    assert build.synchronize(tmp_path) == ["static/js/helper.js", "static/js/future.js"]
+    assert build.synchronize(tmp_path, check=True) == []
+
+
+def test_nested_git_attribute_rules_and_paths_with_spaces_are_supported(tmp_path):
+    source, _ = project(tmp_path, [{"source": "shared/helper.js", "deployment": "js/feature space/helper.js"}])
+    attributes = tmp_path / "static/js/feature space/.gitattributes"
+    attributes.parent.mkdir(parents=True)
+    attributes.write_text("*.js text eol=lf\n", encoding="utf-8")
+    assert build.synchronize(tmp_path) == ["static/js/feature space/helper.js"]
+    assert (attributes.parent / "helper.js").read_bytes() == source.read_bytes()
+    attributes.write_text("*.js text eol=crlf\n", encoding="utf-8")
+    with pytest.raises(ValueError, match="eol=crlf"):
+        build.synchronize(tmp_path, check=True)
+
+
+def test_global_and_local_git_settings_cannot_mask_missing_repository_rule(tmp_path, monkeypatch):
+    project(tmp_path)
+    (tmp_path / ".gitattributes").write_text("frontend/src/** text eol=lf\n", encoding="utf-8")
+    global_attributes = tmp_path / "global-attributes"
+    global_attributes.write_text("* text eol=lf\n", encoding="utf-8")
+    config = tmp_path / "global-config"
+    config.write_text(f'[core]\n attributesFile = "{global_attributes.as_posix()}"\n autocrlf = true\n', encoding="utf-8")
+    subprocess.run(["git", "init", "--quiet", str(tmp_path)], check=True, capture_output=True)
+    (tmp_path / ".git/info/attributes").write_text("* text eol=lf\n", encoding="utf-8")
+    monkeypatch.setenv("GIT_CONFIG_GLOBAL", str(config))
+    monkeypatch.setenv("GIT_DIR", str(tmp_path / ".git"))
+    monkeypatch.setenv("GIT_WORK_TREE", str(tmp_path))
+    with pytest.raises(ValueError, match="static/js/helper.js"):
+        build.synchronize(tmp_path, check=True)
+
+
+def test_attribute_enforcement_fails_clearly_when_development_git_is_missing(tmp_path, monkeypatch):
+    _, output = project(tmp_path)
+    monkeypatch.setattr(build.shutil, "which", lambda name: None)
+    with pytest.raises(ValueError, match="Git is required for frontend publication"):
+        build.synchronize(tmp_path)
+    assert not output.exists()
diff --git a/tests/test_frontend_foundation_offline_js.py b/tests/test_frontend_foundation_offline_js.py
new file mode 100644
index 000000000..314280e5e
--- /dev/null
+++ b/tests/test_frontend_foundation_offline_js.py
@@ -0,0 +1,63 @@
+"""Real Chromium proof at the existing /static/ service-worker scope.
+
+This deliberately does not widen SW scope or claim offline SPA root reload.
+The helper is first evaluated offline, after install-time precaching only.
+"""
+import json
+import shutil
+import subprocess
+from pathlib import Path
+
+import pytest
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+@pytest.mark.skipif(shutil.which("node") is None, reason="node binary not on PATH")
+def test_precached_helper_imports_offline_in_a_fresh_page_and_panels_stay_lazy():
+    script = r'''
+      import assert from 'node:assert/strict';
+      import { chromium } from 'playwright';
+      const origin = process.env.ODYSSEUS_TEST_STATIC_ORIGIN;
+      const browser = await chromium.launch({ headless: true });
+      try {
+        const context = await browser.newContext({ serviceWorkers: 'allow' });
+        const page = await context.newPage();
+        await page.goto(`${origin}/static/js/panels.js`);
+        const installed = await page.evaluate(async () => {
+          await navigator.serviceWorker.register('/static/sw.js?v=20260916autoscroll1');
+          const registration = await navigator.serviceWorker.ready;
+          if (!navigator.serviceWorker.controller) await new Promise(resolve => navigator.serviceWorker.addEventListener('controllerchange', resolve, { once: true }));
+          const response = await caches.match('/static/js/actionMenuOrder.js');
+          return { scope: registration.scope, cached: !!response && response.ok };
+        });
+        assert.equal(installed.scope, `${origin}/static/`);
+        assert.equal(installed.cached, true);
+        // New page gives a fresh ES-module map. No helper import occurred online.
+        await context.setOffline(true);
+        const offline = await context.newPage();
+        await offline.goto(`${origin}/static/js/panels.js`);
+        const requests = [];
+        offline.on('request', request => requests.push(request.url()));
+        const result = await offline.evaluate(async () => {
+          const helper = await import('/static/js/actionMenuOrder.js');
+          const again = await import('./actionMenuOrder.js');
+          const panels = await import('/static/js/panels.js?v=20260909movepicklayer1');
+          return {
+            sameModule: helper === again,
+            exports: Object.keys(helper).sort(),
+            order: helper.orderActionMenuItems([{ label: 'Delete' }, { label: 'Rename' }]).map(i => i.label),
+            panels: panels.panelNames(),
+          };
+        });
+        assert.equal(result.sameModule, true);
+        assert.deepEqual(result.order, ['Rename', 'Delete']);
+        assert.ok(result.panels.includes('editor'));
+        assert.equal(requests.some(url => url.includes('/galleryEditor.js')), false);
+        console.log(JSON.stringify({ ...result, ...installed }));
+      } finally { await browser.close(); }
+    '''
+    result = subprocess.run(["node", "--input-type=module", "--eval", script], cwd=ROOT, capture_output=True, text=True, timeout=90)
+    assert result.returncode == 0, result.stdout + result.stderr
+    data = json.loads(result.stdout)
+    assert data["exports"] == ["SELECT_MENU_ICON", "actionMenuRank", "orderActionMenuItems"]

From f902be18f7219c493ae70bf7ae53afc6bfa212cc Mon Sep 17 00:00:00 2001
From: Alexandre Teixeira <111787685+alteixeira20@users.noreply.github.com>
Date: Tue, 13 Oct 2026 22:11:23 +0100
Subject: [PATCH 09/53] fix(ci): restore dev pytest baseline (#6704)

* chore(ci): initialize dev pytest baseline repair

* fix(ci): restore utility compaction tests and CSS snapshot
---
 static/css/11-tasks.css                      |  3 +-
 tests/test_aux_llm_owner_scope.py            | 40 +++++++++++++++++++-
 tests/test_chatgpt_reasoning_and_grouping.py |  5 ++-
 tests/test_context_compactor.py              |  9 ++++-
 tests/test_history_compact_tool_calls.py     | 27 ++++++++++++-
 tests/test_model_helper_owner_scope.py       | 21 +++++++++-
 6 files changed, 97 insertions(+), 8 deletions(-)

diff --git a/static/css/11-tasks.css b/static/css/11-tasks.css
index 7067c95c9..a770761b4 100644
--- a/static/css/11-tasks.css
+++ b/static/css/11-tasks.css
@@ -989,6 +989,7 @@ a.chat-link[href^="#research-"] {
 .settings-row {
   display: flex;
   align-items: center;
+  gap: 8px;
 }
 .settings-col {
   display: flex;
@@ -997,7 +998,7 @@ a.chat-link[href^="#research-"] {
 }
 .settings-label {
   font-size: 12px;
-  min-width: 85px;
+  min-width: 70px;
 }
 #set-utilityEffortLabel { flex: 0 0 85px; line-height: 1.2; }
 .settings-label-sub {
diff --git a/tests/test_aux_llm_owner_scope.py b/tests/test_aux_llm_owner_scope.py
index f4aeec420..631cbcdae 100644
--- a/tests/test_aux_llm_owner_scope.py
+++ b/tests/test_aux_llm_owner_scope.py
@@ -1,3 +1,4 @@
+import ast
 from pathlib import Path
 
 
@@ -8,11 +9,42 @@ def _src(path: str) -> str:
     return (ROOT / path).read_text(encoding="utf-8")
 
 
+def _utility_kwargs(source: str, function_name: str) -> dict:
+    tree = ast.parse(source)
+
+    functions = [
+        node for node in ast.walk(tree)
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef))
+        and node.name == function_name
+    ]
+    assert len(functions) == 1, function_name
+
+    calls = [
+        node for node in ast.walk(functions[0])
+        if isinstance(node, ast.Call)
+        and isinstance(node.func, ast.Name)
+        and node.func.id == "resolve_endpoint"
+        and node.args
+        and isinstance(node.args[0], ast.Constant)
+        and node.args[0].value == "utility"
+    ]
+    assert len(calls) == 1, function_name
+
+    return {
+        kw.arg: ast.unparse(kw.value)
+        for kw in calls[0].keywords
+    }
+
+
 def test_registered_manual_compaction_uses_session_owner_for_utility_endpoint():
     session_src = _src("routes/session_routes.py")
 
     assert 'owner = getattr(session, "owner", None) or effective_user(request)' in session_src
-    assert 'resolve_endpoint("utility", owner=owner)' in session_src
+    kwargs = _utility_kwargs(session_src, "compact_session")
+    assert kwargs["owner"] == "owner"
+    assert kwargs["fallback_url"] == "getattr(session, 'endpoint_url', None)"
+    assert kwargs["fallback_model"] == "getattr(session, 'model', None)"
+    assert kwargs["fallback_headers"] == "getattr(session, 'headers', None)"
 
 
 def test_task_name_generation_uses_owner_scoped_session_endpoint():
@@ -31,7 +63,11 @@ def test_auto_compaction_utility_endpoint_keeps_chat_owner():
 
     assert "owner=user" in helper_src
     assert "owner: Optional[str] = None" in compact_src
-    assert 'resolve_endpoint("utility", owner=owner)' in compact_src
+    kwargs = _utility_kwargs(compact_src, "maybe_compact")
+    assert kwargs["owner"] == "owner"
+    assert kwargs["fallback_url"] == "endpoint_url"
+    assert kwargs["fallback_model"] == "model"
+    assert kwargs["fallback_headers"] == "headers"
 
 
 def test_background_session_sort_uses_owner_task_endpoint():
diff --git a/tests/test_chatgpt_reasoning_and_grouping.py b/tests/test_chatgpt_reasoning_and_grouping.py
index adc3fe171..dcad44f1d 100644
--- a/tests/test_chatgpt_reasoning_and_grouping.py
+++ b/tests/test_chatgpt_reasoning_and_grouping.py
@@ -183,7 +183,10 @@ def test_history_and_chat_routes_support_reasoning_effort():
     """Verify history and chat routes support reasoning_effort and thinking_mode persistence."""
     hist_src = (ROOT / "routes/history/history_routes.py").read_text(encoding="utf-8")
     assert "reasoning_effort" in hist_src
-    assert 'mode = f"effort:{clean_effort}"' in hist_src
+    assert "def _effort_mode(" in hist_src
+    assert 'return f"effort:{effort}" if effort else "off"' in hist_src
+    assert "mode = _effort_mode(session.model, raw_effort)" in hist_src
+    assert "mode = _effort_mode(session.model, raw_mode[7:])" in hist_src
 
     chat_src = (ROOT / "routes/chat_routes.py").read_text(encoding="utf-8")
     assert "validate_reasoning_effort(sess.model, reasoning_effort)" in chat_src
diff --git a/tests/test_context_compactor.py b/tests/test_context_compactor.py
index 10d0238fb..84b7162f5 100644
--- a/tests/test_context_compactor.py
+++ b/tests/test_context_compactor.py
@@ -311,7 +311,14 @@ class TestMaybeCompactFourthMessage:
 
         cc.get_context_length = lambda url, model: context_length
         cc.llm_call_async = _fake_summary
-        cc.resolve_endpoint = lambda which, owner=None: (None, None, None)
+        def fake_resolve_endpoint(which, **kwargs):
+            assert which == "utility"
+            assert kwargs["fallback_url"] == "http://local/v1/chat/completions"
+            assert kwargs["fallback_model"] == "local-model"
+            assert kwargs["fallback_headers"] == {}
+            return None, None, None
+
+        cc.resolve_endpoint = fake_resolve_endpoint
         cc._update_session_history = lambda *a, **k: None
         try:
             return asyncio.run(
diff --git a/tests/test_history_compact_tool_calls.py b/tests/test_history_compact_tool_calls.py
index 41dd3531d..bcfb414d6 100644
--- a/tests/test_history_compact_tool_calls.py
+++ b/tests/test_history_compact_tool_calls.py
@@ -108,8 +108,12 @@ def _compact_prompt_for(monkeypatch, history):
     import src.model_context as model_context
 
     monkeypatch.setattr(agent_runs, "is_active", lambda session_id: False)
-    def fake_resolve_endpoint(kind, owner=None):
+    def fake_resolve_endpoint(kind, owner=None, **kwargs):
         captured.setdefault("resolve_calls", []).append((kind, owner))
+        if "fallback_url" in kwargs:
+            captured.setdefault("fallback_calls", []).append(
+                (kind, owner, kwargs)
+            )
         return None, None, {}
 
     monkeypatch.setattr(endpoint_resolver, "resolve_endpoint", fake_resolve_endpoint)
@@ -127,6 +131,13 @@ def _compact_prompt_for(monkeypatch, history):
     assert response.status_code == 200
     assert response.json()["status"] == "ok"
     assert manager.saved is True
+    assert any(
+        kind == "utility"
+        and kwargs.get("fallback_url") == session.endpoint_url
+        and kwargs.get("fallback_model") == session.model
+        and kwargs.get("fallback_headers") == session.headers
+        for kind, _owner, kwargs in captured.get("fallback_calls", [])
+    )
     return captured["messages"][1]["content"]
 
 
@@ -151,8 +162,12 @@ def _registered_compact_response(monkeypatch, history, active_run=False):
     import src.llm_core as llm_core
 
     monkeypatch.setattr(agent_runs, "is_active", lambda session_id: active_run)
-    def fake_resolve_endpoint(kind, owner=None):
+    def fake_resolve_endpoint(kind, owner=None, **kwargs):
         captured.setdefault("resolve_calls", []).append((kind, owner))
+        if "fallback_url" in kwargs:
+            captured.setdefault("fallback_calls", []).append(
+                (kind, owner, kwargs)
+            )
         return None, None, {}
 
     monkeypatch.setattr(endpoint_resolver, "resolve_endpoint", fake_resolve_endpoint)
@@ -237,6 +252,14 @@ def test_registered_manual_compact_route_uses_session_owner(monkeypatch):
     assert response.status_code == 200
     assert manager.replaced_messages is not None
     assert ("utility", "session-owner") in captured["resolve_calls"]
+    assert any(
+        kind == "utility"
+        and owner == "session-owner"
+        and kwargs.get("fallback_url") == manager.session.endpoint_url
+        and kwargs.get("fallback_model") == manager.session.model
+        and kwargs.get("fallback_headers") == manager.session.headers
+        for kind, owner, kwargs in captured.get("fallback_calls", [])
+    )
 
 
 def test_registered_manual_compact_route_rejects_active_agent_run(monkeypatch):
diff --git a/tests/test_model_helper_owner_scope.py b/tests/test_model_helper_owner_scope.py
index 31023d316..fb51948b8 100644
--- a/tests/test_model_helper_owner_scope.py
+++ b/tests/test_model_helper_owner_scope.py
@@ -36,7 +36,26 @@ def test_task_parse_resolves_with_owner_scope():
 def test_history_compact_resolves_with_owner_scope():
     body = _function_source("routes/history/history_routes.py", "compact_session")
     assert "owner = effective_user(request)" in body
-    assert 'resolve_endpoint("utility", owner=owner or None)' in body
+    tree = ast.parse(body)
+    calls = [
+        node for node in ast.walk(tree)
+        if isinstance(node, ast.Call)
+        and isinstance(node.func, ast.Name)
+        and node.func.id == "resolve_endpoint"
+        and node.args
+        and isinstance(node.args[0], ast.Constant)
+        and node.args[0].value == "utility"
+    ]
+    assert len(calls) == 1
+
+    kwargs = {
+        kw.arg: ast.unparse(kw.value)
+        for kw in calls[0].keywords
+    }
+    assert kwargs["owner"] == "owner or None"
+    assert kwargs["fallback_url"] == "getattr(session, 'endpoint_url', None)"
+    assert kwargs["fallback_model"] == "getattr(session, 'model', None)"
+    assert kwargs["fallback_headers"] == "getattr(session, 'headers', None)"
 
 
 def test_note_reminder_synthesis_resolves_with_owner_scope():

From 86b886c611338282af6d4a717246ea4e256f58df Mon Sep 17 00:00:00 2001
From: zai184 <zai@gmx.org>
Date: Wed, 14 Oct 2026 00:15:21 +0200
Subject: [PATCH 10/53] feat(skills): remote-only tag hides skills from local
 endpoints (#6693)

Skills tagged remote-only in frontmatter are excluded from the injected
skill index when the active model's endpoint is local (loopback/private/
tailscale per is_local_endpoint). Big on-demand reference lookups
overwhelm small local contexts; local models never see the skill, while
remote models and API/UI listings are unaffected.

- SkillsManager.index_for gains optional keyword-only local_model flag
  (None = don't gate, same contract as active_toolsets=None)
- _build_system_prompt/_build_base_prompt thread endpoint_url from
  _build_route_request_state; unknown endpoint fails open
- tests: cover hidden-on-local, visible-on-remote/unknown, untagged
  skills never gated

Refs: discussed for the local-model overwhelm problem

Co-authored-by: Alexandre Teixeira <111787685+alteixeira20@users.noreply.github.com>
---
 services/memory/skills.py                    |  6 ++
 src/agent_loop.py                            | 11 ++-
 tests/test_skill_index_local_model_gating.py | 98 ++++++++++++++++++++
 3 files changed, 114 insertions(+), 1 deletion(-)
 create mode 100644 tests/test_skill_index_local_model_gating.py

diff --git a/services/memory/skills.py b/services/memory/skills.py
index 5bf583389..2d0ad7063 100644
--- a/services/memory/skills.py
+++ b/services/memory/skills.py
@@ -674,6 +674,7 @@ class SkillsManager:
         *,
         active_toolsets: Optional[List[str]] = None,
         platform: Optional[str] = None,
+        local_model: Optional[bool] = None,
     ) -> List[Dict]:
         """Return the `[{name, description, category, status}]` list the
         agent sees in its system prompt.
@@ -710,6 +711,11 @@ class SkillsManager:
             # Platform gating
             if platform and s.get("platforms") and platform not in s["platforms"]:
                 continue
+            # remote-only tag: hide from local/private-endpoint models. Big
+            # on-demand reference lookups overwhelm small local contexts.
+            # local_model=None (API listings, UI) never gates.
+            if local_model and "remote-only" in (s.get("tags") or []):
+                continue
             # requires_toolsets: hide unless every required toolset is active.
             # active_toolsets=None means the caller doesn't know the active
             # set (API listings, chat preface) — don't gate in that case;
diff --git a/src/agent_loop.py b/src/agent_loop.py
index c7d1f179c..c452c6c22 100644
--- a/src/agent_loop.py
+++ b/src/agent_loop.py
@@ -14423,6 +14423,7 @@ def _build_system_prompt(
     suppress_skills: bool = False,
     active_email: Optional[Dict[str, str]] = None,
     workspace: Optional[str] = None,
+    endpoint_url: Optional[str] = None,
     client_runtime_context: Optional[Dict[str, Any]] = None,
     preserve_conversation: bool = False,
 ) -> List[Dict]:
@@ -14524,6 +14525,7 @@ def _build_system_prompt(
             mcp_disabled_map=mcp_disabled_map, compact=compact, owner=owner,
             suppress_local_context=suppress_local_context,
             suppress_skills=suppress_skills,
+            endpoint_url=endpoint_url,
         )
     else:
         agent_prompt, _skill_index_block = _build_base_prompt(
@@ -14536,6 +14538,7 @@ def _build_system_prompt(
             owner=owner,
             suppress_local_context=suppress_local_context,
             suppress_skills=suppress_skills,
+            endpoint_url=endpoint_url,
         )
         if not active_document:
             _cached_base_prompt = agent_prompt
@@ -15214,6 +15217,7 @@ def _build_base_prompt(
     owner: Optional[str] = None,
     suppress_local_context: bool = False,
     suppress_skills: bool = False,
+    endpoint_url: Optional[str] = None,
 ):
     """Build the agent prompt with only relevant tools included.
 
@@ -15272,7 +15276,11 @@ def _build_base_prompt(
             from src.constants import DATA_DIR
             _sm = SkillsManager(DATA_DIR)
             active_tools = list(set(TOOL_SECTIONS.keys()) - set(disabled or []))
-            skill_idx = _sm.index_for(owner=owner, active_toolsets=active_tools)
+            skill_idx = _sm.index_for(
+                owner=owner,
+                active_toolsets=active_tools,
+                local_model=bool(endpoint_url) and is_local_endpoint(endpoint_url),
+            )
             if skill_idx:
                 lines = ["## Available skills",
                          "Procedures the assistant should consult before doing domain work. "
@@ -24303,6 +24311,7 @@ async def stream_agent_loop(
                 active_email=active_email,
                 workspace=workspace,
                 client_runtime_context=client_runtime_context,
+                endpoint_url=candidate_url,
             )
         # The request user turn is authoritative and must never disappear
         # while rebuilding the route prompt.  Some native terminal requests
diff --git a/tests/test_skill_index_local_model_gating.py b/tests/test_skill_index_local_model_gating.py
new file mode 100644
index 000000000..d84a48c2e
--- /dev/null
+++ b/tests/test_skill_index_local_model_gating.py
@@ -0,0 +1,98 @@
+"""index_for() local-model gating: a `remote-only` tag must hide a skill
+from local/private-endpoint models while staying visible to remote API
+models and to callers that don't know the endpoint at all.
+
+Big on-demand reference lookups overwhelm small local contexts, so the
+skill must vanish from the injected index there. local_model=None (API
+listings, chat preface) means "don't gate" — same contract as
+active_toolsets=None.
+"""
+
+import sys
+from pathlib import Path
+from unittest.mock import MagicMock
+
+# ── module-load stubbing (matches other tests in this repo) ──────────
+for _mod in ("sqlalchemy", "sqlalchemy.orm", "sqlalchemy.ext", "sqlalchemy.ext.declarative"):
+    if _mod not in sys.modules:
+        try:
+            __import__(_mod)
+        except ImportError:
+            sys.modules[_mod] = MagicMock()
+
+from services.memory.skills import SkillsManager  # noqa: E402
+
+
+def _write_skill_md(skills_root: Path, name: str, *, tags: str = "[]",
+                    owner: str = "admin") -> None:
+    skill_dir = skills_root / "general" / name
+    skill_dir.mkdir(parents=True, exist_ok=True)
+    fm = "\n".join([
+        "---",
+        f"name: {name}",
+        "description: test skill",
+        "version: 1.0.0",
+        "category: general",
+        f"tags: [{tags}]",
+        "status: published",
+        "confidence: 0.9",
+        "audit_verdict: pass",
+        "source: learned",
+        f"owner: {owner}",
+        "created: 2026-01-01T00:00:00Z",
+        "---",
+        "",
+        "## When to Use",
+        "- test",
+        "",
+        "## Procedure",
+        "1. step 1",
+        "",
+    ])
+    (skill_dir / "SKILL.md").write_text(fm, encoding="utf-8")
+
+
+def _names(idx):
+    return {s["name"] for s in idx}
+
+
+def test_remote_only_hidden_from_local_model(tmp_path):
+    (tmp_path / "skills").mkdir()
+    _write_skill_md(tmp_path / "skills", "agents-map", tags="reference, remote-only")
+    sm = SkillsManager(str(tmp_path))
+    sm.set_audit("agents-map", "pass", owner="admin")
+
+    assert "agents-map" not in _names(
+        sm.index_for(owner="admin", local_model=True))
+
+
+def test_remote_only_visible_to_remote_model_and_unknown_endpoint(tmp_path):
+    (tmp_path / "skills").mkdir()
+    _write_skill_md(tmp_path / "skills", "agents-map", tags="reference, remote-only")
+    sm = SkillsManager(str(tmp_path))
+    sm.set_audit("agents-map", "pass", owner="admin")
+
+    assert "agents-map" in _names(sm.index_for(owner="admin", local_model=False))
+    # Unknown endpoint (background callers without a URL) fails open.
+    assert "agents-map" in _names(sm.index_for(owner="admin", local_model=None))
+    assert "agents-map" in _names(sm.index_for(owner="admin"))
+
+
+def test_untagged_skills_are_never_gated(tmp_path):
+    (tmp_path / "skills").mkdir()
+    _write_skill_md(tmp_path / "skills", "plain-skill", tags="reference")
+    sm = SkillsManager(str(tmp_path))
+    sm.set_audit("plain-skill", "pass", owner="admin")
+
+    assert "plain-skill" in _names(sm.index_for(owner="admin", local_model=True))
+    assert "plain-skill" in _names(sm.index_for(owner="admin", local_model=False))
+
+
+def test_tag_in_ui_listings_is_not_gated(tmp_path):
+    (tmp_path / "skills").mkdir()
+    _write_skill_md(tmp_path / "skills", "agents-map", tags="reference, remote-only")
+    sm = SkillsManager(str(tmp_path))
+    sm.set_audit("agents-map", "pass", owner="admin")
+
+    # API listings / UI pass no local_model → must still see the skill.
+    assert "agents-map" in _names(sm.index_for(owner="admin", local_model=None))

From c23b1be3f8b2c30064ec133664d8f9eb6bb1b748 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Robert=20Vind-Gardo=C8=99?=
 <41092915+robyroro@users.noreply.github.com>
Date: Wed, 14 Oct 2026 10:41:38 +0300
Subject: [PATCH 11/53] fix(history): reject implicit and coerced truncation
 targets (#6565)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* fix(history): reject implicit and coerced truncation targets

* fix(history): reject falsy non-string message IDs; drop redundant keep_count guard

The or-chain used to resolve before_msg_id / message_id evaluated
falsy non-strings (False, 0) to '' before the isinstance(…, str) check
was reached, so they silently bypassed type validation.  Replace the
chain with explicit presence-aware logic that falls through on None or
empty string (preserving alias semantics) but rejects any other
non-string value with HTTP 400.

Also remove the now-tautological 'if keep_count >= 0:' guard, which
is always True after the negativity check introduced in the parent
commit.  The DB block is unconditional and indented accordingly.

Tests: add {'before_msg_id': False}, {'before_msg_id': 0},
{'message_id': 0} to the parametrised rejection suite.

36 passed, 0 failed (Python 3.14.4 / pytest 9.1.1).

---------

Co-authored-by: Alexandre Teixeira <111787685+alteixeira20@users.noreply.github.com>
---
 routes/history/history_routes.py          | 65 ++++++++++-----
 tests/test_history_truncate_validation.py | 98 +++++++++++++++++++++++
 2 files changed, 144 insertions(+), 19 deletions(-)
 create mode 100644 tests/test_history_truncate_validation.py

diff --git a/routes/history/history_routes.py b/routes/history/history_routes.py
index 0900a0931..a14be5908 100644
--- a/routes/history/history_routes.py
+++ b/routes/history/history_routes.py
@@ -403,26 +403,53 @@ def setup_history_routes(session_manager, upload_handler=None) -> APIRouter:
     async def truncate_session(request: Request, session_id: str):
         _verify_session_owner(request, session_id)
         try:
-            body = await request.json()
-            keep_count = int(body.get("keep_count", 0))
-            before_msg_id = str(body.get("before_msg_id") or body.get("message_id") or "").strip()
+            try:
+                body = await request.json()
+            except json.JSONDecodeError:
+                raise HTTPException(400, "Request body must be valid JSON")
+            if not isinstance(body, dict):
+                raise HTTPException(400, "Request body must be a JSON object")
+            # Resolve before_msg_id / message_id alias with explicit presence checks.
+            # None (JSON null) and empty string are both treated as "not provided here"
+            # and fall through to the alias, preserving the original OR-chain semantics.
+            # Any other non-string value (False, 0, True, 123, list, …) is rejected
+            # immediately so falsy non-strings cannot bypass type validation.
+            raw_msg_id = body.get("before_msg_id") if "before_msg_id" in body else None
+            if raw_msg_id is None or raw_msg_id == "":
+                raw_msg_id = body.get("message_id")
+            if raw_msg_id is not None and not isinstance(raw_msg_id, str):
+                raise HTTPException(400, "Message ID must be a string")
+            before_msg_id = (raw_msg_id or "").strip()
+            if "keep_count" not in body and not before_msg_id:
+                raise HTTPException(400, "keep_count or before_msg_id required")
+            raw_count = body.get("keep_count", 0)
+            # Keep integer-string clients working, but do not silently convert
+            # booleans or fractional numbers into destructive message counts.
+            if type(raw_count) not in (int, str):
+                raise HTTPException(400, "keep_count must be a non-negative integer")
+            try:
+                keep_count = int(raw_count)
+            except ValueError:
+                raise HTTPException(400, "keep_count must be a non-negative integer")
+            if keep_count < 0:
+                raise HTTPException(400, "keep_count must be a non-negative integer")
             deleted_sft_pairs: list[dict[str, str]] = []
-            if keep_count >= 0:
-                db = SessionLocal()
-                try:
-                    all_db_messages = db.query(DbChatMessage).filter(
-                        DbChatMessage.session_id == session_id
-                    ).order_by(DbChatMessage.timestamp).all()
-                    if before_msg_id:
-                        resolved_keep_count = _keep_count_before_message(all_db_messages, before_msg_id)
-                        if resolved_keep_count is None:
-                            raise HTTPException(404, "Message not found")
-                        keep_count = resolved_keep_count
-                    for pos, row in enumerate(all_db_messages):
-                        row._will_delete_for_sft = pos >= keep_count
-                    deleted_sft_pairs = _deleted_sft_pairs_from_db_rows(all_db_messages)
-                finally:
-                    db.close()
+            # keep_count is always >= 0 here; the block is unconditional.
+            db = SessionLocal()
+            try:
+                all_db_messages = db.query(DbChatMessage).filter(
+                    DbChatMessage.session_id == session_id
+                ).order_by(DbChatMessage.timestamp).all()
+                if before_msg_id:
+                    resolved_keep_count = _keep_count_before_message(all_db_messages, before_msg_id)
+                    if resolved_keep_count is None:
+                        raise HTTPException(404, "Message not found")
+                    keep_count = resolved_keep_count
+                for pos, row in enumerate(all_db_messages):
+                    row._will_delete_for_sft = pos >= keep_count
+                deleted_sft_pairs = _deleted_sft_pairs_from_db_rows(all_db_messages)
+            finally:
+                db.close()
             result = session_manager.truncate_messages(session_id, keep_count)
             _remove_deleted_sft_trace_rows(
                 owner=effective_user(request),
diff --git a/tests/test_history_truncate_validation.py b/tests/test_history_truncate_validation.py
new file mode 100644
index 000000000..9772037db
--- /dev/null
+++ b/tests/test_history_truncate_validation.py
@@ -0,0 +1,98 @@
+"""Invalid truncation requests must leave saved chat history intact."""
+from types import SimpleNamespace
+
+import pytest
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+
+from tests.helpers.database import isolated_session_database
+
+
+@pytest.fixture
+def history_client(tmp_path, monkeypatch):
+    from core.models import ChatMessage
+    from routes.history import history_routes
+    from routes import session_routes
+
+    with isolated_session_database(tmp_path) as (manager, database):
+        monkeypatch.setattr(history_routes, "SessionLocal", database.SessionLocal)
+        monkeypatch.setattr(session_routes, "SessionLocal", database.SessionLocal)
+        monkeypatch.setenv("AUTH_ENABLED", "true")
+        manager.create_session("truncate-test", "Test", "http://example.test", "test", owner="alice")
+        for text in ("first", "second", "third"):
+            manager.add_message("truncate-test", ChatMessage("user", text))
+        app = FastAPI()
+        app.state.auth_manager = SimpleNamespace(is_configured=True)
+
+        @app.middleware("http")
+        async def owner(request, call_next):
+            request.state.current_user = request.headers.get("X-Test-Owner", "alice")
+            return await call_next(request)
+
+        app.include_router(history_routes.setup_history_routes(manager))
+        with TestClient(app, raise_server_exceptions=False) as client:
+            yield client, manager, database
+
+
+def saved_messages(database):
+    with database.SessionLocal() as db:
+        return [row.content for row in db.query(database.ChatMessage).filter(
+            database.ChatMessage.session_id == "truncate-test"
+        ).order_by(database.ChatMessage.timestamp).all()]
+
+
+@pytest.mark.parametrize("payload", [
+    {}, {"unrelated": 1}, {"before_msg_id": ""},
+    {"keep_count": None}, {"keep_count": False}, {"keep_count": True},
+    {"keep_count": 1.9}, {"keep_count": -1}, {"keep_count": "bad"},
+    {"keep_count": []}, {"keep_count": {}},
+    {"before_msg_id": True}, {"before_msg_id": ["message"]},
+    {"before_msg_id": False}, {"before_msg_id": 0}, {"message_id": 0},
+    [], None, "two", 2, False,
+])
+def test_invalid_target_preserves_history(history_client, payload):
+    client, manager, database = history_client
+    import json
+    response = client.post("/api/session/truncate-test/truncate", content=json.dumps(payload), headers={"Content-Type": "application/json"})
+    assert response.status_code == 400, response.text
+    assert saved_messages(database) == ["first", "second", "third"]
+    assert [m.content for m in manager.get_session("truncate-test").history] == ["first", "second", "third"]
+
+
+def test_malformed_json_preserves_history(history_client):
+    client, _, database = history_client
+    response = client.post("/api/session/truncate-test/truncate", content="{", headers={"Content-Type": "application/json"})
+    assert response.status_code == 400, response.text
+    assert saved_messages(database) == ["first", "second", "third"]
+
+
+@pytest.mark.parametrize("count,expected", [(0, []), (2, ["first", "second"]), (9, ["first", "second", "third"]), ("2", ["first", "second"])])
+def test_explicit_count_remains_supported(history_client, count, expected):
+    client, _, database = history_client
+    response = client.post("/api/session/truncate-test/truncate", json={"keep_count": count})
+    assert response.status_code == 200, response.text
+    assert saved_messages(database) == expected
+
+
+@pytest.mark.parametrize("field", ["before_msg_id", "message_id"])
+def test_message_id_boundary_remains_supported(history_client, field):
+    client, _, database = history_client
+    with database.SessionLocal() as db:
+        message_id = db.query(database.ChatMessage).filter(database.ChatMessage.content == "second").one().id
+    response = client.post("/api/session/truncate-test/truncate", json={field: message_id})
+    assert response.status_code == 200, response.text
+    assert saved_messages(database) == ["first"]
+
+
+def test_missing_message_id_does_not_clear_history(history_client):
+    client, _, database = history_client
+    response = client.post("/api/session/truncate-test/truncate", json={"before_msg_id": "missing"})
+    assert response.status_code == 404
+    assert saved_messages(database) == ["first", "second", "third"]
+
+
+def test_owner_gate_still_precedes_validation(history_client):
+    client, _, database = history_client
+    response = client.post("/api/session/truncate-test/truncate", json={}, headers={"X-Test-Owner": "bob"})
+    assert response.status_code == 404
+    assert saved_messages(database) == ["first", "second", "third"]

From 0c56527d124d2356f622f2e3f651417a9c76349f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Robert=20Vind-Gardo=C8=99?=
 <41092915+robyroro@users.noreply.github.com>
Date: Wed, 14 Oct 2026 11:01:42 +0300
Subject: [PATCH 12/53] fix(email): preserve mail when bulk Trash moves fail
 (#6633)

* fix(email): preserve mail when bulk Trash moves fail

* fix(email): selective UID EXPUNGE and safe bulk delete cache invalidation

* fix(email): eliminate mailbox-wide EXPUNGE TOCTOU race

- Strictly prohibit mailbox-wide EXPUNGE in bulk email deletion fallback
- Restrict cleanup exclusively to selective RFC 4315 UID EXPUNGE <set>
- Track and preserve pre-existing \Deleted flags if selective expunge fails
- Retain local index records and preserve source emails when cleanup fails
- Ensure consistent partial-failure error semantics across all failure modes
- Add comprehensive hermetic tests for concurrent clients, missing UIDPLUS,
  disconnects after COPY/STORE/EXPUNGE, and retry safety

---------

Co-authored-by: PR #6166 Reviewer <reviewer@odysseus-review.local>
---
 routes/email/email_routes.py           | 107 +++++-
 tests/test_email_bulk_delete_safety.py | 509 +++++++++++++++++++++++++
 2 files changed, 597 insertions(+), 19 deletions(-)
 create mode 100644 tests/test_email_bulk_delete_safety.py

diff --git a/routes/email/email_routes.py b/routes/email/email_routes.py
index fd6bd2747..172790a6c 100644
--- a/routes/email/email_routes.py
+++ b/routes/email/email_routes.py
@@ -81,6 +81,7 @@ _SERVER_OWNED_OAUTH_FIELDS = {
     "oauth_refresh_token",
     "oauth_token_expiry",
 }
+_CACHE_HOOKS: dict = {"invalidate_list": None}
 
 
 def _normalized_mail_host(value) -> str:
@@ -572,6 +573,23 @@ def _uid_exists(conn, uid: str, *, strict: bool = False) -> bool:
         return False
 
 
+def _uid_has_deleted_flag(conn, uid: str) -> bool:
+    r"""Return True if message already carries \Deleted flag."""
+    try:
+        status, data = conn.uid("FETCH", _uid_bytes(uid), "(FLAGS)")
+        if status == "OK" and data:
+            for part in data:
+                if not part:
+                    continue
+                meta = part[0] if isinstance(part, tuple) else part
+                meta_b = meta if isinstance(meta, bytes) else str(meta).encode()
+                if rb"\Deleted" in meta_b:
+                    return True
+    except Exception:
+        pass
+    return False
+
+
 def _resolve_current_email_uid(conn, uid: str, message_id: str | None = None) -> str:
     """Resolve a stale cached UID by the message's stable RFC Message-ID."""
     uid = str(uid or "").strip()
@@ -1831,6 +1849,12 @@ def setup_email_routes():
         delete, move) so the UI doesn't show stale read/unread counts for up to
         the 8s TTL after a manual flag change. With no args, clears everything.
         """
+        hook = _CACHE_HOOKS.get("invalidate_list")
+        if hook:
+            try:
+                hook(account_id, folder)
+            except Exception:
+                pass
         if account_id is None and folder is None:
             _LIST_CACHE.clear()
             return
@@ -4764,6 +4788,7 @@ def setup_email_routes():
             return {"success": False, "error": "No email UIDs provided", "deleted_uids": [], "failed_uids": []}
         deleted_uids = []
         failed_uids = []
+        trash_folder = None
         try:
             with _imap(account_id, owner=owner) as conn:
                 select_status, _ = conn.select(_q(folder), readonly=False)
@@ -4779,7 +4804,8 @@ def setup_email_routes():
                             trash_folder = "Trash"
                     except Exception:
                         pass
-                pending_expunge = False
+                pending_expunge = []
+                preexisting_deleted = set()
                 for uid in uids:
                     try:
                         if not _uid_exists(conn, uid):
@@ -4789,32 +4815,75 @@ def setup_email_routes():
                         if status != "OK":
                             copy_status, _ = conn.uid("COPY", _uid_bytes(uid), _q(trash_folder))
                             if copy_status != "OK":
-                                # Keep deletion reliable even when this IMAP
-                                # server has no writable Trash folder.
-                                store_status, _ = conn.uid("STORE", _uid_bytes(uid), "+FLAGS", "\\Deleted")
-                                if store_status != "OK":
-                                    failed_uids.append(uid)
-                                    continue
-                                pending_expunge = True
-                            else:
-                                store_status, _ = conn.uid("STORE", _uid_bytes(uid), "+FLAGS", "\\Deleted")
-                                if store_status != "OK":
-                                    failed_uids.append(uid)
-                                    continue
-                                pending_expunge = True
+                                # Bulk Delete means move to Trash. Never remove
+                                # the original without a recoverable Trash copy.
+                                failed_uids.append(uid)
+                                continue
+                            if _uid_has_deleted_flag(conn, uid):
+                                preexisting_deleted.add(uid)
+                            store_status, _ = conn.uid("STORE", _uid_bytes(uid), "+FLAGS", "\\Deleted")
+                            if store_status != "OK":
+                                failed_uids.append(uid)
+                                continue
+                            # Keep the local index until the server confirms
+                            # that the copied originals have been removed.
+                            pending_expunge.append(uid)
+                            continue
                         deleted_uids.append(uid)
                         _email_index_delete(owner, account_id, folder, uid)
                     except Exception:
                         failed_uids.append(uid)
                         logger.debug("Bulk email delete failed for uid=%s", uid, exc_info=True)
                 if pending_expunge:
-                    conn.expunge()
-            if deleted_uids:
-                _invalidate_list_cache(account_id, folder)
-            return {"success": True, "deleted_uids": deleted_uids, "failed_uids": failed_uids}
+                    expunge_ok = False
+                    # Attempt selective RFC 4315 UID EXPUNGE so unrelated messages
+                    # carrying \Deleted in the selected mailbox are never expunged.
+                    # Mailbox-wide EXPUNGE is strictly avoided to eliminate TOCTOU races
+                    # where concurrent clients mark unrelated messages \Deleted.
+                    try:
+                        uid_set_bytes = _uid_bytes(",".join(pending_expunge))
+                        uid_exp_status, _ = conn.uid("EXPUNGE", uid_set_bytes)
+                        if uid_exp_status == "OK":
+                            expunge_ok = True
+                    except Exception:
+                        logger.debug("Selective UID EXPUNGE failed", exc_info=True)
+                        expunge_ok = False
+
+                    if expunge_ok:
+                        for uid in pending_expunge:
+                            deleted_uids.append(uid)
+                            _email_index_delete(owner, account_id, folder, uid)
+                    else:
+                        # Prioritize preservation over cleanup: unflag \Deleted from our
+                        # copied messages so future EXPUNGE operations do not destroy them.
+                        # Do not remove a pre-existing \Deleted flag present before this operation.
+                        for uid in pending_expunge:
+                            if uid not in preexisting_deleted:
+                                try:
+                                    conn.uid("STORE", _uid_bytes(uid), "-FLAGS", "\\Deleted")
+                                except Exception:
+                                    pass
+                        failed_uids.extend(pending_expunge)
+            if not deleted_uids:
+                return {"success": False, "error": "Failed to delete requested emails", "deleted_uids": [], "failed_uids": failed_uids}
+            res = {"success": True, "deleted_uids": deleted_uids, "failed_uids": failed_uids}
+            if failed_uids:
+                res["error"] = "Mail operation partially failed"
+            return res
         except Exception as e:
             logger.error(f"Failed to bulk delete emails: {e}")
-            return {"success": False, "error": "Mail operation failed", "deleted_uids": deleted_uids, "failed_uids": [u for u in uids if u not in deleted_uids]}
+            failed_all = [u for u in uids if u not in deleted_uids]
+            return {
+                "success": bool(deleted_uids),
+                "error": "Mail operation failed" if not deleted_uids else "Mail operation partially failed",
+                "deleted_uids": deleted_uids,
+                "failed_uids": failed_all,
+            }
+        finally:
+            if deleted_uids:
+                _invalidate_list_cache(account_id, folder)
+                if trash_folder:
+                    _invalidate_list_cache(account_id, trash_folder)
 
     @router.delete("/odysseus/reminders")
     async def delete_odysseus_reminder_emails(
diff --git a/tests/test_email_bulk_delete_safety.py b/tests/test_email_bulk_delete_safety.py
new file mode 100644
index 000000000..b903c8e97
--- /dev/null
+++ b/tests/test_email_bulk_delete_safety.py
@@ -0,0 +1,509 @@
+"""Bulk Delete must retain messages that could not be moved to Trash."""
+
+from contextlib import contextmanager
+from types import SimpleNamespace
+from unittest.mock import Mock
+
+import pytest
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+
+
+class Mailbox:
+    def __init__(self):
+        self.inbox = {"101", "102", "103"}
+        self.trash = set()
+        self.deleted = set()
+        self.calls = []
+        self.move_status = "NO"
+        self.copy_status = {}
+        self.store_status = {}
+        self.expunge_status = "OK"
+        self.uid_expunge_status = None
+        self.select_status = "OK"
+
+    def select(self, folder, readonly=False):
+        return self.select_status, [b"3"]
+
+    def uid(self, command, raw_uid, *args):
+        uid = raw_uid.decode() if isinstance(raw_uid, bytes) else (str(raw_uid) if raw_uid is not None else "")
+        self.calls.append((command, uid))
+        if command == "FETCH":
+            if uid not in self.inbox:
+                return "OK", []
+            if args and "(FLAGS)" in args:
+                flags = rb"(\Deleted)" if uid in self.deleted else rb"()"
+                return "OK", [(f"1 (UID {uid} FLAGS ".encode() + flags + b")")]
+            return "OK", [f"1 (UID {uid})".encode()]
+        if command == "SEARCH":
+            if args and "DELETED" in args:
+                return "OK", [b" ".join(u.encode() for u in sorted(self.deleted))]
+            searched_uid = args[-1].split()[-1] if args else ""
+            return "OK", [searched_uid.encode() if searched_uid in self.inbox else b""]
+        if command == "MOVE":
+            status = self.move_status.get(uid, "NO") if isinstance(self.move_status, dict) else self.move_status
+            if isinstance(status, Exception):
+                raise status
+            if status == "OK":
+                self.trash.add(uid)
+                self.inbox.remove(uid)
+            return status, []
+        if command == "COPY":
+            status = self.copy_status.get(uid, "OK")
+            if isinstance(status, Exception):
+                raise status
+            if status == "OK":
+                self.trash.add(uid)
+            return status, []
+        if command == "STORE":
+            status = self.store_status.get(uid, "OK")
+            if isinstance(status, Exception):
+                raise status
+            if status == "OK":
+                if args and args[0] == "-FLAGS":
+                    self.deleted.discard(uid)
+                else:
+                    self.deleted.add(uid)
+            return status, []
+        if command == "EXPUNGE":
+            status = self.uid_expunge_status if self.uid_expunge_status is not None else self.expunge_status
+            if isinstance(status, Exception):
+                raise status
+            if status == "OK":
+                expunged = {u for u in uid.split(",") if u in self.deleted}
+                self.inbox.difference_update(expunged)
+                self.deleted.difference_update(expunged)
+            return status, []
+        raise AssertionError(f"Unexpected IMAP command: {command}")
+
+    def expunge(self):
+        self.calls.append(("EXPUNGE", None))
+        if isinstance(self.expunge_status, Exception):
+            raise self.expunge_status
+        if self.expunge_status == "OK":
+            self.inbox.difference_update(self.deleted)
+            self.deleted.clear()
+        return self.expunge_status, []
+
+
+@pytest.fixture
+def bulk_delete(monkeypatch):
+    from routes.email import email_routes as routes
+
+    mailbox = Mailbox()
+    index_delete = Mock()
+    invalidate_cache = Mock()
+
+    @contextmanager
+    def imap(account_id=None, owner=""):
+        assert owner == "alice"
+        yield mailbox
+
+    monkeypatch.setattr(routes, "_start_poller", lambda: None)
+    monkeypatch.setattr(routes, "_POOL_HOOKS", {})
+    monkeypatch.setattr(routes, "_imap", imap)
+    monkeypatch.setattr(routes, "_resolve_mail_folder", lambda *args: "Trash")
+    monkeypatch.setattr(routes, "_list_imap_folders", lambda conn: ({}, ["INBOX", "Trash"]))
+    monkeypatch.setattr(routes, "_email_index_delete", index_delete)
+    monkeypatch.setitem(routes._CACHE_HOOKS, "invalidate_list", invalidate_cache)
+    app = FastAPI()
+    app.include_router(routes.setup_email_routes())
+    app.dependency_overrides[routes.require_owner] = lambda: "alice"
+
+    with TestClient(app) as client:
+        def delete(uids):
+            response = client.post("/api/email/delete-bulk", json={"uids": uids})
+            assert response.status_code == 200
+            return response.json()
+
+        yield SimpleNamespace(
+            mailbox=mailbox,
+            delete=delete,
+            index_delete=index_delete,
+            invalidate_cache=invalidate_cache,
+            routes=routes,
+        )
+
+
+@pytest.mark.parametrize("copy_status", ["NO", "BAD"])
+def test_failed_trash_copy_preserves_original(bulk_delete, copy_status):
+    bulk_delete.mailbox.copy_status["101"] = copy_status
+
+    result = bulk_delete.delete(["101"])
+
+    assert "101" in bulk_delete.mailbox.inbox
+    assert bulk_delete.mailbox.deleted == set()
+    assert result["deleted_uids"] == []
+    assert result["failed_uids"] == ["101"]
+    assert ("STORE", "101") not in bulk_delete.mailbox.calls
+    assert ("EXPUNGE", None) not in bulk_delete.mailbox.calls
+    bulk_delete.index_delete.assert_not_called()
+
+
+def test_mixed_batch_only_deletes_messages_copied_to_trash(bulk_delete):
+    bulk_delete.mailbox.copy_status["102"] = "NO"
+
+    result = bulk_delete.delete(["101", "102", "103"])
+
+    assert bulk_delete.mailbox.inbox == {"102"}
+    assert bulk_delete.mailbox.trash == {"101", "103"}
+    assert result["deleted_uids"] == ["101", "103"]
+    assert result["failed_uids"] == ["102"]
+    assert [call.args[-1] for call in bulk_delete.index_delete.call_args_list] == ["101", "103"]
+
+
+@pytest.mark.parametrize("expunge_status", ["NO", "BAD", RuntimeError("Disconnected")])
+def test_failed_expunge_keeps_index_and_reports_failure(bulk_delete, expunge_status):
+    bulk_delete.mailbox.expunge_status = expunge_status
+
+    result = bulk_delete.delete(["101", "102"])
+
+    assert bulk_delete.mailbox.inbox == {"101", "102", "103"}
+    assert bulk_delete.mailbox.trash == {"101", "102"}
+    assert result["deleted_uids"] == []
+    assert result["failed_uids"] == ["101", "102"]
+    bulk_delete.index_delete.assert_not_called()
+
+
+def test_store_failure_retains_original_and_index(bulk_delete):
+    bulk_delete.mailbox.store_status["101"] = "NO"
+
+    result = bulk_delete.delete(["101"])
+
+    assert "101" in bulk_delete.mailbox.inbox
+    assert bulk_delete.mailbox.trash == {"101"}
+    assert result["failed_uids"] == ["101"]
+    assert result["deleted_uids"] == []
+    assert ("EXPUNGE", None) not in bulk_delete.mailbox.calls
+    bulk_delete.index_delete.assert_not_called()
+
+
+def test_native_move_needs_no_copy_or_expunge(bulk_delete):
+    bulk_delete.mailbox.move_status = "OK"
+
+    result = bulk_delete.delete(["101", "102"])
+
+    assert result["deleted_uids"] == ["101", "102"]
+    assert result["failed_uids"] == []
+    assert bulk_delete.mailbox.inbox == {"103"}
+    assert bulk_delete.mailbox.trash == {"101", "102"}
+    assert not any(command in {"COPY", "STORE", "EXPUNGE"} for command, _ in bulk_delete.mailbox.calls)
+
+
+def test_copy_fallback_expunge_runs_once_for_the_batch(bulk_delete):
+    result = bulk_delete.delete(["101", "102"])
+
+    assert result["deleted_uids"] == ["101", "102"]
+    assert result["failed_uids"] == []
+    assert bulk_delete.mailbox.inbox == {"103"}
+    assert bulk_delete.mailbox.trash == {"101", "102"}
+    assert sum(1 for command, _ in bulk_delete.mailbox.calls if command == "EXPUNGE") == 1
+    assert bulk_delete.index_delete.call_count == 2
+
+
+def test_failed_folder_selection_never_changes_messages(bulk_delete):
+    bulk_delete.mailbox.select_status = "NO"
+
+    result = bulk_delete.delete(["101"])
+
+    assert result["success"] is False
+    assert result["failed_uids"] == ["101"]
+    assert bulk_delete.mailbox.calls == []
+    bulk_delete.index_delete.assert_not_called()
+
+
+@pytest.mark.parametrize("expunge_status", ["NO", RuntimeError("Disconnected")])
+def test_completed_native_move_is_retained_when_fallback_expunge_fails(bulk_delete, expunge_status):
+    bulk_delete.mailbox.move_status = {"101": "OK"}
+    bulk_delete.mailbox.expunge_status = expunge_status
+
+    result = bulk_delete.delete(["101", "102"])
+
+    assert result["deleted_uids"] == ["101"]
+    assert result["failed_uids"] == ["102"]
+    assert bulk_delete.mailbox.inbox == {"102", "103"}
+    assert bulk_delete.mailbox.trash == {"101", "102"}
+    bulk_delete.index_delete.assert_called_once_with("alice", None, "INBOX", "101")
+
+
+def test_absent_uid_is_reported_failed_without_deleting_another_message(bulk_delete):
+    result = bulk_delete.delete(["999"])
+
+    assert result["deleted_uids"] == []
+    assert result["failed_uids"] == ["999"]
+    assert bulk_delete.mailbox.inbox == {"101", "102", "103"}
+    assert bulk_delete.mailbox.trash == set()
+    assert not any(command in {"MOVE", "COPY", "STORE", "EXPUNGE"} for command, _ in bulk_delete.mailbox.calls)
+    bulk_delete.index_delete.assert_not_called()
+
+
+def test_duplicate_and_invalid_uids_do_not_repeat_mail_operations(bulk_delete):
+    result = bulk_delete.delete(["101", "101", "", None, "invalid"])
+
+    assert result["deleted_uids"] == ["101"]
+    assert result["failed_uids"] == []
+    assert bulk_delete.mailbox.calls.count(("COPY", "101")) == 1
+    bulk_delete.index_delete.assert_called_once_with("alice", None, "INBOX", "101")
+
+
+def test_bulk_delete_invalidates_source_and_trash_caches(bulk_delete):
+    result = bulk_delete.delete(["101"])
+
+    assert result["success"] is True
+    assert result["deleted_uids"] == ["101"]
+    bulk_delete.invalidate_cache.assert_any_call(None, "INBOX")
+    bulk_delete.invalidate_cache.assert_any_call(None, "Trash")
+
+
+def test_partial_failure_with_exception_invalidates_caches(bulk_delete):
+    bulk_delete.mailbox.move_status = {"101": "OK"}
+    bulk_delete.mailbox.uid_expunge_status = RuntimeError("Socket reset during expunge")
+    bulk_delete.mailbox.expunge_status = RuntimeError("Socket reset during expunge")
+
+    result = bulk_delete.delete(["101", "102"])
+
+    assert result["success"] is True
+    assert result["deleted_uids"] == ["101"]
+    assert result["failed_uids"] == ["102"]
+    assert result["error"] == "Mail operation partially failed"
+    bulk_delete.invalidate_cache.assert_any_call(None, "INBOX")
+    bulk_delete.invalidate_cache.assert_any_call(None, "Trash")
+
+
+def test_total_failure_returns_success_false(bulk_delete):
+    bulk_delete.mailbox.copy_status["101"] = "NO"
+
+    result = bulk_delete.delete(["101"])
+
+    assert result["success"] is False
+    assert result["error"] == "Failed to delete requested emails"
+    assert result["deleted_uids"] == []
+    assert result["failed_uids"] == ["101"]
+
+
+def test_uid_expunge_preserves_unrelated_deleted_message(bulk_delete):
+    # Unrelated message 999 is already marked \Deleted before bulk delete
+    bulk_delete.mailbox.inbox.add("999")
+    bulk_delete.mailbox.deleted.add("999")
+
+    result = bulk_delete.delete(["101"])
+
+    assert result["success"] is True
+    assert result["deleted_uids"] == ["101"]
+    # 101 was expunged, 999 remains in inbox and remains marked deleted
+    assert "101" not in bulk_delete.mailbox.inbox
+    assert "999" in bulk_delete.mailbox.inbox
+    assert bulk_delete.mailbox.deleted == {"999"}
+    assert ("EXPUNGE", "101") in bulk_delete.mailbox.calls
+    assert ("EXPUNGE", None) not in bulk_delete.mailbox.calls
+
+
+def test_server_lacking_uidplus_never_calls_mailbox_expunge(bulk_delete):
+    # Server does not support UIDPLUS (UID EXPUNGE returns BAD)
+    # Even if no other deleted messages exist, mailbox-wide EXPUNGE is strictly forbidden.
+    bulk_delete.mailbox.uid_expunge_status = "BAD"
+    assert bulk_delete.mailbox.deleted == set()
+
+    result = bulk_delete.delete(["101"])
+
+    assert result["success"] is False
+    assert result["deleted_uids"] == []
+    assert result["failed_uids"] == ["101"]
+    assert "101" in bulk_delete.mailbox.inbox
+    assert "101" not in bulk_delete.mailbox.deleted
+    assert ("EXPUNGE", None) not in bulk_delete.mailbox.calls
+    bulk_delete.index_delete.assert_not_called()
+
+
+def test_concurrent_client_marks_unrelated_deleted_message_during_operation(bulk_delete):
+    # Another client marks unrelated UID 999 \Deleted before/during the operation
+    bulk_delete.mailbox.inbox.add("999")
+    bulk_delete.mailbox.deleted.add("999")
+
+    result = bulk_delete.delete(["101"])
+
+    assert result["success"] is True
+    assert result["deleted_uids"] == ["101"]
+    # 101 was expunged, unrelated 999 is NEVER expunged
+    assert "101" not in bulk_delete.mailbox.inbox
+    assert "999" in bulk_delete.mailbox.inbox
+    assert bulk_delete.mailbox.deleted == {"999"}
+    assert ("EXPUNGE", "101") in bulk_delete.mailbox.calls
+    assert ("EXPUNGE", None) not in bulk_delete.mailbox.calls
+
+
+def test_preexisting_deleted_flag_preserved_when_expunge_fails(bulk_delete):
+    # Message 101 already had \Deleted flag before the bulk operation
+    bulk_delete.mailbox.deleted.add("101")
+    bulk_delete.mailbox.uid_expunge_status = "NO"
+
+    result = bulk_delete.delete(["101"])
+
+    assert result["success"] is False
+    assert result["deleted_uids"] == []
+    assert result["failed_uids"] == ["101"]
+    assert "101" in bulk_delete.mailbox.inbox
+    # Pre-existing \Deleted flag must NOT be removed
+    assert "101" in bulk_delete.mailbox.deleted
+    assert ("EXPUNGE", None) not in bulk_delete.mailbox.calls
+    bulk_delete.index_delete.assert_not_called()
+
+
+def test_preexisting_deleted_flag_expunged_on_success(bulk_delete):
+    # Message 101 already had \Deleted flag before the bulk operation
+    bulk_delete.mailbox.deleted.add("101")
+
+    result = bulk_delete.delete(["101"])
+
+    assert result["success"] is True
+    assert result["deleted_uids"] == ["101"]
+    assert "101" not in bulk_delete.mailbox.inbox
+    assert "101" not in bulk_delete.mailbox.deleted
+    assert "101" in bulk_delete.mailbox.trash
+    bulk_delete.index_delete.assert_called_once_with("alice", None, "INBOX", "101")
+
+
+@pytest.mark.parametrize("status", ["NO", "BAD"])
+def test_uid_expunge_status_failures(bulk_delete, status):
+    bulk_delete.mailbox.uid_expunge_status = status
+
+    result = bulk_delete.delete(["101", "102"])
+
+    assert result["success"] is False
+    assert result["deleted_uids"] == []
+    assert result["failed_uids"] == ["101", "102"]
+    assert bulk_delete.mailbox.inbox == {"101", "102", "103"}
+    assert ("EXPUNGE", None) not in bulk_delete.mailbox.calls
+    bulk_delete.index_delete.assert_not_called()
+
+
+def test_uid_expunge_connection_exception_handled_conservatively(bulk_delete):
+    bulk_delete.mailbox.uid_expunge_status = ConnectionResetError("Connection lost during selective expunge")
+
+    result = bulk_delete.delete(["101"])
+
+    assert result["success"] is False
+    assert result["deleted_uids"] == []
+    assert result["failed_uids"] == ["101"]
+    assert "101" in bulk_delete.mailbox.inbox
+    assert ("EXPUNGE", None) not in bulk_delete.mailbox.calls
+    bulk_delete.index_delete.assert_not_called()
+
+
+def test_disconnect_after_copy_before_store_preserves_message(bulk_delete):
+    # COPY succeeds, but STORE raises a disconnect
+    bulk_delete.mailbox.store_status["101"] = ConnectionResetError("Disconnected")
+
+    result = bulk_delete.delete(["101"])
+
+    assert result["success"] is False
+    assert result["deleted_uids"] == []
+    assert result["failed_uids"] == ["101"]
+    assert "101" in bulk_delete.mailbox.inbox
+    assert "101" in bulk_delete.mailbox.trash
+    assert bulk_delete.mailbox.deleted == set()
+    assert ("EXPUNGE", None) not in bulk_delete.mailbox.calls
+    bulk_delete.index_delete.assert_not_called()
+
+
+def test_disconnect_after_store_preserves_messages_and_index(bulk_delete):
+    # COPY and STORE succeed, but UID EXPUNGE disconnects
+    bulk_delete.mailbox.uid_expunge_status = ConnectionResetError("Disconnected during expunge")
+
+    result = bulk_delete.delete(["101"])
+
+    assert result["success"] is False
+    assert result["deleted_uids"] == []
+    assert result["failed_uids"] == ["101"]
+    assert "101" in bulk_delete.mailbox.inbox
+    assert "101" in bulk_delete.mailbox.trash
+    assert ("EXPUNGE", None) not in bulk_delete.mailbox.calls
+    bulk_delete.index_delete.assert_not_called()
+
+
+def test_disconnect_with_partial_move_success(bulk_delete):
+    # 101 succeeds via MOVE, 102 falls back to COPY+STORE and UID EXPUNGE disconnects
+    bulk_delete.mailbox.move_status = {"101": "OK", "102": "NO"}
+    bulk_delete.mailbox.uid_expunge_status = ConnectionResetError("Disconnected during expunge")
+
+    result = bulk_delete.delete(["101", "102"])
+
+    assert result["success"] is True
+    assert result["deleted_uids"] == ["101"]
+    assert result["failed_uids"] == ["102"]
+    assert "101" not in bulk_delete.mailbox.inbox
+    assert "102" in bulk_delete.mailbox.inbox
+    assert ("EXPUNGE", None) not in bulk_delete.mailbox.calls
+    bulk_delete.index_delete.assert_called_once_with("alice", None, "INBOX", "101")
+    bulk_delete.invalidate_cache.assert_any_call(None, "INBOX")
+    bulk_delete.invalidate_cache.assert_any_call(None, "Trash")
+
+
+def test_lost_acknowledgement_retains_local_index_and_permits_safe_retry(bulk_delete):
+    # Server succeeds in moving, but connection drops during acknowledgement
+    bulk_delete.mailbox.uid_expunge_status = OSError("Connection dropped")
+    bulk_delete.mailbox.expunge_status = OSError("Connection dropped")
+
+    result = bulk_delete.delete(["101"])
+
+    assert result["success"] is False
+    assert result["deleted_uids"] == []
+    assert result["failed_uids"] == ["101"]
+    assert ("EXPUNGE", None) not in bulk_delete.mailbox.calls
+    bulk_delete.index_delete.assert_not_called()
+
+    # Retry when server is reconnected and 101 was already moved (absent from source)
+    bulk_delete.mailbox.inbox.discard("101")
+    bulk_delete.mailbox.uid_expunge_status = "OK"
+    bulk_delete.mailbox.expunge_status = "OK"
+
+    retry_result = bulk_delete.delete(["101"])
+    assert retry_result["deleted_uids"] == []
+    assert retry_result["failed_uids"] == ["101"]
+    bulk_delete.index_delete.assert_not_called()
+
+
+def test_repeated_requests_after_partial_failure(bulk_delete):
+    # Initial request: 101 moves, 102 fails copy
+    bulk_delete.mailbox.move_status = {"101": "OK", "102": "NO"}
+    bulk_delete.mailbox.copy_status["102"] = "NO"
+
+    res1 = bulk_delete.delete(["101", "102"])
+    assert res1["deleted_uids"] == ["101"]
+    assert res1["failed_uids"] == ["102"]
+
+    # Retry with failed UID 102 now succeeding via copy
+    bulk_delete.mailbox.copy_status["102"] = "OK"
+    res2 = bulk_delete.delete(["102"])
+    assert res2["deleted_uids"] == ["102"]
+    assert res2["failed_uids"] == []
+
+    assert bulk_delete.mailbox.inbox == {"103"}
+    assert bulk_delete.mailbox.trash == {"101", "102"}
+    assert ("EXPUNGE", None) not in bulk_delete.mailbox.calls
+
+
+def test_unrelated_messages_never_expunged(bulk_delete):
+    # Mailbox contains unrelated 888 (with \Deleted) and 999 (without \Deleted)
+    bulk_delete.mailbox.inbox.update({"888", "999"})
+    bulk_delete.mailbox.deleted.add("888")
+
+    result = bulk_delete.delete(["101"])
+
+    assert result["success"] is True
+    assert result["deleted_uids"] == ["101"]
+    assert "101" not in bulk_delete.mailbox.inbox
+    assert "101" in bulk_delete.mailbox.trash
+    # 888 and 999 are completely untouched in inbox
+    assert "888" in bulk_delete.mailbox.inbox
+    assert "999" in bulk_delete.mailbox.inbox
+    assert "888" in bulk_delete.mailbox.deleted
+    assert "888" not in bulk_delete.mailbox.trash
+    assert "999" not in bulk_delete.mailbox.trash
+    assert ("EXPUNGE", None) not in bulk_delete.mailbox.calls
+
+
+def test_standard_expunge_never_invoked_by_fallback(bulk_delete):
+    # Perform operations under multiple fallback conditions; standard expunge is never called
+    bulk_delete.delete(["101"])
+    assert ("EXPUNGE", None) not in bulk_delete.mailbox.calls

From 353ea007360e818043587bbff5ca5c822102cc75 Mon Sep 17 00:00:00 2001
From: madonix <accounts@martinhenkel.net>
Date: Wed, 14 Oct 2026 10:47:57 +0200
Subject: [PATCH 13/53] fix(auth): honor AUTH_ENABLED=false in admin-gated
 app-config routes (#6029)

* fix(auth): honor AUTH_ENABLED=false in admin-gated app-config routes

With auth explicitly disabled (reverse-proxy deployments) there is no
session user, so the inline admin checks in auth_routes.py returned 403
unconditionally and settings changes were silently lost. The central
require_admin in core/middleware.py already allows this case; the inline
checks did not.

- add _require_admin_user helper mirroring require_admin semantics and
  use it in the app-config routes (settings, features, integrations)
- return unscrubbed settings on GET /settings when auth is disabled
  (the caller is the operator)
- settings.js: check res.ok in saveDefault so a failed save no longer
  reports 'Saved'
- add regression tests

User-management routes keep requiring a real admin identity; they act on
the user store, which is not meaningful with auth disabled.

Fixes #6028

* fix(settings): verify response.ok on save and expand auth regression tests

- Ensure all settings save handlers in settings.js check response.ok before displaying success notifications, preventing false 'Saved' messages on server rejection.
- Add DOM and JS unit tests verifying response.ok checks and error handling across settings handlers.
- Expand tests/test_admin_routes_auth_disabled.py with comprehensive authorization test coverage for AUTH_ENABLED=false and AUTH_ENABLED=true across settings, features, integrations, secret scrubbing, and user management.

---------

Co-authored-by: Alexandre Teixeira <111787685+alteixeira20@users.noreply.github.com>
Co-authored-by: PR #6029 Reviewer <reviewer@odysseus-review.local>
---
 routes/auth_routes.py                      |  50 ++--
 static/js/settings.js                      |   1 +
 tests/test_admin_routes_auth_disabled.py   | 331 +++++++++++++++++++++
 tests/test_settings_save_response_ok_js.py | 120 ++++++++
 4 files changed, 477 insertions(+), 25 deletions(-)
 create mode 100644 tests/test_admin_routes_auth_disabled.py
 create mode 100644 tests/test_settings_save_response_ok_js.py

diff --git a/routes/auth_routes.py b/routes/auth_routes.py
index 69ca3be56..1042437ac 100644
--- a/routes/auth_routes.py
+++ b/routes/auth_routes.py
@@ -15,6 +15,7 @@ from pathlib import Path
 from core.atomic_io import atomic_write_json, atomic_write_text
 from core.auth import AuthManager, RESERVED_USERNAMES, SetAdminResult, TOKEN_TTL
 from src.constants import DEEP_RESEARCH_DIR, MEMORY_FILE, PASSWORD_MIN_LENGTH, SKILLS_DIR
+from src.auth_helpers import _auth_disabled
 from src.rate_limiter import RateLimiter
 from src.settings_scrub import scrub_settings
 from src.settings import (
@@ -129,6 +130,21 @@ def setup_auth_routes(auth_manager: AuthManager) -> APIRouter:
         token = request.cookies.get(SESSION_COOKIE)
         return auth_manager.get_username_for_token(token)
 
+    def _require_admin_user(request: Request) -> Optional[str]:
+        """Resolve the current user, enforcing admin access.
+
+        Honors AUTH_ENABLED=false the same way core.middleware.require_admin
+        does: when the operator has explicitly disabled auth (e.g. behind a
+        reverse proxy that handles login), there is no session user, and
+        admin-gated app configuration must stay reachable.
+        """
+        user = _get_current_user(request)
+        if _auth_disabled():
+            return user
+        if not user or not auth_manager.is_admin(user):
+            raise HTTPException(403, "Admin only")
+        return user
+
     @router.post("/setup")
     async def first_run_setup(body: SetupRequest, request: Request):
         """Create initial admin account. Only works if no accounts exist."""
@@ -718,9 +734,7 @@ def setup_auth_routes(auth_manager: AuthManager) -> APIRouter:
     @router.post("/features")
     async def set_features(request: Request):
         """Admin only: update feature toggles."""
-        user = _get_current_user(request)
-        if not user or not auth_manager.is_admin(user):
-            raise HTTPException(403, "Admin only")
+        _require_admin_user(request)
         body = await request.json()
         current = _load_features()
         for key in current:
@@ -738,16 +752,14 @@ def setup_auth_routes(auth_manager: AuthManager) -> APIRouter:
         for keybinds + TTS prefs, so it stays callable without admin."""
         user = _get_current_user(request)
         settings = without_retired_settings(_load_settings())
-        if user and auth_manager.is_admin(user):
+        if _auth_disabled() or (user and auth_manager.is_admin(user)):
             return settings
         return scrub_settings(settings)
 
     @router.post("/settings")
     async def set_settings(request: Request):
         """Admin only: update app settings."""
-        user = _get_current_user(request)
-        if not user or not auth_manager.is_admin(user):
-            raise HTTPException(403, "Admin only")
+        _require_admin_user(request)
         body = await request.json()
         current = _load_settings()
         # Per-key validation for numeric settings: coerce to int and clamp to a
@@ -780,9 +792,7 @@ def setup_auth_routes(auth_manager: AuthManager) -> APIRouter:
         file: UploadFile = File(...),
     ):
         """Infer the general prose style from one user-supplied document."""
-        user = _get_current_user(request)
-        if not user or not auth_manager.is_admin(user):
-            raise HTTPException(403, "Admin only")
+        user = _require_admin_user(request)
         filename = Path(file.filename or "sample.txt").name
         suffix = Path(filename).suffix.lower()
         allowed = {
@@ -861,9 +871,7 @@ def setup_auth_routes(auth_manager: AuthManager) -> APIRouter:
     @router.get("/integrations")
     async def list_integrations_route(request: Request):
         """List all integrations (admin only, keys masked)."""
-        user = _get_current_user(request)
-        if not user or not auth_manager.is_admin(user):
-            raise HTTPException(403, "Admin only")
+        _require_admin_user(request)
         items = load_integrations()
         # Mask API keys for frontend display
         safe = [mask_integration_secret(item) for item in items]
@@ -877,9 +885,7 @@ def setup_auth_routes(auth_manager: AuthManager) -> APIRouter:
     @router.post("/integrations")
     async def create_integration(request: Request):
         """Create a new integration (admin only)."""
-        user = _get_current_user(request)
-        if not user or not auth_manager.is_admin(user):
-            raise HTTPException(403, "Admin only")
+        _require_admin_user(request)
         body = await request.json()
         item = add_integration(body)
         return {"ok": True, "integration": mask_integration_secret(item)}
@@ -887,9 +893,7 @@ def setup_auth_routes(auth_manager: AuthManager) -> APIRouter:
     @router.put("/integrations/{integration_id}")
     async def update_integration_route(integration_id: str, request: Request):
         """Update an existing integration (admin only)."""
-        user = _get_current_user(request)
-        if not user or not auth_manager.is_admin(user):
-            raise HTTPException(403, "Admin only")
+        _require_admin_user(request)
         body = await request.json()
         item = update_integration(integration_id, body)
         if not item:
@@ -899,9 +903,7 @@ def setup_auth_routes(auth_manager: AuthManager) -> APIRouter:
     @router.delete("/integrations/{integration_id}")
     async def delete_integration_route(integration_id: str, request: Request):
         """Delete an integration (admin only)."""
-        user = _get_current_user(request)
-        if not user or not auth_manager.is_admin(user):
-            raise HTTPException(403, "Admin only")
+        _require_admin_user(request)
         ok = delete_integration(integration_id)
         if not ok:
             raise HTTPException(404, "Integration not found")
@@ -910,9 +912,7 @@ def setup_auth_routes(auth_manager: AuthManager) -> APIRouter:
     @router.post("/integrations/{integration_id}/test")
     async def test_integration_route(integration_id: str, request: Request):
         """Test connectivity to an integration (admin only)."""
-        user = _get_current_user(request)
-        if not user or not auth_manager.is_admin(user):
-            raise HTTPException(403, "Admin only")
+        _require_admin_user(request)
         integ = get_integration(integration_id)
         if not integ:
             raise HTTPException(404, "Integration not found")
diff --git a/static/js/settings.js b/static/js/settings.js
index dffd466c7..b63b28b48 100644
--- a/static/js/settings.js
+++ b/static/js/settings.js
@@ -1676,6 +1676,7 @@ async function initShortcuts() {
       if (uiModule && uiModule.showToast) uiModule.showToast('Shortcut saved');
     } catch (e) {
       console.error('Failed to save keybinds:', e);
+      if (uiModule && uiModule.showToast) uiModule.showToast('Failed to save shortcut');
     }
   }
 
diff --git a/tests/test_admin_routes_auth_disabled.py b/tests/test_admin_routes_auth_disabled.py
new file mode 100644
index 000000000..ae27fe4e6
--- /dev/null
+++ b/tests/test_admin_routes_auth_disabled.py
@@ -0,0 +1,331 @@
+"""Admin-gated app-config routes must honor AUTH_ENABLED=false.
+
+Regression test for the inconsistency between core.middleware.require_admin
+(which allows requests when the operator disabled auth) and the inline admin
+checks in routes/auth_routes.py (which returned 403 unconditionally, so
+settings changes were silently lost behind reverse-proxy auth setups).
+"""
+import pytest
+from core.auth import SetAdminResult
+
+
+class _StoreDict(dict):
+    """Dict-like settings store that also holds features and integrations."""
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.features = {"web_search": True, "web_fetch": True, "memory": True}
+        self.integrations = {
+            "int-1": {
+                "id": "int-1",
+                "name": "miniflux-sync",
+                "preset": "miniflux",
+                "api_key": "sk-secret-key-123",
+                "base_url": "http://127.0.0.1:8080",
+            }
+        }
+
+
+@pytest.fixture
+def client(tmp_path, monkeypatch):
+    fastapi = pytest.importorskip("fastapi")
+    from fastapi.testclient import TestClient
+    from routes import auth_routes
+
+    stored = _StoreDict()
+    monkeypatch.setattr(auth_routes, "_load_settings", lambda: dict(stored))
+    monkeypatch.setattr(auth_routes, "_save_settings", stored.update)
+    monkeypatch.setattr(auth_routes, "_load_features", lambda: dict(stored.features))
+    monkeypatch.setattr(auth_routes, "_save_features", stored.features.update)
+    monkeypatch.setattr(auth_routes, "migrate_from_settings", lambda: None)
+
+    monkeypatch.setattr(auth_routes, "load_integrations", lambda: list(stored.integrations.values()))
+    monkeypatch.setattr(auth_routes, "get_integration", lambda iid: stored.integrations.get(iid))
+
+    def _add_int(body):
+        item = dict(body, id=f"int-{len(stored.integrations) + 1}")
+        stored.integrations[item["id"]] = item
+        return item
+
+    def _update_int(iid, body):
+        if iid not in stored.integrations:
+            return None
+        stored.integrations[iid].update(body)
+        return stored.integrations[iid]
+
+    def _delete_int(iid):
+        return stored.integrations.pop(iid, None) is not None
+
+    async def _test_call(iid, method, path):
+        return {"exit_code": 0, "message": "Connection successful"}
+
+    monkeypatch.setattr(auth_routes, "add_integration", _add_int)
+    monkeypatch.setattr(auth_routes, "update_integration", _update_int)
+    monkeypatch.setattr(auth_routes, "delete_integration", _delete_int)
+    monkeypatch.setattr(auth_routes, "execute_api_call", _test_call)
+
+    class _AuthManager:
+        is_configured = True
+        signup_enabled = False
+
+        def get_username_for_token(self, token):
+            if token in ("session-token", "admin-token"):
+                return "admin"
+            if token == "user-token":
+                return "user"
+            return None
+
+        def is_admin(self, user):
+            return user == "admin"
+
+        def list_users(self):
+            return [{"username": "admin", "is_admin": True}, {"username": "user", "is_admin": False}]
+
+        def create_user(self, username, password, is_admin=False):
+            return True
+
+        def set_privileges(self, username, privs):
+            return True
+
+        def set_admin(self, username, is_admin, requesting_user):
+            return SetAdminResult.SUCCESS
+
+        def delete_user(self, username, requesting_user):
+            return True
+
+    app = fastapi.FastAPI()
+    app.include_router(auth_routes.setup_auth_routes(_AuthManager()))
+    return TestClient(app), stored
+
+
+def test_set_settings_allowed_when_auth_disabled(client, monkeypatch):
+    monkeypatch.setenv("AUTH_ENABLED", "false")
+    c, stored = client
+    r = c.post("/api/auth/settings", json={"default_model": "some-model"})
+    assert r.status_code == 200
+    assert stored.get("default_model") == "some-model"
+
+
+def test_get_settings_unscrubbed_when_auth_disabled(client, monkeypatch):
+    monkeypatch.setenv("AUTH_ENABLED", "false")
+    c, stored = client
+    stored["brave_api_key"] = "sk-secret"
+    r = c.get("/api/auth/settings")
+    assert r.status_code == 200
+    assert r.json()["brave_api_key"] == "sk-secret"
+
+
+def test_set_settings_still_403_when_auth_enabled(client, monkeypatch):
+    monkeypatch.setenv("AUTH_ENABLED", "true")
+    c, _ = client
+    r = c.post("/api/auth/settings", json={"default_model": "x"})
+    assert r.status_code == 403
+
+
+def test_set_settings_admin_session_still_works(client, monkeypatch):
+    monkeypatch.setenv("AUTH_ENABLED", "true")
+    c, stored = client
+    c.cookies.set("odysseus_session", "session-token")
+    r = c.post("/api/auth/settings", json={"default_model": "admin-model"})
+    assert r.status_code == 200
+    assert stored.get("default_model") == "admin-model"
+
+
+def test_settings_numeric_validation_and_clamping_when_auth_disabled(client, monkeypatch):
+    monkeypatch.setenv("AUTH_ENABLED", "false")
+    c, stored = client
+    # Clamp out-of-range integer values
+    r = c.post("/api/auth/settings", json={"agent_max_rounds": 999, "agent_max_tool_calls": 5000})
+    assert r.status_code == 200
+    assert stored["agent_max_rounds"] == 200
+    assert stored["agent_max_tool_calls"] == 1000
+
+    # Non-integer must raise 400
+    r = c.post("/api/auth/settings", json={"agent_max_rounds": "not-an-int"})
+    assert r.status_code == 400
+
+    # Unknown settings keys are not saved
+    r = c.post("/api/auth/settings", json={"unsupported_key_xyz": "value"})
+    assert r.status_code == 200
+    assert "unsupported_key_xyz" not in stored
+
+
+def test_features_accessible_and_persisted_when_auth_disabled(client, monkeypatch):
+    monkeypatch.setenv("AUTH_ENABLED", "false")
+    c, stored = client
+    # Public GET
+    r = c.get("/api/auth/features")
+    assert r.status_code == 200
+    assert r.json().get("web_search") is True
+
+    # POST allowed without login
+    r = c.post("/api/auth/features", json={"web_search": False})
+    assert r.status_code == 200
+    assert stored.features["web_search"] is False
+
+
+def test_integrations_lifecycle_when_auth_disabled(client, monkeypatch):
+    monkeypatch.setenv("AUTH_ENABLED", "false")
+    c, stored = client
+
+    # List: keys masked
+    r = c.get("/api/auth/integrations")
+    assert r.status_code == 200
+    items = r.json().get("integrations", [])
+    assert len(items) == 1
+    assert items[0]["api_key"] != "sk-secret-key-123"
+
+    # Create
+    r = c.post("/api/auth/integrations", json={"name": "new-srv", "preset": "custom", "api_key": "raw-key"})
+    assert r.status_code == 200
+    new_id = r.json()["integration"]["id"]
+    assert new_id in stored.integrations
+
+    # Update
+    r = c.put(f"/api/auth/integrations/{new_id}", json={"name": "updated-srv"})
+    assert r.status_code == 200
+    assert stored.integrations[new_id]["name"] == "updated-srv"
+
+    # Test
+    r = c.post(f"/api/auth/integrations/{new_id}/test")
+    assert r.status_code == 200
+
+    # Delete
+    r = c.delete(f"/api/auth/integrations/{new_id}")
+    assert r.status_code == 200
+    assert new_id not in stored.integrations
+
+    # 404 for missing item
+    assert c.put("/api/auth/integrations/nonexistent", json={"name": "x"}).status_code == 404
+    assert c.delete("/api/auth/integrations/nonexistent").status_code == 404
+    assert c.post("/api/auth/integrations/nonexistent/test").status_code == 404
+
+
+def test_user_management_fails_closed_when_auth_disabled(client, monkeypatch):
+    monkeypatch.setenv("AUTH_ENABLED", "false")
+    c, _ = client
+
+    assert c.get("/api/auth/users").status_code == 403
+    assert c.post("/api/auth/users", json={"username": "hacker", "password": "password123", "is_admin": True}).status_code == 403
+    assert c.put("/api/auth/users/target/privileges", json={"can_chat": False}).status_code == 403
+    assert c.put("/api/auth/users/target/rename", json={"username": "newtarget"}).status_code == 403
+    assert c.put("/api/auth/users/target/admin", json={"is_admin": True}).status_code == 403
+    assert c.put("/api/auth/users/target/password", json={"new_password": "password123"}).status_code == 403
+    assert c.put("/api/auth/open-signup", json={"enabled": True}).status_code == 403
+    assert c.request("DELETE", "/api/auth/users", json={"username": "target"}).status_code == 403
+
+
+def test_get_settings_scrubbed_for_unauthenticated_and_non_admin_when_auth_enabled(client, monkeypatch):
+    monkeypatch.setenv("AUTH_ENABLED", "true")
+    c, stored = client
+    stored["brave_api_key"] = "sk-secret-brave"
+    stored["default_model"] = "gpt-4o"
+
+    # Unauthenticated caller gets scrubbed settings
+    r = c.get("/api/auth/settings")
+    assert r.status_code == 200
+    data = r.json()
+    assert data["brave_api_key"] == ""
+    assert data["default_model"] == "gpt-4o"
+
+    # Non-admin authenticated user gets scrubbed settings
+    c.cookies.set("odysseus_session", "user-token")
+    r = c.get("/api/auth/settings")
+    assert r.status_code == 200
+    data = r.json()
+    assert data["brave_api_key"] == ""
+    assert data["default_model"] == "gpt-4o"
+
+    # Admin caller gets full unscrubbed settings
+    c.cookies.set("odysseus_session", "session-token")
+    r = c.get("/api/auth/settings")
+    assert r.status_code == 200
+    data = r.json()
+    assert data["brave_api_key"] == "sk-secret-brave"
+    assert data["default_model"] == "gpt-4o"
+
+
+def test_set_settings_403_for_authenticated_non_admin(client, monkeypatch):
+    monkeypatch.setenv("AUTH_ENABLED", "true")
+    c, stored = client
+    c.cookies.set("odysseus_session", "user-token")
+    r = c.post("/api/auth/settings", json={"default_model": "user-choice"})
+    assert r.status_code == 403
+    assert stored.get("default_model") != "user-choice"
+
+
+def test_features_gated_when_auth_enabled(client, monkeypatch):
+    monkeypatch.setenv("AUTH_ENABLED", "true")
+    c, stored = client
+
+    # Unauthenticated
+    assert c.post("/api/auth/features", json={"web_search": False}).status_code == 403
+
+    # Non-admin
+    c.cookies.set("odysseus_session", "user-token")
+    assert c.post("/api/auth/features", json={"web_search": False}).status_code == 403
+    assert stored.features["web_search"] is True
+
+    # Admin
+    c.cookies.set("odysseus_session", "session-token")
+    r = c.post("/api/auth/features", json={"web_search": False})
+    assert r.status_code == 200
+    assert stored.features["web_search"] is False
+
+
+def test_integrations_gated_when_auth_enabled(client, monkeypatch):
+    monkeypatch.setenv("AUTH_ENABLED", "true")
+    c, stored = client
+
+    # Unauthenticated
+    assert c.get("/api/auth/integrations").status_code == 403
+    assert c.post("/api/auth/integrations", json={"name": "a"}).status_code == 403
+
+    # Non-admin
+    c.cookies.set("odysseus_session", "user-token")
+    assert c.get("/api/auth/integrations").status_code == 403
+    assert c.post("/api/auth/integrations", json={"name": "a"}).status_code == 403
+    assert c.put("/api/auth/integrations/int-1", json={"name": "b"}).status_code == 403
+    assert c.delete("/api/auth/integrations/int-1").status_code == 403
+    assert c.post("/api/auth/integrations/int-1/test").status_code == 403
+
+    # Admin
+    c.cookies.set("odysseus_session", "session-token")
+    assert c.get("/api/auth/integrations").status_code == 200
+    assert c.post("/api/auth/integrations", json={"name": "new", "preset": "custom"}).status_code == 200
+
+
+def test_user_management_requires_admin_when_auth_enabled(client, monkeypatch):
+    monkeypatch.setenv("AUTH_ENABLED", "true")
+    c, _ = client
+
+    # Unauthenticated
+    assert c.get("/api/auth/users").status_code == 403
+    assert c.post("/api/auth/users", json={"username": "a", "password": "b"}).status_code == 403
+    assert c.put("/api/auth/users/target/password", json={"new_password": "password123"}).status_code == 403
+
+    # Non-admin
+    c.cookies.set("odysseus_session", "user-token")
+    assert c.get("/api/auth/users").status_code == 403
+    assert c.put("/api/auth/users/target/password", json={"new_password": "password123"}).status_code == 403
+
+    # Admin
+    c.cookies.set("odysseus_session", "session-token")
+    assert c.get("/api/auth/users").status_code == 200
+
+
+def test_document_style_extract_gating(client, monkeypatch):
+    c, _ = client
+    dummy_file = {"file": ("sample.txt", b"dummy prose content")}
+
+    # When auth enabled: unauthenticated is 403, non-admin is 403
+    monkeypatch.setenv("AUTH_ENABLED", "true")
+    assert c.post("/api/auth/settings/document-style/extract", files=dummy_file).status_code == 403
+
+    c.cookies.set("odysseus_session", "user-token")
+    assert c.post("/api/auth/settings/document-style/extract", files=dummy_file).status_code == 403
+
+    # When auth disabled: unauthenticated passes admin gate (400 for sample length < 80)
+    monkeypatch.setenv("AUTH_ENABLED", "false")
+    c.cookies.clear()
+    assert c.post("/api/auth/settings/document-style/extract", files=dummy_file).status_code == 400
diff --git a/tests/test_settings_save_response_ok_js.py b/tests/test_settings_save_response_ok_js.py
new file mode 100644
index 000000000..5bc5eff05
--- /dev/null
+++ b/tests/test_settings_save_response_ok_js.py
@@ -0,0 +1,120 @@
+"""Frontend regression tests: verify settings save handlers check HTTP response status.
+
+Locks in that static/js/settings.js verifies response.ok before displaying success,
+preventing 401, 403, 400, and 500 responses from reporting false success.
+"""
+import re
+import shutil
+import subprocess
+from pathlib import Path
+
+import pytest
+
+_REPO = Path(__file__).resolve().parent.parent
+_SETTINGS_JS = _REPO / "static" / "js" / "settings.js"
+_SETTINGS_DIR = _REPO / "static" / "js" / "settings"
+_SETTINGS_API_JS = _SETTINGS_DIR / "api.js"
+_HAS_NODE = shutil.which("node") is not None
+
+
+@pytest.mark.skipif(not _HAS_NODE, reason="node binary not on PATH")
+def test_settings_js_syntax():
+    """Verify static/js/settings.js and settings/*.js modules are syntactically valid JavaScript."""
+    js_files = [_SETTINGS_JS] + list(_SETTINGS_DIR.glob("*.js"))
+    for js_file in js_files:
+        proc = subprocess.run(
+            ["node", "--check", str(js_file)],
+            capture_output=True,
+            text=True,
+            cwd=str(_REPO),
+        )
+        assert proc.returncode == 0, f"JS syntax error in {js_file.name}:\n{proc.stderr}"
+
+
+def test_post_settings_helper_verifies_response_ok():
+    """Centralized postSettings in settings/api.js must verify response.ok and throw on failure."""
+    assert _SETTINGS_API_JS.exists(), f"Expected {_SETTINGS_API_JS} to exist"
+    api_content = _SETTINGS_API_JS.read_text(encoding="utf-8")
+
+    # Verify fetch to /api/auth/settings with POST method
+    match = re.search(r"fetch\(['\"]/api/auth/settings['\"],\s*\{\s*method:\s*['\"]POST['\"]", api_content)
+    assert match is not None, "Expected POST fetch to /api/auth/settings in settings/api.js"
+
+    # Verify .ok is checked within 300 characters of fetch
+    window = api_content[match.start(): match.start() + 300]
+    assert ".ok" in window, f"postSettings must check response.ok:\n{window}"
+
+    # Verify that it throws an error when !response.ok
+    assert "throw error" in api_content or "throw new Error" in api_content, (
+        "postSettings must throw when response is not ok"
+    )
+
+
+def test_all_settings_save_handlers_route_through_post_settings():
+    """All settings save handlers in settings.js and settings/*.js must route saves via postSettings."""
+    settings_content = _SETTINGS_JS.read_text(encoding="utf-8")
+    module_contents = {p.name: p.read_text(encoding="utf-8") for p in _SETTINGS_DIR.glob("*.js")}
+
+    # Assert no unverified direct POST fetch to /api/auth/settings in settings.js
+    direct_posts = list(re.finditer(r"fetch\(['\"]/api/auth/settings['\"],\s*\{\s*method:\s*['\"]POST['\"]", settings_content))
+    assert len(direct_posts) == 0, (
+        f"Found direct POST fetch to /api/auth/settings in settings.js; all writes must route through _postSettings"
+    )
+
+    # Count _postSettings invocations across settings.js and modules
+    post_settings_calls = len(re.findall(r"_postSettings\(", settings_content))
+    for mod_name, mod_text in module_contents.items():
+        if mod_name != "api.js":
+            post_settings_calls += len(re.findall(r"_postSettings\(", mod_text))
+
+    assert post_settings_calls >= 15, (
+        f"Expected at least 15 _postSettings calls across settings modules, found {post_settings_calls}"
+    )
+
+
+@pytest.mark.skipif(not _HAS_NODE, reason="node binary not on PATH")
+def test_failed_save_shows_failure_in_simulated_dom():
+    """Verify that when fetch returns !res.ok, save logic catches and flags error."""
+    js = """
+    let msgText = '';
+    let msgColor = '';
+    const msg = {
+      set textContent(v) { msgText = v; },
+      get textContent() { return msgText; },
+      style: { set color(v) { msgColor = v; }, get color() { return msgColor; } }
+    };
+
+    async function save(fetchImpl) {
+      try {
+        var res = await fetchImpl('/api/auth/settings', { method: 'POST' });
+        if (!res.ok) throw new Error('HTTP ' + res.status);
+        msg.textContent = 'Saved'; msg.style.color = 'var(--fg)';
+      } catch (e) {
+        msg.textContent = 'Failed to save'; msg.style.color = 'var(--red)';
+      }
+    }
+
+    async function run() {
+      // 1. Rejected fetch (403)
+      await save(async () => ({ ok: false, status: 403 }));
+      const rejectedResult = { text: msgText, color: msgColor };
+
+      // 2. Server error (500)
+      await save(async () => ({ ok: false, status: 500 }));
+      const serverErrResult = { text: msgText, color: msgColor };
+
+      // 3. Successful fetch (200)
+      await save(async () => ({ ok: true, status: 200 }));
+      const okResult = { text: msgText, color: msgColor };
+
+      console.log(JSON.stringify({ rejectedResult, serverErrResult, okResult }));
+    }
+    run();
+    """
+    proc = subprocess.run(["node", "-e", js], capture_output=True, text=True, check=True)
+    import json
+    data = json.loads(proc.stdout)
+    assert data["rejectedResult"] == {"text": "Failed to save", "color": "var(--red)"}
+    assert data["serverErrResult"] == {"text": "Failed to save", "color": "var(--red)"}
+    assert data["okResult"] == {"text": "Saved", "color": "var(--fg)"}
+

From 501059805f792c73b61263010cb13396750a3c0b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Robert=20Vind-Gardo=C8=99?=
 <41092915+robyroro@users.noreply.github.com>
Date: Wed, 14 Oct 2026 13:21:53 +0300
Subject: [PATCH 14/53] fix(cleanup): preserve transcripts with stale message
 counts (#6610)

* fix(cleanup): preserve transcripts with stale message counts

* fix(cleanup): accurately attribute freed space and bound recent session query

* fix(cleanup): add portable fallback for SQLite runtimes lacking RETURNING

---------

Co-authored-by: PR #6166 Reviewer <reviewer@odysseus-review.local>
---
 src/cleanup_service.py                        | 131 ++++--
 tests/test_cleanup_transcript_preservation.py | 377 ++++++++++++++++++
 2 files changed, 473 insertions(+), 35 deletions(-)
 create mode 100644 tests/test_cleanup_transcript_preservation.py

diff --git a/src/cleanup_service.py b/src/cleanup_service.py
index ec1503d9c..b19e8c5c7 100644
--- a/src/cleanup_service.py
+++ b/src/cleanup_service.py
@@ -37,6 +37,41 @@ def _apply_owner_filter(query, DbSession, owner: Optional[str]):
     return query.filter(DbSession.owner == owner)
 
 
+def _message_count_subquery(db, DbSession, DbChatMessage):
+    """Count durable rows instead of trusting the derived session counter."""
+    from sqlalchemy import func
+    return db.query(func.count(DbChatMessage.id)).filter(
+        DbChatMessage.session_id == DbSession.id
+    ).correlate(DbSession).scalar_subquery()
+
+
+def _recent_session_ids(db, DbSession, owner: Optional[str]) -> set:
+    """Fetch the bounded set of recently created session IDs to preserve."""
+    recent_q = db.query(DbSession.id).order_by(DbSession.created_at.desc())
+    recent_q = _apply_owner_filter(recent_q, DbSession, owner)
+    return {row[0] for row in recent_q.limit(CleanupConfig.PRESERVE_RECENT_COUNT).all()}
+
+
+def _supports_delete_returning(db) -> bool:
+    """Check if the current database backend and runtime version support DELETE ... RETURNING."""
+    dialect = getattr(db.get_bind(), "dialect", None)
+    if dialect is None:
+        return False
+    if dialect.name == "postgresql":
+        return True
+    if dialect.name == "sqlite":
+        # SQLite added RETURNING support in 3.35.0 (March 2021).
+        version = getattr(dialect, "server_version_info", None)
+        if version is not None:
+            return version >= (3, 35, 0)
+        try:
+            import sqlite3
+            return sqlite3.sqlite_version_info >= (3, 35, 0)
+        except Exception:
+            return False
+    return getattr(dialect, "delete_returning", False)
+
+
 async def archive_inactive_sessions(session_manager, owner: Optional[str] = None) -> int:
     """
     Archive sessions that haven't been accessed in the configured number of days.
@@ -96,29 +131,26 @@ async def cleanup_old_sessions(session_manager, owner: Optional[str] = None) ->
     from src.database import SessionLocal, Session as DbSession, ChatMessage as DbChatMessage
     db = SessionLocal()
     try:
-        recent_q = db.query(DbSession).order_by(DbSession.created_at.desc())
-        recent_q = _apply_owner_filter(recent_q, DbSession, owner)
-        all_sessions = recent_q.all()
-        recent_session_ids = {session.id for session in all_sessions[:CleanupConfig.PRESERVE_RECENT_COUNT]}
+        recent_session_ids = _recent_session_ids(db, DbSession, owner)
 
         base_query = db.query(DbSession).filter(
             DbSession.archived == True,
             DbSession.last_accessed < cutoff_date,
             DbSession.is_important == False,
-            DbSession.message_count < CleanupConfig.MIN_MESSAGES_TO_KEEP
         )
         base_query = _apply_owner_filter(base_query, DbSession, owner)
-
-        candidate_sessions = base_query.all()
+        actual_count = _message_count_subquery(db, DbSession, DbChatMessage)
+        candidate_sessions = base_query.add_columns(actual_count).all()
         sessions_to_delete = []
+        message_counts = {}
         preserved_count = 0
 
-        for session in candidate_sessions:
+        for session, message_count in candidate_sessions:
             if session.id in recent_session_ids:
                 preserved_count += 1
                 continue
 
-            if session.message_count >= CleanupConfig.MIN_MESSAGES_TO_KEEP:
+            if message_count >= CleanupConfig.MIN_MESSAGES_TO_KEEP:
                 preserved_count += 1
                 continue
 
@@ -128,20 +160,52 @@ async def cleanup_old_sessions(session_manager, owner: Optional[str] = None) ->
                 continue
 
             sessions_to_delete.append(session)
-
-        for session in sessions_to_delete:
-            message_count = db.query(DbChatMessage).filter(
-                DbChatMessage.session_id == session.id
-            ).count()
-            space_freed += message_count * CleanupConfig.ESTIMATED_MESSAGE_SIZE_BYTES
+            message_counts[session.id] = message_count
 
         session_ids = [session.id for session in sessions_to_delete]
         if session_ids:
-            db.query(DbSession).filter(DbSession.id.in_(session_ids)).delete(synchronize_session=False)
-            deleted_count = len(session_ids)
+            # Recheck the real count in the DELETE statement itself. A message
+            # arriving after candidate selection must retain the protection.
+            # Using RETURNING accurately identifies rows deleted by this cleanup,
+            # avoiding misattributing space freed if another transaction independently
+            # deleted a candidate row.
+            from sqlalchemy import delete
+            stmt = delete(DbSession).filter(
+                DbSession.id.in_(session_ids),
+                DbSession.archived == True,
+                DbSession.last_accessed < cutoff_date,
+                DbSession.is_important == False,
+                actual_count < CleanupConfig.MIN_MESSAGES_TO_KEEP,
+            )
+            stmt = _apply_owner_filter(stmt, DbSession, owner)
+            if _supports_delete_returning(db):
+                deleted_rows = db.execute(stmt.returning(DbSession.id)).scalars().all()
+                deleted_ids = set(deleted_rows)
+                deleted_count = len(deleted_ids)
+                surviving_ids = {row[0] for row in db.query(DbSession.id).filter(
+                    DbSession.id.in_(session_ids)
+                ).all()}
+                unaccounted_ids = set(session_ids) - surviving_ids - deleted_ids
+                space_freed = sum(message_counts[sid] for sid in deleted_ids) * CleanupConfig.ESTIMATED_MESSAGE_SIZE_BYTES
+            else:
+                # Portable fallback for legacy SQLite (< 3.35.0) which lacks RETURNING syntax.
+                res = db.execute(stmt)
+                deleted_count = res.rowcount or 0
+                surviving_ids = {row[0] for row in db.query(DbSession.id).filter(
+                    DbSession.id.in_(session_ids)
+                ).all()}
+                deleted_ids = set(session_ids) - surviving_ids
+                unaccounted_ids = set()
+                if deleted_count == 0:
+                    space_freed = 0
+                elif len(deleted_ids) <= deleted_count:
+                    space_freed = sum(message_counts[sid] for sid in deleted_ids) * CleanupConfig.ESTIMATED_MESSAGE_SIZE_BYTES
+                else:
+                    space_freed = sum(message_counts[sid] for sid in sorted(deleted_ids)[:deleted_count]) * CleanupConfig.ESTIMATED_MESSAGE_SIZE_BYTES
             db.commit()
 
-            for session_id in session_ids:
+            cache_evict_ids = deleted_ids | unaccounted_ids
+            for session_id in cache_evict_ids:
                 if session_id in session_manager.sessions:
                     del session_manager.sessions[session_id]
 
@@ -176,7 +240,7 @@ async def get_cleanup_preview(owner: Optional[str] = None) -> Dict[str, Any]:
     estimated_space_freed = 0
     preserved_sessions = []
 
-    from src.database import SessionLocal, Session as DbSession
+    from src.database import SessionLocal, Session as DbSession, ChatMessage as DbChatMessage
     db = SessionLocal()
     try:
         archive_q = db.query(DbSession).filter(
@@ -184,49 +248,46 @@ async def get_cleanup_preview(owner: Optional[str] = None) -> Dict[str, Any]:
             DbSession.archived == False
         )
         archive_q = _apply_owner_filter(archive_q, DbSession, owner)
-        archive_candidates = archive_q.all()
+        actual_count = _message_count_subquery(db, DbSession, DbChatMessage)
+        archive_candidates = archive_q.add_columns(actual_count).all()
 
-        for session in archive_candidates:
+        for session, message_count in archive_candidates:
             sessions_to_archive.append({
                 "id": session.id,
                 "name": session.name,
                 "last_accessed": session.last_accessed.isoformat() if session.last_accessed else "Unknown",
-                "message_count": session.message_count
+                "message_count": message_count
             })
 
-        recent_q = db.query(DbSession).order_by(DbSession.created_at.desc())
-        recent_q = _apply_owner_filter(recent_q, DbSession, owner)
-        all_sessions = recent_q.all()
-        recent_session_ids = {session.id for session in all_sessions[:CleanupConfig.PRESERVE_RECENT_COUNT]}
+        recent_session_ids = _recent_session_ids(db, DbSession, owner)
 
         base_query = db.query(DbSession).filter(
             DbSession.archived == True,
             DbSession.last_accessed < cutoff_delete,
             DbSession.is_important == False,
-            DbSession.message_count < CleanupConfig.MIN_MESSAGES_TO_KEEP
         )
         base_query = _apply_owner_filter(base_query, DbSession, owner)
 
-        candidate_sessions = base_query.all()
+        candidate_sessions = base_query.add_columns(actual_count).all()
 
-        for session in candidate_sessions:
+        for session, message_count in candidate_sessions:
             if session.id in recent_session_ids:
                 preserved_sessions.append({
                     "id": session.id,
                     "name": session.name,
                     "reason": f"part of last {CleanupConfig.PRESERVE_RECENT_COUNT} sessions",
                     "last_accessed": session.last_accessed.isoformat() if session.last_accessed else "Unknown",
-                    "message_count": session.message_count
+                    "message_count": message_count
                 })
                 continue
 
-            if session.message_count >= CleanupConfig.MIN_MESSAGES_TO_KEEP:
+            if message_count >= CleanupConfig.MIN_MESSAGES_TO_KEEP:
                 preserved_sessions.append({
                     "id": session.id,
                     "name": session.name,
                     "reason": f"has {CleanupConfig.MIN_MESSAGES_TO_KEEP}+ messages",
                     "last_accessed": session.last_accessed.isoformat() if session.last_accessed else "Unknown",
-                    "message_count": session.message_count
+                    "message_count": message_count
                 })
                 continue
 
@@ -238,18 +299,18 @@ async def get_cleanup_preview(owner: Optional[str] = None) -> Dict[str, Any]:
                     "name": session.name,
                     "reason": f"contains keyword: {matching_keywords[0]}",
                     "last_accessed": session.last_accessed.isoformat() if session.last_accessed else "Unknown",
-                    "message_count": session.message_count
+                    "message_count": message_count
                 })
                 continue
 
-            session_space = session.message_count * CleanupConfig.ESTIMATED_MESSAGE_SIZE_BYTES
+            session_space = message_count * CleanupConfig.ESTIMATED_MESSAGE_SIZE_BYTES
             estimated_space_freed += session_space
 
             sessions_to_delete.append({
                 "id": session.id,
                 "name": session.name,
                 "last_accessed": session.last_accessed.isoformat() if session.last_accessed else "Unknown",
-                "message_count": session.message_count,
+                "message_count": message_count,
                 "estimated_size_kb": round(session_space / 1024, 2)
             })
 
diff --git a/tests/test_cleanup_transcript_preservation.py b/tests/test_cleanup_transcript_preservation.py
new file mode 100644
index 000000000..e2c27277e
--- /dev/null
+++ b/tests/test_cleanup_transcript_preservation.py
@@ -0,0 +1,377 @@
+"""Cleanup must use durable transcript rows for its deletion safeguards."""
+from datetime import datetime, timedelta, timezone
+from types import SimpleNamespace
+
+import pytest
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+from sqlalchemy import create_engine, event, insert
+from sqlalchemy.orm import sessionmaker
+
+import core.database as database
+import src.database as legacy_database
+import routes.cleanup.cleanup_routes as routes
+
+
+@pytest.fixture
+def cleanup_api(tmp_path, monkeypatch):
+    engine = create_engine(
+        f"sqlite:///{(tmp_path / 'cleanup.db').as_posix()}",
+        connect_args={"check_same_thread": False},
+    )
+    database.Base.metadata.create_all(engine)
+    factory = sessionmaker(bind=engine, autoflush=False)
+    monkeypatch.setattr(legacy_database, "SessionLocal", factory)
+    monkeypatch.setattr(routes, "get_current_user", lambda request: "alice")
+    manager = SimpleNamespace(sessions={})
+    app = FastAPI()
+    app.include_router(routes.setup_cleanup_routes(manager))
+    with TestClient(app) as client:
+        yield client, factory, manager
+    engine.dispose()
+
+
+def seed(factory, manager, stored, actual, *, archived=True):
+    now = datetime.now(timezone.utc).replace(tzinfo=None)
+    with factory() as db:
+        for index in range(10):
+            db.add(database.Session(
+                id=f"recent-{index}", name="Recent", endpoint_url="", model="",
+                owner="alice", created_at=now - timedelta(hours=index),
+                last_accessed=now, message_count=1,
+            ))
+        db.add(database.Session(
+            id="old-chat", name="Project discussion", endpoint_url="", model="",
+            owner="alice", created_at=now - timedelta(days=50),
+            last_accessed=now - timedelta(days=30), archived=archived,
+            is_important=False, message_count=stored,
+        ))
+        db.commit()
+        db.add_all(database.ChatMessage(
+            id=f"message-{index}", session_id="old-chat", role="user",
+            content=f"Saved project discussion {index}", timestamp=now - timedelta(days=30),
+        ) for index in range(actual))
+        db.commit()
+    manager.sessions["old-chat"] = SimpleNamespace(message_count=actual)
+
+
+@pytest.mark.parametrize("stored", [0, 3])
+def test_cleanup_preserves_long_transcript_with_stale_count(cleanup_api, stored):
+    client, factory, manager = cleanup_api
+    seed(factory, manager, stored, 40)
+    preview = client.get("/api/cleanup/preview").json()
+    assert not preview["sessions_to_delete"]
+    protected = next(row for row in preview["preserved_sessions"] if row["id"] == "old-chat")
+    assert protected["message_count"] == 40
+    response = client.post("/api/cleanup")
+    with factory() as db:
+        actual = db.query(database.ChatMessage).filter_by(session_id="old-chat").count()
+        survives = db.get(database.Session, "old-chat") is not None
+    assert response.json()["deleted_count"] == 0
+    assert survives and actual == 40, "Cleanup must count actual rows before hard deletion"
+
+
+def test_cleanup_still_removes_genuinely_short_old_chat(cleanup_api):
+    client, factory, manager = cleanup_api
+    seed(factory, manager, 3, 3)
+    response = client.post("/api/cleanup")
+    assert response.json()["deleted_count"] == 1
+    with factory() as db:
+        assert db.get(database.Session, "old-chat") is None
+        assert db.query(database.ChatMessage).filter_by(session_id="old-chat").count() == 0
+
+
+def test_new_archive_is_not_deleted_in_same_cleanup(cleanup_api):
+    client, factory, manager = cleanup_api
+    seed(factory, manager, 3, 3, archived=False)
+    preview = client.get("/api/cleanup/preview").json()
+    assert not preview["sessions_to_delete"]
+    response = client.post("/api/cleanup")
+    assert response.json()["deleted_count"] == 0
+    with factory() as db:
+        assert db.get(database.Session, "old-chat").archived
+
+
+@pytest.mark.parametrize("actual,expected_deleted", [(19, 1), (20, 0)])
+def test_cleanup_threshold_uses_actual_count_even_when_metadata_is_high(cleanup_api, actual, expected_deleted):
+    client, factory, manager = cleanup_api
+    seed(factory, manager, 100, actual)
+    preview = client.get("/api/cleanup/preview").json()
+    section = "sessions_to_delete" if expected_deleted else "preserved_sessions"
+    row = next(row for row in preview[section] if row["id"] == "old-chat")
+    assert row["message_count"] == actual
+    if expected_deleted:
+        assert row["estimated_size_kb"] == 19 * 512 / 1024
+    response = client.post("/api/cleanup")
+    assert response.json()["deleted_count"] == expected_deleted
+    with factory() as db:
+        assert (db.get(database.Session, "old-chat") is None) == bool(expected_deleted)
+
+
+@pytest.mark.parametrize("protection", ["starred", "keyword", "other_owner"])
+def test_cleanup_retains_existing_protections(cleanup_api, protection):
+    client, factory, manager = cleanup_api
+    seed(factory, manager, 0, 3)
+    with factory() as db:
+        row = db.get(database.Session, "old-chat")
+        if protection == "starred":
+            row.is_important = True
+        elif protection == "keyword":
+            row.name = "Important project"
+        else:
+            row.owner = "bob"
+        # Preserve the old activity date despite the column's onupdate default.
+        row.last_accessed = datetime.now(timezone.utc).replace(tzinfo=None) - timedelta(days=30)
+        db.commit()
+    response = client.post("/api/cleanup")
+    assert response.json()["deleted_count"] == 0
+    with factory() as db:
+        assert db.query(database.ChatMessage).filter_by(session_id="old-chat").count() == 3
+
+
+def test_cleanup_rechecks_messages_at_the_delete_boundary(cleanup_api):
+    """Deliver new rows after selection but before the DELETE executes."""
+    client, factory, manager = cleanup_api
+    seed(factory, manager, 3, 3)
+    engine = factory.kw["bind"]
+    injected = False
+
+    def deliver_messages(connection, cursor, statement, parameters, context, executemany):
+        nonlocal injected
+        if not injected and statement.lstrip().startswith("DELETE FROM sessions"):
+            injected = True
+            connection.execute(insert(database.ChatMessage), [
+                {"id": f"incoming-{i}", "session_id": "old-chat", "role": "assistant",
+                 "content": "New durable message"} for i in range(20)
+            ])
+
+    event.listen(engine, "before_cursor_execute", deliver_messages)
+    try:
+        response = client.post("/api/cleanup")
+    finally:
+        event.remove(engine, "before_cursor_execute", deliver_messages)
+    assert injected
+    assert response.json()["deleted_count"] == 0
+    assert response.json()["space_freed_mb"] == 0
+    assert "old-chat" in manager.sessions
+    with factory() as db:
+        assert db.get(database.Session, "old-chat") is not None
+        assert db.query(database.ChatMessage).filter_by(session_id="old-chat").count() == 23
+
+
+def test_cleanup_space_freed_ignores_concurrently_deleted_session(cleanup_api):
+    """If another transaction deletes a candidate first, do not attribute its space."""
+    client, factory, manager = cleanup_api
+    now = datetime.now(timezone.utc).replace(tzinfo=None)
+    with factory() as db:
+        for index in range(10):
+            db.add(database.Session(
+                id=f"recent-{index}", name="Recent", endpoint_url="", model="",
+                owner="alice", created_at=now - timedelta(hours=index),
+                last_accessed=now, message_count=1,
+            ))
+        db.add(database.Session(
+            id="chat-to-delete", name="Eligible 1", endpoint_url="", model="",
+            owner="alice", created_at=now - timedelta(days=50),
+            last_accessed=now - timedelta(days=30), archived=True,
+            is_important=False, message_count=3,
+        ))
+        db.add(database.Session(
+            id="chat-concurrently-deleted", name="Eligible 2", endpoint_url="", model="",
+            owner="alice", created_at=now - timedelta(days=50),
+            last_accessed=now - timedelta(days=30), archived=True,
+            is_important=False, message_count=10,
+        ))
+        db.commit()
+        db.add_all(database.ChatMessage(
+            id=f"msg1-{i}", session_id="chat-to-delete", role="user",
+            content="m", timestamp=now - timedelta(days=30),
+        ) for i in range(3))
+        db.add_all(database.ChatMessage(
+            id=f"msg2-{i}", session_id="chat-concurrently-deleted", role="user",
+            content="m", timestamp=now - timedelta(days=30),
+        ) for i in range(10))
+        db.commit()
+
+    manager.sessions["chat-to-delete"] = SimpleNamespace(message_count=3)
+    manager.sessions["chat-concurrently-deleted"] = SimpleNamespace(message_count=10)
+
+    engine = factory.kw["bind"]
+    injected = False
+
+    def delete_candidate(connection, cursor, statement, parameters, context, executemany):
+        nonlocal injected
+        if not injected and statement.lstrip().startswith("DELETE FROM sessions"):
+            injected = True
+            with factory() as other_db:
+                other_db.query(database.Session).filter_by(id="chat-concurrently-deleted").delete()
+                other_db.commit()
+
+    event.listen(engine, "before_cursor_execute", delete_candidate)
+    try:
+        response = client.post("/api/cleanup")
+    finally:
+        event.remove(engine, "before_cursor_execute", delete_candidate)
+
+    assert injected
+    data = response.json()
+    assert data["deleted_count"] == 1
+    # Only chat-to-delete's 3 messages (1536 bytes) freed by this cleanup, not (3 + 10) * 512
+    expected_space_mb = round(3 * 512 / (1024 * 1024), 2)
+    assert data["space_freed_mb"] == expected_space_mb
+    assert "chat-to-delete" not in manager.sessions
+    assert "chat-concurrently-deleted" not in manager.sessions
+    with factory() as db:
+        assert db.get(database.Session, "chat-to-delete") is None
+        assert db.get(database.Session, "chat-concurrently-deleted") is None
+
+
+def test_cleanup_recent_session_query_is_bounded(cleanup_api):
+    """Ensure recent-session preservation scales to large collections and respects limits."""
+    client, factory, manager = cleanup_api
+    now = datetime.now(timezone.utc).replace(tzinfo=None)
+    with factory() as db:
+        for index in range(25):
+            db.add(database.Session(
+                id=f"sess-{index:02d}", name=f"Session {index}", endpoint_url="", model="",
+                owner="alice", created_at=now - timedelta(hours=index),
+                last_accessed=now - timedelta(days=30), archived=True,
+                is_important=False, message_count=3,
+            ))
+            db.add_all(database.ChatMessage(
+                id=f"msg-{index}-{m}", session_id=f"sess-{index:02d}", role="user",
+                content="m", timestamp=now - timedelta(days=30),
+            ) for m in range(3))
+        db.commit()
+
+    preview = client.get("/api/cleanup/preview").json()
+    preserved_ids = {row["id"] for row in preview["preserved_sessions"]}
+    to_delete_ids = {row["id"] for row in preview["sessions_to_delete"]}
+
+    # Top 10 newest (sess-00 to sess-09) must be preserved
+    expected_preserved = {f"sess-{i:02d}" for i in range(10)}
+    expected_to_delete = {f"sess-{i:02d}" for i in range(10, 25)}
+    assert preserved_ids == expected_preserved
+    assert to_delete_ids == expected_to_delete
+
+    response = client.post("/api/cleanup")
+    assert response.json()["deleted_count"] == 15
+
+    with factory() as db:
+        surviving = {row[0] for row in db.query(database.Session.id).all()}
+        assert surviving == expected_preserved
+
+
+def test_cleanup_handles_zero_actual_messages_session(cleanup_api):
+    """Sessions with zero durable messages are properly previewed and cleaned up."""
+    client, factory, manager = cleanup_api
+    seed(factory, manager, 10, 0)
+    preview = client.get("/api/cleanup/preview").json()
+    row = next(r for r in preview["sessions_to_delete"] if r["id"] == "old-chat")
+    assert row["message_count"] == 0
+    assert row["estimated_size_kb"] == 0.0
+
+    response = client.post("/api/cleanup")
+    assert response.json()["deleted_count"] == 1
+    with factory() as db:
+        assert db.get(database.Session, "old-chat") is None
+
+
+def test_cleanup_db_error_preserves_cache_and_aborts_cleanly(cleanup_api):
+    """Database execution failures must abort, rollback, and leave in-memory cache intact."""
+    client, factory, manager = cleanup_api
+    seed(factory, manager, 3, 3)
+    engine = factory.kw["bind"]
+    injected = False
+
+    def break_delete(connection, cursor, statement, parameters, context, executemany):
+        nonlocal injected
+        if not injected and statement.lstrip().startswith("DELETE FROM sessions"):
+            injected = True
+            raise RuntimeError("Injected database error during DELETE")
+
+    event.listen(engine, "before_cursor_execute", break_delete)
+    try:
+        response = client.post("/api/cleanup")
+    finally:
+        event.remove(engine, "before_cursor_execute", break_delete)
+
+    assert injected
+    assert response.status_code == 200
+    assert response.json()["deleted_count"] == 0
+    assert response.json()["space_freed_mb"] == 0
+    # In-memory session was not prematurely evicted
+    assert "old-chat" in manager.sessions
+    # Database row was rolled back and still exists
+    with factory() as db:
+        assert db.get(database.Session, "old-chat") is not None
+        assert db.query(database.ChatMessage).filter_by(session_id="old-chat").count() == 3
+
+
+def test_cleanup_portable_fallback_without_returning(cleanup_api, monkeypatch):
+    """Engines lacking RETURNING (e.g. SQLite < 3.35.0) safely clean up without syntax errors."""
+    import src.cleanup_service as cleanup_service
+    monkeypatch.setattr(cleanup_service, "_supports_delete_returning", lambda db: False)
+
+    client, factory, manager = cleanup_api
+    now = datetime.now(timezone.utc).replace(tzinfo=None)
+    with factory() as db:
+        for index in range(10):
+            db.add(database.Session(
+                id=f"recent-{index}", name="Recent", endpoint_url="", model="",
+                owner="alice", created_at=now - timedelta(hours=index),
+                last_accessed=now, message_count=1,
+            ))
+        db.add(database.Session(
+            id="chat-to-delete", name="Eligible 1", endpoint_url="", model="",
+            owner="alice", created_at=now - timedelta(days=50),
+            last_accessed=now - timedelta(days=30), archived=True,
+            is_important=False, message_count=3,
+        ))
+        db.add(database.Session(
+            id="chat-concurrently-deleted", name="Eligible 2", endpoint_url="", model="",
+            owner="alice", created_at=now - timedelta(days=50),
+            last_accessed=now - timedelta(days=30), archived=True,
+            is_important=False, message_count=10,
+        ))
+        db.commit()
+        db.add_all(database.ChatMessage(
+            id=f"msg1-{i}", session_id="chat-to-delete", role="user",
+            content="m", timestamp=now - timedelta(days=30),
+        ) for i in range(3))
+        db.add_all(database.ChatMessage(
+            id=f"msg2-{i}", session_id="chat-concurrently-deleted", role="user",
+            content="m", timestamp=now - timedelta(days=30),
+        ) for i in range(10))
+        db.commit()
+
+    manager.sessions["chat-to-delete"] = SimpleNamespace(message_count=3)
+    manager.sessions["chat-concurrently-deleted"] = SimpleNamespace(message_count=10)
+
+    engine = factory.kw["bind"]
+    injected = False
+
+    def delete_candidate(connection, cursor, statement, parameters, context, executemany):
+        nonlocal injected
+        if not injected and statement.lstrip().startswith("DELETE FROM sessions"):
+            injected = True
+            with factory() as other_db:
+                other_db.query(database.Session).filter_by(id="chat-concurrently-deleted").delete()
+                other_db.commit()
+
+    event.listen(engine, "before_cursor_execute", delete_candidate)
+    try:
+        response = client.post("/api/cleanup")
+    finally:
+        event.remove(engine, "before_cursor_execute", delete_candidate)
+
+    assert injected
+    data = response.json()
+    assert data["deleted_count"] == 1
+    expected_space_mb = round(3 * 512 / (1024 * 1024), 2)
+    assert data["space_freed_mb"] == expected_space_mb
+    assert "chat-to-delete" not in manager.sessions
+    assert "chat-concurrently-deleted" not in manager.sessions
+    with factory() as db:
+        assert db.get(database.Session, "chat-to-delete") is None
+        assert db.get(database.Session, "chat-concurrently-deleted") is None

From 6fceb6ccd365c517e251c04902e1699a5b847084 Mon Sep 17 00:00:00 2001
From: Isharak <isharak7m@gmail.com>
Date: Wed, 14 Oct 2026 16:48:50 +0530
Subject: [PATCH 15/53] fix(security): deny generated-image access when
 ownership verification fails (#6268)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* fix(security): deny generated-image access when ownership verification fails

The except Exception block in serve_generated_image catches all
exceptions during ownership verification and falls through to serve
the file anyway. If the database is down or corrupted, the ownership
check is bypassed entirely — any authenticated user can download any
generated image by guessing the content-hash filename.

Raise HTTP 503 (Service Unavailable) instead of falling through,
so the endpoint fails closed when verification is impossible. This
matches the defense-in-depth principle: deny access on verification
errors rather than granting it.

* fix(security): enforce fail-closed ownership and secure caching for generated images

- Fail closed on missing gallery records, null/empty owners, and DB errors
- Support both cookie session and bearer API token owners via effective_user
- Add in-memory registry for freshly generated images to preserve access
- Eliminate file existence oracle by verifying ownership before disk probing
- Update Cache-Control to private, no-cache, must-revalidate
- Pass owner attribution through tool execution and image MCP server
- Add comprehensive hermetic regression tests for ownership gates and caching

* fix(security): sanitize tool owner arguments and drop unneeded MCP env fallback

- Remove redundant and unsafe ODYSSEUS_MCP_IMAGE_OWNER fallback in image_gen_server.py to fix 4 tests in test_env_reference.py.
- Sanitize caller-supplied tool arguments across all MCP and email tool dispatch paths in src/tool_execution.py: strip untrusted _odysseus_* keys from arguments.
- Only inject _odysseus_owner when verified trusted server context is present, preventing untrusted/anonymous users from spoofing ownership claims.
- Sanitize empty/whitespace owner strings in image_gen_server.py to None.
- Add comprehensive regression tests in test_generated_image_ownership.py for argument sanitization, owner injection, fallback propagation, and server sanitization.

---------

Co-authored-by: isharak7m <192635824+isharak7m@users.noreply.github.com>
Co-authored-by: PR #6166 Reviewer <reviewer@odysseus-review.local>
---
 app.py                                    |  87 ++--
 mcp_servers/image_gen_server.py           |   8 +
 src/ai_interaction.py                     |   9 +
 src/generated_images.py                   |  43 +-
 src/tool_execution.py                     |  40 +-
 tests/test_generated_image_confinement.py |   2 +-
 tests/test_generated_image_ownership.py   | 493 ++++++++++++++++++++++
 7 files changed, 643 insertions(+), 39 deletions(-)
 create mode 100644 tests/test_generated_image_ownership.py

diff --git a/app.py b/app.py
index 5215966fb..60441baf1 100644
--- a/app.py
+++ b/app.py
@@ -516,28 +516,69 @@ app.mount("/static", _RevalidatingStatic(directory=STATIC_DIR), name="static")
 @app.get("/api/generated-image/{filename}")
 async def serve_generated_image(filename: str, request: Request):
     """Serve generated images from the data directory."""
-    img_path = resolve_generated_image_path(filename)
-    # SECURITY: filename is the only key, so anyone who knows / guesses a
-    # 12-hex content hash could pull another user's image bytes. Require
-    # auth and verify ownership via the gallery row (when one exists).
-    try:
-        from src.auth_helpers import get_current_user
-        from core.database import SessionLocal as _SL, GalleryImage as _GI
-        _user = get_current_user(request)
-        if _user:
-            _db = _SL()
+    # 1. Validate filename syntax upfront, rejecting malformed requests (400)
+    # without probing the filesystem or database.
+    from src.generated_images import GENERATED_IMAGE_RE
+    if not isinstance(filename, str) or not GENERATED_IMAGE_RE.fullmatch(filename):
+        raise HTTPException(status_code=400, detail="Invalid filename")
+
+    # 2. Ownership verification:
+    # If auth is enabled, verify caller identity and ownership BEFORE probing disk,
+    # preventing existence oracles during outages or unauthorized requests.
+    from src.auth_helpers import auth_disabled, effective_user
+    if not auth_disabled():
+        _user = effective_user(request)
+        if not _user:
+            raise HTTPException(status_code=401, detail="Not authenticated")
+
+        from src.generated_images import get_registered_image_owner
+        _reg_owner = get_registered_image_owner(filename)
+        if _reg_owner is not None:
+            if _reg_owner != _user:
+                raise HTTPException(status_code=404, detail="Image not found")
+        else:
             try:
-                _row = _db.query(_GI).filter(_GI.filename == filename).first()
-                # Generated-but-not-yet-imported images have no row → allow.
-                # Row exists with a different owner → 404 (don't confirm existence).
-                if _row is not None and _row.owner and _row.owner != _user:
-                    raise HTTPException(status_code=404, detail="Image not found")
-            finally:
-                _db.close()
-    except HTTPException:
-        raise
-    except Exception as _e:
-        logger.warning("Image ownership verification failed for %r", filename, exc_info=_e)
+                from core.database import (
+                    SessionLocal as _SL,
+                    GalleryImage as _GI,
+                    Session as _DbSession,
+                    ChatMessage as _CM,
+                )
+                _db = _SL()
+                try:
+                    _row = _db.query(_GI).filter(_GI.filename == filename).first()
+                    if _row is not None:
+                        if _row.owner:
+                            if _row.owner != _user:
+                                raise HTTPException(status_code=404, detail="Image not found")
+                        elif _row.session_id:
+                            _sess = _db.query(_DbSession).filter(_DbSession.id == _row.session_id).first()
+                            if not _sess or not _sess.owner or _sess.owner != _user:
+                                raise HTTPException(status_code=404, detail="Image not found")
+                        else:
+                            # Gallery record has no owner or session link -> fail closed
+                            raise HTTPException(status_code=404, detail="Image not found")
+                    else:
+                        # Rowless image: check if referenced in a chat session owned by this user
+                        _chat_ref = (
+                            _db.query(_CM.id)
+                            .join(_DbSession, _CM.session_id == _DbSession.id)
+                            .filter(_DbSession.owner == _user, _CM.meta_data.like(f"%{filename}%"))
+                            .first()
+                        )
+                        if not _chat_ref:
+                            raise HTTPException(status_code=404, detail="Image not found")
+                finally:
+                    _db.close()
+            except HTTPException:
+                raise
+            except Exception as _e:
+                logger.warning("Image ownership verification failed for %r", filename, exc_info=_e)
+                raise HTTPException(status_code=503, detail="Ownership verification unavailable")
+
+    # 3. Resolve confined path and verify existence on disk
+    img_path = resolve_generated_image_path(filename)
+
     ext = filename.rsplit('.', 1)[-1].lower()
     mime = {
         "png": "image/png", "jpg": "image/jpeg", "jpeg": "image/jpeg",
@@ -545,10 +586,6 @@ async def serve_generated_image(filename: str, request: Request):
         "mp4": "video/mp4", "mov": "video/quicktime", "webm": "video/webm",
         "mkv": "video/x-matroska", "m4v": "video/mp4",
     }.get(ext, "application/octet-stream")
-    # Generated-image filenames are content hashes → the bytes for a given
-    # filename never change. Cache them hard so the gallery doesn't
-    # re-download every full-size image each time it's opened. `immutable`
-    # tells the browser it never needs to revalidate within the max-age.
     return FileResponse(
         str(img_path),
         media_type=mime,
diff --git a/mcp_servers/image_gen_server.py b/mcp_servers/image_gen_server.py
index 6b68a27f8..697522e3d 100644
--- a/mcp_servers/image_gen_server.py
+++ b/mcp_servers/image_gen_server.py
@@ -139,6 +139,7 @@ async def call_tool(name: str, arguments: dict) -> list[TextContent]:
                 # Save to gallery
                 try:
                     from src.database import SessionLocal, GalleryImage
+                    owner = str(arguments.get("_odysseus_owner") or "").strip() or None
                     db = SessionLocal()
                     db.add(GalleryImage(
                         id=str(uuid.uuid4()),
@@ -147,9 +148,16 @@ async def call_tool(name: str, arguments: dict) -> list[TextContent]:
                         model=model_id,
                         size=size,
                         quality=payload.get("quality", "medium"),
+                        owner=owner,
                     ))
                     db.commit()
                     db.close()
+                    if owner:
+                        try:
+                            from src.generated_images import register_generated_image
+                            register_generated_image(filename, owner)
+                        except Exception:
+                            pass
                 except Exception:
                     pass
 
diff --git a/src/ai_interaction.py b/src/ai_interaction.py
index 9890ed549..c8f7979ca 100644
--- a/src/ai_interaction.py
+++ b/src/ai_interaction.py
@@ -1372,6 +1372,9 @@ async def do_generate_image(content: str, session_id: Optional[str] = None, owne
                 filename = f"{uuid.uuid4().hex[:12]}.png"
                 img_path = img_dir / filename
                 img_path.write_bytes(base64.b64decode(img.get("b64_json")))
+                if owner:
+                    from src.generated_images import register_generated_image
+                    register_generated_image(filename, owner)
                 image_url = f"/api/generated-image/{filename}"
                 image_id = _save_to_gallery(filename)
 
@@ -1392,6 +1395,9 @@ async def do_generate_image(content: str, session_id: Optional[str] = None, owne
                         filename = f"{uuid.uuid4().hex[:12]}.png"
                         img_path = img_dir / filename
                         img_path.write_bytes(dl_resp.content)
+                        if owner:
+                            from src.generated_images import register_generated_image
+                            register_generated_image(filename, owner)
                         image_url = f"/api/generated-image/{filename}"
                         image_id = _save_to_gallery(filename)
                     else:
@@ -1537,6 +1543,9 @@ async def do_edit_image(
         img_dir.mkdir(parents=True, exist_ok=True)
         filename = f"{uuid.uuid4().hex[:12]}{suffix}"
         (img_dir / filename).write_bytes(image_bytes)
+        if owner:
+            from src.generated_images import register_generated_image
+            register_generated_image(filename, owner)
         return f"/api/generated-image/{filename}", _save_edited_image_to_gallery(filename)
 
     async def _try_local_img2img_fallback(client: httpx.AsyncClient) -> Optional[Dict[str, Any]]:
diff --git a/src/generated_images.py b/src/generated_images.py
index 8c312cd99..012c3c568 100644
--- a/src/generated_images.py
+++ b/src/generated_images.py
@@ -1,5 +1,8 @@
 import re
+import threading
+import time
 from pathlib import Path
+from typing import Optional
 
 from fastapi import HTTPException
 
@@ -12,10 +15,47 @@ GENERATED_IMAGE_RE = re.compile(
     r"^[a-f0-9]{8,64}\.(png|jpg|jpeg|webp|gif|mp4|mov|webm|mkv|m4v)$"
 )
 GENERATED_IMAGE_HEADERS = {
-    "Cache-Control": "public, max-age=31536000, immutable",
+    "Cache-Control": "private, no-cache, must-revalidate",
     "X-Content-Type-Options": "nosniff",
 }
 
+_RECENT_GENERATED_IMAGES: dict[str, tuple[str, float]] = {}
+_RECENT_IMAGES_LOCK = threading.Lock()
+_RECENT_IMAGES_TTL = 3600  # 1 hour TTL
+
+
+def register_generated_image(filename: str, owner: Optional[str]) -> None:
+    """Record ownership of a freshly generated image.
+
+    Ensures legitimate access to freshly generated images even before
+    or in case Gallery database records are created/committed.
+    """
+    if not filename or not owner:
+        return
+    now = time.time()
+    with _RECENT_IMAGES_LOCK:
+        if len(_RECENT_GENERATED_IMAGES) > 200:
+            expired = [k for k, (_, exp) in _RECENT_GENERATED_IMAGES.items() if exp < now]
+            for k in expired:
+                _RECENT_GENERATED_IMAGES.pop(k, None)
+        _RECENT_GENERATED_IMAGES[filename] = (owner, now + _RECENT_IMAGES_TTL)
+
+
+def get_registered_image_owner(filename: str) -> Optional[str]:
+    """Return the owner of a freshly generated image if still valid in the registry."""
+    if not filename:
+        return None
+    now = time.time()
+    with _RECENT_IMAGES_LOCK:
+        entry = _RECENT_GENERATED_IMAGES.get(filename)
+        if not entry:
+            return None
+        owner, expiry = entry
+        if now > expiry:
+            _RECENT_GENERATED_IMAGES.pop(filename, None)
+            return None
+        return owner
+
 
 def resolve_generated_image_path(filename: str) -> Path:
     if not isinstance(filename, str) or not GENERATED_IMAGE_RE.fullmatch(filename):
@@ -27,3 +67,4 @@ def resolve_generated_image_path(filename: str) -> Path:
     if not path.exists():
         raise HTTPException(status_code=404, detail="Image not found")
     return path
+
diff --git a/src/tool_execution.py b/src/tool_execution.py
index a83727422..599eade99 100644
--- a/src/tool_execution.py
+++ b/src/tool_execution.py
@@ -1317,7 +1317,8 @@ def _parse_qualified_mcp_args(tool: str, content: str) -> tuple[Dict, Optional[s
         if tool.startswith("mcp__email__"):
             return {}, "Email MCP tool arguments must be a JSON object."
         return {}, None
-    return parsed, None
+    sanitized = {k: v for k, v in parsed.items() if not k.startswith("_odysseus_")}
+    return sanitized, None
 
 
 def _parse_generate_image(content: str) -> Dict:
@@ -1402,9 +1403,12 @@ def _build_mcp_args(tool: str, content: str) -> Dict:
         except (json.JSONDecodeError, TypeError):
             decoded = None
         if isinstance(decoded, dict) and any(k in decoded for k in primaries):
-            return decoded
+            return {k: v for k, v in decoded.items() if not k.startswith("_odysseus_")}
     parser = _MCP_ARG_PARSERS.get(tool)
-    return parser(content) if parser else {}
+    res = parser(content) if parser else {}
+    if isinstance(res, dict):
+        return {k: v for k, v in res.items() if not k.startswith("_odysseus_")}
+    return res
 
 
 def _normalize_mcp_text_error(result: Dict) -> Dict:
@@ -1421,20 +1425,25 @@ async def _call_mcp_tool(
     tool: str,
     content: str,
     progress_cb: Optional[Callable[[Dict], Awaitable[None]]] = None,
+    owner: Optional[str] = None,
 ) -> Dict:
     """Route a legacy tool call through the MCP manager, with direct fallbacks."""
     bound = active_backend_operation()
     if bound is not None and isinstance(bound.resource, NativeBackendResource):
-        return await _direct_fallback(tool, content, progress_cb=progress_cb) or {"error": f"Native tool '{tool}' unavailable", "exit_code": 1}
+        return await _direct_fallback(tool, content, progress_cb=progress_cb, owner=owner) or {"error": f"Native tool '{tool}' unavailable", "exit_code": 1}
     mcp = get_mcp_manager()
     if not mcp:
         if bound is not None:
             raise ResourceIdentityError("Pinned MCP backend is unavailable")
-        return await _direct_fallback(tool, content, progress_cb=progress_cb) or {"error": f"MCP manager not available for tool '{tool}'", "exit_code": 1}
+        return await _direct_fallback(tool, content, progress_cb=progress_cb, owner=owner) or {"error": f"MCP manager not available for tool '{tool}'", "exit_code": 1}
 
     server_id, tool_name = _MCP_TOOL_MAP[tool]
     qualified = f"mcp__{server_id}__{tool_name}"
     args = _build_mcp_args(tool, content)
+    if tool == "generate_image":
+        args.pop("_odysseus_owner", None)
+        if owner:
+            args["_odysseus_owner"] = owner
     result = await mcp.call_tool(qualified, args)
 
     # Stdio MCP servers can only return TextContent, so an explicit
@@ -1444,7 +1453,7 @@ async def _call_mcp_tool(
 
     # If MCP server not connected, try direct fallback
     if bound is None and isinstance(result, dict) and result.get("exit_code") == 1 and "not connected" in result.get("error", ""):
-        fallback = await _direct_fallback(tool, content, progress_cb=progress_cb)
+        fallback = await _direct_fallback(tool, content, progress_cb=progress_cb, owner=owner)
         if fallback:
             return fallback
 
@@ -2193,7 +2202,7 @@ async def _execute_tool_block_impl(
     elif tool in _MCP_TOOL_MAP:
         first_line = content.split(chr(10))[0][:80]
         desc = f"{tool}: {first_line}"
-        result = await dispatched(_call_mcp_tool(tool, content, progress_cb=progress_cb))
+        result = await dispatched(_call_mcp_tool(tool, content, progress_cb=progress_cb, owner=owner))
     elif tool in ("grep", "glob", "ls", "get_workspace", "host_shell"):
         # Code-navigation tools — no MCP server; run the direct implementation.
         first_line = content.split(chr(10))[0][:80]
@@ -2379,7 +2388,7 @@ async def _execute_tool_block_impl(
                     )
                 else:
                     if isinstance(parsed, dict):
-                        args = parsed
+                        args = {k: v for k, v in parsed.items() if not k.startswith("_odysseus_")}
                     else:
                         _args_error = (
                             f"'{tool}' arguments must be a JSON object, "
@@ -2388,11 +2397,12 @@ async def _execute_tool_block_impl(
             if _args_error is not None:
                 result = {"error": _args_error, "exit_code": 1}
             else:
+                args = dict(args)
+                args.pop(_EMAIL_MCP_OWNER_ARG, None)
+                args.pop(_EMAIL_MCP_SESSION_ARG, None)
                 if owner:
-                    args = dict(args)
                     args[_EMAIL_MCP_OWNER_ARG] = owner
                 if session_id:
-                    args = dict(args)
                     args[_EMAIL_MCP_SESSION_ARG] = session_id
                 result = await dispatched(mcp.call_tool(qualified, args))
         else:
@@ -2406,14 +2416,20 @@ async def _execute_tool_block_impl(
             if parse_error:
                 result = {"error": parse_error, "exit_code": 1}
             else:
+                args = dict(args)
+                args.pop("_odysseus_owner", None)
+                args.pop("_odysseus_session_id", None)
                 if tool.startswith("mcp__email__"):
                     if owner:
-                        args = dict(args)
                         args[_EMAIL_MCP_OWNER_ARG] = owner
                     if session_id:
-                        args = dict(args)
                         args[_EMAIL_MCP_SESSION_ARG] = session_id
+                elif tool == "mcp__image_gen__generate_image" or tool.startswith("mcp__image_gen__"):
+                    if owner:
+                        args["_odysseus_owner"] = owner
                 result = _normalize_mcp_text_error(await dispatched(mcp.call_tool(tool, args)))
+                if tool == "mcp__image_gen__generate_image" or tool.startswith("mcp__image_gen__"):
+                    _promote_image_fields(result)
         else:
             desc = f"mcp: {tool}"
             result = {"error": "MCP manager not available", "exit_code": 1}
diff --git a/tests/test_generated_image_confinement.py b/tests/test_generated_image_confinement.py
index 5628706cb..aec8effff 100644
--- a/tests/test_generated_image_confinement.py
+++ b/tests/test_generated_image_confinement.py
@@ -60,7 +60,7 @@ def test_generated_image_headers_include_nosniff():
     assert generated_images.GENERATED_IMAGE_HEADERS["X-Content-Type-Options"] == "nosniff"
     assert (
         generated_images.GENERATED_IMAGE_HEADERS["Cache-Control"]
-        == "public, max-age=31536000, immutable"
+        == "private, no-cache, must-revalidate"
     )
 
 
diff --git a/tests/test_generated_image_ownership.py b/tests/test_generated_image_ownership.py
new file mode 100644
index 000000000..7075366b9
--- /dev/null
+++ b/tests/test_generated_image_ownership.py
@@ -0,0 +1,493 @@
+import os
+from unittest.mock import MagicMock, patch
+import pytest
+from fastapi import HTTPException
+from starlette.requests import Request
+
+from app import serve_generated_image
+from src.generated_images import (
+    GENERATED_IMAGE_HEADERS,
+    register_generated_image,
+)
+
+
+class DummyState:
+    def __init__(self, current_user=None, api_token=False, api_token_owner=None):
+        self.current_user = current_user
+        self.api_token = api_token
+        self.api_token_owner = api_token_owner
+
+
+def _make_request(current_user=None, api_token=False, api_token_owner=None):
+    req = MagicMock(spec=Request)
+    req.state = DummyState(current_user, api_token, api_token_owner)
+    return req
+
+
+@pytest.fixture
+def sample_image(tmp_path, monkeypatch):
+    from src import generated_images
+    image_dir = tmp_path / "generated_images"
+    image_dir.mkdir(parents=True, exist_ok=True)
+    filename = "0123456789ab.png"
+    img_file = image_dir / filename
+    img_file.write_bytes(b"\x89PNG\r\n\x1a\nfake-image-bytes")
+    monkeypatch.setattr(generated_images, "GENERATED_IMAGE_DIR", image_dir)
+    return filename
+
+
+@pytest.mark.asyncio
+async def test_authorized_cookie_session_owner(sample_image):
+    """Cookie session owner receives 200 for their owned image."""
+    req = _make_request(current_user="alice")
+    mock_row = MagicMock()
+    mock_row.owner = "alice"
+    mock_row.filename = sample_image
+
+    with patch("src.auth_helpers.auth_disabled", return_value=False), \
+         patch("core.database.SessionLocal") as mock_sl:
+        mock_db = MagicMock()
+        mock_db.query.return_value.filter.return_value.first.return_value = mock_row
+        mock_sl.return_value = mock_db
+
+        resp = await serve_generated_image(sample_image, req)
+        assert resp.status_code == 200
+        assert resp.headers["Cache-Control"] == "private, no-cache, must-revalidate"
+        assert resp.headers["X-Content-Type-Options"] == "nosniff"
+
+
+@pytest.mark.asyncio
+async def test_authorized_api_token_owner(sample_image):
+    """API token request matching image owner receives 200."""
+    req = _make_request(current_user="api", api_token=True, api_token_owner="alice")
+    mock_row = MagicMock()
+    mock_row.owner = "alice"
+    mock_row.filename = sample_image
+
+    with patch("src.auth_helpers.auth_disabled", return_value=False), \
+         patch("core.database.SessionLocal") as mock_sl:
+        mock_db = MagicMock()
+        mock_db.query.return_value.filter.return_value.first.return_value = mock_row
+        mock_sl.return_value = mock_db
+
+        resp = await serve_generated_image(sample_image, req)
+        assert resp.status_code == 200
+
+
+@pytest.mark.asyncio
+async def test_cross_user_denial_returns_404(sample_image):
+    """Bob attempting to access Alice's image receives 404 (preventing existence leak)."""
+    req = _make_request(current_user="bob")
+    mock_row = MagicMock()
+    mock_row.owner = "alice"
+    mock_row.filename = sample_image
+
+    with patch("src.auth_helpers.auth_disabled", return_value=False), \
+         patch("core.database.SessionLocal") as mock_sl:
+        mock_db = MagicMock()
+        mock_db.query.return_value.filter.return_value.first.return_value = mock_row
+        mock_sl.return_value = mock_db
+
+        with pytest.raises(HTTPException) as exc_info:
+            await serve_generated_image(sample_image, req)
+        assert exc_info.value.status_code == 404
+        assert exc_info.value.detail == "Image not found"
+
+
+@pytest.mark.asyncio
+async def test_cross_user_api_token_denial_returns_404(sample_image):
+    """Bob's API token attempting to access Alice's image receives 404."""
+    req = _make_request(current_user="api", api_token=True, api_token_owner="bob")
+    mock_row = MagicMock()
+    mock_row.owner = "alice"
+    mock_row.filename = sample_image
+
+    with patch("src.auth_helpers.auth_disabled", return_value=False), \
+         patch("core.database.SessionLocal") as mock_sl:
+        mock_db = MagicMock()
+        mock_db.query.return_value.filter.return_value.first.return_value = mock_row
+        mock_sl.return_value = mock_db
+
+        with pytest.raises(HTTPException) as exc_info:
+            await serve_generated_image(sample_image, req)
+        assert exc_info.value.status_code == 404
+
+
+@pytest.mark.asyncio
+async def test_unauthenticated_request_rejected(sample_image):
+    """Unauthenticated caller (no user identity) is rejected with 401 when auth is enabled."""
+    req = _make_request(current_user=None)
+
+    with patch("src.auth_helpers.auth_disabled", return_value=False):
+        with pytest.raises(HTTPException) as exc_info:
+            await serve_generated_image(sample_image, req)
+        assert exc_info.value.status_code == 401
+        assert exc_info.value.detail == "Not authenticated"
+
+
+@pytest.mark.asyncio
+async def test_missing_gallery_row_fails_closed_404(sample_image):
+    """Image on disk with no gallery row, no registry, and no chat reference returns 404."""
+    req = _make_request(current_user="bob")
+
+    with patch("src.auth_helpers.auth_disabled", return_value=False), \
+         patch("core.database.SessionLocal") as mock_sl:
+        mock_db = MagicMock()
+        # No gallery row
+        mock_db.query.return_value.filter.return_value.first.return_value = None
+        # No chat message reference
+        mock_db.query.return_value.join.return_value.filter.return_value.first.return_value = None
+        mock_sl.return_value = mock_db
+
+        with pytest.raises(HTTPException) as exc_info:
+            await serve_generated_image(sample_image, req)
+        assert exc_info.value.status_code == 404
+        assert exc_info.value.detail == "Image not found"
+
+
+@pytest.mark.asyncio
+async def test_null_owner_metadata_fails_closed_404(sample_image):
+    """Gallery row with owner=None and no session link returns 404."""
+    req = _make_request(current_user="bob")
+    mock_row = MagicMock()
+    mock_row.owner = None
+    mock_row.session_id = None
+    mock_row.filename = sample_image
+
+    with patch("src.auth_helpers.auth_disabled", return_value=False), \
+         patch("core.database.SessionLocal") as mock_sl:
+        mock_db = MagicMock()
+        mock_db.query.return_value.filter.return_value.first.return_value = mock_row
+        mock_sl.return_value = mock_db
+
+        with pytest.raises(HTTPException) as exc_info:
+            await serve_generated_image(sample_image, req)
+        assert exc_info.value.status_code == 404
+
+
+@pytest.mark.asyncio
+async def test_session_linked_null_owner_authorized(sample_image):
+    """Gallery row with owner=None resolves owner through session_id."""
+    req_alice = _make_request(current_user="alice")
+    req_bob = _make_request(current_user="bob")
+
+    mock_row = MagicMock()
+    mock_row.owner = None
+    mock_row.session_id = "sess-123"
+    mock_row.filename = sample_image
+
+    mock_sess = MagicMock()
+    mock_sess.owner = "alice"
+
+    with patch("src.auth_helpers.auth_disabled", return_value=False), \
+         patch("core.database.SessionLocal") as mock_sl:
+        mock_db = MagicMock()
+        mock_db.query.return_value.filter.return_value.first.side_effect = [
+            mock_row, mock_sess,  # for Alice
+            mock_row, mock_sess,  # for Bob
+        ]
+        mock_sl.return_value = mock_db
+
+        # Alice is the session owner -> 200
+        resp = await serve_generated_image(sample_image, req_alice)
+        assert resp.status_code == 200
+
+        # Bob is not the session owner -> 404
+        with pytest.raises(HTTPException) as exc_info:
+            await serve_generated_image(sample_image, req_bob)
+        assert exc_info.value.status_code == 404
+
+
+@pytest.mark.asyncio
+async def test_chat_referenced_rowless_image_authorized(sample_image):
+    """Rowless image referenced in a chat session owned by user is authorized."""
+    req_alice = _make_request(current_user="alice")
+    req_bob = _make_request(current_user="bob")
+
+    with patch("src.auth_helpers.auth_disabled", return_value=False), \
+         patch("core.database.SessionLocal") as mock_sl:
+        mock_db = MagicMock()
+        # Row is None
+        mock_db.query.return_value.filter.return_value.first.return_value = None
+        # Alice's chat query returns a match, Bob's does not
+        mock_db.query.return_value.join.return_value.filter.return_value.first.side_effect = [
+            MagicMock(),  # Alice has a match
+            None,         # Bob has no match
+        ]
+        mock_sl.return_value = mock_db
+
+        resp = await serve_generated_image(sample_image, req_alice)
+        assert resp.status_code == 200
+
+        with pytest.raises(HTTPException) as exc_info:
+            await serve_generated_image(sample_image, req_bob)
+        assert exc_info.value.status_code == 404
+
+
+@pytest.mark.asyncio
+async def test_freshly_generated_registry_preserves_access(sample_image):
+    """Freshly generated image registered to Alice is accessible before DB commit; Bob is denied."""
+    req_alice = _make_request(current_user="alice")
+    req_bob = _make_request(current_user="bob")
+
+    fresh_filename = "fedcba987654.png"
+    from src import generated_images
+    img_file = generated_images.GENERATED_IMAGE_DIR / fresh_filename
+    img_file.write_bytes(b"\x89PNG\r\n\x1a\nfake-image-bytes")
+
+    register_generated_image(fresh_filename, "alice")
+
+    with patch("src.auth_helpers.auth_disabled", return_value=False), \
+         patch("core.database.SessionLocal") as mock_sl:
+        mock_sl.side_effect = AssertionError("DB should not be reached for registered owner")
+
+        # Alice retrieves without hitting DB
+        resp = await serve_generated_image(fresh_filename, req_alice)
+        assert resp.status_code == 200
+
+        # Bob is denied with 404
+        with pytest.raises(HTTPException) as exc_info:
+            await serve_generated_image(fresh_filename, req_bob)
+        assert exc_info.value.status_code == 404
+
+
+@pytest.mark.asyncio
+async def test_database_failure_fails_closed_503(sample_image):
+    """Database exception during ownership check raises HTTP 503."""
+    req = _make_request(current_user="alice")
+
+    with patch("src.auth_helpers.auth_disabled", return_value=False), \
+         patch("core.database.SessionLocal") as mock_sl:
+        mock_db = MagicMock()
+        mock_db.query.side_effect = RuntimeError("SQLite database locked or corrupted")
+        mock_sl.return_value = mock_db
+
+        with pytest.raises(HTTPException) as exc_info:
+            await serve_generated_image(sample_image, req)
+        assert exc_info.value.status_code == 503
+        assert exc_info.value.detail == "Ownership verification unavailable"
+
+
+@pytest.mark.asyncio
+async def test_no_login_compatibility_auth_disabled(sample_image):
+    """When AUTH_ENABLED=false, existing images are served with 200, missing images return 404."""
+    req = _make_request(current_user=None)
+
+    with patch("src.auth_helpers.auth_disabled", return_value=True):
+        resp = await serve_generated_image(sample_image, req)
+        assert resp.status_code == 200
+
+        with pytest.raises(HTTPException) as exc_info:
+            await serve_generated_image("aaaaaaaaaaaa.png", req)
+        assert exc_info.value.status_code == 404
+
+
+def test_cache_headers_private_no_cache():
+    """Verify generated image response headers use private, no-cache directives."""
+    assert GENERATED_IMAGE_HEADERS["Cache-Control"] == "private, no-cache, must-revalidate"
+    assert GENERATED_IMAGE_HEADERS["X-Content-Type-Options"] == "nosniff"
+
+
+@pytest.mark.asyncio
+async def test_existence_oracle_eliminated_during_outage(sample_image):
+    """During a DB outage, both existing and non-existent files return 503 without revealing existence."""
+    req = _make_request(current_user="alice")
+
+    with patch("src.auth_helpers.auth_disabled", return_value=False), \
+         patch("core.database.SessionLocal") as mock_sl:
+        mock_db = MagicMock()
+        mock_db.query.side_effect = RuntimeError("DB down")
+        mock_sl.return_value = mock_db
+
+        # Existing file -> 503
+        with pytest.raises(HTTPException) as exc_existing:
+            await serve_generated_image(sample_image, req)
+        assert exc_existing.value.status_code == 503
+
+        # Non-existent file -> 503 (NOT 404)
+        with pytest.raises(HTTPException) as exc_missing:
+            await serve_generated_image("111122223333.png", req)
+        assert exc_missing.value.status_code == 503
+
+
+@pytest.mark.asyncio
+async def test_mcp_image_generation_passes_owner_arg():
+    """_call_mcp_tool passes _odysseus_owner to MCP arguments for generate_image."""
+    from src import tool_execution
+
+    mock_mcp = MagicMock()
+    mock_mcp.call_tool = MagicMock()
+
+    async def fake_call(qualified, args):
+        return {"stdout": "Generated image for: cat\nhttps://host/api/generated-image/1234567890ab.png", "exit_code": 0}
+
+    mock_mcp.call_tool.side_effect = fake_call
+
+    with patch.object(tool_execution, "get_mcp_manager", return_value=mock_mcp), \
+         patch.object(tool_execution, "active_backend_operation", return_value=None):
+        res = await tool_execution._call_mcp_tool("generate_image", "cat", owner="alice")
+        assert res.get("image_url") == "https://host/api/generated-image/1234567890ab.png"
+        call_args = mock_mcp.call_tool.call_args[0]
+        assert call_args[1].get("_odysseus_owner") == "alice"
+
+
+@pytest.mark.asyncio
+async def test_mcp_fallback_propagates_owner():
+    """When MCP manager is unavailable, _direct_fallback receives owner."""
+    from src import tool_execution
+
+    with patch.object(tool_execution, "get_mcp_manager", return_value=None), \
+         patch.object(tool_execution, "active_backend_operation", return_value=None), \
+         patch.object(tool_execution, "_direct_fallback", return_value={"output": "ok", "exit_code": 0}) as mock_fallback:
+        res = await tool_execution._call_mcp_tool("web_search", "query", owner="alice")
+        assert res == {"output": "ok", "exit_code": 0}
+        mock_fallback.assert_called_once_with("web_search", "query", progress_cb=None, owner="alice")
+
+
+@pytest.mark.asyncio
+async def test_trusted_owner_overrides_forged_owner_in_tool_args():
+    """Trusted owner overrides any forged _odysseus_owner in tool block content."""
+    import json
+    from src import tool_execution
+
+    mock_mcp = MagicMock()
+    mock_mcp.call_tool = MagicMock()
+
+    async def fake_call(qualified, args):
+        return {"stdout": "Generated image for: cat\n/api/generated-image/1234567890ab.png", "exit_code": 0}
+
+    mock_mcp.call_tool.side_effect = fake_call
+    forged_content = json.dumps({"prompt": "cat", "_odysseus_owner": "bob"})
+
+    with patch.object(tool_execution, "get_mcp_manager", return_value=mock_mcp), \
+         patch.object(tool_execution, "active_backend_operation", return_value=None):
+        await tool_execution._call_mcp_tool("generate_image", forged_content, owner="alice")
+        call_args = mock_mcp.call_tool.call_args[0]
+        assert call_args[1].get("_odysseus_owner") == "alice"
+
+
+@pytest.mark.asyncio
+async def test_missing_or_empty_owner_removes_forged_owner_claim():
+    """When caller has no trusted owner (None or empty), forged _odysseus_owner is completely removed."""
+    import json
+    from src import tool_execution
+
+    mock_mcp = MagicMock()
+    mock_mcp.call_tool = MagicMock()
+
+    async def fake_call(qualified, args):
+        return {"stdout": "Generated image for: cat\n/api/generated-image/1234567890ab.png", "exit_code": 0}
+
+    mock_mcp.call_tool.side_effect = fake_call
+    forged_content = json.dumps({"prompt": "cat", "_odysseus_owner": "bob"})
+
+    with patch.object(tool_execution, "get_mcp_manager", return_value=mock_mcp), \
+         patch.object(tool_execution, "active_backend_operation", return_value=None):
+        # Case 1: owner=None
+        await tool_execution._call_mcp_tool("generate_image", forged_content, owner=None)
+        call_args = mock_mcp.call_tool.call_args[0]
+        assert "_odysseus_owner" not in call_args[1]
+
+        # Case 2: owner=""
+        await tool_execution._call_mcp_tool("generate_image", forged_content, owner="")
+        call_args = mock_mcp.call_tool.call_args[0]
+        assert "_odysseus_owner" not in call_args[1]
+
+
+@pytest.mark.asyncio
+async def test_qualified_mcp_image_gen_sanitizes_forged_owner():
+    """Qualified mcp__image_gen__generate_image tool dispatches with sanitized owner."""
+    import json
+    from unittest.mock import AsyncMock
+    from src import tool_execution
+    from src.tool_types import ToolBlock
+
+    mock_mcp = MagicMock()
+    mock_mcp.call_tool = AsyncMock(return_value={"stdout": "ok", "exit_code": 0})
+    forged_content = json.dumps({"prompt": "cat", "_odysseus_owner": "bob"})
+
+    with patch.object(tool_execution, "get_mcp_manager", return_value=mock_mcp), \
+         patch.object(tool_execution, "_owner_is_admin", return_value=True):
+        # With trusted owner 'alice' -> sets 'alice'
+        await tool_execution._execute_tool_block_impl(
+            ToolBlock("mcp__image_gen__generate_image", forged_content),
+            owner="alice",
+        )
+        call_args = mock_mcp.call_tool.call_args[0]
+        assert call_args[1].get("_odysseus_owner") == "alice"
+
+        # Without owner -> removes forged owner
+        await tool_execution._execute_tool_block_impl(
+            ToolBlock("mcp__image_gen__generate_image", forged_content),
+            owner=None,
+        )
+        call_args = mock_mcp.call_tool.call_args[0]
+        assert "_odysseus_owner" not in call_args[1]
+
+
+@pytest.mark.asyncio
+async def test_mcp_disconnected_fallback_does_not_resurrect_forged_owner():
+    """When MCP is disconnected, direct fallback receives verified owner context, not forged arguments."""
+    import json
+    from src import tool_execution
+
+    mock_mcp = MagicMock()
+    mock_mcp.call_tool = MagicMock()
+
+    async def fake_call(qualified, args):
+        return {"error": "Server not connected", "exit_code": 1}
+
+    mock_mcp.call_tool.side_effect = fake_call
+    forged_content = json.dumps({"query": "python", "_odysseus_owner": "bob"})
+
+    with patch.object(tool_execution, "get_mcp_manager", return_value=mock_mcp), \
+         patch.object(tool_execution, "active_backend_operation", return_value=None), \
+         patch.object(tool_execution, "_direct_fallback", return_value={"output": "ok", "exit_code": 0}) as mock_fallback:
+        # Trusted owner=None: mock_fallback receives owner=None
+        await tool_execution._call_mcp_tool("web_search", forged_content, owner=None)
+        mock_fallback.assert_called_with("web_search", forged_content, progress_cb=None, owner=None)
+
+        # Trusted owner="alice": mock_fallback receives owner="alice"
+        await tool_execution._call_mcp_tool("web_search", forged_content, owner="alice")
+        mock_fallback.assert_called_with("web_search", forged_content, progress_cb=None, owner="alice")
+
+
+@pytest.mark.asyncio
+async def test_image_gen_server_owner_sanitization():
+    """mcp_servers.image_gen_server sanitizes whitespace, empty, and None owner claims."""
+    from unittest.mock import AsyncMock
+    from mcp_servers import image_gen_server
+
+    with patch("src.database.SessionLocal") as mock_sl, \
+         patch("httpx.AsyncClient") as mock_http, \
+         patch("src.ai_interaction._resolve_model", return_value=("https://host/v1/chat/completions", "gpt-image-1", {})), \
+         patch("src.settings.get_setting", return_value="dummy_key"), \
+         patch("src.settings.load_settings", return_value={"image_model": "gpt-image-1"}), \
+         patch("pathlib.Path.write_bytes"):
+        mock_db = MagicMock()
+        mock_sl.return_value = mock_db
+
+        mock_resp = MagicMock()
+        mock_resp.status_code = 200
+        mock_resp.json.return_value = {
+            "data": [{"b64_json": "aGVsbG8="}]
+        }
+        mock_client = MagicMock()
+        mock_client.post = AsyncMock(return_value=mock_resp)
+        mock_http.return_value.__aenter__.return_value = mock_client
+
+        # Call with whitespace owner: "   " -> owner becomes None
+        await image_gen_server.call_tool(
+            "generate_image",
+            {"prompt": "cat", "_odysseus_owner": "   "},
+        )
+        added = mock_db.add.call_args[0][0]
+        assert added.owner is None
+
+        # Call with valid owner: "alice" -> owner becomes "alice"
+        await image_gen_server.call_tool(
+            "generate_image",
+            {"prompt": "cat", "_odysseus_owner": "alice"},
+        )
+        added = mock_db.add.call_args[0][0]
+        assert added.owner == "alice"

From c3819e3cbf56c4f899eacc66b21115a77d9c570d Mon Sep 17 00:00:00 2001
From: Nguyen Thanh Dat <ntdat812.dev@gmail.com>
Date: Wed, 14 Oct 2026 18:20:35 +0700
Subject: [PATCH 16/53] fix(docker): mount the ChromaDB volume where the image
 actually persists (#6166)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* fix(docker): mount the ChromaDB volume where the image actually persists

chromadb/chroma runs `chroma run /config.yaml`, and that config is one line:
persist_path: "/data". The image declares no VOLUME, so everything the store
writes lives in the container's writable layer. The chromadb-data volume was
mounted at /chroma/chroma — where pre-1.0 images kept the store — so it caught
nothing and the entire vector store was destroyed on every container recreate.

Nothing errors when that happens. The collection survives with a count of 0, so
retrieval simply returns nothing from then on, which reads as "no match".

docs/backup-restore.md tells users to archive the chromadb-data volume, which
means the documented backup was empty too.

Fixed in all three compose files. The volume was never written to, so there is
nothing to migrate.

* fix(tests,docs): harden volume-path test helper and document upgrade migration

tests/test_chromadb_volume_path.py
- _chromadb_volumes() now normalises long-form dict volume entries
  (source/target/type map) to 'source:target' strings, preventing
  AttributeError crashes if a future Compose change uses that syntax.
- test_chromadb_does_not_use_the_pre_1_0_path now uses split(':')[1]
  comparison instead of endswith(), so mount-option suffixes (:z, :ro)
  cannot mask a wrong legacy target path.
- Three new unit tests validate the helper against both YAML syntaxes
  and the mount-option edge case explicitly.

docs/chromadb-volume-migration.md (new)
- Step-by-step guide for users upgrading from pre-#6166 Docker installs
  whose ChromaDB data accumulated in the container's writable layer.
- Covers: detecting the situation, backing up via 'docker cp', seeding
  the named volume before recreating the container, verification, and
  rollback. Validated with disposable Docker volumes.
- Distinguishes fresh installs (no action needed) from existing
  installs with live writable-layer data (action needed before recreate).

docs/backup-restore.md
- Extended ChromaDB caveat block to cross-reference the new migration
  guide for users upgrading from pre-#6166.

Closes the P1 documentation gap and P2/P3 test-robustness findings
from the PR #6166 adversarial review.

* fix(docs,tests): eliminate ChromaDB migration data-loss risks and enforce safe cutover

- Require service quiescence before cold database copy to prevent torn SQLite pages
- Mandate container preservation via immutable Docker image commit before recreation
- Enforce positive empty check on destination volume prior to seeding
- Add staging container validation on an isolated loopback port before Compose cutover
- Provide verified rollback procedures prohibiting return to legacy /chroma/chroma mount
- Add regression test coverage for all migration safety invariants

---------

Co-authored-by: PR #6166 Reviewer <reviewer@odysseus-review.local>
---
 docker-compose.gpu-amd.yml         |   6 +-
 docker-compose.gpu-nvidia.yml      |   6 +-
 docker-compose.yml                 |   6 +-
 docs/chromadb-volume-migration.md  | 408 +++++++++++++++++++++++++++++
 tests/test_chromadb_volume_path.py | 220 ++++++++++++++++
 website/backup-restore.md          |   9 +
 6 files changed, 652 insertions(+), 3 deletions(-)
 create mode 100644 docs/chromadb-volume-migration.md
 create mode 100644 tests/test_chromadb_volume_path.py

diff --git a/docker-compose.gpu-amd.yml b/docker-compose.gpu-amd.yml
index 8e6702b43..183b31601 100644
--- a/docker-compose.gpu-amd.yml
+++ b/docker-compose.gpu-amd.yml
@@ -131,7 +131,11 @@ services:
     ports:
       - "${CHROMADB_BIND:-127.0.0.1}:8100:8000"
     volumes:
-      - chromadb-data:/chroma/chroma
+      # The image runs `chroma run /config.yaml`, whose persist_path is "/data".
+      # It declares no VOLUME, so anything written outside a mount lives in the
+      # container's writable layer and dies with it. /chroma/chroma is where
+      # pre-1.0 images kept the store; mounting there now catches nothing.
+      - chromadb-data:/data
     environment:
       - ANONYMIZED_TELEMETRY=FALSE
     restart: unless-stopped
diff --git a/docker-compose.gpu-nvidia.yml b/docker-compose.gpu-nvidia.yml
index eb3c9d7e3..23404b2eb 100644
--- a/docker-compose.gpu-nvidia.yml
+++ b/docker-compose.gpu-nvidia.yml
@@ -134,7 +134,11 @@ services:
     ports:
       - "${CHROMADB_BIND:-127.0.0.1}:8100:8000"
     volumes:
-      - chromadb-data:/chroma/chroma
+      # The image runs `chroma run /config.yaml`, whose persist_path is "/data".
+      # It declares no VOLUME, so anything written outside a mount lives in the
+      # container's writable layer and dies with it. /chroma/chroma is where
+      # pre-1.0 images kept the store; mounting there now catches nothing.
+      - chromadb-data:/data
     environment:
       - ANONYMIZED_TELEMETRY=FALSE
     restart: unless-stopped
diff --git a/docker-compose.yml b/docker-compose.yml
index 4fb49a45b..a7ddf2f04 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -112,7 +112,11 @@ services:
     ports:
       - "${CHROMADB_BIND:-127.0.0.1}:8100:8000"
     volumes:
-      - chromadb-data:/chroma/chroma
+      # The image runs `chroma run /config.yaml`, whose persist_path is "/data".
+      # It declares no VOLUME, so anything written outside a mount lives in the
+      # container's writable layer and dies with it. /chroma/chroma is where
+      # pre-1.0 images kept the store; mounting there now catches nothing.
+      - chromadb-data:/data
     environment:
       - ANONYMIZED_TELEMETRY=FALSE
     restart: unless-stopped
diff --git a/docs/chromadb-volume-migration.md b/docs/chromadb-volume-migration.md
new file mode 100644
index 000000000..4ec7853ac
--- /dev/null
+++ b/docs/chromadb-volume-migration.md
@@ -0,0 +1,408 @@
+# ChromaDB Volume Migration — Upgrading from pre-#6166 installs
+
+> [!IMPORTANT]
+> This guide is only for Docker-based installs that were deployed before PR #6166
+> was merged. Native host installs are unaffected (they persist to `data/chroma/`
+> on the host filesystem, which was always stored correctly).
+
+---
+
+## 1. What changed and why
+
+Before PR #6166, the `chromadb-data` named volume was mounted at `/chroma/chroma` inside
+the ChromaDB container. However, current `chromadb/chroma` images (version 1.0+) write their
+database to `/data` — configured by the container image's internal `/config.yaml` (`persist_path: "/data"`).
+Because the upstream ChromaDB image declares no `VOLUME` directive:
+
+* **Any vector data written to `/data` accumulated exclusively in the container's writable layer.**
+* The mounted `chromadb-data` named volume at `/chroma/chroma` remained completely empty.
+* Any recreation or removal of the container (`docker compose down`, `docker compose up --force-recreate`, `docker rm`)
+  permanently destroys that writable layer and all vector embeddings within it.
+
+PR #6166 corrects the mount target across all Compose configurations to `chromadb-data:/data`.
+
+Fresh installations will persist data directly to the named volume automatically. However, for
+**existing running installations**, the vector store currently resides in the old container's
+writable layer.
+
+This guide provides a zero-data-loss, fail-closed operational procedure to quiesce, preserve,
+back up, verify, seed, and validate that data before performing cutover.
+
+---
+
+## 2. Architecture and Safety Principles
+
+1. **No Live `docker cp`:** ChromaDB uses SQLite (`chroma.sqlite3`) and binary HNSW segment index
+   files (`data_level0.bin`, `header.bin`, `length.bin`, `link_lists.bin`). Taking a file copy while
+   the database engine is running risks capturing torn SQLite pages or out-of-sync HNSW graph segments.
+   Writers must be quiesced and ChromaDB gracefully stopped before copying files.
+2. **Do Not Trust `docker rename` Alone:** Docker Compose tracks containers by internal metadata labels
+   (`com.docker.compose.project`, `com.docker.compose.service`, `com.docker.compose.container-number`),
+   **not** merely by container name. Renaming a container does not strip its labels; Compose commands
+   can still discover, restart, or recreate it. To guarantee preservation of the writable layer, the
+   stopped container must be committed to an immutable Docker image (`docker commit`).
+3. **Never Overwrite Existing Volumes:** Named volumes must be positively verified as empty prior to seeding.
+4. **Staging Validation Before Production Cutover:** The seeded named volume must be independently validated
+   using a disposable ChromaDB instance on an isolated port before touching the production Compose deployment.
+5. **No Rollback to `/chroma/chroma`:** Rolling back to pre-#6166 Compose files reintroduces the broken
+   mount path where ChromaDB never looks. Rollback procedures must restore data into the corrected `/data` path
+   or redeploy from the immutable backup image.
+
+---
+
+## 3. Step-by-Step Migration Procedure
+
+### Step 0: Identify your project and volume names
+
+Docker Compose prefixes container and volume names with the project name (usually the root directory name).
+Identify yours before proceeding:
+
+```bash
+# Identify running ChromaDB container
+docker ps --filter "ancestor=chromadb/chroma" --format "table {{.ID}}\t{{.Status}}\t{{.Names}}"
+
+# Identify the named volume
+docker volume ls --filter "name=chromadb"
+```
+
+Throughout this guide:
+* `<project>` represents your Compose project (e.g. `odysseus` or `odysseus-maintainer-preview`).
+* `<container>` represents the running ChromaDB container (e.g. `<project>-chromadb-1`).
+* `<volume>` represents the named volume (e.g. `<project>_chromadb-data`).
+
+Set shell variables for convenience:
+```bash
+PROJECT="<project>"
+CONTAINER="${PROJECT}-chromadb-1"
+VOLUME="${PROJECT}_chromadb-data"
+```
+
+---
+
+### Step 1: Pre-Migration Collection Inventory (Baseline)
+
+Establish a baseline of all existing collections and their embedding counts through the live ChromaDB API:
+
+```bash
+# List all collections and record counts
+curl -s http://127.0.0.1:8100/api/v2/tenants/default_tenant/databases/default_database/collections \
+  | python3 -c '
+import json, sys, urllib.request
+data = json.load(sys.stdin)
+print(f"Total collections found: {len(data)}")
+for col in data:
+    c_id = col["id"]
+    name = col["name"]
+    try:
+        with urllib.request.urlopen(f"http://127.0.0.1:8100/api/v2/tenants/default_tenant/databases/default_database/collections/{c_id}/count") as resp:
+            count = resp.read().decode().strip()
+    except Exception as e:
+        count = f"error: {e}"
+    print(f"Collection: {name} (ID: {c_id}) -> Count: {count}")
+' | tee pre_migration_inventory.txt
+```
+
+Save `pre_migration_inventory.txt` securely. This baseline is used in Step 7 and Step 9 to verify
+zero data loss.
+
+---
+
+### Step 2: Quiesce Writers and Gracefully Stop ChromaDB
+
+To ensure transactional and referential consistency across SQLite and HNSW segment files:
+
+1. Stop application writers (Odysseus) to prevent any in-flight requests:
+   ```bash
+   docker compose stop odysseus
+   ```
+2. Gracefully stop the ChromaDB service. This permits SQLite to checkpoint the Write-Ahead Log (WAL)
+   and flushes all in-memory vector index segments to disk:
+   ```bash
+   docker compose stop chromadb
+   ```
+3. Confirm that the container status is `Exited`:
+   ```bash
+   docker ps -a --filter "name=${CONTAINER}" --format "table {{.ID}}\t{{.Status}}\t{{.Names}}"
+   ```
+   *Do not proceed if the container is still running.*
+
+---
+
+### Step 3: Preserve the Original Container as an Immutable Image
+
+Because Docker Compose discovers containers via service labels, running `docker compose up` later
+could recreate and destroy the original container's writable layer.
+
+Preserve the complete writable layer into an immutable Docker image:
+```bash
+BACKUP_IMAGE="${PROJECT}-chromadb-backup:pre-migration-$(date +%Y%m%d-%H%M%S)"
+docker commit "${CONTAINER}" "${BACKUP_IMAGE}"
+echo "Committed container writable layer to: ${BACKUP_IMAGE}"
+```
+
+Verify the image was created:
+```bash
+docker images "${BACKUP_IMAGE}"
+```
+
+This image is your ultimate insurance: even if all containers and volumes are deleted, your
+data remains safely archived in Docker's image store.
+
+---
+
+### Step 4: Take a Cold File Backup
+
+With the container stopped, copy the `/data` directory out to a dedicated host backup directory:
+
+```bash
+BACKUP_DIR="./chromadb-backup-$(date +%Y%m%d-%H%M%S)"
+mkdir -p "${BACKUP_DIR}"
+
+docker cp "${CONTAINER}:/data/." "${BACKUP_DIR}/"
+echo "Cold backup created at: ${BACKUP_DIR}"
+```
+
+---
+
+### Step 5: Verify Backup Integrity
+
+Never proceed to destructive cutover without verifying both SQLite and vector index structures.
+
+1. **Verify SQLite Database File:**
+   ```bash
+   test -s "${BACKUP_DIR}/chroma.sqlite3" || { echo "ERROR: chroma.sqlite3 is missing or 0 bytes"; exit 1; }
+   ```
+2. **Execute SQLite PRAGMA Integrity Check:**
+   ```bash
+   INTEGRITY=$(sqlite3 "${BACKUP_DIR}/chroma.sqlite3" "PRAGMA integrity_check;")
+   if [ "${INTEGRITY}" != "ok" ]; then
+       echo "ERROR: SQLite integrity check failed: ${INTEGRITY}"
+       exit 1
+   fi
+   echo "SQLite integrity check: OK"
+   ```
+3. **Verify Collections Table Structure:**
+   ```bash
+   sqlite3 "${BACKUP_DIR}/chroma.sqlite3" "SELECT id, name FROM collections;"
+   ```
+4. **Verify HNSW Index Binary Files:**
+   Vector representations are not stored inside SQLite; they are kept in segment directories under `/data`:
+   ```bash
+   find "${BACKUP_DIR}" -type f -name "*.bin"
+   ```
+   Ensure `.bin` files (`data_level0.bin`, `header.bin`, etc.) exist for indexed collections.
+
+---
+
+### Step 6: Verify Destination Volume is Empty and Seed Safely
+
+The named volume `${VOLUME}` must be empty before seeding. Under no circumstances should
+migration files be merged into a populated volume.
+
+1. **Positive Empty Check:**
+   ```bash
+   VOL_FILES=$(docker run --rm -v "${VOLUME}:/vol:ro" alpine ls -A /vol)
+   if [ -n "${VOL_FILES}" ]; then
+       echo "ERROR: Named volume ${VOLUME} already contains files: ${VOL_FILES}"
+       echo "Aborting migration to prevent overwriting existing volume data."
+       exit 1
+   fi
+   echo "Volume ${VOLUME} is empty and ready for seeding."
+   ```
+2. **Seed the Volume:**
+   Use a disposable Alpine container to populate the volume with exact ownership and permissions:
+   ```bash
+   docker run --rm \
+     -v "${VOLUME}:/target" \
+     -v "$(realpath "${BACKUP_DIR}"):/source:ro" \
+     alpine sh -c "cp -a /source/. /target/ && ls -la /target/"
+   ```
+3. **Verify Seeded Contents:**
+   ```bash
+   docker run --rm -v "${VOLUME}:/vol:ro" alpine ls -la /vol
+   ```
+
+---
+
+### Step 7: Staging Validation in an Isolated Disposable Container
+
+Before modifying your production Compose stack, validate that ChromaDB boots successfully from the
+seeded volume and serves all collections.
+
+1. **Start Disposable Staging Container:**
+   Run a temporary ChromaDB instance bound to an isolated loopback port (e.g. `127.0.0.1:18199`):
+   ```bash
+   docker run -d --name "${PROJECT}-chromadb-staging" \
+     -p 127.0.0.1:18199:8000 \
+     -v "${VOLUME}:/data" \
+     chromadb/chroma:latest
+
+   # Wait for staging ChromaDB to boot
+   sleep 4
+   curl -s http://127.0.0.1:18199/api/v2/heartbeat || { echo "Staging container failed to respond"; exit 1; }
+   ```
+2. **Compare Collection Counts with Baseline:**
+   ```bash
+   curl -s http://127.0.0.1:18199/api/v2/tenants/default_tenant/databases/default_database/collections \
+     | python3 -c '
+   import json, sys, urllib.request
+   data = json.load(sys.stdin)
+   print(f"Staging collections verified: {len(data)}")
+   for col in data:
+       c_id = col["id"]
+       name = col["name"]
+       with urllib.request.urlopen(f"http://127.0.0.1:18199/api/v2/tenants/default_tenant/databases/default_database/collections/{c_id}/count") as resp:
+           count = resp.read().decode().strip()
+       print(f"  {name}: {count} records")
+   '
+   ```
+   *Confirm that the output matches `pre_migration_inventory.txt` from Step 1.*
+
+3. **Tear Down Staging Container:**
+   ```bash
+   docker rm -f "${PROJECT}-chromadb-staging"
+   ```
+
+---
+
+### Step 8: Apply Updated Compose Files and Perform Production Cutover
+
+Once the seeded volume is proven healthy:
+
+1. Update your repository to the revision containing PR #6166:
+   ```bash
+   git pull
+   ```
+2. Verify the mount line in your Compose file:
+   ```bash
+   grep -E 'chromadb-data:/data' docker-compose.yml
+   ```
+3. Bring up the updated ChromaDB container:
+   ```bash
+   docker compose up -d chromadb
+   ```
+   Docker Compose will detect the updated mount configuration, replace the stopped container,
+   and attach `${VOLUME}` directly to `/data`.
+4. Bring up the application stack:
+   ```bash
+   docker compose up -d odysseus
+   ```
+
+---
+
+### Step 9: Post-Migration Production Verification
+
+1. **Confirm Mount Point:**
+   ```bash
+   docker inspect "${CONTAINER}" --format '{{range .Mounts}}{{.Name}} -> {{.Destination}}{{"\n"}}{{end}}'
+   ```
+   Expected output:
+   ```
+   <project>_chromadb-data -> /data
+   ```
+2. **Confirm Production Collection Counts:**
+   ```bash
+   curl -s http://127.0.0.1:8100/api/v2/tenants/default_tenant/databases/default_database/collections \
+     | python3 -c '
+   import json, sys, urllib.request
+   data = json.load(sys.stdin)
+   print(f"Production collections: {len(data)}")
+   for col in data:
+       c_id = col["id"]
+       name = col["name"]
+       with urllib.request.urlopen(f"http://127.0.0.1:8100/api/v2/tenants/default_tenant/databases/default_database/collections/{c_id}/count") as resp:
+           count = resp.read().decode().strip()
+       print(f"  {name}: {count} records")
+   '
+   ```
+3. **Application Verification:**
+   Log in to Odysseus, navigate to **Settings -> Memory**, and confirm that memory items,
+   tool embeddings, and RAG document queries operate normally.
+
+---
+
+## 4. Rollback Procedures
+
+### Scenario A: Failure During Staging (Before Compose Cutover)
+
+If staging verification in Step 7 fails or reveals discrepancies:
+1. Remove the staging container:
+   ```bash
+   docker rm -f "${PROJECT}-chromadb-staging"
+   ```
+2. Clear the failed destination volume:
+   ```bash
+   docker run --rm -v "${VOLUME}:/target" alpine sh -c "rm -rf /target/*"
+   ```
+3. Restart the original production container. Because the original container was only stopped (never recreated),
+   its writable layer remains completely intact:
+   ```bash
+   docker compose start chromadb
+   docker compose start odysseus
+   ```
+4. Verify production status on port 8100.
+
+---
+
+### Scenario B: Failure After Compose Cutover
+
+If an issue occurs after `docker compose up -d`:
+
+> [!CAUTION]
+> **Do not `git checkout` the pre-#6166 Compose file!**
+> In the pre-#6166 Compose file, `chromadb-data` was mounted to `/chroma/chroma`.
+> ChromaDB 1.0+ persists to `/data`, so checking out the old Compose file will cause
+> ChromaDB to ignore the restored volume and boot with an empty database.
+
+To restore service:
+1. **Option 1 — Restore from Verified Host Backup into the `/data` Volume:**
+   If the container failed due to data corruption during startup:
+   ```bash
+   docker compose stop chromadb
+   docker run --rm -v "${VOLUME}:/target" alpine sh -c "rm -rf /target/*"
+   docker run --rm \
+     -v "${VOLUME}:/target" \
+     -v "$(realpath "${BACKUP_DIR}"):/source:ro" \
+     alpine cp -a /source/. /target/
+   docker compose up -d chromadb
+   ```
+2. **Option 2 — Fallback to Committed Backup Image:**
+   If Compose cannot start ChromaDB with the volume:
+   ```bash
+   docker compose stop chromadb
+   docker run -d --name "${PROJECT}-chromadb-fallback" \
+     -p 127.0.0.1:8100:8000 \
+     "${BACKUP_IMAGE}"
+   ```
+   This immediately restores the exact pre-migration container state.
+
+---
+
+## 5. Post-Migration Cleanup (Explicit Authorization)
+
+Retain the host backup directory (`${BACKUP_DIR}`) and the backup Docker image (`${BACKUP_IMAGE}`)
+for at least 7 days until routine backups have succeeded.
+
+Once you are completely confident in system stability, manually clean up:
+```bash
+# Remove host backup
+rm -rf ./chromadb-backup-*
+
+# Remove backup Docker image
+docker rmi "${BACKUP_IMAGE}"
+```
+
+---
+
+## 6. Re-indexing (Disaster Recovery Only)
+
+If an installation has already destroyed its pre-#6166 container writable layer (e.g. prior to following
+this guide), the vector embeddings cannot be restored from disk. In this scenario:
+
+* **RAG Documents:** Re-upload files under **Settings -> Memory -> RAG**. Odysseus automatically re-chunks
+  and re-indexes documents upon upload.
+* **Semantic Memories:** Text memory records reside authoritatively in `data/app.db` (SQLite). Vector representations
+  are re-indexed automatically when Odysseus connects to a healthy ChromaDB instance.
+* **Tool Index:** Rebuilt automatically by Odysseus upon first query.
+
+Re-indexing is a disaster recovery fallback, not a substitute for preserving existing database state.
diff --git a/tests/test_chromadb_volume_path.py b/tests/test_chromadb_volume_path.py
new file mode 100644
index 000000000..60ff68374
--- /dev/null
+++ b/tests/test_chromadb_volume_path.py
@@ -0,0 +1,220 @@
+"""Regression guard for issue #6132 — the ChromaDB named volume was mounted at a
+path the image never writes to, so the whole vector store lived in the
+container's writable layer and was destroyed on every recreate. Silently: the
+collection survived with a count of 0, and retrieval just stopped returning
+anything.
+
+``chromadb/chroma`` runs ``chroma run /config.yaml``, and that config is a single
+line — ``persist_path: "/data"``. The image declares no ``VOLUME``, so nothing
+outside a mount survives. ``/chroma/chroma`` is where pre-1.0 images kept the
+store.
+
+The documented backup procedure (website/backup-restore.md) archives the
+``chromadb-data`` volume, so a wrong mount point also makes that tarball empty.
+
+Pure YAML — no Docker required.
+"""
+
+from pathlib import Path
+
+import pytest
+import yaml
+
+ROOT = Path(__file__).resolve().parents[1]
+
+COMPOSE_FILES = [
+    ROOT / "docker-compose.yml",
+    ROOT / "docker-compose.gpu-nvidia.yml",
+    ROOT / "docker-compose.gpu-amd.yml",
+]
+
+# `persist_path` from the image's own /config.yaml.
+CHROMA_PERSIST_PATH = "/data"
+LEGACY_PERSIST_PATH = "/chroma/chroma"
+VOLUME_NAME = "chromadb-data"
+
+
+def _chromadb_volumes(path: Path) -> list[str]:
+    """Return a normalised list of ``source:target`` strings for the chromadb service.
+
+    Docker Compose accepts volumes in two syntaxes:
+
+    * Short-form string: ``"chromadb-data:/data"`` or ``"chromadb-data:/data:ro"``
+    * Long-form mapping::
+
+        - source: chromadb-data
+          target: /data
+          type: volume
+
+    Both forms are normalised to ``"<source>:<target>"`` so that callers can
+    use ``split(":")`` to extract either part without worrying about the original
+    syntax or trailing mount-option fields (e.g. ``:z``, ``:ro``).
+    """
+    compose = yaml.safe_load(path.read_text(encoding="utf-8"))
+    service = compose["services"]["chromadb"]
+    raw = list(service.get("volumes") or [])
+    result: list[str] = []
+    for entry in raw:
+        if isinstance(entry, dict):
+            # Long-form: normalise to "source:target" for uniform handling.
+            source = entry.get("source", "")
+            target = entry.get("target", "")
+            result.append(f"{source}:{target}")
+        else:
+            # Short-form string: keep as-is; split(":")[1] is still the target
+            # even when a third field (mount options like :z, :ro) is present.
+            result.append(str(entry))
+    return result
+
+
+@pytest.mark.parametrize("path", COMPOSE_FILES, ids=lambda p: p.name)
+def test_chromadb_volume_is_mounted_at_the_persist_path(path: Path):
+    mounts = _chromadb_volumes(path)
+    targets = {m.split(":")[1] for m in mounts if m.startswith(f"{VOLUME_NAME}:")}
+    assert targets, f"{path.name}: no {VOLUME_NAME} mount on the chromadb service"
+    assert targets == {CHROMA_PERSIST_PATH}, (
+        f"{path.name}: {VOLUME_NAME} is mounted at {sorted(targets)}, but the image "
+        f"persists to {CHROMA_PERSIST_PATH!r}. Anything written outside a mount is "
+        "lost when the container is recreated (issue #6132)."
+    )
+
+
+@pytest.mark.parametrize("path", COMPOSE_FILES, ids=lambda p: p.name)
+def test_chromadb_does_not_use_the_pre_1_0_path(path: Path):
+    """Verify that no mount places chromadb-data at the pre-1.0 store path.
+
+    Uses ``split(":")[1]`` rather than ``endswith()`` so that mount-option
+    suffixes (e.g. ``:z``, ``:ro``) do not mask a wrong target path.
+    """
+    mounts = _chromadb_volumes(path)
+    legacy = [m for m in mounts if ":" in m and m.split(":")[1] == LEGACY_PERSIST_PATH]
+    assert not legacy, (
+        f"{path.name}: {LEGACY_PERSIST_PATH} is the pre-1.0 store location; "
+        f"current images never write there. Offending entries: {legacy}"
+    )
+
+
+@pytest.mark.parametrize("path", COMPOSE_FILES, ids=lambda p: p.name)
+def test_chromadb_data_volume_is_declared(path: Path):
+    compose = yaml.safe_load(path.read_text(encoding="utf-8"))
+    assert VOLUME_NAME in (compose.get("volumes") or {}), (
+        f"{path.name}: the {VOLUME_NAME} volume is mounted but not declared"
+    )
+
+
+# ---------------------------------------------------------------------------
+# Unit tests for _chromadb_volumes() — parse-correctness, not Compose state
+# ---------------------------------------------------------------------------
+
+class _FakePath:
+    """Minimal Path stand-in that returns a fixed YAML string."""
+
+    def __init__(self, yaml_text: str):
+        self._text = yaml_text
+
+    def read_text(self, encoding: str = "utf-8") -> str:  # noqa: ARG002
+        return self._text
+
+
+def test_helper_normalises_long_form_volume_dict():
+    """Long-form dict volume entries must not raise AttributeError."""
+    p = _FakePath(yaml.dump({
+        "services": {"chromadb": {"volumes": [
+            {"source": "chromadb-data", "target": "/data", "type": "volume"},
+        ]}},
+        "volumes": {"chromadb-data": None},
+    }))
+    result = _chromadb_volumes(p)  # type: ignore[arg-type]
+    assert result == ["chromadb-data:/data"]
+
+
+def test_helper_passes_short_form_string_unchanged():
+    """Short-form strings (with or without mount options) are returned as-is."""
+    p = _FakePath(yaml.dump({
+        "services": {"chromadb": {"volumes": ["chromadb-data:/data:z"]}},
+        "volumes": {"chromadb-data": None},
+    }))
+    result = _chromadb_volumes(p)  # type: ignore[arg-type]
+    assert result == ["chromadb-data:/data:z"]
+    # split(":")[1] still extracts the correct target regardless of :z suffix
+    assert result[0].split(":")[1] == "/data"
+
+
+def test_helper_legacy_check_catches_path_with_mount_option_suffix():
+    """The split-based legacy check catches the old path even with :z appended."""
+    mount = f"{VOLUME_NAME}:{LEGACY_PERSIST_PATH}:z"
+    # Confirm endswith() would miss it (the bug we fixed)
+    assert not mount.endswith(f":{LEGACY_PERSIST_PATH}"), (
+        "endswith() should NOT catch ':z'-suffixed legacy path — that was the bug"
+    )
+    # Confirm split()[1] does catch it
+    assert mount.split(":")[1] == LEGACY_PERSIST_PATH, (
+        "split(':')[1] must still identify the legacy target path with :z suffix"
+    )
+
+
+# ---------------------------------------------------------------------------
+# Regression tests for ChromaDB migration safety invariants (PR #6166 audit)
+# ---------------------------------------------------------------------------
+
+MIGRATION_DOC = ROOT / "docs" / "chromadb-volume-migration.md"
+
+
+def test_migration_guide_requires_quiescence_before_backup():
+    """Step 2 must stop ChromaDB before running docker cp to prevent torn SQLite pages."""
+    text = MIGRATION_DOC.read_text(encoding="utf-8")
+    assert "docker compose stop chromadb" in text, (
+        "Migration guide must require stopping ChromaDB before database backup"
+    )
+    # Confirm stopping step occurs prior to the cold backup step
+    stop_step = text.find("Step 2: Quiesce Writers and Gracefully Stop ChromaDB")
+    backup_step = text.find("Step 4: Take a Cold File Backup")
+    assert stop_step != -1 and backup_step != -1 and stop_step < backup_step, (
+        "Quiescence/stop step must precede cold backup step in migration sequence"
+    )
+
+
+def test_migration_guide_mandates_container_preservation_via_commit():
+    """Guide must preserve stopped container as an immutable image before any recreation."""
+    text = MIGRATION_DOC.read_text(encoding="utf-8")
+    assert "docker commit" in text, (
+        "Migration guide must instruct operators to commit the container to an immutable backup image"
+    )
+    assert "com.docker.compose.project" in text, (
+        "Guide must explain that Compose discovers containers by internal labels, not name alone"
+    )
+
+
+def test_migration_guide_requires_sqlite_and_hnsw_integrity_verification():
+    """Guide must mandate SQLite PRAGMA integrity_check and checking HNSW index files."""
+    text = MIGRATION_DOC.read_text(encoding="utf-8")
+    assert "PRAGMA integrity_check;" in text, (
+        "Migration guide must require SQLite PRAGMA integrity_check"
+    )
+    assert "data_level0.bin" in text or "*.bin" in text, (
+        "Migration guide must require verifying HNSW segment index binary files"
+    )
+
+
+def test_migration_guide_requires_empty_volume_precheck():
+    """Guide must verify destination volume is strictly empty prior to seeding."""
+    text = MIGRATION_DOC.read_text(encoding="utf-8")
+    assert "ls -A" in text or "empty and ready for seeding" in text, (
+        "Migration guide must check that the destination named volume is empty before seeding"
+    )
+
+
+def test_migration_guide_includes_staging_validation():
+    """Guide must validate the seeded volume with a staging container before Compose cutover."""
+    text = MIGRATION_DOC.read_text(encoding="utf-8")
+    assert "chromadb-staging" in text, (
+        "Migration guide must include staging container validation step"
+    )
+
+
+def test_migration_guide_warns_against_reverting_to_broken_mount():
+    """Rollback instructions must explicitly prohibit git checkout to pre-#6166 broken mount."""
+    text = MIGRATION_DOC.read_text(encoding="utf-8")
+    assert "Do not `git checkout` the pre-#6166 Compose file" in text or "broken" in text.lower(), (
+        "Rollback instructions must explain why checking out old Compose file breaks volume mount"
+    )
diff --git a/website/backup-restore.md b/website/backup-restore.md
index 424b8bd59..54596145f 100644
--- a/website/backup-restore.md
+++ b/website/backup-restore.md
@@ -131,3 +131,12 @@ where you run it matters:
 >
 > On native installs ChromaDB lives at `data/chroma/` and is included in the
 > snapshot normally.
+>
+> **Upgrading from a pre-#6166 install?** The old Compose files mounted
+> `chromadb-data` at the wrong path (`/chroma/chroma`), so the volume was
+> always empty while live data accumulated in the container's writable layer
+> under `/data`. If you have a running pre-#6166 ChromaDB container, follow
+> [docs/chromadb-volume-migration.md](https://github.com/odysseus-dev/odysseus/blob/dev/docs/chromadb-volume-migration.md)
+> to rescue that data before recreating or deleting existing containers. The
+> migration guide provides step-by-step instructions for recovery, backup
+> verification, volume seeding, rollback, and re-indexing.

From f1a47f381209d467fc1f84ecb6f40535bdae2ea5 Mon Sep 17 00:00:00 2001
From: Alexandre Teixeira <111787685+alteixeira20@users.noreply.github.com>
Date: Thu, 15 Oct 2026 09:29:41 +0100
Subject: [PATCH 17/53] refactor(notes): decompose Notes into feature-owned
 modules (#6713)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* refactor(notes): decompose Notes into feature-owned modules

* fix(notes): avoid HTML interpolation in reminder picker

* docs(notes): drop checkpoint archives, session logs and publication drafts

The N0-N6 tarballs and raw pytest/node logs are not read by any script or
test, and the logs carry absolute home-directory paths. Once squashed into
dev they would stay in history for good. notes-pr.md and notes-issue.md
were the drafts used to open #6712 and #6713, not documentation.

notes-validation.md keeps the counts, the checkpoint hashes and
implementation.sha256 as the record; local interpreter paths and the local
Docker image name are replaced with portable placeholders.

* fix(notes): keep the state store raw and stop masonry re-observing after close

- state: writes built from views (filter, spread, splice) stored nested
  read-only views in the store, so structuredClone on a stored note threw
  DataCloneError. Store writes now unwrap nested views.
- layout: a save that resolves after closePanel re-renders the leaving pane
  and re-created the masonry ResizeObserver that teardown had disposed.
  Skip creating it once Notes is closed.
- index.js: drop 30 imported or declared names that were never used and
  group the imports at the top. Import order is unchanged.
- Revert unrelated punctuation edits in .gitattributes and keep the header
  comment and docstring first in compare/vote.js and
  test_notes_dom_xss_helpers.py.

Both fixes have a node test that fails on the previous head.

* test(notes): make script rejection assertion case-insensitive

Address CodeQL js/bad-tag-filter alert #1150 in test-only assertion and refresh Notes evidence manifest checksum.

---------

Co-authored-by: Léo <leograndcontact@gmail.com>
---
 .gitattributes                                |    4 +
 .../evidence/notes/implementation.sha256      |  112 +
 .../evidence/notes/native-desktop.png         |  Bin 0 -> 61946 bytes
 .../evidence/notes/native-mobile.png          |  Bin 0 -> 28151 bytes
 docs/frontend-architecture/handbook.md        |   16 +-
 .../frontend-architecture/notes-case-study.md |  260 +
 .../notes-changed-files.md                    |  165 +
 .../notes-module-inventory.md                 |   56 +
 docs/frontend-architecture/notes-roadmap.md   |   13 +-
 .../frontend-architecture/notes-validation.md |  261 +
 frontend/modules.json                         |  206 +
 .../notes/application/agentActions.js         |   67 +
 .../notes/application/cardOperations.js       |   79 +
 .../notes/application/checklistOperations.js  |   68 +
 .../features/notes/application/deletion.js    |   51 +
 .../src/features/notes/application/drafts.js  |   55 +
 .../src/features/notes/application/queries.js |   66 +
 .../features/notes/application/reminders.js   |  182 +
 .../features/notes/application/selection.js   |   39 +
 .../src/features/notes/application/state.js   |   83 +
 .../features/notes/application/submission.js  |   69 +
 .../features/notes/application/workflows.js   |   78 +
 .../src/features/notes/domain/noteRules.js    |   87 +
 .../src/features/notes/domain/recurrence.js   |  269 +
 frontend/src/features/notes/index.js          |  503 ++
 .../src/features/notes/infrastructure/http.js |   29 +
 .../notes/infrastructure/notifications.js     |   20 +
 .../features/notes/infrastructure/storage.js  |   63 +
 .../src/features/notes/ui/cardChecklist.js    |  148 +
 .../src/features/notes/ui/cardInteractions.js |  337 +
 .../src/features/notes/ui/cardRendering.js    |  244 +
 frontend/src/features/notes/ui/cardReorder.js |  181 +
 frontend/src/features/notes/ui/checklist.js   |  190 +
 .../src/features/notes/ui/checklistReorder.js |  111 +
 frontend/src/features/notes/ui/clipboard.js   |   82 +
 frontend/src/features/notes/ui/colors.js      |  111 +
 frontend/src/features/notes/ui/draftEditor.js |   67 +
 frontend/src/features/notes/ui/drawing.js     |  442 ++
 frontend/src/features/notes/ui/editor.js      |  518 ++
 frontend/src/features/notes/ui/filters.js     |  139 +
 frontend/src/features/notes/ui/layout.js      |  123 +
 frontend/src/features/notes/ui/lifecycle.js   |   36 +
 .../src/features/notes/ui/mobileEditor.js     |  257 +
 .../src/features/notes/ui/mobileReorder.js    |  214 +
 frontend/src/features/notes/ui/panel.js       |  506 ++
 frontend/src/features/notes/ui/quickAdd.js    |  170 +
 .../src/features/notes/ui/reminderDisplay.js  |  129 +
 .../src/features/notes/ui/reminderPicker.js   |  335 +
 frontend/src/features/notes/ui/selection.js   |   61 +
 frontend/src/features/notes/ui/text.js        |   39 +
 frontend/src/features/notes/ui/toolbar.js     |   78 +
 .../src/features/notes/ui/windowLayout.js     |  114 +
 frontend/src/shared/ui/confetti.js            |   28 +
 scripts/verify_frontend_runtime.py            |   14 +-
 scripts/verify_notes_browser_runtime.py       |   76 +
 static/js/compare/vote.js                     |   30 +-
 .../notes/application/agentActions.js         |   67 +
 .../notes/application/cardOperations.js       |   79 +
 .../notes/application/checklistOperations.js  |   68 +
 .../js/features/notes/application/deletion.js |   51 +
 .../js/features/notes/application/drafts.js   |   55 +
 .../js/features/notes/application/queries.js  |   66 +
 .../features/notes/application/reminders.js   |  182 +
 .../features/notes/application/selection.js   |   39 +
 static/js/features/notes/application/state.js |   83 +
 .../features/notes/application/submission.js  |   69 +
 .../features/notes/application/workflows.js   |   78 +
 static/js/features/notes/domain/noteRules.js  |   87 +
 static/js/features/notes/domain/recurrence.js |  269 +
 static/js/features/notes/index.js             |  503 ++
 .../js/features/notes/infrastructure/http.js  |   29 +
 .../notes/infrastructure/notifications.js     |   20 +
 .../features/notes/infrastructure/storage.js  |   63 +
 static/js/features/notes/ui/cardChecklist.js  |  148 +
 .../js/features/notes/ui/cardInteractions.js  |  337 +
 static/js/features/notes/ui/cardRendering.js  |  244 +
 static/js/features/notes/ui/cardReorder.js    |  181 +
 static/js/features/notes/ui/checklist.js      |  190 +
 .../js/features/notes/ui/checklistReorder.js  |  111 +
 static/js/features/notes/ui/clipboard.js      |   82 +
 static/js/features/notes/ui/colors.js         |  111 +
 static/js/features/notes/ui/draftEditor.js    |   67 +
 static/js/features/notes/ui/drawing.js        |  442 ++
 static/js/features/notes/ui/editor.js         |  518 ++
 static/js/features/notes/ui/filters.js        |  139 +
 static/js/features/notes/ui/layout.js         |  123 +
 static/js/features/notes/ui/lifecycle.js      |   36 +
 static/js/features/notes/ui/mobileEditor.js   |  257 +
 static/js/features/notes/ui/mobileReorder.js  |  214 +
 static/js/features/notes/ui/panel.js          |  506 ++
 static/js/features/notes/ui/quickAdd.js       |  170 +
 .../js/features/notes/ui/reminderDisplay.js   |  129 +
 static/js/features/notes/ui/reminderPicker.js |  335 +
 static/js/features/notes/ui/selection.js      |   61 +
 static/js/features/notes/ui/text.js           |   39 +
 static/js/features/notes/ui/toolbar.js        |   78 +
 static/js/features/notes/ui/windowLayout.js   |  114 +
 static/js/notes.js                            | 5473 +----------------
 static/js/shared/ui/confetti.js               |   28 +
 static/sw.js                                  |   53 +-
 tests/browser/notesNative.mjs                 |   66 +
 tests/browser/notesOffline.mjs                |   39 +
 tests/browser/notesReference.mjs              |  148 +
 tests/fixtures/notesRecurrenceBaseline.mjs    |  269 +
 tests/helpers/notes_source.py                 |   10 +
 tests/notesApplication.test.mjs               |   93 +
 tests/notesCharacterization.test.mjs          |  105 +
 tests/notesDraftAutosave.test.mjs             |   19 +-
 tests/notesInfrastructure.test.mjs            |   47 +
 tests/notesRecurrence.test.mjs                |   41 +
 tests/notesReminders.test.mjs                 |   90 +
 tests/notesWorkflows.test.mjs                 |  147 +
 tests/selectedNotesContext.test.mjs           |    2 +-
 tests/test_notes_document_mutual_minimize.py  |    3 +-
 tests/test_notes_dom_xss_helpers.py           |    8 +-
 ...st_notes_mobile_checklist_toggle_static.py |   15 +-
 tests/test_notes_reference_browser.py         |   23 +
 tests/test_notes_reference_contracts_js.py    |   20 +
 tests/test_notes_search_reset_on_reopen_js.py |   22 +-
 tests/test_notes_select_esc_listener_js.py    |    4 +-
 tests/test_notes_sidebar_new_note.py          |   16 +-
 121 files changed, 15318 insertions(+), 5544 deletions(-)
 create mode 100644 docs/frontend-architecture/evidence/notes/implementation.sha256
 create mode 100644 docs/frontend-architecture/evidence/notes/native-desktop.png
 create mode 100644 docs/frontend-architecture/evidence/notes/native-mobile.png
 create mode 100644 docs/frontend-architecture/notes-case-study.md
 create mode 100644 docs/frontend-architecture/notes-changed-files.md
 create mode 100644 docs/frontend-architecture/notes-module-inventory.md
 create mode 100644 docs/frontend-architecture/notes-validation.md
 create mode 100644 frontend/src/features/notes/application/agentActions.js
 create mode 100644 frontend/src/features/notes/application/cardOperations.js
 create mode 100644 frontend/src/features/notes/application/checklistOperations.js
 create mode 100644 frontend/src/features/notes/application/deletion.js
 create mode 100644 frontend/src/features/notes/application/drafts.js
 create mode 100644 frontend/src/features/notes/application/queries.js
 create mode 100644 frontend/src/features/notes/application/reminders.js
 create mode 100644 frontend/src/features/notes/application/selection.js
 create mode 100644 frontend/src/features/notes/application/state.js
 create mode 100644 frontend/src/features/notes/application/submission.js
 create mode 100644 frontend/src/features/notes/application/workflows.js
 create mode 100644 frontend/src/features/notes/domain/noteRules.js
 create mode 100644 frontend/src/features/notes/domain/recurrence.js
 create mode 100644 frontend/src/features/notes/index.js
 create mode 100644 frontend/src/features/notes/infrastructure/http.js
 create mode 100644 frontend/src/features/notes/infrastructure/notifications.js
 create mode 100644 frontend/src/features/notes/infrastructure/storage.js
 create mode 100644 frontend/src/features/notes/ui/cardChecklist.js
 create mode 100644 frontend/src/features/notes/ui/cardInteractions.js
 create mode 100644 frontend/src/features/notes/ui/cardRendering.js
 create mode 100644 frontend/src/features/notes/ui/cardReorder.js
 create mode 100644 frontend/src/features/notes/ui/checklist.js
 create mode 100644 frontend/src/features/notes/ui/checklistReorder.js
 create mode 100644 frontend/src/features/notes/ui/clipboard.js
 create mode 100644 frontend/src/features/notes/ui/colors.js
 create mode 100644 frontend/src/features/notes/ui/draftEditor.js
 create mode 100644 frontend/src/features/notes/ui/drawing.js
 create mode 100644 frontend/src/features/notes/ui/editor.js
 create mode 100644 frontend/src/features/notes/ui/filters.js
 create mode 100644 frontend/src/features/notes/ui/layout.js
 create mode 100644 frontend/src/features/notes/ui/lifecycle.js
 create mode 100644 frontend/src/features/notes/ui/mobileEditor.js
 create mode 100644 frontend/src/features/notes/ui/mobileReorder.js
 create mode 100644 frontend/src/features/notes/ui/panel.js
 create mode 100644 frontend/src/features/notes/ui/quickAdd.js
 create mode 100644 frontend/src/features/notes/ui/reminderDisplay.js
 create mode 100644 frontend/src/features/notes/ui/reminderPicker.js
 create mode 100644 frontend/src/features/notes/ui/selection.js
 create mode 100644 frontend/src/features/notes/ui/text.js
 create mode 100644 frontend/src/features/notes/ui/toolbar.js
 create mode 100644 frontend/src/features/notes/ui/windowLayout.js
 create mode 100644 frontend/src/shared/ui/confetti.js
 create mode 100644 scripts/verify_notes_browser_runtime.py
 create mode 100644 static/js/features/notes/application/agentActions.js
 create mode 100644 static/js/features/notes/application/cardOperations.js
 create mode 100644 static/js/features/notes/application/checklistOperations.js
 create mode 100644 static/js/features/notes/application/deletion.js
 create mode 100644 static/js/features/notes/application/drafts.js
 create mode 100644 static/js/features/notes/application/queries.js
 create mode 100644 static/js/features/notes/application/reminders.js
 create mode 100644 static/js/features/notes/application/selection.js
 create mode 100644 static/js/features/notes/application/state.js
 create mode 100644 static/js/features/notes/application/submission.js
 create mode 100644 static/js/features/notes/application/workflows.js
 create mode 100644 static/js/features/notes/domain/noteRules.js
 create mode 100644 static/js/features/notes/domain/recurrence.js
 create mode 100644 static/js/features/notes/index.js
 create mode 100644 static/js/features/notes/infrastructure/http.js
 create mode 100644 static/js/features/notes/infrastructure/notifications.js
 create mode 100644 static/js/features/notes/infrastructure/storage.js
 create mode 100644 static/js/features/notes/ui/cardChecklist.js
 create mode 100644 static/js/features/notes/ui/cardInteractions.js
 create mode 100644 static/js/features/notes/ui/cardRendering.js
 create mode 100644 static/js/features/notes/ui/cardReorder.js
 create mode 100644 static/js/features/notes/ui/checklist.js
 create mode 100644 static/js/features/notes/ui/checklistReorder.js
 create mode 100644 static/js/features/notes/ui/clipboard.js
 create mode 100644 static/js/features/notes/ui/colors.js
 create mode 100644 static/js/features/notes/ui/draftEditor.js
 create mode 100644 static/js/features/notes/ui/drawing.js
 create mode 100644 static/js/features/notes/ui/editor.js
 create mode 100644 static/js/features/notes/ui/filters.js
 create mode 100644 static/js/features/notes/ui/layout.js
 create mode 100644 static/js/features/notes/ui/lifecycle.js
 create mode 100644 static/js/features/notes/ui/mobileEditor.js
 create mode 100644 static/js/features/notes/ui/mobileReorder.js
 create mode 100644 static/js/features/notes/ui/panel.js
 create mode 100644 static/js/features/notes/ui/quickAdd.js
 create mode 100644 static/js/features/notes/ui/reminderDisplay.js
 create mode 100644 static/js/features/notes/ui/reminderPicker.js
 create mode 100644 static/js/features/notes/ui/selection.js
 create mode 100644 static/js/features/notes/ui/text.js
 create mode 100644 static/js/features/notes/ui/toolbar.js
 create mode 100644 static/js/features/notes/ui/windowLayout.js
 create mode 100644 static/js/shared/ui/confetti.js
 create mode 100644 tests/browser/notesNative.mjs
 create mode 100644 tests/browser/notesOffline.mjs
 create mode 100644 tests/browser/notesReference.mjs
 create mode 100644 tests/fixtures/notesRecurrenceBaseline.mjs
 create mode 100644 tests/helpers/notes_source.py
 create mode 100644 tests/notesApplication.test.mjs
 create mode 100644 tests/notesCharacterization.test.mjs
 create mode 100644 tests/notesInfrastructure.test.mjs
 create mode 100644 tests/notesRecurrence.test.mjs
 create mode 100644 tests/notesReminders.test.mjs
 create mode 100644 tests/notesWorkflows.test.mjs
 create mode 100644 tests/test_notes_reference_browser.py
 create mode 100644 tests/test_notes_reference_contracts_js.py

diff --git a/.gitattributes b/.gitattributes
index dd49c4a03..e2ae3a6e6 100644
--- a/.gitattributes
+++ b/.gitattributes
@@ -36,3 +36,7 @@ static/lib/** -whitespace linguist-vendored
 *.ico  binary
 *.woff binary
 *.woff2 binary
+
+# Notes reference deployment modules.
+static/js/features/notes/** text eol=lf
+static/js/shared/ui/confetti.js text eol=lf
diff --git a/docs/frontend-architecture/evidence/notes/implementation.sha256 b/docs/frontend-architecture/evidence/notes/implementation.sha256
new file mode 100644
index 000000000..023b5ca30
--- /dev/null
+++ b/docs/frontend-architecture/evidence/notes/implementation.sha256
@@ -0,0 +1,112 @@
+53dfddd71f02a9a60df42e3fb045bd1a80919d50870c0b77afe18a853f485bea  .gitattributes
+867c6a4b025fefecb6ac4a91a38563a36107d9653599f64685e16a5be4fe7727  frontend/modules.json
+76de35ac93d72edb5dcd295e85c704af9b3f08c2fe9fdc56e0bcbebd4b322fd8  frontend/src/features/notes/application/agentActions.js
+37021f9643f6a3299d36b6021783a559e60ad84848ac2b12f0980b5034b6b9c4  frontend/src/features/notes/application/cardOperations.js
+fe3033db6ef316c6b15c6b01c0f202ee76a61ea2c5b6952b20144660ff17eb54  frontend/src/features/notes/application/checklistOperations.js
+85fc592724524bb5ff37d7e5e58a68fda9d7e645810b6c87a2d4dd3cb41f9dd5  frontend/src/features/notes/application/deletion.js
+ce38e7976ee315b198baebffe45f9a1f4e63d87affd9898ed5cf4bde37b903e7  frontend/src/features/notes/application/drafts.js
+6210915184c30f73911f144fe0d12a9935d6f2ce42cb2aaf6aeaa75614ca51a2  frontend/src/features/notes/application/queries.js
+0da923790f4036d5fe354df4e529feb4b96e178495cb951f269093c0a8347e4e  frontend/src/features/notes/application/reminders.js
+8f95d086fc2e60beae32b9e9debba41b35448e1c5b4ac78e4989652ef2d44e35  frontend/src/features/notes/application/selection.js
+4ceb424b3b6e30a5f507804f42051be02390d4ce1f03ef284094e48825cde5c3  frontend/src/features/notes/application/state.js
+1c5d5af833aab91f71a34c11535885eb7bf9f751de5aa89f79defe0f696f20fb  frontend/src/features/notes/application/submission.js
+1d58ea2d495c8d301c550eb9ba7f627c515a8784bcd105558d941522965e77b0  frontend/src/features/notes/application/workflows.js
+9ddbfb20e0a5564dd83365ad498286d68ef03fd60d632619ad4d9656e2f73c95  frontend/src/features/notes/domain/noteRules.js
+946ef7a98b0a2dbe329e8259250af11a11702c74fd997e17fb3aff007fbe40c9  frontend/src/features/notes/domain/recurrence.js
+25cf3a1cef5dbac0840aef513ffa010a9b08d206de96ce2527e6159a5454b555  frontend/src/features/notes/index.js
+8b186bbfbb003b8d738c80713e1cbb5c6924ee14119929c5ea65707b46076b0c  frontend/src/features/notes/infrastructure/http.js
+c7552d1f4600ae721437892fc0a1e5a0332abe30082bd943cd13a379c9514fec  frontend/src/features/notes/infrastructure/notifications.js
+ff91a55c55fbdd876c69d9ec10e4e992104c95b6d12d752d9745193fccbc646a  frontend/src/features/notes/infrastructure/storage.js
+4ff6d69d04547a0325041f774c3bf0707d8b67982d59a221127e07dc9b01383c  frontend/src/features/notes/ui/cardChecklist.js
+dd87f1929ef8a5d57fdf1ddb12a0a6be53d95be07946be54f946c6fe31ef80bc  frontend/src/features/notes/ui/cardInteractions.js
+4ff661a65d88e810f346260a354070dba325d6beaa57d1c4e82e8bf09b894538  frontend/src/features/notes/ui/cardRendering.js
+113d4457f25291d15afb7fb6775ea063f24c9dac51bb0d262787c9e40705235b  frontend/src/features/notes/ui/cardReorder.js
+eecafbd92076209fa41826820125fbe9ffa757d6d1bff018e9acc2ede2a18e72  frontend/src/features/notes/ui/checklist.js
+155ea3d70e653f38a62ff50fc5be6aee019d42e86d28753da9edb258ac7c93e1  frontend/src/features/notes/ui/checklistReorder.js
+5462fea63a2aa9d1fc07dca91b462f6ff24f352b05d99ea6feb437469c0e1f3e  frontend/src/features/notes/ui/clipboard.js
+2619e5f8b15eb3057330ef220abe6bc354a496effc0df3d89385cdfef9242c86  frontend/src/features/notes/ui/colors.js
+11cf24e7e8e8954d764cb58d786fa6f6d71f84f1c6c5ba644d761e28cfdbaedf  frontend/src/features/notes/ui/draftEditor.js
+f55d4eff7f550e183ecf240a45002936063dbb4eae153e11834da4cb6bd13d35  frontend/src/features/notes/ui/drawing.js
+f85c86e70b3a380449fe3c7ecc7a4e68946de320523f5edc8e33f8eab3f0a02a  frontend/src/features/notes/ui/editor.js
+3946b8324ad8f0212621e526479668308e48b799bf0dbb608e5cd4626f6c1f03  frontend/src/features/notes/ui/filters.js
+a893d09e96fb98d13db8ae5c3fb8c5e7a040c62031dd961396a18b7ae2a82a38  frontend/src/features/notes/ui/layout.js
+8d8c62a87d4df134d3b9dd97eaf59d02c52f1a38f6bc2e109e8426081d453a8d  frontend/src/features/notes/ui/lifecycle.js
+62ad9408cb139143168f2c5834ec56b83264c4daed3e84fa9b4b0a281712144c  frontend/src/features/notes/ui/mobileEditor.js
+2a3ccbad103dcc880e4baf2b3aa3ece4df7b73752bd30078185f03227585148f  frontend/src/features/notes/ui/mobileReorder.js
+856fe945cf697278f795b8753704119839fa12bc5e0e69e9dab57c4b4dd6d24e  frontend/src/features/notes/ui/panel.js
+8aa081cb7341d9a67ef46c74da49aebd729e9b53a73d618b81c89566c874b507  frontend/src/features/notes/ui/quickAdd.js
+8a4f23a013f06876894e6544b49540b288007d0d7e4cddca955978588f47a64a  frontend/src/features/notes/ui/reminderDisplay.js
+cb043be801ab40cf8141af6ff1ad788e69fef57a87960ca992071ad9ad29ad90  frontend/src/features/notes/ui/reminderPicker.js
+38f12ba7771589aa427f054f48919569dcee9abe0246e02b9767202adb854cdc  frontend/src/features/notes/ui/selection.js
+2634f252b2899e2e70fc9fec37144b0cc9b0ed00724da81bfef74b1acf7c05b6  frontend/src/features/notes/ui/text.js
+d2655ef163825ce6c40d8ef46bc9dfc63a2aa19fb1a7e10b28002f79cb0db409  frontend/src/features/notes/ui/toolbar.js
+a0aa203e87814d0eebebb6b049776c3efd576f4a5c6e17e486c8a2893c9c21df  frontend/src/features/notes/ui/windowLayout.js
+68f0cbe07c7b61fcaf92920cd47042c576ab27fd9553c971cff45c595c25d80a  frontend/src/shared/ui/confetti.js
+c16fcde607dce2f10a1afd1f8845403a7d0b97a9d5a67ec7aa329c367ba585e8  scripts/verify_frontend_runtime.py
+c2e5de2b8ce168220bad4fcefed710e60eeb0dd3e992e76cd980f2c0ca52815a  scripts/verify_notes_browser_runtime.py
+fa31d673c40f973490e9fac52130b4a915b944a7abdd217a9bd8d57e66d57ca6  static/js/compare/vote.js
+76de35ac93d72edb5dcd295e85c704af9b3f08c2fe9fdc56e0bcbebd4b322fd8  static/js/features/notes/application/agentActions.js
+37021f9643f6a3299d36b6021783a559e60ad84848ac2b12f0980b5034b6b9c4  static/js/features/notes/application/cardOperations.js
+fe3033db6ef316c6b15c6b01c0f202ee76a61ea2c5b6952b20144660ff17eb54  static/js/features/notes/application/checklistOperations.js
+85fc592724524bb5ff37d7e5e58a68fda9d7e645810b6c87a2d4dd3cb41f9dd5  static/js/features/notes/application/deletion.js
+ce38e7976ee315b198baebffe45f9a1f4e63d87affd9898ed5cf4bde37b903e7  static/js/features/notes/application/drafts.js
+6210915184c30f73911f144fe0d12a9935d6f2ce42cb2aaf6aeaa75614ca51a2  static/js/features/notes/application/queries.js
+0da923790f4036d5fe354df4e529feb4b96e178495cb951f269093c0a8347e4e  static/js/features/notes/application/reminders.js
+8f95d086fc2e60beae32b9e9debba41b35448e1c5b4ac78e4989652ef2d44e35  static/js/features/notes/application/selection.js
+4ceb424b3b6e30a5f507804f42051be02390d4ce1f03ef284094e48825cde5c3  static/js/features/notes/application/state.js
+1c5d5af833aab91f71a34c11535885eb7bf9f751de5aa89f79defe0f696f20fb  static/js/features/notes/application/submission.js
+1d58ea2d495c8d301c550eb9ba7f627c515a8784bcd105558d941522965e77b0  static/js/features/notes/application/workflows.js
+9ddbfb20e0a5564dd83365ad498286d68ef03fd60d632619ad4d9656e2f73c95  static/js/features/notes/domain/noteRules.js
+946ef7a98b0a2dbe329e8259250af11a11702c74fd997e17fb3aff007fbe40c9  static/js/features/notes/domain/recurrence.js
+25cf3a1cef5dbac0840aef513ffa010a9b08d206de96ce2527e6159a5454b555  static/js/features/notes/index.js
+8b186bbfbb003b8d738c80713e1cbb5c6924ee14119929c5ea65707b46076b0c  static/js/features/notes/infrastructure/http.js
+c7552d1f4600ae721437892fc0a1e5a0332abe30082bd943cd13a379c9514fec  static/js/features/notes/infrastructure/notifications.js
+ff91a55c55fbdd876c69d9ec10e4e992104c95b6d12d752d9745193fccbc646a  static/js/features/notes/infrastructure/storage.js
+4ff6d69d04547a0325041f774c3bf0707d8b67982d59a221127e07dc9b01383c  static/js/features/notes/ui/cardChecklist.js
+dd87f1929ef8a5d57fdf1ddb12a0a6be53d95be07946be54f946c6fe31ef80bc  static/js/features/notes/ui/cardInteractions.js
+4ff661a65d88e810f346260a354070dba325d6beaa57d1c4e82e8bf09b894538  static/js/features/notes/ui/cardRendering.js
+113d4457f25291d15afb7fb6775ea063f24c9dac51bb0d262787c9e40705235b  static/js/features/notes/ui/cardReorder.js
+eecafbd92076209fa41826820125fbe9ffa757d6d1bff018e9acc2ede2a18e72  static/js/features/notes/ui/checklist.js
+155ea3d70e653f38a62ff50fc5be6aee019d42e86d28753da9edb258ac7c93e1  static/js/features/notes/ui/checklistReorder.js
+5462fea63a2aa9d1fc07dca91b462f6ff24f352b05d99ea6feb437469c0e1f3e  static/js/features/notes/ui/clipboard.js
+2619e5f8b15eb3057330ef220abe6bc354a496effc0df3d89385cdfef9242c86  static/js/features/notes/ui/colors.js
+11cf24e7e8e8954d764cb58d786fa6f6d71f84f1c6c5ba644d761e28cfdbaedf  static/js/features/notes/ui/draftEditor.js
+f55d4eff7f550e183ecf240a45002936063dbb4eae153e11834da4cb6bd13d35  static/js/features/notes/ui/drawing.js
+f85c86e70b3a380449fe3c7ecc7a4e68946de320523f5edc8e33f8eab3f0a02a  static/js/features/notes/ui/editor.js
+3946b8324ad8f0212621e526479668308e48b799bf0dbb608e5cd4626f6c1f03  static/js/features/notes/ui/filters.js
+a893d09e96fb98d13db8ae5c3fb8c5e7a040c62031dd961396a18b7ae2a82a38  static/js/features/notes/ui/layout.js
+8d8c62a87d4df134d3b9dd97eaf59d02c52f1a38f6bc2e109e8426081d453a8d  static/js/features/notes/ui/lifecycle.js
+62ad9408cb139143168f2c5834ec56b83264c4daed3e84fa9b4b0a281712144c  static/js/features/notes/ui/mobileEditor.js
+2a3ccbad103dcc880e4baf2b3aa3ece4df7b73752bd30078185f03227585148f  static/js/features/notes/ui/mobileReorder.js
+856fe945cf697278f795b8753704119839fa12bc5e0e69e9dab57c4b4dd6d24e  static/js/features/notes/ui/panel.js
+8aa081cb7341d9a67ef46c74da49aebd729e9b53a73d618b81c89566c874b507  static/js/features/notes/ui/quickAdd.js
+8a4f23a013f06876894e6544b49540b288007d0d7e4cddca955978588f47a64a  static/js/features/notes/ui/reminderDisplay.js
+cb043be801ab40cf8141af6ff1ad788e69fef57a87960ca992071ad9ad29ad90  static/js/features/notes/ui/reminderPicker.js
+38f12ba7771589aa427f054f48919569dcee9abe0246e02b9767202adb854cdc  static/js/features/notes/ui/selection.js
+2634f252b2899e2e70fc9fec37144b0cc9b0ed00724da81bfef74b1acf7c05b6  static/js/features/notes/ui/text.js
+d2655ef163825ce6c40d8ef46bc9dfc63a2aa19fb1a7e10b28002f79cb0db409  static/js/features/notes/ui/toolbar.js
+a0aa203e87814d0eebebb6b049776c3efd576f4a5c6e17e486c8a2893c9c21df  static/js/features/notes/ui/windowLayout.js
+7f1a7961d586767298672fad71a0d627389e185f0fb28792a04d0b987e1d5c5c  static/js/notes.js
+68f0cbe07c7b61fcaf92920cd47042c576ab27fd9553c971cff45c595c25d80a  static/js/shared/ui/confetti.js
+97fd43c17f3cb1928947e24159a3b59dc81ef7dca95862e8a47154e9cb732f88  static/sw.js
+910cd5777564e9f6338b8a864a772beffea197dc476464171c180e7be96e572d  tests/browser/notesNative.mjs
+ef4bc40a710919c81c582d3b9fe80376d0d5ae66fb9be3c293871a83ee360f97  tests/browser/notesOffline.mjs
+437ec2e9865b3e066bbec8d7595a0d947f1e503b96e7b4d819ec1bed86c9bb1e  tests/browser/notesReference.mjs
+9af973a5d2fb08a5eed550be0198bef501af56802c3844b5d0bb8e718cc685cf  tests/fixtures/notesRecurrenceBaseline.mjs
+859a5f442dc717f59993891c338cd6ae9d6e5e009392a2ee69ab0e3b063bb572  tests/helpers/notes_source.py
+739ffc3f20de8e2bdf1d513b17bf485f85821e9906109cdf8ffea04b81b0f1dd  tests/notesApplication.test.mjs
+1946369be43177b19a44cd9ae4f90d64da6558d1a470f8e347b490a2188782be  tests/notesCharacterization.test.mjs
+99f0cd92a30cf01c0ee6814f6684edeb80ebdb9a5ab96583244092865bfb6212  tests/notesDraftAutosave.test.mjs
+0417205809de16c7c7338ea80ba19ca844603b3e06655987226f5f83d962d18b  tests/notesInfrastructure.test.mjs
+dcf7c2d33de9bb457f96af070354ecc3ab69669002bdc9c7c943bef1b3d2e9bc  tests/notesRecurrence.test.mjs
+dd9a703465dde8f92625a3226ab52d20a02aa5d3415fbcc70609f69a372ccc12  tests/notesReminders.test.mjs
+5a9112569f226525faaf6603a9867620b47902534f9cd882c08f71f2f96614b2  tests/notesWorkflows.test.mjs
+35fb2bd1f02757b73188342ec00f1e97253b8ba8dfb577861675872a517bd949  tests/selectedNotesContext.test.mjs
+c6c64c2b695b84d00f8a80a980be00766175c482548c86484f991ef671ecfbe9  tests/test_notes_document_mutual_minimize.py
+02c2aeb856798d982e5debcb9c605172933b0216a039cf0d96cdd415b1e2ef83  tests/test_notes_dom_xss_helpers.py
+5a511c7a2ef5d28463df34f3462db9ce59575d624cf8181577bab2cc371b4f9f  tests/test_notes_mobile_checklist_toggle_static.py
+1db10a0d344818459d64279da807ddefe9b866dfe560ac4b154b486dd1a5efc0  tests/test_notes_reference_browser.py
+49f466b1a717098aa25439b6ff9ef3ae3d027d9dd976212b165b0b99a582b952  tests/test_notes_reference_contracts_js.py
+c2d877a11eafcb99b24a1c89111e5df4453a62bc8cf7d26ae1118b25c4a5ace4  tests/test_notes_search_reset_on_reopen_js.py
+6d95f073421427b5e149ef1e85c8b5749095d00337f05960134552985f73e372  tests/test_notes_select_esc_listener_js.py
+b3118a4b40fcfcbb26ad9ccbcb332fc6ced873d8cad1160be38a286ad1e664a4  tests/test_notes_sidebar_new_note.py
diff --git a/docs/frontend-architecture/evidence/notes/native-desktop.png b/docs/frontend-architecture/evidence/notes/native-desktop.png
new file mode 100644
index 0000000000000000000000000000000000000000..fd30ced2a811f8c02a3373dff38644b7e6be9c1e
GIT binary patch
literal 61946
zcmcG$Ra{i<8#X$kfV6^iNh94IDpHb4H`3kRh)8$0w19vxbR*r}Fm%VzH4N;9zW?v{
zo$P~su-DO=#d`97?z--45uzwBiGfOl3Ic&Jq@_N527wTNfIv@oo+AKH3JHhvK%f^O
z=@0Le-O>-1koC2?+L4bZARVU=&nPBS=sTnre^5Q4W1mr(1IIs$pdz9&8z*X9%07S5
z>vtfW!3Xh#QfPU~EcZFQG8_ms?BRUSd*uj)G*84CSnZa3x*q)Oe1*XF>3H^QO9DDl
z05D{m`=%YAkg6-3U+1W7hh?B}@HOzX<Gb8Lu_h5p+ch29^GkIFJ%5UI;4y&@WE^8A
zsgimBIna_VSgSfw8btdlXj^k6i{lCK==Y6t!|Lm69dw`zv?s{2LT>P9AP`%VkhjCA
z=QYwe2GGZs=Y0AGyAPW<NcKRN;Uss{h#<e0L4HqZUr9!_0*}}<h0vGVSWSU<O@McE
z+6U-BAiq!cTeq)*X5f#rdkS>@fuIu@k?l_tD^Zv<9|)v>O|jyK@|-mrctIjDcjSAA
z%u}G*svpoXy+QyV+Xy`{!O@H}s1o`z@Q0WFz#j;jz5@GBK>S;P3785K56~kB#3xGf
zv<#Rw-w4~+r?j+9u?Pe<;PPe-`YVcc$+f$#&{05G9UZILlO>2g{7*q`$A6w<CcEwI
z(;+?a%YJ!7Pg|;8`aEpZxhjd2Up*~tsl;E1I=pKux`M&N!DM4{m*e4WMrHF_XH5UE
z-1Zac;;rr{WMr}F-J2&Rl~Fh#0*+_Iz{)sY*tK;A{&=eYyg<jLy0T^Ky89wD`nV`b
zcWg|t(At)2{li9{`H3Tb`rWReu?~hF<po9*<#w+qWxqu=Hi$r=^RbuDFYG{|x3<`#
zzUFUNS`?ODXAkA_#Ut{?$CL`TZI&rNU(0LS7f~|h<Tu548H^=*6*+a;-XBlMjLb8c
zH1IoLsCYP=j%AXbA6Mlwn#+Xs&3;z(FgUy7vOQPtGjbeHDt#^|UrP`{SL?N`sv-^3
zaO#1J!(6!&UX7g=FN;<@Oki<YGm~Lm`L#=F)tq(~Ko^QLban*=cZRBaL@5QFPaOP}
zRWmXY8m&1?Lo!4Jo##-IzPNBrZ$js%b#?mmIm+Emp=FmLj$6D52_$!?hL4H@G9*L5
zOjc*Jc)H?sj1e|jQ$6m~QC(zXjwvmh9SCeuwzciT$z_SpC-!z7Zi(s!a1lEnMG=c=
zkPT8d%>n#cM^j3}Ek<|B{h-m-jNm0n*2e9_xFL-kZ)eNBr-+Z*7C9gM)Uu`(&LAfs
zl$p@e0gJu80oOMb#Qte%q`rUBDC#D&v0uAW;~9o^#J=w&m*3@#$nTQIY!Atq?7}~U
z@95nA<h_GSr>?7)PT!Gg2}8ugrJ6YSu9r?f@9#zx%%MBjYTqS(|Bjjw`M97qvo`8n
zwu&#>Ol|tVZ@esLg3<B8?QN@P_3yKNjhya>_0Wl&t!--N%<K;HKfPDfMqus@5F7Hy
zke`zuXoz&tP<)Q@F}P#QO~CS4oiLLp<x)Dzf}TZjdIqtx^U75fkbvE(wus!@#a&qi
zTn$Mp)slw#5EFW@iq1LH!tuO`v7v@L?QCTUBne}7g{up12JV2Rgv!zKs`R2`6%8gp
z9{{~Vk@$O>xL)f!)*Z=}y?sjs%2bpcIMVJY71-{q^d!p(T<J8rstZ{p)uJoc&S*H#
znKWiZy|S{UAH34;(;pp9TD<UUti7DyyC3d1%<@h-pU<R&>X?1>7_3UE{Grd1Wvf_%
z?55l}cNY{#cQ0(b_mHpPLCbnoRCUhgzY-HiXD0lpq<){i`T^?gp~TA_3cn+iEwCi{
z#`XGlZUw|>w7!3Ds~|HX!lGJtY8MBOi~z@Xtq^0W8dLHzG2*<n9i@+R22!^vI+Erj
z5S3sO@Z~DV7RwAtDa!jYdtXs=u%NB(+g2qu6kg%pWNuj|au4UVR!IO9<H)%-_DQZr
zH<b=y4;C684>7tF@84}9W%-n%ufF?5y0)i_Db@k`_JjuXmb|~)BUP|dHcfiKD};-l
zr9uE!r%||XWf7ht5YVw5lyCC9)4&zh9s4Kv{EfDV-qQF%F^WRg;2Ix(Ouoj`IO$w$
zRo{f_`Z;qMHGz&-+iSmy$~uNTNcEU#bS5$!5D{3tJ(S%K>~6*J!@OQq4X)XV#ZCzE
z7_ucZ;SJbSr=Z`C<|(Ufvmixi?rke*jdtv+MFll-M8Zp%|4qC5t0P%EMRflz<C4GZ
zx|CiqPXaFSWX3ZIOkQ@ATd~!q@8fc{B-U1d^$mFE+e@zV&~;u?mR5E8IjzfMZ##?2
zy0q%PGm3aTNzb7#*SCnZSEV|gu;)`!7Wh0fs6Ud-ZpQBVs|uE=JQY?(G1%>aEEWG;
zEv3;L4TDeh{xVA2|2M5@V@2KQm)ay!VJ_>Tsh7KP+=tAm(|C_dbJDL3;7eSD6Jti1
zj_*47%xzSpbeYlf*SQWm^J)zx#)^4XA6f$%Zmojrq-H!lb{zgj?S50EWUlFI{YoH>
zNa*sdV}$A1844hyaGr|thd*gYE<+Vl<hN^IMhc-j0`W%glbbKMqQAu-VFVd2Cq3k{
zu5Ic0Hp0Luw>eE6%Rcff)Zu`~RFPS4!;;ed&BXM^+Am^1^c3~VhK^17*H6DZPtMqF
zq<$J6Z+o$>?Rq+&gX3%S?3F!4HBt9$B$7%$eU`YH>d=qSRvUCAJdGy=cmw3u@R$p|
zOIcx%evShl34DgX;l2(nk_;D9eCq)4ti8|Y?RHhhII>RVH@VYz>P*QZV|!Z~txAV%
zMx0s*L4GKd-hIXA`6ZWLmzhaCTu=JuTHe^sj2OMI+YPM!7<E+6I7p*|#q3(>cu{*!
z!>FV1UfsdtF1$WV`2KaherKts=P(stv4SySb?TGI6*CrA3ScSUdJ%1h!!D?X-z^X&
zvat&trbMrtXK3l!u<J{4fx-p+Wiwlxj2(>$0T)h?X0RDb95*h?+%Md--a7%_Di4wK
zy4V<tLUni!3b#h5oyeP+!uNoQX7K1&3bi8QN#(mX-<wN{9hxfKeMf&QWw4hJB?{|4
zR68%eLc!GWdB|P9ho5Akjbq^4&Xrb{bzem9iaC16@B3hX`|Msm;<4oR{$!A`EKDkm
z>B4mwTmy@%C6)>61(8X;b-KIo_1&CGW1%se;zuU&P?6jWp?W5PPPfwSlxm~yC~xDD
z_oF)Fjjr%|tf_(bjJyoY9ah1FMj_jtlc#aj6+{y%ZEP)Gu`(#W+w#Oww4R>7bNaM3
zi?<o_#c}$2_}0i+Gr065e@LrUae~O^z52MfG)jt(1Ij@0m<3}Rn&=?Qymghc^NP3a
zOkM2cx52l1qKQSNr8et*9nd-s{DSN6fogZ`-)0ogJE}EGHL=z|HeI2E)}_@gBs{I1
z=PJYq$Pqyu8>h41WO96~zdHp>HMQiebo_Z@jK|XmKRWMAV~|OprF!CrQVgzVXX1yu
zX2Cb|G2rO;vsZeaiwQ!mDBf}81jJB$!U<KKcSvDdh<c(I&j}Y2mtme|Z+~wNC7HRg
z!z(RW9wwGWea^{l<y%eD>`&g_{$XG+%qZ6zBq4+kE#5k2j1ywaRwK)l5F1Rqe-#s!
zPgglF?Qs{2U-0Z~hXwq78wdQ^YiqfxId`p&=Z2$#vO}`%a5UAN`XvF$d!^=@({)YL
z_!qeRS8(?VYy)eh>e@MVA%8w99(Q^1B1W_0mYEsXJv13wn#%O`kMmaAqOG%nEU1wX
z@X3k5p$7OPRQPGz^=A(|)?MgR1d!j^7ga^G09A0s+TiF4{x&oGFrKhlbLeuu7);gz
zuG!1!O_nSi@;F_wiNa8o=q?M1P`JPt)f@~wEQM}mFdZr0|Msx{7T@xmsx^%x0HXSE
z?3|%0#>*O+6M++p>r?9CttvBtd@~35&~F{y4&96Bt)RfSiutOgjBoC0eg%Wto)`BC
zR~$Ca;4Rv1M?JVt8wN~aJs3l`p;H^Co{PkymOeKXVya<pjN2=lvsz>ty3KywbSyI{
zkVOoopDj1ej1Ot3K~{+IK4mx>Jj{^SM`}7Pz@@?X&OE#au(g2O9HE&{YVaHK^5q7T
zK2ofHgs&~0tL0T3hI2G2B{TO>*V@2BxfJ&s=X=1&ajSTWc$ViINT~_&9n_?#L89%)
zXsQm#Un)76m6zB}#f?mSeM<>m5N>LYMS3PFH+;9;QQNphId=~!*_$@e(2o|P&)Z(d
z2$gXVelgBHCpn*k%TvM)+a~Xwbs2slY1BP=opOfE5#!&nN-ta)b$^CKAfy^RIm53I
z`EEl0=>BL@U0}hA`Wwyjmv$(UO#+Y<8)ZCeZ?=-Mm^Y2yeYjYNnfIpERZxp*ZQ8^S
zh_G8#GvbuB@E5n9^P1WV>YGiN3B=e0Zv}a|$$jihKS`^}eZ{J6_H@B2_e@#qB9snc
zvK&5%z`|p!{+5tgciKF-!hiCG0z+KI)Ljt*#RrV|k6NS*+L9h;JBB!WPr1#rv&5gS
zHp26ZEAUxpf2jGnoxRiI3=JZ`HFNW2S#Y?!55z$8=gz?k$9fscoI>P4ZTLhjVm}W>
z&^q0VajSgsa?ZK*@=jIpE)m|Dxn$Mv!Cma98-ZV5TJn^6+CyUJD8A69Rcn@pCiXvY
zIA+EVz+d3k09k^HOzx72v(Ar~F(Nd4A}M%8GH8|#3gcgwOq8m5JcSg=2(VwJ)vd#4
z%qiK7r#8#{0@hH!c_i$?mm!oVXzFlStCc5os^QP#&CD|UdZlF;=8;L|oGSQcq6ezy
zcGk>QGkg3;&*L%$Y&~%?($bF;D(7Ln7+&9n>^guDfWPeVz-rsNI5*C97+Zn|ak^?S
zy_fo~4;(P$Zl@@lTsl>syBA;BzB!P)2AC*3`KbOGHG;=uxXR-kRxYK+weHj8vXEl*
z;U!*-`|eblo^M5du~pw8R&)gh6<@bNncpT!#uv`CrDel1jxeb@ra->e9rcR2w6!&s
z#p;b3>x<j>rrh{yyfs}P@9zF!^G_XWFY}978Cdc|)`*P0*qGVObjncsgLUia-PFv-
zy63xNIo|}-Hf!6oQHpx#s!HphiWzLDoP0pocK_%trk=OQw9eMF%nHc2O=Fhi(h?`b
z68X+`x0su_)jpzh2P>>EZ>(EP$>h$xdvTw~`g%$vXg#KAn5N>P%C?7<JE7`$d)INA
zHcyDl_!bA*rG9HgT}^XV7&)lpWOQSfw&Y?}xRu1lVg)>_Fr4gZE_;U&@+QT<-RYqp
zL(e5u&VdD*GKV%NOZ&ucY+YBr3)aBE(ubB<ypXzJQG%{{vAAy&l`7QC03#@^T{!d<
zb(Nn@sc{pRG;FqPud{~U2RU^;Ip1$D7tPUlE9Y|=kDGL{7k4>5rkKX%`l&CbIXk52
z{AZ^In%7scGI*<RBT@3X00)=%cTzqiu7X5+6ZwFA*Lzy)laHG8v$a&dSFA@p3rgo3
zyWfI{asP(}luqGp_F#>l_6;pd%Jowl&ekh%q&gx5a7e_?>2r=<`*kIZLd9g%aKi?i
zeH7-+62F*yOuy({G&vz*sB%@_Cc?%G3*gLOG<aw9Dk*us*rlX_SWSieT3E)@)8J0K
zb(VP7x~97Fa@H~E6wGA0urEOVClXU3@_vf6GJV^n22JjtfZi$$iWmm*s>L&YyWn79
zRi`!|+ixb92Y(+4J7tNIlRZCarg(FxFP7n{7FzD>r#Sg*qG22(v?lLK&s}tI3!Iwq
z?&}AG(m5~NTV;=2Zc3IUpA0;L%EB@e4Wn~%PSXkM{5-Ln(M&xcj9{3#AbR>r)Uaie
zbyV0_a(uB1P$V~Xu03?*p{ETJ0&FB)mdDZNc%-wWY5Zw?k}<E$8@@-4<*kI#kyCE>
zEn3=8pclN$rPNU?;6pZMBUDoTWnOAOOhFmlyVI;@Ob&I9uPpnxk^7?G>%2IUl)UMk
zt=hvTVp#S*a?wnWAdCL99s*NKC07e6kizSe{JwWHuW+#=7e@$L2pF7A-k<A`tJ~3#
zjMRUfo2@L-XyyBuezcuNfp$!lS65Ru-YieVZlpp|z+2JlYdk*b8TTi*!}Ot|^rQ?S
ze|ldRJoLjpl9K&!9(;e&AQD!e4#z=*UZDXxFj`)+7VE=njl_IVQhvlnICKg2s(L^1
z61;Rj7~>7qbJ~RyPN2qHAL)pAiNNPgxaurZ8$^^6PTjmkkyM^PJ1<Ed$RK$!35F!G
zUQgVUI%{5BNEhKt_GlblKE<epZe|Wb?Il5MCWu|M*Uy5yPG{ky7}ZXk&SR&6yh}q{
zryezL1YPX9Q!P6t3MRKQv>kc^&}mETmLtKJ+P_^F!UxLp1J?o?cW1^8kxg{nn=RdX
z*A~cDP`+tBz&HpIJcxo?;Z5f|KAJ6iecLHa+l?PmZM<NMI8`r19q)k{4(h3_<Sy+f
zzT4FbpV*qooGDR30plZe(Hz3>p1P<REU0yb<bul@*oBNgTelYhs6*eQe+qibfE6l3
zvcgdzXWWJ4Oy^IrL-v*8Snnm%!p{QeL;Y^W7mCi5Ceq3IDkkInMCwqQ6bcS|nUWM}
z8p|fU;i;I7P8cl%13QBcqU3v+Amo=r&~xpU2ZN&3w_&O!mO8$tzdKp4DMV{N4Cd;X
zHAA^;p*EaD7^_3l5el}$yPAXILPJptqXkw~g5|aov)XX9U7br|#{YztwU7OoESc*t
zF^iW4C9H|!jkAKz5D06~!u&S7$xY5`jk$04s2?-eQ3n?>3R;GO9lE1d-8XsVD66(U
z9(ifW<2zIPpazbD^KO6m8nw2yalRSDzG|?mlGZ{4V%wq_(t5vq+&GT0hE8=k>PKZi
z{3o*8!<AUYas5aEQhyNBI{RyS{!R&q5Y+bY-KI0my%g1w@e^ZPPV`3V1m-Trw74{W
z7|-|lPjDtgHj(T4cx-LX=-q5@dv{PeWsoi`dsgRHPCAdt>7A$WUtjbjJ?s*Ojj8{B
zIH(xj5!m*l0)Q*^&+{PSv#!`b%?l{#{&VVAE-os!2S39HWkgVlEcFqMkUj>Ndh4j_
zvP9rAF^f(+m&wLT7M9(0DoA^M&4q2)U|8ewZ~d(IK^Z2jh<9$BEEL^bxfZRujwQy;
z%dWq53rb<c&^?fBC7;JquCC2;F4t*f+@75B=fsAaH2K<3mTk$GDQsv5TF+!c8<3om
zOHx$|jzO(I5p7YGg<Abys7B$OLO1~(dMj$iV{f{*(O6@hic8{QtUZpkNmEHS*QwE*
z?(C*3b$zg+=qeXeDQC!o97e-PY3OsLNpM;~ZF*;4ImMq{)U`!&(SPl{?nb`6>)+m!
zngPzzAtJ4%7P8RO8JcX<Z|pd!?eILC*UA!Xc*qIfA*hc^AK2$g1FY67V{dK+>d3xy
z>+y^GS>@M>#~&!?e?UJqiuyEe7fe}s?3Y!SRa#=aO#0(3=n*+TT2otpwRN=k-nPs^
z%-&}tm*;-}!NW!Ow<~gU%vtBE9sM85_uRu-nnKyVW6u64%->wP>Ox14%RV8Kjcyl0
zwTYXDo3^+5N<~N0N)9sporBj3Mo>a!4pipUKdWatC!@F5kF?t}4E&rzw|ge(coUu2
z?9WmY8>-`K8Fw@!l}U_EY(0TLv*n%Xxz=-}!9RrT=+Z*lu#;^k?WAv~)loF#6ob_@
z;7Ml7Q&lISHR@n2qf+6Si6*ljB#8wxk=G$1@YGPd|7p(XyM4VnvM^-2Eb}zvGJV+=
zEX?nDtF6&yU=Om-RNrN(uD7f$tuuJA6hVWAT|{6iE31-v3=_bNKDYTDJ%)E}aSKWu
zHgbJ+mau}r?3cVWg=2qWk9!?a`Ks^+S`|p_nFH3|KMgMrJ%h?;oi3(}^HLX_&K*1>
z*VBBEp81tSlQFD<WTTK#^_puf3g%Kph@pqKy%Z;MQA$&CI<M)*<WgCl1u^j1R-Oh-
zBG+|r5~D1SWu9`kK3k<$YP1a~oGn1J`C=$(9KTfm%p<~r4lmb!fS7e0$q1o{wI5AJ
z9&108Q`SSr)R8J+m1(fy6iF?hp)A3&ht~hYJg?8o{tY8Df=?lDipwr|^%2%jsr2fu
zbGp6`kJQ?Dxvy<K{|5(L@XG*jz*CJ?0$|Nec5cam!#dkLx9co?9?E>LQosW>zo@p4
zvd$9YO9aXy74BO*V6-q~UECz6?aM3%<&3KWg^-w=JM)L(d(6duP=Vy7)q;xamf?bH
zlCF?2eWyvSsn3n*_{ICxhHvqL6SOeYZ%*L4TzCSGWF!}VQsyQ{3Y58#x<fRYr^U6$
zWLuybvqy8D&-wEYsl|dBa$9pRRw%VF4ttQJ?d@be#g|W?>*q`sG}JEc#sY}YM4Fy}
z2>9(wrYTqIKx~MN9IWmXx;7TGz5|&#*n%lP9}#CzxL*twpKfyFtPz;`c|`QtO@_p}
zj0SRAqpEy86Rm%bfv}H0{u7WN8W{%P@6i6v?vKG*$A9A0w>wF;=4UED(%CgU;(RzN
zpCn<6(Z>=QH5%od^S{(OX&PM*%gJ}Ba{+LBm0~6N_#1_`rIuD#P!CqQ+5%9Q0JXWD
zeR?-6sS{@a{BZO4Gc*7v#9ODTNB}<{FIpbjzc@c|OR)WSvX4*O>VOi&;|*|i3qK?I
zcL!oSqFDLw*3Ta63G#pU;hxWdn#12qe^IRMfBmfku=IbA39kNMy8c&WAb7f_T1o@F
z3#VVG9QJ(rZ$LKM^os;W0N%u}`+)dgNB@6LrWpm>u2VKc`oE!8-g8g-i4AYU4TmWK
z;ZG-i=_6z{R*}q8$llbtzu{S;4xqt8ZN8sVBfnl*SoXQ|9<0)+GC5RwAnEm2QZ1wS
zuOGJ6-+iNlSP|;Dq*pR>n@0_MU>=*2qI8cFT<&_hzR|_Ya@SVh-QD5?L!Xyp=tzbu
z$SkeUm^dxp*N;80(T05eW3<XHRFvMe`4Xt%7;&b_?#Zjj1(wxE%9;rUw$6$sQ@vv6
z*XDrCGMj|ymROs!Iag&>pC~?!bjkJi;a;$MYObB;%iz=9l*#?lJT3`x5&f1)xM}qa
zC#}_U1%8nweDXSI#MIHfc&k8A54JNTSavWa?Y2j)Vu>clE2U<zR%}!;$18ND`BvF#
z%wI=q*&}6I`(opa0;SI-%^L<Q$0c7ReU<dV(&))MET3zgzHH$I2psG2Aox{KzZQ<`
zz~!5?5R(CSSO8M)2x&Lryg|r1HjB~Im+?uw>K3Xmf4e%eiq<V9vEsF0J4rmRC0mRM
zW!@YMvBK=ho=6c8>}`Y8M=>+u1q>uy2Oa05syG*2)rev64P(S<Xhp}dS^77wtp#Pe
z!7?q){Y?lFJzcA&RByhE534&e>oLupwDRtnEQ{Px=BNx|G&3N6zA1}Zwqbg6J#po!
z{iLUMMEG4RQa7#kO{XK*iWvi=$Jr(0j_z&3qXgOraH2&r2DUU)iJpVnf`7a#mMh8T
z)z!Cqt7#$wIl0&T_$MbBy`TuJW6Q;7Wk~5`{Ck$E#gA3VPMkwdOvQI7eHSUsT8W|W
z+8E4_j+EBkcJiq=XH7)~!V%g2j6?{JacE{)B{B&%YKwk5<#e0HU*0@5sle1};uvXt
zZ`0q;jk)$CEnC{WV#1_3e#+Zg=B<;Jj7kb6m-g!f_GG5kW2q}pgf77#L@CHD!J2F7
z2V&#WQE^Jk);vw^lEOqZfUW$i6D9M}rw`z$6YZk_>)_<&bqEj>f0x}rizOOJ{bj84
z%S>%#>2<;ulWN9y$hFVA*im{pZ<S>pFL6-N0Jx?$2Bm#Ed*k-@WTS=4e6M^+A0ZN%
zqhKlawB*fu@}r92J~~AH@^qp3<%&R<tM28FQgvW`*-(F652Rt=;z~DrkWPpuplfy3
z+9fOcII+L7MR;_Q%JE{Vvn05x@2tFaJy#MsO}}vDe#ZIVe3>Y_%RU2#{*%Fsh0$t-
z_fyPUm(+G6g4DD=bz>__>}TIkj6}T4RbC=LTd3CL@SnZ#u-D&l$K-?b_swhRtuqwf
z+=>c0cl*kd3|ZPbPt~Ep-w3;~`E+Y*{$%ZsyS|ZuKb<NaLILB&lRy@fRfVqRwGu9>
zRl)o=w+BrbTDN4nX}%w+&$3@i$m!N79<Ae$sQL=9*sr60Pz4v|7YkW@rVZ$Fn7Jao
z{cH7dBN<}|Q-Rp0jlP2T{Ojm(%LPJUYf|lm;Ww2+Y<h%SBoZtC(Mk49R{7ly8;+AZ
zgeEQm*|sm0bCsG6zE4lotB@tkO@kV@e#yg6*AGf;oDzJ!Hs@fFn^e3|%%g%QlBP=D
zANKNqc<GR5|9oJ&Mpe!2U=`Rm4f}`O0jRI?9`WzPW;GZRiE$6+XnB<Ntco+kfE8P?
z*Q<sy-x;xe(Z=o45qHWl!K)>Go}I^P04V$k6AKnN6rqhiNA#-@3#4-u?OX@VGTd18
zHj`Izwid!qzUP*%GKtn0(YNY0Hxm3&_ER-iY<nsW$>mmT0@l%@$8Y<u<-eX9W-+}^
z9@u!f{inV8p&?_U;SbRJXi~@OPV4YHZO2k)d=g;>lF-39W36fT15TSMO}Swd1Q44C
zHK7vhJ{&cjOG(2iG~7KjPkN{@^1K*5rD9a^(??pocd}j`W5Q&vV|p}oM&YL^zy5~>
z{2w3HoXvuxH416Sul!YK_)9P0Z-ovR9cLD>g7V<q5oA}K$F=%>N!-otJy*Fty*{K}
zKXKVS3E_4p1GVj}$>jN0oFEj*maA6BClFK<aX`?yS00;y2%abu6x2InsEt=pQg77X
z2|*<h5pTPCB-jbQ^%+f1a;qv&$5O-vi!0IPAMo3Sqiej^R+iSl1p))>cPP^ADd6*u
z#-830luVSA-VSrw-g3q?&8gx>vT~Yr-=qo9@k&lNPI817U@kOhs431v5u&Y^*o4XF
zVJv-1H6iI(|D3D-uiOwMIbH}0qoehBcmU)mEG+jzx7+@=`mZ;HeL+#1PEN(t*kkD_
zN}3DtL=lnUgeMg-KvUY^(gSLAgQ?5lg8Uq(5mRUk`}YE3u6n-fF3GZ?`9-T+=Pk|c
zwL)P|OrEGL_pW*GEU!^bjV&DPhMh=Q+CZqlUQh!>YON{o-#k{{$LyByK_G&?Ke&f)
z@1J5~23gk%RtcEqymO4ms)f2v!Fu!UD`F5t6iUYu64drFy1&)+f_(KvqGra5L|iD<
zDDmV{;;lHeW|^k_JLonzq(8q$Pa4=&Hb)Ijr$CGAOXi_bVZtVg*h+7r3>e#JQSvz0
z2sa97r^iO|IC6IWvuYPlni1HA>(VIf_>m}}Jz3DwLf(g6xLMaUe{An_+`1R8Ls*xl
z*0S>Qs4PgoiT`3C>bzT@z1-(Ca4D;4LQ_S)o2=ynQ5^q3f(@HGle>O&as8YPm`vm9
zrYY@6nTIFYSyN4hMQ`Qz9N;ag7RMAHmcYLDQ?Q;+8di167Xv$GfC75DKrEAri^f<v
z1ia@MG8OZzevLrRm%>YI^()n7j^Imu<TDc@eWUug0CWYMqJ1y-yOwuIrP&v{ksL&F
z7ZF2fTk;C>;UUk_T$u4j*6rhP3>A#<59WMj%Xz6g#m8j*N4CjDTr7Hy#JohJOi+Os
zo)r~!z^tKt-Jw8Eeu$M}!E>dq%OE5YJ=Zhv{X27wiz9Ez2wEj&H93Xz+1SeBOwXl^
z13@Xl3X?n<fsqHJ%#PI`uJ0xyT1;sYg5ln{Fiev%9Hr~t-;=^^-(uKI+l!ZlYA%a>
zP0CunBcWE&QnPR7c#^kltkSI)jO1T%0Z3}f1WWVYxMWttb*=Bm)Y@<8g>AEL&6P0Z
z0{|P;xnIdWvuy#$2P!p)UEPgZdn%+rjH7n9g%!tIFJ!YNWHQr-W^@{Ej8A^MH<7jM
zCOuOmtI@Q$)B<Jkm*qK2O{=WEJ3dQ$;2=Ifal|`%IDgtWRCAW07L;l8B7Eg>AN?xI
zmy8ZPxkL9GaG}Usxbdp0Q;63viSI!l#J`gXq>}DHWvIf#l34AyM|aN!nzMh`2~qR;
z(UP8buR9Expp{OVWr&F)JiVJ2R4zl)LJeb-njyewP%9l9AI;9M7N(~EF_S?Q-mUBD
z>GD}qx7uL$PB-XWn6Xs8N1wxtD_6Pr6!jwsCISct1dvS7qC`%Yl4t|Ij19R;Dr7=5
zb=dcdiKDEpKhLT29<DL!4Bh3fQBD*d-5-#q&BZpD@eB9={1mqeRGR1aErpIgPfw3V
z=a|Y(W9<X3C?M{0ZsAC98oTFA&;y2?>_u33!)f_QJ<;gvj-@(i*=T3g<=#iN#F*w?
zPluL&vAAEw@cI-zS-IA3hy<=SOVHM<gem899!^dwzTPZ8DQg`=7n_*Il&o?E4~zF2
z;&PT+LCTazWfw&Bd<RR7q?nS+6}XVA%i59|jZckNq!(98qX$&XG(NU7qgV(a!x7`C
z`v^MhdfqGVlh%UDoO_~)^tH(vxi5X@LjJ)6_{Uwb(T_!8NADQN{*BlU*w^(qvv+ff
zhCD<$bo}d4RKzX6HJFTMccvJ`)xTLnB0Ba(u@usj^`iIZ^Miwxr<Loq#_7LFFq2+X
z?@e#5c?;r0eDvIIjST2i=6a%j!Tv1C;=LNzF<|pJ3{7KCLZ|yLIhY<ZGZdHV^|rSc
zR{K;>&o(Q3_*0T=DVf`FyuE|Y+2d(Y$JUv<M{~>;X~@YKSFfUF)u)(ju4feshjK%u
zTzdLo4TFlGYIH-))_|eJt_ZFHbkUwqO3V<AUvjAQ@JJqeEoXPBemtTqIl#x6XUAE!
zO3ts<*4*9MGL3_6RDt@HOY!&pGc6E7XvD*9t3NNMOkc9o7|o4mO_3%M{7-JMqdYlY
zfV;qvP==>wM7Lb|Jry4X4IhO$5Ya7&x``E9QFY|z|Dyi7^{NcUox%W)Y;cwKf}^=u
zJKByr8Qu@M9^S7o6WJYi8u-hWSz9VqbLBJX7Cestcr4VzTD`cTmJad_^AnQ=Gi8-j
zFdTfAY?R>QA_~LJd@jskco%;&eOy=Nf|XJ4zvQcp?^xR>)6-df#-oC3=~};gP%w&Y
z7y4p*Hlnxz(Xr67T7bxfi>rG4w;wH<dtkn!iF~%Zf1eRc$uIUaX27`(X0oT)SX4L9
zsI#Xq-vk<;nJ64KFo`FrDN?SSja+P)k06R~R^foVK0=RHR&mO1D??K?Cg>(!<(4+*
z&S;D=(K5wzdRsKSZOe`MC|MY~#ad-AugmVOouV{uu}7q(xuAq?h#{e5e4(hu4)Tl1
zevZPqQ^oB*=kt=i^2bU+Xl%`Vaa9-Nt1mD68&Z?aIkkuGs0?!o2Ze6oNdR#BCB*zm
z40}Qco*hATYNZ&=MAy3mpckC~%BsKYUV}Fd-ExZJ3hr4BM3U9*v`bD}4{7`V%zj;7
zG|8_@<2leR?h2Xtq$k<PFyA_`1o^RdP(ASD^QH~ld{?-2%9UO)jY$5k%AY6qs&Z!-
z8TIPGjEUv7SVyo!WRN*EX#Kz7$8={7R!&U214OU{ltDpruNR#o%S4a9=1K;N#qc*;
z4G2Vecb96G^zpw#+C15a$43piO(g)mjb*Qfj{Izs=1dST>>WMV78l=G7X)m{D~i=a
zXKt60{QQO-{gIj~8b+LLrpi>gDSo;&(?OkwgLQ5H*Uqb_E8kwVNNKA@J9<qZrOj<@
zvb>UxOI5g#_Y^Z>;!=)}^#_2k;52T%5-X+YX?jY^t`;8}*i{w!_3=xp;1FBBhMskn
z+mdHge=~V~5-|XAFih_-(YqQnEUPTb_3nX{Uo8%7p$&R0DU{zW<xS8G>*T393mmv;
zid5VPzPF{yFZz|2TSUP|tNS{R(XtrT<=%j2r_U|m5lQfSG~MB-C1bBIuylc<A4jsR
zv(`XG#B%f}gK>+c3Da<;|AQe&44sg-X7eJ5byGjKdc4+2{y_-@#ysGV_U>K-5CQkO
zWb~DWP!CmOm#jJyM+}>WOIX)}&)>v>t$2_KH;(l+2$cKn&5P8@4DWq&i8lR+i|d5U
zY|eq54vSIFI&BVrHg};g-Tl%he`9w76;c&r*^qc(p4bH+#x-=NYas@c;BK$Ge!S;Q
znW{o#Tr=#?-UF=y-&;F2*CPFmG4+*qwf2UPNO@le0}c6X^n;}f$7;FGmyFG9SA&g>
zta44w6l=~)d7Z1Y<RlWc-_bt1eLINMTm)W{N&CM52mM8hz7Y-$*~MtK#1El2d?5X2
zqvYJ@$e6rbi$>$scy796Q+a!K>daoPZ#h&?;9spwIE59WJXNOhRZCLxk4;g(ed8C|
zUe~YO=>xy=!2^F%QQB%geC_N0eC{Bqa4;DMd#eYZXQxW5xL>4qpeF0^r;N|l_P04S
z5*JUMcf;Sev#J)XHiR@_lcIV}UKD?Gcl#0=XdNHDHr`9B=NP8;?$1E_d~<`eV2S)+
zEK}~yd+#O`nNcFJk-lp<F_g5g{MP6rXw$ElLwF*|1lC}h?<Qhp7A*OAEpngJre9Vr
zYDpsB_imlI<WnI4Q7|kF&%3cbL5}LW_1fI@DA^3lxwD91Xz#h&tIKm*_6xeaTig7(
z@+}_74a>D_V-pL1HKjkE1<+k;O;I8Q$g$LOiptmeyq>i@$$3i=$4Se9(AZ_gzK3zh
z43Aja>6;z<XuE;Hmh89gA8u{|-ksL-ak3^e`w45{dk7jRtLI~Iaa3{lm1Iwm^;aIo
zeLjQ)?<-wyWH8^TI4=u&X0W@8k(D)jM_O7B6mP_^V-I;?msfg>B6SPyuF!JZGNvhp
zg#ul#u5RB4Vc(gN(;v|T<en01+sk8$S6zBOrnQ>p9?l((<%l1;fWln$MQPICbPE6!
z+}}HX^Z$Ut)_}x`+*296GnCNUa4v3JeN<GUOGLK0`4eDVovtH4{I-FWvbGYZ#%~oj
zU1!sYcwI-<9yNFX{==)naqqx3%X95Qi&gJoab4!fZFFiY&GbIG!Oq=N=c33u4c!8_
zw0?DN=F;o-XutN?+}&*$01a?+0Tqywg@^i+SRgO>n-c+BTGxhd@=P*VecXoYyf}|L
zZkXq+AB$DE85ZY?x9qVDhn9Qp_IDWs>K#;R02o-~CDMnU>5a_ve-Hx{|E1j1mskF@
z&6n3v`#Q#$dOx0Hlnc4XCnj7h%@CO<SVzzxR_Oy(4B8ieB?tl~n<3%YahY*v8%URb
z)Kn^;NWV}A3OH8}cWH`c!6`f?Kq7a#Q30%WzL}TO`t)uedc8B&$lYJ#3Ay{V{pqjn
z0e$@-52*hDpzt@&Aw>q5JvulvG0b7X5anI#zQiAOd7~Rnnk!-X{_H37mo)$k5|Y(A
zxy*k=^<^62Hi7Yl#!x|G@oC$R8`8iT5f5JOI}N@4hF)=i+x*`&?b?Y4pGWd4kYXiC
zwYFUMN8r*7vm_5%;(WfEoW4Fq)QvP?OR>B^<_hb$L<<|7tH^&W_T8*AjzF%4XQ~vP
z>|Fa+n;%p0Q$u1Gm5hE4VsuLKz%nuSAthGCE*f3fd25T$?I$(0<@@!Jw1=CTB@65F
zlKb-$WbKJZ<oNMwLkxSFkep*dIEeU~k;<?<SVrpnM0jlcT;q#P@`qbrFusWIc^hwj
z;4^)$UWBjpvSeRI4gQks0v=nx;3J8=-zU-WT||_OLJgvHbeT(Z2KG;%0HD7KCch+M
z(JC3(9cp&ZsZQxJ5Eb!`oVPmC!1_Bh06#7wk=vbDmsO1#fkgzIx2B6ZzK-<$HJCsb
zdFdm50rTpgKHC0cQ38$hsWD9cWjw$SKX%0b3nkvZ!Ty^H`Mpc4x~tqx(jiTcro6bI
z3&^ptwWc2yt+Ce`uE`pnSAX@21tV-t+Q_QKFPv93w>@uHc}8U~b#G+eO<Q#Qi^Hmr
z|Mt1mlWy*@eU^^@VFCXGjkRyC!I(&nP*W&x{3`$tGg9nCZH?}n49_pgp*6Pgx-n;E
zhAR~ckVFpmW8XqXY<OZ$zV~gO<T=<YCb#vpma;9#44m9c1@#4<J;S_<K?ryK$9trD
zLhxYpq+Odfim$Nl5Iz&(PiO~h#P{zl6Z@^hV;4O-cIQ9s=s8T2tTkrzYPpt1ovLg-
zw{aaZf4Qw-dBto5CEah?vw9C$uoDUnp!QxD1}hj>^23|$Go+%NlC}91eq2eSvO&5^
zHN*J-x#4&@O`nv2cA=<Uq>D2xR<QeGxN*|?5)CG5VaVV&_mOg@Av)PadipA$jC%QR
z#vbl@Ae^WFbC(mWjRL+istzrihj;F`#+I;YnT}kiAsh=11aHS?E~W-sc&BGx$HpIb
z1eoVz!>yG^!TWu}OOGB`bhsC#wxu7&l9oNx8cFCKN|gs(PZu^`(7=|R*_=hiER#vD
z>N@;ITtfie#jciUH~B7GJI;={Z`3P&gSY<*0lBh!`=UD<;?1K~wIAUKx6@#EuZ84v
zhS;IakPQ*^t(14uBxF$#xA!q+;EwqR{)r$l^7tUko;@m3S~rA|;#Ocw*jN5LIAfB_
z>0!7n!prH6V;>vBcwTqBr9YESu72%uOH%e$svA7!f$&8C;J={_mkz3Ho8ncxmpGTe
z(elk3{iZJ4mrUub27$|)zIUx%wUE~9X_$$gcN`^GQ)?m$cuUV|q~nBh8zXPQZ>Mff
zZ5bdEubT`W7NUqzi#o2pb(@dRcfB*|v&MSXL)XZdfiZmLVFwug`kAFIyV*ICBcS^K
z1FO}R_{#A;Ijc2Qbbnv{F$zkSOP>m4K~}Rxz@y)ZgF5%@8B5Ed&n>sl)?IMb8&hj9
z`DIQJ+w=d*9Ni7^H!=c5`?1^1v>ghCd$SiOzUCCK8ElTYYi&HCDp8z#ALRNMVRJBv
z43iaM$GWDU;pWDYSm#S!IH*fvSkx`|eU5l!59Y#Q9cc{?a*|3JpVpi3=l$qjq@D{n
z+*1$hCO2OMP4A(OJBurfr+4)L_5S#B7=K8bi0SF63|8qwIJ&x|n6;`HGoeZD>9db_
z2u`FQHKT8Dl2j5hs^PC&OhGH@um7DC_6Wuo-Evv53E#}-y9!fm6ILevs-W=T#Nx{D
zv0r<`%>kxXP@&NWg_QQyvwc*DFs#EA&%@I9DPF_#X=j&r<74VsHEw~vAGq|GgzGmO
z=f9={TR&?K)_&9WCk>jPP=;BkSEIU-o9w!D2y4ClJ>y-$r|p_T2ALbrv-+89tW(JG
znxlXgsvKpqeF*0d=)#uTEOQF5D5KZ#fkMH)H|-WYSFTcG<`mv!X4x}1???FEA=p7n
zEGK6p3pb7c)gGau>iQURx*nuGBH=#0`c30Z!>UY?p;RD2rOub`keb8L;x63%9HUk6
z{psl8ViyxnVRZqe@5trglv>z^h(zh-<Ym@*2C0#9RvX}Sr15qBybcEr7wZL9^eti{
zneYoi>w<kNM^~GRQ{jov8e5w&m%@ohhp>Y{+CsX)^d5b-0WhY@cKQzN;H4iL7R#qc
z`|8Ke>^$bclavM@h_bF$A(T;zd71aC92a&Ca3lZ3a$fqJv_nQjgQc=4Rj)~}Zw&)9
ztFHzg#$1c5p4jubcpZ0VUu0eSB8E;>MC|V%-+NDBtfh;t4Z<8*vY?R!OeQ!AuP<k<
zcAin9#JO+9Vx)C_PVgRt$&&c9qi7m?F4J|+rG0SOSr`HP+`5bd$HMkH_DC+7zjeC;
zd)W^lgtzSH)*1plCD&6x1HNgXU3%Y$-c~*9q8&#fYsBrtMQ*uCZrLuhJ=L(fEQ`9=
za&U|C{UBS8LwrN`yXe<X1{j|lql@>Qp0gzy+=6Fs$#fs?*$tz*sH>d;)19D6Wj5}N
zHjH47LmPG-XSFkXazQLy1nqxakD=!6S_1dY92XJ2z;Dab(}8JG7$2d=IruiZGrlC#
zZMeGVIR><TOGeT#W6Gd_{I`r3+#TU1;VX%#dWu1bTqea8hKag%qfvJ&9;b7;%F2os
zQ$SAwD5<r}_nO&?Cs|jDMIQq2c3S^r+lubPz5#$Rz;x^~Q{<T><gy5807K`-k!YI}
z@piy;@qOm1pVg8r$N4Q&`@=#Cw^Lje#+0EAKR;;bahlK3yg^Ikj(?@PZFC{f@yQ(_
z&>?H9pJTqL<BRK5-N-cTD*Q@vetBZyYz{3_rkIt*PUrA_M>QBi)rN@h&v}OH$l@{j
zOnbFR-F;TAF8S{BRZb$5lIzb6OH4b!lgqVR#*DK5qeRy=lCI|9re~-z_KVTRPL+T7
zz?cJ>%OF*PI(;I{l}9bUOFpd&H-w)AINX+H4A8mobWw8|RW6ly3Hj8mvWnyg>9fSq
z#cVYhAUCUVeOSlA7J(HLtCS9%H#?QnQNI>A`sKR)+qDpcDGB}2ZUe4I)otJ=K3{<N
zatrZO8P0Wa9rP|-IF67>+@okazyd_tv)Og<4-_5C>hlj~+cPnmyhdJ>M@_ElvW`GN
z(3dOk{bZCM{f+*?$IRCF0^<EF@4J8?n|$8p;((S`8md1xF>dc2<RE<om21J1(n8tE
zNcd<rO<}Bw=T;KSo6{R6Gq@YUUS2xf9?peAY{^5LD0vPQ&=f|*0~g{UOCd<okb!+t
zb^r9Ar;XcsuCT#@@`0s_u1UktiOiwzWw(<k9`Xj{dRGze2&M`nuVz|uvsIU-Wx-FO
z3cVoi1pFY{f^jl818K$dGi+Sw(ye6o2V>ciVc|~>ZsnADS9?5E56_P7j)!XI_iP_d
zw#AlxbnAS#+igX5>t|qwg#EhssRe<w1;-x@JhTAr7)i@Y(_Jno-1UFQSZ#hSq5u0l
z)w1{Q{NPeOw{g4p6i^fX{j$#sZ+TA}Ht}=f;9-wy8xfz#d8%lg@d)Ovr6Z?htx_(o
z0#K{deCD|Q+3iz-Do}*#T!Gb3t(!J-fiz;}p@^eIlYo}yGLw4@*CW`e?=aSyC)=*`
zc}6iT?q<Fz?tFT`lLWKpM(2J0L9(MTzP~aar!`&#Pk$6ShnX@2t8W?XeW}8mXi9o?
z@l6W;w2wb$L{`bY@6?m5AgUx6!cXzDIDbs0_Ix*DFj<20<*kW`>vp1UbHpDUDQL-l
z|Em<=9}U&@Gs7)WT`)*y)Fez7UrtL#=L_W2(^sK&j-fJAJsc@vY-N+|3CoMe`0BQG
zl%KT2uwvW`4qHf@fmjF#cmFB}DqkO8$E9H)Y2L5q7w)6V$M~l>U&wJiU%uUvsY<Un
zh`r&3;1ZBtZDpu&Cnde`WBJP~kxXx$@py1HOow)j00x7FD^jnO^T9bIcR#9eW#`kX
zqR}u5z%($-0+N{rdrfLWBr?xPt?HUqPC{`KGQEx5<MFo(*;T3G@WYGiA4u0yG%fe%
zS$0hdb8MjsE7u$p<gY-xw-Ax-mn5IC=ja$&8Fv*0gbwqeq&Qx$cx~a?nz={iLCz0X
z>N;OA`6Yuqf7N7wy>Xg_kMBJYa1hmA=Vh5crb2bEix#xHP+QOLk<wah)oQEHOADb6
z8rqpdR+NSzT}G1(3*rvs5?SVgBrc7A<0F)bp!Jhd7>K;6pgAGjH~0EkBo$ovvtP(+
z`qRjLY$avdiCoXx5+S%R%lfH^R{d5(=Olg<IgylYiO(6GxS5;2?EBRgQt2~1=>5)N
zoK|b={oKQKpyXIHtmRtoa)j7?^;A?CCx)kM^>?e!01*OC<Rt5B_x8%WCDDmx>Bqc_
zMF^woh9abhCg?KyEc8;^^GM59)zu;2K}?I2&~Qi4PDKVskLinj9Z<X1Fa(0cEwHXl
zTik8(B&qj)&%ys4*QK9P=URYMqzQ;s^_uy9UFo;xuYRh^JW|P$p_lUAKY$<T6#1^)
zwm!UZzsJ@*+tefTflm)C!-h)nmtdZ1X;3|{y*N>bjQ-bgS7vIH(Ute_0LO_oIY!>n
zr|xlIh?!A!H%_(eJ5{TzqV)z7mC6v;o40J=tk8CHHv$idBjqa}pSFt9T&+(ykXL-A
z8x6ZBd(+lw2T&{_7W|O$>zRN?@+^^Uaz{MrdTmYVRuNIxlUya!agPQy+iH*9FNe$b
zH!DHQI#&Rhb7;6gqH(Fr#@c0;)G88Oo98YwEpjm;s0WXxdx8CE=8|_DYHc})F&N3N
zpYr>v!Y}OuiaBk!r&}7GhMY0ehUi2RWS@tA<4WuLWm^PowEQakFWJ$3oD^HHiZUk8
zbopG}(S3N)vaZKP_i5~a0S=E^qR#!g2Y9K5l4BZH0oh&wK0?(y+fmB8J89{z%n^NX
z@@wnt!k6Jl)LCnh;s6TndHbk+>7;29@R8L=ybNc&J1I-|tf#R2b^z_Bv1S^76U#&O
zc}Tgh*=LK}N*Rp3VRAk9npP9*z&W43I3Ri2)!dUSjy&P(LkJsK@ALZbBpU!In}05+
z!06fl`Qi`b@U;PP`xA7Z6!qMp+y1^>V#be2;vbf34Q1;0?zH>6Hqih(W!|t#PAK-E
zc0N9CQa#%JteZJk)v?NQl0I!9!)14>$5&ec$M|uE_{HS99zdCm2Jj@@TyNy|@ZTbd
zFHL{ei+8nJ=dBm4akG_Pu0wq)miMy4s|d@Jq@}ou2t&d-sG#ig%;HM(rkn4-BnSB(
zNE;j5kx5v%X6Q$RYt0M+3GQmrx-4%)ua>mjPwB%t;2jNzKq=z;8W5cK0qC=3)~%_X
z7e|B;+1+s?b9t+x{n~SDce|y+r2BhTuZj(TF2j*EL-RK>(O2HES^i*al(&;ce2(9(
z)q=JigNY;L4_f~Ne2=Btn9-;2X8!g{lQi=Fvc((fEX?cZ14lcE>p9BRTW&Zj)|D*v
z+^T5N**uz+wSCszdIU|nZ?%3rJHXW>2#`-3t8b2~-T;iXyjCO>hc30u#C3$7s38NE
zS@4ia^?&$^-#dQb)$-;GS5Kc5!dK&Z0lbw_n~V$3+v*9<KN$S$4rFBKXlGQ*GeP_}
zrUD)k5GVf+SkX`a|3>8c|HKh9{8x*wpkUyl6cLhONeFxP9uPCWP{zCE>?5YqvY$4;
z_$>|pm(dT(j!<L9>gnbwyAsJs{C!a*syzDU15zL|{axf{)-i-2>F06+ank>=fX4;4
z?d0x$Z#NQ%b#2P7M%hIItnKLXa}4H)Acsgz>uExBrDk4<|8i6&4(fD1DS2rYU?+|@
zj6Pw8bw#3Mo{b~@7l2h>A1BXm2>?Tnwx)K^*9EJyVz43q<-dh<kf%g_UV3DW-4-f4
zU-#qc68)DNeWJyF&JG0zb~9xo4D|9(Li(?ie_+6-ahm+0Wig2^0Z4~AL^R|i;u<<;
ziw@{nDKP~BCg2y~OZ~@1bko~QeRw-xb-AXkq7ov#WX_q^dz{OTnl@nUSSO1YmQII`
z7uJRU5>L?OW^;(Yrz)Zvkl--ye_Mwq{hmtv2?cJem!t%0K>LPF9*}FN+XAMhSZU(@
zSw-{sjuBEow)syA5XesV%YT(>$4-iuln>DbaY4P$v89YVVr<SkjVh|RX=0<L?Ctn~
z>7DJ}g|F1{zbPHkpH<Q;t<{8Cf&t7lc8evE-b;hT#?;YJ?kI%(0e%H`mIdq%$3u4`
zLhd@G>8yC`6dTw^!03<$^r1?n@x&VP(#y{zyfOOllM(f4A?qa1)XSh;Q}5JrUlaXf
zNksm~^(-k$+FhSK>nUsPFss&0N_OxzC{9Wgg!mo~EtJnbOa;-^-oHhAD$V;d{V>gJ
zy`a+I?-=+<?y?4+_AG=NRQv&N;=1;J(VvD$@2O<{I&P*FNdeBt4|L~eJ&BCvX|M}P
z*L=CT8AaH;`=T3)RcB4PO}`}es1%<4oJL=|SjI}<8~g1C$g%pw%tnHxiH^N+(1>kO
z@%623)L*4betYepr!pmlwPai&>Es~LIM;cFMhR@|J^JqU^^o)~E14h{FW;a+ZA+Hx
z9)L)P{h<`?9U;?iYhSY~^EkcXh1QK5u-$E~LmgeMRCy*Zi_J^Rc05<|TVZEmYD|>`
z8143d{V#|XFH_lu=or~#d*JP~>?&&Dgqj|Xu)9F6f??WJ)6En<U|M_IX5|Dj2ZMk$
z-f-sm<qrMK!pFYfXkYr)ehrOH&`Wq#MT~*kqVE?JlyCGimG~lqv`Ra}5n!l<DjrRg
zbQ`vPigCV<e7GwIzIFg;LsV=w>~jYIhSncRK3!8gE>}_RtG)FromA@pKC<z++xQ4P
zQKB4-e=<wXyGjxl@84ScL=H_u2XL2<d-pT%XTIZSSunjh9#7~nA@2(_06w6{*JDCa
z$Y6@^7do0MQK`O}lPLX;J`|0B$sVLt<naAv<6d!^)4W8+(G4Ts$j$Bg6SAY<3!XL{
z8V4=hWLS4=tgT@wJdEbUIRN>xgOT^wp7X14e6HS6R~On59c?Fl{3Y4c#yW8Q%SYu0
zp=+PV?+R5+$~=uz)p0*1;8&m=r^6?kt-go)?v?xdDjy87HszaJ+LV_(icJ&v?8qgp
zl!0zw9kNpQVg85RgFFXUK$g)tAUh5+DEv+dO|0Vqe4K;+&^Dx|-MH7tiVP7`(x|Xi
ze^zMODXIQhbFL!5+ftj^S{1Ffr|m^Wl&$#mDzojq5`A3Q1}eh3>h2gE_<tAif%s#@
za=iVKNB<9NZyi<D*R>5>fJ&Kk2m&JA9U>A+iF9{&$Dx#x?(S}o?rxBdLw6rSy5U<#
z{oT)f-_Q4c<Nf2?!{IOvXYaN5+H1~v&Fi|>8~BTH{{$u=?1dlJeQ=;5sxI16KwCdM
zIsB_z>oo4zk%4#^u$nJpl^$x?&%`mAeU$G>|0?YW)OVhY3-nX>xsbpr2MVGH)biL9
z*$bLP+Q@9B*bPp;(}Ma!FP2yQEL~6Wm}cpwP4?DxM!qGmRY*r%9w6K&tX%}ny2^&*
zgFe~@Qe>3=+2V|}lt|f=f)upE%cJ4>TTdQjvpI{G*YzbQX0*Nc?wMd5el6l1rkH-{
zuY~69u8Rj?vmv=ROta?xzx-Z+abT_ImJCd9_!B)A7p~qsXPtuO@m`O(W3)cZ!2O+L
zgXeT6@S%K6I&|@AXz;MAk_kPWU^xh~(RR^<ZtY?*#hs=%)HqduBw3lITZVH4`-D78
z-`Ny2d%Nn*%_?Dfo;X(r{anq-G7<+lZ1pyKLnk@-Ic?<^4}3n-6?VD5kD-bzY4D2V
ze=cR_bQ7@VJ4}0XP#c1B?_TOM5XA#Cj<N+bHh>Rryd5ERxvN5m!B8(<18AdOSz?iA
z7bEC$$frAWn`OHyj74={DW8bf9_0dQNyM9=1JdD*w~Q-an`_W?#8hqdr0P4LAKKg9
z=fb!{Mi)1>^<#1eEwA2)>~)Cp)A(Rziz_;IiGKElCstLZ-`?-d7Oxf?l!lWnvu6Nb
z5^$^!JsfBrvMMuJ+sb34t>4OP<kl>eFTB0X1G%;u_jUG|wy07`XoJ(h{2?;7%Z+3)
z)7!x^79sK2jwSPrm?wy@fo7@ZTl_a?&iBv05D#Y#{%o;YHNb0db4gZo)NT}<#9=mY
z{5gv4dD*Xw=&Id{30D=_bz-Pwg`R{JA1z%hT>%dPox6P9hf%sF7vuTRW1a$+evNmX
z_nJJ$Rh4A6LGMx5M#-;Bh~D7bkj0xa^qeW;W!T|j{Q3eA8W+X0T{P-MnHCj%_{~+n
zlcw)MYo<fjFKSbKT`y-~ZFz`nHhWTZYIs=M=(u$XT2aS7r5Ggr3c_B5YE+Al1bS)=
z{kpUBi!wBj3Zy**2cy#($Om*;pldp~HL}yk@|(K!IDsZtnWfcV`&JeD$i7O?&2v+{
zZ`o#1a@Hv9)07>DS~HC!bdoyiukGU@+EU#SwcoKB%Uu&JZVAf7EkDmfbGfGXYXt@C
zCoB{OZO}N%$WFUvt*zWDp8Cx%_s<<la9@UH5!Rn<y0YU1n%(T7YqueEw2ioFHH+ER
zvQ*#GkTQ6BZMa2G)iPmI?9=&)mCWxY^IIvLCm-T9yhEBdPM?1+{5(@i7$)BP^1Fwn
zz*>e}wc(Uu-s2PFLnpMvK+-$re9tZ~Bou8w0)>kSG};H`;h8FyFOzy-gLm_zV2J7O
z`7r43?*FXu`vzcv50;fzvFNEeGm2sSMC2CZo-sKiF0LtW*UEq}lGA)#!VE5T4x2SR
zeuM^A!@Nca6Re#3a?z&^vHa6~4nT<^jfUWUaN&#GS!m&39tAE4xW32~5^qLj!*V#@
zP!iib#x7~5eGb>#-Jz>V%@UP}Z7hQZ$cFlezlyLre{WaA2Q=CbI>^XjM)G*#AQJ|G
zTOy7sxMzbVD8ke>E}&bJ{-Jy8vUirF{J@xQx#gLY9xtj53R&0*e{YG~t5`3l2uPLj
z+#&msl`)Vm9wa{*j)1oHMT^u3hLiLu5uY5t2J(fjd+v;psx#7x$_@wm1CDX+nw8UC
z!KjuGey3SY*|>}BY#T5$jJV}`RA=11_-(6b&_T1ka(o#Y*ii#~E2iqUuVxzogCCpK
zSsY*_5R-DNB;ZVRz=Xp@{=Rix)h_O1kx^bwDAFUxSvj%Y?zTx}P8^sB+Fsvmwdcum
zZXK_Rw0iS-+mWIo+s(E8T|Bg)&K`Gu6%m2Q8J0P&>d<`@0bzR)9c*Af@BunR@FGt5
zzSsq0N<pD789w*vg_pn};=jl?_RK9-=A$dRwDpIqtha|Iv?kw{Ljfwwfvp?y29R3~
zC@5{I`IBWTR*mOJjfy&ZOwojz6HU@x`(BbBtx@1I8}0?v&m?qep%>l$l*#Vq{Akw3
zp4#U4D=z5K9Z{-?$<EMqT4vm1JRV*OEybdG$MRejUOyD<znveYe6rVmy`?c?+Wy_M
z<({;WA0+y<e{ePW+D_ynHQan>;WUyfL&_U^2kLng!Gg7w$h~g5zbU_#-^bbJu#1i9
z*sh0`Vgifx0SZM~=Lq#7L|TtLGSz6Iz_5$o<8OkBA(a*S`dJtYL#VMVOyPdu;rHf6
z91e(@c|&2@chIH3gYsDR51w5tprE=E70xFZ*`EF8b-PAoZ)zB4FEVI~$MgP8jQuSp
z;;aG@#A3t*gU5_3q6PKGLG$TLZ%!*b3#9y;)voE|8kP4QzmB&6uxuwCEtgT{WZRHW
z?i7WI6h1sVeQfo+ciJSMZjw!eCbaFFH|1+Z#S!pvjD7}|%eKuTri2{Vsb^JfjCRT;
z-rWqiU`|9DR?eDXai!=mAbz@o@{a~ZkiFA_Y3#g>q?>rjo`DdDJ9xj_kSTgJp`-ug
zpa2l*@1UUny(}+wJp5>XP}(5g`Fnoy5$vNY3r-G@$_skAbwY7b|ED&{l(r$)<^jV>
zc0FPhfMgAe{Bz2l9z%-P-&(+}dv}}qp7>K<Z#~mL&9wZQ;tt(Xv5%kNsY0TtSU;W8
zPi9rQ6dc2*MZ%Z8npVm>iob&VK{^kP^$q!(M`&@JoLY|h?|$4l1QuiOFfVYw-l#@1
zIv|F1b40ohLzbJ1Qd^$;dRQibm4UJ}$cBY^5Jy1xgZ)&xRO40l-Zp>@wU5ACr2xua
zc%kUFzpSq+t8FfCDf;dG*6SA!!97s^b%a>|WmZyIMipkW?bZA0e&Dasj~}ft8L?0l
z1Cw}8f1)A9G&mLjH-)Ljyo!bJPOVkG6o5!YOPFK%^-Ud3A-`1chA>ChEtP;?8UbF^
zS<sl3f$aPK*{Q6X^QBezECKu)%CP{OBSG+|{#kGe@XjysLkuk?`WqMfLE<k>Emrmg
z<4HI`1)bHLp2W~Ivk_%9x-D0@)?Z$WNC2Jlq2G5~0g`&{+q#fBf*Ysj@bSP8EH^$x
zJSsG3`pEFT0LGaJrZsaDoN`5$sO9}8Fp%7Fj9Ak_OC_<4yo1~~N$4MiE2g)n=UofV
zfZqm^V7i#9Bb5JM@zF1@0SV)qz;Ujl&7dQKmqZ$#m$t^vFdaokoz+!8)B4JS3SWq$
zsMdTUp}niKl}?WAB+Ky<CCkm_-g&JH*`I5<L)VYWu&{7|P#ja*D)k03NBPA3Jdrl;
z$nU!>GwV_A)k*c64QSJZ2W66dAsF31s+YxnC=bO%ZELp7rBFvcKoLL(uG4iw=ssF;
z&|XO`q2uw|m@&<1v6<a5^pJJnDnu6#7#`dJE+=BS@8455ow0Vgwd$4{M(h9^tssa1
zPeaK&Q`b(0==vzre*`6^L4ZjS<n2M00s0BYpd(?#_==-~>@;0=a$H_fn3Y=a^)(K=
z0nRKF%;rdUFuU%^c-ScDwkq+TlYF3`aBI~xC?p5Jj;mPd$oTSq9arTQWWup2ZX@Dh
zvVq2%z#xKpr8MK(^}YdNUVwE&V1;?yyOx8zDr}7eEW>I8Ah5&JJoxeaVVHkD$jgXh
z&;tncfj3>o+U@i|SimDO@%4Y?8gv|q&6?FpQ^vBVHZ;cq4!{X6$MqHUo1cmc#p@t_
zN}jMUe7Av1@OJ<BO+Td$7x1R}b3FekjD$BT6g0;O*`c<pKi_mVbIo}8h?djVO_rxZ
z0}7PjjK8TJd6NMB2eccxJy+KRqr*<Q#QMF2BEsn(oCb5xf@X6SV-HS^T{V|)UY>GK
zsjk;Ww`&bRxsJa88=!KDTfe`jYx>aqTV)Y{NQw&}ukx!iKH8}4Hr@WzM+kSZ`2J$t
zBIu_#ur&)EP)psxV)Jeta!pu1YHtlxyWTWR?TS~a&;hIA9V|qkPDHZ=JpI`@n6s9|
z5x2J7Z)^ellv@a0ms?s|F^fyb44CHxrw8pz<6EEpxvzA@h}h;Y2&bkeXUId(?Pv0&
zY>w=X;dYJiqsf8wOhh`i$M^TU3I7Kyy2p9hzyA;X7O(a%M&Ey^0_R?>FZ})t78)_H
ztAMfpJF@j&Z9JYN@C69nnoKw{6#RO65P|B30+UzXuYP~lt@vv<N(>V_Idep_Iw-fR
zehm4?&5?Zldb7VThH#FWCH}N__LAst6cH6xF8;E;E(Ffvs7@EtY_J*Hl)O}+R9E@o
zFWy6IKTIN5qp_in>4U9I6h*uAqZ$tk8j~b%Qgc*66fulX1XT0IjjrZ`f?DE%QT%@y
zwB*k(F1)lwOK<|53W>Oeyy2G|q&uVOc=&YKQb;PRoA_Z2Q*~*@_~6jc9uZjFL2FC;
z{0)gB3Zl;_#YsrH49n<Rc<d2k*f<auz!%P7EGjYyss%p}jj*L_V)t@<j)1A%sNm0#
z6=BzZ1~1tW^(n@d+MAN=yp=#^*)6jN>5iLEfbNW7MBp3;uHq`u&0EYqbz8&pFELU4
ze;_<{>HYLC4Z#iv-m`FOPBLw*Mf{m5rdr!lZ@OwM(Vx32*|B(td(i7|2)B{@<#7|J
zPeH!?*h6*d?_D2)D$KtJW4Or5H#?sDC#r2QZu<X@TV#C-h!+}v@-y(M|B!*=u8>lo
zkV!4U29^L-BwG@f$x!i$u(p$r2Zk|*UuON7MrX|`_#yZ~_Y6$4bebx168iRf2mNb3
z6hy0W8P+PJt;bf#C#I+N`CR1IV`c=0kI=M=72;GODa0_ke=XhLz|#Hf)@>$130DN!
zz+vqrROJ3QEEKQYjLj}Pwc%J0CA$1`uJIw$jdRyG8Ck$q@?7A<NE(Q*;PJUxoYlpt
zL3(5=u*6K5j~%Ab#uF*HvcyU5`j!vy#5OK3gcPxcNVdE@z?^kf`RpVu#D5rcdqxY=
zj1=r`Fvd(^e-m-8X|VN8r%Zj=Zb09#R1sTrpcLYfCH|$nV$j+>a@vqWCBnxFgSz3E
zC*`Le@Ju4SwU}*3=O#jb{K)rXHk$*9ZqLs>)hnab?lg4QhMdxB$*0d;z>V-8cl{Jp
z^I!DCxN)vuHy3L?UkXZ0w%X;4uTJL=?XK}cSR6K0&>yu8x8m~f0!Hrdm-zX6A$}1P
z@uzYm55;`zH=5&08s=>c4^0`gjc)gm!o(Z*t1G*HiKuYAp<-^JDM}~1oEgRjb76yv
z>bcQqZd{L_{ss{`3XhRi<9B@-EB*nT!p~(FA&m_d)2n4yzcAyhY>hKLV`rY1J4`-n
zbTiqjk7d&%LS=iA@^p{KK5R_e(YUoxYT9+!&i1$Og^s#$ON0d1`eU{RhqWN4<%z3{
z!>kGuhHRNKFI`fzc`It_ne!<jAm1F60#Z>hH*Rd0SP18TF;f4iikAtRp+7FkkeNit
z^}=9qdAR!J!e+h`7li^9JPsmG^t;}DhGTZN&k#e-F3{7Ri<<E@x;FuPTCm`-)6q!A
z!CaY`+M0#A$Nk$_ffyP9<1G`@3#C5tqbdT|D6~Kc8eUuTi&&$m8Cza4(JjA&nR;N!
zxXfE<7r`GktO@+J-sVk}V?V)H3WJ3Ho;?pV8I{D1XNnINr<Zlb`!9AeQ<NheRs~Yt
z?h6JKF3I=jP}lmjPEuLi9EFpXlHNR)u`=qu$*;M3W`}+=v>3%@Yo}yWKPUv229YbL
zUHj8&)Z0@<J!i%plc|@z@57c&Fho@N494xIe>%Fu4kGJJE(IPt=zmf+(wX%ktf-V7
zuW_{6p`Njs;AMGF66JF4z0RFD%uIU|GKXp6dMy$Zh0o*Q)LPMCf;bV8H(89zd)S_O
zRxLH!w}Zqxot<y=;=C(Ub(hP*yH(YejT3fh(zfVCa{&SQKu2weDp^HA=9i~9bEO@o
zrN=YcbP972I@}|s<L|<8T(=jTJdQ`ZjnoM<Rz<nh#p}AO-CC~k7@IXjv+#Qp9jw@6
zv>~UEOn6<h-HfZ1DPfqCy<@DOXx*J^5Jj66p~;(6&8pUqi7bMikWN_9*WgmlMc!mX
zRiJ#*6hKzsa*3OSvCE-3jC+(28(#nkz$wV9oWKsl@uQqF!VSahS2n+t+2ssKVD=Ow
zDrave>Mq9Qwq}$g-*EV}Z<RG!Fdll{dC5uYsJ6r0Z_$Uqi9QxjaWJ9lrec#c;P3A?
z@hh-q%`N)jg}OoCFp{Z%5_bd{ZQo1gFj?w&=T<{G5!wW>q#3P)^)0OZS<kA<&;wY0
zfYG6Zk2VieVs>{gMvt@8w^k7T?x$*Q6dy&Q&gS<Gh;POYrD3k)lxgNnCWCC#6tL$+
z`hUcVQOm4KhB07Y&zLz&CbkWzZ4qXhnutf2C$Icc{qv><j%ioKQY+sbU?py&Whm2j
zmDQ0&E6_VU_d#YTZMgMpwiY*5b9x19JDs*C=9}4mi{T!^wjQBHb=lX)Rct=OJI`o%
zT&;9UMjfp&ys3iOcqYIBp`5Wg8eHcc>}x-reZtJH@G7ioH=OJhZ^N&OR$aOBGBK5U
zCQHLln>SRaZ<(WHZm*Ki4N@AVQcp>bPctB;tb5P8bqJ<Weo)FWs(9;8!w5%Oa(QR4
z<DV>Jz7)sB+~c%e7}+z(IO#z{i&`#tj<N*GgFUVXcuqc}%$Hu0MYzJ3Adk~)zYd~l
zyp_x;vhoeMXqibMY_RFfBLsB7Q{da!r@3z*-e;%)8ju+`cY(NkGJ7l>pYt6h$eQxD
zq$4NQpPZ9h<M$XPI=&^R*`La~Jw6@@stLT<kI>tLtQ#qkb5!B}Zqzh+v@KaqC<jWK
z{R;9)j(c>NITQyenh?q~kc`CViK(#`S2zA(q@!{Z=x&^NIO}p1pM%E}B#5<(Eb4gR
zXL};+dZ8J4Q5U+AlXD}Pf*;Ty!xQUEp<gp3qxR`Onu43!fEFiit=|33z3{S65s=bG
zmiya1GM_8UsvpNj1};2!7LT{X!77(QS%STA4rY&(I|>_~?ZrqP#8a+5xAf|aNbzBy
zgzeZMRbAd!y#%piwcDMLMCMMHv)H+rI1q*!*5~R}ls<xXNPVE=PGqm+@zuDB+-dIH
ziP8XgEq&*Xs4`PUvKpsh9F|Iy+6e36PPv|LIjdnjVav|-{KZ5}hUCcbb4*bQ1rEq5
z(){2jM86yZ*!P4G3&RmpXFcA%U-*p#(@h&LsN3ocU3cu+GfFF-o(Urj{aoZ&ETpx)
zETTaq{MWTBQi!}!v3^8!B$%&jbyJvRkR8GXSp*D@J;Tqo+pm6yU@To@G{{!0&XJ0<
zjP2JdSOJe;Z_WU1n&<bAAC*&@42yl8SD%JSZCQ%+1jQftJ+9pzI2F<+8A2pQD#;C8
zSGfXe=UK;g+9H?H+2zfLX$8aV<wE+3nteH`h41fOqZE~w^fO<)W}}Z>dyN*y&DF{-
z)R0@<x4fBCyLFj3TwQ@}U%DGsRA`q_3R}rib$Ke+#e3Brv_1+n?q>`jyXAtJO9?yz
zlnWgjqf%H+Xnj&W<-V0TRC^evOqm!j1WR=Ahu_&d*87jpe%4tcs8Kx@_YFBa$D99E
znw#R;0LkLx@906`N^xt}B>kB%^+i?6c7sHYJl<x9bSlHj(9+lGHUGvUzD?gz-mIY!
zMGh6G6NBma3&%8s`cFHUPh%a%eCv`<%Vk(c*CI*!;{>;DF}$C1Gnebn)4P9q{pj<c
z7OBg@SkQcyscBGRqUkWMVF@yKq8`7bXQvbgl;ytJ+OXvOsLeqP(}f0I^v6R+uwt@7
z#ladK1&a4n*k@a&Q83ZRQSv6YbJ_Pc5oP|C>UTDlo<DmxpCKeBGFJB1)nR8jzMy|{
z9FOHP()GG%NnYGu@XJ99cF&X`G=scn%FA8trYr3Gm&l*89*Fptwnk!sj6v$wsN-x0
z$7E@;yvwnE)$f~g#A@+vAsxO52f^=ZjG(n@EEsZRw22XPW{T}Y@%(DW)=BRs7mX9X
z2uQdIl1!^!wxy3ixCU;-H<hPR>SCsMPa6!Wazz!GD2ZRw??qiB@my*=fv>f%|BGf_
zWMmmV=Q@k!e^-SDj!s@%{J%KFa-Fd6tSKF^*v~N|e!Ta>D9M@0wUaN_9~22#d<Jrb
zeHTa1gKB}j2>#VWwBL^z&aC`PtOI}dhq%XU!`l@A9ZffoyxB{91JZJT`o9b<@bCXO
zHYR@%An@V;bV%uKgD>q(Y*yX;uBJsr>{mN_g<>H=d&8VAwfkxkr%)b^la{S`D#S2$
ztv(y?ac95`?@Iou0LkMb*Y1s@1>&mHm><<#igbp|s2QFJ5SL;FYU{%#IO&9y5TLS0
zJ0w=eiZWJOpp$gJTIe>rYQ;fhg)apd<VE05n++R)u^iq1tLeIu^zcA>laBVo;%Eh%
zD`g^Ea_@S3mM;reIpy>3aP%lpWLKeaeZ<bi{@l#F;aZeDOhUEVD_#ybpVWx20@)Wg
z6?+2D12CxT)<1U>%ax)8EsIuR?2Ce7X*6UUshyOxUy&RcWmi9+_hy+DF~IQL*>%CM
z&Cjg9@nB^ryL*K72DUjWK<V*pvY4>Z0>5Obfj55Q!r4eBrj7QM&JDx-4|2d1Tl|V|
z!W_X3L6eA?QB)b4lqQS}9r_$P4|5tV5EDSM?W^4dR>+j-C?8dSh(5)ela_4J{-KX5
zL85AV+6pTB6d!|578fzX@13NXE@l5<0gRa6Ny{wszi_xexp?v^2%mi75E-mu62RLY
zJg7SzNnXS6-4z86zb8g;rI4E}`d-yH8oOM3_OD%pd-fWv0<THqQ3E^YtNEo?h;m=9
zmBfQK61wPqxt4}SNss2_O~kPFSesR`zLy!CJoe=cBxW74Fwiv^=r?#KsTMD%WZ%O}
z?A5n=%1tWBoAn8j=+KTz9ih`$cW5T2WcALtE-$ff?TNS6C8TK3I<1khsGC>DNq?Xt
z>UPcXA-s;O`wIjv`?vDxbA?nwj7HN%b6k^a=hC4jw+mwxv7gYA%;>Sw8*T{Dp%s-|
z91(oQAKS2%(#J75y|o^E=u{Hz$d&5Ue*^F~n}i+ENZRH1U?6PxFeNRkJq|M<cp4c$
zS2<mUZ52o9dpSOmSfFclzVD6^mI4x$f|7zu$tR(u*KZu{?(<rKI^kZ_?|Q$9tyP`P
zTf~}aRCYZvx=yptM{K@kOTk$D;3~s6_@Q^J2K|<b7892tc|Y<;VFN1ahk+tISF`J7
zUbLZISNEY;i?=f-Kmt&Um&oz)Rb<tvr6)0tXH^ffSwoZyvpzG^P1pRj)%;~DH!c&!
zX(pd@&9?c3Nre?RxP}e%zmRv)!Rb}WQNK6wa8?b=YsSo;`~2umhar8MXx{@Rl*&>Y
z?;9P6)6}fqo&QB%I+Sc^O49G~zQE9A?s{K|VA`7`efRpRKCpuWy4Hhq(}pP$pvb%#
zt3A4G_|{Y~LGV>bH7mjw?3}$>-32|cl3ZhJv*5+hn;iJ|ZUm6^J>8U&$D@gB4G>L=
z<uc33OJsSqJ{Ha+^`#Ry3iZ#1A99y7!>5=(1`g87?!-14K%sH{T6O8Lz(jMom?7w+
z;`Y`GE|gILrr$ZpQMFmfCOK3(R&0fZ+Fyw<XAi%BUR$0b-9KLUBi#k;_Pjh4i3Cx^
zj!DKSTy6(Mzdn#lzFS$It`u|C+g&9BNH4AXBQ_w91)kA>IeH|k7TvqJ52E>I`pY~8
zJaHAt!aP-y(|y11`}S2_<VP2v!?fUT=6bn*N<X5D`b#`&{#3Xqwp`*mEWWk@zR?5-
zr(^PpgF~NT6wsA~^zL?2^lOL3zEi+poH6-?wwIY?nL({OdDsNd!Hb$Qj&%>C5sga1
zi<8pi=r%vs%eIx(JQ1{=p*#-dTK%mdMU}b3319*<nEsXKi%6><;J|_|ux0n&4KeCN
zLkjBc>C8sPz2hfjMR3{QJKo=3Vv!wI9AvL3`e})4)c08I`T*>f)%YUN<u;<043On7
ztQyN}Quh`?4ZV38l~~xrBgmQZw!D+Y`Fit`n^v`95Yo4B@%0fu#*?2q2Q|8MdqBnG
z()$z)4(r};{Oo@bL`O^;NX^{WRlr9~|2>>=^NwJakI7a*Wzo}h{;^7m7aEhU84hS;
z_uGZ6=Lt1ju!GfEuC#%fhR?zWc(G8UKPFO<qMyAQxV^c_E3hi6FK<jk9R5dZ<!`sH
z7b;mh#?cfBoS<^mBwE^D`pWViKv_+#&?+Hketqnq)&0H*#|pZoKup-)ck6UH(n+{s
zY<bdzDbjG=nM5tPOgL`RJ6k=LJ%Uz92!Cqez}gekcp0IZr|L<XRS6vfO%p}a0t)m%
z5p9dAdP8NX;M~P<?ev^OMsa$RO>&`B&Yra@)}*o|PHedDFbom;KiBuVzQq=x;6N>-
z7XUdn!$b@ltL%{Jnl85iuffHM0X_DB2=AYh-k}o@ux^t4ZJ*;KY*m;`8h+_Pmc<(J
z66r%bodOkxH{47oE@`&1!)AMKV4fBCXjkX+gJ;-kR2hAsRR-Qww3`1J0iu<UuRGf|
zTHGm%tx+Q?C_NKjp7PdQ-3Vng+?}3-lsC}Xt$Ulz?r(X2X>8(7s@E%(-zbm^xSS|T
zayd$oa7};v5%69)WI7{)ZdLMsO`q&i)}WEja#p$g&a1&i`&+pykVSUuW>M93@ly4a
z=NKBW#G#<PXLI`clXp;NQc+2!%C5H0km$~9gx`_f{|*(rZJO48$x!T$-K<fmcxY>E
zVOGLE!w#JlL`G`7=rW`S{h;56TZj#TtYk`xpo}es`{KJlO>*!*X-ijB&y~XB1pa>R
zj$rrsqd#_P9S_Ok+LwMri)LCKP?Kpz>n>P+wne%Qnl-IdFjmc+04QJx*tiA$gJkz`
zSj_E}S%MfDtb94$pGO`BMtiicS?W({Fe_1!F}kY@THSFQ`uph)Zj30g5mZF0(G~<p
zC>~D~89vkUkC+00>Iwd%wC==fYkvM%9uEWizW&eVm%ogSBS8o9GaA?|=C3Y$`GtEk
zW>AE6Ye2gOa@)NYcxa+a{fm@Vt-SJhvqZ0;MLBD(@k9P-2Ha);SARQYH2a=ffGCo(
z-tnAx8O%@izrgL4hQ*|4zkHH-U?LH>1V}Sp|D%B51sCa$w7kl7_YT>ezu(e7IO;|(
zp7|?%-N*m_9d+%$pyhrWAKo&o2Hmj&ZQUP4C%U@7mt^0fS$c^!|10QG666p^v1*$Z
zJ+a)|Uk16z<s>B8L!W_oV{+IEbYbXz{z}7u-_?%i7}KpiZ=dmc%H}NjJkWLDr|M)B
z9&W)_y1nML5#hvsdlbJT3+R(>i~qDkpOfXC{t9UGWF%9o`;HNc@iSRXFTcJjt&raI
z<VA~mI6jx83yI!IKola`2UvLSGOkOaT`$;vNNX(3&J=Pz((e_SSo?zL>ovZBou}9*
zO$LQ~F(i9Y&N2!PC>T~J$9eA0QaQF_C2q>3W=H2rogp^vr&frd=ZW?=5?8fsTtBX`
z9~kNg{e&YQKT-ACwX-=5#xnAWC8=`V6$WYt|2R%h$|uGy`?I;r4hFqzCRd$G)_a+*
z4SDHAT}5^d?7q9t&b!c^tBaR}ZMTNmtr=bVr3K^%11ouoXsOcZh2~G@1^`Of&*{Ga
zzfErY9?jd_IGXKyW>HAzNJ)uOY1R3$E@O7t$M_VA!3Y;fZG!pdFf;vXC<0ZzE%S@;
z6T26)IveS=qdPVM0IaFTVTu~dj-A>FFcoiflyN;>+K<0`XQA$IKYDq(0?J!`HpJ=b
zxIf!|s%*E^nULFo;gFmJ0mxH%MxE{e(tOvqD+Gp*1NR|2&yFWxI#IQJ+eau!MD&ad
z9t=KF5b%sb=ttdJ-?05;<@&O{oM&ocnnMAlnC|kV(B1m!`&{VvGJx{Nd$#%PI2_}d
ztD1^;EQZJ9n9TCi(Uc4%km-HMzwRV7#(?ebxnN%uCZZNPF9w;69iMZefem*=Addau
z{qe$nO+ha(HZ0r^_9pq5*f^R#V#~rhTy!tzCo9#kA;U}j8I#iJOHK+Z_T|J|mvL!T
zL*_U@3vfK&=U=&U*nKC-Z*f<SoQl(Nq0{v?!9SnZxpBR{7xNhw_usA$tvygSz-n{h
zri}5=|G%S_^Zo~}HG3tSG1Kx`YclXc@rT*2PUTDR?pINoj!iY+ns&+C8gwsmCy42h
zeJ`Z!0?jgs_|hNh11z*i<1belE}H`QEI!&@t-IgOSm!j9y2rn9lv$6nQ|`tTAv{xu
zTONW$@^=GBl*%^Foqdj`G;>`Pv^}Cx52E<>zr?D}E`DN_Hx7hvNRtv62}8DeJ)9|g
zeQ(U9Zw>;S_9$i=DS>^37OxZje<Rp6m1cddNoHHdrqUiBgo?M5K+xv6Ihid3#atbV
zWLnsmmRQ>=AAu^jt|Eg3Wcr}Pk6;h>-wj&D!=_7E9HmHkPel%<TJiq8>%jbRDHr+5
zL1!YU@<)(vfLLEh$^j$J`G1S`QSQf$b*x!*RcV$gf>ENBf@Xv7pt+5a-=RGX^bMOa
z(BcD~n>;inojJAwV|}g^0q;eh&{a#C{^EZ%X5GnNI2-*pE`GqU>rNX2;xggYnpO~Z
zk<%~GD78lGdkrF>^3G+&IlS4c`+ow>6P_E*|JpWEn!C~ior9ycZI#C22mfwu_-Exq
zd5(htMBo<IlW)0|YR3R@0G<xR!jn&{pu{Qzdor+ZrivJ70C{N*16r6WW%wn^4?@H+
z?AUM&PLpvFg|Wg|w+;EY_Tjut(B&<Z+I-AB1<Q3`4(koV-=2;erFA3F8O&|~9+sd7
z>kP@f9$ksAx}M*|+@5wgn;sB`ehzOi$t<e2?KU~R6!-w1UNvV{5bUp4z&n0C&|EJm
zY3PsvwoyaY?iky)SNGsi4T}b)1w^G~{U=D=N?`J~ng!qWR-Ns}WRGeD@=oqweQ&Ia
zs#l}zR4sOv{77R@?iOS`!;6xSagN9M+cBO!X0qOp83~(AwmS-Ym8}@3R%5wOIBu4u
zx0<^-J@6)I7L(Q4v}0Jtu71B8f<7}^DfVG%1?)wzKa^%?6mD`_cRm@@ABV*Fk`lhs
z#oJ+|#kA`L`SIZa&SN4qeC6*XaZfccI`;c+84-YUTufN2SFc+#!PBe}TM=1$@`TyJ
zaVg#ta1_C?KVDsB+<Yx#fZGq0o1u~hcb#bhTJphfoOrKD$*=ot7TL8L5G+rj5-r=F
zz&POQtfy4tqXEIRIRbIs<meX}0xbLi^<u7hzoF#(BGjENjfGYj_@ym46~|I*bNz_z
z=ybSuNA!+6UbCcJIIz7Y;MNfYvx6nCow=1ftS`}e$S`km#^oXxHE822aO+GM)4n=G
zKQ-ixM~)b&T5Pau$n;EguLZQIV|o5Poj$^($O|MmivdWzi}mDu)vVP|%S4J)tzph^
zBWF2YCVzSR!&%JRHTtRPjuBYbi6Q?ox}pnc{Nze0=(_W*qz&4T7ddQYBv-W=CEY-w
z61-a+Thp#w7Kgm^6-otwq?g2V<A(oS2o5OvzgmBVhT+$(8$$2j@BzejnXS8b1QCC)
zstnP7v=5$5rmsc~f99VZ)*dz3%#;w0mP`w|Kv>zk2Kj4nyqxQW%K)(dBDr%NhVZ~D
zhHJ^`(GYOtQPlunp4$4x?;k7xCFHj;;eYD(*NX=XSm#44n-6Ksusq&i(8ajpg>ubo
zv(!o&HBq92I7`0MQ?8KYvScAQlUwet#y^uRiGRME2U?7po<+c(KYb*UkW*eQ9P<f2
zFA#sS_yIHVaQFkdgYq1S9_G)qjO9+K&bDnE*8klaq%9<<JPWV-31=#R|7$&kL19Rv
zU0hAMPrTf}aLJ>EADk$L+-hA~mR?6CCs!p3#$?=J>mj!g7OKWab)xq;^k2RS{7pi4
zQ%ht2_R&n!BHx(DZj@FIm|e-H#USFrp##A=EZ;v_C!)9RW7*Qg*7XvHc*$zbb`3lE
zJ`B;fkMGd={!NuWybD9f>wa%0%Hr3q!7gMqNCDE%XGlmoc7wMQJGMAQ69p{aHh+Q#
z^YTye9sOB<e8CrRSr@)B2+ECtm-Y97#rD6DF*iw2Q^<1>fM>lycrC`~s%CHSSL`4d
zlaj{&Dhy=IZa0rscn~xGjT5zjEZgv&4}9sxo6qDZJ!rJ3e=n8Xh?+XWTYzptegV`e
zTw0cFfKFv(;8V#0qA|Svu3%kLF+4n&GXes<+nbb_5hW2{YRCF0mcL2o5i{mW>G`+s
zlUDT8<Nz*fTRPk{Ln8AVQU1J8Pug)8K9;8F&viN?T`S!dy^)m>5z!o+sQCCSrEmoS
zg3lVxy%>Mm)BONHGs?FHUHv?;e~1YA$wg{1HpjjbSo2jM5~X`yJ_OgG9Q+f}{bK=(
zwQc0iOpcimZr48_M;R(F9|qav9X6q8_upwfIQ9R@@z^Zb%KRZoNp^P(adpeGs!CP~
z#bp)P;sHKr_yJ!mg}_EBwsGZLu;5Ox^@c$i-)>+Z!D+`pbmdipkUSn*AKy6lVKmTb
z%DHz_(!@b#cbYAHZsob<<|h}65&wM8ohB2o>b5}}0SCoK#LE0VgBS;n$YXpoZwPG^
zt$$zq>i)ZwnRVaJr0cy|Bj%j~!1@|0a-RN&V-*&K^Y@GHR1#4?$9?iLj?RcDtewS>
z2`FE`;xQOZW&pd`8q0vx`?V?&a@^-m-x<k^&0KHGm)vW+n?C$+cGZ7(zxy1oXN=6Q
zH$rMR3UQNMmp4w;q6jA8^bh!<-hw?$lExA@W?DK~Agh=hM@%R%Tt_O3(c4RO6GFdL
zF$YbD_oj>H9nUY;3Dkg2SG$SEWy1%Zuwl8NwlJ~85*5^>%=27_oui(;)396#lWFbG
zdHV4HuUIm~i;NEh@A02grQ!@f42<ky0Du>B98lptQ@i~sQnd67L6cCxS<=PTd$2<^
zlkx6(Z{+I|w`BO%1GiCx;%Zhqp#T>5`(8-fgFC?;Hke)p{0~%na&1li`0S)3gsDQV
zI*)gCW!Mz}&wivQw$AvUckKBnP)y{O=f+!$b%#`6Yyks>-0kHNS|!{#_Fhvvd*dQQ
zgCo?SOiw+zK4st%n-2RF_8$Qb8~eu}kKV1hYgX2i8LEj|Zi8J-KS{MJGbAt@;fLEJ
zL*c0GDqt_8pA8HoOVW_?bw~CIp^VW~4Z_>S7X2rE-G>-{PW}0`fcU&23EG`shxYvm
zqADkhWogtV4kr?s|ATKeIA1;F_S&=~KKo;g!@qIg_)wV_f{{GoMElq)DNrPi$%}UQ
z=JV^;_iI7KAh1Z*8;3pDMyFq`dzzX3#x%fTYK`kxF>0-@vP;6Gy15=9QseoGm!4Yv
z?X}IW7Gw+_Ku_xrkAeTrn?9wb-0HQQsQ1sLikvUhcKJ69fI$pdeV{J+@5KTPl#E<Z
zTGKZ-V_z9P&Z@5f0O_#-UO9P%*_2&xdCIcZ=bEBDCVna~1-;U00x;pAv})+}q2Rse
z34g3_5vfmZV8BBkUQD2X&7*+x?SBRs_^kBegNKfIcm9z%oY?5Xhp0w56lOUzr;i@N
zs-e6Lf+KT+9d2VmSIlfQ1~4Vse-MP|DnOG7$L9_%-qsA`>wNi8E30p}Tn?I(-@_x`
z0Vlw)Hs0L(*8_vUwtQ(Ez@Ae3XC6Spz=`39dMYRS|B$r&Y5vy&4L<Y#lezo<-B+ut
z<B`acg&o=hlpY*(<3B*6-E@a8#^04zQ50FWHf>D3%h1%3meu?B2mDdt3pd#-gdohf
zkspLfIP%H`^K!<s#aKAmX@Q$=*aJU-6ppvQ?*kSiJW7a?OI=-=eh-p3kfalaW{{}d
z7C-9@$y`e^%9W_7U^hYx0_hy0`=U7_{-2n!jpft?+)D1JE}y@boL2!dAdb@q*Pp=6
zOaFoG&npJ}$jQ4Rc-ZjTVm?@}K0VUAo>@?LoR*ZkOxl)m?`OkH2dKv}sDi-J5e(F(
zKy1;iQHfnX)lj?gl?Y!974&|!e}D;`&t~BPM%zU9$ib;+Q~~&wu#E&1He>XYr&9WC
z_%dPnXDmKN%-c!0;$k4*EyhI?W%^CO)B5@9K3Yf+t;DMtU~P_Pi;ihSTeqr;SUNv|
zWOlwj4Qi6AtFsg}e9J@bBhRzBfjKLaLg%d{fPn_X&o>huJP~2ahSe6sSB7<j6c>xk
z5&ngSRv<+l>sgB?gGw4ZjZa{|i5c(2sBr)6W-)I6ADFC39<)^5DWAyq>BgFx+g}0F
zV4+;iQHGV+&D*^0F1FL50SJ$CR1<<f<&#)c$9v|BPm2{eV4rC>q<+~)2?^PuPMK%o
z8v30V2?eoiSQpmwLZzefr0udYZG#$L`NxHYqOmeh4miK)0Ov%3K7>QF!17fqJIuet
zfh#GP4usBLragTs>eRbP>_YHp@!{fyjMVZiLBp&}tEQFd&ARI~acYpu=_-&XWiq4J
zH8xb2Naq>H0l$4*AV|DY;T=hP|8H(?wPv`bs=UDXo7ZuLrUurrKF@Y>4b2cbd5Q%|
zcex9;zgpe9QOE;3e`1CTr;v*i&kfCpdabQ_d_ePCO|)CyspGP%Su80oAr@QYq-5)2
zrWDHlP{PJ#EM#Khia*>ie0_D#<2{kLQpOh5p0oj#?l7}a4n#F5q)u3X=*a^S5+Y3>
zw_cg8V`>f)2k&8B-b%*L4?WAm)P1Cz7Rgb)FbXo?Pr4K)kenf%`LtVpZ2~(ulvhaG
zShE$~$06k*mJAjZH{+tolFBlY$;+Ek>_2`ApZlU%z#SjOPzK-%U=K>&;%p_PbDZnx
z^~8rF{qn#VXBK$KtxUUKO=>dTXv|iC)x%%_ggBvCHPG-nmzri7;<UjR_{S8#&@D|a
z&Nsi+==LHtul2{u(LmA}>R0-YMZ4*0s5q#1tD0u;F>AA`JyB4@nxirCmJ;n+)r$!X
z4}Oi<tMRvP2dhK#@vN<KUEjIh?TlXtjtiA~Pr5Y1Xvdc3AE2X?gozPPP}{trnzRay
z6cFTQqb`NG^SR{YpY8cPC)itB)xm5(JFBXpn>MaAxth~2KQSR&-;ZkRpb89pgdtLM
z!DSVNn71k|wOmnBA|)o)M#--BgPg|JLKIJobtb4wz^r(MiP@C)ZNCB6B?2e1)-sK_
zSO9QQ3nQe%BFkegD!%bs?!=L%pzZ8A`&MaM)y>TaYxX^0wcFX4bh~-&V!2-5{~(8w
zy(g~-qR}gHeM0txM)*@=QZyb(#Pyci*Jj{7Qf*USi+pgfWeA5unh<oe?|Kt6F&qw4
zs;sIIHUe>5*LgBbdW(}&KczaAiRo?M%Y^7Z^s>so)M{X)r=n)9TT!QKl51JAq}QJn
z0rcm<b&)D&Ev-xX42^q1IJ6hRI1*wkU@BBQwy0s7{@kQ5aD=k%i`3Qq8feIMxrmnL
zuK0j?q<GM%dBEdpDjJ%;fuML*f%awMVsBiW-8fynr@C_YmZC9UZ0~!#yvOH16JuJn
zcF<*L_$%7<L$C9V+5Q)zs1YlH=-o>lx-;Yc{9j!$iy=%Y_RGIg(A?MOd4_m=8>wrB
z+g90YO708Uxh>R0b`q^v8lW@2P8DY!Z?sW&)#FY05tBdvQ;m(0;^60FhS`C1_fB02
z)F4sxN4GrdD;+aZs)7<%TUXp_bIUyZW|X5JE-rX2HgTRNLC2Krpjo#Wc=u@R97VVN
zC#q(qV(siqr8X@#;r#&RcV0N=<gh$fhxL~X##G!i_L9s==N{Dm?GpG?3pZDN?<Bq2
zk6O?fK>rUquo~n;i?^R4h5@q`WoPEin!&evow{j)Vt2@xE}UKMjHxWdlbT8S!xmvM
z9EnB8Tjh+CtHz*yO%r-7@CrjSqdNmadV4uJAr&zMFGdqgt!++W%u-nW(k(U`pP*$T
z&hr^Y)N4{=)Kc#5!cgU`hI<;(AHG2K%*R)fUqLUO1fll9tu_RaGY6QDla#BzXX2(q
zw0(_!c5Uus?pmdx^OCa(6Ypc0pCJnb(W<_eLh0NLd78zkZoQ75epxK~7!5U2_!61T
zrBQ#s?AOELfhndVQ8ubIW+_HbyxsNApiq}1VNWhHkv3-Oj$`9fut#{3{MAOThzHZ`
zD{cldJ5!sB{0-*}PoW3hE5EBBP_2!+X+=LIVQ7#yWZC%Bb~!O=digzHS4u?20W_Bp
z{l?UInHJ=ormqoY)`0=$8@di)ubVdSDu8TEV>gu{2gt1T1u$Y)H{|BwreyNsXpC=X
z-`?>wPTKdEVpe<lk#cvw$o?65qi7o|diQ-u8svr7Yf-9QZ1W#j{?lKi5;8{WWAZDw
zZOS|2;#x?DH@|-U=;D$!pTSwvcw&)WtntY_*r-ryisbdHA7)MTZ(nU3u|M&fb;)n$
zZ=&ZUe&4@d-Dz63X{`_t5RuShThF6RfgaWU?EaMj3EzN~v#P0v-?}7SDe>!<?^BkK
zexN#T`_$Crit9jLik<$01;nXh(i}cYOL%~Y@UhK$??P(QlRB}eBpwfkg_$cpp67X5
zdrA3^<WG~P6;mxvE10BN7mqy)oiub5r}~GNI&KPOHUnQ{p)EOl8{eg8n}sdd6SUHE
zll2RcSO&F8Zk0`rjg9RTd@5iW?PQf+414kn=T*pXU<0phSyk~@FsJV*3j>?QLG-zi
zsKTX3?F1aF2OE98#lTszEXSzZUv2KjZZpIg%6<6B{Cx@6tBq###>=f7?`fkvo7_N3
z!rNN;#mb#oIpESZbr74S`q)>b4oDcCuaDBKOSdQPUL1o284NiF6)_~}8w+gAiveb%
zs1rA)ooWCyJy^JGC~IPplDmBfH#aatBwnp=(Y>4OneWDKgK7&^RMPI(%n>0^G=B14
z_ww-aA<gQ1N*6A;T<VQp{Ve!(Kmg3ouSi5Zll6U_ik`)f!ri&IQVCilH64!W2xn$A
zw6ICHZgtVeDAob9$tHoUqmVit(q?GUx)b5;L~WMhSVDWe{)Wpu&s%bRL;a1KI_2RY
zdskPX(`4lJC`{X(?A@BP5Dta;gk0?h-lC|;mn`ejt_jM#%p*1x{ci@<&tRE^N@cSl
zeLgj@YQB$?>W>bdRQt0%CtkA|(XA`7!rhcRt$I0dDIPRy9)!9{Nkg99*~okjT}v{Q
z80d4#&76`EMn+D0fql(CP7g1t%)er5H#Mu%ZD#Er>BtJXdt<H+yS<~$LvlHoaIQCO
z0P59xL)98fi=tTIPg*0_XH=<dJI*3)qG~JU@aQXjKIGB2Atj$X>K-aj2{6c?RI$1v
ze6uf3m*(tpux&T)kD+{lhZd1D@0K>A&BLg6pXmKbQDI;V2G*d}TtGnt@Pc*o<ZF0K
zQ^Uf3{*!_tk*(;9fl1;stQDNS;9WxD=ctgN+uG+Z9_LuyeBWh%8#p@Vur1WJ7))>|
zYp*<XA}tkmiY@4AEI#1C%4HimG7&s-E9|YWHZSbi!rj=7snDtDay_73Cg0G@ejexP
zr?Sq@&G4mbb*qm6DUE(+S(b}~`%<uRfSNS<Ry#|N$bxNem|xAoraW2$&Xb}M6=fh-
zZaB<vnCmZCRq(!?+s4S#G4_v^zwS~4&_2BGZ^F_ojYd8(E>)m@uyF6yx_M#1_iY(=
z=zLJSdNAK&>Ex`LRjnmbLe|}<G#q~A>)S7t$79s)inc^Qdol`c0)CdzgQK>M#O{`9
za`&|3<J}m}56Y&YR#Y9>VKt@b>#C)*E^Q;nZ>0-9je(EP55#bCa>b9_BKQ!D<#0m!
zYxip%ko5!v6Q$mOkmT5J7Ahk(QYogRl(+nICBy$o%#4%-3Unfdam4?`WJn7!;09;R
zj-pmX<@U=dtqOQ?BU^Dmz5|~O{y+E{C=4lR#p7%BJ655SCM@U)mJVo_(PvD+@oK!U
zsPUcp&yljqXKu)?eUd}OwtGqSU(obQX5QrSf9y|~OVF<xA5uTPbWiBiJdw|8)!2CI
z*>%qKHV8JCR~$XX)mOF27Up)uDn-VwJa2v)ZlEHU!#41Sn=Uzd=jZJL(}H<WFPp5I
z*~yWJ$3;fIv5xY+-j~gESc?qjX@?m4eQRmQHbO>52eGjM6)skIl_sR5l+V6IXRTL!
z{}poUazl*2lU}iAuOg<(zpTLNb8=`EBwsv{k4~+)#KtW|zI>FA-LJQFq)l`rk}NGd
zK4m8!OhB1_#OTpFq~#fVGqp|Cr4|Xc++k3@_PD&b(LJZApLD8Az4{;{z^9S`b~k}9
zUQLL%#RDm3Jo`a`%g6%Gc7Pa>qZHSL^*JKIFZixHiq8vQSwx5`7xRdmWU8c5zMkv+
zoZtBHabo09eX95OzRjYH@6$G7zD6=HVl|JdLcetob3;WXakzt8IJqxcZ4x}!CBbgT
zTBagaf>2@9rMgd~3r3-PQv!_P4|vr&H#J@g;cQ)SjyVQg9KZG^h-UYL#gnIV$~?8I
z_Dj>+=rgQbXJN%J%$byv(J7w3*!fW4vfMOxx&G54(1NXA*Y|s;3LYld*-{(_H*i#X
zuPA$?=y~<Kg~Y>eeVSR`9##EU(0zWpnxW&X;8!_qQWCqAIv0d3Lt5K{u5vj{wzhS(
zhf%c{v|6Q;y9#n1%5&dV!Vx~cm8~sEZrGJ~m~0-_%qy7BLIAf)Jr&2PNrMGv3)u?Z
zPMVmtD5lC>H@fd2x~9x~TOby&f|t|R7^}eFwt0$FJHcLz;0|)P485jijS|QHyD6J`
z#OSBSFHnjwNAXOIyB?xg*QZDv9Aa9sT@=31{i1FTJxZHh7784PLN>Ks#cT{9m$BjD
z>`$K((*zAI&rMQ|uPh9{CDM>f&$u<(OUxaS@;<RiuF1`>HxX03`1xI!KFHOP#PjfK
zleaDW$FFV;4LNPm3us}&Sfba!Lw04T)%zN#C;Q>VtWjT0r)ibqV~51`iQVd9)J@hU
zw!^)NB>q*MRch)e(HItP7TKS?360jXoPO;+-@ktf`mUV7etk?GXE^m|YdTMDfMJ4E
zxw<E~m+@tTDh`P-=~pKncA)^r^;GHI80HW0E<)xH6H0B^W~`J(^??loVq7`Ii4V$l
zk3I@kjN}E;d5%PMErf?;1lyiPqKifm^m0u$GP3-f44G-(_Y&-#6vSqNmF*F5I-c6$
z&T%+p|0s`$Z>aE$Cop(M5_08o<3un$U53-AxKrzmK3nNB>x#ZhX=<>O$lu1D_>Jyf
zTc|fC&B27vl(FRiOUs$fg*gXEr3SojI<@z$L%KHW14nQZr>ylP+NPyoqp6avRd!JR
zB&V~v{vFaju`G#|qsLSzUX344ntWxrSk~6S6mUaERt0=2|KRDg)PX78Cn6mf<O%%f
zGt0=SToRTaCr|`Eq?ZzJQ~9z?#$hv%a$T!|r;mqSA}@B&3+H;t-NnO-lgpW@Ukx%7
zkWkYtm_x_N!|v763~b^YnWwuXqmO7-?&anuvtlPD;XR?_W^&@QF1s}5PcI=Y-dFPV
z>mT<q0WJReA@R_A_p`i(`uzeeig=!rL{JAx%qYqa!pL8u200CIRh~MX$BZ*&zb&gR
z+OUZ4_u?YK;$COP?xK>FjWbcRAgcd}(9*ULoHImU`uy2!sr`d)=e4YK(>>R7CHN?P
zkl?ga!It;8ZrasX`F+YF9idi|6Deg=13x9$xnH^MY+fIRyS=;X4O5LGsXUg0(r!>;
zly`5lB`BXgJmX3145h1iGhrQw`D@J_dO%+Ilu)WR6W>RY-08tR=(JPXm}Onc*Z9{F
zL-tjfYsdUZ4gKskx;n}igYVxD<b=H*8#CLUuiceC+4T9aQ7S~{?YNPiOUY$9FZcf4
zD{MSy8~&`(;FF-<+M3P<wmPcvC7-EeURlYL{y?<`PTRKY?;EaU0w3V`gB$WA(ByE_
z=+vOw^9`_QfLYIq-*$rSYZ=BhE7vKeYk6+%PAC>F^^m-eOe#pYzEwfj)alTU6q3q?
zCtVy3UaWKOY&vsn26D~h#XK`Z8y~gxCPEQR78W%NODMIpMrUT1oma<hp^8Q_%uNV_
z9)EtwZ@UXUW*hjCTLR${fNF*8dpb|Y=NIiHVx}2c2^ivFzwmAq@6Qi@uRlDR_f?eK
zI%rnCYVDZKPN?UT#BD8`-bJuuECQS%pneZdqM)lI>vdL5V(CkoXSV-3#GQ1%-hevN
zvLLftKYIiQnH$9r$$n=pZntmqu^1BZWb5YWBax=X0AgNh>bi$lJOO4?mw^HM*c8NM
zZ7DF2;57~wa!bpEKV#$TGpg~{5j{}64{^ghFu@wFDv}4$^*wTP`}mb_cZg7E3-(=(
zDbqoBQ@~GClPgfr=VYIVd#y!($bj3Hcx^vXwZT%-IKERn^@T5il`5TLS!{zzkD_8Y
zN5W-n$k9TuU+9+$7A?jYIkAMb*Dpd{^!)|>G9Z!9r<Br*%m&tFn^w7gSXV=~y&&NM
z-a>8bw+?*~hoPYmf?bTobs_NqAZYqP0ruhoqS0V=H1Hf3Qx`06V?(D7d%|%N0voW=
zHhXA+7iRrtL4^bbr6qSgCfE@)%EJS3|J*Dp!twSUuUZb*_zV*_`2=&2`}f|P%Wd|{
zEtoF{$BMFQXwlxiQvp1c<)=K96x-9?{ad+4p`i{`nR#NdjkhC*>wCF5rsIaBTys-x
z>H382n=w=pYEPHPhAwKPU0tD&;~0%aAD0`Iy*YeAKjyrl>EpM`7%(4Czvb(z(EInz
zVz`clO;C4wW|)`UyVd(q(A97-CBz5(_-?~SCN_%0c&QabpI}A5z_OQGJ9;f6(+M*a
zmBn?2NpQwI#jc*1?2Z985u4!~{8vX4i{2R2HuKP(()FKy0i4pnB~}u<K$a&i?#Ti#
zFVBz=i7)y?7Y&#M0pZh~EQPd3GG|qZ+@A7IomZZhJ)iW`7il935*e6<$@UW6({5#?
ztBl9@<W!$w;)OoJbG+U@@9Ytgkd}!qkcEmC#?V_Jhf4M5w=TUxuvuq`0W>+V6)AjE
zQS~Y+^vAXtxH5`6dNML^IKnRq?KX)qC`X{DUR_<nA#5r%t_D4$R2c`bt*!UvJ;N_?
z&-U$0<55#zs2BzA8kux+PG{|##d92glYd6_EUfUf^5$OiOO>}xMV<H9yq`F!C`;!b
z{U9;)?k=m(JqWF0v%FCBVdA}&j{OwR6W$<^b@y&ipY9PB^-}v{&D3<3s0}_W-fQ{j
z6CqQ<FBj(?XGYx)POx}+GYOwv>Fhr`8rM7ND{T8pr&vCv(l5g3SgSXVw;qn&PpW{e
zNn@s<IXv9fwj0Ldyf*6);9fQ){^=7JuWwJ!<dDqB>$I9TLOOIy_wR2O?4753d#SP*
z^mItQ;Xbh{%U${;pnH1!8jXSXZOq)mO@dL)(rKm9+*b;xT`z(pc6N{>0j-GH&-?p;
zQh2PmS)*ysMng*%-&A?5vnSY!1N2(ofBStyx6O=Va(_)uO;nZU<me6lKkU6{IGo-4
zE<CA{Xh}pDqDL3Kdx9Wpln|XDx>2JOk02t59zBTOf@q_LAlm3g?`?F(7=~dld4A8{
z`@fI({r0{e_CEG}$Q*Isv({bKTGw@**SXH?Yvshzj~`nOHhMG^idvs|Go6xUo<iS-
zX3G@iAVV5D*-ONesqjZPDrd<fSkJwW2c+Nh-@Y4WsQdWyPWkOTtKu#8-Qt3iiu}17
z3Q|13qhh)=aX6pSd>8Lkjn4FBD(p>fGmE&kCtu^GCJ92as>hfnQ<ik?iqp~9ICn2E
zXMg{nuWuub`$r|=i-%&2MoW*@iE`8~hSH66)PtTk_4S3JQTWka@IxnW($Qg@n>0)<
zXkjI7s)WcVU=6i8YgE&lTFFFTzI#$zhRqaIwSAeHSI)$3;8K~G^G)f--^2XQse1hF
zwv`vqxzZPO8R4uacZYWG2ui1lkUgZJ;KU#$BUgK~H(`q%Pqn>gic<W4Om6@4yjo*U
zPg1aT-jt@k3*k(hH%||*1D57yhj<ZF&c9fINMarJl@LXTaz{Jc!Vx4kMKf>*ThP>`
z2K{jVPL3fr?p%A%)0ZrKC(8_v@M(Hq|J>w=NXu<jcd{NhOdsngEzfT5VPvydEQup(
zkS_sw3o9e%u*7I`vU;4UpJYZ~B-+_n#o7DWt06N1|0I(=J!8jDGU;0lL%$|!_44Ml
zw6<|^zYJ%WTfPpnF8a<net$J9_V(B53YUJRje(v`qdb>srQh|dWU*bx=-vmH=w+Ra
z!Sk-r&L|-pfpqaFNpIs4MvAm$hzwZn0uZh=c3p}DJ8ECGA}D0f!-ZY{y}%MtbF1r(
zM{0fvn~g*C-tkX?C(dbI$Wdd5x0=(_wNf0L+1E~|+>+15GTG!Ejf`Hu_&y@~GSp{>
zSaWFl7<-hVKB^sha-18gP)k)~JA$Y5(MOsg+u7r(v231Z%fj<u2B8#pZ#5F#McH05
zgQrG>4ycKy8LmRLtGq|IWLo1bZ-CcfO7VD6i}JEUbb|a<-t(?Ml`F0iQRH3qYH*5v
ztjRR=s#wt5s7l9<VvBW;k5>3;>F0x5KJKVDWbBpCZFtFk)J%2#g;>3H_s$aO9h0UO
zi<;5G(Ps{8PWC*90d)xOIwm<z_XwWjx*uCJ#pc(fQ`;@%x=7DoM;ktx=bcarYI;^w
z@S=KnU?Ej3>~J4V9&R)A)3Q9?+lXWPTjO@BnDgy8#WvDAY#BVOsL`9U;qqFuleQK5
zH$6oNqhe%Rml>kpwb^8^4Gc}^KJ2w3IK21l_~!9*W&!Sn3K6BWT-B0NTL;=-j8`eH
zhlYM0GFlU9ykD`T8vslGr$oem&jen|{+p^;3ni^@*XB(;fyZ}SNR3U)g?xQhmM82Y
z#TgcfR1*GR=lFpxJRFX6!bUb4PN+dGZdtPmz`qLfS@co4SFUd95}-S+tI~@L7-Z$?
zG%W4-8~@}^L<ldb$}LV|TF0{zHV4RX(chVqlR#(>tREl%xpv9me20qavoL-@?bGv(
zEwz;G84XcZ)hj8aRq&q{-evxwVXh5-9IyTK_3Mv!kSB=<!QBu$=a(JgosmB_+%D%9
z#MJZApQhMmb)WEa7W=5`3^hg~`z>=qZS5`raY)N|N+420PRktEMcwmp9e;fOn8_%#
zqOmj?91AYg&jCiEw4B<(8;3n>NQ)=^r&SR`wt2<$8UYddiLV;%Dk*)Be&r+Xe5(NJ
ztXa7FKXi(X5q2tD0b4;XeTOO~w6a%H`y0l~4k2y!dqw#JoQx8JOXI{Qbo!WrQ40Y|
z!XHj&q3#Q8vDfeG1t?gSHerJqS2&46XN@Ivo(qFZRe8ipO}&fT56$z~_T3yGRAp}e
zr@D!$1p(ju=Ns4inl^GbrelG?9?YgvZ~N_<@+)@(S5@Pqts-a)7SCJaGsj(|So{L;
zLWgqK#p2vz|6C6EhoJ8fk49KJUp9+${nq*w1WVA<p!=akhQ3ZUGjAf2_!v(U=}u{X
zlYHE`;{s$*#J7$n&+K8(IgqPE^|bdt<b(?Q`oBhbkV_xFmw3$dm?d*@Ir<A5f3wei
z8PKF-f$RMM^(@}=Wi)0q2b^`fALirDn#>vM6~3%iZ9E2L>dx!+$}&Lp1v*I=@)`Ff
z6qE*czB$BrdYP`i{1`%RivA7KdsKq97#4M=Mf~<1)ol5;1(YPXs5?b!mch(9!A!YB
zS7*M(3k)9bEr^5Cz8h>Dh`n}AeXUrZ#qkbk@6EPqjInBJ<!6ouCH~80bduh}4wYLw
zp|wWkzk%+|6TtR7f^C2d6D4?YR_~d<)$TBJiatc%{O1~4g3WmuMJQCPIA!>W5V@R>
zKJ+b!(ZK&M%qg%-{A#C-2X>WU#1h)b$H<nMdXu38`Qj<mty(O>|LW0TCONJQmLJ+#
zX=O`1el;^G=VMwiF7O>}@qc0~=%#CTsRQuZ9e!J12w4RrhIe-w*jYLJSAF&MViQ&W
zxduREdh+F+?7jQkpA~^7(qIJ;pulcau{6S;{{AG0c!*ozNOm4D0&jTbXC|mz*ciET
zJNQjwdUeg0Pb_KG9Czr!>u7XGBu&T<la+0`$KepJBcN2X?$gof@ye$El9u>SkK7bM
zkS@4w&7hAAvHl63i@jzNAUAx+d+GumS_(89qrU6)8K$=kmtT#2>H(x7^iqT<-1T94
zCULC$C=XSoWKaUT)5o5jgXqIYvx--oM4hZ6#X@r^2qBdd&{`uAWaEb-`u|KS&?D&W
zw#ekB?eS}8uz3ZMYdnKwrx;<^rDyPCS9oM!R<z^8X~HB#eF&;|B+^Wp57{7DO3wb-
zaJ|_nw566@^J__xs%qmuTe;77hBJ=-?B&jk{~vNTJu|(<2vGhBJU3gRKZ^<Iy4I98
z3+R+{MXY&$F_F{8#=NYT!j{>&9!;i%wK;=3EA3;hk^WroYG>zugVLFU?pRjK>p4&+
zzisGg@u&O_uXQ=bMEGXVQ_z~}EgB+)i~qI69zgDR2`)E%F0-?zsS1#oUGHSRw|1ZX
zb<>Mp(vO}-ZBIa%N@SUcrR+mW=OVfjJGsdR-vE2<&xbturwX4Es0}rpmcq{s6R>s3
z9q&{ho&0UeOFr$CSe>o<C_ZEID7No43nTY`Fu?!(bp9$oNRQhV6-)w!N+8z?gTK{h
zfp6+$J#)$E7-Fb=sxB}464A>2pVOT(DSca>!dTG7@Gci<^{DnA_Sc_-6ncOl@-GMM
zzgM&YhyK})N|8vR!ji)C=+C)Emn4Ul+6Sqhm+2@~;UpLN<KvXBf9CWjgUdV*_brWB
z{#bG@bCl<GiE;`;`LsXFe@kufJK&HnnpccVgvrfi#$oYdo`mou9OP*7Eqc#Dt+ZtQ
z{4XVu0U^Xr@sAy;eMCqAv^=aQr!1}ncEdn{H%gT^i_^hXb$M=SO1i3BpG3C>UmoI`
z+q@nsd;-j1#=8{Sg&m7m!@CrT6_abeS3gof%+AjEucjW^TKNER%$T_DRa7yMKdve$
zXowpeeV5CX$!2pkEUq08)pcTZinOY!M{Qv}tOAC#55UViOiLqdzX8esdbYo=WMoxc
zQMQyX$t}rMLd>ofV#d`2FdPROaw^FiV&At0{MUju?#INv7NW3b1@z25dz+#XZ9%~y
zZ>$6u5n&JR5G7jitpg=cP!;lzk@{3!d7XxaMeFzK_aqgtIz!~6W){9rZhIF2IYJUZ
z%)4(Qt!ftzt73l49oW=gGgXYMavR@<5#{{iX(4q2g&v490N*Oh@|krl15<GmZ~wR9
z8>}qBIjV)dVlu=|)flwL4H^NW`Mu+fgg5#^DWBZE@(A<=)tT<7KF0_q8BQo!yRe7%
z74-GwK7XqCx)4@Umkp=9t9W*XW6Yvb4oBO@L**=9x!9r$NM`90#}Q>ExfM;1c^-*H
zzBO<$rIXA!$0B$AktgIkvv7;@`)fQqqs>q`ZJ(ExdN$D}+Mfcni#g`^2*V%zUU5GW
zCCiR}LnpvZe>skLZ+h0t1@~BVd--yQ2fJO9e~4rGHun(@Rb(kGx+<bTko#gsc9<~P
zj$)L(AmANlwJ_mLSVl$>=RWb*-HV4tKeKwJzgLzAI_mf3t{!MM$;rgx>z6s&k#bCL
z<IrhoZ|frxxPXGCuyx=~hQr5!+N-v*vayjJ-a+~f+C?u_2@l?x>NZL|{??eOGd%V>
z8<!Zr$E2AY?<xHf`*pIAy@bV8OOGwKi>zze`0^eb2db;8M|CbqeWn>id|%)r8DIk%
z5>?>n(6L8&IclG@PTeB9k|GP~pujrVNKNItL)M>ftf{*aBJv4UeNuk)H&+(?RQ91F
ze9y#!|4WlfUC|de1D&sX9bJ(Le<`$y7C_G*1Pe60s1dlq%C!IMb*v7@{=O?A=Ia+4
zHB%LuJ{=K>D?wdfDFcgUzh=&02VK8T)V*M-(c>!hrb_&PI|CG=X{%P!J2T{;JeNfz
zzx6m)4fxkGM3-t!m`LMh%E;e(TnJH3xLM)SBG6aE1ROhPVvUvC(ju|m-n4%fYx$I#
zcR>+R-DX=qYnWT=vcf_J6rvlflkA3{&K2>0F`kX}Fv(e@GcEt(DU-SBO~P8ggdn7R
z-{n+=@OZ0uc9rucqX~OSm-x!$!)UQEe+O=k(dwF;9UZPWWOV%iC-JP<i_K_FHYf&m
zM&l9MXURO9cS{sMv`twWF!<}rlY7C`9+ya$5aE2puET_)bkn^YD^9dt_##f0cRoEm
zuD&j!%Mc7T*Z7%K$4{cg+|-mjyu>D<StW4#OkR)cjgeI-xU6nlp#!<sx*+$(_k{q_
z`}LRTdiF~)3i~Hi1h(<G!{4`>RCF>jWQQY+)0F*ieK-A(KN}l2RK-e8`4U{)SDp1}
zA~o{RLtuJ~ivZ!$lEP_QA)w5PDaL@DL%3W-POt#pKco2XJu?wViyX^=#@*2D$}Uk4
zd5r1`P1*tuY%9l4WCi3xYkh<1_%v13gZaDBhCdhfubGonIh5=SyuZod8>YQMH_k6y
zzD{^B&nvX8$eBZrzj<gG1(b9}B&KZ)9IAkL%RRE6rhLzun$8EyEg(^mtoO@BroYx&
z#Oj#8aQ8;$HJ?iA`fChUe7$R>PLQj}B24YpJV{N-e1!5)|3_Pm@#f`fs$x;9C*w0_
zJv9}yNYY5R(x8;1^;|2AACY%=$XHi)_zt4G3=4-(PV*xy$4khvVX@U^JiQ*eW8|wh
zn3>x9lC4GxHxFDHS=F<<ZuQ9llM1$`Aei}uVxLbHd{cOGD|27Y{JGf+!`G&Uf47@j
zmzA(sWnWh2X1)E5uV}(BcDQj_DFAoq(LD67WgyN?H>Gw0wT|d6&X$jWHH%m26$`ZA
zdamR={tyc%!t(m;Y}@BADX$#<`p2|z0;c30zrHo+j0@yu&XtZhouFCs#y>nr_r7c6
zfOCIMw-(4_g1XPY5WB_r^+(H(<Q_$bu;j6A+9|kj#SFqs-ra6na5^+uTgNVOi+F2`
zJV>hSsV=^B-`gHJj_Mm`0ZT3mYFGHRF-#Q}!6#$7UNdvOVkf+{xOYr|;Csv%BNjP^
zyG+!ze4spIX1{Wq?TT|V)p9SnGFAA&hAVtwN&IpHtglR)-`_zX?r=-%t`w@CvX5X6
zzB2eEwe;!VZk3gprP<}_1eM@=Ktr=Wm5u*m0T7BOLBt~K9Qv{H!-o3nrO)*n7+fZ4
zvh_!eU(U{HJPos{@%_Ft>{DjfEA4(#Sw?$)*qFO05yhp&4f|m_r4D9rhY+Z1DQdKy
zX=@9DwMF?&|4V}kLJ8!3(rld)$3l-eP8M@54adbr(u#Rr9tHOiog8ixzcKjQ><RT%
za)Pyun-E?pu*zNDC4_epzDWaI9w!&Epr0y6bs;>_XhdN-udoX?HC=F!f6W9lsZis0
z=r`G}JD_?o{)>9<TxpR`u^HaD^i(%xKJF8T$=NO;)IR~X$frx_;EPMim_7K3J;9u(
zw|KG~pw;!7^w*b^FZ%+Yo0hkFejVvWWaTt`VZ7^7E0Hc|J7jk%8QGOZsW5U_SE}m$
zJ0_I&;xOIL=A@cf_`xo=uBzb}by`|~T2yjabebQGk;aZfp*g`tCjNPD7u=O<{1@q=
zb9LTqxa9$9mcSOzHzWD$y0JR4|MYm-<(1B|8!Wl<mSUZjkL`*$Zw9r!*(_rY?}J}>
znRh=+gpCp4D=BRjmkDmB27ai>9g-GmqTkitg_CG9<o0^n2Vi{Znlzq7oa9lVD$0Bp
z`VNA8Dw;2VsMViO%Z;tG>oh;vD5Hnpq+y-YOtkHtx|u8;axh1vp+}s4>-)KjSBC`S
z{rZgva@Vv9#pBWKLBi<blXITtY>(vcPA8KA&6vJ6kNXr*P#bD7i<ICE#$D5<h?~{O
zP8ihHY5(@}Kb+lnSAZy)f;Beo`}1KJVTaG5A$TmgKjO$Lyv{0VU-~WHieR<QtZI<E
zcdy-|e4W}z?}fFNS!7Y*sUOd%q2{9lG|A}=>nZ)L-2M_VpfoAp_eIy;Ex^zC2uJ<)
z9!02%zA9XO(<ZQeCAXwO0@{NS3I|&f{(MsFGjGylQfjpg<*hnm;lg}kOzstxcS*%R
zzst7nOz5&pMLB+PPj1U-@)%WyhWlNM^gqc2#j*rNPH?)2rUU6x#p6-g8iP+EM$j`9
z3?Y??CRI2ZdI$Dr^w%yN1!Hitj#XQ}OE><EO3)=a??1%p!6m7Hz=59VFlC($@wlhY
zZ7fgUDqan;q4yZB34urMvGD_0?ETV`>!zkaO?tAB!$mkiVW}|i2UKufa;)bM3gis;
zp90HAcK>oMXxT~akBd*Vm~2_{KUHsv1cwNMYG2xg^8Ven0IIwau<%=+01fe1UY<Om
zJj>T_+c47;UF9_u3eT~>fM3b|*T44zJ8ppMfPJr!{DUf1ZS%X{H4?3vdNJD~P#$G~
z?N4qJwB2F~&dcwYd<y+HXfplr<d2hhc~ImM%l_x{|F%P;-=M|J!?a45!gbH#Kfm(>
zR<ro6_!SEC|MDjS9sK|Dr}D-v{;BOWmh8`cX8cJiH-jLbXzSa|s;1C7;Wz$Ka{-c$
z#MPLY!@h6b_6+~I5QsU&KT^x!|Nq}mxEoPqP9Q+%{qg~*hs!KeQ?`?YgBs7IAFnRm
zU+-fTNKLJ$r<H=qA1s41RYV!;A%Tgz%w8{Ug}3kQ{sk&G@upqYJ!<j%$+9NfJCfu)
zy!M!S<CDIisE3wLsc0P<?<#~>C(I8gC-pI1P^dBo__Fo(d{bOHF6Vp9nt>`E3kM}{
zDxc2SfbAB{esevhyb)AT={J4eMy`6d)tT;hlU}Q1WJy_~BQ4q78mX@Gl=gjuQ9B7y
zDEBf9opBu7jL;`+^s<p?k-}Ryq&savORASD+CNF@;@vxF{FQrh1NZ3X>d9YZi9Mzj
zmqraN4M4mM><R($^f$8A_&*;dp6&GCt|T8wY<9mPN}V1s<XFkoyc^wgr4tmV1cF39
z(mqiMtYx+KJMJ}joy_OvXhYmZr3amp%WQBUCIdMY-fcT-`BJ%h+TnY|lZV&nKQl5J
z&K^2>-L4bvVix6I8QM|g-fqn?yhHDCJ%;A`)$81uLFMI7#%m1{Mo-C}Pfhizd0iBh
zlj}_yZI?3n&>>IJp15BAepGL-w{$&!vse1XFhYEV=3The`f`|47>kr?^Xspb<`U9x
zu_b<Komu#-BM~8E?YNn=;POE?_OybMB6$DU$V>K>^}h=ptO=MIbajQ@N|~(!b{jh*
zR~16qgbXHiKSf0*D7B;JR=>G%Cw{nZ<$IBr>UG8F)9#rY_g4RXNQ>o)?=^*`#T-P#
zs;b#*0pA}l3sPNAR#Iw8>aZ|O<5H>h>&}Q8`1fUm)Y*9#QbGCx>2y-pe33}G3TfEe
zFd!G?G``Oga_SwbMpFj2H>&gYwf~XZ^h8OH5$6|sPpE+yYSd(F@fBLTwoEWZ(5#CW
z=@G)k)Vg+(^V-Jx(V3&eT&>puEvik{?;!~^$UwKadu%jK!uNYqouKaA-D<-U-eJ84
zZzB_3g@Vr+sj($xbQ?$;y|Hu^tM2xFHbnByY~IwH&tJwfUVqbOXRe$WvUWb2QeldX
zP@Z%_qci=8)7OcpZ}V#<*`q3sRJh5R@6%&HMMVTBJXz_rwhilGR(2tbpf4tN^9Y98
zyQi4F$;~Y_<R+C5!He?fN7q@|ZBmi*+@7l${CU21j!<`2&`Lg-%{$Y(GX>R$32;&-
zYrI}OrRsB15JVHIDo?V9Ss&JAz$RB$_m&<sJzF^C_dJl>ABl0rm0y8;2uIzanSfz8
z=Z+=uGCXT}#VWQwMpWuCC#j4HRlP?9o5d?gVG4$!wsW;Bp#c|Vvllybw=zr`w{<V3
zlD82UkGE%K8K>peV~*aaDX4!B#?sE#L(*y2>S7DS@GjiGwuaS^DuGkd+@C!SDf%`)
zH?zRGYv^px$>waLjq-kh1w-@~v!I0%=qr|D7i{l$8AQ6#LRvtMrWCHxdbgaBt4CL;
zrYiIojjc?MKusfojOuR-*QM;X;PU9nkdOtNqmY!HS*wKZRn0DK=j3(X8KIQPNsg7F
zE?GRjs;a&oom7b*(s7XqM=NbOzmv?LA<yU^e=CHZ=cS6~3|t+Wu<ws<LmF1s`JHqH
z;kBj-aT*&^@f>+<<3~KwPDhTVE!5>zCJo$b9X4#RMLVghdyZ?(4#uUV{dwZH`eVl2
z%WW9?vzcNqNBc<R&f_!UwBv#zD1o&5LX`cJ3?2evIy$P4-SOCG;WCj(NpBIcT{>#W
zyBl`rfs9E?CIJWoY`xf#?`D%KkC&cb&*A_%3v^rbt>;_~orq6Kws^+$=>V?zxSS_A
zjK^<Yy%n)>w%0XEj5{~+KTe!Ani0oj_@5@~IyA1jU+e~aSY0g5IFD*Z8P&vxx35r_
zeS#QEER>kny}FZ;g$Vv;pesBneNUv78otw5Z)N->NePZ7w5ro4@DOlj>JfnE4cARC
zj@lIsE03wDd^*Aq)9iK&3XrM!eWUYMa?nEU84_Vq98(5=5nbhILu|lrENpJo=!In&
z8qI_Sk!UbV3uxO@;ZyqAJ3VShBBp1wx6Q{`Op#J!vm?Xsct?BLf_q1%oWB{;@I2`3
zq?WHlyPGX#@>tl~@d*kBM@P4!T!%O#4%G=hX|gZ(tZ4G3ag!=tKJQKV!7NFac4>8W
z{gSn3vN`>V1VSpeKHDl_1AA&qo#N__URW#9_Pta!^H!BzLQ+ewMG->&+Uk{dvJV(F
z>asWpEAtgn@!0Z*olO_zCwJt=8<dJUAGf%1oTI=N`58KFk?#5LdjE}Ubf-Z9sP6L}
zI4?@!d>&_VR)lfin!J}5DjOwzW*%@D_z>g25*UE3zh!!bf@e9_RkTgpQ$Y;DuNjd}
z_1o3g%>s6#m3pRBvOcSlh_#@gh$mH_Lt0{Fx|(x(cgyFO+tequh@To1ltcywKVG|k
zAgiQFXG<P$=OG<qmqvKVtSaWPo-0PIq3Hi6#vEGM*@pKMZi}w;76_-PsaAi{;!xYt
z=5ssnT#Bg<YZE484e?fczx$WlY;Hp~Ti?NKY(dyl+5Ynk7q~bTT|cW@Ns66yzJqPo
zvaO5=hvdcGZ?5O#5XdjM#I;T=wQ+?#E*A{4hQ-O0LRT@&Hr3Ad^Bn$~2K2*+KIx)+
z>p}d*vvZ^S1#=e>u!LuuP+uftMw-Zrm98@X9T*}2lbvzl=0+=ZnC{`waB^g4j0^EN
zp9nq2&PY>SX&8?o*&SD|G?4=0nRRi5NHdGEdeT&%<LrW9pWD!P)EQGek5r-v4Zn~i
z%jL}`taZv)5TYxIY2sbjib-cb>NcA%Z2P&t8~V94!^NR9R`Y}Gz<i-!0i;;0)Cvqa
z(<EHhx9-W`R8JFOF)*2%Y|1)qY3epS7w$tw<_Z9PPJcShiD^pN)KpYtOxS1sI~oiV
z(_`RvCZxq;RIK!Mi#=y$v~c6^cfC#;n!z4lo`gC-H4)^<!iqxcnoJ3YPH4|YQJF!x
zjlq{@oFJ4l@uT_-?gXi0Kj*p9T{4xe<ue{4$LFPpk_@;A+<UsXIg3W|PuqCrq?8n-
zn88;KcBfJEei>eKKDtI;?$`GgyGB(Bia&Q-@CypYX7uN|*5zypjqvD8pkUcJzlBQN
zazPq-mK+0S`ZxXp$*~)YL7FIvOsV}fy6s}4^H@u|6&o^i><L!LQRT-Yg6@R;#Zo}f
z?T*3k(XqsXU`o2Rq^aI00$ue3s@c&zSHY9aux_oX5ed%&PsHp@qXH2*s=sM8!(}y&
z*x%loS1z^NwI3$ty6739<ss($*Na6Ob(@5Kzi#p5A<kXN2O0b2<*?jUIfkSnXz@-z
zU)w{~^AXF<4H?}#Q-o8c+THZjqaz4bIGS8qORL^u2AiAXa1ZjAM4u~h<jfovi`2ce
z2cZbf6yt-6+?<}K{c_^|y%TkYB;OvM^Ed3V#uc{POD5-A$f=Wc=y_|u?=gR9hW8fI
zr}-@M;-Cqb{OTW77l#+;%L@LuH8ol(3bNV@I_bk}ySODK?UQg1De>`6r0a&h{_a_3
z0H!10B7INka5&)5gz;T?nOWBmHeqbT?aQr<geXF_t?Tz@jd=7to_X4d4$Syr%YL~M
z@lmBw+4K3rnk>+;?@q_X{s-6TvajK)BKmrS9Eo;yeIjYuSMf)O&6YPd+v=y!ht+t*
zo*c_$zA!pC4#X|^xwxNq4HMB46s0yn+t*uKmNkgAO8t+35NKav*AtOeq0m$BEM!_^
zU*JyZs%6jA7?g%*`LtfF(1UP}!|-1$;32KmaExUi$x>888})e;JnTdZo_g>TxCxH0
zhN|6WNV_b=&gLkoX_Zp3bPrx@@x^mSMiHYAdmE-&-TH9^mkVTW1BNXi;bx?V5U1W)
zwSU|Cz<@<((oUpil8Wc&b{VsIPmg?EGx!TA^qBs(bf|12Yk0eiBE^z<_AqW-0s(zP
z`W*rx`}zyUHHEDg&qARN=*~PEA1X|ZIUJAWN!^#y44-cwn68#c=}q%?_Frv|y??uG
zrfywdx0ERQHBsjmUhyvNLg(iO1=<q0R5mU6b?!o?96nq_cR>IPD|=pFJ|_%0CYgbI
zbsa+fvqQMSFFiD0LY+ZFYi^*)47Fr}C3nB}4*ziyoKvr+No>zH$MCs|T=%ayegN5U
zLs8P<-QOlVR;?Gm#-B#gO_N_SJnBH1k6ybj60ov(y#Ck4P}L?$L0IY&ApwCAp9)R(
zG)exekokkRSFU!B56o*}e39$J>T(ddXme)n;)V3s1-=vz(Hg?J|C-N_QwB%~&>Uod
z-8BaZ4<Lq^f1L<?Jv#dT@e3~O#A#GR9}m~gYx@PR{t}vcM?Q9TO`){3$-TXBy9{R6
zCx{3QbJFve>C<gIK$|g4KQOXJ%%Kx*y}QA2uLw||5>wp-c#6tkN8M8<Ns1~BiqmeW
z?YX+l`!i>&HM;EaX(ksN3lF2x8W)S^PWa8*S95yU;}2TGmel=MDosxJPOY3n2QQbc
zDBqn7MhMwErTpt%7I7*pnhSR9Nh-l}XBximn@v_+*x2LQS6sBYL(8)8Ab(Bw@jDfd
zH*6<CeYXclqNew+N$(#gp64{z^Y_|2+BL5VLSY!X^Ecaq!klvr4&5#LE5v8dYa5PO
z14>{04nPM5+`DpDILw|qS}j!O#qGeauOiu(a$Hh3Ix1r_UB1cWKDXdEgK2WUymN93
z@@_oYYF^Q@;$$I{_nu3~a_?u+Lfy`gkfDj*t(v216C9L72+Eb%ZGvsdkZ`@2F@vi@
z{ZIR#Cr$RM+ogCrxUCG_>~hRDb<Nq{?#1Zo9PS#3UUCg?z6%Fl?y4=v(n+_XRLFDi
z6|bcINhz~G6_%{Vy1CI~o~=<wa|Lo&7DYfq&tYGS92?a&5=NI)RZS$rtjErgH36c&
zM%8Ah=987V(wmX>{#faAxW|kRH(4UI!NsK<JN8Wa@HF6L!Nl7mpL&?<TFbMT-xeeV
z+FouVFecLQ70o9}MFnx)@%u8@!Bg$!cZySL&rFYPYh=x9sA_U|Mpf7g*a<hUoSLAs
zrK>FZNEJM!^wM0{_d^4=qNKhr&6Y{*sRszxjYpmRJZ(PK-Q66oG7qtY)KbJ$xv%W+
zcaK}U-7b<_DKCE<`+Q{NWrsWn>0eu>TWPRGM0spaRbi%xQ~i<Bv+jFgp>1-ArkNbQ
zfU~OAjm@3o8tL<&CdVGl`y0Dk#0Qy}hD|%V^UW1%p=MOSlz=GeUl*Xa2jcXT+0L%#
zq&#1Q)`&=^lkHRRS5N`xE(c0lb?e(!L2PU3gg;KO%*(v`Eu8fOVbKHplbvfmiALpY
z(Mm6^9GlQ^N#a>d5~k5(G+tMo+pB*r;481#0n7t;MgUqjW9FOaK0aO%<a<^pu^-3p
zI!<~I%#|4lVvVGc=`sH$kH!+axt*g31KRUM^~ghvyz2voXUEudbzgLg`5gDB$gvvk
zLTz@B^MPicrRD(j0+Dm1G`1{{=WKB9EI8w2&x%MIJ^quGHr<gD!X2l?kff5=ot-%I
z<w5+SXI6E!rixs-7>*0lvcg&J*i(JJ6KNgkc-lla0etgJyZ1<U#LN$5LZakBU4WFc
zbpU$Ia#I*ui_F1XWHTywJ{7Ft>SuA)U{Fav+5INRaPLZGLU9pClwoeRhIW=*VRf~H
zEiaLXmgUDiVbL;|jf}3aZX15~a7UPXzm+uEm6m7U_X(jHYqT`+VSe!$e%YS$gQ2Y}
zhX!pvzdsIdUHN6m5X(i*J%<WoYMq1a%P_<yi5T7hF$Od}FuP`HFW11)#Ba1pYgT`F
z!0BxM{MI`WWsAy{%%7s$m^hUjO{B_~$E2M-Iht-yEjKsu+g!z;JD~SJt#xL3-L_%W
zn|lP-#9ytzU*w;w%_}R)ZmM(dHV8fSDN-nd+||vri|eT@qt2B2QC;?XWF&G8wP4GV
z$nh!i(4Ce;CE&d>U%X-6c5+~8<oQnN3x>%t=*D!TYe@a823u9&$+&K?)P;1wRuf`F
ziR4gx`-dFykIk3>o0j6s1wDJ3PkI=nRy#*CUN7%`ZnY(vtHjSJ4LD1&{G0mvWM#(U
z)5H8u4R$cn&d!bveX`(|dtBNibMGzqU;{qc0O9+YwyUQNsbxx=^fJ@QW)tMHBX-Y*
zL7(x(7u(nq@hjlr$z!nxL9!0i!q392O_Sei6li~33Qi8mZC&?>lzhHc(YMW^m84Sl
zYD?1lo4|RR^Iyr6la*CfW+myo&7U(I7wnCUluth@F|#Lr%ySSzyloFL7x$3MBQmm?
z`+**Zvu3*%#*w(%NCK<!D&`&}l`E+*t{+z_rKL6X!);>!8hDJ6oKp=|IeuQXoO89z
zhFtL<JBhdOUovQE@vm%z$+^_l<e3dF4qI{SRr-G|s`TkEJsU7xe~>pPAS5!-2<->f
zFN?G&*P!<Pvv7p*pzGn@KF+73Q=S#UwTjAl&8B5QuDWG3BqlaM-q-p|n0^7u4Ec+|
zbMR)%gZo_;Ic__WB4j0of}RcaUoys_48I~R7`*J)BAuRp(;CgcSJ65jwp7xO{=mP>
ztU-y~?HL(m9`4`K_|p9bEM$TzpNI%7HaFBvnw&Pim6!(wjh<+6r<N3?J?6*@xmrMU
zi_hjqb6IH}v&x8&5HSWVS9!PT_JRS}N&bD_3tWQs8)2Arj@Zq$%3+eAnB0oGKd4ar
zLFF}9wN#M?zG2*_BlK7mr?+Exf3tgG=ziKY`CLO0i4V&oc&0??^kO?(B_=JT{hN?M
z^*qlH5D2H|RXm7Req48##YSp4npSeU*7LboO1Ro~aWoyRak=H@L7zcq2wr%9WOTHh
zA?(N6`U0g8--u6EQ(cZehtg88oOahTi_oj#aS<^QPizcw`j;`ipsK2Qo9r-`M7gX2
zL$`KfF;v74?Na`Voh&7xI^qzcP|3fq`nb=Q6Tp(jhBqm1nBIwZ5sg-oU!w{!m&n)^
z_5S97%UwG42t_X89kC22h53o9MeI<rw+*4GeIjW}J0g(}P{Eqc5=q`i>O);^p~;D5
ziY&un78O2o>BEWOHf?O}@b_~tzcX#fOSQ3LQCw5Cq9X~wN9W(Mv-sMa<M#~lX)W6?
zUE4*-JQ{d2StKHmFG_WBidO7{$D-sk$j#@uF~F~-+}M1$BdXUM#e6?Z#lfg8s~ueu
z?j7||6gOSo-yG`FS!yNQhNNedmWY$C3hJN~OZUQVC24U>3{8=64{9F-1qJ6W@OP|!
zdCHK)PL2=QH~8r-S6Uvh$W!#ek9a#WV_ENHXP5No3OG(nh*t9Q(NsJ;rsARib60hn
z!#j#5y-lpZg4yKB9Xv=&E2|TPH~81D<IMQ(Vuf)6`fR)19Se5ARBS8ES@f*?F(0}0
zIKF45K7%by%=e8Dd!D?8YA>%GJLok8^g6=czHh-|K$+2Yg^J!bPC0u}Mo@@%s{C0|
z%!Hxk*)$#!0{MPdB>WC!_%T_wHoKB>X#iU*i8>Q&6F|;?1%f7ibem^)B`2>}#1$8C
ztpRq!V<5-&bRJ@=ANII#83nu)STB>ygp21QxYcrcaJ{kJ1?4g%NENpUMGHO+=6mrp
zsaGL)S;4qld%?DxZE?Ui5oNw;!xBTHP6>JUN_4I=pJ^CrscWy_@McEQWOqO4G(?S7
z+Fj=<gqw{7daQ-CF!J-V=Va%pMKv2!bZJ)rlOROJ)j%?R6(lLvNJYjBeU=gur=t~_
zx^rBdC7Snh!4M8jKR#$adP|cw{B~?^FUF5Jfd8r~JqM|B+Y<d1xfM6BhR?O{UEVTB
zE551FV9=nVA_y3{H2>D;flDyq26tpK2N*`%4ZB4_tgyD!$&TEYQ>Bgjs&n<5DHvMs
z#RWEmH(ESk75J7D4Q_flnzSO$XI*8!M|O1n7gGT^Ou%l5hdhMSexWbG(w;L~iP=>!
z%z}?SkyU>EmI><-@`LW~t>@;81hrvWYd;ACVzOF2bF{UAV%VZxdZ0PF+D>N1b1OW9
z5^$>@uA5ZiupFh$E60J2^|ZA$uKn;t-~Q(9-JSK_4H2Jqo&W%TtyD>$xVFoj7tx)C
z-+EV@^nog8&?V<SvlhMU`^UUb9G~&&*nBk%Q_4|N<Zs{Kdx-#~u<O07P8PPdHPh$a
zOL!PA{qi?`c4b_jB4%+l0TVu3zsJOlD;IJNGU_gN8j1bPPdRpB7v^;A{X4v?+G4nC
z%{W$vO`$FDkTOnD(gdz!hJG`bzH}9#DzWe4E*$`1oA#~z>%jCo#rB=jo~&XwO%A%|
zPOETHzMG#c86d`gk!XC?j8s|)lNA2Aq+wqG(nX0OC#lbv<AV31XJSoG3?0l}J&jV}
zt1-yK`L3nV3}1_`WOuW`AayBC#PksCHJVfS)zrwrXfv+oV*jE6If-bj6Jvc4ae;G{
zK405Co88>?R#uhO`r^7C7D{(^C`~4>(0q&tXjrKh&ojJ?ZE7X@tcW8G{bcL3*~t$2
zrvp54d=)xN^LpA}AKxkl;YL{4<2xn_*wc!ts><p47yV(8M&c|woQZ9ScwOVhg^tAY
zpEblfP>1^0vd5E%iNT>J-+51~97DC-AuArxt-@ulXud)qqveT|kj_k+$G2t=x9<UH
zL16)IqiTRDgXy37f+?meEIT<{so=$jRl5sD;`0;nW{-o7(Xxik)E>|PB(da#CTqyg
z6v_~<WLY6d7-3g4_dVaQebUbH3x%4rJ$F*Cg=?2K4EP}PBLy#47uMmd)QOx9`Y=uv
zs6Vo2t&sq<;*|8IpOyw^)cNt`>_~S8Jx(sA#hoZS;tAf(j;M?0QeREFgv)ncA=nNq
zMV(euKuCb14`DTnnf1VpDzyEApYG10TO?7&e;yqT)0o4=*xbw$#3=AMJld$|u)o*N
zy*9VYCNI`y72Zk+d1?7=E+#ghPn-AEFL;5S{fVDn=inuj6wX5QRSY%vTrCk4%`DI?
zP?7$B@b6X|sc8Sj0{-Lc_0zNe>}tb{q#O6ZZO+9MlsFhQy*^MiKkeW!Igq?~+b=u!
z0?Z@e1o!$9X%u)LqB4wKw<8RUT{;gUbh!<hz3e@CV@uc)KSuc;X@NNY^6k7M?*`GO
z(|S2Hv?oST_Xl)bVj3}31;r=^{K-V_wThLsXt*y9oI8bq(;>!8D4IV^LDPl1fa?bW
zF<?>t@7Mo*1pnuZ0%e630rq$$K3x(^{;uRnZ3jPClT>`)Gl)|dJLy6D!otvRCsAoC
z(mN}@QqhWXkh>&T@l?1f-Spn>4=sAqOAm<i4H$^Pq@@SQjZZFrb?2cpVkE}Swoj;P
zgwr5e#j3+6GKy|D67q=XItcNY(@Kq8+f6$&v!kS6uq85rb@_dyv`ZF;VWBQbm&ImC
z3E`%2<U@(ik4YIJug0$vd8S)zX7y&ZKO~+rp`iKzndc*859r^?3lWR@G3PXO9JaL5
zG<yp|#vAmh)nj?g;Wv2)(F{t|{Tih3P7p4%>1aZx{IgL#_tkedROa7Vt&ElKPSjLd
zAxQ2)_Iz10yc%}r)2Amn7$C0z<n`sVy^(-hmTUgfi|Y^-%f0oV3$Zg@31gsrrod}i
zk7K(yjbG0ZLcUCNS<&`$+Jp}!fkU+5Q1a-eShJtWbx5l6S{r7xSdaWlODm(3Q=Kx8
z4YkPI-}zY(Uh3eV=b5F9NM>blYo^zUxb5PVnCpL(Kri68AYanb8`Z56e>{VHZ@EQd
zI2Kcv>_TsH`Gid0vgc^liKPDqdoNxoUjA&MePaAC&{uE!s{klNN;t%n{+>u}F|&){
zNg#L@U&3XMJ-_C%TzwZTH$PvIP*}t>9<(INwar0ZW(=;YZW#|d<nDeC!pVfZ#chtn
zV$V3QDpXfHPW6}!BSxL)2l3iQK}0`YVSf_o)1*!DFzhu$l3LlMw`yA!vzd4P+OOz`
zQSr(-{0RjG(0m(vF|Xslu0!~{i4Su(sqTPwA01ux+r6q3d?re+oI7+f7>!MMHd^Ga
z%GEAIpQQARr&#HMU{zHfABu9sq3<Ok7_R~I^R$&YUahPN3%dnb<v2sDPzGIlccX)r
z#>ufjCHK|uJpPGfY==voKsueWm1}IK*+fVmxF^24$tHL<Fha&@N$}C)>57sjOXvLC
zj6paMJ5%mRing7tR<9J5!dPPaA_xhO=yo^8tCs4vm&Y8N%RyMiX+rVvwuhg^R@dNu
zs~bi<XU{r?^{wd1;_>*aT5q?tSc6?p^x#%3*n5>%ebBuP63TbX85hQsn6=}=zPh40
zOqx#(Oz0l26YGK`oPncHd#nl0w@y2C6P3K<Tw1@gTK+Q--q`;hc|>SnOO;aS)7ks|
z;kzE4(#-PeOtv$!2*^9+ZE%xFm0ZozPlxC+9(|hGWe_O}a2b)k2}wyPof?4oj)F%H
zQes8bj!+OIH?R_;rV!9OyQ3H>w*Y?&kp`a(36gC$RGSdS7qw~j2AE^CaD&BHfJfd&
zAsm~{+`eD5m=g>B;5M#9Z!oG$YeWzY&+Ntlwg4%9u<gt(na2PS3r)fqJuIp=CQ<53
z$J<qAiYcmgAU43qf4?T;lvQsz@o~d1Sp1G|Td$WynW!Y3vicgYw1H!zD=vbk;GEA3
zJ6lHM3%q7>gC?8JBi-gq;H2~iVWjut`{hyhg@)#4M27+vI!le4%s^hLv=JbrEXk|>
z{TDy4wJ^8PvpYEg$3~Nz@F>;VT2FhfLgZVhlVC4_Fqd&vwa-O5zy$#Wx;NIC<7ep}
zU%s$luWHn`m=k8<0<x{sVyLs%^mMaBp<xTNu_w`)z}0j22QHy!9mr=NdU$*~#00Ou
zNRytysj<bw<329s_1^|}!aLYt?}cbGGM5da&n8G0k*fO(x;D64eYD}0FA8ANRZPR`
zp@`KuQH#WgfPgXjBf{^TXAV;*ebH7HupG1$T#iiG8pj=ypC3fYs7AuuM$3GStUCws
zcm9^}1kU$(&^0($d{>-O&QFq=o-rsuNjl$3R=M?IM+ziGh9<U>L4pl6{h2KG;li&>
zzb*@x!H=T=s(mjuQ0HTX&PA>Ya~fB;ZHIv91i-n!uwioU;tR1YId-LwS35rj%XsEU
zQBvjB&#{4gw=Mh_&My`((JJ2>#1^6cMA0xnw==n@v}bfQv1bJUH71Di6Ul#H9dUe^
zOq#8=kpRGt^4H{Qwbu{=LPj7V-+FfT`?qYy$uYsHp-P<vUs~Ncdalu;5B35Em<|22
zp-uP5d`>P<@PT0H`A$u!31SXAqL3$^%5*)k+MQaaLCR~{6pTPO7FSH@xr?to=eK3*
z*<(o%GMF>AU7lO0u*L<j|7o9sSDdNr^R9k-5U09(BJ<NSMEP+nA+sWaa?cnJ|6X+U
z`RhG-1(@7Y6A#r8ex~ZRAd)GqJx?GtsD9|bQBJv9R)3Vc<L478g_ARLvlv$1{WASK
zIxl0~Wiw58_PpC^SF)2xz3FxOf`7jd-#}v5N=23X=y22fuoqS!ZyfUWZn}npISOP*
zk~X#30h0$LJ%h=|79yUy+1f|`Gt84}0$^Qhn(->?XYBYFCb<T{Xsv|a%z&NZmz{)N
zK)+*_2h-H00P>!*ANB@Y;c+&OqdOe{aqi+vJE%7bGmG*FkengQH9SbD@ts?rZ&|xo
zYz{S%qE`tOH4nOGa@-^By{&$}m2Gm|43Mw16AeNPdiG+!*=M-_?7-@Ly}4oQq4aF+
zx01Ernd1KQtWEps0pu*zv-`;dJWb~T=elu<v-{A1vz`Ey6>jF?lnE}ROY->5#eBa`
z5``;vlGk~?p!5Dch@ma8!8I0QFCPYG+3l8Y@TSJUe$q=ovcOmi09#_r(R+x-@W3lk
zw6|C<)W(ETik*|}U`4Y|lbiK^KP{0E`fM*l3$NiphrAutCFP)CO>OYLakJW|zLP@|
zD~WH&9S^025`Rz088E{$S?R*m2sb9?Mm1)f&FAGXS@A_}c<&ax1bOU;Gw{?(M-k57
z{D#L|oErdk-Ie6(V>~Pk4|{4**&jKiKRhBq`671;j%?+#E32bFOx&pbR-kg3=DF7t
z)<1nQI-r#mc25Or>uBJ=w-4=SD~2R~%WFQ5x1z1J>KjEs0qLQqbo_9X_}ptf4@9sH
zXz6nu_rN`TTbO&EflGTrkqrEUn)@iFP6qtfUFDU7U$ujIA@X<X8q5Y`>>V8PsR!i{
z{=PjWBuPGl-7gn}t@5eOy!U?X+s=Q%1xXtmOV&G{5~@1%w7T&niS7Mrqr!tEQUqRu
zZ;xDgNOFlgE4ss%X=xT>VS6mTV1*>yomIGr74z8j<rdHun!_I0t2(@L7U-Q57p+*;
zMsdW0fU}ij6^!iQ#epgh4_AXzfRnUxUF#IrHLk+}vVn)d6RGxrFxk^K%Z}4Deb1U^
z?8au{6s3gM>x=BULb&wVh&eD2b1qXHG6vwU60t=|hRhN%-<6nSZ==+wh78jYhf%0s
znb)Wty=?%S#Z$_Jf)YM9mS%UFC;4~2CN4KkX!nyYGOXau)x?6&^fJWTU}>B3KdB+<
z`m9PqA9B6~#VvB`q<MGYpZ72`t^TqxD5;(qc*HjvL}s=B`HlJZ(dH&O*92-_xb=_}
zF;{W4u~{@q4dJG|ikCVy!D=SyJ;_Zv15m&oN_>Eir?_AOk*lGp8eCNUMt*OJ*P_px
zX671%Ro;`Y07E-w?4$Ln@zrm2kLKaqbfi0ed*_vF<RI;ddz3peH}i7FeI+$20CqAg
z2`|qK%-cC{O|3?yDFD^3^5F!w2=a8;DJqYLw~hZQHwVD@lBW{rd{zsr7nxL3P>gNy
zE?$5bSA$xg+!nsHTd;&NLkFBi19zfQta##$VJ@%3q&yi;&kZ{hKv*#s^NKT3B+j#1
zoS@#>WYg^izDFzAnUqrFzBNIarnJ#zQ2`8-$=V>`H1wW*hWqbXDKcrfbA=yCACwG4
zwvF<ZA5BuX^(xgpxYCltFj`?zfO_C$lV1Q;VIInpx+V_7<gj0;($xg6-HA#@{d~=&
zEfBktvbV_%=4;z-P?MFs8U;(BCn>d&MS;p2;QmB}Cjyu%TB*HGKk!vI&}9igQ&%^h
zjT$%xSe}OT5&Nw!U1No1hwZ`Ea-gSyXvCaLJGv%S<VS$Z-r$SBN^5skFIiWzn~NKR
zURvA}bsh+`haV<{8rrx4N31A>g8YAJDQ(PQd`+_pSX*xuWSL`zwWPjPYZWjQR{+!q
z*aP+2dXURfz<Oh0kq!Z))Iu`{70g8le;gwnCwX{$SlcUklk*_yazL~h3=C9JRXq-t
z$iuskh*x?gBDcL!#rvdOdLH#QIHmGgN-4X@XPfwcu>d#sUYqzy(jxMM3?s;Et}`>G
z;;D)fZ%@`=M#o>cQ+oT@oCJ(r+tT~}IrUo-iuL9|?qQ?g<(+Isz}-Pgz7>HTla=UG
z?;HY1P3`s77Rtgl4F})0DLlG>;}cZYhV%RQT@`J$6b(JM;S&6_es0J<={c{c+zqlH
zB%w#a%7=e%in{P#g+M+;SzI!e@45nn6MXsnZ}x?}%prp$LAa2i9-=~IcqFEGb@hj1
z-Df(wb!w!fv&$|#UlT-VaFFePS8MyK{LRFuu%J6_H^Jc>SXA!EC0G5%IQS>TSg>->
zW>engK9ta%2Ap3F&Yus~X|}giMP=EWyOtI(8);D+b$m3>J_&4UHNAKh(C>s86fLQ@
zMq_h05S%_6nbu7*cb^j;A>=g7)jhoXI(94yG3$Z1AdAoE0pKDMrtN(~SQBxCi32(<
zc$j58Z{=X$AD_Qf*0~9#sN@YN*}LrrLlqffl}E=`lgR~3jOR}F{NfLaiAZe>%X1yt
zC#&0hvhgh@q8r0Tsqf@0I;}<Dg1lC|Z2Xa6ctQwlaDNYHF4>tK%qkZF2o>7c8-DKE
zY@}^D5<-R`^(BkjG{z-FhVDGvlzf8H53?xT-bk5*o6kkC1sn4DZz~_YeHg(W4=%U^
z<kjAh%j8pYZ3=B)3`z6!!lH|y`B1&XtB8nUkXx{pm_yIca8Z{Q+ZgeoTDdlbg=xeo
zjIN_QiGCC}^Id&MabE=TF1*y+LJ7o-3iz72xk9?S($N&g_DGetPP@Y#jxa_g_#s0{
zle>*$!(F56f=j_6&y*P;ALs+GL2B0v6>{b9wHScOzRN{X;D%iujtbcwC+M+A(dRQ~
z9DMef^5JdjD9EFb%lEWcXi{xk-0WdSn{*#!qFC?aZ<1<w+1K*&X(OtAVK-tXrVaaV
zi7T5`cG;_5hdi<Ptnq3+reI{KiduhC7yN>dW_JTAGK6?igSvIKq1HCppoe^I=J-UJ
zNh`^aTi^74m>f%dp#TpRa_0l&-NZc+)2DVu<r^Ei4cxkOB0>V6=^h%nqTQ(-Vd&$Z
ze&RbPnr4T-9%_z`c62+NT-@JD1g<8ggHd$xQ*!X{IHkO-8#cZckEdMBI$B>f;IK*s
zBb7`0w;<d$SMfLv!Q$(PE#2Lg`i?=W`&;l?{opon2eFt(k3rMLd6ZwiA^Wqn1ppI^
z+8<?JobJCiUV?CE8EPr}e-+mM98-Yu<N9%wOii@w*<i>iPp<83QS027yWUXZIZ@>3
z+Yb#63-!k!#CDp+uf9`Gd?I2R2<Fd}iMuZ5r(cxc0)O6a@!*v6a!SUrbP^B<tZCpB
zlP31Z(gCMPxcTIC2p@{EpVy2jE#T^VZB=ebT|Ip;<}p(BL!Mj>Rk1QL38N(YGMuC}
zRF{lsKw0_kd0ecCUmQZ4F}eXY=OePXos0|gWJs=_qgk73jS!bZMqdob#2+_3TeCVT
z@zB|ncN*rwA&wGf?*Ut)JpT^=O^-tvaC$ki@V`0CVC@}n!zQPT6T+k&@*aMu&7vBI
zGPyNNx33ol7iWX^4kaB|IIn{Y)!Xg4O6&IIN~luqaJWus<f=avg4Ce&4zn=quURZz
z0RP#|^Li63lK3n@`e1n`gKj4U<;YeOa1kX`)5q?V+H6@f?LW-Zj5!n)zUbcNY+PUl
zUS`&HqFUZk--)8jTmj%n2Zyc8SQ}0Yjrj02#H1gL&6<bC7Py&jF0P-c2t}sMo*lXA
zEJ2I~!nE0Ai;&|ux8F3e{D3P4+aN8gU#)_|c1mjmxQ(gEZt?RAR$X#1#}b?0pp;Fd
z>O49G%W$P2Z8Pz9&92P5eUqAutALxVbWE_O7=+%u8dD=QX&HME9mg5}{yCgGdINsi
zB<3{?K$lE9TsHC9@x`%;S>Q(MT|WOqzW@|Tz}e55hBaY+K@wtdi9+7I?T-=AW6W;S
zmsd4UU|(c@*RDuk>?nGykq4al;1O@riPTD~yf5Ox^+}J2fJ8kA<geKKO%&-s>vP2(
zvQ!&?=!h;T>5C#z_ptM~SRUbXAN0bH$Tr8oJDw?n;QJYbC#Jn<44@L6@8^8N<OB_v
zv<hAt)a=$`dZGgMO|W8-A#*-UdC9vSDNyl)LlX5lR8DrkMAZ)9s}_X@<7a1!HyyRd
zDi8;MxV!p3xNQ`8P}icQC|Fu|Ve4m{AY;DgiHH+M(~2Mb%m`Rx%s4$Hgq{hHiemf@
zgXqqPrT2xUPqUNk9nev&AnC!I2LkQ>^NC$`6`I-)*`?KvGqf@t1JSZ30sZO`X`V+<
z03XYJeSN`6Yjd>(ylWQ%zB_9i4K9Rq)U*@($HOKU-OHoA8jWJmg`B-1L0uIOyQRgj
zepb9(uL4Qd6lkL>a1k#<C!CR*{H+FSGA@(Rax1GZ>$_sro@f~GfxA~+YLkmfsHv$`
za)t*B+O%SjD#JsTm$a`9eE<M-aUIf%(=>(14b`suVjNS{7(~%*x`jTj%L*Yb{SnE|
z?d~-Viwbk2O=iksv7(2|ZG-rwYe-gF-(4Qkn|Nv&NxP!X7d(xpxhDUuy|e#kdjJ3U
zyW@0Hj+}C$&ZeDI6lJ<#uGfiBkz7SCLq(zuX~Z^8N)nPJ*C&O94dr6Q92W`MOu4=o
zEyi3dhMBQ_Uh8}N{_y>N|AcQp?Y8Z`_r+`P_v`(7Js$VR^DV$6QxG#!kW6;{2KJRt
zhmkV6tZ(rxIHQzfCwpII3?z8HJKx7ECY$lJLcWBMNCZZkmZ6zkCVslDxc8x~T=IJv
zh9I>F)^cn1K5z?wR~>pWZ2EzHccGMOe02Rbdo`t+tdT&Wy6uz&x70YZMs>j~#NACT
z9=$k~U`Z|I!Lxjvz-YL#0tqf~(5Eq%3#q($zGwk3Yr{)(?)TlWwN~f=Ch<1^32Iy@
zoD*81cYrJY0}xBx+L9LlvC}VD%hYP<HnuWy(#Y&RC>5rkkfjrdomL_P|HymjZ8$4g
zUE7ty{#Tg8ljnRi8D1Gs?3NvE-tpiB(SeOZ&&ze6b+rvrONvpUMRwH*Bf}7)6ykvR
z!=3K^#=|@3re)?)7T(jG=`?ykTXJA&$TEf@*flq;yYlsgq$9XMCe<uYa7O>|K6|Ch
zTA6{z;&N?nxYltN*Np&!5wxV}*J%rl-drAy;FST9FF!;4aUEyIRt-NRSWy&@ucClS
z#}$sbGFP04IB&w`DiY;N|7yoHnVM@;2O+FUePtbWu=<mo)t>ekc4=!Nm=FOWv$qz*
zZ`~W+>xw$kX6kYCZJ2nD6A&t_TdxO$RZl@)ajTu$=dZ7bdA6xh?g4<1bFK>=G-tNn
zNyz3tSI%Cmb*J*82@7F_soL15<So=B@sbs>lKna0h__DY%B7G;==I11+#EA(;aen-
z()QV<b1eB{7IS2E8L>6_rB`n}a;;ma3?6O{?sQ{naf-WF7h5j)QG6TYDleEphf~^t
z>qHf_ia!C$rJEdrS4-AiSY$E6@w1Iw^g8EW`VCj{+ViF8u&_CCU$k-r&lV1|yb_dq
zl2E;I*>ExL6M0TF(KL^z0MWCciuJj_41|aLD6>1ju-*%>6=;JMVCx0FSJ=HigmzH9
z9lv{PN~-`k+1a`bB}=kiSBqb^Ibo(9v66J`s%R>qu3WE_m4&=}Hh5KDJnN7@)Bw(&
z%_%<GHd9}Yt9GRob~dRq;8`kA)06rQGQ*|bSzA)<RGgVZde}1k*A_E1M*v2xmehZ{
zrLdt;EK@G?p5dLPCs>;|0{ZmN*pUS(JSDFuQ9d)ssZdj|t7@gKXI%YFc`&7V75L8f
zZHgk-+XXti51UU_ua@q@olC79Mu@RXm`#w&z|ULnM|XvIj5hITse!;t-5zs!yg@b}
zrLCj6yf(kQLF0bIB_gTd3Mul1jfPUl;=hy1>T!zd$!9#rGVS-d4xZmR6RQ#BMW1!}
z2};q9l=7SzWijI+g?9{5l2(V}^ygys!6$L^rQp`*`u0)Ogw3HHX2RRb(50S?QyZbG
zD%0xt@iZr2#mZAMU45OGDDO({y)y3stoI*g2{?<&6O>2D++&PWziB(u5>5dg5=;QF
zj9{a1ccE;hnT$QbN7G630gDw|Iov7uuzu{&F{4ftAz)c=7r7WgJrVsLs+X|<Lr{(C
zGnAqE&f0d2%Rg}-M|L4Yv=51Vc_z23Y>MM0H*$<u@((~CV^dvjZhPn*)M%*seXMt<
z-KpS_)fHr$j0r^3><P=kF^^5V3k}O-Q%=dy&52CVaVyThRFn70obXK<`Bs)?sNcZ%
zowyseY&1;u^uM|7*CI!lHi6cBE|XvR+lKm+o{y|Gt^;?+R!WFF1-XQe;e~ZbF>e8O
zqtLmm=(yW~Uzf*)VP|E$dSm`^QIq8_|BnIqew!&1?UdIAh5NSmujb+1*S;2=n{qmc
zLyL+(4#fFK^T8;mmlNljV5FJ8KghDUd2HiN7dgn}r%fr8FO%m(VpOouJFH5)z2LU%
z;DfY@o;)p>Z<^C5t#ZbdA{}kL9wy9*?!#@(^3Hm;{@{*MbV7bts}>AY%aM1LR_(c=
zN5FE=vlIId!Hsqwh>JIYN*+lp6E!cd{ycyNEB2W4OR+IJXw`%ndddUA^&8hXIvEEa
zUNtqd2{LHPdqT5#sFv0tTjV&nG%59_2=*6=Qf_bv3zd|B)r@Spn|1~GLHF~Y$2UGd
zbI6HWPGCI#*rxtC2=4eg0|7(Kz~&4YJW2xnTC<Do^}62H3y`Cu#FqgcS?X!k$E{}o
zG<yPWuVxsATXgwQszdYe9C~!Q%;kgX_88z7{pxK!R;J*Vy5n4i&qb=%Pteu;;PsyQ
zB-PKdkis94ciLU&O>nFQ`~LS6(vVIH7_>H)?PyMF`7hV#{`;*;j)X=KG{9=iqK33@
zVSy7QlTg3GI>+%499<XEuC)!)tZjC1OXtp6?5x@nvGMe1#O86)NOkjBm;)&miYPc<
zT%AJ-KAlTN16vGy>%C*^ZXeeg1_2IXE5I)Y-`&QKb%I%$f?A|h-CiP=sGaE=#)duA
z-2&ND@}8EHL%dXyFQ6dD(XMUSv_N<6htU(lV5AbqpsNPsoon|1kPuJIbDewL`%C<q
zCr5_g4?~y6<aI_ZT5S$eF;=r*_FLlWK!io%moVOXEtoB?oxl`4N`OYUC$~)mS{8$i
zxCCu%Br*P53%FiUpp|@PA^}0?GSlxvfBpj8I;VLM%RGJgO|nH^#dF<oLNe*PG<i)K
zsxrA7?+)LkCM%Z`ZMLNrKYr3E@i!E7Up7+es?EXQb58Dg_gOvDz*^!a=G=gOLjqh4
z%<Da^z$N<Q<wq0zI15I9G{KK1_|YByf4L(dm0WeE{IoM$_uICb1m>jMfjM{q7zIWV
zzlXA7Cr<txZ=&pMo8H=O62qpS%Y58nn(PC{uRCGiwNL;)p44a7C$?P<T#}73@yxrs
z-8wH%C9{1zI{FNY1+ZaI{~_4TOTwXE=fLRJs4RH}8JTGN?^K?QuP6-r@@T)`Ed2T@
z<t>F^>%hqm2)%x>!c#C&?2+Tu`w8#bB3V{PjyH5?Z|b?;&nOe#<HAC#T;$i$ye4x?
zV=v{@E%NOsSKY2&{Vry2UBKC@G>cqd_DVMXvE9JfSla>C!Kr^zurJ4gRAC2ySoN_8
zuqHr!QQ!$i;`f3OhExJx|IEIMp<C?g>lnWq&ROQUzf|k<4c9uP!Ad54+#>fTnqN6;
zJ5o0G-Wjt-s#FS@d5*zz_L5h|a7%Fg1rPz__QzTlWtqD?OnNPut4To9#lNdS9&BKF
zq1P^_P2OEJ6i>$Q@idi<eHv9=Do(_7e@0bc`i3a%R8Y`BlM29J>?bg_YLk=muM$)M
zS1M6LIDsATG>Y7t*+DB2no=BHDhRg6-!wIuHmC|1cbB^=*Xw0=>Wr)upjYAmfUbPi
z!vL-D_<|+g7{Co<M|D97fCF1ne1Pq#mfN*5=_Bzof{rumkJSE~qzcL@ND4X}=b0W2
zl7VwqkX#tYu>b8#fAI@B0?P}rHK@leh-JxKssOnVNjU^1e)zRkPB3|Op2#fmY2~lK
zN9+a;8iw!%(QtGYrp;XI!F~0e&R*lNZ;kM~HN62^^k$aUd$o*m$I2j3j26v4;V;#S
z1^nCkTN4)fuAxG8>M|eE$L~bZ`p#K;eG&^5<p;$vXwfB*$wCO0#G2#y%piSRBl5lG
zvu=V$w0-Y@UdX%YAfhOG+-7Q~{L29lF%MeA0(o^zUx9Ql=IQbdj~xEwSfu<gqp9RY
zJHT9Z7=MAoz7#)k?1RryEn5W;@EG32Ck+J#gF~Otq4@yqMsDpBllT=yAPg#z<IiP2
zUmi!V(CF{DwFn`ZOBpZbN;_D=jlLyNmtu_#RU3K%J9C5Bl7OE81vnC@e6&AhmgeV=
ze-<=7NL-Pp^3=ubUc!yub@%kSy1K<kv>UPUtguG^7Eoo!{004kyI}AY7GjN*WVUsk
zjvzXh->?XEXAjZ(>FObkHB8<&D&flus)z^lI*jq~v%uoMYv8(=Zg(s9=}sH*GJEYn
z20TRdL=PaWrZLs!*QUxekF6nG%5LEu4-NeRN@CT!d<5uo(?eFQihPWhe)a&CSN!6R
z6mR51zv*h26?_0;37<MI?LJ8A>jS1Lz@a_?>EdaT+hA!JdspGx;=vN%>E-P88t+XT
zF1`)4XJ>g!Tx=d)JRmXyf4h2iF-<IDu5yzK!xvG6=X%yVVf_L06z@Ko-`sWWL0wj8
z?i&gSFPUYBs#)-HI8e(#u?~dQOn+HjHd^aw_<*e%sCs+YB!@F{0MJ&!(r~Gknrc3G
zipz1Vn`$d5k#7MeoTe&oGd%g#QR6Igm858#0bw0B;<R&DX6Rmqfn|~7!4#`(dqdu2
zfBalHhs9mD%BKrb(1OhFLDFzYyFUg`$KV%m#KU@reKY1BCTh_}BzqS>Sn%;$d%zQO
z1HKn;jjbnO*~LtVy(FzR?q?MJDr1`>?I~iHUclsu>4hEaH;JkCmDv`#kEd>e#Byd>
z_He<TM8Mo|j7lo&%0Xb!`k5QR_&Fc71~EGCSfycN5oVyr|JgX+l9Czw)}r(gVsh@a
zQ3WW!aFJC0EqE?852zYIt0Qft9mVFT8`StCi5>R1I&BALCo$a9JsFtEQMv$}Q3|_d
z3eH_kMc%-j7k2SB1*s{z71IT|(>>W<d)d!5_0~r7(V}7M3QYEJY~4CJ8+fnXf&`+#
zUEG1JMcFzFW0->O`L(`U@i!Dkn9P*r$r*?`p92X9^BNQWi9aM-N84!Z;0lD))Eg{v
zD4VWvv33sR4G?uJBECI4qcrniuU=THz@ObNp0;8xzM<M2OkS<l6G?P47qyP7#T!ZF
zX~(Lfp=!go=}FOYi@4w!;#X&2Gu)$f3qN~x|7Gf&LgwfOPIe}hhW`zY=3UkH=?cGT
z?%cCadcZ?+#?=|SDwy7DK{j0TyjTKCVhp;821vCvD!5ABMqor;a0~605Q$1oS9Sw4
z-#dw7+ftJOGKE~YiWKzmY_3fz!EKzvdZbPlvOg>T?*Jh{;#qf3R#a%{WuqP>pXme7
zS={H~oNcbM>D(<;WjWHV{MJpMe}ee5Z@#a9?ho*h&lF5=XDe$gTFrr}$pw%50M&V}
z8%4fIQ$0#?IqohW{KE5iYkT{7ZY$`cJCOL$o17*TpuBb)FkE-SoJ+@F10xy947sw<
zRw&eq|20bw<Pt$oei__Ket*DV+*Hx0)~+{3FB|1h4Q5v-YGsRKAKYyK5){BOrv_v_
z^wu=tKvoBQ(N$mHLe)g@>j+93{i0n?jJY+9&aa(pdT@(bWnixcIwRv@=_J=M+&G5=
zQ$$L9l$)F)z3<6xo;KZ3=kKnNl|Ko`oo)5=%Nx`@n(w!d)X$T?qwb?8pAko;fm{pX
z5TrVzL>+$CpUGzcLto_rPXId%X}k*EopZFn4vyG0iHytM>m0SQ!Snm7u}3m`cf;wg
z?cU$plvDs59LwCU7*N#4;#9t=y>yCAf#V;@D6xrTC5kO~rQ!KeQPvu91IAL|gOIUI
z?jDe20+lE9fTIbFcEkVk5)rEcJT4iJ12RTn0pV$rzwC@h!GJ^gu?`gCAq}3yl0k0z
z-PZfio|_OhU^95{av<g+{pX19irc8NdB*A{$n5~op0vq@(CANRKQ3L8&y<Q#jH>@P
zw^`-@6tZm}t@`mZj}0I+42)8UHhBCFW?xpj5{PFhrh|pr)ek};8}_S+)1S@Xf~s_Y
z)MMy|-cTQVC}1F^=}AiwRDV|mi@mm>yajTz5N((G_O~P_@GQOH+{?h#iyrcfC;9<U
zee*snHfDZxGo)}Y>OD9jHA#|IT4P7Qon^4{5dnj7EpN4IGxRJ0lnof4u@xJj)@L4i
y=R1?A`+tgvoe%@`KrHrC-lGDV;TK6WNI_{U5vl$=h5q0Z==7;`CZv;>{{9cbS^1v;

literal 0
HcmV?d00001

diff --git a/docs/frontend-architecture/evidence/notes/native-mobile.png b/docs/frontend-architecture/evidence/notes/native-mobile.png
new file mode 100644
index 0000000000000000000000000000000000000000..fdede2e843dd34d8fb0040b5aa4ce264600cd08a
GIT binary patch
literal 28151
zcma&Nbx>T<(>6GSBqR_ZK@&8%LvV)#cOBdkoWb282?2r!83?X3Ft|Gm?#|#A+}#J6
z<@bJ4yKjA4yZ_vp>Qi;@J#+hZKi$vMVQMO}*q9`k00016UQS8_06+@?0MM0QJ$tgu
z;H1j~0B-^EQeS{xX$MQM{m5qg8Ey(&Io$Y3uKj~Pem;5Ts6gO87{_LiXkk!$Aivht
zZ^hL+LYsV`;=y%$Frs2<<+;TzTj?A(szfGyN@wC?-k(@(K+UxL{PWu`e-r-|9ru~X
zrU*N}CQ|J0)&ShDW81$VU`t^sv)co*MJFl8Y?KNI@Ex1$>GI(>E#T`b>eqnxKjoeQ
zLO#X;zEl1GGhsRuh2`|20Z6?vwrdeBQg{;2{{?8xw%k!XV>h9t@&SAmO&t6qq7Km=
zz5oDTB)sF@eGU2i2CZ#cL6wTk8U6owGlGo+d$KBYK);Xbqp>Y**!8EEfTO^=O1U9!
z2VU(+TIX&wZw&Od=r#^wv@ij@DhxKO201*P2U0-WSq%;6`t`*Z!Akjx13OnZ>nn4T
zHjj$Z*6g8qbxV=WK6>e`U#3UiC7b?e|5_`iTT)Fnn{S%dc1AeD4dBI8VO_oyuL0ND
zO&W4T;zCV^GJH(h#4<&D8!}{Q2U2TXu=w@&WSO>m3p8<M1dDsP2W7RMug9O4yKV^N
zc-VI73)O12=jmoQ#&d+c6$O+Zv<EuRnbdDq${U{kUYIw1_2ET1H`~I;CSIXl4$rAn
zu9$k~xrYUox(SyqLax_e8P>XsmGo;z?>wkC1=bS1Abqd0Eqr5K?zOW3647Yo>lq`G
z11dpH63nt9r^&L54jA#&T9$L5*uTe7NlXnPf4@+pl?RzD;PhMF^V5m4xO8i3Q!nAr
zcQ0|q3rBYO_1+&dg#y0I+b%{p62gW1ZV=*iSWE0OsKEo_M&Z~lVcA8OU$OOe$F+SW
zCDgylpVf1mu%uo8MMkMY-g+{8KQfR1`_91gC)4!{I@9R7K2ph|SL9uIZCCD1EnrXa
zEpBdl?u?@ms9}4Tm8WBwP~?$uy`N&ZK3*H2r?6Jy;e(2YYX0G_-f7ngPEK<>E%SuT
z@)8*k27Z~Vl&@)BQz6Gl6y3AViEsyeJ@iUeV%I6!V6J)lrt2Q9{g{yEo6TbSR|RMs
zb(2dMOG4oUSA#aC^ZfHBEg+03vg_|}k!Rn1@$-jb&z+M+NTN=dA+=C3q6=C3>H4=|
zOtt6oQ*^r|b;9=i$;SC5rC1C0KW7HVyEv(cqFexgeMu&KMMQ{{%G-|d7se$Me0&(&
z(DldfKyigUyxu`J2qBD#KqkJjn#ay)Ln2#>V(FpS0r1^DM@}B9k?=E&#Cfk0lav1U
zs$5~v?v-S`RP4;ISCkOQXzk}0F$&rDXl*a$pKFS!sN?JDZ}5^NFaOyiQI)~ljMXn;
zXCq!@XD5q2^{OWY*wst5FpxzzEEUFa8AD<<<YiFVsKS9l>RM^NH((mTtO$WXrI(1Q
z5l{z6Kgx%PZ{^4mY1zKLMe~m0l15H}tV#=3A4L!$B~{qi8J$${Qkq7+O!gZy(W1%=
zY_%lq=lL?5eKc|t$r0FzcnWk5H0l($WLMt@``e>sVYFULjUkDDdm(B>A9B&kA|-vX
z9XJybVD3T=_$ORacya{_1ebS&(lW`5Un3jIb|iiZ^Bq3>XlV1iPW`#`l1IaG)*l-l
zQ`(Mx9X~w&0|JWuoG*;AMG1>C;nF!``RVBOQ9pmrSQB#9r1XNR|Ii<tW3GPUSeOm3
zdQWUN{tCm1^hK;;u6myqf&9*Fh_IA8frAO&>v9{$-;B`&Tn!TRlC)@TM7bYx1T;?M
z$pCGMah0zwY5r&IiW9iv_}7L3D5rWS@32k%^kXVqUGW(Jn#J+|71>x;8kD<AP=Kt@
z+Rc5GHBZs7Z=i;DvGF;84;v&8XnQM#2l(_n_Br6q7g{uc<l86HAK$>7jqL>w@#QhU
znUAq|n;Sd0vM<k7Zvx50wICcR=iZMSix@D?4CWdn>U?9@OXP9E5k7*}rs94aTb-ZB
z%KFM`%SuDCb-D({Lhid5dy=ZTe#>CTMTnuOAfA%yz3w3&CE;9<!%P(8%5qyXauh#x
zDNfRQ8qv>*1K^Xk*e|^@%by4x!nuku7FqDwFn9O0LY}n8EbEa_t{zRb$i^wK!*{Du
zc6I{18?N@`l%u1MGBd4CtXGc*2+a7w4fuEs>fpZEGwQn9jwgkwSu7=W3-Gmy=SUn8
zaPVdOzWAajJ8uYR{3W*f?uRUE4YpX57KyQ;7Cz2R9etb}EyX$Hg@W8$m1%^|E;j1y
z-}t^qkto3s_u(ca7=06Lax{A$)jBAMMFuMn(=$>;BZzz*?=Vxe-Z?3D3>SVJ8!sdw
zx%0E_?cZw*d>CJt{<>xqtxb=~PmpZ5dh%!TbiV61H`&Ahp~+lJ{v6N_SVVl^>S+bl
zexm^BlQ;V$)46)x`k*sW)|(M1@5l}%7K)z}6ZJll4P?MZZJ^F%=c#GxaQ4IV-mE)#
z!c=@MY+5xOPh_+U?(REh)goXwuJ%nUe@RGPo49%?N(+#koxO^@LY@LrQx!CXS{N+M
zsDBT2;XshZ*<3SXjGKXiJVT)BUe4kYF67n>EW(n><+<0@8eSbJ47_Y#KzW&rPAZo$
zCr5TvOlo+PH!I|;Wi?<p;aaOkNaxlrh_ZcytD2<!rp?&ibq5K6SEoH&dRt^QdV=ZU
z4OW2$rtiFsH^{QzYGs|Ns#p|o+;>Nd!k7F{aK*j$OPzD%&|x0uNi9iYf725O&Ed-p
z*FRE_97lWi96BSY$%jyiQd>VWm&o}@AYo1iyv8c9r2WQ9hr_UjeJ^1ku-f<dv~a$6
zpET3KuEM$+b)RlBFVU_Mb!8i7DoqCXRQ#zXugsIutGe`*v?VDsSL{<&_c!bkfiMaB
zyOH7j7zD4Fn$fkj|75{nGRf3e9`~d~;h*itxJz=saC+7IC*7kmt?eFURtQyTl_ZPX
z0hi|E5lHIE<%w`>)@gM^jS`NyQxOQBRxw2}jMBY{Re$LyPGipjUN0cNeSI6uhyk!=
zpkJ`gH%7AU&V(n{T31@h5J>x^la%r%*IzCP=K*393ThENkKV`KL7QMYlBL^VL5N}N
z8W7l@a_NmKJRX1xUj1`C6g)W|3H(c<mCdgPos~diis{ShltF247p?>ME`hou=lLMg
zJSr}|9Hh1xBNCT*q#04M&CS+Ck#kfhmp4;;vp3sv-H3Kz&W-Nx63lhEzc`FGvqskP
zUNEo+s17C(^Eq7{`pog<R#AB?P^7y3q{*epE>oEZP+b|j$RDx^9M*G|5KC@yREiQe
zocVmn3NnYtsPhXx6veLS@dar}qe9|4xqq345v?_^+%as6DN#}o<N%|PRm+OJ$Q+;C
z(^KTuQ&iz6N)AMI)(HS~b77Ax5oVIRlE2J-E&c`75in~Zo%ZzCroXksUH~NrRb?=6
z6ST%wt580d_qW{*M-!D(swx-<k8s<hf@B%CdPEy%68GCE?VU?RzyCMqj1ZAYgaQhO
z-T)+VQ0khL*Fh9DLX5rQCS=`rIzXcT*La`Wow-}^)DgpH_hcoj^Ra{>Q&e5kR*li$
zx)rTh-G8RlU)7J<zptxCG0FJh+srNlNh59^F8nM)r-wa#{b;I@+D6A&zC!=Je~T|y
z;pv{GhDCQ$lHAylU8Y5u{eK2e)7u|cmVH0*{-RzV?ypd-J3<C!tS2RH!Hi@clzHxD
zJNb83m@-2jAEe9_gSAmnt%^r-zZx6GCmZ);V#H=`jdJ*CYA9<kZ|CNAHF@26rDgVR
zp&3w;pdZkbOCL$jAL!qC3+)aWbH!E`^fZ^2=gN;iN^AIEqe(jVFOGfZX@+cjX&LlR
zOKD`fpJq4qe1Pk;58AbVjn(ky`atHE_L#nVIyK5bA1+SzAuq_9JaGci20w!1z0FbO
zuN9j_$cRoO$}TcF((gWc`_MwBs)p^|L`o&{1Ks^*56d6iS1bzc)#cO$d^%P?z_-EU
z*<X^@;U-Nt!B-;>7Mq*;Ervas*hd_`99Z>^9BuPVQ+wZg{f~NAVgvk7y2}W`VEN9H
z_;uJSftEr|h(V}tOx_Gb?+C~6Hkk$1%QK}L$C1|jSQgo(XvAAt#tX;MR#m;k0~3Y6
zmv^m#V|Ro7oWZQ)nkwXylVUL(Db`MG&+k!p$=4TQ%XH2YsRf+l+0~9qJGq@8g(sX8
z<4qIm4UYjy>Xbx8puy!!pbku!)O)O%XN`h@dWKWoAzOnuV_8Q^pSAch%}&@*VtSG}
z?u+xx%$Br$4}+`EpjL}FdYCU0U8GaJnlyKDGU{HUPZxIpQ7Nb1yP@dc?Q{NEIij~c
zgcpkURGw|4c2prI5k(-;>EMkMug>Kl*s3(d;<Uz%&gwteeL#jiL(9e;W+FP>olNR~
zk#n4Gg77$yrxbHpeN%_?RF>$@t?ej>r(RG^+{)$>k6NaYe&}m7cUOMO%H>>Cc=DIu
z@*|$#Uvv`UIJjZ`-!k_9A&LJtlXh#CR5rI001*7~xpqDG^+2q-&He@efcb5A{`UTb
zb~Nqv&D$qj!K59XS8iogM*;xoin=+X{|`j)-!}UXNceB2=@T;k28C`GAQ^yLiV816
zs-8S3iNzd~u5PI-xZpj$ww{+(ta*Vw7Z7+(#u4s}^ZkPe2fpBVoxpbL2a`kEYMsGN
zGW4~I**#C7ksi3mP=aMBjMHIZbu*3erBQ8``?u~&7OA*C=S?Hg=J(qz0rS5So?wzN
zWBi7Tzj_69(vG~oW1Fq0A_1n{9X9Hg7Uig|m$N{7;2c6WEdsIj9#*!m6zC28X_|)T
zMXHVE_2EG^mqmm3y<t4fElP<+O5-+zBDk;j;YWS>ya2|mol9_KpYHUOSyKShw%2@7
z6mQh2wZNK3c*XnPK7N+bbC(7~7#DEHcN?0xpgyd8=z^J}_6MZ3SPPzAtFF{fhgA%7
zbEf5+x5`cEOfzo|{O$a5NrUrUkCW=ioh5>;@hqin!tTn;%wAIjFB;ig<j81GVw|nE
z7nSgLc`odr0$7#1oLfKBsW9vyT98e0!h$VR)4+33$)>}+@~$pt?<MDZDT;Q!&%D3Y
z3JMy<d?V-0->sh(%nW~}a1NvJp{lS;E8rrsikSi@M68}X{E@}ekF}Q4(a*@2Yn9Wm
zc0X17gFcJ1mi=8Lf0Uw>)8N<F&*nF&;6yf}H`Wn~m9qU>B%F9#M>MBSx~0<_On*4y
zfI{eX>8WMqRj)X~t&G0qN|5MaJ(MMcE&=9}_APhJ`Z$w0j+R0b<mTP8y{{O@G>zl(
z^?&yQoTl;G5(jU?v<hm-;+1RN5Pq5kt_KB?X=Q4<w>p^F=+_O0l{za)yRNvH9$(~>
z6^79O#iKs9@;(jCy{5aLQpjS<r6Cj-^&G-vVi%v$>|Q7;+dC@<88XGlzPKAoaCHb-
zaF`~P$IS4psBmU~+x)Mb<Cg@OL>Vk|XDYeA5*dT(ttwMRkP0ef@y>`pz0a8vgMZze
zRxX;VuH!M>hxeBl*eh=i9Sm5tqJM%ws}_LT?{Hp<C`R}w%3Jt`PMfDRIg94%db=7t
zv<7iSZ*Nov$EIrPxTcwa$`cO69&Umu17i%*p_08l92x7F-;83bd+nfv!d7+Ox#I<l
z^Ag$e5R|L?CC`1K>zpiGzj@_IbYfV)VA*Kdq^-UIiJ^nzr}t~qvQ$Z_$}**I=k-b6
z%73&GbZf44bws|MxgV<G4;<ly1_Y|A+stijVvWn`zLHHlcU1rvp8k6mtRXt(E2yPZ
z3Ow}P)6Cr-t>3bWP#6?e5k2^ud^X3m{~QxMuVDa3dLH}jsMAyLIyv`i<##&YY1k>y
z`6x@qbtXm821{hm?Am$AGLoI%K4h!W#-#<dXBELp)rx>WK0A3h#P&>20sjuugEiz=
z-Ce!X_P!7hjTd}O8bo4*VEfqn+t*0IPHxfTHN#vzVDnSU^956dH1EE-`7z^#L6;Mt
z_Vy0Hf6<VXF#8wt;5SIDULxu9x24n<r{?n}L04|IQPHZJYL={8AK!!Q3OI>Am`d37
zZ<WublP%5=$%KkbOB>Vs?y#7^k%O5HL|fDc>BUxzY%HaPA8v1G;GL!11_Pu9WUiB9
zq5f-Uw~1y9_}T0A?zPn#x!ELR9erQhHqUgE?%8Gg*0Wc)3R95&7zlmQ;cu14F32Hn
znOkxkO=+#kY#L_p^m=)8+Jn>eZm(N+Vo;_}z|PQ}*qx7o$n|oIvL;axFvwW7$B9Iu
z^L$9>ZH{(RZc$Z9YiVJZsfW-~g{~nCSj{uV!8%V5wPdOy*|SA}2sg(U@7HcNlx*ZV
zA%Ll%LS_YWm21RMvj)}ifptyOV!Wm+NljrPm$O)bOs<D-Gk$y(Pad?8`av0DW8@j5
zJZui~iC!*+2%gq_sw<a5O&F-DS#p3?ib_gZ^Ut_lv8sV&i^umWP3|s3LcB6%MiJ*1
z^DP1<3pLk$t|opvMevsW8=Kv|xwyuV3|0T5*=^&(xth=r&7|l4lC_lL?)T>=qR7RF
z%O#BZD4?McX-qdG*N*#4uIi!xT5_puM$Sxvf}x0tnI;`gd)vfp-w&${ThXh}(uz&~
zJ{rG&P5E?|VyKMbT*Rb_=OSzjV$zhrqZE({(t-?&%(V9nPTE#HQ-`9T+z+{024}ln
zvx|A^F|Lgj!(G!v@of0sb1_Tt{0i9?Y+|7xcEpL&?Amcl37?M}2(R4dmr)2G)*`g<
zNl)Bk0?KEH{2S}*x)>6HyqSvIF(KK(eNLnPqfm$78+a4q3}T+gD~m6YiKV6yoThvA
zb7{Bo@9>9XmM&8uOrFxflu0GCzoPR_R)zs4Ba<saLHS^yZQ8F}7(4zNtYE`M=q>t~
zJm-z$K>^m*nVPQ<;3JFa6^<6)aAsAX+HKR!%s6OSbDi7wIEE--j-EpYQl=#tUW)k$
z6NLe5k8+Gj!_ghgtRo`D?n-?AypQ;xpirV&cQn1`KFcfZIr1?IOX8Trgm(r(q^D3c
z?>Td@?7DfGnaE!^?dG;S+-)jSTBn<{I<|3$13gfWp0n{073Y!DBYJ&fL-X7ahkZOF
zee)@<VAqKyoqNga`Op$F5iqb?5T{>>XfhFEVm{lOf)-~-&bAamsu4<M>Fn2ivk5?Y
zq6l?!UfyYa`w=-F1#CvWvnEE0T#g{AMRoR937q{iKg`7mrgBWfs5p^4YPpdlo*#}=
zMfv>c+tq#tKz6d9!Q`#wdNf{F+|;ywDP#eI_1^f9UqXAGyqxcZPj3UIR(xS5cgsFY
zoWeDR-{uJ!?#d>N3pEPd=<zQZi`;#ZCFG+>sK~T!+^~IdH7fp$(&)enC{|N4Ngr<{
zztNOoy}tA72{#!2NqUR|*<3)^uPXQ?o#lOW3*3BSx3?TFCb>p&S7uRRsyemq1vNr<
zLmO>P@VJ4zm8+m|i^v=y;urDNLa?i^XeIm2c>#681o*AX6F!B-#fA`QAbftddeFK$
z_}t!qe)QU-rYIp?P2k`h1LjQIBN#fUtd;%slbvV1wOs5M6GJ<Niy7TRL}ji#m!-ro
zKg}h&4KD%pWewP!7yRMHL_A$8PvSBUFTT*T9jC<s?bEAamdd1XkkUmU$V&sRQ86c{
z#eh=_PqkVm_c|U%s6L98<ke;$jybDrNCY^x9VYe@lK87D{iZK`!%4N{tk~TlcAQM<
z$MVkujNm^Ke2`i@E5@$+B%(V##+t+cdXMl+Z5Zd!N@2u@NjH4rN??}1gk`9Tst$AN
ze*#T2@#-slSU~)mw#K||o<3EN%I*WIr!!}YhVPj`!xi@a<WvmHM)OZX<&L<Ti$5_4
zmKG%v{O%4A<JZZZ9IrrWZf;)ee`q=!?hck^VL`8|!pdI67-tMCc<u4kB!84RtJvAs
z4<|pOkhwbkcz=1*!`H%P?mh?HSTU#&4r2*T(T^=oO`agL+#<qt^SpTm{IJza4}~3$
zl*F!3rlqS6{c4;5D{Mx!zhf%2mTwf&ht>71Us`d1E96u!Y4&_81r2|ERij^rNh<7N
z<(E1aJ~S+5gf#9s(KeRrevc>pimxX9^)gs-KeZaV7CfFRO}D9$`Wp!srtqpSC|<NR
zDx9w|V76o}VzjmX(BxOz=U~4aSf5uLa3w=o$Jv2~io#t!@;QK!9zTW`e$wETg-jg<
z>{PU0ujCXffiHx~6ZB+FZYpPL^CtF|B3u)AtAms;jRo(MM>X>W$Zb=1kCnmKtZbH%
zXY6cG3!?Y;#1DK;ePNwe;#sDX{yMlK=gDEVN#vUNi^$?@U_ZoZ_CwfMMPQ8*MRado
z6<SAyS48{27@3v^65a%{Tr*7|zdT>AIRSrlrY4bE4A+!D<M)E9uoU$$_Wae??Bmx2
z`K+%(X@HNQl`I~71q&e+RpCI^@q~z5bTrT$q(_L%;i)v>haB`#C~_xf=s7itApQ`n
z=k$8+bMW&B$(JaGzb8qn0A6^+PoBHzJu6|Uxyz$Vl8A5Yk?beQncB)aBU_9~q?al3
zaHn_}B7RC@W9bF>dJMAL4#wj5yBuo6jEwH5;f6e9h}0pB%z)@UHN+b?qJkm|!3Y{j
zXR7Jbv0N8O2dA(Z3>NYF*;Gbxyyw!hza)m}#}5it?9tLRT=Q1w0kBZpi+jDjD`-Wv
z@OZm`{*QBUBzw{h^E)n?@wa>ZwJMQ4_~77jem(O2z<pxiDrP;F6QB_=Q!n59I2o$+
z@}7c<#PAVw>no#@ILrjn_*y!iW=(}->lDdFpN9^D%_Nu;5W!5CST)RS2p;lO>lbGu
zlNa@y|D|^}&nXhVdd{6_xQE5CypT<#du^lLM!-oFc<l&Z)lbWv8M#d!6h~EPK%ysR
zV&2Elwu-I0y?3z8;wO8Rz+dyrPizl><0Ha9+L}MHn<onY*knsV@Rk4{VVAe;iTsHz
zke<MccsAThY1g)yml^rv8$2dpB2>UCKZz79`it4b@P{43qHZMpV)51N>zxz$#ZQm3
z$XrE4R1O=LPR(JW4;998V7%hu3#N>nc;?yCMlStNqZ7|E3)%<QPyg179)o@gKfzw&
z!~3V|Pwkkag(zn{N&u$@8XRW7ZNSP#DxYvA@wP7E*WoX*ii-xL^Ka1-C-Wu7zN;~o
zT}NdG3JPasz}9t-ocHS+1v2e?*=oNVGMsCTuJ+Ofldb)htghAL2G_ka@2c%+$90su
zw!tvxWo$d#W_|oC@5&-M#LOT!YIuO*jHfr61pCFU{f*axh!;fT)rN3{s0mxYs3???
zX%$e54u&B7n=pjZ-(vRvg~LCxW&hb15kpO+by%+*(YWM>X)~+-@QWp==D1DV0$UK0
z0Ty;N_l(l81(PaeUyv)Nm`=m>c)KBJzR|%kUWRB%Mh=at>?et-5kV@xUHb!?^d`aD
zk*_n7Ia^DmP4w__U#zdbO;zpqNgknZj;Q-M33`a88$GE1yN_5b7{yn&;icQmHoOzT
zvYw+h_C#c^bNO&mVCin(x)_@=5z?%B@l=xI9x{w5sug<G2uZ!RO&^70vQ$^V28Ttt
ziLUCa=`0GVgYF+e(;Xhf#5t>9KYrrH_Yh9n?}3tk+^7bzTFi&1=ze+|5hBG`nxG=)
zZ$LA%_bW?$r=0EDiB?}0?k+}h0*kT?)@E4=kxg3*V*zw#OWPujbEo=Eyf&vIf+f-J
zBxbi0nFvHo%6l;Y#gy)^8Q5)KVVsK}M0$k%nS{RD2MYx$m|5o4rOuO8So7>utE+7}
z2C8i`Zg|K91sKzBTNt>+bvFKX<~+SoLXN!EX&nG*1*Uebi0*6yYT1x3(4N@0nDj?3
zolo`Yp$;vH-f(n^bw{vgmzILS;VX|f$U^ARdz`-^A@Bct!~eh4^8e5BUhnoNUb3O{
z$?hnSr>^&x^}VrU<R34~pArq9gxqdxD9gM&Ur4$K4SZD+bM+uy4*j8#u}vcu<LThi
zy-!njnd0y#y$Wrn8Y+wtc%x`S>HV;|DZ_$DkqvmDyi4<-B0Cd2h#eCZ`}i3$PQps3
z5T#<p({erx*S)&kX)dmZ&=9?*%cy*d6X8tnKwUxK{2$_M*CbhElccGi%`<iN5Dq0Z
z-?nR;D&19?K!y=(7to2`3d6V4GLL+>iH&X190Dzv%NEa1G-FU#aIXhADm3i{tG&^9
zmUuZ&-4cgSVi9j+xW1xozFEDv)sH(%W&XaAx$i7b+r^i0*vy1Yf`V4>RpB~+M5vD-
zFH%yWeX{}g*#{N#6PU>otLe%0xK|qbFOG-)D#7x=0~EgECA%-@1W7-kQjR{~QtzHr
zWgh#UZ%cg1G$6$eMXvZfj8$b0Qdkt*T(Aw58~Q6Rmubq2Uzl!AoYn_A*A_sjeBa#J
zHhw8bb2SK1_RR9b<~Oss?buN+9ov$9Ic%Xd*SQH|bH8*}$~iU%Yb*L+_?>0zo3hG?
zzK{L->F&q=ZilgFg-nuY+9vPP$Jy_<Y;{m!wN^PUohh$_>7SHXCvzn{+Xt(dCF~;`
zngB2f+o8%pvF!Xfr_?+wXVCL@a*xr)f8?*xB=%42`kc*aH;e&d`EKwOsheHgR+^|9
zWRgQCL#Bq(|I>!DA1CJc$=Z$eSo~cBiv{*@_mq3|9Mb|qpbk&ym9G8_&zxsNUhTJr
zGZ)A%_D`e#r3+9nV~k^Qv16R?HFuE~A&QWu@lNyuqjM)r^AqY!O{~%`4E?eVNL;9`
z1))0#UvDZb1-Yj)&()(&@*g)Tj|2B6C(3HleZ@~zA3r@vXBY6yBSr6i25>wuPR);C
zP^z<@m$xNmm`MoG79X(yt(Z$e3(8d>F)v!r*BPoS=>;w`9vAJkoeWWRnf9`|1pvZz
z%<!`U9~~VYyzti&{xbpRT(4C^ISg>qv&>$U$f{^4|1!WT8CME~-dhyT3$yXMFZ$Sx
zzqAwe`>ANxvz3<0j_w~d&X;FDf`<Oog22e|xf)~06u;bDNeEzb1c^R2Bu$tQsPT|x
zw2aG&Px2!#EV29}t+N_(8gKuN*XH6rVGpOU-y%SbnXHK&#<+s>9LwtrBL<2+p$A&R
z^*HyO9{<q12HtD3nH}tj{hk(4I`=4L43|7S>1+*umOF%xr0uA4vLU@r5z{M;&fOO^
z3iUq=kH!9_r6%t+ak)Q)uWV*XW*U}S#G49jxD)Fs*x)&^;o(O1-I1AVEYF%Umu*ac
zQ{?;DqV8?R(oz7jH&NCo+qHeeH{T+T^BJmEODXLB(87Nueru;^7U6E1us~3aq0i8}
zBRni9uG!SI(D11UVXf~I-B^P44Q>({@#O8lG3Ti@y(J@D1GGz~_{jzQHi^q<_oc}3
zXV@o{_JpqI=^fdeXy5-^GwnMb4&Vqzsu&Gv7!@&bUBT}ZGm^;tkEAuF!S<jvZBDRH
z_mc0WS8^KH#e8a+f)SjXAK66V^Rw3D3cWn<FO>L8X5Bf$ESGp>>=&>smIYiI?7hFi
z2yyb(BxMK(1$_&!F0U^AF|VK)pL?|{57CEkC&K^`!IoV8qKZ)!j;I)?{zfHlN$z38
z#DnmyxbaL;gT10FL3^xRNnniTuG=%Vp|MNrPxUpV<pp_Zt;vj-OqbSErqA4SFbci}
z*xJZCSQbZIJk{M0xq&*U-sIMzPqnedrE+!j^sY0kJDrmd!+Xh>4d!u8q3FJJtJ6w}
zbMth7v;`@u%p@^a1h&*=)<k2^+5kx*Pclp4R;Z&|S=YfZS~wf>mtKBPXMl;oZP*ZZ
zU3bN*wE&N}8;vi4f22m)Q-deS7`MfJY##^1Pdc$Ot$UiI!dI52Vqx3(*Mo6cXCi7L
z!^gZ}CQScx!uZ8@)>L*RG?5(QH2FwV&6L1=d4xfcZTV3vdOljDZ3$HEL5oQyB0<WA
zhgnDI`^SSeMSeefJwcX}irM{kGtGXmJ(p*}n$euKqyV&{yyRE?ZU~$#%f=UojwvBk
zGC4`CRT)(V<zPm-D6rXIHRc6IZJJCjrd}VF$P!j>W#m>^Cp`Y-p@L{#0m(Mpk8AQo
z^E30{*F#Zadlb-_<Htk(`eBKOj|sd;(}>Y;`5xHV4X3LMXfb!CTu&@W`70m1%z$7G
z@cV?Ta@GL%bYc<D{P&0F7xv!1T}$e%;k`~J8L;MohEGXizd%_8^$~iZEwICe>k6y-
zjRBQw6EIhbhhyQA+y~`c)A5sw&y>R_KR6!eZ!`T(dIl+u1wCdedrc>2%EpOo#GG_X
zW;9V)hjLGNTU|q#f7{N6BYh7}67yObLfA-+|FGvNSf%=H;U4?FTT?-Yq6xPmey)9}
zsv28d<2wySgC<|cp2o46*=1SrFD7OPk3ovmR;XaFrJbmva*#xJ+5udFvfR8zacJ2`
z!vZtWwJf&loE%p~0>fGSv?);Ta-tGxS@__R`V+K8I9xKb;x7pWs`J|4?@1$5awzC_
zy$mt^-)iYE0aq-L%<&;o5?_!5IS<O&8ZbvsTIaBH#M&SoffkEK6!G<h>2N7~g92O9
zU`+`1_L`r51*49@Fh-2@&sJ!Vtfpi^IKppdwqs{F5|YQP+IE;nn0M%OnIxW@i~Zq4
z33tlQo#3gO1U%;KC&+kC=cjrNU4|b5L`#rknZ9gz;5wVfmpf{cA6S)}X-Rr^mj}C7
zS-7c*K(58DrTEM&M$QDxggvIh(O@{bbBiiWdP}v!dh#L%p2C`nsVG}kRLT~G@AWjd
z+J}5ekSRkB2;%w6?t0d#$Zkn%dW^?oH%%iqV-HU4a=L^oHegR{QR(?TV6X9tEh<K1
za*31s12)FB$c4aRxZ79h<~u`U_@qh+;hsy5f-LCOAr+#>Za$Flp`hyR>v4==>W_Ct
zLJwSKdyP4bG7GWs2vP;nXT}TZ{xP6S!yjW@0+#s&xIa}F#lB<+)cx_;>K5!BBFMBo
zm0?e7@V@ddd`+S-usAJ^$uwY1BFDkS<-^OEVneTy#CLi8UJ=i}=)P)-L|H5p+<MD&
zv!fc{@(VVTT7?!QhU>p6um#;UiE-!j@+AKD=&m=a%ieG)Qrk5h&!Tl9DQmRzeh`Ub
z6do3xjw|Q{w+5^rDFcZxZ|XO`A&x>bkvI7(>wGW$`*8zq_%1QWZ8HZ|(x(%cE+hlD
z)(Z8J6sd9uFrJBW5M>KZ_wYp5d#&HrSu>Uq&+$}o^Ly^c=B{C(V2^)4aF=tA>*NGP
zoG+jGtA&U^{t;`RyYu5Ah+G!4lq&0G&*auYs9gzeLp8Hyme|KTjBKO_KY8r3TD)s<
z5b{b}wp|<OHO!G9FbP=qf?13QT(l3CJ=E9cMsUsB8{|YLl9<>^e=%99iNOhHKzhc3
zWl7?!YPphgDj`82G!p+<UmGejhbLFa$MAvShl;%iIz!(YzNg4Tx*+E_^^z_l!LwFS
zkZ@y@int1;V9m(q7GO~_=0v}3qc0f^x?nH4AF?5)^?Eoh*BT>ZuZ7F)$bY_KH&iTw
z0N-sa<q^P*-h!xOX!(~I>pBv$=W}g-WXU%bW%GE^q96{$R`E~SEiuBXLX5pyems*u
zAna!-)|?D#rNz$`VZWXz;d@piWr*b})--Herx6vVe+T>?GD#sV=>m5bfoj<1C6bd9
zp6L=>*TNj#=bH*bq{%TCxm-$t8NAA+c9Dru0XuTk7Mvxq2)1<f$VN*>0|>!MlMxxm
zgmd-xUTJL20qeVq=QX?5DpZ-FweQ&&=zaqKQn%FzFhsc+B;`Fbteotss{VXQA{4+7
zf9jSsAS5PXa)wrC+b~BD4VRI^i%`Eb5AgbQr-r0={Om(2bd_{(dv;-yJtc3V52CUx
zRx~B-ph5!2a?E3f#Se`Zs2VP<X)u}{3Kul&e@9DCWO8f^mp&m%5=8@@);qd~Do0c&
z>V6x}epvm&ygcEtC-62CbyzfN`KC<pap%4pcU^r;1y|js2D3&R(%($+vk~`~(<eN`
zE1y@%3P$cH8wU+_+#%deP}1k5PSS%VyDC*34{<w+V14r!F|;XGJ@4q`Sqaqku)h(z
zW^&J4Jr^n_l~2p3ai7*m4-T-Fdn}S66hbcnUO8FLxCMPhFSTyqUHWk*J#m{EaDB6F
zOagbwU@5@o@Vi{k^keX?_w`vcT&ditbUnxxWsnfY9aRjifN@gu;+}K!S2yPOR)$tJ
z|L0jg!T$@hdUiz#`NNuyZm>+iOh*qF5I48?YhBxLP$~swgA<>x-B>FD_D%R+ieU7V
z@H@>>StU8L3nORGHE%P2MZ__dkc*qTeb9eF=()4fU7YHUmbxiqPF&+lc&CbyTUaNx
z=@(VZ=ikXcHw*Khr4=;WnP`BB+`fA|ysdlw^1E+R>=&3<f3k9NYyzAI&?Y25M@{dn
zr%p4-jSXmfsmE@9R7j_8O%)0F>Y7)mxLe_xpGcdtPXefw@VV)mz{n1N4oGFy(uoVu
z%ENsDnDt8#_msvflmnD+=6!6Oa+0KYQi~}_k2PkfJp-ueK5@tYW`F!|g=-j%!_LCX
z?`#Y&-u*}8^+#(dwWOjkyCi$gl*g9$MZk?HVDb8Ac2?&hSq4e^-&Es@lYv+_yW?-_
z1Z6RcPF{xD9iodb0UocS^d$*XLiQTZ;?B<flg@~ZvsXRrj<dfqUO2CG3+_KVdj&W`
zlg4<_H)l(nGrkimDte2x9g)|w=cBSwihb$)BtG=8DA!?+=LJq}GR1Sm&6DUui7W*G
z-=Ag6Wq<A0{Agl=$BQaJF{+~ZTSWC(tA7{<<?3ZmJ6+RIkzx88zT1;^6~2$CA_Eko
zU%DD7b$erOM9>Pg)*7PTap(ZaMc!Qrn2rDTHT~@|uWLS-ao#()sQ}i8sxc-o@Ae13
zpgrSCR$!ai<FSl@wR%5JeBh*52mH%;-brP&jDCH6_MOjOUT|~#ev|vl9bVlO!Y4?f
zXraDJ)SHt%BuGL)E|k2}L3Yw?bj0Z9;|A*q{&%#`m0NN-B3!)HQ7yNc4n^w0a<)8!
zSQoQ{gz9^zoZpTP47R349Wr`@0BC$2^CQcN^R`$?;%l`ja;x=W-U&Gq)=OsSTA>tq
zS7aD~;M&>;1yGsun=z7bKJge@gkufDw{`EIJPrWU9y?a5ccwr*HTaQcuV33?7sA&3
z_O<s?;~D5_74)CgyWJa--tX9lqsG`io(++ce_6=@1PBspc?%xdvkYjp&Bj@YO(g{X
z8Cp$$8mE)0{9Kv)(I()ZaS2r%LdNxPlpOO-zwGr#3e1A2WGlbJ+62E=dwvYSH3)kO
zJ6OLecv})`wrZX9K4z(mp%}g3G9+&PB}6|xUx|mTc2p_kL98^Zw)I8z>w#4LRNrWr
z%jIujV#~XLOA-t~-FSw}MFX*pX65Bcn5#JQPVQ41;m8A}Ja76E{4^8Q+cE3Zw>?Z@
zFjJ!wp0{^3@*nvG{H_<(!6(>*cJP(%GV0>EJJ3t;-^h%5E_X7n|6cGDdv%*lYPf1=
zN1M!Id$F~4Z*k9_Z~G0M!|G5VV7{gLWCnFJ=sf_eJ$#&iqmF@C?!%7l!8M_o56#oo
zLZ|^;3FB)Q3x)kuVO3G&swc`ygvj8bK)GimuFXg8@HJD+o5Z-B3Cz0-DGx0<<}Bum
zT>(;3dBS1)tpP%nW#^Gm2Wwg;-V~>{%>2*ZW`l}>NUPG@<m3DOKzchLD?N1^!A<qC
zeVCn1X1&jk1;Zyumjkp#E=x=jx{MJgk@+F3E^?e#va2`(BNhmrcIF>#9;}EeOgDLm
z30&3FzrUh<bP!Pc7u`6Og}4$t1PT{fgO={)p7nJCwdGOl%8?T@e7uu+pjZjWmX!Kz
zxh8?9)b*7MW6a|?>Rd;xZr>pAM%W-u*6pOcy4B`r>$|H%W34O46r&NAYn@D=IkvAa
z>r_n&b^J`Nd1iVe_wZTngv}f2C)&>@gQVq$e($=Dn8(nvJNFe$<}EcioA^n%R<e3d
zN$>OAtF_eD#Ku0C@ATGHL(!uV1!{$iR?*s~5q|2kH~JSh{ECVU#|y6oGlhEnkwHwF
zqqOxDm#Qpu0q}HA<`V4^jsX+;gKL?eUmQgB5!?T(7oZ8OIShD=d3?A=ZCsb&=XOuk
znB2y!yz*LFK|YjC_V6Yogosdlb5&L4fR*G!>&-j{w#(J`<3LI<xu=r8I0xd7L~7~t
zDY}zSrD<wzegK!=#i~kmW+(5@?3iG-KEXzhqtHNN{2bV`r@rn?`E{0Ic3QnptVWO`
zV$`?L^Dwz(e7`ARO3e<oKc7j~WVggN8dvPD-S+VbOJX1pLM@qlvN>`lU+*YU1fvWp
z?b*aSD>onN(D?Y`^kYPHff_0B$QcJxuVZY7&XdJ-MOEwVnCCw^9(FU~XQ;>iD%4p_
zX8@`W_0KbJZ-@BtFz_j}Js!euT^;bj{52EKp9g4s>@zd+OaveOkqerKL2EXZ*AoX(
zT~VVY@n%infl4GjyB?>W12CkuF7S(yna1(og~lh2$PlQX7~b5~*6oetQY)0+_B-?F
z5mAjzPvO3_#vHeP>SJIQZ=@4*Z5qV!j$r<kZkgBUt<`s&MRiqOtex$PuX+cdG&2(e
z*y^LA@?y^^i**$TyzN@QcUAj;2T=#2;15S-58Lp^Gt}kE6Rp02)Pb*i3g)RR)aXMN
z5Q^RwF5dF?od?7F6J-(Wol{LhgQNyYJ)xJD5fTs=DEVV<VtRGm_6P8fl$->t3&MQP
z_sWFee$S!nZ9ak|HJ$4v*9@CoL784dMxL0!BNn%;&m<~TDzd-NS>+$~oXeN2FQo4>
zm7b4HnLH{9@y8j<u?YlgbQ2<aWbpi7JL>1!f$tr*>rgX+XJIQ3K{JmBs4K_aBlTs3
z3=BBaP{)2)S$_s43ePjh&yQ%>ryq<`$e-BT;U;+f0;XRrz{ex*XLf9+x}CY9ZSRsS
zXySXWb#w(8nc#f%Q;hS}E^o=(R__ZediF)xeNRQ`?1>*a3}Y!spKUp;VE03*2E;6Y
z62#DAY%e<I5PvFrEC-khP1Ja$2)fq_NnjD7e+O6~#NILxZY`ktAZnsWJWeRa4Z22{
z)Vp0S+qrrnsOd?1DLH<!aVNw*u&oz&U-i?TcHCHTYaDFS8s~iY8_|*uvLYDhk(nsP
z&v(s8dTOS5fAjjY&|W|!DXYui!?Cp2E1&bL(Aps%XFd6c@!ogGSx-hH{GG3|Hb!RZ
zHVseIZxky(b2@^obj5d!SG;I?U(vPZK#ulbJ`TN5F^djkftF&6c+{QENJaT*5fgJx
zt_=cSYj~{MO82f?q$)?u-PJ<*xXc)ToilvoNs{f5;XPw!l)wV^rS$LN6BYA+Ai;Q(
zB_edPk>6nGUG4nzMG*CdxL%RhZ*A8P<6#F|qf9FPD&)t!<Ue+91+z6-9}fxOXFl$g
z2G3RYJiVEX)$)uKBj1ZH)0wqJ^W)9v_<V@z(|<Nbb$ePw3=+ChD;nE&i!>5al<le{
zHnS{;=ars5fjFTlPm8tr?uOJE7~7oRNr40`4`;XEmUuh#<yo<G23<cli@$RiyLY@P
z72f0y_B^#&&Y5a#o*F2Mo@B5+G3QDwsre#jz01boR%C+CafF7D{o~_FQmfb*a!|1M
zVLl&zF|5-XkF2@G=U~-wiT^OjtZgEI;&s3)Y1bWJMDnB7Y`OWTPpntYB=foW`mpTD
zpM=ZDyE?6-Xm$n{gaHS)9A%X!4U~^d`kG8Mx)bVsizt8jDs=zATVW19N}-HxQ?hxe
z8S3<4qKgrue0^LU6%%;21bqmF-EoZ4X@{l8E2$DRCsv2Z;dM|oC=7S7#qazcO*vYV
z(bK%CkL~|eyzS5`B64#!azqn!hhBqtDee=xfEl)4zqW@n9U{tJGd{%my-~BFgnrVx
zQx78>@HKtf$+zcsFT|84ZmpsuhBjDcw9h^e?Fd(6$r?MBz(sf?SWNSLS<OIaabohM
z%gb=Xd;a79z!Uv&0Yz+n`+kyW5Bs+YzvPw;KHA?rD?l)}aF$nl=W_uL-r6>mJ>EY#
zyC{Re%U|dLR3w|V&&W*+W_{f<e&qi_Ukr4Ro?u@1Vk*Mtxf-Ovmmx}i=EDcSl{vO{
z*v}9}QLz7e#>l$sT~UcB(!vz9KMKp<Vh}50TUsL`b9eEzR|Fc(r+v-wd`DP#mVsfk
z&Tm8G1W*%zwdlr*S%c>Y+;n>bFDDCw7~JUyovH9VnmQ=9wbRQ8uI>uxAV8P}X0QZ|
z`9_lg|C(LHmVktuA-?EM&p3ZTB=X(oc1VY8EYe6xK^5|qu|VBcVwFrMKpo?Ju^ZQI
zbBZLs8!=nRN3>Elsz=a~UA`dSdk3>LhtCb7wFy~IrL-+E_$glI4#};#@UD<K<ab+V
zC@u%`GYD<`%2ffB`w(eX(Cm|~U!3%dtkF+_^JXM9bFmxPDKP-`{87A@lJPVX`v-|1
zlE~#JteL>{+fcL9n;+2*IDoH9I7iE*VN%ez>sN!;WsnU44koa|hTjSuSi{|KB{t=Z
z`Otsf;5mRaJSXVcM%QDmOY(ikB?}CyJF;%maQyravw~*Ee#@+yR$UWp$+UKdC)KCZ
z4^WS*7FgT4`96&-S!FurjB?Iob&GbQOB0LxqVtJ->;$QB>o2^Z0{}>wO=!ae7~TRf
z*#gV6693nT$eDDU8~8N_K<y)ov0{@8+iTc!z>A8MPkK}G0N96;T|RmMV37pfTnkrO
z0uQZC)IjrlmM`i5`v6|?9_@EG=AbX7YEQFDEMc$5e~;Ed<+VxWp^ZMSM(O%xNlXOI
zZ`@e`y2<ZjdS6f-TsJ}U7bho+lFc{e);7<=M@r+iEFmfkI>imzF95=6DsSIdSm?W+
zc3cLqQ;a_GZ@*#UE(oAO5rWpCnH)RREVjIULJ1A<s;1y+1WThNku++PoLr&A19{(j
z%b-UUr=V{TK}xbCjW{j`5;~_DM%td#>i~2KGxC9Wg6)FaV4F8|%E|$$!<>96R^fiJ
zd3+>Ajo0B71?{Yw%<jxJtR&&DR?FW<Je5Bz*$$KtnUaYDR<IBi(Ya9fp8uWSH01Y8
z(<1FHb^pZTkZVqZ64Scb^f=T0j-3cmJ|!X!@KviIjyAt1wYa#Uwzy<Occ{TG4N_r~
z?Ko#Ow;e$%>D^#R6o#ZR+b+dO%P1Frno=w_8au309^oh7jT^*kkNYp(Y06M#z3Wa(
zK-q9q$~(X!cj1`Sv+Px;ylktOX}b|ku9Ximm^Jg9y!$nce`EpWDmjckB`Up$G`E`o
zL6$||1<sbIjR}7B2|~BdGi_Ts<N@y}kuiX*uN^GX1DLVDtk3|T(MsMk)$3#bzrWr8
znz($?s+ea8@mtFb(DGrE$~mH2xakhq-$Ceawc89!=fkgV!v<#@n_Z(9s4;6mC<e+3
zgtm`;bX6dV`#%FgKWyc>l8Zq)RoQt0|E_vWE9RH%8BCB$gX0gjDPa<jyyW+Tid-S$
z7pW!!rxW=N%Hw|ZzBA~e%uzxcdJDrtXkSJ7HjL*-Zo3D?{o|h+p)#Fe9OAzJG-FsJ
zm2M8%9sCDU_d6Z|bxf@8TA-GrHPz)4)_DQIEGsFVJi`2ZKJB8T${hYU{h^SN_u!b!
zYd>;6YvuA^_C!yL+(#a90Y2oZ7R=A+x-=xnNT_Q3*h%>sTX365ql!x_kv#A;{zy7?
zK5H`N4N1@uKK!}{_wlM%EH!>>`th@>o}|6f+v0d`NlHV4j(4!9kW`^+#`7dIs3$6x
zq%?Nn(1kR}n=zEV`D@E;t?h{F_H<#N*ewgpuB?eQz7V<Yay$MvjLUABq_<g|XBtFl
zsAj`k<2(OMMHQ7w>0N>o^<^c|&`UjX6eseHzn8jx$0pyqHk^ufRkC;8yUVE}qe*;-
zF-KXkYvARP_5g8%Qtff_qzm|`%dekXeORh2K+OFOLmN$d3*X6Pc%XEOK17QWwZ;JJ
za5=2;+{bmJKeA!!Dv*D#x@^NQSVz=*@lzsqFJSFUdd1FKOdu04k`Yeb{^xCYb@~pI
zO~K<-<^wr|(6dRtpzg1v7~Iyura>Ch$8X&HHfw?O3d1$=zm8GecIuTDS5(-d2b*q2
z@pDi<E^6``+4Fp3rC2}>byj1d!-c9Al?1+%n{~$2tD7jXGLJ3G`AbG&G?7i7=Wdrq
znjGaDwVcPU8&=9L0`-KrKe?RB!Ua%4GnN=34GS}y;{gWC`hib2L$c(9z;($&f#-%4
zAiN0?Wx}uqJqD{$)XC*J2V7>Vq81-R%cq1V+b~-Ib+%85`d0&6CIzm*_N-fNWBneV
zd~{$c6JE7QJ?=Zlu)QOF%(3h`!oI;;HK4cDG06U~F&xu+skz5mwgOKr3;@pZ3Hl!0
zl^Nf(??>duLp89#`rqgQ!fheqNl~iH-a5Z!6jS#SNO-68E{JHbXOfkHuP2ChgV;H`
z)ue4DFD}#-h(L7m;H-JkLj<9;I&T2%sXPe?6+ZpjsH+6ROXQ>9;&Z<YK`^EsHR;Vw
z%VG50tMEU7NHc4rM#r#(mS<E5A&q;xwm~pyml4+4{H<N-^YI5k;;?1KLb_YB(!C{n
z!NFn|Z4FKkOnqz&YbFg$1kGtt*Y|??fOk9<m%mufDQ{f50)#t5WbwM6A37erNL5Ix
z2QOaKkRH+bg6vpHAVP?S<A>(kzU4UNUdqUHPlo7Bz$r!41R-f|yOXn41M8{Cpi_?>
zc)n|qy3V(W=J6vh?k*s?`Zy#g8{x!0XRMf+*w~myJjkZuv${FJSiLtjq`;h*k`FX4
zQABJ>EF1Km<^3_*JOeDQJb}&)mnU4xAg!L(AVzx_8juu<Ox=~1wr!Cp2@lBy5_0Jz
zX@Y-%cr1q9ahoq}K;vpZk{`1he#EYGh&7>-Cn*C_+aFv#Mj0GD<)^}7=9i&D*#$V8
z`t|N^LmDQX{a)<s6K@)%EPB&jPoMQOYh6*7KqGzJt2DNKOkkF>gRE>Km#!>Rg+J;>
zN-ezsM~+WX<E7$hDF*H&Cp0dEL}<wEJP4~cOfOhpetgWuPTc*qGnd|eg+I`p1U@F)
z`xhthN*>fPgdMGs8e9k*HzyBG`O1@s)YgwV%-n5~4}}!0Lkkd<`-s(3tQMZmr%XU1
z{h)wwm6E-HA{{2a3HXPFL3wq+={INj=s2DW{TXtMBA#Zn+b$XmDkIYRw#ie(@dB1a
zaae&LrP#QPr!V^|8c1_((_gpw+ekLnMHCJ0TEDZvxC|R>=R$@_=X`VgH?-0s(IU;(
zi{mDK3fTPZwy|L4sgVM#=JgQ2{i<xW@XvRf$sf=4ouClNgK2Km<=<RyLF;FCj9`t5
z<K4-gGmX7{!Rr>CAP1A{`20o+ae03sw|cgKyX2&ZPJExLiuG)o*v}^&gZNTihySY=
zP^PJ)GO}st5Ie1JdD%@XK`U`7X0y5wO<5kTat*&6*SC7+WU_`ExVukN22XP}9Mx%^
zN3AC{)cmvXlRk^2kYIyZGb(}85$ONSF}>AoDin&qEQCA*f^~8jmkm<lrLiFl6bRCo
zy94$@Y%uTC_%8xFp7LT?;(%_iRYBQ|p_YndLDAodaG{tXUP4&FhZ(;dULerHdv)bu
z`Lb?w*$>q$lPN&>-3PSOlJ_F(T6tIyMg4(A!5x|d8JFMF8`ZM}R}C;Grm*o^K53Rg
zEqwH^fa8kp3~Y5Gfa@sHO#ju1Iyl%BxX)nB=+vnk8G$9aJ{SdQ8EpBpZf-49tt!4N
zsllE7N59cOj7)lAt#2d!8c({AY%_pCJpsqkBCGTwvfIERRwSYp;l1!*AL@th39J3I
z;fj+%Hr%JczAC%Or^iZCr8<0@_5>npv+vmA3SL~d^9K@~*-t>8K(p?(0j+vxZ-t>P
z4&ZO7LH+-n`u%SrAWTa6khsbt*-XK!IS$I(p$H>fQP{*@{m*&#`|OnHBSe`()K%AZ
zV3a|`{D?o#REu)c^#9e~c}6w0E&4u)qJW@MrAzN&(*-G8q=pg*y$EgrfzW#|7J8Es
zN@x;lKuUzro2VdNAoM1^gFxu*F3-8=-E-eLU*6|;zGbYDkulcHDs%q+W!8QenL9t>
zUWQQDdR3DFh%Ng}-|~+Yi%DFD6B0+%6h0#Go$Jjxbe`Srm@s}lDn|6}B_P_EB-Pii
zJ~Y%;Dp;1z<2@|Z01K7bFO9yTQ7aRjo~pJFBxR)ljMr4OH=VX2a0XymXar{{uvmsz
zUlnLJuNSI0w)q?Ny>VcxyZ-(Utw?`&s@B6Y#FX?bW+!-IqSX27ZJ^)uYW3-JEu9#D
z$4L7p0^*0;omyB%>A%W9x(fDwduO|N^@Un<`zW2*Zt}}O(C1yRLB>h)9EWwOztH9P
z&YS-VUMN%uTSy$uyH|r}97~TDZ$Q1D+e~ZrL;!OTxU5Hevlx^*YQIoIi%OjVDf)`R
zrBOky0>7DS)2eMU^#YAv^qF0)9IR$Or_eMVoTk}7S1`Z#&GzVq>YC~0_bQ9~iwirt
z@de#B6_c-v<TLz8TZb{%T~Me+YofdL7dhwbT6_7kpY7kZ_5D}3UdTHtmuQNyJoY=-
zYBc-Qfm6_Bk~TLprX)YJE5RQ|y}L1Skbk-*?N{P7K#<j?L8>OI(X4Zn!-Xl#@zuE#
zu4^jJc-QLgp49eGN0Ab&SbPW$=@~_u0U#~wek_q}`PONXkRzPZy24O~rl<b%U#9$X
zGvagpf~!1$fCS9Q_IzZPJONXq1j5jjZPh%}l%An*9)f)}h6&FktzxI`=Sha3H<mod
zHyZB^g(sRb^zf}yYOu^T$ICp+S&Rhqf`t3xAZk8wp(IcFeX&64PH?b*Ay1S&ylSr2
z&u|RaCO(DtIo}(`+n+h8!x=8ipLpMR*zBVmp~zKkUab`ac?N-R7Tqo%Yy*4*iTueE
zr0<auI=scs5{4uB-3KDRM<oTVN+rw*&7TMi7f=f_&ML2n&Xf5(7hAq~mkAE+25!+I
z2frc?l1ZywdCFkU5DTJ-0}X+t$nfo|q@*!0OuPzJFDqV^8BA}o_33N{Uk2x^=zXYQ
z?>d%}0C(xK&byAYklOX0Xk-b3*o#>Y$ggsBn+wIxzHk04RaZgXFwYg$?A%&7x-k`>
zEq!#Mj+YhMey1QNaxyq|@Ql!D^M<}r_eMtD*XI^CFNJgS3tyWXVm*zDxQiw7MX903
z7RJbj>2-cj(SuZDIKUXS(ML1+`D0QZ;GlUmXPvO>3+I3x_1&BMHAzF3B4QGQb8sA{
z9Mt|pe_TqEDZbMz+MS?Q7wJ`UyuYy42k<=_M6yA3wT)2Q^C@+3&PJ=QxuI3JIX0&D
zy;X&PAa$8Zb}gk6n1UqETzYEAJtnFkY*<f;(>ke{7T}QXlIQ3losrRWKV5`Djx1D%
z>QGtt$7;drXREW`{m`P7lmkHW)?XJC3B&EoW?UXaEoy*}qh;!V(v8<!r>oP76Px;j
zxRk#S&D9$UKn)d7UTaL1GY5=gI4thGG+1?7HUCqX2^pR^uL6Pw|Cu9o7NCoWLW<&d
z+s<1diiv}`gRa#A<H1#^Ghd-O5ge^1e)OR;>xwlcg3%@;J)-mGnJc(oU!qn>Gp_KJ
z|3Pn~Z%WFMe*6sNn%Kt-WAw2&U&f!{qc?N`I|W;&hKuj^VBiy<3{%u4R1aF29BV@p
zp7PDP?$2k~%q0=gN2#L)X*8VfcMDX^zy<iBnu-3|lzGoq<v%*@mN@O^?*nd;!d9i7
z<<(PsnaRv#x^TWoSqb83$F7IwZZFyMBANww4YdD|k58~?_9u{HB4Jd+(Q2E_sm>Lc
zEhJSd?zt}23+Zs^*KDCW+WXvhJ41`nC_eqw9Ok;ogI>~(D}Issb~#bwSsXpd3DH1P
z29niNOq)R^cWB!9C6?<vP@ldGXPQ4`TO1}Y>f(5vl#}ah2vI)kUf!qth9fO`V=eS&
z_I|azP%V5y#2_V1k$oPx3l7!gCeELn3_elG@lPnZJLJMj0hxPL9XCHEYu(eYONH)I
z4rZ!{4OSj&+Ydx;?zXbV_ElYYJC4}C>zVAI*i6GX;86Ju1AMj6BR`!n{e_VkhRnC;
zCa)Qs@CeoC8TbeJ18jlZ1~p#qn!2Es1}gH*n>Rv}aXty!1GV?bu}py>^wt<#4oqIh
zq8O__b}bJY$RqY_gCLhF<du>|6=3Z{KS;eScT{24UcXEKOvm#)`!s=}Jk(g2*?w&Y
zqZK<0&eD<Ly3=h|uRN_zIzigDjBp=uYf<Xx9(td-nQ=)&wS(JET#JHy8qgXXl$?BI
zhB7UAL*CmLd$({_Y*mIVWvDzn`|j-kT%(3Rwy>DzdY^LgaJY73=)|StK5&kJv#L<L
z6xO4BIhy=dYBi@h^3#~TYe3ptrouKXM@ebCxwK(bY3b=t*HDNWBJRrDyl5Ujfg0`H
zTeXO~`PM^*M?YJ-jJ6}p<X+Cn+WDM@2J^3b0ly49O>Ks+zEE)n70J?*=!njDs5p;#
zc?>_0Y@JejzCz~=IXrb~3qF~kZ4Z*)mcq%Q;?IY^+HUXcs8?M5;m^AMQ|o+BceHB~
ze-!<0L-n6e99-KXHT#ST-JuemxubD-m7!nO$m`Dj^m^@ERdzvWwIowdHaF)ZefQ!o
zMrFggM)!b#_w_#aoUX=P$tW5V!&;q{bT7W1RB-C>c=m&J9(#<3z{?;Xm%o;jm2~Zo
zE~+GTfIpkYz48myiE^#k0-lcA)0{)v*h*xQE`Yq$L)}68$FsQ<oUkHBsWT1D#*P?U
zi^iuUDhAtpdKlP!$VKYe4O=A*>{7p7New~tJLC%KpXEn&t?2*o-{f-ixKmiyAo0^<
zEm|-#qr*=Yx2O2UUb?|s{@2=*;PcgqnR$5gQyVdrFRZOSYGv)X*QW~`(iNV<;EpQV
zM~CJU%XWqX=Gf&~HcRVNQww6ICq*9<Of+gGJ}7hd@d@j@z17}~B-b5cD5#+IY_uBC
zwHMQ6))9XPhvS|+dz#~ym)Uc@w0m*IFn0n)m+`s1{CyRm$r4+vodh$K)zQkAPjS&X
z2hbdMO6!lbOp?9zpQXn8B@Ta&L`&R*ct>IXIu9>cjp7*gTFdZGpi5ON!@91j_;qH|
zuy+glgiw+kCA`L{#D4u;YW3L<TUyQSQ*`{3RGGUT_ByGjZiUC)&*kh#Qv9Q15X&jX
z7HS*QrCZ)=8i-@fs#P`r$CobkA6KByh}*3NgW+%Uozu6hd!(*2GkE+bGZ`3nERW~K
zo!mk<*4!;n70Vd@RVmQ8!A@->#4QrcFuyY4jUHn^_aHFh+&EVA^bwT2`GS2qJR$k9
zs-$SwXK5=j9d~kq@jG==#Q)YAZe<@=7nzw>m!CXW9L+;HW*4<k=1mZ?ZRyS)xw;Gi
zx{Ow>BPZ#CH?JA~T*{B`{N^JA{`ykkqJLxw)K=LS#X(o0$7}6I*ZkfkLxIX#B-HEy
z?IOlUjAD7=4i~7<QJI4m2dNj)5uLoqn3;}}r|azD&9K7QYTQwg0=*a^QlS{&6^GZq
z*|&{8_n_!fBvUqt`+7;-&InfrX-u}MqFx~t@-*;_!tUIELh`KwH3i?j!)-qWg)lLA
zQGf<`#rO*MRTX-Y>WHhABQ0G)cPEQgVek<>^_K@)U0r&KI?;)QpbiIBjxMyk>1VS`
zp64hVHQv<HWJXY>6(Jk1Z&S`Cx7rU1z7e1$qO#yuLh|>#GP#x-NOdL&Hi{7Rib^hV
zse9YQ^l|8hTvH@d+mZfH)kI#a34IP-{fX>O=ukAJ#c6MpyRF=(-Q0@i7wEDj2_;mi
z>1+FV0wbND%{t}Zb=LpTPeFUo7bq(U86XM9PQPOSBo^pJTWjnF76my(-q?+8lBtT)
ztF6e}9Hb;EK-D!U*ob+^c;M`@V;)$YORJh-+no-hG0V>A%@PIXIRFZI$ooQUBx<s@
zTzdr+pC#aRlsLcjXe#A(n`~M)nU#&jS!|g;q%Q({`RSIxeare2s!}h>p?<ytDA{Wf
z!Zrh57eU_hKQkO(O3;(sYYOZaZhSoB?e6u$$cB&48J)AkfSN{cJMp6{m}UJrDeho%
zWE6d$x<5So_43DJ&qIU_AHDv_tcc`eilf_4n57k*O&W``f(pxL?xS>&e0dj9J$FH-
z1wR~9KF(zLCEVp)Sz-4_Ais7cQAwLEVBUQGHosSQpWpE#7N@^07pS3|zi7R$UeTmx
z$uxYR@HkPpTeh`&T2BmeCp=ZTXo=5yJNv6{Ne{h!v&5>#btUA9rh4@zE&;#K|9b!t
z3X;>G`VZ(Df0$xRPd5hUq<(d&gbkPzKbAFPSHURAi%Bezo-plPNy_6)H6UeNf$dv5
zzJ-a(I`7rIU!rbsVi5`)CZlFWgPZ$J>iyP4A!V?iVHrFfqG9g>p0*A<GG(OjQj1<n
zQX0+|r8l`{P1<I~XWMS9lQ#rzvLN{Glc}&=ozWu6JxLQ(ul6VYe(q$Fla0Gh4?~+;
z)aBL0I{RBMkjW~dW8q~<RYOK4VuvkP*^r8Y7az)Pfe_QVP%D3datDujhmfQ`JlWE3
z{)_XaBA?6QNG%%FoHw@~N%U-e*<C;sRGHhBKo#9-<!u8Kpz!Py8YJz+HHp3B6Tm0&
z{WPyGNG&?Ux#jI^aK@t6FmrKbF*oR1XR+_<)QLf&z#L_2k4v%6l>+pHWIC0Kc448W
zp%tqtt9HZ03G|T%kELRxjV75sdJyeURB)?qm-=eI-1ad=ymP!?_`~?&AvaK4OuGt&
zcxbVD#uWKGRlTnVGaw__iRyxsdBh#z*N1YJCJH86ncT!}$+7i9;i{dBUj&L^W)Xvu
zyJb!PU;z{hgKD6U6UC;t23>1aLk9Iw1t{w&a}^>2uL!axe`D0a<A*dx8-}QC_KktU
zf=MvbFVK@dqS@w{Ro{}xJGr(pG=@CXBB7a6u*eP*MOCvp{-`=uVo-*}MOai9p-beW
z_q<eYh)kCZureE_?$HMfQCpp6LnpuWQvrHSoURXeFQWGAGw##aMqd*)pRXK#bBb6V
z-+K9lJ0ZRqK2z&f;D|1{!YSkG+_EA)@cd)>wi?WYcRMuy8Cym^ea|bLDFD@{?qt*c
zLpS-~v6?PgwFj*h<%2*a$1T(kTlOG}>>H<SygxnQF<j(8TbCG@ZrgIV?xSE1DGkp<
zM$n(H(>69Py!?NEt4mzUj)#BP1OoV|Jckj<YwF#Zlu5qbOVRo7ryQB+!E-ZRU9~4{
zL7?#+pZcbzJbOD^o-Nl^-V~w4uRhZfGKyK#p5bxuzHdO$nCu{pDf}K2*=fMhJS%vY
zY}c@^L-S7PiobvCi1_mJnWw3u8^@u|*>xee$$$<MD?WsYvo>8+vEh`I)N*##gZBB0
zq>lj;j^mr2G4Z!%z|S#CxdznwBi+;)ffz8zK?Rfc=LqtB=VE5&-N%fW@7)7Druub1
zVgjP0SyR=yQhTUK%)=-J2wqs@PM^h=Jm#d-k25$9`J_MQt(Y(rM+h2ME#3wFQxAz%
zUuVA_(Oa`zpuWU_f)e#0$5}J!qeLPwOe+o2So3&xCr~A1=s|7e+%7WP4GOJzm55-E
zOzq*9ZiFB+5YkNjsy9NgL&ORTaO1zJL{0^_H7gi}4^`rjaC<}-1Gmzbc_R*ih4m3o
zB?%6dSc(HI4^Cn!-X1*I$@K%4)f}r(RX#gMK_}Y}v^uR{VESKO-Gs}HmwBO}%3+`n
zD)BpUzf^^WC666^f65^aGbp1AxYn?PMkCFJF-l~w(qU*_z(K36cqjauQ4Ar-h}iR-
zM;wk&wnpQKF==DG2D?+MRbZv2*<~)^LP=S9l}*`a4WVPHiqkSyv021CzWlAnl`0@O
zq{L^ftoyLmj-DMa`>huRVl_zvn|m}9gc9#AFS{9YY{bW8H8Q*SwO>5~>Rr5^*3L;t
z&3WXjgVk@UXD6Prso9J4EcE9dpEXNJ!j(ZT1H}rI#P7nsB!p$lnp8<ay8>(;^5Wo~
zxQ}BS3V`WQIuf;pm1fd)?`|591(HEH<DE3~-$gPCON_b)rvq5?d5(~XdzUI8?LX!b
zY}TQw6oXcTA??P(Fc&QSznx$Ft$l8SC?Q`+_`pq(yDd)pXQN`bemD2ky5ah__FrES
zIn4<A*@N`X9@CBWZ$j6bl8XvE{u#FaEFFQx-|w#_%mumPFR**0fknXw2aBm^x92X?
z_-}@qV6T(njo|#v5}gyR*L1f*cX?bmfCi3|=Y9BgZCGX$N6BI}qr5GTgj-i*udCUP
zDy%qJtjzKiYv7CTn=Df9zOD`?^!7Q~t0eiSF307!{iaE4-rG3V^4|`LtzsoZy&tF$
zl0b-$skf#`j;(7D(SI*{E<nK~<vrr-twsH=pd3;*_WYuYL2|CO4X6~ASUS3@*_)W$
zISRXE8pZIQVS}7+bGy}a)lZg7phG4<I0t_y`j`vQ!_ltv+<Rb>`3Nyc;rrcd9J@7{
zc=@f(AK|HNx$kkvjCB@BUk=y*rA3Y4c+iKEzSeDKy1Bw@vscl(O9BCBn-;|mj`_5*
z1G2(1PsY#B{3pH{Nb#e`f8M6mGtu16t_c|)zFtu=FMX?QclWGj2_E$_!0Uz8+L!24
zT4s<0N8%fEmRpdS*%{j4i?Hvm_;%sOKj#zqT$bFS`nyi98bUl`B|89LrHck%oum%&
z&@<yt-f8D=D?-(t9oFx*rpzGKwPrWWtGlc}1rB7Ulu}W_Ye%^!T82$~^?2R;1O*M#
zX4#N;KYy6wpFx5f$1nOY0QUFm^bw$m@8qp7nan`I`_6+8L=f^9^+oW8N!v*ynVReL
za69YUL7rR#?SyU0OkGF@M$weiv{HTn@nt1zniBF~7iGsH`pII<Tc5Q0v#;kjS1p42
zs;r!!xM~-S6&A|=ld6-Dt8CGcX;&jwZ|N6=pGNHUTvG95#WN1@JY#h`+O?=ZJMd27
zpT6!0KkAb58$6Fb<`S|P5FMbl@gx;$#3xD0pN&G%RZT(HP8%Xg-BVmP1A*5gr1Cz2
zt{y{raO1vq!YwO?12c*2oCc8}zGt?YHovQcLNkN5{T2x9tn4hafVe}0-<ReW1r|l;
zP6jpNLkU8y!<wy=9fgjIqWG5=FN4n`ncek`JDSupD3Ww<L7dg_shhoA2!k@gq1(;g
zXC=kEU2=%EJI-<q@-~09ei0l=3?Qcs)$%kn^%C|J;WW%d;Nx&GcaFx{=kBA44e$bk
z=aT{U;sx}h%Q-D-Qdnf@?eQ+)@Ak<yrOzO#lR-F=;iJcPK56z9bnsy#{kxSe2-e3U
z<W(^RL&XJIB8+zn!njkQ>8F*>2(a+!f6G8GfVZd+yCSMosL2fDqi59jk;=sLOr~I8
zq+SEj<Z1rhf72y<Y$ZRqG^yE+AAGMZ4yyyLDA?JUU|`2}DY%MG$!E5V)vr=|m*k(d
z<FKEXqD_REy#>efF)3&CS{?4L7=Z~Z(mGL=atc+0!VB;{&!FMxs8PRA6Kb;6*-}H}
z$2P+AJNZUV25_+CSY|a6I|PTx*TTy7C!UvD_=GUo60#J_`mX!+Bn0Z&Ae*G$%S}rN
zH;PHj_&EfBUrgesB0GOlbmnyCpasY)9Y}r%G~jfYAiQzg3d%uc&Y0etCg|CH!nl)S
zdA=S&&7Fj024Yv0u@-AR^><4JGOHeX63!f)a~Zh9O!^2};mLcS%2nd}W*#!h20Lns
z5{%nP{E@g4-jSE97~I$XOA)BP`}$ikiElkY?{Gu+M6#vr*IZ05ju!b=iNX$FSq2`1
zrFoP)R|?1rJ^n7xd^%6a0~DIIUZsRTwWaH_hxte=3dfPNsp_MY@>f>_@qv3u)yQPX
z=-~QQt(?iG2FQ#4e{4>N0n4SA@<HjQq)};6qskCU^rlHegq59`t5;%ugPG+I?gcd}
zw75+<T6>e?vJ*G8fP_+|@KalBdL}=`E98wSy<y!5&Mi(Pf(<0&-$*A~|F`B+kT|G4
zE>)Y>pvoyux!(H-?2FRvZ|{hLWua~DJVf>?d(FPtvKoq(#&~Pw2s)Cv>)-NB>b&{7
z<Q>c#mJM8e#76-~q3Uy22K_o^IX=K#_9p1P#g%G1_0hldj{WaR)!!;iNrIntVFrRG
zEKTWst~J*UV?X-<;pObp&yuP97E|@kt_~5ar*XHL>#uegFt+a+xdCOvt};2`VtCgL
zm1aWWyRUpB;l&RLQ7PZ;Hy#t+gR3n8mopY8nMYgcThdqW2iDV=%tn-KfcBTL9YP}Y
zb)ZQR$w5!z2C9?`t>8r9Byb*E7@P#86~>c1D!#%yH|?%bCVD5~m(^}T-6NM{#ash`
zn-`wsc|$D{0Y>`PW;Tn3Ie*Mig++tRu-MI_%|g$lTohS1g0|a*ZIXRim9w3mdRE#-
z(AMDi-MV%(5)+qnFXw!|b`jIa)&bMC7^{a`m@QyUowI!<Dex?QN2G;AQE#F0lA=FM
zCnldF&>ffIBPN%9RlATR#-Jlo0AYFv^};n*I(C>Xjjh|ZksGZ`<_(*pwbXr$0puC}
zb}cn|Q*yEi^gHI6-h%yIh?2DXGeCwKUpS#|&jUu!O<4-?diO#Px?&9A)v`GknU3(L
z>T<hZd9^^qMk=)_zc71M3SnZZ2U9Nn128V`)0gMoGD;;|S4Yxq>6YMP&&iAK>6M5#
z#>p<3r7_jJDCg?ImLrJb%w^aW*(eQ#V2r8=-ij{<bAf-j(msyM1AWpPyJbdh&NX%Z
zT~t9#+I3q&jAA1QpB@7z=Nz2=6`THf7LZ=*6%ZI1+{3#*W_)E}e;vF2nRppZGN7`A
zrH49d0ciquC6w?5lAcN<Uq=ptQZ4H_i;T<|S?FXA;;KnTBX!6@qeZ_G6lJ9nv|aE+
z6F`bsTGtg`cRyA;)-uSp&GGr2(<UI;DfZ)Uh`pGN5<lHQ9BJ>wMMDXJQ*2k1)R1rD
zZypX(0XgQ6h36FlnlTz?%^z^KQT992Nf{<kJ*e@+`g!;9OD%t2OZ6kzh!?Or*R;M@
zB(>Q`1CicbTKkHP_I48Q?6IY$=?q_=Nj2SfX@f><B1G({Z#Z$^25nY7m26n1RVG5a
zha;T<Pjf20ZTUy^lzYg=BfT-Ba>;NLBX!F!Vr7A^-dr*HTpOBwa#VUQBbyUo&X>n8
zvab1UbSg<Z8mg=3aWXM5yopNON6yR~uuJCaoHJi1-zN)y`xKJ$`gpcC=n2yO`!1QU
zEFQVPto1PhHC9ty$ay>DkUxM!Cn*{_{YF~m?-&__S|6>N;xqNq7pt9<ISw+5K=PFo
z>(op$7TzvDk~w&TxsK8(uN>gm;iHRv_l$tWQ?ID|Br6WL3D`f+=B`4=T>10JWeyp!
zgKVF_Ha7$A)}aJ(c<NvU?q*Mr5Zs+t4~eTF!E!bBZlp4TM(qd()b}S-i^Dkwg_9M9
zpZ+GyBZ~Q6=^OwRZhRY3!maQa=Y=PLYpAW><aoo&T*OC$O)OqlY}P|POeL|8Ekq>_
zr86{(LC*FXx2Oe~hKx353t4gBQAE!-mO?y^Ce#qh&khAj2u8ei3Y5*f(w9?Y2KYd2
z%@b`5Gq9T)hZg0wE&A%HAUb#iQ}9)R>K_k@Z@~%*D=h5fgSw?8ljs!?$WTn~=ofCe
zvn$C0)`XB?pyIS-N;>0+rSOb)Ssj1$malZG5ok4|PeTUSy{z^+&R)OjndW<U*}}lm
ztl7LMDBF4IROIgpZtQha&&H4d+!s)BfX57ZXncN^{Mi#}W})W771*w+yrCUMctdef
z;q{CK%#$5_M=X=PTHU%>*ViuK9rD#^7Y3(M=qIFOkvLY9M*r!toMKf$oa2TADhjrN
zzp)`<LeHXQ5t9De{s_Gn!>Q)I)9FnH#hVHVYKw=HZ%3n4Wv8iR(PF(-OJ7)8g|bvV
z?SZV>-*1(rwC2q=gOa4ji=HGSx@+O)Cv|$^;;CzHM{|dD9FwPL&NNxyHbB%5qf`Gh
zO)*3u4o|jD&i!*K#W*@yue@OP0cezX>|aIb_%w=OV1EIt-}?yspJwX+(WocBlR{Fs
z-Ciy%m}Ns}Y3vABgt)GPH=l!EoR3edF8J2NxRQE&jZt15b7$8?AH))`7~(rajWi-w
zn^tH*MpecM9E%9P0u68;ErpYA1WKduJ^#W>8Jc)ylo{jan{Cy75gef=yoOwG<%|?X
z-r5Cd$DUg^7oe<DwgV3dBkbpdukMgolkyKTlM8ZLiXu916H=aWMTh+hmE8M?7uIFt
z+_Z<Ya;Oe?5P}LF#??SFML&wuy4i^Zp$jyV^qg_u2>!6mV^c%x>k39<WfD1b)szJx
z<e-ODtO*=NR}Qz_5A!@CvpEaQ%3%OsNhFKNU)l>wIZ#zlFV@RDC2C7)SAns`*PNY9
z@(sH2;rIY)U*|+Mk-v6@4dI`s?f7?6^ElCp#Mq0vOHaRMbuS6O@YPVRYJm|MzvaJX
zFJuIlT;Ge0EO)w9E=%-6>GiR4J)26w7d_*`A-iOH>SiN5BC}QYPA;&;@x=4#S6%hJ
zph`}XCdvK%UOw1NOI*1MlqWfAVS^-V@W<W{or)3j;SuG-qzS-k!(jP5o=K>@l*Bhc
zQoioT<q~h!#JJa|PT{KiWJ*IS)CejeN$OZW`?AzMH>~-SAdK^0wwVp%>ze42WvsMH
zzxmM<ne}Da=%b6jVY4=D{uZHQP2_|vkIb(lsm`qhkGZ~y*MDW9i<=698k{5CifS6m
z@>~4yTL{%hxS;*}%eVUe0v0k)<Ap5sveCAB`u;uBKUK$BwtUv^G}~=wd!3~>cs+|y
zwkwJG2QI8N{^aGnp(K)=mJz?D52xUU!q!|OZG?$v!#fuhK2~E!VTRaqys&0MTxyq4
z^FCLsr^W#3ylMx}@x_pv?jR2<qd9$6VreqgpJLz~Z2$3aGE?;O3*WYw;9$9~%1}>5
z9Wa3UBr`5O(gQYI3eF?tE2Z+mt8LsYbaMWjKk+WHjNeEue~iBu`srPFK6jz*EX<2V
z;)$zNmeV2hN>90FA|pwXaRwv_w#M#R$`w5aV5w9(Pz?mo;ZP3;9#ZVzy40%mbTBE@
z>&4G$n1$xN+VA#+=XuKcq0mK7){e@8^-BH}V+=gmw6K-N2`aLk_SgvhH!8K=ZE5_A
zYX1y;$uY?I<a*y8#@uJdQlr%mu|yByfW;$UbIP074XAHM7u&5D<;nDPc|LTl(|Tx~
zxb@I`t%sE8wh_a*!W;OwpdxPiy9KEOm|jp@*bNn!0CUnzmKsJCC*G<k1R#T<`z4h>
zpd}&xgDK|O8@fHQ-J%GwC{$<AlNu2cs|&v|iUlwys25nUJ9cK=pYKouZSlBR0Jt!E
zYU65@?T~}mww|C8^<xYcVJ5)mGNmH$DJzBMXN%!UPa|qxRi;IDgXyJ=mU<5Xz&2Ub
za8xL;qtlc7Y&s7Hya`{Z%>x>S4=dZ(o1^D3cEom4uGt(QU5S+zMmDDSdsUebS5{^9
z2o-LE%2#<#)QX)mYy`@>kttCrj{Zz^H^*5ee(hLC_AkCLdV#ix^os-1dMWTmk2b<B
zF$SMwk?d787u!43o{?Fu-ghcDCv{GG`v<J9^W{7XVH_Zb$zKe7T=&{I-vAXG-}T+v
z9UC4-eqDGI(m@Yelvro3NWKLW0qH>J>%X$kQryd0lH6Ibi~RW@X)Ta)1huq$6~PW#
zaa?dLN~(Xvb)M#AGZ<Er4Xb~*cmbN~cr`~XpFkezkO&vZ&~bjsOyI!oV}AeN@)r&Z
z4yB8rdS$@<O%<V#7kd);J7k$3GK>~R{!VHRrfCqQ@<U%=BrN?gGU5&Z%a<jk2UFXB
zi(-x~<>!9Xum@V9K%<(5Fq9ClyOzev@2IDOQ>~|MU4S<?_uNAC3BilT#pV6|xblMB
z+{(_ZBBK^nibdC{U-v!T#+al_#A$)wJytYzK+AfFEgejRhu1YpHd)NmOR`cScelk2
z#*)1~Z$IxZo})eTTe!h2b`!*(gw_K@L2DkAx#Q|mvcH$|o$v$br+w?%zbeLr<!C$_
zJ-*R|n&|84^BX!GeQN+!GJSh_L*HJ3Io{n(<fqG5Hh%d$2mN^k(S1R1m>D?T46MuJ
zL#I`FGX$ZtdQZG$Az4FD%4CMH+u-@!10~24z>?3N+d}yN)Vus|)+hft^zVuIzj@35
z=g_}w&hbA}p#Kcce+K8DWRd^9hs%F1lYi`H^Z)BeDE(;3$5GFSYfvp>ih1rtrcO6g
z>;}R><3v8$joh`|i_37$4h^2TD`1%gy1u5EtKI`X5dB_n5rSTN1q@}r`bGpC0jViz
KDV8g|c=KQNfk=`7

literal 0
HcmV?d00001

diff --git a/docs/frontend-architecture/handbook.md b/docs/frontend-architecture/handbook.md
index 103e02ee9..ade3bec14 100644
--- a/docs/frontend-architecture/handbook.md
+++ b/docs/frontend-architecture/handbook.md
@@ -1,9 +1,10 @@
 # Odysseus frontend architecture handbook
 
-Status: F1 foundation and continuation guide, pending review. The final Notes
-reference case study belongs to the comprehensive Notes draft PR; the recipient
-handoff follows its integration. This document must evolve with reviewed internal
-checkpoints and distinguish executed work from proposals.
+Status: F1 merged in PR #6701. The complete Notes reference is implemented as an
+unpublished review diff on `refactor/notes-reference-decomposition`. Read its
+[case study](notes-case-study.md), [module inventory](notes-module-inventory.md)
+and [validation receipts](notes-validation.md). Publication and the recipient's
+post-integration reproduction remain pending.
 
 Read the [ADR](ADR-001-source-and-deployment.md), [assessment](assessment.md),
 [validation report](validation.md) and [Notes roadmap](notes-roadmap.md).
@@ -90,6 +91,13 @@ existing objects and initialization timing when extracting a stateful module.
 Do not instantiate a new store in both the legacy facade and the feature API.
 Compatibility facades only forward the same live implementation.
 
+The Notes reference uses internal read-only live views to preserve captured note
+identity across existing asynchronous completions. Its state owner supplies all
+mutations; the public index exposes operations without the store. Notes deliberately
+retains last-completion fetch ordering. Do not infer request-generation guards from
+its decomposition. Its page-owned reminders survive panel closure, and panel/editor
+listeners and observers have separate disposal scopes.
+
 Document lifecycle scopes: page, authenticated user, session, mounted panel and
 editor/draft. Name owners of subscriptions, DOM listeners, timers, observers,
 pending requests and caches. Mounting must be idempotent; disposal releases the
diff --git a/docs/frontend-architecture/notes-case-study.md b/docs/frontend-architecture/notes-case-study.md
new file mode 100644
index 000000000..cc1a28d7e
--- /dev/null
+++ b/docs/frontend-architecture/notes-case-study.md
@@ -0,0 +1,260 @@
+# Notes reference decomposition
+
+Implementation started: 2026-10-13. Final validation: 2026-10-14.
+Foundation: [PR #6701](https://github.com/odysseus-dev/odysseus/pull/6701),
+`1cc56cb9d78f3e2399d1d61155b71d771a17b85b`. Branch was safely updated via
+non-destructive fast-forward to latest official `upstream/dev` at
+`86b886c611338282af6d4a717246ea4e256f58df`, incorporating PRs #6704 and #6693.
+Neither changed a file in the Notes diff. The independent AGY audit returned
+CONDITIONAL PASS; all pre-publication corrective actions (issue template conformance,
+PR template conformance, visual evidence paths, and em-dash removal) have been completed.
+
+The entire implementation belongs to one Notes PR. N0 through N6 are internal
+checkpoints, not separate branches, commits or PRs. The [validation receipts](notes-validation.md),
+[module inventory](notes-module-inventory.md) and [changed-file inventory](notes-changed-files.md)
+accompany this case study.
+
+## Responsibility map and size
+
+The original `static/js/notes.js` contained 5,471 lines. It mixed mutable Notes
+data, view preferences, selection, undo, CRUD, date calculations, reminders,
+browser persistence, editor autosave, rendering, canvas tools and window management.
+Its import evaluated storage preferences and scheduled reminder initialization.
+
+| Original responsibility | Maintained owner |
+| --- | --- |
+| Completion, tags, recurrence, date labels and serialization | `domain/recurrence.js`, `domain/noteRules.js` |
+| Notes data and selection/filter/editing state | `application/state.js`, instantiated once in `index.js` |
+| CRUD, undo and fetch completion ordering | `application/workflows.js`, `cardOperations.js`, `deletion.js` |
+| Checklist mutations and rollback | `application/checklistOperations.js` |
+| Editor optimistic submission and recovery | `application/submission.js` |
+| Serialized autosave and synchronous backup | `application/drafts.js`; form collection in `ui/draftEditor.js` |
+| Filtering, searching and ordering | `application/queries.js`; controls in `ui/filters.js` and `toolbar.js` |
+| Selected-note attachment and bulk requests | `application/selection.js`; controls in `ui/selection.js` |
+| Existing agent-solve workflow | `application/agentActions.js`, through supplied HTTP/session ports |
+| HTTP, persistence and browser notifications | `infrastructure/http.js`, `storage.js`, `notifications.js` |
+| Background scheduler and delivery decisions | `application/reminders.js` |
+| Panel mounting, closing, keyboard handling and navigation | `ui/panel.js` |
+| Docking, fullscreen bounds and stacking | `ui/windowLayout.js`, using existing shared capabilities |
+| Cards, card gestures, quick add and masonry | `ui/cardRendering.js`, `cardInteractions.js`, `cardChecklist.js`, `cardReorder.js`, `quickAdd.js`, `layout.js` |
+| Editor types, colors, reminders and checklists | `ui/editor.js`, `colors.js`, `reminderPicker.js`, `checklist.js` |
+| Drawing, local drawing undo and PNG upload | `ui/drawing.js` |
+| Mobile reader/editor and reorder gestures | `ui/mobileEditor.js`, `mobileReorder.js`, `checklistReorder.js` |
+| Clipboard, safe rendering and reminder display | `ui/clipboard.js`, `text.js`, `reminderDisplay.js` |
+| Owned document/window listener disposal | `ui/lifecycle.js`, with panel and observer disposal callbacks |
+| Composition and supported exports | `index.js`; five-line legacy facade at `static/js/notes.js` |
+
+The feature has 41 maintained modules: two domain, eleven application, three
+infrastructure, twenty-four UI and one index. Source is counted once, excluding
+byte-identical deployment copies. Domain has 356 lines, application 826,
+infrastructure 112, UI 4,628, and composition 518: 6,440 maintained feature lines.
+The module inventory records final per-file counts. The legacy entry shrank
+from 5,471 to five lines. Interfaces and explicit composition increase the total
+source size; reducing total lines was not the architectural objective.
+
+One 28-line stateless confetti renderer also moved to `shared/ui/confetti.js`.
+Notes and Compare both use it. Compare retains its existing `spawnConfetti` export,
+which is the same function as the shared export. This removes Notes' import of
+Compare's private voting implementation without migrating Compare itself.
+
+## Dependency graph and composition
+
+```mermaid
+flowchart TD
+  Legacy[Legacy Notes URL and window bridge] --> Index[Notes index: one composition]
+  Index --> UI[Notes UI factories]
+  Index --> App[Application workflows and state owner]
+  Index --> Ports[HTTP, persistence and notification adapters]
+  UI --> Rules[Pure domain rules]
+  App --> Rules
+  Index --> Shared[Existing shared UI capabilities and maintained confetti]
+```
+
+Application modules receive adapters and feedback operations as arguments. They
+do not import browser infrastructure or DOM views. Pure domain modules receive
+the clock at the original read sites. UI consumes a read-only state view and
+application operations. Composition supplies callbacks between views and workflows;
+modules do not import the coordinator back. F1 rejects maintained-source cycles.
+
+There are nine exact legacy-import exceptions, all on the Notes index. They bridge
+the existing UI, modal, color-picker, drag, tile, dock, stacking, Escape and tour-hint
+capabilities at their existing URLs. Their removal condition is migration of the
+corresponding shared responsibility to maintained source with its identity and
+lifecycle contract verified. No new feature imports another feature's private internals.
+
+## State and asynchronous ownership
+
+`createNotesState` is called once. It owns the Notes collection, selection IDs,
+editing ID, search, filters, archive/view flags, loading and dismissed-reminder time.
+Neither the facade nor reminders create a second collection. The public feature API
+does not expose this store.
+
+Internal views are read-only live views rather than detached snapshots. This choice
+preserves captured note identity: an existing asynchronous rollback still acts on
+the same captured note. Array/object writes and selection mutations must use the
+state owner's operations. Workflow-local undo queues and serialized draft promises,
+and UI-local canvas undo/gesture state, are not competing Notes stores.
+
+Fetches retain the original last-completion behavior. An earlier request that
+finishes later can overwrite a later request's result. Tests pin this behavior;
+generation guards would be a separate behavioral change. Submission also retains
+the original first-temporary-note replacement rule. Multiple simultaneous creations
+need a separately reviewed correlation fix, not a silent change during extraction.
+
+Archive, unarchive, pin, item edit/remove/add, delete and undo preserve their original
+optimistic ordering and rollback. Animation callbacks remain view-owned. Drawing
+save keeps the existing button guard around its asynchronous PNG upload. Draft writes
+are serialized per editor; a completed older save cannot clear a newer local draft.
+
+Reminder scans still use the originally loaded Notes collection, not a second
+all-active cache. An archived-only collection or a failure-cleared list can defer
+active reminders until an active refresh/reopen. The timer remains alive when the
+panel closes, but extraction does not redesign this inherited data-availability
+limitation. Review such a change separately from scheduler/state ownership.
+
+## Public compatibility
+
+The import URL remains `/static/js/notes.js?v=20260911notesselectioncancel1`.
+App, Chat stream updates, Chat note links and Documents continue using their existing
+imports. Calendar and Documents retain their window bridge calls. HTML and app
+bootstrap code are unchanged. The service worker retains the exact legacy entry.
+
+The legacy namespace still exports `openPanel`, `closePanel`, `togglePanel`,
+`isPanelOpen`, `openNote`, `newNote`, `refreshDueBadge`, `dismissFiredReminderDot`,
+`openNotes`, `closeNotes`, `isNotesOpen`, and `default`.
+The default object's ten methods are unchanged; `dismissFiredReminderDot` remains
+named-only. Aliases refer to the same functions, including those on the default
+object. `openNote` and `refreshDueBadge` remain async; function arities are pinned.
+
+`window.notesModule` is exactly the default controller. The canonical unversioned
+feature index and both tested legacy entry URLs share the same controller and
+operations. The default object retains its existing mutability. A different legacy
+URL has its own ESM namespace, as native ESM requires, but creates no second store
+or scheduler because it forwards to the same canonical index.
+
+The canonical index additionally exports `startNotesBackground` for explicit
+activation. The compatibility facade invokes it once through an idempotent start
+operation. Existing consumers need no change. Remove the facade only after every
+consumer, global bridge, bootstrap and offline reference has migrated together.
+
+## Protected selected Notes/Todos integration
+
+The sender dispatches `odysseus:notes-context-selected` on `window` with
+`{ noteIds, accepted: false }`. Dispatch and acknowledgement remain synchronous.
+Chat owns acceptance, its session/pending selection, the context indicator and
+the `selected_note_ids` send payload. Notes exits selection only after acceptance.
+Rejected selections stay selected and display the existing feedback.
+
+No Chat internals were imported or changed. Existing session lifecycle events still
+transfer a pending selection on materialization, restore selections on chat switches,
+and reset them for a new chat. Backend ID validation and owner filtering remain
+authoritative. Unit/backend tests cover these contracts; the real authenticated
+browser probe verifies rejection, pending-chat acceptance, the actual indicator and
+new-chat reset. Live model execution is not part of that probe.
+
+## Persistence and HTTP contracts
+
+| Key | Preserved format |
+| --- | --- |
+| `odysseus-notes-view` | `list` or `grid` |
+| `odysseus-notes-labels-collapsed` | `1` or `0` |
+| `odysseus-notes-first-open-hint-v1` | Existing first-open marker |
+| `odysseus-notes-reminder-fired` | JSON array of IDs |
+| `odysseus-notes-reminder-glowed` | JSON array of IDs |
+| `odysseus-notes-reminder-pending-highlight` | JSON array of IDs |
+| `odysseus-notes-reminder-active-highlight` | JSON array of IDs |
+| `odysseus-notes-reminder-dismissed-at` | Decimal millisecond timestamp |
+| `odysseus-note-draft-<id>` and `odysseus-note-draft-__new__` | Existing JSON draft fields and `_ts` |
+
+CRUD, reorder, upload, reminder firing, default-chat lookup, session creation and
+chat-stream requests keep their URLs, methods, credentials, payloads and error
+interpretation. Uploads retain `files` and optional `gallery_id` multipart fields.
+The agent-solve stream still disables `manage_notes` and drains without switching
+the user's chat. No backend implementation changed.
+
+Storage backup failures still warn once; failed network saves keep recoverable
+drafts, including intentionally empty text. Draft JSON does not serialize a canvas
+bitmap. A drawing remains ephemeral until its explicit PNG upload, as before.
+
+## Lifecycle scopes and explicit corrections
+
+| Scope | Owner and disposal |
+| --- | --- |
+| Browser page | One reminder startup timeout and interval; page termination ends them. The reminder factory also has explicit disposal. |
+| Open panel | Capture/bubble keyboard handlers, reorder listeners and masonry observer; both close paths dispose them. |
+| Editor/canvas | Local DOM handlers and draft workflow; drawing's window listener is released when its canvas detaches or the panel closes. |
+| Mobile editor/gesture | Overlay and document touch handlers; owner replacement and panel disposal remove handlers and reset registration flags. |
+| Menus/hints | Notes portals close with the panel; shared dismiss functions unregister their Escape/tour lifetimes. |
+| File picker | Existing completion or 30-second cleanup owns the temporary input. |
+
+Two implementation corrections follow the user's explicit lifecycle requirements.
+The original close paths canceled the supposedly background reminder interval.
+The new page-owned interval survives closing/minimizing Notes, while retaining the
+3-second startup delay, 30-second period and immediate first check. Closing a panel
+also releases owned observers/listeners, pending hold timers, active Notes gestures
+and portals; late panel fetch callbacks do
+not recreate UI on a detached panel. Network completion/state ordering is preserved.
+
+Shared drag/window utilities continue owning their own active-gesture handlers.
+They were not moved into Notes. Idle open/close and editor replacement are verified;
+every possible interleaving with an active shared window drag was not tested.
+
+## Source and deployment
+
+Every maintained source is registered in `frontend/modules.json` and copied without
+rewriting imports. Notes sources map to `static/js/features/notes/` at the same
+relative paths. Shared confetti maps to `static/js/shared/ui/confetti.js`.
+Repository-owned LF attributes and byte parity cover all 43 maintained modules,
+including the unchanged F1 proof. The legacy facade is an authored compatibility
+entry, not a second implementation.
+
+All new outputs join exact service-worker precache arrays. A real offline test also
+found eight previously missing exact legacy URLs in the Notes graph; those entries
+are now included. The eager Notes graph has 57 exact runtime URLs. Cache naming
+follows the repository's `odysseus-v659-notes-reference` convention. Root offline
+reload remains outside certification because the existing worker scope is `/static/`.
+
+Python startup and Docker serve the committed static graph without maintained
+source or frontend tooling. The publisher is a development check/copy operation,
+not a runtime compiler or an atomic deployment system.
+
+## Checkpoints, rollback and lessons
+
+[Checkpoint receipts](notes-validation.md#internal-checkpoints) record the actual
+checks and local snapshot hashes. These intermediate snapshots are engineering
+evidence, not standalone release artifacts. N5 includes bounded editor, cards,
+checklist, drawing, mobile, toolbar and window reviews on the same branch.
+
+The N3 mechanical state rewrite initially confused canvas-local and feature undo
+bindings. The N5 drawing test found it; the canvas binding was restored and the
+same drawing/undo interaction was replayed against the original implementation.
+Use scope-aware transformations and test each stateful UI responsibility before
+accepting a broad rewrite. Source parsing alone does not prove semantic equivalence.
+
+For rollback, reconstruct the prior complete artifact from its revision/snapshot
+in a fresh temporary directory, run parity/graph/behavior checks there, then publish
+the matching static graph and service worker as a unit through the authorized
+release process. Restore the whole facade/source/output/manifest set, not just
+`notes.js`. No schema or storage-key migration needs reversal. Do not reset a dirty
+worktree or delete unrelated outputs. The validation report gives a non-destructive
+snapshot reproduction recipe.
+
+For the next maintainer:
+
+1. Start with the module inventory and the state/workflow contracts, then reproduce
+   the focused tests, offline test and isolated native browser probe.
+2. Review the explicit timer/lifecycle corrections separately from unchanged
+   business rules. Inspect both maintained source and byte-identical deployment.
+3. Resolve or track the reproduced upstream CI failures and the open PR overlaps
+   before authorizing publication. Create/link the dedicated issue, then publish
+   exactly one Notes PR targeting official `dev`.
+4. Record the integrated revision and independent recipient reproduction to complete
+   H. The designated maintainer can then apply this method to future features.
+
+For Calendar, Documents, Email and later monoliths, characterize actual exports,
+URL identities, state writers, clock reads, I/O and lifecycle first. Extract pure
+rules, then adapters, then a single state owner/workflows. Use explicit callback
+ports to break coordinator cycles. Split UI by interactions and resource lifetime,
+not by arbitrary line ranges. Transfer source/output ownership and offline URLs
+with each boundary, and preserve source-sensitive assertions at their new owner.
+Those feature migrations are not part of this implementation.
diff --git a/docs/frontend-architecture/notes-changed-files.md b/docs/frontend-architecture/notes-changed-files.md
new file mode 100644
index 000000000..02f916e46
--- /dev/null
+++ b/docs/frontend-architecture/notes-changed-files.md
@@ -0,0 +1,165 @@
+# Notes complete changed-file inventory
+
+Changed files in PR #6713 (`refactor/notes-reference-decomposition`) against
+`dev`. 121 files: 16 modified and 105 added. No files are deleted. Deployment copies
+are byte-identical to their registered maintained sources. Image files are review
+evidence, not production dependencies.
+
+The unchanged foundation worktree, backend, app bootstrap, HTML, CSS, dependency
+lockfiles, Dockerfile and CI workflow are outside this diff. The only Compare
+change delegates its existing stateless confetti export to maintained shared UI.
+
+## Maintained source (42)
+
+| Status | File |
+| --- | --- |
+| A | [frontend/src/features/notes/application/agentActions.js](../../frontend/src/features/notes/application/agentActions.js) |
+| A | [frontend/src/features/notes/application/cardOperations.js](../../frontend/src/features/notes/application/cardOperations.js) |
+| A | [frontend/src/features/notes/application/checklistOperations.js](../../frontend/src/features/notes/application/checklistOperations.js) |
+| A | [frontend/src/features/notes/application/deletion.js](../../frontend/src/features/notes/application/deletion.js) |
+| A | [frontend/src/features/notes/application/drafts.js](../../frontend/src/features/notes/application/drafts.js) |
+| A | [frontend/src/features/notes/application/queries.js](../../frontend/src/features/notes/application/queries.js) |
+| A | [frontend/src/features/notes/application/reminders.js](../../frontend/src/features/notes/application/reminders.js) |
+| A | [frontend/src/features/notes/application/selection.js](../../frontend/src/features/notes/application/selection.js) |
+| A | [frontend/src/features/notes/application/state.js](../../frontend/src/features/notes/application/state.js) |
+| A | [frontend/src/features/notes/application/submission.js](../../frontend/src/features/notes/application/submission.js) |
+| A | [frontend/src/features/notes/application/workflows.js](../../frontend/src/features/notes/application/workflows.js) |
+| A | [frontend/src/features/notes/domain/noteRules.js](../../frontend/src/features/notes/domain/noteRules.js) |
+| A | [frontend/src/features/notes/domain/recurrence.js](../../frontend/src/features/notes/domain/recurrence.js) |
+| A | [frontend/src/features/notes/index.js](../../frontend/src/features/notes/index.js) |
+| A | [frontend/src/features/notes/infrastructure/http.js](../../frontend/src/features/notes/infrastructure/http.js) |
+| A | [frontend/src/features/notes/infrastructure/notifications.js](../../frontend/src/features/notes/infrastructure/notifications.js) |
+| A | [frontend/src/features/notes/infrastructure/storage.js](../../frontend/src/features/notes/infrastructure/storage.js) |
+| A | [frontend/src/features/notes/ui/cardChecklist.js](../../frontend/src/features/notes/ui/cardChecklist.js) |
+| A | [frontend/src/features/notes/ui/cardInteractions.js](../../frontend/src/features/notes/ui/cardInteractions.js) |
+| A | [frontend/src/features/notes/ui/cardRendering.js](../../frontend/src/features/notes/ui/cardRendering.js) |
+| A | [frontend/src/features/notes/ui/cardReorder.js](../../frontend/src/features/notes/ui/cardReorder.js) |
+| A | [frontend/src/features/notes/ui/checklist.js](../../frontend/src/features/notes/ui/checklist.js) |
+| A | [frontend/src/features/notes/ui/checklistReorder.js](../../frontend/src/features/notes/ui/checklistReorder.js) |
+| A | [frontend/src/features/notes/ui/clipboard.js](../../frontend/src/features/notes/ui/clipboard.js) |
+| A | [frontend/src/features/notes/ui/colors.js](../../frontend/src/features/notes/ui/colors.js) |
+| A | [frontend/src/features/notes/ui/draftEditor.js](../../frontend/src/features/notes/ui/draftEditor.js) |
+| A | [frontend/src/features/notes/ui/drawing.js](../../frontend/src/features/notes/ui/drawing.js) |
+| A | [frontend/src/features/notes/ui/editor.js](../../frontend/src/features/notes/ui/editor.js) |
+| A | [frontend/src/features/notes/ui/filters.js](../../frontend/src/features/notes/ui/filters.js) |
+| A | [frontend/src/features/notes/ui/layout.js](../../frontend/src/features/notes/ui/layout.js) |
+| A | [frontend/src/features/notes/ui/lifecycle.js](../../frontend/src/features/notes/ui/lifecycle.js) |
+| A | [frontend/src/features/notes/ui/mobileEditor.js](../../frontend/src/features/notes/ui/mobileEditor.js) |
+| A | [frontend/src/features/notes/ui/mobileReorder.js](../../frontend/src/features/notes/ui/mobileReorder.js) |
+| A | [frontend/src/features/notes/ui/panel.js](../../frontend/src/features/notes/ui/panel.js) |
+| A | [frontend/src/features/notes/ui/quickAdd.js](../../frontend/src/features/notes/ui/quickAdd.js) |
+| A | [frontend/src/features/notes/ui/reminderDisplay.js](../../frontend/src/features/notes/ui/reminderDisplay.js) |
+| A | [frontend/src/features/notes/ui/reminderPicker.js](../../frontend/src/features/notes/ui/reminderPicker.js) |
+| A | [frontend/src/features/notes/ui/selection.js](../../frontend/src/features/notes/ui/selection.js) |
+| A | [frontend/src/features/notes/ui/text.js](../../frontend/src/features/notes/ui/text.js) |
+| A | [frontend/src/features/notes/ui/toolbar.js](../../frontend/src/features/notes/ui/toolbar.js) |
+| A | [frontend/src/features/notes/ui/windowLayout.js](../../frontend/src/features/notes/ui/windowLayout.js) |
+| A | [frontend/src/shared/ui/confetti.js](../../frontend/src/shared/ui/confetti.js) |
+
+## Deployment copies (42)
+
+| Status | File |
+| --- | --- |
+| A | [static/js/features/notes/application/agentActions.js](../../static/js/features/notes/application/agentActions.js) |
+| A | [static/js/features/notes/application/cardOperations.js](../../static/js/features/notes/application/cardOperations.js) |
+| A | [static/js/features/notes/application/checklistOperations.js](../../static/js/features/notes/application/checklistOperations.js) |
+| A | [static/js/features/notes/application/deletion.js](../../static/js/features/notes/application/deletion.js) |
+| A | [static/js/features/notes/application/drafts.js](../../static/js/features/notes/application/drafts.js) |
+| A | [static/js/features/notes/application/queries.js](../../static/js/features/notes/application/queries.js) |
+| A | [static/js/features/notes/application/reminders.js](../../static/js/features/notes/application/reminders.js) |
+| A | [static/js/features/notes/application/selection.js](../../static/js/features/notes/application/selection.js) |
+| A | [static/js/features/notes/application/state.js](../../static/js/features/notes/application/state.js) |
+| A | [static/js/features/notes/application/submission.js](../../static/js/features/notes/application/submission.js) |
+| A | [static/js/features/notes/application/workflows.js](../../static/js/features/notes/application/workflows.js) |
+| A | [static/js/features/notes/domain/noteRules.js](../../static/js/features/notes/domain/noteRules.js) |
+| A | [static/js/features/notes/domain/recurrence.js](../../static/js/features/notes/domain/recurrence.js) |
+| A | [static/js/features/notes/index.js](../../static/js/features/notes/index.js) |
+| A | [static/js/features/notes/infrastructure/http.js](../../static/js/features/notes/infrastructure/http.js) |
+| A | [static/js/features/notes/infrastructure/notifications.js](../../static/js/features/notes/infrastructure/notifications.js) |
+| A | [static/js/features/notes/infrastructure/storage.js](../../static/js/features/notes/infrastructure/storage.js) |
+| A | [static/js/features/notes/ui/cardChecklist.js](../../static/js/features/notes/ui/cardChecklist.js) |
+| A | [static/js/features/notes/ui/cardInteractions.js](../../static/js/features/notes/ui/cardInteractions.js) |
+| A | [static/js/features/notes/ui/cardRendering.js](../../static/js/features/notes/ui/cardRendering.js) |
+| A | [static/js/features/notes/ui/cardReorder.js](../../static/js/features/notes/ui/cardReorder.js) |
+| A | [static/js/features/notes/ui/checklist.js](../../static/js/features/notes/ui/checklist.js) |
+| A | [static/js/features/notes/ui/checklistReorder.js](../../static/js/features/notes/ui/checklistReorder.js) |
+| A | [static/js/features/notes/ui/clipboard.js](../../static/js/features/notes/ui/clipboard.js) |
+| A | [static/js/features/notes/ui/colors.js](../../static/js/features/notes/ui/colors.js) |
+| A | [static/js/features/notes/ui/draftEditor.js](../../static/js/features/notes/ui/draftEditor.js) |
+| A | [static/js/features/notes/ui/drawing.js](../../static/js/features/notes/ui/drawing.js) |
+| A | [static/js/features/notes/ui/editor.js](../../static/js/features/notes/ui/editor.js) |
+| A | [static/js/features/notes/ui/filters.js](../../static/js/features/notes/ui/filters.js) |
+| A | [static/js/features/notes/ui/layout.js](../../static/js/features/notes/ui/layout.js) |
+| A | [static/js/features/notes/ui/lifecycle.js](../../static/js/features/notes/ui/lifecycle.js) |
+| A | [static/js/features/notes/ui/mobileEditor.js](../../static/js/features/notes/ui/mobileEditor.js) |
+| A | [static/js/features/notes/ui/mobileReorder.js](../../static/js/features/notes/ui/mobileReorder.js) |
+| A | [static/js/features/notes/ui/panel.js](../../static/js/features/notes/ui/panel.js) |
+| A | [static/js/features/notes/ui/quickAdd.js](../../static/js/features/notes/ui/quickAdd.js) |
+| A | [static/js/features/notes/ui/reminderDisplay.js](../../static/js/features/notes/ui/reminderDisplay.js) |
+| A | [static/js/features/notes/ui/reminderPicker.js](../../static/js/features/notes/ui/reminderPicker.js) |
+| A | [static/js/features/notes/ui/selection.js](../../static/js/features/notes/ui/selection.js) |
+| A | [static/js/features/notes/ui/text.js](../../static/js/features/notes/ui/text.js) |
+| A | [static/js/features/notes/ui/toolbar.js](../../static/js/features/notes/ui/toolbar.js) |
+| A | [static/js/features/notes/ui/windowLayout.js](../../static/js/features/notes/ui/windowLayout.js) |
+| A | [static/js/shared/ui/confetti.js](../../static/js/shared/ui/confetti.js) |
+
+## Compatibility and deployment configuration (5)
+
+| Status | File |
+| --- | --- |
+| M | [.gitattributes](../../.gitattributes) |
+| M | [frontend/modules.json](../../frontend/modules.json) |
+| M | [static/js/compare/vote.js](../../static/js/compare/vote.js) |
+| M | [static/js/notes.js](../../static/js/notes.js) |
+| M | [static/sw.js](../../static/sw.js) |
+
+## Tests (21)
+
+| Status | File |
+| --- | --- |
+| A | [tests/browser/notesNative.mjs](../../tests/browser/notesNative.mjs) |
+| A | [tests/browser/notesOffline.mjs](../../tests/browser/notesOffline.mjs) |
+| A | [tests/browser/notesReference.mjs](../../tests/browser/notesReference.mjs) |
+| A | [tests/fixtures/notesRecurrenceBaseline.mjs](../../tests/fixtures/notesRecurrenceBaseline.mjs) |
+| A | [tests/helpers/notes_source.py](../../tests/helpers/notes_source.py) |
+| A | [tests/notesApplication.test.mjs](../../tests/notesApplication.test.mjs) |
+| A | [tests/notesCharacterization.test.mjs](../../tests/notesCharacterization.test.mjs) |
+| M | [tests/notesDraftAutosave.test.mjs](../../tests/notesDraftAutosave.test.mjs) |
+| A | [tests/notesInfrastructure.test.mjs](../../tests/notesInfrastructure.test.mjs) |
+| A | [tests/notesRecurrence.test.mjs](../../tests/notesRecurrence.test.mjs) |
+| A | [tests/notesReminders.test.mjs](../../tests/notesReminders.test.mjs) |
+| A | [tests/notesWorkflows.test.mjs](../../tests/notesWorkflows.test.mjs) |
+| M | [tests/selectedNotesContext.test.mjs](../../tests/selectedNotesContext.test.mjs) |
+| M | [tests/test_notes_document_mutual_minimize.py](../../tests/test_notes_document_mutual_minimize.py) |
+| M | [tests/test_notes_dom_xss_helpers.py](../../tests/test_notes_dom_xss_helpers.py) |
+| M | [tests/test_notes_mobile_checklist_toggle_static.py](../../tests/test_notes_mobile_checklist_toggle_static.py) |
+| A | [tests/test_notes_reference_browser.py](../../tests/test_notes_reference_browser.py) |
+| A | [tests/test_notes_reference_contracts_js.py](../../tests/test_notes_reference_contracts_js.py) |
+| M | [tests/test_notes_search_reset_on_reopen_js.py](../../tests/test_notes_search_reset_on_reopen_js.py) |
+| M | [tests/test_notes_select_esc_listener_js.py](../../tests/test_notes_select_esc_listener_js.py) |
+| M | [tests/test_notes_sidebar_new_note.py](../../tests/test_notes_sidebar_new_note.py) |
+
+## Runtime validation (2)
+
+| Status | File |
+| --- | --- |
+| M | [scripts/verify_frontend_runtime.py](../../scripts/verify_frontend_runtime.py) |
+| A | [scripts/verify_notes_browser_runtime.py](../../scripts/verify_notes_browser_runtime.py) |
+
+## Documentation and execution receipts (9)
+
+| Status | File |
+| --- | --- |
+| A | [docs/frontend-architecture/evidence/notes/implementation.sha256](../../docs/frontend-architecture/evidence/notes/implementation.sha256) |
+| A | [docs/frontend-architecture/evidence/notes/native-desktop.png](../../docs/frontend-architecture/evidence/notes/native-desktop.png) |
+| A | [docs/frontend-architecture/evidence/notes/native-mobile.png](../../docs/frontend-architecture/evidence/notes/native-mobile.png) |
+| M | [docs/frontend-architecture/handbook.md](../../docs/frontend-architecture/handbook.md) |
+| A | [docs/frontend-architecture/notes-case-study.md](../../docs/frontend-architecture/notes-case-study.md) |
+| A | [docs/frontend-architecture/notes-changed-files.md](../../docs/frontend-architecture/notes-changed-files.md) |
+| A | [docs/frontend-architecture/notes-module-inventory.md](../../docs/frontend-architecture/notes-module-inventory.md) |
+| M | [docs/frontend-architecture/notes-roadmap.md](../../docs/frontend-architecture/notes-roadmap.md) |
+| A | [docs/frontend-architecture/notes-validation.md](../../docs/frontend-architecture/notes-validation.md) |
+
+See [the case study](notes-case-study.md) for ownership and handoff,
+[the module inventory](notes-module-inventory.md) for line counts, and
+[the validation report](notes-validation.md) for exact executed checks.
diff --git a/docs/frontend-architecture/notes-module-inventory.md b/docs/frontend-architecture/notes-module-inventory.md
new file mode 100644
index 000000000..5d8184858
--- /dev/null
+++ b/docs/frontend-architecture/notes-module-inventory.md
@@ -0,0 +1,56 @@
+# Notes source and deployment inventory
+
+The feature has 41 maintained modules. The unchanged F1 action-menu proof and
+shared confetti bring the full manifest to 43. Outputs are copied byte-for-byte;
+count maintained source once. The legacy entry is a five-line compatibility facade.
+
+| Source under frontend/src | Deployment under static | Lines | Layer |
+| --- | --- | ---: | --- |
+| [features/notes/application/agentActions.js](../../frontend/src/features/notes/application/agentActions.js) | [js/features/notes/application/agentActions.js](../../static/js/features/notes/application/agentActions.js) | 67 | application |
+| [features/notes/application/cardOperations.js](../../frontend/src/features/notes/application/cardOperations.js) | [js/features/notes/application/cardOperations.js](../../static/js/features/notes/application/cardOperations.js) | 79 | application |
+| [features/notes/application/checklistOperations.js](../../frontend/src/features/notes/application/checklistOperations.js) | [js/features/notes/application/checklistOperations.js](../../static/js/features/notes/application/checklistOperations.js) | 68 | application |
+| [features/notes/application/deletion.js](../../frontend/src/features/notes/application/deletion.js) | [js/features/notes/application/deletion.js](../../static/js/features/notes/application/deletion.js) | 51 | application |
+| [features/notes/application/drafts.js](../../frontend/src/features/notes/application/drafts.js) | [js/features/notes/application/drafts.js](../../static/js/features/notes/application/drafts.js) | 55 | application |
+| [features/notes/application/queries.js](../../frontend/src/features/notes/application/queries.js) | [js/features/notes/application/queries.js](../../static/js/features/notes/application/queries.js) | 66 | application |
+| [features/notes/application/reminders.js](../../frontend/src/features/notes/application/reminders.js) | [js/features/notes/application/reminders.js](../../static/js/features/notes/application/reminders.js) | 182 | application |
+| [features/notes/application/selection.js](../../frontend/src/features/notes/application/selection.js) | [js/features/notes/application/selection.js](../../static/js/features/notes/application/selection.js) | 39 | application |
+| [features/notes/application/state.js](../../frontend/src/features/notes/application/state.js) | [js/features/notes/application/state.js](../../static/js/features/notes/application/state.js) | 72 | application |
+| [features/notes/application/submission.js](../../frontend/src/features/notes/application/submission.js) | [js/features/notes/application/submission.js](../../static/js/features/notes/application/submission.js) | 69 | application |
+| [features/notes/application/workflows.js](../../frontend/src/features/notes/application/workflows.js) | [js/features/notes/application/workflows.js](../../static/js/features/notes/application/workflows.js) | 78 | application |
+| [features/notes/domain/noteRules.js](../../frontend/src/features/notes/domain/noteRules.js) | [js/features/notes/domain/noteRules.js](../../static/js/features/notes/domain/noteRules.js) | 87 | domain |
+| [features/notes/domain/recurrence.js](../../frontend/src/features/notes/domain/recurrence.js) | [js/features/notes/domain/recurrence.js](../../static/js/features/notes/domain/recurrence.js) | 269 | domain |
+| [features/notes/index.js](../../frontend/src/features/notes/index.js) | [js/features/notes/index.js](../../static/js/features/notes/index.js) | 518 | composition |
+| [features/notes/infrastructure/http.js](../../frontend/src/features/notes/infrastructure/http.js) | [js/features/notes/infrastructure/http.js](../../static/js/features/notes/infrastructure/http.js) | 29 | infrastructure |
+| [features/notes/infrastructure/notifications.js](../../frontend/src/features/notes/infrastructure/notifications.js) | [js/features/notes/infrastructure/notifications.js](../../static/js/features/notes/infrastructure/notifications.js) | 20 | infrastructure |
+| [features/notes/infrastructure/storage.js](../../frontend/src/features/notes/infrastructure/storage.js) | [js/features/notes/infrastructure/storage.js](../../static/js/features/notes/infrastructure/storage.js) | 63 | infrastructure |
+| [features/notes/ui/cardChecklist.js](../../frontend/src/features/notes/ui/cardChecklist.js) | [js/features/notes/ui/cardChecklist.js](../../static/js/features/notes/ui/cardChecklist.js) | 148 | ui |
+| [features/notes/ui/cardInteractions.js](../../frontend/src/features/notes/ui/cardInteractions.js) | [js/features/notes/ui/cardInteractions.js](../../static/js/features/notes/ui/cardInteractions.js) | 337 | ui |
+| [features/notes/ui/cardRendering.js](../../frontend/src/features/notes/ui/cardRendering.js) | [js/features/notes/ui/cardRendering.js](../../static/js/features/notes/ui/cardRendering.js) | 244 | ui |
+| [features/notes/ui/cardReorder.js](../../frontend/src/features/notes/ui/cardReorder.js) | [js/features/notes/ui/cardReorder.js](../../static/js/features/notes/ui/cardReorder.js) | 181 | ui |
+| [features/notes/ui/checklist.js](../../frontend/src/features/notes/ui/checklist.js) | [js/features/notes/ui/checklist.js](../../static/js/features/notes/ui/checklist.js) | 190 | ui |
+| [features/notes/ui/checklistReorder.js](../../frontend/src/features/notes/ui/checklistReorder.js) | [js/features/notes/ui/checklistReorder.js](../../static/js/features/notes/ui/checklistReorder.js) | 111 | ui |
+| [features/notes/ui/clipboard.js](../../frontend/src/features/notes/ui/clipboard.js) | [js/features/notes/ui/clipboard.js](../../static/js/features/notes/ui/clipboard.js) | 82 | ui |
+| [features/notes/ui/colors.js](../../frontend/src/features/notes/ui/colors.js) | [js/features/notes/ui/colors.js](../../static/js/features/notes/ui/colors.js) | 111 | ui |
+| [features/notes/ui/draftEditor.js](../../frontend/src/features/notes/ui/draftEditor.js) | [js/features/notes/ui/draftEditor.js](../../static/js/features/notes/ui/draftEditor.js) | 67 | ui |
+| [features/notes/ui/drawing.js](../../frontend/src/features/notes/ui/drawing.js) | [js/features/notes/ui/drawing.js](../../static/js/features/notes/ui/drawing.js) | 442 | ui |
+| [features/notes/ui/editor.js](../../frontend/src/features/notes/ui/editor.js) | [js/features/notes/ui/editor.js](../../static/js/features/notes/ui/editor.js) | 518 | ui |
+| [features/notes/ui/filters.js](../../frontend/src/features/notes/ui/filters.js) | [js/features/notes/ui/filters.js](../../static/js/features/notes/ui/filters.js) | 139 | ui |
+| [features/notes/ui/layout.js](../../frontend/src/features/notes/ui/layout.js) | [js/features/notes/ui/layout.js](../../static/js/features/notes/ui/layout.js) | 120 | ui |
+| [features/notes/ui/lifecycle.js](../../frontend/src/features/notes/ui/lifecycle.js) | [js/features/notes/ui/lifecycle.js](../../static/js/features/notes/ui/lifecycle.js) | 36 | ui |
+| [features/notes/ui/mobileEditor.js](../../frontend/src/features/notes/ui/mobileEditor.js) | [js/features/notes/ui/mobileEditor.js](../../static/js/features/notes/ui/mobileEditor.js) | 257 | ui |
+| [features/notes/ui/mobileReorder.js](../../frontend/src/features/notes/ui/mobileReorder.js) | [js/features/notes/ui/mobileReorder.js](../../static/js/features/notes/ui/mobileReorder.js) | 214 | ui |
+| [features/notes/ui/panel.js](../../frontend/src/features/notes/ui/panel.js) | [js/features/notes/ui/panel.js](../../static/js/features/notes/ui/panel.js) | 506 | ui |
+| [features/notes/ui/quickAdd.js](../../frontend/src/features/notes/ui/quickAdd.js) | [js/features/notes/ui/quickAdd.js](../../static/js/features/notes/ui/quickAdd.js) | 170 | ui |
+| [features/notes/ui/reminderDisplay.js](../../frontend/src/features/notes/ui/reminderDisplay.js) | [js/features/notes/ui/reminderDisplay.js](../../static/js/features/notes/ui/reminderDisplay.js) | 129 | ui |
+| [features/notes/ui/reminderPicker.js](../../frontend/src/features/notes/ui/reminderPicker.js) | [js/features/notes/ui/reminderPicker.js](../../static/js/features/notes/ui/reminderPicker.js) | 334 | ui |
+| [features/notes/ui/selection.js](../../frontend/src/features/notes/ui/selection.js) | [js/features/notes/ui/selection.js](../../static/js/features/notes/ui/selection.js) | 61 | ui |
+| [features/notes/ui/text.js](../../frontend/src/features/notes/ui/text.js) | [js/features/notes/ui/text.js](../../static/js/features/notes/ui/text.js) | 39 | ui |
+| [features/notes/ui/toolbar.js](../../frontend/src/features/notes/ui/toolbar.js) | [js/features/notes/ui/toolbar.js](../../static/js/features/notes/ui/toolbar.js) | 78 | ui |
+| [features/notes/ui/windowLayout.js](../../frontend/src/features/notes/ui/windowLayout.js) | [js/features/notes/ui/windowLayout.js](../../static/js/features/notes/ui/windowLayout.js) | 114 | ui |
+| [shared/ui/confetti.js](../../frontend/src/shared/ui/confetti.js) | [js/shared/ui/confetti.js](../../static/js/shared/ui/confetti.js) | 28 | shared UI |
+
+Maintained Notes feature total: 6440 lines. Original entry: 5,471 lines.
+Legacy facade after decomposition: five lines. Shared confetti: 28 lines.
+
+See [the case study](notes-case-study.md) for responsibilities and public/state/lifecycle
+contracts, and [the validation report](notes-validation.md) for executed evidence.
diff --git a/docs/frontend-architecture/notes-roadmap.md b/docs/frontend-architecture/notes-roadmap.md
index 6371e9aca..522923dc2 100644
--- a/docs/frontend-architecture/notes-roadmap.md
+++ b/docs/frontend-architecture/notes-roadmap.md
@@ -1,15 +1,20 @@
 # Notes reference decomposition roadmap
 
-Status: planning only. F1 changes no Notes implementation. Begin after the
-foundation has been reviewed and integrated into official `upstream/dev`.
-The reference program ends after Notes integration and the completed H handoff.
+Status: N0 through N6 implemented as an unpublished Notes review diff after F1
+merged in PR #6701. Actual decisions, interfaces, module ownership, checkpoint
+receipts and execution limits are in the [case study](notes-case-study.md) and
+[validation report](notes-validation.md). The proposal below retains the original
+responsibility map for comparison. Notes integration and the recipient's independent
+H reproduction remain pending.
 F1 remains an entirely separate foundation-only PR. The complete Notes
 decomposition, regression tests, compatibility validation and final reference
 case study belong to one comprehensive draft PR targeting official `dev`.
 
 ## Verified current responsibility and compatibility map
 
-Baseline: `8feb50e89468235cd3e0986da80edbd3acaf2c40`.
+Historical assessment baseline: `8feb50e89468235cd3e0986da80edbd3acaf2c40`.
+The implementation starts from merged F1 at
+`1cc56cb9d78f3e2399d1d61155b71d771a17b85b`.
 The module is `static/js/notes.js`, about 5,470 lines, with browser identity
 `/static/js/notes.js?v=20260911notesselectioncancel1`. Preserve that identity across
 the app import, HTML, SW and lazy consumers until a separately reviewed migration
diff --git a/docs/frontend-architecture/notes-validation.md b/docs/frontend-architecture/notes-validation.md
new file mode 100644
index 000000000..e4e701c6c
--- /dev/null
+++ b/docs/frontend-architecture/notes-validation.md
@@ -0,0 +1,261 @@
+# Notes implementation validation and checkpoint receipts
+
+Implementation baseline: `1cc56cb9d78f3e2399d1d61155b71d771a17b85b`, updated via
+non-destructive fast-forward to latest official `upstream/dev` at
+`86b886c611338282af6d4a717246ea4e256f58df` (incorporating PRs #6704 and #6693).
+Independent AGY audit returned CONDITIONAL PASS. Pre-publication corrective
+pass verified issue template, PR template, visual evidence paths, and em-dash removal.
+The official integration branch is `dev`. Tracking issue #6712; PR #6713.
+
+## Final executed evidence
+
+| Check | Result |
+| --- | --- |
+| Notes Python tests, discovered by filename, plus F1 publication/graph/offline/loader tests | 172 passed, one release-smoke skip without `APP_PORT` |
+| Node architecture, Notes oracle, domain, infrastructure, application, reminders, drafts, selection and workflow tests | 46 passed |
+| Native Python lifespan/static distribution probe | Passed for every mapped output, with source/Node absent |
+| Existing Docker image distribution probe | Passed with networking disabled and candidate files mounted read-only |
+| Real authenticated native app, desktop and touch-mobile | Passed CRUD persistence, owner identity, actual Chat selected-context indicator/reset and the original release smoke scenario |
+| Real Chromium first evaluation of Notes offline | Passed; every maintained output cached, facade/canonical API identity shared |
+| Source/output parity and F1 boundaries | Passed, 43 maintained modules and nine composition-only legacy exceptions |
+| Foundation-based full pytest execution | 13 failed, 13,909 passed, 60 skipped, six subtests passed, 192 warnings, 517.04 seconds |
+| Targeted unchanged F1 baseline reproduction | Same 13 failures, 77 passed, six warnings |
+| Targeted untouched latest `dev` reproduction | Three inherited failures, 87 passed, six warnings |
+| Final indexed latest `dev` plus Notes overlay, full pytest | Three same-environment baseline failures, 13,923 passed, 60 skipped, six subtests passed, 192 warnings, 512.09 seconds |
+| Untouched latest `dev` readiness checks, without the prewarm override | Five passed |
+
+The foundation-based full repository result is not green. Its failures reproduce against
+the unchanged foundation in a disposable archive, with the same interpreter and
+closed Chroma port. None was disabled, relabeled or fixed in this Notes change.
+The focused Notes suite and required source/deployment gates are green. The final
+code/test overlay is fingerprinted in [implementation.sha256](evidence/notes/implementation.sha256).
+The only post-full-suite test-source edit removes a terminal
+blank line from the browser wrapper; its content was compared ignoring terminal
+whitespace and all three focused contract/browser checks passed again. Raw command
+outputs are kept out of the repository; the counts above are the record.
+
+The first full run reported 19 failures. Six were introduced validation issues:
+the SW cache name did not follow the existing numeric convention; a temporary
+probe environment input was not registered by the configuration-reference checker;
+and a Notes source assertion still expected the original default object spelling.
+The cache name now follows the convention, the probe passes its output list as a
+command argument, and the assertion verifies the new public binding. All 58 tests
+in those affected files passed after correction. The foundation-based full run has only the
+13 reproduced baseline failures below.
+
+### Reproduced baseline failures
+
+- `tests/test_aux_llm_owner_scope.py::test_auto_compaction_utility_endpoint_keeps_chat_owner`
+- `tests/test_chatgpt_reasoning_and_grouping.py::test_history_and_chat_routes_support_reasoning_effort`
+- `tests/test_containment_enforcement.py::test_namespace_handshake_closes_model_stdin`
+- `tests/test_containment_enforcement.py::test_execution_environment_cannot_replace_probed_bwrap[False]`
+- `tests/test_context_compactor.py::TestMaybeCompactFourthMessage::test_does_not_crash_on_none_content_turn`
+- `tests/test_context_compactor.py::TestMaybeCompactFourthMessage::test_handles_multimodal_list_content`
+- `tests/test_css_computed_style_snapshot.py::test_computed_styles_match_the_committed_baseline`
+- `tests/test_history_compact_tool_calls.py::test_manual_compact_tolerates_chatmessage_with_none_content`
+- `tests/test_history_compact_tool_calls.py::test_manual_compact_tolerates_dict_message_with_none_content`
+- `tests/test_history_compact_tool_calls.py::test_registered_manual_compact_route_tolerates_none_content`
+- `tests/test_history_compact_tool_calls.py::test_registered_manual_compact_route_uses_session_owner`
+- `tests/test_model_helper_owner_scope.py::test_history_compact_resolves_with_owner_scope`
+- `tests/test_readiness.py::test_tool_index_is_reported_but_not_critical_by_default`
+
+These cover existing compaction fixtures/source assertions, namespace containment,
+settings-row CSS baseline drift and readiness expectations. The baseline reproduction used
+`git archive` into `/tmp/odysseus-notes-baseline-OitxsU`, not another branch/worktree.
+
+## Reproducible commands
+
+### Latest integration target
+
+Final upstream inspection found `86b886c611338282af6d4a717246ea4e256f58df`.
+PR #6704 repairs ten of the foundation's reproduced failures; PR #6693 adds
+remote-only skill gating. Neither changes a file owned by the Notes diff.
+The branch remains on the requested foundation, with no merge or rebase.
+An archive of that latest target plus the exact final Notes code/test overlay is
+validated in `/tmp/odysseus-notes-latest-VmZrgC` using the same full-suite command.
+The fixture has a local Git index, initialized from the latest target and updated
+with the review files, but no commit. This enables the tracked-publication checks.
+The first archive-only attempt had one Git-metadata failure and seven checkout-only
+skips. Both affected files subsequently passed all 19 tests with metadata present;
+the complete suite was then rerun in that indexed fixture.
+An untouched archive at `/tmp/odysseus-notes-latest-baseline-mfE4ss` reproduced
+the remaining two containment failures and the readiness failure: three failed,
+87 passed.
+
+These are reproduced local-environment failures, not a claim that official CI is
+currently failing. The readiness assertion expects prewarming enabled, whereas
+the full-run safety command explicitly sets `ODYSSEUS_TOOL_INDEX_PREWARM=0`.
+With that override absent, all five readiness tests pass on untouched latest `dev`.
+The two namespace tests receive extra `Failed to create stream fd` stderr in this
+host's contained process output. That same output occurs without the Notes overlay;
+no backend containment code was changed or a failing assertion weakened.
+Reproduce those two checks on the supported CI runner before claiming a green
+full-suite certification.
+
+In the final indexed full-suite run the only failures are `test_namespace_handshake_closes_model_stdin`,
+`test_execution_environment_cannot_replace_probed_bwrap[False]`, and
+`test_tool_index_is_reported_but_not_critical_by_default`. The missing-Git-metadata
+publication failure and the seven checkout-only skips are absent from this run.
+No Notes regression was reported. Feature code matched N6 at publication. Later
+commits on the PR changed `ui/reminderPicker.js` (date input value assigned through
+the DOM property) and, after review, `index.js`, `ui/layout.js` and
+`application/state.js`; `implementation.sha256` covers the current files.
+
+To reproduce the integration rehearsal, extract the latest target with `git archive`
+into a fresh fixture and copy only files in the changed-file inventory on top.
+Do not overlay foundation files that are unchanged in this PR. Install the locked
+development dependencies in the fixture, then run the commands below there.
+
+While this review diff is uncommitted, this prepares an equivalent Linux fixture
+without changing either task worktree:
+
+```sh
+notes_fixture=$(mktemp -d /tmp/ody-notes-integration-XXXXXX)
+git archive 86b886c611338282af6d4a717246ea4e256f58df | tar -x -C "$notes_fixture"
+{ git diff --name-only -z; git ls-files --others --exclude-standard -z; } |
+  tar --null -T - -cf - | tar -xf - -C "$notes_fixture"
+git -C "$notes_fixture" init -q
+git -C "$notes_fixture" fetch --no-write-fetch-head "$PWD" 86b886c611338282af6d4a717246ea4e256f58df
+git -C "$notes_fixture" read-tree 86b886c611338282af6d4a717246ea4e256f58df
+(cd "$notes_fixture" && npm ci --ignore-scripts --no-audit --no-fund && git add --all)
+# Run the validation commands below from notes_fixture, using an isolated Python environment.
+```
+
+Use a real dependency directory for this recipe; a symlink named `node_modules`
+can bypass the repository's directory-only ignore pattern. No checkpoint or
+fixture commit is needed. After integration, validate the actual integrated checkout
+directly, rather than relying on the uncommitted-diff recipe.
+
+### Commands
+
+Use the actual tested interpreter, or install the repository requirements in your
+own isolated virtualenv. Node development dependencies were installed with the
+existing lockfile and `npm ci --ignore-scripts --no-audit --no-fund`.
+
+```sh
+python3 scripts/build_frontend.py
+python3 scripts/build_frontend.py --check
+node scripts/check_frontend.mjs
+node scripts/check_frontend.mjs --inventory
+
+ENDPOINT_URL=http://127.0.0.1:1 node --test \
+  tests/frontendArchitecture.test.mjs tests/noteTestOracle.test.mjs \
+  tests/notesDraftAutosave.test.mjs tests/selectedNotesContext.test.mjs \
+  tests/notesCharacterization.test.mjs tests/notesRecurrence.test.mjs \
+  tests/notesInfrastructure.test.mjs tests/notesApplication.test.mjs \
+  tests/notesReminders.test.mjs tests/notesWorkflows.test.mjs
+
+CHROMADB_HOST=127.0.0.1 CHROMADB_PORT=1 \
+  python -m pytest -q -rs \
+  $(rg --files tests -g 'test_*note*.py') \
+  tests/test_frontend_build.py tests/test_frontend_foundation_offline_js.py \
+  tests/test_frontend_module_graph.py tests/test_frontend_module_version_parity.py \
+  tests/test_panel_loader_js.py
+
+python scripts/verify_frontend_runtime.py
+python scripts/verify_notes_browser_runtime.py
+
+docker run --rm --network none \
+  --mount type=bind,src="$PWD",dst=/candidate,readonly \
+  --workdir /candidate --entrypoint python \
+  <existing-odysseus-image> scripts/verify_frontend_runtime.py
+
+CHROMADB_HOST=127.0.0.1 CHROMADB_PORT=1 \
+  ODYSSEUS_STARTUP_WARMUPS=0 ODYSSEUS_TOOL_INDEX_PREWARM=0 \
+  python -m pytest -q -rfs
+
+git diff --check
+```
+
+`ENDPOINT_URL` satisfies the existing oracle's import configuration; its endpoint-
+driving main does not run in these unit tests. Port 1 is the closed loopback target
+used for pytest; the two runtime scripts reserve their own non-listening Chroma port.
+The native browser script creates a private distribution/database and a temporary
+authenticated user, then terminates the server and removes that fixture. It uses
+the real application and Notes API rather than mocked browser routes.
+
+The deterministic browser harness uses stub API responses and the real Notes ESM,
+DOM and stylesheet graph. It verifies namespace/default methods and arities,
+aliases, remount/search reset, rejected/accepted attachments, draft persistence,
+drawing/undo and listener/portal cleanup. It also checks larger-touch reorder after
+re-render, active-drag close cleanup and cancellation of a mobile selection hold.
+It includes the mobile viewport meta tag,
+tap-to-read/edit behavior and the existing selection jiggle. The original monolith
+can be replayed with `NOTES_BASELINE=1`; it is read from the frozen F1 revision.
+
+## Browser and packaging evidence
+
+Actual app screenshots: [desktop](evidence/notes/native-desktop.png) and
+[mobile](evidence/notes/native-mobile.png). These are Chromium screenshots of the
+disposable authenticated app at 1440 x 1000 and 390 x 844, not rendered mockups.
+The deterministic before/after fixture had an identical mobile PNG and only 14
+changed desktop pixels in the header region; no layout/style change was observed.
+CSS, app bootstrap and HTML have no implementation diff.
+
+The native and Docker distribution probe serves all manifest outputs without
+`frontend/`, `node_modules/` or Node on the server path. It checks response bytes,
+JS MIME, revalidation, CSP, shell startup, static confinement and source-tree 404.
+Docker used existing image
+`sha256:cc2d47e2327d573af01c6b027f23d2ab0f2ee9b85d658e9eb8065bd02b9c3515`.
+This is not a fresh Dockerfile build or deployment.
+
+Tested locally: Linux, Python 3.14.4, Node 22.23.1 and Playwright/Chromium 1.62.1.
+CI's exact Python 3.11/Node 20 pair, Firefox/WebKit, macOS/Windows executable builds,
+live model/email notification delivery and full root offline reload were not run.
+The Docker runtime uses its own existing dependency versions. Shared active-window
+gesture interleavings are not exhaustively covered. No broader platform certification
+is claimed.
+
+The full-run safety overrides differ from official CI's plain pytest command.
+For the readiness default-contract check, use
+`env -u ODYSSEUS_TOOL_INDEX_PREWARM python -m pytest -q tests/test_readiness.py`.
+Keep explicit warmup/storage isolation on the disposable live-app probes.
+
+## Internal checkpoints
+
+Checkpoint snapshots are kept with the maintainer handoff, not in the repository.
+The hashes below identify them. They contain scoped source/output/facade/manifest/test
+overlays, not secrets or user data. Each starts from the same frozen baseline; they
+are not separate PRs or release candidates.
+
+| Stage | Boundary and executed exit evidence | Snapshot SHA-256 |
+| --- | --- | --- |
+| N0 | Public/consumer/state/lifecycle map; 95 baseline Python and 11 Node passes; four new characterization tests; desktop/touch harness; 33 F1 publication/graph checks | `db0a2e6e68fec3442ce350ffb0acf47bcdf2a5266f7c64c2bf910a1c41c4fb62` |
+| N1 | Pure recurrence/date rules; eight Node and nine focused Python passes; differential oracle in four time zones; parity/boundaries | `fd0638470744706fbbd5787cb47bd2078a93c9b854139f89f8fdc169c1f353c6` |
+| N2 | HTTP/storage adapters; fourteen Node and seven focused Python passes; exact requests, keys and fallback contracts | `30826fb7972d1b9e3a790f97ee81f66dcb3dc58eb7d23e24d4f46e6d841b7c73` |
+| N3 | Single state owner and CRUD/undo boundary; ten Node and seven focused Python passes; read-only state and archive rollback | `4bc5293519b8438d0126a61887bea64195dcdb7d59bcfaaba8ed4ae8c38be439` |
+| N4 | Page-owned reminder workflow; four reminder contract tests and seven focused Python passes; singleton interval, catch-up, markers and fallback | `febb835c4958c8758e4b7c23ce89f3ec8d103c2cc28f89817d258b3791a9fcdf` |
+| N5 | Complete UI/application integration; 44 Node passes, targeted source guards and actual browser checks; drawing binding correction, read-only state and disposal | `e147f645bdb2161a4b1dc6cf10c36ba6d0c214d8e12fccb478835043eaaf3e94` |
+| N6 | Final facade, identity, exact offline graph, native/Docker checks, final editor-deletion/reorder ownership review, touch cleanup regression checks and maintainer review package | `c450e91f9fbfe5f0cd805e596b92a76383f22a74e9515ca3e3f6154aebf5f61f` |
+
+The N6 overlay contained the final code, tests, manifest and attributes at
+publication, not the evidence directory itself. From the repository root, run
+`sha256sum -c docs/frontend-architecture/evidence/notes/implementation.sha256`
+to verify the current implementation files.
+
+No checkpoint commits were made. To reproduce an overlay, create a fresh temporary
+directory, extract `git archive 1cc56cb9...` there, then extract the desired
+snapshot from the handoff on top. Install the locked test dependencies
+in that fixture and run its relevant commands. Begin from the baseline rather than
+overlaying snapshots onto a later dirty tree. For live rollback, release a complete
+matching artifact through the authorized release workflow.
+
+Temporary mechanical extraction scripts are not part of the supported deliverable.
+They were archived locally, then removed. The first generated patch accidentally targeted
+the separate foundation worktree; only those edits were reversed, absolute paths
+were adopted, and that worktree's clean state was verified afterward.
+
+## Open PR overlaps and handoff limits
+
+The following remained open at the read-only GitHub refresh:
+
+- [#6585](https://github.com/odysseus-dev/odysseus/pull/6585): optional Notes field removal in the backend. Existing null-field behavior is retained here.
+- [#6647](https://github.com/odysseus-dev/odysseus/pull/6647): read-only Notes intent routing.
+- [#6652](https://github.com/odysseus-dev/odysseus/pull/6652): `manage_notes` registry dispatch.
+- [#6470](https://github.com/odysseus-dev/odysseus/pull/6470): shared theme, typography, sidebar and modal changes.
+- [#6695](https://github.com/odysseus-dev/odysseus/pull/6695): extension system/platform integration.
+
+Their changes were not merged or reimplemented. Shared UI exceptions, root-SW scope,
+the original last-completion fetch race, temporary-note correlation and canvas-draft
+limits are documented in the case study. Backend owner checks and PR #6495 contracts
+remain authoritative.
diff --git a/frontend/modules.json b/frontend/modules.json
index 0363222b1..0f882adbd 100644
--- a/frontend/modules.json
+++ b/frontend/modules.json
@@ -4,6 +4,212 @@
     {
       "source": "shared/actionMenuOrder.js",
       "deployment": "js/actionMenuOrder.js"
+    },
+    {
+      "source": "features/notes/domain/recurrence.js",
+      "deployment": "js/features/notes/domain/recurrence.js"
+    },
+    {
+      "source": "features/notes/infrastructure/http.js",
+      "deployment": "js/features/notes/infrastructure/http.js"
+    },
+    {
+      "source": "features/notes/infrastructure/storage.js",
+      "deployment": "js/features/notes/infrastructure/storage.js"
+    },
+    {
+      "source": "features/notes/application/state.js",
+      "deployment": "js/features/notes/application/state.js"
+    },
+    {
+      "source": "features/notes/application/workflows.js",
+      "deployment": "js/features/notes/application/workflows.js"
+    },
+    {
+      "source": "features/notes/application/reminders.js",
+      "deployment": "js/features/notes/application/reminders.js"
+    },
+    {
+      "source": "features/notes/infrastructure/notifications.js",
+      "deployment": "js/features/notes/infrastructure/notifications.js"
+    },
+    {
+      "source": "features/notes/ui/text.js",
+      "deployment": "js/features/notes/ui/text.js"
+    },
+    {
+      "source": "features/notes/ui/colors.js",
+      "deployment": "js/features/notes/ui/colors.js"
+    },
+    {
+      "source": "features/notes/ui/panel.js",
+      "deployment": "js/features/notes/ui/panel.js"
+    },
+    {
+      "source": "features/notes/ui/reminderDisplay.js",
+      "deployment": "js/features/notes/ui/reminderDisplay.js"
+    },
+    {
+      "source": "features/notes/ui/selection.js",
+      "deployment": "js/features/notes/ui/selection.js"
+    },
+    {
+      "source": "features/notes/ui/filters.js",
+      "deployment": "js/features/notes/ui/filters.js"
+    },
+    {
+      "source": "features/notes/ui/cardRendering.js",
+      "deployment": "js/features/notes/ui/cardRendering.js"
+    },
+    {
+      "source": "features/notes/ui/layout.js",
+      "deployment": "js/features/notes/ui/layout.js"
+    },
+    {
+      "source": "features/notes/ui/quickAdd.js",
+      "deployment": "js/features/notes/ui/quickAdd.js"
+    },
+    {
+      "source": "features/notes/ui/cardInteractions.js",
+      "deployment": "js/features/notes/ui/cardInteractions.js"
+    },
+    {
+      "source": "features/notes/ui/cardChecklist.js",
+      "deployment": "js/features/notes/ui/cardChecklist.js"
+    },
+    {
+      "source": "features/notes/ui/cardReorder.js",
+      "deployment": "js/features/notes/ui/cardReorder.js"
+    },
+    {
+      "source": "features/notes/ui/draftEditor.js",
+      "deployment": "js/features/notes/ui/draftEditor.js"
+    },
+    {
+      "source": "features/notes/ui/editor.js",
+      "deployment": "js/features/notes/ui/editor.js"
+    },
+    {
+      "source": "features/notes/ui/reminderPicker.js",
+      "deployment": "js/features/notes/ui/reminderPicker.js"
+    },
+    {
+      "source": "features/notes/ui/checklist.js",
+      "deployment": "js/features/notes/ui/checklist.js"
+    },
+    {
+      "source": "features/notes/ui/drawing.js",
+      "deployment": "js/features/notes/ui/drawing.js"
+    },
+    {
+      "source": "features/notes/ui/clipboard.js",
+      "deployment": "js/features/notes/ui/clipboard.js"
+    },
+    {
+      "source": "features/notes/ui/mobileEditor.js",
+      "deployment": "js/features/notes/ui/mobileEditor.js"
+    },
+    {
+      "source": "features/notes/ui/mobileReorder.js",
+      "deployment": "js/features/notes/ui/mobileReorder.js"
+    },
+    {
+      "source": "features/notes/ui/checklistReorder.js",
+      "deployment": "js/features/notes/ui/checklistReorder.js"
+    },
+    {
+      "source": "features/notes/application/queries.js",
+      "deployment": "js/features/notes/application/queries.js"
+    },
+    {
+      "source": "features/notes/application/agentActions.js",
+      "deployment": "js/features/notes/application/agentActions.js"
+    },
+    {
+      "source": "features/notes/application/deletion.js",
+      "deployment": "js/features/notes/application/deletion.js"
+    },
+    {
+      "source": "features/notes/domain/noteRules.js",
+      "deployment": "js/features/notes/domain/noteRules.js"
+    },
+    {
+      "source": "features/notes/index.js",
+      "deployment": "js/features/notes/index.js",
+      "legacyImports": [
+        {
+          "specifier": "/static/js/ui.js?v=20260916largetoolscroll1",
+          "reason": "Existing shared UI/platform identity, injected at Notes composition. Remove when that shared responsibility migrates to maintained source."
+        },
+        {
+          "specifier": "/static/js/modalManager.js",
+          "reason": "Existing shared UI/platform identity, injected at Notes composition. Remove when that shared responsibility migrates to maintained source."
+        },
+        {
+          "specifier": "/static/js/colorPicker.js?v=20260910eyedropper1",
+          "reason": "Existing shared UI/platform identity, injected at Notes composition. Remove when that shared responsibility migrates to maintained source."
+        },
+        {
+          "specifier": "/static/js/windowDrag.js",
+          "reason": "Existing shared UI/platform identity, injected at Notes composition. Remove when that shared responsibility migrates to maintained source."
+        },
+        {
+          "specifier": "/static/js/tileManager.js?v=20260910responsivebounds1",
+          "reason": "Existing shared UI/platform identity, injected at Notes composition. Remove when that shared responsibility migrates to maintained source."
+        },
+        {
+          "specifier": "/static/js/modalSnap.js",
+          "reason": "Existing shared UI/platform identity, injected at Notes composition. Remove when that shared responsibility migrates to maintained source."
+        },
+        {
+          "specifier": "/static/js/toolWindowZOrder.js",
+          "reason": "Existing shared UI/platform identity, injected at Notes composition. Remove when that shared responsibility migrates to maintained source."
+        },
+        {
+          "specifier": "/static/js/escMenuStack.js",
+          "reason": "Existing shared UI/platform identity, injected at Notes composition. Remove when that shared responsibility migrates to maintained source."
+        },
+        {
+          "specifier": "/static/js/tourHintDismiss.js",
+          "reason": "Existing shared UI/platform identity, injected at Notes composition. Remove when that shared responsibility migrates to maintained source."
+        }
+      ]
+    },
+    {
+      "source": "features/notes/application/submission.js",
+      "deployment": "js/features/notes/application/submission.js"
+    },
+    {
+      "source": "features/notes/application/drafts.js",
+      "deployment": "js/features/notes/application/drafts.js"
+    },
+    {
+      "source": "features/notes/ui/lifecycle.js",
+      "deployment": "js/features/notes/ui/lifecycle.js"
+    },
+    {
+      "source": "features/notes/application/cardOperations.js",
+      "deployment": "js/features/notes/application/cardOperations.js"
+    },
+    {
+      "source": "features/notes/application/checklistOperations.js",
+      "deployment": "js/features/notes/application/checklistOperations.js"
+    },
+    {
+      "source": "features/notes/application/selection.js",
+      "deployment": "js/features/notes/application/selection.js"
+    },
+    {
+      "source": "features/notes/ui/toolbar.js",
+      "deployment": "js/features/notes/ui/toolbar.js"
+    },
+    {
+      "source": "features/notes/ui/windowLayout.js",
+      "deployment": "js/features/notes/ui/windowLayout.js"
+    },
+    {
+      "source": "shared/ui/confetti.js",
+      "deployment": "js/shared/ui/confetti.js"
     }
   ]
 }
diff --git a/frontend/src/features/notes/application/agentActions.js b/frontend/src/features/notes/application/agentActions.js
new file mode 100644
index 000000000..d96828211
--- /dev/null
+++ b/frontend/src/features/notes/application/agentActions.js
@@ -0,0 +1,67 @@
+/** Create an agent session, link it to a note and drain its background stream. */
+import { _noteToAgentPrompt } from '../domain/noteRules.js';
+export function createAgentActions({
+  _patchNote,
+  _renderNotes,
+  api,
+  app,
+  createFormData,
+  state,
+  streamComplete,
+  uiModule
+}) {
+  async function _agentSolveNote(id) {
+    const note = state.notes.find(n => n.id === id);
+    if (!note) return;
+    const prompt = _noteToAgentPrompt(note);
+    if (!prompt) { uiModule.showToast('Nothing to solve — note is empty'); return; }
+    try {
+      const dc = await (await api.defaultChat()).json();
+      if (!dc.endpoint_url || !dc.model) { uiModule.showError('No default chat model configured'); return; }
+
+      // 1. Create the session server-side (no UI switch). skip_validation
+      //    avoids re-probing : the default-chat endpoint is already known good.
+      const label = (note.title || (Array.isArray(note.items) && note.items[0]?.text) || 'todo').slice(0, 40);
+      const csFd = createFormData();
+      csFd.append('name', 'Agent: ' + label);
+      csFd.append('endpoint_url', dc.endpoint_url);
+      csFd.append('model', dc.model);
+      if (dc.endpoint_id) csFd.append('endpoint_id', dc.endpoint_id);
+      csFd.append('skip_validation', 'true');
+      const csRes = await api.createSession(csFd);
+      if (!csRes.ok) { uiModule.showError('Could not create agent session'); return; }
+      const sess = await csRes.json();
+      const sid = sess.id;
+
+      // 2. Link the session to the note right away so the tag appears.
+      const n = state.notes.find(x => x.id === id);
+      if (n) app.mergeNote(n, { agent_session_id: sid });
+      _renderNotes();
+      _patchNote(id, { agent_session_id: sid }).catch(() => {});
+
+      // 3. Kick off the agent run in the background. POST to chat_stream in
+      //    agent mode and drain the SSE so the server runs the loop to
+      //    completion + saves : without rendering anything in the chat UI.
+      const fd = createFormData();
+      fd.append('message', prompt);
+      fd.append('session', sid);
+      fd.append('mode', 'agent');
+      fd.append('disabled_tools', JSON.stringify(['manage_notes']));
+      api.startChat(fd)
+        .then(async (res) => {
+          if (!res.ok || !res.body) return;
+          const reader = res.body.getReader();
+          // Drain to completion (server finishes + persists the run).
+          while (true) { const { done } = await reader.read(); if (done) break; }
+          streamComplete(sid);
+        })
+        .catch(() => {});
+
+      uiModule.showToast('Agent working in background — tap the Agent tag when ready');
+    } catch (e) {
+      uiModule.showError('Agent failed: ' + (e.message || e));
+    }
+  }
+
+  return { _agentSolveNote };
+}
diff --git a/frontend/src/features/notes/application/cardOperations.js b/frontend/src/features/notes/application/cardOperations.js
new file mode 100644
index 000000000..1131d2ec0
--- /dev/null
+++ b/frontend/src/features/notes/application/cardOperations.js
@@ -0,0 +1,79 @@
+/** Optimistic card mutations and rollback. Animation completion is a UI-supplied boundary. */
+export function createCardOperations({
+  app,
+  api,
+  effects,
+  pushUndo,
+  undoArchive
+}) {
+    const state = app.state;
+    function togglePin(id) {
+      const note = state.notes.find(n => n.id === id);
+      if (!note) return;
+      const prevPinned = note.pinned, prevSortOrder = note.sort_order;
+      app.mergeNote(note, { pinned: !prevPinned });
+      const patch = { pinned: note.pinned };
+      if (note.pinned) {
+        const minPinned = state.notes.filter(n => n.pinned && n.id !== id).reduce((m, n) => Math.min(m, n.sort_order || 0), 0);
+        app.mergeNote(note, { sort_order: minPinned - 1 });
+        patch.sort_order = note.sort_order;
+      }
+      effects.render();
+      api.patchNote(id, patch).catch(() => {
+        app.mergeNote(note, { pinned: prevPinned, sort_order: prevSortOrder });
+        effects.render(); effects.showError('Failed to pin');
+      });
+    }
+    async function updateColor(id, color) {
+      try {
+        await api.patchNote(id, { color: color || null });
+        const note = state.notes.find(n => n.id === id);
+        if (note) app.mergeNote(note, { color });
+      } catch { effects.showError('Failed to update color'); }
+    }
+    function stageArchive(id) {
+      const index = state.notes.findIndex(n => n.id === id);
+      if (index < 0) return null;
+      const removed = app.removeNoteAt(index);
+      const undo = () => undoArchive(removed, index);
+      pushUndo({ label: 'archive', run: undo });
+      return () => {
+        effects.render();
+        api.patchNote(id, { archived: true }).then(() => effects.archived(undo)).catch(() => {
+          app.insertNoteAt(index, removed); effects.render(); effects.showError('Failed to archive');
+        });
+      };
+    }
+    function unarchive(id) {
+      const index = state.notes.findIndex(n => n.id === id);
+      if (index < 0) return;
+      const removed = app.removeNoteAt(index);
+      effects.render();
+      api.patchNote(id, { archived: false }).then(() => effects.showToast('Unarchived')).catch(() => {
+        app.insertNoteAt(index, removed); effects.render(); effects.showError('Failed to unarchive');
+      });
+    }
+    function deleteOptimistically(id, toast = false) {
+      const index = state.notes.findIndex(n => n.id === id);
+      if (index < 0) return;
+      const removed = app.removeNoteAt(index);
+      effects.render();
+      const deletion = api.deleteNote(id);
+      const completion = toast ? deletion.then(() => effects.showToast('Deleted')) : deletion;
+      completion.catch(() => {
+        app.insertNoteAt(index, removed); effects.render(); effects.showError('Failed to delete');
+      });
+    }
+    // Desktop deliberately persists without updating local sort_order, as before.
+    function persistOrder(ids) { return api.reorder(ids); }
+    async function commitMobileOrder(ids) {
+      try {
+        await api.reorder(ids);
+        ids.forEach((id, index) => {
+          const note = state.notes.find(note => note.id === id);
+          if (note) app.mergeNote(note, { sort_order: index });
+        });
+      } catch (error) { console.warn('reorder failed', error); }
+    }
+    return { togglePin, updateColor, stageArchive, unarchive, deleteOptimistically, persistOrder, commitMobileOrder };
+}
diff --git a/frontend/src/features/notes/application/checklistOperations.js b/frontend/src/features/notes/application/checklistOperations.js
new file mode 100644
index 000000000..b4a596b04
--- /dev/null
+++ b/frontend/src/features/notes/application/checklistOperations.js
@@ -0,0 +1,68 @@
+/** Checklist item workflows. Supplied feedback callbacks update the invoking view. */
+export function createChecklistOperations({
+  app,
+  api,
+  effects,
+  uid
+}) {
+    const state = app.state;
+    function itemNote(id, index) {
+      const note = state.notes.find(n => n.id === id);
+      return note && Array.isArray(note.items) && note.items[index] ? note : null;
+    }
+    function removeItem(id, index) {
+      const note = itemNote(id, index);
+      if (!note) return;
+      const removed = note.items[index];
+      app.mergeNote(note, { items: note.items.filter((_, i) => i !== index) });
+      effects.render();
+      api.patchNote(id, { items: note.items }).catch(() => {
+        app.spliceItems(note, index, 0, removed); effects.render(); effects.showError('Failed to remove item');
+      });
+    }
+    function editItem(note, index, text) {
+      const oldText = (note.items[index].text || '').trim();
+      if (text === oldText) { effects.render(); return; }
+      const oldItem = note.items[index];
+      if (!text) app.spliceItems(note, index, 1);
+      else app.updateItem(note, index, { text });
+      api.patchNote(note.id, { items: note.items }).catch(() => {
+        if (!text) app.spliceItems(note, index, 0, oldItem);
+        else app.updateItem(note, index, { text: oldText });
+        effects.render(); effects.showError('Failed to update item');
+      });
+      effects.render();
+    }
+    function addItem(id, text, added) {
+      const note = state.notes.find(n => n.id === id);
+      if (!note) return;
+      const items = Array.isArray(note.items) ? [...note.items] : [];
+      items.push({ id: uid(), text, done: false });
+      app.mergeNote(note, { items });
+      added(); effects.render();
+      return () => api.patchNote(id, { items }).catch(() => {
+        app.mergeNote(note, { items: items.slice(0, -1) }); effects.render(); effects.showError('Failed to add item');
+      });
+    }
+    function toggleItem(id, index, changed, completed) {
+      const note = itemNote(id, index);
+      if (!note) return;
+      const wasDone = note.items.length > 0 && note.items.every(it => it.done);
+      app.updateItem(note, index, { done: !note.items[index].done });
+      changed(note.items[index].done);
+      if (!wasDone && note.items.length > 0 && note.items.every(it => it.done)) completed();
+      api.patchNote(id, { items: note.items }).catch(() => {
+        app.updateItem(note, index, { done: !note.items[index].done }); changed(note.items[index].done);
+      });
+    }
+    async function toggleTodayStep(id, index, changed, completed) {
+      const note = itemNote(id, index);
+      if (!note) return;
+      app.updateItem(note, index, { done: !note.items[index].done }); changed();
+      try {
+        await api.patchNote(id, { items: note.items }); effects.render();
+        if (note.items.every(it => it.done)) completed();
+      } catch { app.updateItem(note, index, { done: !note.items[index].done }); }
+    }
+    return { removeItem, editItem, addItem, toggleItem, toggleTodayStep };
+}
diff --git a/frontend/src/features/notes/application/deletion.js b/frontend/src/features/notes/application/deletion.js
new file mode 100644
index 000000000..e31e9b422
--- /dev/null
+++ b/frontend/src/features/notes/application/deletion.js
@@ -0,0 +1,51 @@
+/** Confirmed deletion and past-reminder clearing workflows. */
+export function createDeletion({
+  app,
+  _deleteNoteApi,
+  _fetchNotes,
+  _isPastReminder,
+  _renderNotes,
+  effects,
+  state
+}) {
+  async function _deleteNote(id) {
+    const ok = effects.styledConfirm
+      ? await effects.styledConfirm('Delete this note?', { confirmText: 'Delete', danger: true })
+      : effects.confirm('Delete this note?');
+    if (!ok) return;
+    try { await _deleteNoteApi(id); await _fetchNotes(); _renderNotes(); effects.showToast('Deleted'); }
+    catch (err) { effects.showError(err.message); }
+  }
+
+  async function _clearPastReminders() {
+    const targets = state.notes.filter(n => !n.archived && _isPastReminder(n));
+    if (!targets.length) {
+      effects.showToast?.('No past reminders to clear');
+      return;
+    }
+    const ok = effects.styledConfirm
+      ? await effects.styledConfirm(`Delete ${targets.length} past reminder${targets.length === 1 ? '' : 's'}?`, { confirmText: 'Delete', danger: true })
+      : effects.confirm(`Delete ${targets.length} past reminder${targets.length === 1 ? '' : 's'}?`);
+    if (!ok) return;
+    await Promise.all(targets.map(n => _deleteNoteApi(n.id).catch(() => {})));
+    await _fetchNotes();
+    _renderNotes();
+    effects.showToast?.(`Cleared ${targets.length} past reminder${targets.length === 1 ? '' : 's'}`);
+  }
+
+  async function deleteFromEditor(id) {
+    const ok = effects.styledConfirm
+      ? await effects.styledConfirm('Delete this note?', { confirmText: 'Delete', danger: true })
+      : effects.confirm('Delete this note?');
+    if (!ok) return;
+    const index = state.notes.findIndex(note => note.id === id);
+    if (index >= 0) app.removeNoteAt(index);
+    app.setEditingId(null);
+    _renderNotes();
+    _deleteNoteApi(id).then(() => effects.showToast('Deleted')).catch(() => {
+      effects.showError('Failed to delete');
+      _fetchNotes().then(() => _renderNotes());
+    });
+  }
+  return { _deleteNote, _clearPastReminders, deleteFromEditor };
+}
diff --git a/frontend/src/features/notes/application/drafts.js b/frontend/src/features/notes/application/drafts.js
new file mode 100644
index 000000000..4f7a4715d
--- /dev/null
+++ b/frontend/src/features/notes/application/drafts.js
@@ -0,0 +1,55 @@
+/** Serialized autosave and synchronous local draft backup. DOM collection is a supplied port. */
+export function createNotesDrafts({
+  app,
+  api,
+  persistence,
+  scheduler,
+  effects
+}) {
+  const state = app.state;
+  const { _draftKey, _clearDraft } = persistence;
+  function bindDraft({ collect, id, view }) {
+    let t = null;
+    let pending = Promise.resolve();
+    let stopped = false;
+    let warned = false;
+    const save = () => {
+      const d = collect();
+      // An empty edit can be intentional: don't restore stale server text over it.
+      try { persistence.setItem(_draftKey(id), JSON.stringify(d)); }
+      catch {
+        if (!warned) effects.showError('Draft backup unavailable. Keep this note open until saved.');
+        warned = true;
+      }
+      return d;
+    };
+    const persist = (d) => {
+      if (!id || id === '__new__' || d.note_type === 'draw') return pending;
+      const { _ts, ...payload } = d;
+      payload.label = [...new Set(payload.label.split(/\s+/).map(s => s.replace(/^#+/, '')).filter(Boolean))].join(' ') || null;
+      pending = pending.then(async () => {
+        try {
+          await api.patchNote(id, payload);
+          view.failed = false;
+          const note = state.notes.find(n => n.id === id);
+          if (note) app.mergeNote(note, payload);
+          if (persistence.getItem(_draftKey(id)) === JSON.stringify(d)) _clearDraft(id);
+        } catch {
+          if (!view.failed) effects.showError('Note not synced. Your edits are kept on this device; retry Save.');
+          view.failed = true;
+        }
+      });
+      return pending;
+    };
+    const flush = () => { scheduler.clearTimeout(t); return save(); };
+    const stop = () => { stopped = true; scheduler.clearTimeout(t); return pending; };
+    const sched = () => {
+      const d = save();
+      if (stopped) return;
+      scheduler.clearTimeout(t);
+      t = scheduler.setTimeout(() => persist(d), 500);
+    };
+    return { flush, stop, schedule: sched };
+  }
+  return { bindDraft };
+}
diff --git a/frontend/src/features/notes/application/queries.js b/frontend/src/features/notes/application/queries.js
new file mode 100644
index 000000000..6a92250c9
--- /dev/null
+++ b/frontend/src/features/notes/application/queries.js
@@ -0,0 +1,66 @@
+/** Application-owned filtering, searching and note ordering. */
+import { _noteTags, _visibleNoteTags, _nextGoalStep, _isCalendarReminderNote } from '../domain/noteRules.js';
+import { _hasTimeComponent } from '../domain/recurrence.js';
+export function createQueries({
+  _hasActiveReminder,
+  state
+}) {
+  function _sortedVisibleNotes() {
+    const displayNotes = _userVisibleNotes();
+    let filtered = state.activeLabel ? displayNotes.filter(n => _noteTags(n).includes(state.activeLabel)) : displayNotes;
+    if (state.activeFilter === 'reminders') {
+      filtered = filtered.filter(n => n.due_date && _hasTimeComponent(n.due_date));
+    } else if (state.activeFilter === 'no-reminders') {
+      filtered = filtered.filter(n => !(n.due_date && _hasTimeComponent(n.due_date)));
+    } else if (state.activeFilter === 'default') {
+      filtered = filtered.filter(n => _visibleNoteTags(n).length === 0);
+    } else if (state.activeFilter === 'goals') {
+      filtered = filtered.filter(n => n.note_type === 'goal' && !n.archived);
+    } else if (state.activeFilter === 'today') {
+      // Today view: only goals that still have an unchecked step.
+      filtered = filtered.filter(n => n.note_type === 'goal' && !n.archived && _nextGoalStep(n));
+    }
+    if (state.searchQuery) {
+      filtered = filtered.filter(n => {
+        const q = state.searchQuery;
+        if ((n.title || '').toLowerCase().includes(q)) return true;
+        if ((n.content || '').toLowerCase().includes(q)) return true;
+        if ((n.label || '').toLowerCase().includes(q)) return true;
+        if (Array.isArray(n.items) && n.items.some(it => (it.text || '').toLowerCase().includes(q))) return true;
+        return false;
+      });
+    }
+    const sorted = [...filtered].sort((a, b) => {
+      // In reminders view: sort by due date ascending (soonest first)
+      if (state.activeFilter === 'reminders') {
+        const da = new Date(a.due_date || 0).getTime();
+        const db = new Date(b.due_date || 0).getTime();
+        return da - db;
+      }
+      // Archived view: newest archived first (ignore manual sort_order).
+      if (state.showingArchived) {
+        return new Date(b.updated_at || 0) - new Date(a.updated_at || 0);
+      }
+      if (a.pinned && !b.pinned) return -1;
+      if (!a.pinned && b.pinned) return 1;
+      // Active reminders (due date in the past, not done/archived) rank
+      // immediately under the pinned block.
+      const aActive = _hasActiveReminder(a);
+      const bActive = _hasActiveReminder(b);
+      if (aActive && !bActive) return -1;
+      if (!aActive && bActive) return 1;
+      const so = (a.sort_order || 0) - (b.sort_order || 0);
+      if (so !== 0) return so;
+      return new Date(b.updated_at || 0) - new Date(a.updated_at || 0);
+    });
+
+
+  return sorted;
+  }
+
+  function _userVisibleNotes() {
+    return state.notes.filter(n => !_isCalendarReminderNote(n));
+  }
+
+  return { _sortedVisibleNotes, _userVisibleNotes };
+}
diff --git a/frontend/src/features/notes/application/reminders.js b/frontend/src/features/notes/application/reminders.js
new file mode 100644
index 000000000..5e2475993
--- /dev/null
+++ b/frontend/src/features/notes/application/reminders.js
@@ -0,0 +1,182 @@
+/** Page-owned reminder scheduler and notification delivery workflow. */
+import { _hasTimeComponent, _isDueTodayOrOverdue, _advanceRecurring } from '../domain/recurrence.js';
+export function createNotesReminders({
+  app,
+  api,
+  persistence,
+  notifications,
+  clock,
+  scheduler,
+  effects,
+  fetchNotes,
+  isNoteFullyDone,
+  hasItems,
+  dismissedKey
+}) {
+  const state = app.state;
+  const { _loadFiredReminders, _saveFiredReminders } = persistence;
+  const _patchNote = api.patchNote;
+  const _fetchNotes = fetchNotes;
+  const _isNoteFullyDone = isNoteFullyDone;
+  const _hasItems = hasItems;
+  const REMINDER_DISMISSED_AT_KEY = dismissedKey;
+  const _updateRailBadge = effects.badge;
+  let _reminderTimer = null;
+  let startupTimer = null;
+  let started = false;
+  let disposed = false;
+  function _checkReminders() {
+    if (!state.notes.length) return;
+    const now = clock.now();
+    const fired = _loadFiredReminders();
+    let changed = false;
+    for (const note of state.notes) {
+      if (!note.due_date || note.archived) continue;
+      if (!_hasTimeComponent(note.due_date)) continue;
+      if (fired.has(note.id)) continue;
+      const due = new Date(note.due_date).getTime();
+      if (isNaN(due)) continue;
+      if (due <= now && due > now - 60000) {
+        _fireReminder(note);
+        // Recurring? advance the due_date instead of marking as fired
+        if (note.repeat && note.repeat !== 'none') {
+          const next = _advanceRecurring(note.due_date, note.repeat, clock);
+          if (next) {
+            app.mergeNote(note, { due_date: next });
+            _patchNote(note.id, { due_date: next }).catch(() => {});
+            // Don't add to fired : new due_date is in the future
+            continue;
+          }
+        }
+        fired.add(note.id);
+        changed = true;
+      } else if (due <= now - 60000) {
+        // Past, never seen : silently advance recurring or mark fired
+        if (note.repeat && note.repeat !== 'none') {
+          const next = _advanceRecurring(note.due_date, note.repeat, clock);
+          if (next) {
+            app.mergeNote(note, { due_date: next });
+            _patchNote(note.id, { due_date: next }).catch(() => {});
+            continue;
+          }
+        }
+        fired.add(note.id);
+        changed = true;
+      }
+    }
+    if (changed) _saveFiredReminders(fired);
+    // Always refresh badge : fired state may have changed visually without note mutation
+    _updateRailBadge();
+  }
+
+  function _fireReminder(note) {
+    const title = note.title || 'Note reminder';
+    // Include the verbatim note content so the email/notification actually
+    // shows what to do, not just a count. Cap the per-item lines (8 max) and
+    // total length so the body stays inbox-friendly.
+    let rawBody;
+    if (_hasItems(note)) {
+      const pending = (note.items || [])
+        .filter(i => !i.done && !i.checked)
+        .map(i => (i.text || '').trim())
+        .filter(Boolean);
+      if (pending.length) {
+        const shown = pending.slice(0, 8).map(t => `- ${t}`).join('\n');
+        const extra = pending.length > 8 ? `\n…and ${pending.length - 8} more` : '';
+        rawBody = `Pending (${pending.length}):\n${shown}${extra}`;
+      } else {
+        rawBody = `${(note.items || []).length} item${(note.items || []).length === 1 ? '' : 's'}`;
+      }
+    } else {
+      rawBody = (note.content || '').slice(0, 400);
+    }
+
+    // Ask the server to dispatch according to user settings. The server may
+    // return an LLM-written synthesis line and/or send an email. We still show
+    // a local browser notification so the user gets immediate feedback even if
+    // the server path is disabled or slow.
+    const showLocal = body => notifications.show(title, body, note.id);
+
+    // Fire-and-forget server dispatch. If synthesis comes back quickly enough,
+    // use it as the notification body; otherwise the local notification has
+    // already shown with the raw body.
+    let shown = false;
+    const timer = scheduler.setTimeout(() => { if (!shown) { shown = true; showLocal(rawBody); } }, 1500);
+
+    api.fireReminder({ note_id: note.id, title, body: rawBody })
+      .then(r => r.ok ? r.json() : null)
+      .then(data => {
+        scheduler.clearTimeout(timer);
+        if (shown) return;
+        shown = true;
+        const body = (data && data.synthesis) ? data.synthesis : rawBody;
+        showLocal(body);
+      })
+      .catch(() => {
+        scheduler.clearTimeout(timer);
+        if (!shown) { shown = true; showLocal(rawBody); }
+      });
+
+    // Pulse the card if visible; otherwise queue it so the next time the user
+    // opens the notes panel the card gets a brief glow.
+    effects.highlight(note.id);
+  }
+
+  function _startReminderLoop() {
+    if (disposed || _reminderTimer) return;
+    _reminderTimer = scheduler.setInterval(_checkReminders, 30000);
+    _checkReminders(); // run once immediately
+  }
+
+  function _countDueReminders() {
+    return state.notes.filter(n => !n.archived && _isDueTodayOrOverdue(n.due_date, clock) && !_isNoteFullyDone(n)).length;
+  }
+
+  function _countFiredReminders() {
+    // Reminders whose time has actually passed (not just date-today),
+    // and which fired after the last user dismissal.
+    const now = clock.now();
+    return state.notes.filter(n => {
+      if (n.archived || _isNoteFullyDone(n)) return false;
+      if (!n.due_date || !_hasTimeComponent(n.due_date)) return false;
+      const t = new Date(n.due_date).getTime();
+      if (isNaN(t) || t > now) return false;
+      return t > state.firedDotDismissedAt;
+    }).length;
+  }
+
+  function dismissFiredReminderDot() {
+    app.setFiredDotDismissedAt(clock.now());
+    try { persistence.setItem(REMINDER_DISMISSED_AT_KEY, String(state.firedDotDismissedAt)); } catch {}
+    _updateRailBadge();
+  }
+
+  async function refreshDueBadge(opts = {}) {
+    // Usually lightweight, but callers that just created a note reminder can
+    // force a refresh so the background reminder loop sees it immediately.
+    if (opts.force || state.notes.length === 0) {
+      try {
+        const wasArchived = state.showingArchived;
+        app.setShowingArchived(false);
+        await _fetchNotes();
+        app.setShowingArchived(wasArchived);
+      } catch {}
+    }
+    _updateRailBadge();
+  }
+
+  async function _initReminders() {
+    try {
+      const res = await api.listNotes(false);
+      if (res.ok && !disposed) {
+        const data = await res.json();
+        app.replaceNotes(data.notes || data || []);
+        _startReminderLoop();
+      }
+    } catch {}
+  }
+
+  function start() { if (started || disposed) return; started = true; startupTimer = scheduler.setTimeout(_initReminders, 3000); }
+  function dispose() { disposed = true; scheduler.clearTimeout(startupTimer); scheduler.clearInterval(_reminderTimer); _reminderTimer = null; }
+  return { start, dispose, _checkReminders, _fireReminder, _startReminderLoop, _countDueReminders, _countFiredReminders, dismissFiredReminderDot, refreshDueBadge, _initReminders };
+}
diff --git a/frontend/src/features/notes/application/selection.js b/frontend/src/features/notes/application/selection.js
new file mode 100644
index 000000000..6017025e2
--- /dev/null
+++ b/frontend/src/features/notes/application/selection.js
@@ -0,0 +1,39 @@
+/** Selected-note attachment retains synchronous acceptance; bulk requests retain partial-failure behavior. */
+export function createSelectionOperations({
+  app,
+  api,
+  effects,
+  sendContext,
+  exitSelection,
+  fetchNotes
+}) {
+    const state = app.state;
+    function attachSelected() {
+      const ids = [...state.selectedIds];
+      if (!ids.length) return;
+      const detail = { noteIds: ids, accepted: false };
+      sendContext(detail);
+      if (!detail.accepted) {
+        effects.showToast('Choose a chat or model before attaching notes');
+        return;
+      }
+      exitSelection();
+    }
+    async function archiveSelected() {
+      const ids = [...state.selectedIds];
+      if (!ids.length) return;
+      await Promise.all(ids.map(id => api.patchNote(id, { archived: true }).catch(() => {})));
+      exitSelection(); await fetchNotes(); effects.render(); effects.showToast(`Archived ${ids.length}`);
+    }
+    async function deleteSelected() {
+      const ids = [...state.selectedIds];
+      if (!ids.length) return;
+      if (effects.styledConfirm) {
+        const ok = await effects.styledConfirm(`Delete ${ids.length} note${ids.length === 1 ? '' : 's'}?`, { confirmText: 'Delete', danger: true });
+        if (!ok) return;
+      }
+      await Promise.all(ids.map(id => api.deleteNote(id).catch(() => {})));
+      exitSelection(); await fetchNotes(); effects.render(); effects.showToast(`Deleted ${ids.length}`);
+    }
+    return { attachSelected, archiveSelected, deleteSelected };
+}
diff --git a/frontend/src/features/notes/application/state.js b/frontend/src/features/notes/application/state.js
new file mode 100644
index 000000000..b87ef11c4
--- /dev/null
+++ b/frontend/src/features/notes/application/state.js
@@ -0,0 +1,83 @@
+/** The sole Notes state owner. Views have live read-only access; writes use operations. */
+export function createNotesState(initial = {}) {
+    const values = {
+      open: false, notes: [], editingId: null, selectedIds: new Set(),
+      activeLabel: null, activeFilter: null, reminderChipNext: 'reminders', searchQuery: '',
+      viewMode: initial.viewMode || 'list', showingArchived: false, selectMode: false,
+      suppressNextNoteTapId: null, labelsCollapsed: !!initial.labelsCollapsed,
+      loading: false, firedDotDismissedAt: initial.firedDotDismissedAt || 0,
+    };
+    // Preserve captured note identity across asynchronous completions without
+    // giving a view a writable reference to the application store.
+    const views = new WeakMap(), targets = new WeakMap();
+    const unwrap = value => targets.get(value) || value;
+    // Copies built from views (spread, filter, map) still hold nested views;
+    // store only raw data so the owner never keeps its own read-only views.
+    function unwrapDeep(value, seen = new WeakSet()) {
+      if (!value || typeof value !== 'object') return value;
+      if (targets.has(value)) return targets.get(value);
+      if (seen.has(value)) return value;
+      seen.add(value);
+      if (Array.isArray(value)) value.forEach((item, index) => { value[index] = unwrapDeep(item, seen); });
+      else if (Object.getPrototypeOf(value) === Object.prototype) for (const key of Object.keys(value)) value[key] = unwrapDeep(value[key], seen);
+      return value;
+    }
+    function readonly(value) {
+      if (!value || typeof value !== 'object') return value;
+      if (targets.has(value)) return value;
+      if (views.has(value)) return views.get(value);
+      const view = new Proxy(value, {
+        get(target, key) {
+          if (target instanceof Set) {
+            if (['add', 'delete', 'clear'].includes(key)) return () => { throw new TypeError('Use Notes selection operations'); };
+            if (key === 'valueOf') return () => views.get(target);
+            if (key === 'forEach') return (callback, thisArg) => target.forEach(value => callback.call(thisArg, value, value, views.get(target)));
+            const member = Reflect.get(target, key, target);
+            return typeof member === 'function' ? member.bind(target) : member;
+          }
+          return readonly(Reflect.get(target, key));
+        },
+        set() { throw new TypeError('Use Notes state operations'); },
+        deleteProperty() { throw new TypeError('Use Notes state operations'); },
+        defineProperty() { throw new TypeError('Use Notes state operations'); },
+        setPrototypeOf() { throw new TypeError('Use Notes state operations'); },
+        preventExtensions() { throw new TypeError('Use Notes state operations'); },
+        getOwnPropertyDescriptor(target, key) {
+          const descriptor = Reflect.getOwnPropertyDescriptor(target, key);
+          if (descriptor && 'value' in descriptor) return { ...descriptor, value: readonly(descriptor.value) };
+          return descriptor;
+        },
+      });
+      views.set(value, view); targets.set(view, value);
+      return view;
+    }
+    const state = Object.freeze(Object.fromEntries(Object.keys(values).map(key => [key, () => readonly(values[key])])));
+    const view = Object.freeze(Object.defineProperties({}, Object.fromEntries(Object.entries(state).map(([key, get]) => [key, { get, enumerable: true }]))));
+    return {
+      state: view,
+      setOpen: value => { values.open = value; },
+      setEditingId: value => { values.editingId = value; },
+      setActiveLabel: value => { values.activeLabel = value; },
+      setActiveFilter: value => { values.activeFilter = value; },
+      setReminderChipNext: value => { values.reminderChipNext = value; },
+      setSearchQuery: value => { values.searchQuery = value; },
+      setViewMode: value => { values.viewMode = value; },
+      setShowingArchived: value => { values.showingArchived = value; },
+      setSelectMode: value => { values.selectMode = value; },
+      setSuppressNextNoteTapId: value => { values.suppressNextNoteTapId = value; },
+      setLabelsCollapsed: value => { values.labelsCollapsed = value; },
+      setLoading: value => { values.loading = value; },
+      setFiredDotDismissedAt: value => { values.firedDotDismissedAt = value; },
+      replaceNotes: notes => { values.notes = notes; },
+      removeNoteAt: index => readonly(values.notes.splice(index, 1)[0]),
+      insertNoteAt: (index, note) => { values.notes.splice(index, 0, unwrapDeep(note)); },
+      prependNote: note => { values.notes.unshift(unwrapDeep(note)); },
+      replaceNoteAt: (index, note) => { values.notes[index] = unwrapDeep(note); },
+      mergeNote: (note, patch) => { for (const [key, value] of Object.entries(patch)) unwrap(note)[key] = unwrapDeep(value); },
+      updateItem: (note, index, patch) => { Object.assign(unwrap(unwrap(note).items[index]), unwrapDeep({ ...patch })); },
+      spliceItems: (note, ...args) => unwrap(unwrap(note).items).splice(...args.map(arg => unwrapDeep(arg))),
+      selectId: id => { values.selectedIds.add(id); },
+      deselectId: id => values.selectedIds.delete(id),
+      clearSelection: () => values.selectedIds.clear(),
+    };
+}
diff --git a/frontend/src/features/notes/application/submission.js b/frontend/src/features/notes/application/submission.js
new file mode 100644
index 000000000..4703eb7c1
--- /dev/null
+++ b/frontend/src/features/notes/application/submission.js
@@ -0,0 +1,69 @@
+/** Editor submission ordering, optimistic state, reminder rearming and save recovery. */
+export function createNotesSubmission({
+  app,
+  api,
+  persistence,
+  clock,
+  uid,
+  effects,
+  fetchNotes
+}) {
+  const state = app.state;
+  const { _loadFiredReminders, _saveFiredReminders, _loadGlowedReminders, _saveGlowedReminders, _loadDraft, _clearDraft } = persistence;
+  function submitNote(payload, note, isEdit) {
+      // Reset fired reminder if due_date changed (so re-arm works), and also
+      // clear the entry-glow seen flag so the new firing glows again on the
+      // next time the user opens the panel.
+      if (isEdit && note.due_date !== payload.due_date) {
+        const fired = _loadFiredReminders();
+        fired.delete(note.id);
+        _saveFiredReminders(fired);
+        const glowed = _loadGlowedReminders();
+        glowed.delete(note.id);
+        _saveGlowedReminders(glowed);
+        effects.clearGlow(note.id);
+      }
+      // Edited notes move to the top of their section (under pinned). Compute
+      // sort_order = (min unpinned sort_order) - 1 so the saved note sorts above
+      // siblings; the pin block keeps its own ordering above this.
+      if (!payload.pinned) {
+        // Both edits AND newly-created notes anchor above the rest of the
+        // unpinned section. Without this, freshly created notes sit at the
+        // bottom because manually-reordered siblings already carry negative
+        // sort_order values.
+        const minUnpinned = state.notes
+          .filter(n => !n.pinned && (!isEdit || n.id !== note.id))
+          .reduce((m, n) => Math.min(m, n.sort_order || 0), 0);
+        payload.sort_order = minUnpinned - 1;
+      }
+      // Optimistic update : update local state first, render, then save in background
+      app.setEditingId(null);
+      const draftId = isEdit ? note.id : '__new__';
+      const submittedDraft = JSON.stringify(_loadDraft(draftId));
+      if (isEdit) {
+        const idx = state.notes.findIndex(n => n.id === note.id);
+        if (idx >= 0) app.replaceNoteAt(idx, { ...state.notes[idx], ...payload });
+      } else {
+        app.prependNote({ ...payload, id: 'tmp_' + uid(), created_at: new Date(clock.now()).toISOString(), updated_at: new Date(clock.now()).toISOString() });
+      }
+      effects.render();
+      // Background save
+      api.saveNote(payload).then(saved => {
+        if (JSON.stringify(_loadDraft(draftId)) === submittedDraft) _clearDraft(draftId);
+        if (!isEdit && saved && saved.id) {
+          // Replace temp ID with real one from server. AND re-render : the
+          // existing card's `data-note-id="tmp_xxx"` is stale after Object.assign
+          // bumps the in-memory id, so all subsequent clicks (edit, done, copy,
+          // archive, delete) silently fail to find the note in `_notes`.
+          const tmp = state.notes.find(n => n.id.startsWith('tmp_'));
+          if (tmp) app.mergeNote(tmp, saved);
+          effects.render();
+        }
+      }).catch(err => {
+        effects.showError('Save failed: ' + err.message);
+        fetchNotes().then(() => effects.render());
+      });
+
+  }
+  return { submitNote };
+}
diff --git a/frontend/src/features/notes/application/workflows.js b/frontend/src/features/notes/application/workflows.js
new file mode 100644
index 000000000..018cbf8aa
--- /dev/null
+++ b/frontend/src/features/notes/application/workflows.js
@@ -0,0 +1,78 @@
+/** Notes CRUD, optimistic archive and in-memory undo workflows. */
+export function createNotesWorkflows({
+  app,
+  api,
+  effects
+}) {
+  const state = app.state;
+  const _undoStack = [];
+  const _renderNotes = effects.render;
+  const _patchNote = api.patchNote;
+  const uiModule = effects;
+  function _pushUndo(entry) {
+    _undoStack.push(entry);
+    if (_undoStack.length > 20) _undoStack.shift();
+  }
+
+  function _popAndRunUndo() {
+    const entry = _undoStack.pop();
+    if (entry) entry.run();
+    return !!entry;
+  }
+
+  function _undoArchive(note, prevIdx) {
+    // Re-insert at original position and clear archived flag on the server.
+    const safeIdx = Math.min(Math.max(prevIdx, 0), state.notes.length);
+    app.insertNoteAt(safeIdx, { ...note, archived: false });
+    _renderNotes();
+    _patchNote(note.id, { archived: false }).catch(() => {
+      // Roll back local insertion if the server refuses
+      const i = state.notes.findIndex(n => n.id === note.id);
+      if (i >= 0) app.removeNoteAt(i);
+      _renderNotes();
+      uiModule.showError('Undo failed');
+    });
+  }
+
+  function _archiveNoteById(id, { card = null, celebrate = false } = {}) {
+    if (!id) return false;
+    const idx = state.notes.findIndex(n => n.id === id);
+    if (idx < 0) return false;
+    const note = state.notes[idx];
+    if (celebrate && card && note) effects.celebrateArchive(note, card);
+    const removed = app.removeNoteAt(idx);
+    app.setEditingId(null);
+    _renderNotes();
+    const undo = () => _undoArchive(removed, idx);
+    _pushUndo({ label: 'archive', run: undo });
+    _patchNote(id, { archived: true }).then(() => {
+      effects.archived(undo);
+    }).catch(() => {
+      app.insertNoteAt(idx, removed);
+      _renderNotes();
+      uiModule.showError('Failed to archive');
+    });
+    return true;
+  }
+
+  async function _fetchNotes() {
+    app.setLoading(true);
+    try {
+      const res = await api.listNotes(state.showingArchived);
+      if (!res.ok) { app.replaceNotes([]); return; }
+      const data = await res.json();
+      app.replaceNotes(data.notes || data || []);
+    } catch (e) {
+      console.error('Failed to fetch notes:', e);
+      app.replaceNotes([]);
+    } finally {
+      app.setLoading(false);
+    }
+  }
+
+  function _saveNote(note) { return api.saveNote(note); }
+
+  function _deleteNoteApi(id) { return api.deleteNote(id); }
+
+  return { _pushUndo, _popAndRunUndo, _undoArchive, _archiveNoteById, _fetchNotes, _saveNote, _deleteNoteApi, _patchNote, undoCount: () => _undoStack.length };
+}
diff --git a/frontend/src/features/notes/domain/noteRules.js b/frontend/src/features/notes/domain/noteRules.js
new file mode 100644
index 000000000..ba3f8ae2f
--- /dev/null
+++ b/frontend/src/features/notes/domain/noteRules.js
@@ -0,0 +1,87 @@
+/** Pure Notes completion, tags, reminder and serialization rules. */
+import { _hasTimeComponent } from './recurrence.js';
+export function _isCalendarReminderNote(n) {
+  return n && n.source === 'calendar' && n.label === 'calendar';
+}
+
+export function _hasActiveReminder(n, clock) {
+  if (!n || n.archived || _isNoteFullyDone(n)) return false;
+  if (!n.due_date) return false;
+  const t = new Date(n.due_date).getTime();
+  return !isNaN(t) && t <= clock.now();
+}
+
+export function _isNoteFullyDone(note) {
+  if (_hasItems(note) && Array.isArray(note.items) && note.items.length > 0) {
+    return note.items.every(it => it.done);
+  }
+  return false;
+}
+
+export function _hasItems(note) {
+  return note && (note.note_type === 'todo' || note.note_type === 'goal' || note.note_type === 'checklist');
+}
+
+export function _goalProgress(note) {
+  if (!Array.isArray(note?.items) || note.items.length === 0) return '';
+  const done = note.items.filter(it => it.done).length;
+  return ` ${done}/${note.items.length}`;
+}
+
+export function _nextGoalStep(note) {
+  if (!Array.isArray(note?.items)) return null;
+  for (let i = 0; i < note.items.length; i++) {
+    if (!note.items[i].done) return { idx: i, item: note.items[i] };
+  }
+  return null;
+}
+
+export function _noteTags(n) {
+  const tags = [];
+  if (n?.label) tags.push(...n.label.trim().split(/\s+/).filter(Boolean));
+  if (n?.due_date && _hasTimeComponent(n.due_date)) tags.push('reminder');
+  return [...new Set(tags.map(t => t.replace(/^#+/, '').trim()).filter(Boolean))];
+}
+
+export function _visibleNoteTags(n) {
+  return _noteTags(n).filter(t => t !== 'reminder');
+}
+
+export function _isPastReminder(n, clock) {
+  if (!n?.due_date || !_hasTimeComponent(n.due_date)) return false;
+  const due = new Date(n.due_date).getTime();
+  return !isNaN(due) && due <= clock.now();
+}
+
+export function _serializeNoteForCopy(note) {
+  const lines = [];
+  if (note.title) lines.push(note.title);
+  if (note.content) lines.push(note.content);
+  if (Array.isArray(note.items) && note.items.length) {
+    if (lines.length) lines.push('');
+    for (const it of note.items) {
+      if (!it || !(it.text || '').trim()) continue;
+      lines.push(`- [${it.done ? 'x' : ' '}] ${(it.text || '').trim()}`);
+    }
+  }
+  return lines.join('\n').trim();
+}
+
+export function _noteToAgentPrompt(note) {
+  const parts = [];
+  if ((note.title || '').trim()) parts.push(note.title.trim());
+  if ((note.content || '').trim()) parts.push(note.content.trim());
+  if (Array.isArray(note.items)) {
+    note.items.filter(it => !it.done && (it.text || '').trim())
+      .forEach(it => parts.push('- ' + it.text.trim()));
+  }
+  const body = parts.join('\n');
+  return body ? `Help me get this done:\n\n${body}\n\nThe source note is read-only. Do not edit, replace, or update it.` : '';
+}
+
+export function _standardVisualVariant(note) {
+  const source = String(note?.id || note?.title || note?.created_at || 'standard-note');
+  let hash = 0;
+  for (let i = 0; i < source.length; i++) hash = ((hash << 5) - hash + source.charCodeAt(i)) | 0;
+  return Math.abs(hash) % 5;
+}
diff --git a/frontend/src/features/notes/domain/recurrence.js b/frontend/src/features/notes/domain/recurrence.js
new file mode 100644
index 000000000..f72498fbb
--- /dev/null
+++ b/frontend/src/features/notes/domain/recurrence.js
@@ -0,0 +1,269 @@
+// Local-time date and recurrence rules. Callers supply the clock at the original read sites.
+export const _ORDINALS = ['1st', '2nd', '3rd', '4th', '5th'];
+export const _DAYS = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'];
+export function _hasTimeComponent(dateStr) {
+  return typeof dateStr === 'string' && /T\d{2}:\d{2}/.test(dateStr);
+}
+
+export function _formatDueDate(dateStr, clock) {
+  if (!dateStr) return '';
+  const d = new Date(dateStr);
+  if (isNaN(d)) return '';
+  const now = new Date(clock.now());
+  const hasTime = _hasTimeComponent(dateStr);
+  const today = new Date(now.getFullYear(), now.getMonth(), now.getDate());
+  const due = new Date(d.getFullYear(), d.getMonth(), d.getDate());
+  const diffDays = Math.round((due - today) / 86400000);
+  const timeStr = hasTime ? d.toLocaleTimeString([], { hour: 'numeric', minute: '2-digit' }) : '';
+  if (hasTime && d < now) return 'overdue';
+  if (!hasTime && diffDays < 0) return 'overdue';
+  if (diffDays === 0) return hasTime ? timeStr : 'today';
+  if (diffDays === 1) return hasTime ? `tmrw ${timeStr}` : 'tomorrow';
+  const dateLabel = d.toLocaleDateString([], { month: 'short', day: 'numeric' });
+  return hasTime ? `${dateLabel} ${timeStr}` : dateLabel;
+}
+
+export function _isDueOverdue(dateStr, clock) {
+  if (!dateStr) return false;
+  const d = new Date(dateStr);
+  if (isNaN(d)) return false;
+  if (_hasTimeComponent(dateStr)) return d < new Date(clock.now());
+  return d < new Date(new Date(clock.now()).toDateString());
+}
+
+export function _isDueTodayOrOverdue(dateStr, clock) {
+  if (!dateStr) return false;
+  const d = new Date(dateStr);
+  const now = new Date(clock.now());
+  const today = new Date(now.getFullYear(), now.getMonth(), now.getDate());
+  const due = new Date(d.getFullYear(), d.getMonth(), d.getDate());
+  return due <= today;
+}
+
+export function _laterTodayDate(clock) {
+  const now = new Date(clock.now());
+  const eight = new Date(now.getFullYear(), now.getMonth(), now.getDate(), 18, 0); // 6pm today
+  // If less than 1 hour before 6pm, push to "in 3 hours" instead
+  if (eight - now < 60 * 60 * 1000) return new Date(now.getTime() + 3 * 60 * 60 * 1000);
+  return eight;
+}
+
+export function _tomorrowDate(clock) {
+  const t = new Date(clock.now());
+  t.setDate(t.getDate() + 1);
+  t.setHours(8, 0, 0, 0);
+  return t;
+}
+
+export function _nextWeekDate(clock) {
+  const t = new Date(clock.now());
+  const daysUntilMon = (8 - t.getDay()) % 7 || 7;
+  t.setDate(t.getDate() + daysUntilMon);
+  t.setHours(8, 0, 0, 0);
+  return t;
+}
+
+export function _toLocalDatetimeStr(d) {
+  // Format as YYYY-MM-DDTHH:MM (local, no TZ)
+  const pad = n => String(n).padStart(2, '0');
+  return `${d.getFullYear()}-${pad(d.getMonth()+1)}-${pad(d.getDate())}T${pad(d.getHours())}:${pad(d.getMinutes())}`;
+}
+
+export function _formatReminderTag(dateStr, clock) {
+  if (!dateStr) return '';
+  const d = new Date(dateStr);
+  if (isNaN(d)) return '';
+  const now = new Date(clock.now());
+  const sameDay = d.toDateString() === now.toDateString();
+  const tomorrow = new Date(now); tomorrow.setDate(tomorrow.getDate() + 1);
+  const isTomorrow = d.toDateString() === tomorrow.toDateString();
+  const time = d.toLocaleTimeString([], { hour: 'numeric', minute: '2-digit' });
+  if (sameDay) return `Today, ${time}`;
+  if (isTomorrow) return `Tomorrow, ${time}`;
+  const dateLabel = d.toLocaleDateString([], { month: 'short', day: 'numeric' });
+  return `${dateLabel}, ${time}`;
+}
+
+export function _nthWeekdayLabel(d) {
+  const n = Math.ceil(d.getDate() / 7); // 1..5
+  return `${_ORDINALS[n - 1] || `${n}th`} ${_DAYS[d.getDay()]}`;
+}
+
+export function _isLastWeekdayOfMonth(d) {
+  const test = new Date(d);
+  test.setDate(d.getDate() + 7);
+  return test.getMonth() !== d.getMonth();
+}
+
+export function _nthWeekdayOfMonth(year, month, weekday, n) {
+  const first = new Date(year, month, 1);
+  const offset = (weekday - first.getDay() + 7) % 7;
+  let day = 1 + offset + (n - 1) * 7;
+  // Last day of month
+  const lastDay = new Date(year, month + 1, 0).getDate();
+  if (day > lastDay) day -= 7;
+  return new Date(year, month, day, 0, 0, 0);
+}
+
+export function _lastWeekdayOfMonth(year, month, weekday) {
+  const lastDay = new Date(year, month + 1, 0);
+  const back = (lastDay.getDay() - weekday + 7) % 7;
+  return new Date(year, month, lastDay.getDate() - back, 0, 0, 0);
+}
+
+export function _snapToRepeat(currentDate, normRepeat, clock) {
+  const hh = currentDate.getHours();
+  const mm = currentDate.getMinutes();
+  const now = clock.now();
+  const anchor = currentDate.getTime() > now ? currentDate : new Date(clock.now());
+  const parts = normRepeat.split(':');
+  const kind = parts[0];
+  if (kind === 'weekly') {
+    const targetWd = parseInt(parts[1], 10);
+    if (isNaN(targetWd)) return null;
+    const d = new Date(anchor.getFullYear(), anchor.getMonth(), anchor.getDate(), hh, mm, 0, 0);
+    const delta = (targetWd - d.getDay() + 7) % 7;
+    d.setDate(d.getDate() + delta);
+    if (d.getTime() <= now) d.setDate(d.getDate() + 7);
+    return d;
+  }
+  if (kind === 'monthly') {
+    const sub = parts[1];
+    let y = anchor.getFullYear();
+    let m = anchor.getMonth();
+    // Walk forward up to 14 months to find the next matching slot.
+    for (let tries = 0; tries < 14; tries++) {
+      let target;
+      if (sub === 'day') {
+        const wantDay = parseInt(parts[2], 10);
+        if (isNaN(wantDay)) return null;
+        const lastDay = new Date(y, m + 1, 0).getDate();
+        target = new Date(y, m, Math.min(wantDay, lastDay));
+      } else if (sub === 'nth') {
+        const n = parseInt(parts[2], 10);
+        const wd = parseInt(parts[3], 10);
+        if (isNaN(n) || isNaN(wd)) return null;
+        target = _nthWeekdayOfMonth(y, m, wd, n);
+      } else if (sub === 'last') {
+        const wd = parseInt(parts[2], 10);
+        if (isNaN(wd)) return null;
+        target = _lastWeekdayOfMonth(y, m, wd);
+      } else {
+        return null;
+      }
+      target.setHours(hh, mm, 0, 0);
+      if (target.getTime() > now && target.getTime() >= anchor.getTime()) return target;
+      m++;
+      if (m > 11) { m = 0; y++; }
+    }
+    return null;
+  }
+  return null;
+}
+
+export function _formatRepeatLabel(repeat, originalDate) {
+  if (!repeat || repeat === 'none') return '';
+  const norm = _normalizeRepeat(repeat, originalDate);
+  if (norm === 'daily') return 'Daily';
+  if (norm === 'yearly') return 'Yearly';
+  const parts = norm.split(':');
+  if (parts[0] === 'weekly') {
+    const wd = parseInt(parts[1], 10);
+    if (isNaN(wd)) return 'Weekly';
+    return `Weekly on ${_DAYS[wd]}s`;
+  }
+  if (parts[0] === 'monthly') {
+    if (parts[1] === 'day') return `Monthly on day ${parts[2]}`;
+    if (parts[1] === 'nth') {
+      const n = parseInt(parts[2], 10);
+      const wd = parseInt(parts[3], 10);
+      return `Monthly on ${_ORDINALS[n - 1] || `${n}th`} ${_DAYS[wd]}`;
+    }
+    if (parts[1] === 'last') {
+      const wd = parseInt(parts[2], 10);
+      return `Monthly on last ${_DAYS[wd]}`;
+    }
+  }
+  return norm;
+}
+
+export function _normalizeRepeat(repeat, originalDate) {
+  if (!repeat || repeat === 'none') return 'none';
+  if (repeat === 'daily' || repeat === 'yearly') return repeat;
+  if (/^(weekly|monthly):/.test(repeat)) return repeat;
+  // Legacy bare values: derive params from the original date
+  const wd = originalDate.getDay();
+  const n = Math.ceil(originalDate.getDate() / 7);
+  if (repeat === 'weekly') return `weekly:${wd}`;
+  if (repeat === 'monthly') return `monthly:day:${originalDate.getDate()}`;
+  if (repeat === 'monthly_nth_weekday') return `monthly:nth:${n}:${wd}`;
+  if (repeat === 'monthly_last_weekday') return `monthly:last:${wd}`;
+  return repeat;
+}
+
+export function _advanceRecurring(dateStr, repeat, clock) {
+  const orig = new Date(dateStr);
+  const hh = orig.getHours();
+  const mm = orig.getMinutes();
+  let d = new Date(orig);
+  const norm = _normalizeRepeat(repeat, orig);
+  if (norm === 'none') return null;
+
+  function step() {
+    if (norm === 'daily') {
+      d.setDate(d.getDate() + 1);
+      return;
+    }
+    if (norm === 'yearly') {
+      d.setFullYear(d.getFullYear() + 1);
+      return;
+    }
+    const parts = norm.split(':');
+    const kind = parts[0];
+    if (kind === 'weekly') {
+      // Snap to the requested weekday in the next 1-7 days
+      const targetWd = parseInt(parts[1], 10);
+      let delta = (targetWd - d.getDay() + 7) % 7;
+      if (delta === 0) delta = 7;
+      d.setDate(d.getDate() + delta);
+      d.setHours(hh, mm, 0, 0);
+      return;
+    }
+    if (kind === 'monthly') {
+      const sub = parts[1];
+      const ny = d.getFullYear() + (d.getMonth() === 11 ? 1 : 0);
+      const nm = (d.getMonth() + 1) % 12;
+      let target;
+      if (sub === 'day') {
+        const wantDay = parseInt(parts[2], 10);
+        const lastDay = new Date(ny, nm + 1, 0).getDate();
+        target = new Date(ny, nm, Math.min(wantDay, lastDay));
+      } else if (sub === 'nth') {
+        const n = parseInt(parts[2], 10);
+        const wd = parseInt(parts[3], 10);
+        target = _nthWeekdayOfMonth(ny, nm, wd, n);
+      } else if (sub === 'last') {
+        const wd = parseInt(parts[2], 10);
+        target = _lastWeekdayOfMonth(ny, nm, wd);
+      } else {
+        d = null; return;
+      }
+      target.setHours(hh, mm, 0, 0);
+      d = target;
+      return;
+    }
+    d = null;
+  }
+
+  step();
+  if (d === null) return null;
+  const now = clock.now();
+  // Cap catch-up to avoid runaway on a malformed/very-old date.
+  let guard = 5000;
+  while (d.getTime() <= now) {
+    if (--guard <= 0) return null;
+    step();
+    if (d === null) return null;
+  }
+  return _toLocalDatetimeStr(d);
+}
diff --git a/frontend/src/features/notes/index.js b/frontend/src/features/notes/index.js
new file mode 100644
index 000000000..146844b8a
--- /dev/null
+++ b/frontend/src/features/notes/index.js
@@ -0,0 +1,503 @@
+/** Notes composition and intentional public API. The legacy entry activates compatibility startup. */
+import { createSelectionOperations } from './application/selection.js';
+import { createToolbar } from './ui/toolbar.js';
+import { createWindowLayout } from './ui/windowLayout.js';
+import { createCardOperations } from './application/cardOperations.js';
+import { createChecklistOperations } from './application/checklistOperations.js';
+import { createNotesSubmission } from './application/submission.js';
+import { createNotesDrafts } from './application/drafts.js';
+import { createNotesLifecycle } from './ui/lifecycle.js';
+import * as noteRules from './domain/noteRules.js';
+import { createText } from './ui/text.js';
+import { createColors } from './ui/colors.js';
+import { createPanel } from './ui/panel.js';
+import { createReminderDisplay } from './ui/reminderDisplay.js';
+import { createSelection } from './ui/selection.js';
+import { createFilters } from './ui/filters.js';
+import { createCardRendering } from './ui/cardRendering.js';
+import { createLayout } from './ui/layout.js';
+import { createQuickAdd } from './ui/quickAdd.js';
+import { createCardInteractions } from './ui/cardInteractions.js';
+import { createCardChecklist } from './ui/cardChecklist.js';
+import { createCardReorder } from './ui/cardReorder.js';
+import { createDraftEditor } from './ui/draftEditor.js';
+import { createEditor } from './ui/editor.js';
+import { createReminderPicker } from './ui/reminderPicker.js';
+import { createChecklist } from './ui/checklist.js';
+import { createDrawing } from './ui/drawing.js';
+import { createClipboard } from './ui/clipboard.js';
+import { createMobileEditor } from './ui/mobileEditor.js';
+import { createMobileReorder } from './ui/mobileReorder.js';
+import { createChecklistReorder } from './ui/checklistReorder.js';
+import { createQueries } from './application/queries.js';
+import { createAgentActions } from './application/agentActions.js';
+import { createDeletion } from './application/deletion.js';
+import { createNotesReminders } from './application/reminders.js';
+import { createNotesNotifications } from './infrastructure/notifications.js';
+import { createNotesState } from './application/state.js';
+import { createNotesWorkflows } from './application/workflows.js';
+import { createNotesApi } from './infrastructure/http.js';
+import { createNotesPersistence, REMINDER_DISMISSED_AT_KEY, NOTES_FIRST_OPEN_HINT_KEY, NOTES_LABELS_COLLAPSED_KEY } from './infrastructure/storage.js';
+import * as dates from './domain/recurrence.js';
+import uiModule from '/static/js/ui.js?v=20260916largetoolscroll1';
+import { spawnConfetti } from '/static/js/shared/ui/confetti.js';
+import * as Modals from '/static/js/modalManager.js';
+import { attachColorPicker } from '/static/js/colorPicker.js?v=20260910eyedropper1';
+import { makeWindowDraggable } from '/static/js/windowDrag.js';
+import { snapModalToZone } from '/static/js/tileManager.js?v=20260910responsivebounds1';
+import { applyEdgeDock, clearDockSide } from '/static/js/modalSnap.js';
+import { topToolWindowZ, topPortalZ } from '/static/js/toolWindowZOrder.js';
+import { bindMenuDismiss, dismissOrRemove } from '/static/js/escMenuStack.js';
+import { bindTourHintDismiss } from '/static/js/tourHintDismiss.js';
+
+const api = createNotesApi({ origin: window.location.origin, request: (...args) => fetch(...args) });
+const persistence = createNotesPersistence({ storage: typeof localStorage === 'undefined' ? undefined : localStorage });
+const { _loadPendingHighlights, _loadGlowedReminders, _saveGlowedReminders, _loadActiveHighlights, _saveActiveHighlights, _savePendingHighlights, _loadFiredReminders, _saveFiredReminders, _draftKey, _loadDraft, _clearDraft } = persistence;
+const clock = { now: () => Date.now() };
+const app = createNotesState({
+ viewMode: (typeof localStorage !== 'undefined' && localStorage.getItem('odysseus-notes-view')) || 'list',
+ labelsCollapsed: typeof localStorage !== 'undefined' && localStorage.getItem(NOTES_LABELS_COLLAPSED_KEY) === '1',
+ firedDotDismissedAt: (() => { try { const v = parseInt(persistence.getItem(REMINDER_DISMISSED_AT_KEY) || '0', 10); return Number.isFinite(v) && v > 0 ? v : 0; } catch { return 0; } })(),
+});
+const state = app.state;
+const lifecycle = createNotesLifecycle();
+const scheduler = { setTimeout: (...args) => setTimeout(...args), clearTimeout: id => clearTimeout(id), setInterval: (...args) => setInterval(...args), clearInterval: id => clearInterval(id) };
+const notifications = createNotesNotifications({ browser: window, notify: window.Notification, openPanel: () => openPanel(), toast: title => uiModule?.showToast?.(title) });
+const reminders = createNotesReminders({
+  app,
+  api,
+  persistence,
+  notifications,
+  clock,
+  scheduler,
+  fetchNotes: () => _fetchNotes(),
+  isNoteFullyDone: note => _isNoteFullyDone(note),
+  hasItems: note => _hasItems(note),
+  dismissedKey: REMINDER_DISMISSED_AT_KEY,
+  effects: { badge: () => _updateRailBadge(), highlight: id => {
+ _setReminderCardGlow(id, true);
+ const card = document.querySelector(`.note-card[data-note-id="${id}"]`);
+ if (card) { card.classList.add('note-card-reminder-fired'); setTimeout(() => card.classList.remove('note-card-reminder-fired'), 3000); }
+ else _queuePendingHighlight(id);
+} }
+});
+const workflows = createNotesWorkflows({
+  app,
+  api,
+  effects: {
+ render: () => _renderNotes(),
+ showError: (...args) => uiModule.showError(...args),
+ archived: undo => uiModule.showToast('Archived', { duration: 6000, action: 'Undo', actionIcon: _NOTE_UNDO_ICON, onAction: undo, actionHint: 'Ctrl+Z' }),
+ celebrateArchive: (note, card) => { if (_hasItems(note) && !(note.items || []).some(i => !i.done)) { const r = card.getBoundingClientRect(); spawnConfetti(r.left + r.width / 2, r.top + r.height / 2, 80); } },
+}
+});
+const _NOTE_UNDO_ICON = '<svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round" style="vertical-align:middle;"><polyline points="9 14 4 9 9 4"/><path d="M4 9h11a5 5 0 0 1 5 5v0a5 5 0 0 1-5 5H9"/></svg>';
+function _pushUndo(entry) { return workflows._pushUndo(entry); }
+function _popAndRunUndo() { return workflows._popAndRunUndo(); }
+function _undoArchive(note, prevIdx) { return workflows._undoArchive(note, prevIdx); }
+function _archiveNoteById(id, options) { return workflows._archiveNoteById(id, options); }
+function _fetchNotes() { return workflows._fetchNotes(); }
+
+function _deleteNoteApi(id) { return workflows._deleteNoteApi(id); }
+function _patchNote(id, patch) { return workflows._patchNote(id, patch); }
+function _uid() { return Math.random().toString(36).slice(2, 10); }
+function _formatDueDate(dateStr) { return dates._formatDueDate(dateStr, clock); }
+function _isDueOverdue(dateStr) { return dates._isDueOverdue(dateStr, clock); }
+
+function _laterTodayDate() { return dates._laterTodayDate(clock); }
+function _tomorrowDate() { return dates._tomorrowDate(clock); }
+function _nextWeekDate() { return dates._nextWeekDate(clock); }
+function _formatReminderTag(dateStr) { return dates._formatReminderTag(dateStr, clock); }
+function _snapToRepeat(currentDate, normRepeat) { return dates._snapToRepeat(currentDate, normRepeat, clock); }
+function _ensureNotificationPermission() { return notifications.ensurePermission(); }
+
+function _startReminderLoop() { return reminders._startReminderLoop(); }
+
+function _countFiredReminders() { return reminders._countFiredReminders(); }
+
+function _hasActiveReminder(...args) { return noteRules._hasActiveReminder(...args, clock); }
+const _isNoteFullyDone = noteRules._isNoteFullyDone;
+const _hasItems = noteRules._hasItems;
+function _isPastReminder(...args) { return noteRules._isPastReminder(...args, clock); }
+function _esc(...args) { return text._esc(...args); }
+
+function _safeImgSrc(...args) { return text._safeImgSrc(...args); }
+function _linkify(...args) { return text._linkify(...args); }
+function _isBgImage(...args) { return colors._isBgImage(...args); }
+
+function _dotBg(...args) { return colors._dotBg(...args); }
+function _dotIsActive(...args) { return colors._dotIsActive(...args); }
+function _customColorStyle(...args) { return colors._customColorStyle(...args); }
+function _pickCustomBgImage(...args) { return colors._pickCustomBgImage(...args); }
+function _wireFormColors(...args) { return colors._wireFormColors(...args); }
+
+function openPanel(...args) { return panel.openPanel(...args); }
+
+function _smoothScrollToNoteCard(...args) { return panel._smoothScrollToNoteCard(...args); }
+function _clearViewedReminderGlows(...args) { return reminderDisplay._clearViewedReminderGlows(...args); }
+function _setReminderCardGlow(...args) { return reminderDisplay._setReminderCardGlow(...args); }
+function _queuePendingHighlight(...args) { return reminderDisplay._queuePendingHighlight(...args); }
+function _flushPendingHighlights(...args) { return reminderDisplay._flushPendingHighlights(...args); }
+function _updateRailBadge(...args) { return reminderDisplay._updateRailBadge(...args); }
+function _enterSelectMode(...args) { return selection._enterSelectMode(...args); }
+function _exitSelectMode(...args) { return selection._exitSelectMode(...args); }
+function _updateBulkBar(...args) { return selection._updateBulkBar(...args); }
+
+function _renderLabelsInto(...args) { return filters._renderLabelsInto(...args); }
+function _renderLoadingSkeleton(...args) { return cardRendering._renderLoadingSkeleton(...args); }
+function _renderNotes(...args) { return cardRendering._renderNotes(...args); }
+function _captureCardPositions(...args) { return layout._captureCardPositions(...args); }
+function _animateReflow(...args) { return layout._animateReflow(...args); }
+function _applyMasonry(...args) { return layout._applyMasonry(...args); }
+function _renderQuickAdd(...args) { return quickAdd._renderQuickAdd(...args); }
+
+function _editNote(...args) { return quickAdd._editNote(...args); }
+function _bindCardEvents(...args) { return cardInteractions._bindCardEvents(...args); }
+function _wireCardChecklist(...args) { return cardChecklist._wireCardChecklist(...args); }
+function _wireTodayView(...args) { return cardChecklist._wireTodayView(...args); }
+function _wireCardReorder(...args) { return cardReorder._wireCardReorder(...args); }
+
+function _wireDraftAutosave(...args) { return draftEditor._wireDraftAutosave(...args); }
+function _commitOpenInPlaceEditor(...args) { return draftEditor._commitOpenInPlaceEditor(...args); }
+function _applyDraftToNote(...args) { return draftEditor._applyDraftToNote(...args); }
+function _buildForm(...args) { return editor._buildForm(...args); }
+function _wireReminderPicker(...args) { return reminderPicker._wireReminderPicker(...args); }
+function _buildGoalHtml(...args) { return checklist._buildGoalHtml(...args); }
+function _wireGoalForm(...args) { return checklist._wireGoalForm(...args); }
+function _buildChecklistHtml(...args) { return checklist._buildChecklistHtml(...args); }
+function _wireRow(...args) { return checklist._wireRow(...args); }
+function _wireChecklist(...args) { return checklist._wireChecklist(...args); }
+function _collectItems(...args) { return checklist._collectItems(...args); }
+function _buildDrawHtml(...args) { return drawing._buildDrawHtml(...args); }
+function _wireCanvas(...args) { return drawing._wireCanvas(...args); }
+function _uploadCanvasAsPng(...args) { return drawing._uploadCanvasAsPng(...args); }
+function _openNoteCornerMenu(...args) { return clipboard._openNoteCornerMenu(...args); }
+function _copyNote(...args) { return clipboard._copyNote(...args); }
+function _isNotesMobileMode(...args) { return mobileEditor._isNotesMobileMode(...args); }
+function _openMobileFullscreenEdit(...args) { return mobileEditor._openMobileFullscreenEdit(...args); }
+function _closeMobileFullscreenEdit(...args) { return mobileEditor._closeMobileFullscreenEdit(...args); }
+
+function _bindLongPressDrag(...args) { return mobileReorder._bindLongPressDrag(...args); }
+
+function _wireChecklistTouchReorder(...args) { return checklistReorder._wireChecklistTouchReorder(...args); }
+
+function _sortedVisibleNotes(...args) { return queries._sortedVisibleNotes(...args); }
+function _userVisibleNotes(...args) { return queries._userVisibleNotes(...args); }
+function _agentSolveNote(...args) { return agentActions._agentSolveNote(...args); }
+
+function _clearPastReminders(...args) { return deletion._clearPastReminders(...args); }
+const text = createText({
+  uiModule
+});
+const colors = createColors({
+  api
+});
+const { COLORS, COLOR_HEX } = colors;
+const windowLayout = createWindowLayout({
+  makeWindowDraggable,
+  snapModalToZone,
+  clearDockSide,
+  applyEdgeDock,
+  topToolWindowZ
+});
+const toolbar = createToolbar({
+  app,
+  state,
+  persistence,
+  _renderNotes,
+  _fetchNotes,
+  _applyMasonry
+});
+const panel = createPanel({
+  wireToolbar: toolbar.wireToolbar,
+  wireSelectionActions: () => selection.wireSelectionActions(),
+  _wireNotesWindow: windowLayout._wireNotesWindow,
+  _restoreNotesSidebarDock: windowLayout._restoreNotesSidebarDock,
+  _bringNotesToFront: windowLayout._bringNotesToFront,
+  disposeUI: () => { layout.dispose(); mobileReorder.dispose(); checklistReorder.dispose(); lifecycle.dispose(); },
+  lifecycle,
+  Modals,
+  NOTES_FIRST_OPEN_HINT_KEY,
+  REMINDER_DISMISSED_AT_KEY,
+  _clearViewedReminderGlows,
+  _closeMobileFullscreenEdit,
+  _commitOpenInPlaceEditor,
+  _copyNote,
+  _enterSelectMode,
+  _exitSelectMode,
+  _fetchNotes,
+  _flushPendingHighlights,
+  _isNotesMobileMode,
+  _popAndRunUndo,
+  _renderLoadingSkeleton,
+  _renderNotes,
+  _startReminderLoop,
+  app,
+  bindTourHintDismiss,
+  dismissOrRemove,
+  persistence,
+  state,
+  workflows
+});
+const reminderDisplay = createReminderDisplay({
+  _countFiredReminders,
+  _hasActiveReminder,
+  _loadActiveHighlights,
+  _loadGlowedReminders,
+  _loadPendingHighlights,
+  _saveActiveHighlights,
+  _saveGlowedReminders,
+  _savePendingHighlights,
+  _smoothScrollToNoteCard,
+  state
+});
+const selectionOperations = createSelectionOperations({
+  app,
+  api,
+  fetchNotes: _fetchNotes,
+  exitSelection: _exitSelectMode,
+  sendContext: detail => window.dispatchEvent(new CustomEvent('odysseus:notes-context-selected', { detail })),
+  effects: { render: _renderNotes, styledConfirm: uiModule.styledConfirm, showToast: (...args) => uiModule.showToast(...args) }
+});
+const selection = createSelection({
+  operations: selectionOperations,
+  _renderNotes,
+  app,
+  state
+});
+const filters = createFilters({
+  NOTES_LABELS_COLLAPSED_KEY,
+  _clearPastReminders,
+  _esc,
+  _isPastReminder,
+  _renderNotes,
+  _userVisibleNotes,
+  app,
+  persistence,
+  state
+});
+const cardRendering = createCardRendering({
+  COLORS,
+  COLOR_HEX,
+  _animateReflow,
+  _applyMasonry,
+  _bindCardEvents,
+  _captureCardPositions,
+  _customColorStyle,
+  _dotBg,
+  _dotIsActive,
+  _esc,
+  _formatDueDate,
+  _formatReminderTag,
+  _hasActiveReminder,
+  _isBgImage,
+  _isDueOverdue,
+  _isNotesMobileMode,
+  _linkify,
+  _loadActiveHighlights,
+  _renderLabelsInto,
+  _renderQuickAdd,
+  _safeImgSrc,
+  _sortedVisibleNotes,
+  _updateRailBadge,
+  _wireTodayView,
+  state,
+  uiModule
+});
+const layout = createLayout({
+  isOpen: () => state.open
+});
+const quickAdd = createQuickAdd({
+  _applyDraftToNote,
+  _applyMasonry,
+  _buildForm,
+  app,
+  openPanel,
+  state,
+  uiModule
+});
+const cardOperations = createCardOperations({
+  app,
+  api,
+  pushUndo: _pushUndo,
+  undoArchive: _undoArchive,
+  effects: { render: _renderNotes, showError: (...args) => uiModule.showError(...args), showToast: (...args) => uiModule.showToast(...args), archived: undo => uiModule.showToast('Archived', { duration: 6000, action: 'Undo', actionIcon: _NOTE_UNDO_ICON, onAction: undo, actionHint: 'Ctrl+Z' }) }
+});
+const checklistOperations = createChecklistOperations({
+  app,
+  api,
+  uid: _uid,
+  effects: { render: _renderNotes, showError: (...args) => uiModule.showError(...args) }
+});
+const cardInteractions = createCardInteractions({
+  cardOperations,
+  COLORS,
+  _archiveNoteById,
+  _bindLongPressDrag,
+  _customColorStyle,
+  _dotBg,
+  _dotIsActive,
+  _editNote,
+  _isBgImage,
+  _isNotesMobileMode,
+  _openMobileFullscreenEdit,
+  _openNoteCornerMenu,
+  _pickCustomBgImage,
+  _renderNotes,
+  _setReminderCardGlow,
+  _smoothScrollToNoteCard,
+  _updateBulkBar,
+  _wireCardChecklist,
+  _wireCardReorder,
+  app,
+  spawnConfetti,
+  state,
+  uiModule
+});
+const cardChecklist = createCardChecklist({
+  checklistOperations,
+  _editNote,
+  _renderNotes,
+  app,
+  spawnConfetti,
+  state
+});
+const cardReorder = createCardReorder({
+  persistOrder: cardOperations.persistOrder,
+  lifecycle,
+  _isNotesMobileMode,
+  state
+});
+const draftEditor = createDraftEditor({
+  bindDraft: (...args) => drafts.bindDraft(...args),
+  _collectItems,
+  _loadDraft
+});
+const editor = createEditor({
+  deleteFromEditor: id => deletion.deleteFromEditor(id),
+  submitNote: (...args) => submission.submitNote(...args),
+  COLORS,
+  _applyMasonry,
+  _archiveNoteById,
+  _buildChecklistHtml,
+  _buildDrawHtml,
+  _buildGoalHtml,
+  _collectItems,
+  _customColorStyle,
+  _dotBg,
+  _dotIsActive,
+  _esc,
+  _isBgImage,
+  _renderNotes,
+  _safeImgSrc,
+  _uid,
+  _uploadCanvasAsPng,
+  _wireCanvas,
+  _wireChecklist,
+  _wireDraftAutosave,
+  _wireFormColors,
+  _wireGoalForm,
+  _wireReminderPicker,
+  api,
+  app,
+  state,
+  uiModule
+});
+const reminderPicker = createReminderPicker({
+  lifecycle,
+  _ensureNotificationPermission,
+  _esc,
+  _formatReminderTag,
+  _laterTodayDate,
+  _nextWeekDate,
+  _snapToRepeat,
+  _tomorrowDate,
+  bindMenuDismiss,
+  dismissOrRemove
+});
+const checklist = createChecklist({
+  _esc,
+  _uid,
+  spawnConfetti
+});
+const drawing = createDrawing({
+  lifecycle,
+  _safeImgSrc,
+  api,
+  attachColorPicker
+});
+const clipboard = createClipboard({
+  _agentSolveNote,
+  bindMenuDismiss,
+  dismissOrRemove,
+  state,
+  topPortalZ,
+  uiModule
+});
+const mobileEditor = createMobileEditor({
+  _applyDraftToNote,
+  _buildForm,
+  _fetchNotes,
+  _linkify,
+  _renderNotes,
+  _uid,
+  _wireChecklistTouchReorder,
+  _wireRow,
+  app,
+  state,
+  uiModule
+});
+const mobileReorder = createMobileReorder({
+  commitMobileOrder: cardOperations.commitMobileOrder,
+  lifecycle,
+  _applyMasonry,
+  _enterSelectMode,
+  app
+});
+const checklistReorder = createChecklistReorder({
+  lifecycle
+});
+const queries = createQueries({
+  _hasActiveReminder,
+  state
+});
+const agentActions = createAgentActions({
+  _patchNote,
+  _renderNotes,
+  api,
+  app,
+  createFormData: () => new FormData(),
+  state,
+  streamComplete: sid => { try { window.sessionModule?.markStreamComplete?.(sid); } catch {} },
+  uiModule
+});
+const deletion = createDeletion({
+  app,
+  _deleteNoteApi,
+  _fetchNotes,
+  _isPastReminder,
+  _renderNotes,
+  effects: { styledConfirm: uiModule.styledConfirm, confirm: message => confirm(message), showToast: (...args) => uiModule.showToast(...args), showError: (...args) => uiModule.showError(...args) },
+  state
+});
+const notesModule = { openPanel: panel.openPanel, closePanel: panel.closePanel, togglePanel: panel.togglePanel, isPanelOpen: panel.isPanelOpen, openNote: panel.openNote, newNote: quickAdd.newNote, openNotes: panel.openPanel, closeNotes: panel.closePanel, isNotesOpen: panel.isPanelOpen, refreshDueBadge: reminders.refreshDueBadge };
+const publicOpenPanel = panel.openPanel, publicClosePanel = panel.closePanel, publicTogglePanel = panel.togglePanel, publicIsPanelOpen = panel.isPanelOpen, publicOpenNote = panel.openNote, publicNewNote = quickAdd.newNote, publicRefreshDueBadge = reminders.refreshDueBadge, publicDismissFiredReminderDot = reminders.dismissFiredReminderDot;
+export { publicOpenPanel as openPanel, publicClosePanel as closePanel, publicTogglePanel as togglePanel, publicIsPanelOpen as isPanelOpen, publicOpenNote as openNote, publicNewNote as newNote, publicRefreshDueBadge as refreshDueBadge, publicDismissFiredReminderDot as dismissFiredReminderDot, publicOpenPanel as openNotes, publicClosePanel as closeNotes, publicIsPanelOpen as isNotesOpen };
+export function startNotesBackground() { reminders.start(); }
+export default notesModule;
+const submission = createNotesSubmission({
+  app,
+  api,
+  persistence,
+  clock,
+  uid: _uid,
+  fetchNotes: _fetchNotes,
+  effects: { render: _renderNotes, showError: (...args) => uiModule.showError(...args), clearGlow: id => _setReminderCardGlow(id, false) }
+});
+const drafts = createNotesDrafts({
+  app,
+  api,
+  persistence,
+  scheduler,
+  effects: { showError: (...args) => uiModule.showError(...args) }
+});
diff --git a/frontend/src/features/notes/infrastructure/http.js b/frontend/src/features/notes/infrastructure/http.js
new file mode 100644
index 000000000..eeafd1b0f
--- /dev/null
+++ b/frontend/src/features/notes/infrastructure/http.js
@@ -0,0 +1,29 @@
+/** Notes HTTP port. Response interpretation stays with the owning workflow. */
+export function createNotesApi({ origin, request }) {
+  const json = (method, body) => ({ method, credentials: 'same-origin', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(body) });
+  async function saveNote(note) {
+    const response = await request(note.id ? `${origin}/api/notes/${note.id}` : `${origin}/api/notes`, json(note.id ? 'PUT' : 'POST', note));
+    if (!response.ok) throw new Error('Failed to save note');
+    return await response.json();
+  }
+  async function patchNote(id, patch) {
+    const response = await request(`${origin}/api/notes/${id}`, json('PUT', patch));
+    if (!response.ok) throw new Error('Failed to update note');
+    return await response.json();
+  }
+  async function deleteNote(id) {
+    const response = await request(`${origin}/api/notes/${id}`, { method: 'DELETE', credentials: 'same-origin' });
+    if (!response.ok) throw new Error('HTTP ' + response.status);
+  }
+  return {
+    saveNote, patchNote, deleteNote,
+    listNotes: archived => request(`${origin}/api/notes${archived ? '?archived=true' : ''}`, { credentials: 'same-origin' }),
+    reorder: ids => request(`${origin}/api/notes/reorder`, json('POST', { ids })),
+    upload: body => request(`${origin}/api/upload`, { method: 'POST', body, credentials: 'same-origin' }),
+    uploadUrl: id => `${origin}/api/upload/${id}`,
+    fireReminder: body => request('/api/notes/fire-reminder', json('POST', body)),
+    defaultChat: () => request(`${origin}/api/default-chat`, { credentials: 'same-origin' }),
+    createSession: body => request(`${origin}/api/session`, { method: 'POST', body, credentials: 'same-origin' }),
+    startChat: body => request(`${origin}/api/chat_stream`, { method: 'POST', body, credentials: 'same-origin' }),
+  };
+}
diff --git a/frontend/src/features/notes/infrastructure/notifications.js b/frontend/src/features/notes/infrastructure/notifications.js
new file mode 100644
index 000000000..cd98eb702
--- /dev/null
+++ b/frontend/src/features/notes/infrastructure/notifications.js
@@ -0,0 +1,20 @@
+/** Browser notification permission/display port, independent of Notes rendering. */
+export function createNotesNotifications({ browser, notify, openPanel, toast }) {
+  async function ensurePermission() {
+    if (!('Notification' in browser)) return false;
+    if (notify.permission === 'granted') return true;
+    if (notify.permission === 'denied') return false;
+    try { return await notify.requestPermission() === 'granted'; }
+    catch { return false; }
+  }
+  function show(title, body, noteId) {
+    if ('Notification' in browser && notify.permission === 'granted') {
+      try {
+        const notification = new notify(title, { body, tag: 'note-' + noteId, icon: '/static/favicon.ico' });
+        notification.onclick = () => { browser.focus(); openPanel(); notification.close(); };
+      } catch {}
+    }
+    toast(title);
+  }
+  return { ensurePermission, show };
+}
diff --git a/frontend/src/features/notes/infrastructure/storage.js b/frontend/src/features/notes/infrastructure/storage.js
new file mode 100644
index 000000000..06aaa01ab
--- /dev/null
+++ b/frontend/src/features/notes/infrastructure/storage.js
@@ -0,0 +1,63 @@
+/** Browser persistence and unchanged Notes key/serialization contracts. */
+export const REMINDER_FIRED_KEY = 'odysseus-notes-reminder-fired';
+export const REMINDER_GLOWED_KEY = 'odysseus-notes-reminder-glowed';
+export const REMINDER_PENDING_HIGHLIGHT_KEY = 'odysseus-notes-reminder-pending-highlight';
+export const REMINDER_ACTIVE_HIGHLIGHT_KEY = 'odysseus-notes-reminder-active-highlight';
+export const REMINDER_DISMISSED_AT_KEY = 'odysseus-notes-reminder-dismissed-at';
+export const NOTES_FIRST_OPEN_HINT_KEY = 'odysseus-notes-first-open-hint-v1';
+export const NOTES_LABELS_COLLAPSED_KEY = 'odysseus-notes-labels-collapsed';
+export const _DRAFT_PREFIX = 'odysseus-note-draft-';
+
+export function createNotesPersistence({ storage: localStorage }) {
+function _loadPendingHighlights() {
+  try { return new Set(JSON.parse(localStorage.getItem(REMINDER_PENDING_HIGHLIGHT_KEY) || '[]')); }
+  catch { return new Set(); }
+}
+
+function _loadGlowedReminders() {
+  try { return new Set(JSON.parse(localStorage.getItem(REMINDER_GLOWED_KEY) || '[]')); }
+  catch { return new Set(); }
+}
+
+function _saveGlowedReminders(set) {
+  try { localStorage.setItem(REMINDER_GLOWED_KEY, JSON.stringify([...set])); } catch {}
+}
+
+function _loadActiveHighlights() {
+  try { return new Set(JSON.parse(localStorage.getItem(REMINDER_ACTIVE_HIGHLIGHT_KEY) || '[]')); }
+  catch { return new Set(); }
+}
+
+function _saveActiveHighlights(set) {
+  try { localStorage.setItem(REMINDER_ACTIVE_HIGHLIGHT_KEY, JSON.stringify([...set])); } catch {}
+}
+
+function _savePendingHighlights(set) {
+  try { localStorage.setItem(REMINDER_PENDING_HIGHLIGHT_KEY, JSON.stringify([...set])); }
+  catch {}
+}
+
+function _loadFiredReminders() {
+  try { return new Set(JSON.parse(localStorage.getItem(REMINDER_FIRED_KEY) || '[]')); }
+  catch { return new Set(); }
+}
+
+function _saveFiredReminders(set) {
+  try { localStorage.setItem(REMINDER_FIRED_KEY, JSON.stringify([...set])); }
+  catch {}
+}
+
+function _draftKey(id) { return _DRAFT_PREFIX + (id || '__new__'); }
+
+function _loadDraft(id) {
+  try { return JSON.parse(localStorage.getItem(_draftKey(id)) || 'null'); } catch { return null; }
+}
+
+function _clearDraft(id) { try { localStorage.removeItem(_draftKey(id)); } catch {} }
+
+return { _loadPendingHighlights, _loadGlowedReminders, _saveGlowedReminders, _loadActiveHighlights, _saveActiveHighlights, _savePendingHighlights, _loadFiredReminders, _saveFiredReminders, _draftKey, _loadDraft, _clearDraft,
+  getItem: key => localStorage.getItem(key),
+  setItem: (key, value) => localStorage.setItem(key, value),
+  removeItem: key => localStorage.removeItem(key),
+};
+}
diff --git a/frontend/src/features/notes/ui/cardChecklist.js b/frontend/src/features/notes/ui/cardChecklist.js
new file mode 100644
index 000000000..6bbf39326
--- /dev/null
+++ b/frontend/src/features/notes/ui/cardChecklist.js
@@ -0,0 +1,148 @@
+/** Card checklist editing and Today-step interactions. */
+export function createCardChecklist({
+  checklistOperations,
+  _editNote,
+  _renderNotes,
+  app,
+  spawnConfetti,
+  state
+}) {
+  function _wireCardChecklist(body) {
+    // Remove a single checklist item (hover X)
+    body.querySelectorAll('.note-checkbox-rm').forEach(btn => {
+      btn.addEventListener('click', (e) => {
+        e.stopPropagation();
+        if (state.selectMode) return;
+        const noteId = btn.dataset.noteId;
+        const idx = parseInt(btn.dataset.idx);
+        checklistOperations.removeItem(noteId, idx);
+      });
+    });
+
+    function _startChecklistItemEdit(noteId, idx, span) {
+      if (span.isContentEditable) return;
+      const note = state.notes.find(n => n.id === noteId);
+      if (!note || !Array.isArray(note.items) || !note.items[idx]) return;
+
+      span.textContent = note.items[idx].text || '';
+      span.contentEditable = "true";
+      span.spellcheck = false;
+      span.focus();
+
+      const selection = window.getSelection();
+      const range = document.createRange();
+      range.selectNodeContents(span);
+      selection.removeAllRanges();
+      selection.addRange(range);
+
+      const save = () => {
+        if (!span.isContentEditable) return;
+        span.contentEditable = "false";
+        const newText = span.textContent.trim();
+        checklistOperations.editItem(note, idx, newText);
+      };
+
+      const onKeydown = (e) => {
+        if (e.key === 'Enter') {
+          e.preventDefault();
+          save();
+        } else if (e.key === 'Escape') {
+          e.preventDefault();
+          span.contentEditable = "false";
+          _renderNotes();
+        }
+      };
+
+      span.addEventListener('blur', save, { once: true });
+      span.addEventListener('keydown', onKeydown);
+    }
+
+    // Edit a single checklist item (hover Edit button)
+    body.querySelectorAll('.note-checkbox-edit').forEach(btn => {
+      btn.addEventListener('click', (e) => {
+        e.stopPropagation();
+        if (state.selectMode) return;
+        const noteId = btn.dataset.noteId;
+        const idx = parseInt(btn.dataset.idx);
+        const span = btn.parentElement.querySelector('.note-check-text');
+        if (span) _startChecklistItemEdit(noteId, idx, span);
+      });
+    });
+
+    // Prevent clicks from toggling the row while actively editing inline
+    body.querySelectorAll('.note-check-text').forEach(span => {
+      span.addEventListener('click', (e) => {
+        if (span.isContentEditable) {
+          e.stopPropagation();
+        }
+      });
+    });
+
+    // Quick-add new checklist item (hover input at bottom of todo cards)
+    body.querySelectorAll('.note-cl-quickadd-input').forEach(input => {
+      input.addEventListener('click', (e) => e.stopPropagation());
+      input.addEventListener('keydown', async (e) => {
+        e.stopPropagation();
+        if (e.key !== 'Enter') return;
+        e.preventDefault();
+        const text = input.value.trim();
+        if (!text) return;
+        const noteId = input.dataset.noteId;
+        const persist = checklistOperations.addItem(noteId, text, () => { input.value = ''; });
+        if (!persist) return;
+        // Refocus the input on the same card
+        setTimeout(() => {
+          const next = document.querySelector(`.note-cl-quickadd-input[data-note-id="${noteId}"]`);
+          if (next) next.focus();
+        }, 0);
+        persist();
+      });
+    });
+
+    // Checkboxes (dot toggle, optimistic) : disabled in select mode
+    body.querySelectorAll('.note-checkbox').forEach(el => {
+      el.addEventListener('click', (e) => {
+        if (state.selectMode) return; // let card-level handler take over
+        e.preventDefault();
+        e.stopPropagation();
+        const noteId = el.dataset.noteId;
+        const idx = parseInt(el.dataset.idx);
+        checklistOperations.toggleItem(noteId, idx, done => el.classList.toggle('done', done), () => {
+          const card = el.closest('.note-card');
+          if (card) { const r = card.getBoundingClientRect(); spawnConfetti(r.left + r.width / 2, r.top + r.height / 2, 60); }
+        });
+      });
+    });
+
+
+  }
+
+  function _wireTodayView(body) {
+    body.querySelectorAll('.notes-today-row .note-check-dot').forEach(dot => {
+      dot.addEventListener('click', async (e) => {
+        e.stopPropagation();
+        const id = dot.dataset.noteId;
+        const idx = parseInt(dot.dataset.idx);
+        const row = dot.closest('.notes-today-row');
+        await checklistOperations.toggleTodayStep(id, idx, () => row?.classList.add('done'), () => {
+          const r = (row || dot).getBoundingClientRect();
+          spawnConfetti(r.left + r.width / 2, r.top + r.height / 2, 60);
+        });
+      });
+    });
+    body.querySelectorAll('.notes-today-title').forEach(el => {
+      el.addEventListener('click', () => {
+        const id = el.dataset.noteId;
+        if (!id) return;
+        // Drop the Today filter first so the regular card list is rendered;
+        // _editNote needs to find a .note-card in the DOM to replace with
+        // the editor form.
+        app.setActiveFilter(null);
+        _renderNotes();
+        _editNote(id);
+      });
+    });
+  }
+
+  return { _wireCardChecklist, _wireTodayView };
+}
diff --git a/frontend/src/features/notes/ui/cardInteractions.js b/frontend/src/features/notes/ui/cardInteractions.js
new file mode 100644
index 000000000..09e083c41
--- /dev/null
+++ b/frontend/src/features/notes/ui/cardInteractions.js
@@ -0,0 +1,337 @@
+/** Card taps, pin/color controls, menus and archive animation. */
+export function createCardInteractions({
+  cardOperations,
+  COLORS,
+  _archiveNoteById,
+  _bindLongPressDrag,
+  _customColorStyle,
+  _dotBg,
+  _dotIsActive,
+  _editNote,
+  _isBgImage,
+  _isNotesMobileMode,
+  _openMobileFullscreenEdit,
+  _openNoteCornerMenu,
+  _pickCustomBgImage,
+  _renderNotes,
+  _setReminderCardGlow,
+  _smoothScrollToNoteCard,
+  _updateBulkBar,
+  _wireCardChecklist,
+  _wireCardReorder,
+  app,
+  spawnConfetti,
+  state,
+  uiModule
+}) {
+  function _bindCardEvents(body) {
+    // Skip completed leading rows so the first unfinished checklist item is
+    // visible when a note preview has its own scroll area.
+    requestAnimationFrame(() => {
+      body.querySelectorAll('.note-checklist-preview').forEach(preview => {
+        const firstPending = preview.querySelector('.note-checkbox:not(.done)');
+        if (firstPending) preview.scrollTop = Math.max(0, firstPending.offsetTop - 4);
+      });
+    });
+    const tapToEditOrSelect = (cardEl) => {
+      const id = cardEl.dataset.noteId;
+      // A long-press enters select mode and re-renders the card. Ignore the
+      // synthetic click that mobile browsers emit when that same touch ends.
+      if (state.suppressNextNoteTapId === id) {
+        app.setSuppressNextNoteTapId(null);
+        return;
+      }
+      if (state.selectMode) {
+        const cb = cardEl.querySelector('.note-card-cb');
+        if (cb) {
+          cb.checked = !cb.checked;
+          cb.dispatchEvent(new Event('change'));
+        }
+      } else if (_isNotesMobileMode()) {
+        // Mobile: open the per-note fullscreen edit overlay instead of the
+        // in-place form. Tiles on mobile are read-only previews.
+        _openMobileFullscreenEdit(id, cardEl);
+      } else {
+        _editNote(id);
+      }
+    };
+    // Mobile: long-press anywhere on a note card → enter Select mode and
+    // select that card. Cancelled by movement (so it doesn't interfere with
+    // vertical scrolling) or by lifting the finger before the timer fires.
+    if (_isNotesMobileMode()) {
+      body.querySelectorAll('.note-card').forEach(card => _bindLongPressDrag(card));
+    }
+    body.querySelectorAll('.note-card.note-card-reminder-fired-sticky').forEach(card => {
+      card.addEventListener('click', () => _setReminderCardGlow(card.dataset.noteId, false), true);
+    });
+    // Click title : edit, or toggle select in select mode
+    body.querySelectorAll('.note-card-title[data-action="edit"]').forEach(el => {
+      el.addEventListener('click', (e) => {
+        e.stopPropagation();
+        _smoothScrollToNoteCard(el.closest('.note-card'));
+        tapToEditOrSelect(el.closest('.note-card'));
+      });
+    });
+    // Click content : edit, or toggle select in select mode
+    body.querySelectorAll('.note-content-preview').forEach(el => {
+      el.addEventListener('click', (e) => { e.stopPropagation(); tapToEditOrSelect(el.closest('.note-card')); });
+    });
+    // A saved drawing is the note's primary content. Open its editor directly
+    // when the preview is clicked, matching title/content preview behavior.
+    body.querySelectorAll('.note-card-drawing .note-card-image').forEach(el => {
+      el.addEventListener('click', (e) => {
+        e.stopPropagation();
+        tapToEditOrSelect(el.closest('.note-card'));
+      });
+    });
+    // Click empty area of checklist preview (not on checkbox/X) : edit
+    body.querySelectorAll('.note-checklist-preview').forEach(el => {
+      el.addEventListener('wheel', (e) => {
+        const atTop = el.scrollTop <= 0;
+        const atBottom = el.scrollTop + el.clientHeight >= el.scrollHeight - 1;
+        if ((e.deltaY < 0 && atTop) || (e.deltaY > 0 && atBottom)) {
+          const pane = el.closest('.notes-pane-body');
+          if (pane) {
+            pane.scrollTop += e.deltaY;
+            e.preventDefault();
+          }
+        }
+      }, { passive: false });
+      el.addEventListener('click', (e) => {
+        if (e.target.closest('.note-checkbox, .note-checkbox-rm, .note-cl-quickadd, input')) return;
+        e.stopPropagation();
+        tapToEditOrSelect(el.closest('.note-card'));
+      });
+    });
+    // Clicking todo item text now toggles its checkbox : let the click bubble
+    // up to the parent .note-checkbox row handler. To open the editor, the
+    // user clicks the pencil corner.
+    // (No-op block kept as a marker : removing the listener entirely means
+    // clicks naturally bubble to the row toggle below.)
+    // In select mode, clicking anywhere on the card toggles selection
+    if (state.selectMode) {
+      body.querySelectorAll('.note-card').forEach(card => {
+        card.addEventListener('click', (e) => {
+          if (e.target.closest('.note-card-cb')) return; // checkbox handles itself
+          e.stopPropagation();
+          tapToEditOrSelect(card);
+        });
+      });
+    }
+    // Mobile, non-select: tapping anywhere on the card body (not on an
+    // interactive child : buttons, pin, checkbox, color dot, reminder pill,
+    // agent tag, links) opens the fullscreen editor. Previously only the
+    // title / content preview triggered edit, so padding + empty gutters were
+    // dead zones that felt broken on mobile.
+    if (_isNotesMobileMode() && !state.selectMode) {
+      const _INTERACTIVE = 'button, a, input, label, .note-card-color-dot, .note-checkbox, .note-checkbox-rm, .note-cl-quickadd, .note-agent-tag, .note-card-pin, .note-card-corner-trash, .note-card-corner-menu, .note-card-corner-unarchive, .note-card-edit-corner, .note-card-reminder, .note-card-cb';
+      body.querySelectorAll('.note-card').forEach(card => {
+        card.addEventListener('click', (e) => {
+          if (e.target.closest(_INTERACTIVE)) return;
+          e.stopPropagation();
+          tapToEditOrSelect(card);
+        });
+      });
+    }
+    // Multi-select checkbox (only in select mode)
+    body.querySelectorAll('.note-card-cb').forEach(cb => {
+      cb.addEventListener('click', (e) => e.stopPropagation());
+      cb.addEventListener('change', () => {
+        const id = cb.dataset.noteId;
+        if (cb.checked) app.selectId(id);
+        else app.deselectId(id);
+        cb.closest('.note-card').classList.toggle('note-card-selected', cb.checked);
+        _updateBulkBar();
+      });
+    });
+    // Pin toggle (optimistic)
+    body.querySelectorAll('.note-card-pin').forEach(btn => {
+      btn.addEventListener('click', (e) => {
+        e.stopPropagation();
+        const id = btn.dataset.noteId;
+        cardOperations.togglePin(id);
+      });
+    });
+    // Color picker
+    const _applyCardColor = async (card, id, newColor) => {
+      const isBg = _isBgImage(newColor);
+      COLORS.forEach(c => { if (c.value && c.value !== 'custom') card.classList.remove('note-color-' + c.value); });
+      if (newColor && !isBg) card.classList.add('note-color-' + newColor);
+      if (isBg) card.setAttribute('style', _customColorStyle(newColor));
+      else card.removeAttribute('style');
+      card.querySelectorAll('.note-card-color-dot').forEach(d => {
+        d.classList.toggle('active', _dotIsActive(d.dataset.color, newColor));
+        d.style.background = _dotBg(d.dataset.color, newColor);
+      });
+      await cardOperations.updateColor(id, newColor);
+    };
+    body.querySelectorAll('.note-card-color-dot').forEach(dot => {
+      dot.addEventListener('click', (e) => {
+        e.stopPropagation();
+        const card = dot.closest('.note-card');
+        const id = card.dataset.noteId;
+        if (dot.dataset.color === 'custom') {
+          _pickCustomBgImage().then(url => { if (url) _applyCardColor(card, id, 'bg:' + url); });
+          return;
+        }
+        _applyCardColor(card, id, dot.dataset.color);
+      });
+    });
+    // Plain pencil corner → open editor. The unarchive corner shares the
+    // .note-card-edit-corner class for styling, so :not() keeps the edit
+    // handler off it.
+    body.querySelectorAll('.note-card-edit-corner:not(.note-card-unarchive-corner)').forEach(btn => {
+      btn.addEventListener('click', (e) => {
+        e.stopPropagation();
+        const id = btn.dataset.noteId;
+        if (id) _editNote(id);
+      });
+    });
+    // Copy corner : bottom-right, just left of the Done check. Shared with
+     // the Ctrl/Cmd+C shortcut wired further down so both code paths run the
+     // same serializer + feedback flash.
+    // ⋯ corner menu : Copy + Agent (solve-this-todo).
+    body.querySelectorAll('.note-card-corner-menu').forEach(btn => {
+      btn.addEventListener('click', (e) => {
+        e.preventDefault();
+        e.stopPropagation();
+        _openNoteCornerMenu(btn);
+      });
+    });
+    body.querySelectorAll('.note-card-label-chip').forEach(chip => {
+      chip.addEventListener('click', (e) => {
+        e.preventDefault();
+        e.stopPropagation();
+        const label = chip.dataset.noteLabelFilter;
+        if (!label) return;
+        if (state.activeLabel === label && state.activeFilter === null) {
+          app.setActiveLabel(null);
+        } else {
+          app.setActiveFilter(null);
+          app.setActiveLabel(label);
+        }
+        _renderNotes();
+      });
+    });
+    // Done (✓) at bottom-right : only visible on hover for active notes.
+    body.querySelectorAll('.note-card-done').forEach(btn => {
+      btn.addEventListener('click', (e) => {
+        e.stopPropagation();
+        const id = btn.dataset.noteId;
+        const card = btn.closest('.note-card');
+        const idx = state.notes.findIndex(n => n.id === id);
+        if (idx < 0) return;
+        // Celebrate completion : same confetti shower the bulk-archive uses.
+        if (card) {
+          const r = card.getBoundingClientRect();
+          spawnConfetti(r.left + r.width / 2, r.top + r.height / 2, 80);
+        }
+        const finish = cardOperations.stageArchive(id);
+        if (!finish) return;
+        if (card) {
+          card.classList.add('note-card-sliding-out');
+          let done = false;
+          const once = () => { if (done) return; done = true; finish(); };
+          card.addEventListener('transitionend', once, { once: true });
+          setTimeout(once, 400);
+        } else {
+          finish();
+        }
+      });
+    });
+    // Unarchive corner : only visible in archive view.
+    body.querySelectorAll('.note-card-corner-unarchive').forEach(btn => {
+      btn.addEventListener('click', (e) => {
+        e.stopPropagation();
+        const id = btn.dataset.noteId;
+        cardOperations.unarchive(id);
+      });
+    });
+    // Trash corner : archive view only. Permanent delete, no confirmation.
+    body.querySelectorAll('.note-card-corner-trash').forEach(btn => {
+      btn.addEventListener('click', (e) => {
+        e.stopPropagation();
+        const id = btn.dataset.noteId;
+        cardOperations.deleteOptimistically(id, true);
+      });
+    });
+
+    body.querySelectorAll('.note-card-archive').forEach(btn => {
+      btn.addEventListener('click', (e) => {
+        e.stopPropagation();
+        const id = btn.dataset.noteId;
+        if (!id) return;
+        const card = btn.closest('.note-card');
+        let done = false;
+        const finishRemove = () => {
+          if (done) return;
+          done = true;
+          _archiveNoteById(id, { card, celebrate: true });
+        };
+        if (card) {
+          card.classList.add('note-card-sliding-out');
+          card.addEventListener('transitionend', finishRemove, { once: true });
+          setTimeout(finishRemove, 400);
+        } else {
+          finishRemove();
+        }
+      });
+    });
+    // Unarchive (optimistic) : only present in archive view
+    body.querySelectorAll('.note-card-unarchive').forEach(btn => {
+      btn.addEventListener('click', (e) => {
+        e.stopPropagation();
+        const id = btn.dataset.noteId;
+        cardOperations.unarchive(id);
+      });
+    });
+    // Delete (optimistic)
+    body.querySelectorAll('.note-card-delete, .note-card-x').forEach(btn => {
+      btn.addEventListener('click', (e) => {
+        e.stopPropagation();
+        const id = btn.dataset.noteId;
+        cardOperations.deleteOptimistically(id);
+      });
+    });
+    // Copy entire checklist (title + items, markdown-style)
+    body.querySelectorAll('.note-card-copy').forEach(btn => {
+      btn.addEventListener('click', async (e) => {
+        e.preventDefault();
+        e.stopPropagation();
+        e.stopImmediatePropagation();
+        const id = btn.dataset.noteId;
+        const note = state.notes.find(n => n.id === id);
+        if (!note) return;
+        const lines = [];
+        if (note.title) lines.push(note.title);
+        if (note.content) lines.push(note.content);
+        if (lines.length) lines.push('');
+        for (const it of (note.items || [])) {
+          if (!it || !(it.text || '').trim()) continue;
+          lines.push(`- [${it.done ? 'x' : ' '}] ${(it.text || '').trim()}`);
+        }
+        const text = lines.join('\n').trim();
+        try {
+          await navigator.clipboard.writeText(text);
+          uiModule.showToast?.(`Copied ${(note.items || []).filter(i => (i?.text || '').trim()).length} items`);
+        } catch {
+          // Fallback for browsers blocking the async API
+          const ta = document.createElement('textarea');
+          ta.value = text;
+          ta.style.position = 'fixed'; ta.style.left = '-9999px';
+          document.body.appendChild(ta);
+          ta.select();
+          try { document.execCommand('copy'); uiModule.showToast?.('Copied'); }
+          catch { uiModule.showError?.('Copy failed'); }
+          ta.remove();
+        }
+      });
+    });
+
+    _wireCardChecklist(body);
+    _wireCardReorder(body);
+
+  }
+
+  return { _bindCardEvents };
+}
diff --git a/frontend/src/features/notes/ui/cardRendering.js b/frontend/src/features/notes/ui/cardRendering.js
new file mode 100644
index 000000000..315e47218
--- /dev/null
+++ b/frontend/src/features/notes/ui/cardRendering.js
@@ -0,0 +1,244 @@
+/** Render note cards from application queries and read-only state. */
+import { _nextGoalStep, _goalProgress, _hasItems, _standardVisualVariant, _visibleNoteTags } from '../domain/noteRules.js';
+import { _hasTimeComponent, _formatRepeatLabel } from '../domain/recurrence.js';
+export function createCardRendering({
+  COLORS,
+  COLOR_HEX,
+  _animateReflow,
+  _applyMasonry,
+  _bindCardEvents,
+  _captureCardPositions,
+  _customColorStyle,
+  _dotBg,
+  _dotIsActive,
+  _esc,
+  _formatDueDate,
+  _formatReminderTag,
+  _hasActiveReminder,
+  _isBgImage,
+  _isDueOverdue,
+  _isNotesMobileMode,
+  _linkify,
+  _loadActiveHighlights,
+  _renderLabelsInto,
+  _renderQuickAdd,
+  _safeImgSrc,
+  _sortedVisibleNotes,
+  _updateRailBadge,
+  _wireTodayView,
+  state,
+  uiModule
+}) {
+  function _renderLoadingSkeleton() {
+    const body = document.querySelector('#notes-pane .notes-pane-body');
+    if (!body) return;
+    body.innerHTML = '';
+    _renderLabelsInto(body);
+    _renderQuickAdd(body);
+    const skel = document.createElement('div');
+    skel.className = 'notes-skeleton';
+    skel.innerHTML = `
+    <div class="notes-skeleton-card"></div>
+    <div class="notes-skeleton-card"></div>
+    <div class="notes-skeleton-card short"></div>
+    <div class="notes-skeleton-card"></div>
+  `;
+    body.appendChild(skel);
+  }
+
+  function _renderNotes() {
+    _updateRailBadge();
+    const body = document.querySelector('#notes-pane .notes-pane-body');
+    if (!body) return;
+    const prevPositions = _captureCardPositions();
+    const activeReminderHighlights = _loadActiveHighlights();
+
+    const sorted = _sortedVisibleNotes();
+
+    let html = '';
+    // Today view: render a compact card listing the next-unchecked step from
+    // each active goal. Tapping a step toggles it done (same idx-based wiring
+    // as regular checkboxes). Tapping the title opens the goal note for full
+    // editing.
+    if (state.activeFilter === 'today') {
+      body.innerHTML = '';
+      _renderLabelsInto(body);
+      _renderQuickAdd(body);
+      if (sorted.length === 0) {
+        body.insertAdjacentHTML('beforeend', `<div class="notes-empty">All caught up — no pending goal steps right now.</div>`);
+      } else {
+        let todayHtml = `<div class="notes-today-wrap">
+        <div class="notes-today-header">
+          <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="3" y="4" width="18" height="18" rx="2"/><line x1="16" y1="2" x2="16" y2="6"/><line x1="8" y1="2" x2="8" y2="6"/><line x1="3" y1="10" x2="21" y2="10"/></svg>
+          <span>Today &middot; one step per goal</span>
+        </div>
+        <div class="notes-today-list">`;
+        for (const note of sorted) {
+          const next = _nextGoalStep(note);
+          if (!next) continue;
+          const progress = _goalProgress(note).trim();
+          todayHtml += `<div class="notes-today-row" data-note-id="${note.id}">
+          <span class="note-check-dot" data-note-id="${note.id}" data-idx="${next.idx}" title="Mark step done"></span>
+          <div class="notes-today-text">
+            <div class="notes-today-title" data-action="edit" data-note-id="${note.id}">${_esc(note.title || '(untitled goal)')}</div>
+            <div class="notes-today-step">${_linkify(next.item.text || '')}</div>
+          </div>
+          <span class="notes-today-progress">${_esc(progress)}</span>
+        </div>`;
+        }
+        todayHtml += `</div></div>`;
+        body.insertAdjacentHTML('beforeend', todayHtml);
+      }
+      _wireTodayView(body);
+      return;
+    }
+    for (const note of sorted) {
+      if (state.editingId === note.id) continue; // skip : form is shown instead
+      const borderColor = COLOR_HEX[note.color || ''] || 'var(--border)';
+      const dueFmt = _formatDueDate(note.due_date);
+      const overdue = _isDueOverdue(note.due_date);
+
+      let contentHtml = '';
+      if (_hasItems(note) && Array.isArray(note.items)) {
+        // Goal notes can carry a free-form description above the step list :
+        // todos rarely do, but the same render works for both.
+        if (note.note_type === 'goal' && (note.content || '').trim()) {
+          const fullText = note.content || '';
+          const preview = fullText.length > 300 ? fullText.slice(0, 300) + '…' : fullText;
+          contentHtml += `<div class="note-goal-desc">${_esc(preview)}</div>`;
+        }
+        contentHtml += '<div class="note-checklist-preview">';
+        // Show ALL items : the preview container is scrollable (CSS caps
+        // its max-height + overflow-y:auto), so there's no need to truncate.
+        for (let i = 0; i < note.items.length; i++) {
+          const item = note.items[i];
+          const doneClass = item.done ? ' done' : '';
+          const indent = Math.min(item.indent || 0, 3);
+          contentHtml += `<div class="note-checkbox${doneClass}" data-note-id="${note.id}" data-idx="${i}" style="padding-left:${indent * 16}px">
+          <span class="note-check-dot" title="Mark done"></span>
+          <span class="note-check-text">${_linkify(item.text)}</span>
+          <button class="note-checkbox-edit" data-note-id="${note.id}" data-idx="${i}" title="Edit item">
+            <svg width="10" height="10" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M11 4H4a2 2 0 0 0-2 2v14a2 2 0 0 0 2 2h14a2 2 0 0 0 2-2v-7"/><path d="M18.5 2.5a2.121 2.121 0 0 1 3 3L12 15l-4 1 1-4 9.5-9.5z"/></svg>
+          </button>
+          <button class="note-checkbox-rm" data-note-id="${note.id}" data-idx="${i}" title="Delete item">
+            <svg width="10" height="10" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round"><line x1="18" y1="6" x2="6" y2="18"/><line x1="6" y1="6" x2="18" y2="18"/></svg>
+          </button>
+        </div>`;
+        }
+        contentHtml += '</div>';
+      } else {
+        const fullText = note.content || '';
+        const preview = fullText.length > 600 ? fullText.slice(0, 600) + '…' : fullText;
+        // _linkify already calls _esc internally, so URLs become clickable
+        // anchors (used by e.g. the "remind me to reply" email deep-link).
+        contentHtml = preview ? `<div class="note-content-preview">${_linkify(preview)}</div>` : '';
+      }
+
+      const isBg = _isBgImage(note.color);
+      const cc = (note.color && !isBg) ? ' note-color-' + note.color : '';
+      const cardStyle = isBg ? ` style="${_customColorStyle(note.color)}"` : '';
+      const isStandard = !note.note_type || note.note_type === 'note';
+      const visualClass = isStandard && !note.color ? ` note-standard note-standard-v${_standardVisualVariant(note)}` : '';
+      const sel = state.selectedIds.has(note.id) ? ' note-card-selected' : '';
+      const reminderTagHtml = note.due_date && _hasTimeComponent(note.due_date)
+        ? `<div class="note-card-reminder${overdue ? ' overdue' : ''}">
+          <svg width="10" height="10" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round"><path d="M18 8A6 6 0 0 0 6 8c0 7-3 9-3 9h18s-3-2-3-9"/><path d="M13.73 21a2 2 0 0 1-3.46 0"/></svg>
+          <span>${_esc(_formatReminderTag(note.due_date))}${note.repeat && note.repeat !== 'none' ? ' · ' + _esc(_formatRepeatLabel(note.repeat, new Date(note.due_date))) : ''}</span>
+        </div>`
+        : '';
+      const noteTags = _visibleNoteTags(note);
+      const dueBadge = dueFmt && !_hasTimeComponent(note.due_date) ? `<span class="note-due-inline${overdue ? ' note-due-overdue' : ''}">${dueFmt}</span>` : '';
+      const colorDots = COLORS.map(c => `<span class="note-card-color-dot${_dotIsActive(c.value, note.color) ? ' active' : ''}" data-color="${c.value}" style="background:${_dotBg(c.value, note.color)}" title="${c.name || 'default'}"></span>`).join('');
+      const goalClass = note.note_type === 'goal' ? ' note-card-goal' : '';
+      const reminderGlowClass = activeReminderHighlights.has(note.id) && _hasActiveReminder(note) ? ' note-card-reminder-fired-sticky' : '';
+      const goalPill = note.note_type === 'goal'
+        ? `<span class="note-goal-pill" title="AI-broken-down goal">
+          <svg width="10" height="10" viewBox="0 0 24 24" fill="currentColor"><path d="M12 0L14.59 8.41L23 12L14.59 15.59L12 24L9.41 15.59L1 12L9.41 8.41Z"/></svg>
+          Goal${_goalProgress(note)}
+        </span>`
+        : '';
+      const drawingClass = note.note_type === 'draw' ? ' note-card-drawing' : '';
+      html += `<div class="note-card${note.pinned ? ' note-card-pinned' : ''}${cc}${visualClass}${sel}${goalClass}${drawingClass}${reminderGlowClass}${state.selectMode ? ' note-card-selectmode' : ''}" draggable="${(state.selectMode || _isNotesMobileMode()) ? 'false' : 'true'}" data-note-id="${note.id}"${cardStyle}>
+      ${state.selectMode ? `<input type="checkbox" class="memory-select-cb note-card-cb" data-note-id="${note.id}" ${state.selectedIds.has(note.id) ? 'checked' : ''} />` : ''}
+      ${goalPill}
+      <button class="note-card-pin${note.pinned ? ' active' : ''}" data-note-id="${note.id}" title="${note.pinned ? 'Unpin' : 'Pin'}">
+        <svg width="16" height="16" viewBox="0 0 24 28" fill="${note.pinned ? 'currentColor' : 'none'}" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"${note.pinned ? ' style="color:var(--accent,var(--red));"' : ''}><g transform="rotate(${note.pinned ? 0 : 45} 12 14)" style="transition:transform 0.2s ease;"><line x1="12" y1="17" x2="12" y2="27"/><path d="M5 17h14v-1.76a2 2 0 0 0-1.11-1.79l-1.78-.9A2 2 0 0 1 15 10.76V6h1a2 2 0 0 0 0-4H8a2 2 0 0 0 0 4h1v4.76a2 2 0 0 1-1.11 1.79l-1.78.9A2 2 0 0 0 5 15.24V17z"/></g></svg>
+      </button>
+      ${state.showingArchived
+          ? `<button class="note-card-corner-trash" data-note-id="${note.id}" title="Delete forever" aria-label="Delete forever">
+            <svg width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><polyline points="3 6 5 6 21 6"/><path d="M19 6l-1 14a2 2 0 0 1-2 2H8a2 2 0 0 1-2-2L5 6"/><path d="M8 6V4a2 2 0 0 1 2-2h4a2 2 0 0 1 2 2v2"/><line x1="10" y1="11" x2="10" y2="17"/><line x1="14" y1="11" x2="14" y2="17"/></svg>
+          </button>
+          <button class="note-card-corner-unarchive" data-note-id="${note.id}" title="Unarchive" aria-label="Unarchive note">
+            <svg width="17" height="17" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round"><path d="M9 14l-5-5 5-5"/><path d="M4 9h11a5 5 0 0 1 5 5v0a5 5 0 0 1-5 5H9"/></svg>
+          </button>`
+          : `<button class="note-card-done" data-note-id="${note.id}" title="Mark done" aria-label="Mark done">
+            <svg width="17" height="17" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.4" stroke-linecap="round" stroke-linejoin="round"><polyline points="20 6 9 17 4 12"/></svg>
+          </button>
+          ${_hasItems(note) ? `<button class="note-card-copy note-card-copy-corner" data-note-id="${note.id}" title="Copy all items" aria-label="Copy all items">
+            <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="9" y="9" width="13" height="13" rx="2"/><path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"/></svg>
+          </button>` : ''}`}
+      <div class="note-card-header">
+        <div class="note-card-title${note.title ? '' : ' empty'}" data-action="edit">${_esc(note.title || '')}</div>
+        ${dueBadge}
+      </div>
+      ${_safeImgSrc(note.image_url) ? `<img class="note-card-image" src="${_esc(_safeImgSrc(note.image_url))}" alt="" draggable="false" />` : ''}
+      ${contentHtml}
+      ${_hasItems(note) ? `<div class="note-cl-quickadd"><input type="text" class="note-cl-quickadd-input" placeholder="+ Add item" data-note-id="${note.id}" /></div>` : ''}
+      ${reminderTagHtml}
+      ${noteTags.length ? `<div class="note-card-label">${noteTags.map(t => `<button type="button" class="note-card-label-chip" data-note-label-filter="${_esc(t)}" title="Filter #${_esc(t)}">#${_esc(t)}</button>`).join(' ')}</div>` : ''}
+      <div class="note-card-actions">
+        <div class="note-card-colors">${colorDots}</div>
+        <span style="flex:1"></span>
+        ${state.showingArchived ? `
+        <button class="note-card-action note-card-delete" data-note-id="${note.id}" title="Delete permanently">
+          <svg width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><polyline points="3 6 5 6 21 6"/><path d="M19 6l-1 14a2 2 0 0 1-2 2H8a2 2 0 0 1-2-2L5 6"/><path d="M8 6V4a2 2 0 0 1 2-2h4a2 2 0 0 1 2 2v2"/><line x1="10" y1="11" x2="10" y2="17"/><line x1="14" y1="11" x2="14" y2="17"/></svg>
+        </button>
+        <button class="note-card-action note-card-unarchive" data-note-id="${note.id}" title="Unarchive">
+          <svg width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M3 12a9 9 0 1 0 3-6.7"/><polyline points="3 4 3 10 9 10"/></svg>
+        </button>` : `
+        ${_hasItems(note) ? `
+        <button class="note-card-action note-card-copy" data-note-id="${note.id}" title="Copy all items">
+          <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="9" y="9" width="13" height="13" rx="2"/><path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"/></svg>
+        </button>` : ''}
+        <button class="note-card-action note-card-archive" data-note-id="${note.id}" title="Save (archive)">
+          <svg width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M19 21H5a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2h11l5 5v11a2 2 0 0 1-2 2z"/><polyline points="17 21 17 13 7 13 7 21"/><polyline points="7 3 7 8 15 8"/></svg>
+        </button>
+        <button class="note-card-action note-card-delete" data-note-id="${note.id}" title="Delete">
+          <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round"><line x1="18" y1="6" x2="6" y2="18"/><line x1="6" y1="6" x2="18" y2="18"/></svg>
+        </button>
+        <button class="note-card-action note-card-corner-menu" data-note-id="${note.id}" title="More" aria-label="More actions">
+          <svg width="16" height="16" viewBox="0 0 24 24" fill="currentColor"><circle cx="5" cy="12" r="1.7"/><circle cx="12" cy="12" r="1.7"/><circle cx="19" cy="12" r="1.7"/></svg>
+        </button>`}
+      </div>
+    </div>`;
+    }
+
+    // Always render quick-add at top (collapsed unless user is typing)
+    const existingForm = body.querySelector('.note-form');
+    if (existingForm && state.editingId === '__new__') {
+      // Keep the expanded form, replace cards after it
+      const next = [...body.children].filter(c => c !== existingForm);
+      next.forEach(c => c.remove());
+      if (sorted.length === 0) {
+        body.insertAdjacentHTML('beforeend', '<div class="notes-empty-msg">No notes <span style="vertical-align:-3px;margin-left:4px;">' + uiModule.emptyStateIcon('smiley') + '</span></div>');
+      } else {
+        existingForm.insertAdjacentHTML('afterend', html);
+      }
+    } else {
+      body.innerHTML = '';
+      _renderLabelsInto(body);
+      _renderQuickAdd(body);
+      if (sorted.length === 0) {
+        body.insertAdjacentHTML('beforeend', '<div class="notes-empty-msg">No notes yet <span style="vertical-align:-3px;margin-left:4px;">' + uiModule.emptyStateIcon('smiley') + '</span></div>');
+      } else {
+        body.insertAdjacentHTML('beforeend', html);
+      }
+    }
+
+    _bindCardEvents(body);
+    _animateReflow(prevPositions);
+    _applyMasonry(body);
+  }
+
+  return { _renderLoadingSkeleton, _renderNotes };
+}
diff --git a/frontend/src/features/notes/ui/cardReorder.js b/frontend/src/features/notes/ui/cardReorder.js
new file mode 100644
index 000000000..dd32d517c
--- /dev/null
+++ b/frontend/src/features/notes/ui/cardReorder.js
@@ -0,0 +1,181 @@
+/** Desktop and large-touch-device card reorder gestures. */
+export function createCardReorder({
+  lifecycle,
+  _isNotesMobileMode,
+  persistOrder,
+  state
+}) {
+  function _wireCardReorder(body) {
+    lifecycle.release(body);
+    // Drag-reorder notes on pointer/mouse devices. Mobile uses the custom
+    // placeholder sorter below `_bindLongPressDrag`; native HTML5 dragging is
+    // unreliable on touch browsers and can compete with the long-press flow.
+    if (!_isNotesMobileMode()) {
+      body.querySelectorAll('.note-card').forEach(card => {
+        card.addEventListener('dragstart', (e) => {
+          if (e.target.closest('.note-checkbox, .note-card-x, .note-card-select, .note-card-pin, .note-card-action, .note-card-color-dot, .note-card-title, .note-card-edit, .note-card-edit-corner, .note-card-done, .note-card-corner-menu, .note-agent-tag, .note-card-label-chip')) {
+            e.preventDefault();
+            return;
+          }
+          card.classList.add('dragging');
+          body.classList.add('drag-active');
+          e.dataTransfer.effectAllowed = 'move';
+          try { e.dataTransfer.setData('text/plain', card.dataset.noteId); } catch {}
+        });
+        card.addEventListener('dragend', async () => {
+          card.classList.remove('dragging');
+          body.classList.remove('drag-active');
+          body.querySelectorAll('.drop-before, .drop-after').forEach(el => el.classList.remove('drop-before', 'drop-after'));
+          const ids = [...body.querySelectorAll('.note-card')].map(c => c.dataset.noteId);
+          try { await persistOrder(ids); }
+          catch {}
+        });
+      });
+    }
+    // Track which card we last swapped with so a single hover-over triggers
+    // one swap, not a jitter as the pointer keeps moving inside the same card.
+    let _lastSwapId = null;
+    function _maybeSwap(dragging, clientX, clientY) {
+      const target = document.elementFromPoint(clientX, clientY)?.closest('.note-card');
+      if (!target || target === dragging || !body.contains(target)) return;
+      const id = target.dataset.noteId;
+      if (id === _lastSwapId) return;
+      // FLIP across ALL siblings. In list view only `target` moves visually, but
+      // in grid view (2-col) and when the pinned-section grid-column-start rule
+      // shifts, several cards reflow at once. Capture every card's pre-swap rect,
+      // do the DOM swap, then animate any that actually moved. The dragging card
+      // is excluded : it's already finger-tracked via translate3d.
+      const cards = [...body.querySelectorAll('.note-card')].filter(c => c !== dragging);
+      const prevRects = new Map(cards.map(c => [c, c.getBoundingClientRect()]));
+      const draggingNext = dragging.nextSibling === target ? dragging : dragging.nextSibling;
+      body.insertBefore(dragging, target);
+      body.insertBefore(target, draggingNext);
+      for (const c of cards) {
+        const prev = prevRects.get(c);
+        const next = c.getBoundingClientRect();
+        const dx = prev.left - next.left;
+        const dy = prev.top - next.top;
+        if (Math.abs(dx) < 0.5 && Math.abs(dy) < 0.5) continue;
+        c.style.transition = 'none';
+        c.style.transform = `translate(${dx}px, ${dy}px)`;
+        requestAnimationFrame(() => {
+          c.style.transition = 'transform 0.22s cubic-bezier(0.34, 1.2, 0.64, 1)';
+          c.style.transform = '';
+          c.addEventListener('transitionend', () => { c.style.transition = ''; }, { once: true });
+        });
+      }
+      _lastSwapId = id;
+    }
+    lifecycle.listen(body, body, 'dragover', (e) => {
+      e.preventDefault();
+      const dragging = body.querySelector('.note-card.dragging');
+      if (!dragging) return;
+      _maybeSwap(dragging, e.clientX, e.clientY);
+    });
+    lifecycle.listen(body, body, 'dragend', () => { _lastSwapId = null; });
+
+    // Legacy touch drag for larger touch devices only. Phone-sized Notes uses
+    // the placeholder sorter wired by `_bindLongPressDrag`; running both flows
+    // makes one press start two independent drag sessions.
+    if (!_isNotesMobileMode() && 'ontouchstart' in window) {
+      let dragCard = null;
+      let isDragging = false;
+      let longPressTimer = null;
+      let startX = 0, startY = 0;
+      const LONG_PRESS_MS = 350;
+      const MOVE_THRESHOLD_PX = 8;
+      const _selectorSkip = '.note-checkbox, .note-card-x, .note-card-select, .note-card-pin, .note-card-action, .note-card-color-dot, .note-card-title, .note-card-edit, .note-card-edit-corner, .note-card-done, .note-card-corner-menu, .note-agent-tag, .note-card-label-chip, input, textarea, button, a';
+
+      // Anchor for the finger-follow transform. Recomputed after every swap so
+      // the card stays under the finger across reorderings.
+      let anchorX = 0, anchorY = 0;
+      const _follow = (clientX, clientY) => {
+        if (!dragCard) return;
+        const dx = clientX - anchorX;
+        const dy = clientY - anchorY;
+        // Compose with the CSS .dragging transform (scale + rotate).
+        dragCard.style.transform = `translate3d(${dx}px, ${dy}px, 0) scale(1.03) rotate(-0.6deg)`;
+      };
+      const _reanchor = (clientX, clientY) => {
+        if (!dragCard) return;
+        // Clear any prior translate so the card resettles in its natural slot,
+        // then anchor at the finger's current position. Subsequent _follow calls
+        // translate by (finger - anchor), keeping the finger at the same relative
+        // spot on the card it had when we re-anchored.
+        dragCard.style.transform = '';
+        anchorX = clientX;
+        anchorY = clientY;
+      };
+
+      const _endDrag = (committed) => {
+        clearTimeout(longPressTimer);
+        longPressTimer = null;
+        if (dragCard) {
+          dragCard.classList.remove('dragging');
+          dragCard.style.transform = '';
+        }
+        body.classList.remove('drag-active');
+        _lastSwapId = null;
+        if (isDragging) {
+          document.documentElement.style.touchAction = '';
+          if (committed) {
+            const ids = [...body.querySelectorAll('.note-card')].map(c => c.dataset.noteId);
+            persistOrder(ids).catch(() => {});
+          }
+        }
+        dragCard = null;
+        isDragging = false;
+      };
+      lifecycle.onDispose(body, () => _endDrag(false));
+
+      lifecycle.listen(body, body, 'touchstart', (e) => {
+        if (state.selectMode) return;
+        const card = e.target.closest('.note-card');
+        if (!card) return;
+        if (e.target.closest(_selectorSkip)) return;
+        const t = e.touches[0];
+        startX = t.clientX; startY = t.clientY;
+        dragCard = card;
+        longPressTimer = setTimeout(() => {
+          if (!dragCard) return;
+          isDragging = true;
+          dragCard.classList.add('dragging');
+          body.classList.add('drag-active');
+          document.documentElement.style.touchAction = 'none';
+          _reanchor(startX, startY);
+          try { if (navigator.vibrate) navigator.vibrate(15); } catch {}
+        }, LONG_PRESS_MS);
+      }, { passive: true });
+
+      lifecycle.listen(body, body, 'touchmove', (e) => {
+        if (!dragCard) return;
+        const t = e.touches[0];
+        if (!isDragging) {
+          // Movement before long-press fires = user is scrolling; cancel pickup.
+          if (Math.abs(t.clientX - startX) > MOVE_THRESHOLD_PX || Math.abs(t.clientY - startY) > MOVE_THRESHOLD_PX) {
+            clearTimeout(longPressTimer);
+            longPressTimer = null;
+            dragCard = null;
+          }
+          return;
+        }
+        e.preventDefault();
+        // Live-follow the finger first, then check for a swap. After a swap the
+        // card's natural slot moves, so we re-anchor and re-apply the offset.
+        _follow(t.clientX, t.clientY);
+        const before = dragCard.parentNode && [...dragCard.parentNode.children].indexOf(dragCard);
+        _maybeSwap(dragCard, t.clientX, t.clientY);
+        const after = dragCard.parentNode && [...dragCard.parentNode.children].indexOf(dragCard);
+        if (before !== after) {
+          _reanchor(t.clientX, t.clientY);
+          _follow(t.clientX, t.clientY);
+        }
+      }, { passive: false });
+
+      lifecycle.listen(body, body, 'touchend', () => _endDrag(true));
+      lifecycle.listen(body, body, 'touchcancel', () => _endDrag(false));
+    }
+  }
+
+  return { _wireCardReorder };
+}
diff --git a/frontend/src/features/notes/ui/checklist.js b/frontend/src/features/notes/ui/checklist.js
new file mode 100644
index 000000000..59a01aaa4
--- /dev/null
+++ b/frontend/src/features/notes/ui/checklist.js
@@ -0,0 +1,190 @@
+/** Checklist rows, goal forms, keyboard input and item collection. */
+export function createChecklist({
+  _esc,
+  _uid,
+  spawnConfetti
+}) {
+  function _buildGoalHtml(note, items) {
+    const desc = (note?.content || '').toString();
+    return `
+    <div class="note-form-goal">
+      <textarea class="note-form-goal-desc" placeholder="Description (optional)" rows="3">${_esc(desc)}</textarea>
+      ${_buildChecklistHtml(items)}
+    </div>
+  `;
+  }
+
+  function _wireGoalForm(form, container) {
+    if (!container) return;
+    // _wireHashtag is a closure inside _buildForm : out of scope here. Inline
+    // the same behavior (type "#foo " in the description → tag added to the
+    // form's label input) so editing a goal note doesn't ReferenceError.
+    const desc = container.querySelector('.note-form-goal-desc');
+    const labelInput = form?.querySelector('.note-form-label');
+    if (desc && labelInput) {
+      const tagRe = /(^|\s)#([A-Za-z0-9][\w-]*)\s$/;
+      desc.addEventListener('input', () => {
+        const m = tagRe.exec(desc.value);
+        if (!m) return;
+        const tag = m[2];
+        // Same dedup-after-stripping fix as the plain note hashtag handler.
+        const existing = labelInput.value.trim().split(/\s+/).filter(Boolean);
+        const stripped = existing.map(t => t.replace(/^#+/, ''));
+        if (!stripped.includes(tag)) {
+          existing.push('#' + tag);
+          labelInput.value = existing.join(' ');
+          labelInput.classList.add('flash-once');
+          setTimeout(() => labelInput.classList.remove('flash-once'), 600);
+        }
+        const cut = desc.value.length - m[0].length + m[1].length;
+        desc.value = desc.value.slice(0, cut);
+      });
+    }
+    // Always wire the checklist. The previous gate on a `note-form-goal-fresh`
+    // class was dead code : nothing ever set that class, so the editor never
+    // hooked up add/drag/Tab.
+    _wireChecklist(container);
+  }
+
+  function _buildChecklistHtml(items) {
+    let html = '<div class="note-checklist-inputs">';
+    for (const item of items) {
+      const indent = Math.min(item.indent || 0, 3);
+      html += `<div class="note-cl-row${item.done ? ' done' : ''}" draggable="true" data-item-id="${item.id || _uid()}" data-indent="${indent}" style="padding-left:${indent * 16}px">
+      <span class="note-cl-grip" title="Drag to reorder">⋮⋮</span>
+      <span class="note-cl-dot"></span>
+      <input type="text" class="note-cl-text" value="${_esc(item.text)}" placeholder="Item..." />
+      <button type="button" class="note-cl-rm">&times;</button>
+    </div>`;
+    }
+    // `type="button"` matters on mobile : without it some browsers treat
+    // bare <button> as form-submit and the click handler never fires inside
+    // certain containers. Also bumped tap target so fingers don't miss.
+    html += `<button type="button" class="note-cl-add">+ Add</button></div>`;
+    return html;
+  }
+
+  function _wireRow(row, container) {
+    row.querySelector('.note-cl-rm')?.addEventListener('click', () => row.remove());
+    row.querySelector('.note-cl-dot')?.addEventListener('click', () => {
+      const wasDone = row.classList.contains('done');
+      row.classList.toggle('done');
+      // The custom dot has no native input/change event. Notify the form so
+      // mobile edit mode switches its action from Archive back to Update.
+      container.dispatchEvent(new Event('input', { bubbles: true }));
+      const becameDone = !wasDone;  // we just flipped it
+      const dot = row.querySelector('.note-cl-dot');
+      const dRect = (dot || row).getBoundingClientRect();
+      // Small confetti burst on each fresh check so the user gets a
+      // "well done" beat per item, not just the grand-finale on all-done.
+      if (becameDone) {
+        spawnConfetti(dRect.left + dRect.width / 2, dRect.top + dRect.height / 2, 16);
+      }
+      // Bigger burst when the whole list is now done.
+      const rows = [...container.querySelectorAll('.note-cl-row')];
+      const hasText = rows.some(r => (r.querySelector('.note-cl-text')?.value || '').trim().length > 0);
+      if (hasText && rows.every(r => r.classList.contains('done') || !(r.querySelector('.note-cl-text')?.value || '').trim())) {
+        spawnConfetti(dRect.left + dRect.width / 2, dRect.top + dRect.height / 2, 60);
+      }
+    });
+    const txt = row.querySelector('.note-cl-text');
+    txt?.addEventListener('keydown', (e) => {
+      if (e.key === 'Enter') { e.preventDefault(); container.querySelector('.note-cl-add')?.click(); }
+      else if (e.key === 'Tab') {
+        e.preventDefault();
+        const cur = parseInt(row.dataset.indent || '0');
+        const next = e.shiftKey ? Math.max(0, cur - 1) : Math.min(3, cur + 1);
+        row.dataset.indent = String(next);
+        row.style.paddingLeft = (next * 16) + 'px';
+      } else if (e.key === 'Backspace' && txt.value === '') {
+        e.preventDefault();
+        const prev = row.previousElementSibling;
+        row.remove();
+        if (prev && prev.classList.contains('note-cl-row')) prev.querySelector('.note-cl-text')?.focus();
+      }
+    });
+    // Drag handlers
+    row.addEventListener('dragstart', (e) => {
+      row.classList.add('dragging');
+      e.dataTransfer.effectAllowed = 'move';
+      try { e.dataTransfer.setData('text/plain', row.dataset.itemId); } catch {}
+    });
+    row.addEventListener('dragend', () => {
+      row.classList.remove('dragging');
+      container.querySelectorAll('.drop-before, .drop-after').forEach(el => el.classList.remove('drop-before', 'drop-after'));
+    });
+  }
+
+  function _wireChecklist(container) {
+    if (!container) return;
+    // Delegate the + Add click off the container so re-renders + mobile
+    // touch quirks don't leave the button dead. The previous direct
+    // `addEventListener` on the button silently broke on mobile when
+    // _wireChecklist ran more than once (or before the button was in DOM).
+    if (!container._addDelegated) {
+      container._addDelegated = true;
+      container.addEventListener('click', (ev) => {
+        const addBtn = ev.target.closest('.note-cl-add');
+        if (!addBtn || !container.contains(addBtn)) return;
+        ev.preventDefault();
+        ev.stopPropagation();
+        const inputs = container.querySelector('.note-checklist-inputs');
+        if (!inputs) return;
+        const row = document.createElement('div');
+        row.className = 'note-cl-row';
+        row.draggable = true;
+        row.dataset.itemId = _uid();
+        row.dataset.indent = '0';
+        row.innerHTML = `<span class="note-cl-grip" title="Drag">⋮⋮</span><span class="note-cl-dot"></span><input type="text" class="note-cl-text" placeholder="Item..." /><button type="button" class="note-cl-rm">&times;</button>`;
+        inputs.insertBefore(row, addBtn);
+        row.querySelector('.note-cl-text').focus();
+        _wireRow(row, container);
+      });
+    }
+    container.querySelectorAll('.note-cl-row').forEach(row => _wireRow(row, container));
+
+    // Drag-over handler on the inputs container
+    const inputs = container.querySelector('.note-checklist-inputs');
+    if (inputs) {
+      inputs.addEventListener('dragover', (e) => {
+        e.preventDefault();
+        const dragging = inputs.querySelector('.note-cl-row.dragging');
+        if (!dragging) return;
+        inputs.querySelectorAll('.drop-before, .drop-after').forEach(el => el.classList.remove('drop-before', 'drop-after'));
+        const rows = [...inputs.querySelectorAll('.note-cl-row:not(.dragging)')];
+        const after = rows.find(r => {
+          const box = r.getBoundingClientRect();
+          return e.clientY < box.top + box.height / 2;
+        });
+        if (after) {
+          after.classList.add('drop-before');
+          inputs.insertBefore(dragging, after);
+        } else if (rows.length) {
+          rows[rows.length - 1].classList.add('drop-after');
+          inputs.insertBefore(dragging, container.querySelector('.note-cl-add'));
+        }
+      });
+      inputs.addEventListener('dragleave', (e) => {
+        if (!inputs.contains(e.relatedTarget)) {
+          inputs.querySelectorAll('.drop-before, .drop-after').forEach(el => el.classList.remove('drop-before', 'drop-after'));
+        }
+      });
+    }
+  }
+
+  function _collectItems(form) {
+    const items = [];
+    form.querySelectorAll('.note-cl-row').forEach(row => {
+      const text = row.querySelector('.note-cl-text')?.value?.trim();
+      if (text) items.push({
+        id: row.dataset.itemId || _uid(),
+        text,
+        done: row.classList.contains('done'),
+        indent: parseInt(row.dataset.indent || '0'),
+      });
+    });
+    return items;
+  }
+
+  return { _buildGoalHtml, _wireGoalForm, _buildChecklistHtml, _wireRow, _wireChecklist, _collectItems };
+}
diff --git a/frontend/src/features/notes/ui/checklistReorder.js b/frontend/src/features/notes/ui/checklistReorder.js
new file mode 100644
index 000000000..c5c7e1101
--- /dev/null
+++ b/frontend/src/features/notes/ui/checklistReorder.js
@@ -0,0 +1,111 @@
+/** Mobile checklist grip dragging and document listener ownership. */
+export function createChecklistReorder({
+  lifecycle
+}) {
+  let _clDrag = null;
+
+  let _clDocBound = false;
+  let _clOwner = null;
+
+  function _wireChecklistTouchReorder(form) {
+    const container = form.querySelector('.note-checklist-inputs');
+    if (!container) return;
+    container.querySelectorAll('.note-cl-grip').forEach(grip => {
+      if (grip.dataset.touchBound === '1') return;
+      grip.dataset.touchBound = '1';
+      grip.addEventListener('touchstart', (e) => {
+        if (e.touches.length !== 1) return;
+        e.preventDefault();
+        const row = grip.closest('.note-cl-row');
+        if (!row) return;
+        _beginChecklistGrab(row, container, e.touches[0]);
+      }, { passive: false });
+    });
+    if (!_clDocBound || _clOwner !== form) {
+      if (_clOwner) lifecycle.release(_clOwner);
+      _clOwner = form;
+      lifecycle.listen(form, document, 'touchmove', _onClTouchMove, { passive: false });
+      lifecycle.listen(form, document, 'touchend',  _onClTouchEnd,  { passive: true });
+      lifecycle.listen(form, document, 'touchcancel', _onClTouchEnd, { passive: true });
+      _clDocBound = true;
+    }
+  }
+
+  function _beginChecklistGrab(row, container, touch) {
+    if (_clDrag) return;
+    const rect = row.getBoundingClientRect();
+    const placeholder = document.createElement('div');
+    placeholder.className = 'note-cl-row-placeholder';
+    placeholder.style.height = rect.height + 'px';
+    container.insertBefore(placeholder, row);
+
+    row.classList.add('note-cl-row-dragging');
+    row.style.position = 'fixed';
+    row.style.left = rect.left + 'px';
+    row.style.top  = rect.top + 'px';
+    row.style.width = rect.width + 'px';
+    row.style.zIndex = '10002';
+    row.style.pointerEvents = 'none';
+
+    _clDrag = {
+      row, placeholder, container,
+      grabOffsetX: touch.clientX - rect.left,
+      grabOffsetY: touch.clientY - rect.top,
+    };
+    try { navigator.vibrate?.(8); } catch {}
+  }
+
+  function _onClTouchMove(e) {
+    if (!_clDrag) return;
+    if (e.touches.length !== 1) return;
+    e.preventDefault();
+    const t = e.touches[0];
+    const { row, placeholder, container } = _clDrag;
+    row.style.left = (t.clientX - _clDrag.grabOffsetX) + 'px';
+    row.style.top  = (t.clientY - _clDrag.grabOffsetY) + 'px';
+
+    const under = document.elementFromPoint(t.clientX, t.clientY);
+    const target = under && under.closest
+      ? under.closest('.note-cl-row:not(.note-cl-row-dragging)')
+      : null;
+    if (!target || target === row) return;
+    if (target.parentNode !== container) return;
+
+    const tRect = target.getBoundingClientRect();
+    const targetMidY = tRect.top + tRect.height / 2;
+    if (t.clientY < targetMidY) {
+      if (placeholder.nextElementSibling !== target) {
+        container.insertBefore(placeholder, target);
+      }
+    } else {
+      if (target.nextElementSibling !== placeholder) {
+        container.insertBefore(placeholder, target.nextElementSibling);
+      }
+    }
+  }
+
+  function _onClTouchEnd() {
+    if (!_clDrag) return;
+    const { row, placeholder } = _clDrag;
+    _clDrag = null;
+    const phRect = placeholder.getBoundingClientRect();
+    row.style.transition = 'left 0.18s ease, top 0.18s ease';
+    row.style.left = phRect.left + 'px';
+    row.style.top  = phRect.top + 'px';
+    setTimeout(() => {
+      placeholder.parentNode.insertBefore(row, placeholder);
+      placeholder.remove();
+      row.classList.remove('note-cl-row-dragging');
+      row.style.cssText = '';
+      // Order is persisted as part of the form's normal save (rows are
+      // re-serialized in DOM order via _collectItems).
+    }, 200);
+  }
+
+  function dispose() {
+    if (_clDrag) _onClTouchEnd();
+    _clDocBound = false;
+    _clOwner = null;
+  }
+  return { dispose, _wireChecklistTouchReorder, _beginChecklistGrab, _onClTouchMove, _onClTouchEnd };
+}
diff --git a/frontend/src/features/notes/ui/clipboard.js b/frontend/src/features/notes/ui/clipboard.js
new file mode 100644
index 000000000..1dab84258
--- /dev/null
+++ b/frontend/src/features/notes/ui/clipboard.js
@@ -0,0 +1,82 @@
+/** Note clipboard feedback and the Copy/Agent corner menu. */
+import { _serializeNoteForCopy } from '../domain/noteRules.js';
+export function createClipboard({
+  _agentSolveNote,
+  bindMenuDismiss,
+  dismissOrRemove,
+  state,
+  topPortalZ,
+  uiModule
+}) {
+  function _openNoteCornerMenu(btn) {
+    document.querySelectorAll('.note-corner-menu-dropdown').forEach(dismissOrRemove);
+    const id = btn.dataset.noteId;
+    const note = state.notes.find(n => n.id === id);
+    if (!note) return;
+    const menu = document.createElement('div');
+    menu.className = 'note-corner-menu-dropdown';
+    menu.innerHTML = `
+    <button type="button" class="ncm-item" data-act="copy">
+      <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="9" y="9" width="13" height="13" rx="2"/><path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"/></svg>
+      <span>Copy</span>
+    </button>
+    <button type="button" class="ncm-item" data-act="agent">
+      <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M12 8V4H8"/><rect x="4" y="8" width="16" height="12" rx="2"/><path d="M2 14h2M20 14h2M15 13v2M9 13v2"/></svg>
+      <span>${note.agent_session_id ? 'Re-run agent' : 'Agent: solve this'}</span>
+    </button>`;
+    document.body.appendChild(menu);
+    const r = btn.getBoundingClientRect();
+    // Right-align to the ⋯ button, clamped to the viewport.
+    const mw = 168;
+    let left = Math.min(r.right - mw, window.innerWidth - mw - 8);
+    left = Math.max(8, left);
+    // Drop down by default; flip up if there isn't room below (the button
+    // sits at the card's bottom edge now).
+    const mh = menu.offsetHeight || 96;
+    const below = window.innerHeight - r.bottom;
+    const top = (below < mh + 8 && r.top > mh + 8) ? (r.top - mh - 4) : (r.bottom + 4);
+    menu.style.cssText += `position:fixed;z-index:${topPortalZ()};top:${Math.round(top)}px;left:${Math.round(left)}px;`;
+    const close = bindMenuDismiss(menu, () => { menu.remove(); });
+    menu.querySelector('[data-act="copy"]').addEventListener('click', () => { close(); _copyNote(id, btn); });
+    menu.querySelector('[data-act="agent"]').addEventListener('click', () => { close(); _agentSolveNote(id); });
+  }
+
+  async function _copyNote(noteId, btnEl) {
+    const note = state.notes.find(n => n.id === noteId);
+    if (!note) return false;
+    const text = _serializeNoteForCopy(note);
+    if (!text) return false;
+    let ok = false;
+    try {
+      await navigator.clipboard.writeText(text);
+      ok = true;
+    } catch {
+      const ta = document.createElement('textarea');
+      ta.value = text;
+      ta.style.position = 'fixed'; ta.style.left = '-9999px';
+      document.body.appendChild(ta);
+      ta.select();
+      try { ok = document.execCommand('copy'); } catch { ok = false; }
+      ta.remove();
+    }
+    if (ok) {
+      if (btnEl && !btnEl._copyFlashing) {
+        const original = btnEl.innerHTML;
+        btnEl._copyFlashing = true;
+        btnEl.innerHTML = '<svg width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.4" stroke-linecap="round" stroke-linejoin="round"><polyline points="20 6 9 17 4 12"/></svg>';
+        btnEl.classList.add('copied');
+        setTimeout(() => {
+          btnEl.innerHTML = original;
+          btnEl.classList.remove('copied');
+          btnEl._copyFlashing = false;
+        }, 1200);
+      }
+      uiModule.showToast?.('Copied');
+    } else {
+      uiModule.showError?.('Copy failed');
+    }
+    return ok;
+  }
+
+  return { _openNoteCornerMenu, _copyNote };
+}
diff --git a/frontend/src/features/notes/ui/colors.js b/frontend/src/features/notes/ui/colors.js
new file mode 100644
index 000000000..0a9503cfb
--- /dev/null
+++ b/frontend/src/features/notes/ui/colors.js
@@ -0,0 +1,111 @@
+/** Note colors, custom background selection and form color controls. */
+export function createColors({
+  api
+}) {
+  const COLORS = [
+    { name: 'none',    value: '' },
+    { name: 'red',     value: 'red' },
+    { name: 'orange',  value: 'orange' },
+    { name: 'yellow',  value: 'yellow' },
+    { name: 'green',   value: 'green' },
+    { name: 'blue',    value: 'blue' },
+    { name: 'purple',  value: 'purple' },
+    { name: 'custom',  value: 'custom' },  // sentinel : clicking opens native color picker
+  ];
+
+  const COLOR_HEX = {
+    '':       'var(--border)',
+    // Pale/pastel palette : matches the calendar event color picker.
+    red:      '#f0b5ba',
+    orange:   '#e8ccb2',
+    yellow:   '#f2dfbd',
+    green:    '#cce0bc',
+    blue:     '#b0d7f7',
+    purple:   '#e2bcee',
+  };
+
+  const _CUSTOM_GRADIENT = 'conic-gradient(from 0deg, #e06c75, #d19a66, #e5c07b, #98c379, #61afef, #c678dd, #e06c75)';
+
+  function _isBgImage(c) { return typeof c === 'string' && c.startsWith('bg:'); }
+
+  function _bgImageUrl(c) { return _isBgImage(c) ? c.slice(3) : ''; }
+
+  function _dotBg(value, noteColor) {
+    if (value === 'custom') {
+      const url = _bgImageUrl(noteColor);
+      return url ? `center/cover no-repeat url('${url}')` : _CUSTOM_GRADIENT;
+    }
+    return COLOR_HEX[value];
+  }
+
+  function _dotIsActive(value, noteColor) {
+    if (value === 'custom') return _isBgImage(noteColor);
+    return value === (noteColor || '');
+  }
+
+  function _customColorStyle(c) {
+    if (!_isBgImage(c)) return '';
+    const url = _bgImageUrl(c);
+    return `background-image: linear-gradient(color-mix(in srgb, var(--panel) 60%, transparent), color-mix(in srgb, var(--panel) 60%, transparent)), url('${url}'); background-size: cover; background-position: center; border-color: color-mix(in srgb, var(--fg) 25%, var(--border));`;
+  }
+
+  function _pickCustomBgImage() {
+    return new Promise(resolve => {
+      const input = document.createElement('input');
+      input.type = 'file';
+      input.accept = 'image/*';
+      input.style.cssText = 'position:fixed; left:-9999px; top:-9999px;';
+      document.body.appendChild(input);
+      let done = false;
+      const finish = (v) => { if (done) return; done = true; input.remove(); resolve(v); };
+      input.addEventListener('change', async () => {
+        const file = input.files?.[0];
+        if (!file) return finish(null);
+        const fd = new FormData();
+        fd.append('files', file);
+        try {
+          const res = await api.upload(fd);
+          const data = await res.json();
+          const fileId = data.files?.[0]?.id;
+          if (!fileId) throw new Error('Upload failed');
+          finish(api.uploadUrl(fileId));
+        } catch { finish(null); }
+      });
+      // Best-effort cleanup if user dismisses the dialog.
+      setTimeout(() => { if (!done && !input.files?.length) finish(null); }, 30000);
+      input.click();
+    });
+  }
+
+  function _wireFormColors(form, setColor) {
+    // Color dots : apply to entire form immediately
+    const _applyFormColor = (newColor) => {
+      const currentColor = newColor || '';
+      setColor(currentColor);
+      form.dataset.noteColor = currentColor;
+      const isBg = _isBgImage(currentColor);
+      COLORS.forEach(c => { if (c.value && c.value !== 'custom') form.classList.remove('note-color-' + c.value); });
+      if (currentColor && !isBg) form.classList.add('note-color-' + currentColor);
+      if (isBg) form.setAttribute('style', _customColorStyle(currentColor));
+      else form.removeAttribute('style');
+      form.querySelectorAll('.note-color-dot').forEach(d => {
+        d.classList.toggle('active', _dotIsActive(d.dataset.color, currentColor));
+        d.style.background = _dotBg(d.dataset.color, currentColor);
+      });
+      form.dispatchEvent(new Event('change', { bubbles: true }));
+    };
+    form.querySelectorAll('.note-color-dot').forEach(dot => {
+      dot.addEventListener('click', () => {
+        if (dot.dataset.color === 'custom') {
+          _pickCustomBgImage().then(url => { if (url) _applyFormColor('bg:' + url); });
+          return;
+        }
+        _applyFormColor(dot.dataset.color);
+      });
+    });
+
+
+  }
+
+  return { COLORS, COLOR_HEX, _isBgImage, _bgImageUrl, _dotBg, _dotIsActive, _customColorStyle, _pickCustomBgImage, _wireFormColors };
+}
diff --git a/frontend/src/features/notes/ui/draftEditor.js b/frontend/src/features/notes/ui/draftEditor.js
new file mode 100644
index 000000000..09df33b79
--- /dev/null
+++ b/frontend/src/features/notes/ui/draftEditor.js
@@ -0,0 +1,67 @@
+/** Collect editor drafts, restore them and wire the autosave workflow. */
+export function createDraftEditor({
+  bindDraft,
+  _collectItems,
+  _loadDraft
+}) {
+  function _collectFormDraft(form) {
+    if (!form) return null;
+    const type = form.querySelector('.note-form-type-pill.active')?.dataset.type || form.dataset.noteType || 'note';
+    const d = {
+      _ts: Date.now(),
+      note_type: type,
+      color: form.dataset.noteColor || '',
+      title: form.querySelector('.note-form-title')?.value || '',
+      label: form.querySelector('.note-form-label')?.value || '',
+      due_date: form.querySelector('.note-form-due')?.value || null,
+      repeat: form.querySelector('.note-form-repeat')?.value || 'none',
+    };
+    if (type === 'note') d.content = form.querySelector('.note-form-content')?.value || '';
+    else if (type === 'goal') { d.content = form.querySelector('.note-form-goal-desc')?.value || ''; d.items = _collectItems(form); }
+    else d.items = _collectItems(form);
+    return d;
+  }
+
+  function _isDraftEmpty(d) {
+    if (!d) return true;
+    if ((d.title || '').trim()) return false;
+    if ((d.content || '').trim()) return false;
+    if (Array.isArray(d.items) && d.items.some(it => (it.text || '').trim())) return false;
+    return true;
+  }
+
+  function _wireDraftAutosave(form, id) {
+    const view = {
+      get failed() { return form._autosaveFailed; },
+      set failed(value) { form._autosaveFailed = value; },
+    };
+    const draft = bindDraft({ collect: () => _collectFormDraft(form), id, view });
+    form._flushDraft = draft.flush;
+    form._stopDraftAutosave = draft.stop;
+    form.addEventListener('input', draft.schedule);
+    form.addEventListener('change', draft.schedule);
+    form.addEventListener('click', event => {
+      if (event.target.closest('.note-cl-dot, .note-cl-rm')) draft.schedule();
+    });
+  }
+
+  function _commitOpenInPlaceEditor() {
+    const form = document.querySelector('#notes-pane .note-form');
+    if (!form) return;
+    const d = _collectFormDraft(form);
+    if (_isDraftEmpty(d)) { form.querySelector('.note-form-cancel')?.click(); return; }
+    form.querySelector('.note-form-save')?.click();
+  }
+
+  function _applyDraftToNote(note, id) {
+    const d = _loadDraft(id);
+    if (!d) return { note, restored: false };
+    const merged = { ...(note || {}) };
+    ['note_type', 'color', 'title', 'label', 'due_date', 'repeat', 'content', 'items'].forEach(k => {
+      if (d[k] !== undefined) merged[k] = d[k];
+    });
+    return { note: merged, restored: true };
+  }
+
+  return { _collectFormDraft, _isDraftEmpty, _wireDraftAutosave, _commitOpenInPlaceEditor, _applyDraftToNote };
+}
diff --git a/frontend/src/features/notes/ui/drawing.js b/frontend/src/features/notes/ui/drawing.js
new file mode 100644
index 000000000..da33c9236
--- /dev/null
+++ b/frontend/src/features/notes/ui/drawing.js
@@ -0,0 +1,442 @@
+/** Canvas drawing tools, local drawing undo and PNG uploads. */
+export function createDrawing({
+  lifecycle,
+  _safeImgSrc,
+  api,
+  attachColorPicker
+}) {
+  function _buildDrawHtml() {
+    return `
+    <div class="note-form-draw-wrap">
+      <canvas class="note-form-canvas" width="600" height="320"></canvas>
+      <div class="note-form-draw-toolbar">
+        <input type="color" class="note-form-draw-color" title="Stroke color" value="#222222" />
+        <label class="note-form-draw-tool note-form-draw-size-wrap" title="Stroke size">
+          <input type="range" class="note-form-draw-size" min="1" max="24" value="3" />
+        </label>
+        <div class="note-form-draw-be" role="group">
+          <button type="button" class="note-form-draw-be-btn note-form-draw-brush active" data-mode="pen" title="Brush">
+            <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M9.06 11.9l8.07-8.06a2.85 2.85 0 1 1 4.03 4.03l-8.06 8.08"/><path d="M7.07 14.94c-1.66 0-3 1.35-3 3.02 0 1.33-2.5 1.52-2 2.02 1.08 1.1 2.49 2.02 4 2.02 2.2 0 4-1.8 4-4.04 0-1.67-1.34-3.02-3-3.02z"/></svg>
+          </button>
+          <button type="button" class="note-form-draw-be-btn note-form-draw-eraser" data-mode="eraser" title="Eraser">
+            <svg width="22" height="22" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="m7 21-4.3-4.3c-1-1-1-2.5 0-3.4l9.6-9.6c1-1 2.5-1 3.4 0l5.6 5.6c1 1 1 2.5 0 3.4L13 21"/><path d="M22 21H7"/><path d="m5 11 9 9"/></svg>
+          </button>
+        </div>
+        <button type="button" class="note-form-draw-undo" title="Undo" aria-label="Undo">
+          <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><polyline points="9 14 4 9 9 4"></polyline><path d="M4 9h11a5 5 0 0 1 5 5v0a5 5 0 0 1-5 5H9"></path></svg>
+        </button>
+        <button type="button" class="note-form-draw-text" title="Add text — click to cycle size" aria-label="Add text">T<span class="note-form-draw-text-badge"></span></button>
+        <button type="button" class="note-form-draw-line" title="Line — click to cycle size">
+          <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><line x1="4" y1="20" x2="20" y2="4"/></svg>
+          <span class="note-form-draw-shape-badge"></span>
+        </button>
+        <button type="button" class="note-form-draw-circle" title="Circle — click to cycle size">
+          <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="12" cy="12" r="9"/></svg>
+          <span class="note-form-draw-shape-badge"></span>
+        </button>
+      </div>
+    </div>
+  `;
+  }
+
+  function _wireCanvas(container, initialImageUrl) {
+    const canvas = container.querySelector('.note-form-canvas');
+    if (!canvas) return;
+    const resolveThemeColor = (expression, fallback) => {
+      const probe = document.createElement('span');
+      probe.style.color = expression;
+      probe.style.position = 'fixed';
+      probe.style.visibility = 'hidden';
+      document.body.appendChild(probe);
+      const resolved = getComputedStyle(probe).color || fallback;
+      probe.remove();
+      return resolved;
+    };
+    const colorToHex = (color, fallback) => {
+      try {
+        const probe = document.createElement('canvas');
+        probe.width = probe.height = 1;
+        const probeCtx = probe.getContext('2d');
+        probeCtx.fillStyle = color;
+        probeCtx.fillRect(0, 0, 1, 1);
+        const [r, g, b] = probeCtx.getImageData(0, 0, 1, 1).data;
+        return `#${[r, g, b].map(v => v.toString(16).padStart(2, '0')).join('')}`;
+      } catch { return fallback; }
+    };
+    const surfaceColor = resolveThemeColor('var(--panel, var(--bg))', '#282c34');
+    const surfaceColorHex = colorToHex(surfaceColor, '#282c34');
+    const highlightColor = colorToHex(
+      resolveThemeColor('var(--accent, var(--red))', '#e06c75'),
+      '#e06c75',
+    );
+    const colorInput = container.querySelector('.note-form-draw-color');
+    if (colorInput) colorInput.value = highlightColor;
+    // Bump the backing-store resolution for retina displays so strokes stay
+    // crisp. Set only style.width : leaving style.height to auto so the canvas
+    // scales uniformly via its intrinsic aspect ratio. If both CSS dimensions
+    // are pinned, max-width:100% shrinks the width only, leaving rasterized
+    // glyphs visibly stretched relative to their on-screen input.
+    const dpr = Math.min(window.devicePixelRatio || 1, 2);
+    const cssW = canvas.width;
+    const cssH = canvas.height;
+    // Fill the container up to the logical width (don't pin a hard 600px,
+    // which on a narrow phone forces the card wider than the viewport and
+    // pushes the drawing outside the note). _pos() scales pointer coords by
+    // the actual displayed width, so accuracy is preserved at any size.
+    canvas.style.width = '100%';
+    canvas.style.maxWidth = cssW + 'px';
+    canvas.style.height = 'auto';
+    canvas.style.aspectRatio = cssW + ' / ' + cssH;
+    canvas.width = cssW * dpr;
+    canvas.height = cssH * dpr;
+    const ctx = canvas.getContext('2d');
+    ctx.scale(dpr, dpr);
+    ctx.fillStyle = surfaceColor;
+    ctx.fillRect(0, 0, cssW, cssH);
+    ctx.lineCap = 'round';
+    ctx.lineJoin = 'round';
+
+    // Load prior drawing as starting point so consecutive edits compose.
+    const safeInitialImageUrl = _safeImgSrc(initialImageUrl);
+    if (safeInitialImageUrl) {
+      const img = new Image();
+      img.crossOrigin = 'anonymous';
+      img.onload = () => { try { ctx.drawImage(img, 0, 0, cssW, cssH); } catch {} };
+      img.src = safeInitialImageUrl;
+      // Float an X over the canvas so the user can blank it out and go back to
+      // a clean draw surface. Removes itself once clicked.
+      const wrap = container.querySelector('.note-form-draw-wrap');
+      if (wrap && !wrap.querySelector('.note-form-draw-bg-rm')) {
+        const rm = document.createElement('button');
+        rm.type = 'button';
+        rm.className = 'note-form-draw-bg-rm';
+        rm.title = 'Clear photo (regular draw)';
+        rm.innerHTML = '&times;';
+        rm.addEventListener('click', (e) => {
+          e.preventDefault();
+          e.stopPropagation();
+          ctx.fillStyle = surfaceColor;
+          ctx.fillRect(0, 0, cssW, cssH);
+          rm.remove();
+        });
+        wrap.appendChild(rm);
+      }
+    }
+
+    // Swap the native browser color dialog for the in-house HSV picker
+    // (same one used by Themes + the gallery editor). Existing `input` event
+    // listeners + .value reads keep working : see colorPicker.js.
+    if (colorInput) attachColorPicker(colorInput);
+    const sizeInput = container.querySelector('.note-form-draw-size');
+    const beSeg = container.querySelector('.note-form-draw-be');
+    const brushBtn = container.querySelector('.note-form-draw-brush');
+    const eraserBtn = container.querySelector('.note-form-draw-eraser');
+    const textBtn = container.querySelector('.note-form-draw-text');
+    const lineBtn = container.querySelector('.note-form-draw-line');
+    const circleBtn = container.querySelector('.note-form-draw-circle');
+    const undoBtn = container.querySelector('.note-form-draw-undo');
+    // Single source of truth for what clicks/drags do. Other booleans are
+    // derived from this so we never end up with conflicting "eraser AND text"
+    // states (the bug that made T appear broken after using the eraser).
+    // Modes: 'pen' | 'eraser' | 'text-s' | 'text-m' | 'text-l' | 'line' | 'circle'
+    let mode = 'pen';
+    let drawing = false;
+    let last = null;
+    // The text tool has three preset sizes (CSS px font-size).
+    const TEXT_SIZES = { 's': 16, 'm': 26, 'l': 40 };
+    // Line / circle stroke widths in logical pixels : three crisp options.
+    const SHAPE_WIDTHS = { 's': 2, 'm': 5, 'l': 10 };
+    // Snapshot taken at the start of a shape drag so the preview can repaint
+    // cleanly on each move without accumulating intermediate strokes.
+    let _shapeSnapshot = null;
+
+    // Per-canvas undo stack. We snapshot the bitmap (as ImageData) BEFORE each
+    // operation : stroke, text commit, or future operations : and pop+restore
+    // on Undo. Cap to 30 to keep memory bounded.
+    const _undoStack = [];
+    const UNDO_LIMIT = 30;
+    const _syncUndoButton = () => {
+      const available = _undoStack.length > 0;
+      undoBtn?.classList.toggle('has-undo', available);
+      undoBtn?.toggleAttribute('disabled', !available);
+      undoBtn?.setAttribute('aria-disabled', available ? 'false' : 'true');
+    };
+    const _markCanvasDirty = () => container.dispatchEvent(new Event('input', { bubbles: true }));
+    const _snapshot = () => {
+      try {
+        const w = canvas.width, h = canvas.height;
+        _undoStack.push(ctx.getImageData(0, 0, w, h));
+        if (_undoStack.length > UNDO_LIMIT) _undoStack.shift();
+        _syncUndoButton();
+      } catch {}
+    };
+    const _undo = () => {
+      const prev = _undoStack.pop();
+      if (!prev) { _syncUndoButton(); return; }
+      // Restore against the raw backing store: temporarily reset the active
+      // ctx scale, paint the snapshot 1:1, then reapply our standard transform.
+      ctx.save();
+      ctx.setTransform(1, 0, 0, 1, 0, 0);
+      ctx.putImageData(prev, 0, 0);
+      ctx.restore();
+      _markCanvasDirty();
+      _syncUndoButton();
+    };
+
+    const _pos = (e) => {
+      // CSS can shrink the canvas (max-width:100%) without changing its logical
+      // size, so compute the displayed-to-logical scale per axis. Pointer coords
+      // are in CSS pixels; the dpr-scaled ctx expects logical (cssW × cssH).
+      const r = canvas.getBoundingClientRect();
+      const sx = cssW / r.width;
+      const sy = cssH / r.height;
+      const t = e.touches ? e.touches[0] : e;
+      return { x: (t.clientX - r.left) * sx, y: (t.clientY - r.top) * sy };
+    };
+    const _begin = (e) => {
+      if (mode.startsWith('text-')) {
+        // Stop the event so the browser doesn't synthesize a follow-up click
+        // that would blur the input we're about to create.
+        e.preventDefault?.();
+        e.stopPropagation?.();
+        _openTextInput(e);
+        return;
+      }
+      _snapshot();
+      last = _pos(e);
+      drawing = true;
+      if (mode.startsWith('line-') || mode.startsWith('circle-')) {
+        // Capture the backing pixels so the preview can replay each move from
+        // the same starting state (otherwise live shapes accumulate).
+        try { _shapeSnapshot = ctx.getImageData(0, 0, canvas.width, canvas.height); } catch {}
+        return;
+      }
+      ctx.beginPath();
+      ctx.moveTo(last.x, last.y);
+    };
+
+    // Drop an HTML input at the click position so the user can type, then
+    // rasterize the text onto the canvas at blur/Enter. Mirrors how PDF form
+    // annotations work in our doc editor.
+    let _activeTextInput = null;
+    const _openTextInput = (e) => {
+      // Commit any prior pending input before starting a new one : otherwise
+      // the first click leaves an orphaned input the user thinks "didn't work".
+      if (_activeTextInput) { try { _activeTextInput.blur(); } catch {} }
+      const r = canvas.getBoundingClientRect();
+      const t = e.touches ? e.touches[0] : e;
+      // Position is anchored to the wrap, not the canvas; since the canvas is
+      // the first child of the wrap and the wrap has no padding, they share an
+      // origin, so we offset from the canvas rect directly.
+      const px = t.clientX - r.left;
+      const py = t.clientY - r.top;
+      const logical = _pos(e);
+      // Size is decided by which T variant is active (S/M/L), not the stroke
+      // slider : those are independent dials.
+      const sizeKey = mode.startsWith('text-') ? mode.slice(-1) : 'm';
+      const sizeCss = TEXT_SIZES[sizeKey] || TEXT_SIZES.m;
+      const wrap = container.querySelector('.note-form-draw-wrap');
+      if (!wrap) return;
+      if (getComputedStyle(wrap).position === 'static') wrap.style.position = 'relative';
+      const input = document.createElement('input');
+      input.type = 'text';
+      input.className = 'note-form-draw-textinput';
+      input.placeholder = 'type then Enter';
+      const color = colorInput?.value || '#222';
+      const maxW = Math.max(120, Math.floor(r.width - px - 4));
+      input.style.cssText = [
+        'position:absolute',
+        `left:${px}px`,
+        `top:${Math.max(0, py - sizeCss * 0.7)}px`,
+        `font:${sizeCss}px Arial, sans-serif`,
+        `color:${color}`,
+        'background:#ffffff',
+        'border:2px solid var(--accent)',
+        'border-radius:4px',
+        'outline:none',
+        'padding:2px 6px',
+        'min-width:120px',
+        `max-width:${maxW}px`,
+        'z-index:1000',
+        'box-shadow:0 2px 8px rgba(0,0,0,0.25)',
+        'pointer-events:auto',
+      ].join(';');
+      wrap.appendChild(input);
+      _activeTextInput = input;
+      // Focus synchronously so the call still counts as inside the user gesture
+      // on iOS / Android, then re-focus on the next frame in case a competing
+      // synthetic event (touch → click) moved focus away.
+      input.focus();
+      requestAnimationFrame(() => { if (document.activeElement !== input) input.focus(); });
+      let committed = false;
+      const commit = () => {
+        if (committed) return;
+        committed = true;
+        const text = input.value;
+        if (_activeTextInput === input) _activeTextInput = null;
+        input.remove();
+        if (!text) return;
+        // Snapshot BEFORE rasterizing so Undo removes the text in one step.
+        _snapshot();
+        ctx.save();
+        ctx.globalCompositeOperation = 'source-over';
+        ctx.fillStyle = color;
+        // Canvas now scales uniformly (style.height: auto), so a single ratio
+        // suffices for picking the logical font size that matches what the
+        // user just saw in the HTML input.
+        const sx = cssW / r.width;
+        const logicalSize = sizeCss * sx;
+        ctx.font = `${logicalSize}px sans-serif`;
+        ctx.textBaseline = 'top';
+        ctx.fillText(text, logical.x, logical.y - logicalSize * 0.7);
+        ctx.restore();
+        _markCanvasDirty();
+      };
+      input.addEventListener('blur', commit);
+      input.addEventListener('keydown', (ev) => {
+        if (ev.key === 'Enter') { ev.preventDefault(); input.blur(); }
+        else if (ev.key === 'Escape') { input.value = ''; input.blur(); }
+      });
+    };
+    const _move = (e) => {
+      if (!drawing) return;
+      e.preventDefault?.();
+      const p = _pos(e);
+      if (mode.startsWith('line-') || mode.startsWith('circle-')) {
+        // Restore the pre-shape bitmap, then redraw the preview shape from
+        // anchor → current pointer.
+        if (_shapeSnapshot) {
+          ctx.save();
+          ctx.setTransform(1, 0, 0, 1, 0, 0);
+          ctx.putImageData(_shapeSnapshot, 0, 0);
+          ctx.restore();
+        }
+        ctx.globalCompositeOperation = 'source-over';
+        ctx.strokeStyle = colorInput?.value || '#222';
+        const sizeKey = mode.slice(-1);
+        ctx.lineWidth = SHAPE_WIDTHS[sizeKey] || SHAPE_WIDTHS.m;
+        ctx.beginPath();
+        if (mode.startsWith('line-')) {
+          ctx.moveTo(last.x, last.y);
+          ctx.lineTo(p.x, p.y);
+        } else {
+          const dx = p.x - last.x;
+          const dy = p.y - last.y;
+          const radius = Math.hypot(dx, dy);
+          ctx.arc(last.x, last.y, radius, 0, Math.PI * 2);
+        }
+        ctx.stroke();
+        return;
+      }
+      const erasing = mode === 'eraser';
+      ctx.globalCompositeOperation = 'source-over';
+      ctx.strokeStyle = erasing ? surfaceColor : (colorInput?.value || highlightColor);
+      ctx.lineWidth = Number(sizeInput?.value || 3) * (erasing ? 2.5 : 1);
+      ctx.lineTo(p.x, p.y);
+      ctx.stroke();
+      last = p;
+    };
+    const _end = () => {
+      if (drawing) _markCanvasDirty();
+      drawing = false; last = null; _shapeSnapshot = null;
+    };
+
+    canvas.addEventListener('mousedown', _begin);
+    canvas.addEventListener('mousemove', _move);
+    lifecycle.listen(canvas, window, 'mouseup', _end);
+    // Non-passive so text mode can preventDefault : otherwise the synthetic
+    // mousedown/click that follows a touch can blur the freshly-created text
+    // input on iOS Safari, making T look like a no-op.
+    canvas.addEventListener('touchstart', (e) => { if (mode.startsWith('text-')) e.preventDefault(); _begin(e); }, { passive: false });
+    canvas.addEventListener('touchmove', _move, { passive: false });
+    canvas.addEventListener('touchend', _end);
+    canvas.addEventListener('touchcancel', _end);
+
+    // Single mode setter : keeps the toolbar, swatch, and cursor in sync, and
+    // makes sure exiting the eraser restores the user's chosen color whether
+    // they exit by clicking another tool or by toggling eraser off.
+    let _preEraseColor = null;
+    const _setMode = (next) => {
+      const wasEraser = mode === 'eraser';
+      mode = next;
+      const isEraser = next === 'eraser';
+      const isPen = next === 'pen';
+      const isText = next.startsWith('text-');
+      // Swatch: theme surface while erasing, restored when leaving that mode.
+      if (isEraser && !wasEraser && colorInput) {
+        _preEraseColor = colorInput.value;
+        colorInput.value = surfaceColorHex;
+      } else if (!isEraser && wasEraser && colorInput && _preEraseColor) {
+        colorInput.value = _preEraseColor;
+        _preEraseColor = null;
+      }
+      // Brush/Eraser segmented pill : slides to the active side. When a non-
+      // pen/eraser tool (T / line / circle) is active, neither half is
+      // highlighted, but the pill still indicates which side the user was on
+      // last so they can return with one click.
+      const isLine = next.startsWith('line-');
+      const isCircle = next.startsWith('circle-');
+      beSeg?.classList.toggle('is-eraser', isEraser);
+      brushBtn?.classList.toggle('active', isPen);
+      eraserBtn?.classList.toggle('active', isEraser);
+      textBtn?.classList.toggle('active', isText);
+      lineBtn?.classList.toggle('active', isLine);
+      circleBtn?.classList.toggle('active', isCircle);
+      // Per-button size badges (S/M/L), driven off the mode suffix.
+      const tBadge = textBtn?.querySelector('.note-form-draw-text-badge');
+      if (tBadge) tBadge.textContent = isText ? next.slice(-1).toUpperCase() : '';
+      const lBadge = lineBtn?.querySelector('.note-form-draw-shape-badge');
+      if (lBadge) lBadge.textContent = isLine ? next.slice(-1).toUpperCase() : '';
+      const cBadge = circleBtn?.querySelector('.note-form-draw-shape-badge');
+      if (cBadge) cBadge.textContent = isCircle ? next.slice(-1).toUpperCase() : '';
+      // Reflect the chosen size in the icon itself : thicker line/circle stroke
+      // for M+L, larger T glyph for M+L. CSS rules read `.size-s/.size-m/.size-l`.
+      const _sz = next.slice(-1);
+      [textBtn, lineBtn, circleBtn].forEach(b => b?.classList.remove('size-s', 'size-m', 'size-l'));
+      if (isText && /[sml]/.test(_sz)) textBtn?.classList.add('size-' + _sz);
+      if (isLine && /[sml]/.test(_sz)) lineBtn?.classList.add('size-' + _sz);
+      if (isCircle && /[sml]/.test(_sz)) circleBtn?.classList.add('size-' + _sz);
+      canvas.style.cursor = isText ? 'text' : 'crosshair';
+    };
+    brushBtn?.addEventListener('click', () => _setMode('pen'));
+    eraserBtn?.addEventListener('click', () => _setMode('eraser'));
+    // T / Line / Circle: each cycles its own three sizes, then back to pen.
+    const _cycle = (prefix) => {
+      const seq = ['s', 'm', 'l'];
+      if (!mode.startsWith(prefix)) return prefix + 's';
+      const cur = mode.slice(-1);
+      const next = seq[seq.indexOf(cur) + 1];
+      return next ? prefix + next : 'pen';
+    };
+    textBtn?.addEventListener('click', () => _setMode(_cycle('text-')));
+    lineBtn?.addEventListener('click', () => _setMode(_cycle('line-')));
+    circleBtn?.addEventListener('click', () => _setMode(_cycle('circle-')));
+    undoBtn?.addEventListener('click', () => _undo());
+    _syncUndoButton();
+
+    // Stash so the save handler can read it later without re-resolving DOM.
+    canvas._cssW = cssW;
+    canvas._cssH = cssH;
+    return canvas;
+  }
+
+  async function _uploadCanvasAsPng(canvas, galleryId = null) {
+    if (!canvas) return null;
+    const blob = await new Promise(r => canvas.toBlob(r, 'image/png'));
+    if (!blob) return null;
+    const fd = new FormData();
+    fd.append('files', blob, 'drawing.png');
+    if (galleryId) fd.append('gallery_id', galleryId);
+    try {
+      const res = await api.upload(fd);
+      const data = await res.json();
+      const id = data.files?.[0]?.id;
+      return id ? {
+        url: api.uploadUrl(id),
+        galleryId: data.files?.[0]?.gallery_id || null,
+      } : null;
+    } catch { return null; }
+  }
+
+  return { _buildDrawHtml, _wireCanvas, _uploadCanvasAsPng };
+}
diff --git a/frontend/src/features/notes/ui/editor.js b/frontend/src/features/notes/ui/editor.js
new file mode 100644
index 000000000..f5bdc7c9f
--- /dev/null
+++ b/frontend/src/features/notes/ui/editor.js
@@ -0,0 +1,518 @@
+/** Build and wire note, checklist, goal and drawing editor forms. */
+export function createEditor({
+  deleteFromEditor,
+  submitNote,
+  COLORS,
+  _applyMasonry,
+  _archiveNoteById,
+  _buildChecklistHtml,
+  _buildDrawHtml,
+  _buildGoalHtml,
+  _collectItems,
+  _customColorStyle,
+  _dotBg,
+  _dotIsActive,
+  _esc,
+  _isBgImage,
+  _renderNotes,
+  _safeImgSrc,
+  _uid,
+  _uploadCanvasAsPng,
+  _wireCanvas,
+  _wireChecklist,
+  _wireDraftAutosave,
+  _wireFormColors,
+  _wireGoalForm,
+  _wireReminderPicker,
+  api,
+  app,
+  state,
+  uiModule
+}) {
+  function _buildForm(note = null) {
+    const isEdit = note && note.id;
+    const type = note?.note_type === 'checklist' ? 'todo' : (note?.note_type || 'note');
+    const color = note?.color || '';
+    const items = note?.items || [{ id: _uid(), text: '', done: false }];
+
+    const form = document.createElement('div');
+    form.className = 'note-form';
+    form.dataset.noteType = type;
+    form.dataset.noteColor = color || '';
+    if (color && !_isBgImage(color)) form.classList.add('note-color-' + color);
+    if (_isBgImage(color)) form.setAttribute('style', _customColorStyle(color));
+    let currentImageUrl = _safeImgSrc(note?.image_url || '');
+    form.innerHTML = `
+    <div class="note-form-header">
+      <input type="text" class="note-form-title" placeholder="Title" value="${_esc(note?.title || '')}" />
+      <button type="button" class="note-form-icon-btn note-form-remind-btn${note?.due_date ? ' has-date' : ''}" title="Remind me">
+        <svg width="31" height="31" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M18 8A6 6 0 0 0 6 8c0 7-3 9-3 9h18s-3-2-3-9"/><path d="M13.73 21a2 2 0 0 1-3.46 0"/></svg>
+      </button>
+      <input type="hidden" class="note-form-due" value="${note?.due_date || ''}" />
+      <input type="hidden" class="note-form-repeat" value="${note?.repeat || 'none'}" />
+    </div>
+    ${currentImageUrl && type !== 'draw' ? `<div class="note-form-image-wrap"><img class="note-form-image" src="${_esc(currentImageUrl)}" draggable="false" /><button class="note-form-image-rm" title="Remove">&times;</button></div>` : ''}
+    <div class="note-form-body">
+      ${type === 'note'
+          ? `<textarea class="note-form-content" placeholder="Take a note..." rows="4">${_esc(note?.content || '')}</textarea>`
+          : type === 'draw'
+          ? _buildDrawHtml()
+          : type === 'goal'
+          ? _buildGoalHtml(note, items)
+          : _buildChecklistHtml(items)}
+    </div>
+    <div class="note-form-reminder-tags"></div>
+    <div class="note-form-meta">
+      <div class="note-form-type-seg${type === 'todo' ? ' is-todo' : type === 'draw' ? ' is-draw' : ''}" role="group">
+        <button type="button" class="note-form-type-pill${type === 'note' ? ' active' : ''}" data-type="note">
+          <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><line x1="4" y1="6" x2="20" y2="6"/><line x1="4" y1="12" x2="20" y2="12"/><line x1="4" y1="18" x2="14" y2="18"/></svg>
+          <span>Note</span>
+        </button>
+        <button type="button" class="note-form-type-pill${type === 'todo' ? ' active' : ''}" data-type="todo">
+          <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><polyline points="9 11 12 14 22 4"/><path d="M21 12v7a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2h11"/></svg>
+          <span>Todo</span>
+        </button>
+        <button type="button" class="note-form-type-pill${type === 'draw' ? ' active' : ''}" data-type="draw">
+          <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M12 19l7-7 3 3-7 7-3-3z"/><path d="M18 13l-1.5-7.5L2 2l3.5 14.5L13 18l5-5z"/><path d="M2 2l7.586 7.586"/><circle cx="11" cy="11" r="2"/></svg>
+          <span>Draw</span>
+        </button>
+      </div>
+      <button class="note-form-photo-btn" title="Attach photo">
+        <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="3" y="3" width="18" height="18" rx="2"/><circle cx="8.5" cy="8.5" r="1.5"/><polyline points="21 15 16 10 5 21"/></svg>
+      </button>
+      <input type="file" class="note-form-photo-input" accept="image/*" capture="environment" style="display:none" />
+      <div class="note-color-picker">
+        ${COLORS.map(c => `<span class="note-color-dot${_dotIsActive(c.value, color) ? ' active' : ''}" data-color="${c.value}" style="background:${_dotBg(c.value, color)}" title="${c.name || 'default'}"></span>`).join('')}
+      </div>
+      <input type="text" class="note-form-label" value="${_esc(note?.label || '')}" placeholder="#tag1 #tag2" title="Tag(s) — space-separated" />
+      <div class="note-form-actions-group">
+        ${isEdit ? `
+        <button type="button" class="note-form-text-btn note-form-archive-btn note-form-collapsible" title="Archive">
+          <svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="2" y="3" width="20" height="5" rx="1"/><path d="M4 8v11a2 2 0 002 2h12a2 2 0 002-2V8"/><path d="M10 12h4"/></svg><span class="nft-label">Archive</span>
+        </button>
+        <button type="button" class="note-form-text-btn note-form-delete-btn note-form-collapsible danger" title="Delete">
+          <svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><polyline points="3 6 5 6 21 6"/><path d="M19 6l-1 14a2 2 0 0 1-2 2H8a2 2 0 0 1-2-2L5 6"/><path d="M8 6V4a2 2 0 0 1 2-2h4a2 2 0 0 1 2 2v2"/><line x1="10" y1="11" x2="10" y2="17"/><line x1="14" y1="11" x2="14" y2="17"/></svg><span class="nft-label">Delete</span>
+        </button>
+        ` : ''}
+        <span class="note-form-actions-spacer"></span>
+        <button class="note-form-cancel note-form-text-btn note-form-collapsible" title="Close (keep changes)">
+          <svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.2" stroke-linecap="round"><line x1="6" y1="6" x2="18" y2="18"/><line x1="18" y1="6" x2="6" y2="18"/></svg><span class="nft-label">Close</span>
+        </button>
+        <button class="note-form-save note-form-text-btn" title="${isEdit ? 'Update' : 'Save'}">
+          <svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.4" stroke-linecap="round" stroke-linejoin="round"><polyline points="20 6 9 17 4 12"/></svg><span class="nft-label">${isEdit ? 'Update' : 'Save'}</span>
+        </button>
+      </div>
+    </div>
+  `;
+
+    let currentType = type;
+    let currentColor = color;
+    // Stash original-form values so round-trips (Note→Todo→Note) restore the
+    // user's hand-formatted text instead of a join of generated items. Same the
+    // other way: if you started in todo, switch to note, switch back, items
+    // come back unchanged.
+    let _stashedNoteText = (type === 'note') ? (note?.content || '') : null;
+    let _stashedTodoItems = (type === 'todo' && Array.isArray(note?.items)) ? note.items.slice() : null;
+    // Goal mode kept its own pair of stashes (description + steps) so a
+    // Todo→Goal→Todo round-trip wouldn't lose either side. The Goal pill in
+    // the type picker was later removed, so the only entry point now is
+    // *editing* an existing goal-typed note : but the switch handler still
+    // accepts Goal→Todo/Note transitions (downgrading legacy goals), so
+    // these stashes still earn their keep.
+    let _stashedGoalDesc = (type === 'goal') ? (note?.content || '') : null;
+    let _stashedGoalItems = (type === 'goal' && Array.isArray(note?.items)) ? note.items.slice() : null;
+
+    // Drawing also stashes the saved image URL so it survives Note↔Draw flips.
+    let _stashedDrawUrl = (type === 'draw') ? (_safeImgSrc(note?.image_url) || null) : null;
+    const _refreshFormLayout = () => {
+      const body = form.closest('.notes-pane-body');
+      if (!body) return;
+      _applyMasonry(body);
+      requestAnimationFrame(() => {
+        _applyMasonry(body);
+        requestAnimationFrame(() => _applyMasonry(body));
+      });
+    };
+
+    // Type segmented control : Note | Todo | Draw
+    form.querySelectorAll('.note-form-type-pill').forEach(pill => {
+      pill.addEventListener('click', () => {
+        const newType = pill.dataset.type;
+        if (newType === currentType) return;
+        const bodyEl = form.querySelector('.note-form-body');
+        // Stash whatever the user has in the current mode before swapping it
+        // out, so a subsequent flip back restores their work.
+        if (currentType === 'note') {
+          _stashedNoteText = form.querySelector('.note-form-content')?.value || '';
+        } else if (currentType === 'todo') {
+          _stashedTodoItems = _collectItems(form);
+        } else if (currentType === 'goal') {
+          _stashedGoalDesc = form.querySelector('.note-form-goal-desc')?.value || '';
+          _stashedGoalItems = _collectItems(form);
+        } else if (currentType === 'draw') {
+          const c = form.querySelector('.note-form-canvas');
+          if (c) { try { _stashedDrawUrl = c.toDataURL('image/png'); } catch {} }
+        }
+        // Render the new mode's body and re-wire its inputs.
+        if (newType === 'todo') {
+          let nextItems;
+          if (_stashedTodoItems && _stashedTodoItems.length) {
+            nextItems = _stashedTodoItems;
+          } else if (_stashedGoalItems && _stashedGoalItems.length) {
+            // Going Goal→Todo keeps the AI-generated steps as a plain checklist.
+            nextItems = _stashedGoalItems;
+          } else if (_stashedNoteText) {
+            const lines = _stashedNoteText.split('\n').map(s => s.trim()).filter(Boolean);
+            nextItems = lines.length ? lines.map(t => ({ id: _uid(), text: t, done: false })) : [{ id: _uid(), text: '', done: false }];
+          } else {
+            nextItems = [{ id: _uid(), text: '', done: false }];
+          }
+          bodyEl.innerHTML = _buildChecklistHtml(nextItems);
+          _wireChecklist(bodyEl);
+        } else if (newType === 'draw') {
+          bodyEl.innerHTML = _buildDrawHtml();
+          // If the user just attached a photo (via the photo button) and then
+          // toggled to Draw, paint that photo onto the canvas so they can draw
+          // on top of it. _stashedDrawUrl wins if they were drawing earlier in
+          // the same edit session.
+          _wireCanvas(bodyEl, _stashedDrawUrl || currentImageUrl || _safeImgSrc(note?.image_url) || null);
+        } else {
+          const text = (_stashedNoteText !== null && _stashedNoteText !== undefined && _stashedNoteText !== '')
+            ? _stashedNoteText
+            : (_stashedGoalDesc && _stashedGoalDesc)
+            || (_stashedTodoItems || _stashedGoalItems || []).map(i => i.text).join('\n');
+          bodyEl.innerHTML = `<textarea class="note-form-content" placeholder="Take a note..." rows="4">${_esc(text)}</textarea>`;
+          _wireHashtag(bodyEl.querySelector('.note-form-content'));
+        }
+        const focusEl = newType === 'note'
+          ? bodyEl.querySelector('.note-form-content')
+          : newType === 'todo'
+            ? bodyEl.querySelector('.note-cl-text')
+            : null;
+        if (focusEl) {
+          requestAnimationFrame(() => {
+            focusEl.focus({ preventScroll: true });
+            try {
+              const end = focusEl.value.length;
+              focusEl.setSelectionRange(end, end);
+            } catch {}
+          });
+        }
+        currentType = newType;
+        const seg = form.querySelector('.note-form-type-seg');
+        seg?.classList.toggle('is-todo', newType === 'todo');
+        seg?.classList.toggle('is-draw', newType === 'draw');
+        form.querySelectorAll('.note-form-type-pill').forEach(p => p.classList.toggle('active', p.dataset.type === newType));
+        // The standalone image preview (form-image-wrap) and the canvas would
+        // otherwise both show the same image_url when editing a drawn note.
+        // Hide it in draw mode, restore it when leaving draw mode.
+        const imgWrap = form.querySelector('.note-form-image-wrap');
+        if (imgWrap) imgWrap.style.display = (newType === 'draw') ? 'none' : '';
+        // The background-color dots set the note card's bg : they make no sense
+        // for a drawn note (the canvas image IS the card content), so hide them.
+        const bgPicker = form.querySelector('.note-color-picker');
+        if (bgPicker) bgPicker.style.display = (newType === 'draw') ? 'none' : '';
+        if (form.closest('.notes-pane.notes-view-grid') && window.matchMedia('(max-width: 768px)').matches) {
+          form.style.gridColumn = '1 / -1';
+          form.style.gridRowEnd = newType === 'draw' ? 'span 152' : 'span 64';
+        }
+        _refreshFormLayout();
+      });
+    });
+
+    // Slide a finger across the Note/Todo/Draw control to switch modes (mobile).
+    // On touchmove we find the pill under the finger and click it : reusing the
+    // pill click handler above, so the body re-renders + content stashing all
+    // work. Only fires when crossing into a *different* pill.
+    const _typeSeg = form.querySelector('.note-form-type-seg');
+    if (_typeSeg) {
+      let _sliding = false;
+      const _activateAt = (x, y) => {
+        const pill = document.elementFromPoint(x, y)?.closest?.('.note-form-type-pill');
+        if (pill && !pill.classList.contains('active')) pill.click();
+      };
+      _typeSeg.addEventListener('touchstart', () => { _sliding = true; }, { passive: true });
+      _typeSeg.addEventListener('touchmove', (e) => {
+        if (_sliding && e.touches[0]) _activateAt(e.touches[0].clientX, e.touches[0].clientY);
+      }, { passive: true });
+      _typeSeg.addEventListener('touchend', () => { _sliding = false; });
+      _typeSeg.addEventListener('touchcancel', () => { _sliding = false; });
+    }
+
+    _wireFormColors(form, value => { currentColor = value; });
+
+    if (currentType === 'todo') _wireChecklist(form.querySelector('.note-form-body'));
+    if (currentType === 'goal') _wireGoalForm(form, form.querySelector('.note-form-body'));
+    if (currentType === 'draw') {
+      _wireCanvas(form.querySelector('.note-form-body'), _safeImgSrc(note?.image_url) || null);
+      // Same hides we apply on type-switch : keep them consistent on initial open.
+      const _ip = form.querySelector('.note-form-image-wrap'); if (_ip) _ip.style.display = 'none';
+      const _cp = form.querySelector('.note-color-picker'); if (_cp) _cp.style.display = 'none';
+    }
+
+    // Auto-grow the plain-note textarea so editing longer notes is
+    // comfortable : it expands with the content (up to a cap) instead of
+    // staying a cramped 4-row box. The user can still drag-resize too.
+    const _contentTa = form.querySelector('.note-form-content');
+    if (_contentTa) {
+      const _grow = () => {
+        _contentTa.style.height = 'auto';
+        // Inline form: cap at ~50vh so a huge note doesn't push the action
+        // buttons off-screen. Fullscreen mobile overlay: the body scrolls and
+        // there are no inline buttons crowding, so allow nearly the full height
+        // : capping at 50vh there clipped longer notes ("part disappears").
+        const inFullscreen = !!_contentTa.closest('.note-fullscreen-overlay');
+        const max = Math.round(window.innerHeight * (inFullscreen ? 0.9 : 0.5));
+        _contentTa.style.height = Math.min(_contentTa.scrollHeight, max) + 'px';
+      };
+      _contentTa.addEventListener('input', _grow);
+      // Grow on open so existing content is fully visible. Run again after the
+      // fullscreen overlay's open animation settles : measuring mid-animation
+      // (the overlay starts scaled/transitioning) can under-size the box.
+      setTimeout(_grow, 0);
+      setTimeout(_grow, 360);
+    }
+
+    _wireReminderPicker(form);
+
+    // Photo upload
+    const photoBtn = form.querySelector('.note-form-photo-btn');
+    const photoInput = form.querySelector('.note-form-photo-input');
+    if (photoBtn && photoInput) {
+      photoBtn.addEventListener('click', () => photoInput.click());
+      photoInput.addEventListener('change', async () => {
+        const file = photoInput.files?.[0];
+        if (!file) return;
+        const fd = new FormData();
+        fd.append('files', file);
+        try {
+          const res = await api.upload(fd);
+          const data = await res.json();
+          const fileId = data.files?.[0]?.id;
+          if (!fileId) throw new Error('Upload failed');
+          currentImageUrl = api.uploadUrl(fileId);
+          // Only ever keep the latest attached photo : drop any existing wrap
+          // before inserting a fresh one. Picking a second photo replaces the
+          // first instead of stacking.
+          form.querySelector('.note-form-image-wrap')?.remove();
+          const wrap = document.createElement('div');
+          wrap.className = 'note-form-image-wrap';
+          wrap.innerHTML = `<img class="note-form-image" draggable="false" /><button class="note-form-image-rm" title="Remove">&times;</button>`;
+          // Insert AFTER the whole header (a flex-row), not after the
+          // title input itself : otherwise the image lands as a sibling
+          // of the title inside the header and flex puts them side-by-side.
+          form.querySelector('.note-form-header').after(wrap);
+          wrap.querySelector('.note-form-image-rm').addEventListener('click', () => { wrap.remove(); currentImageUrl = ''; });
+          wrap.querySelector('img').src = currentImageUrl;
+        } catch (err) { uiModule.showError('Image upload failed'); }
+        photoInput.value = '';
+      });
+    }
+    // Existing image remove
+    form.querySelector('.note-form-image-rm')?.addEventListener('click', () => {
+      form.querySelector('.note-form-image-wrap')?.remove();
+      currentImageUrl = '';
+    });
+
+    // Title Enter -> focus body (textarea or first checklist item)
+    form.querySelector('.note-form-title').addEventListener('keydown', (e) => {
+      if (e.key === 'Enter' && !e.shiftKey && !e.ctrlKey && !e.metaKey) {
+        e.preventDefault();
+        const ta = form.querySelector('.note-form-content');
+        if (ta) { ta.focus(); return; }
+        const firstItem = form.querySelector('.note-cl-text');
+        if (firstItem) firstItem.focus();
+      }
+    });
+
+    // Hashtag → label: typing "#foo " in title/content appends "foo" to the
+    // space-separated tag list. Repeats are deduplicated, so #foo #foo only
+    // keeps one. Tags already present in the label field are left alone.
+    const labelInput = form.querySelector('.note-form-label');
+    const _hashtagRe = /(^|\s)#([A-Za-z0-9][\w-]*)\s$/;
+    function _wireHashtag(el) {
+      if (!el || !labelInput) return;
+      el.addEventListener('input', () => {
+        const m = _hashtagRe.exec(el.value);
+        if (!m) return;
+        const tag = m[2];
+        // Dedup against the stripped form : labelInput may already hold `#tag`
+        // (after Enter normalised), so includes(tag) on the raw split would
+        // miss the duplicate and append a bare `tag` next to `#tag`.
+        const existing = labelInput.value.trim().split(/\s+/).filter(Boolean);
+        const stripped = existing.map(t => t.replace(/^#+/, ''));
+        if (!stripped.includes(tag)) {
+          existing.push('#' + tag);
+          labelInput.value = existing.join(' ');
+          labelInput.classList.add('flash-once');
+          setTimeout(() => labelInput.classList.remove('flash-once'), 600);
+        }
+        const cut = el.value.length - m[0].length + m[1].length;
+        el.value = el.value.slice(0, cut);
+      });
+    }
+    _wireHashtag(form.querySelector('.note-form-title'));
+    _wireHashtag(form.querySelector('.note-form-content'));
+    // Pressing Enter in the tag field commits the current word as its own tag
+    // and parks the cursor after a trailing space, so the next word becomes a
+    // separate tag rather than overwriting the previous one.
+    labelInput?.addEventListener('keydown', (e) => {
+      if (e.key !== 'Enter' || e.shiftKey || e.ctrlKey || e.metaKey) return;
+      e.preventDefault();
+      e.stopPropagation();
+      // Strip any leading #s the user typed, dedupe, then re-prepend exactly
+      // one #. So typing "foo" or "#foo" both end up as "#foo " in the input;
+      // the save handler keeps stripping #s before storing so DB stays clean.
+      const tags = [...new Set(labelInput.value.split(/\s+/).map(t => t.replace(/^#+/, '').trim()).filter(Boolean))];
+      if (!tags.length) return;
+      labelInput.value = tags.map(t => '#' + t).join(' ') + ' ';
+      labelInput.setSelectionRange(labelInput.value.length, labelInput.value.length);
+      labelInput.classList.add('flash-once');
+      setTimeout(() => labelInput.classList.remove('flash-once'), 600);
+    });
+
+    // Shift+Enter (or Cmd/Ctrl+Enter) anywhere in the form -> save
+    // Escape -> cancel edit
+    form.addEventListener('keydown', (e) => {
+      if (e.key === 'Enter' && (e.shiftKey || e.ctrlKey || e.metaKey)) {
+        e.preventDefault();
+        form.querySelector('.note-form-save')?.click();
+      } else if (e.key === 'Escape') {
+        e.preventDefault();
+        e.stopPropagation();
+        form.querySelector('.note-form-cancel')?.click();
+      }
+    });
+
+    // Save. Prevent the button from stealing focus on press: on mobile, the
+    // first tap would otherwise just blur the focused textarea/input (closing
+    // the keyboard and shifting layout), so the tap never reached the button and
+    // you had to tap "Done" twice. mousedown preventDefault keeps focus put while
+    // still letting the click fire.
+    const _saveBtnEl0 = form.querySelector('.note-form-save');
+    _saveBtnEl0.addEventListener('mousedown', (e) => e.preventDefault());
+    _saveBtnEl0.addEventListener('click', async () => {
+      // Guard against spam-clicks: the drawing save AWAITS a canvas upload before
+      // the optimistic re-render removes the form, so without this a slow upload
+      // let repeated clicks create duplicate notes.
+      const _saveBtn = form.querySelector('.note-form-save');
+      if (_saveBtn._saving) return;
+      // Mobile: when an existing note is opened and closed without edits, the
+      // Update (✓) button morphs into Archive (set up below). Route the click
+      // directly through the archive flow. Using a DOM .click() proxy here was
+      // fragile on mobile because the real archive button can move from the
+      // footer to the fullscreen header.
+      if (_saveBtn.classList.contains('archive-mode')) {
+        _archiveNoteById(note?.id);
+        return;
+      }
+      _saveBtn._saving = true; _saveBtn.disabled = true; _saveBtn.style.opacity = '0.5';
+      try {
+      form._flushDraft?.();
+      await form._stopDraftAutosave?.();
+      form._flushDraft?.();
+      const title = form.querySelector('.note-form-title').value.trim();
+      // Normalize tag input: split on whitespace, strip leading #s, dedupe,
+      // re-join with single spaces. Empty → null.
+      const _rawLabel = form.querySelector('.note-form-label')?.value || '';
+      const _tags = [...new Set(_rawLabel.split(/\s+/).map(t => t.replace(/^#+/, '').trim()).filter(Boolean))];
+      if (form.querySelector('.note-form-due').value && !_tags.includes('reminder')) _tags.push('reminder');
+      const labelVal = _tags.length ? _tags.join(' ') : null;
+      const payload = {
+        title,
+        note_type: currentType,
+        color: currentColor,
+        label: labelVal,
+        due_date: form.querySelector('.note-form-due').value || null,
+        repeat: form.querySelector('.note-form-repeat')?.value || 'none',
+        image_url: currentImageUrl || null,
+      };
+      if (currentType === 'note') {
+        payload.content = form.querySelector('.note-form-content')?.value || '';
+      } else if (currentType === 'draw') {
+        // Upload the canvas PNG before saving so image_url points to a
+        // persistent file. We block the save until upload completes : drawings
+        // can't be re-rendered later without the URL.
+        const canvas = form.querySelector('.note-form-canvas');
+        const upload = await _uploadCanvasAsPng(canvas, note?.gallery_id || null);
+        if (!upload?.url) { uiModule.showError('Failed to save drawing'); return; }
+        payload.image_url = upload.url;
+        if (upload.galleryId) payload.gallery_id = upload.galleryId;
+      } else if (currentType === 'goal') {
+        // Legacy: existing goal-type notes still edit through this branch.
+        // No AI involvement : save as a normal note with description + items.
+        payload.content = form.querySelector('.note-form-goal-desc')?.value || '';
+        payload.items = _collectItems(form);
+      } else {
+        payload.items = _collectItems(form);
+      }
+      if (isEdit) payload.id = note.id;
+      submitNote(payload, note, isEdit);
+      } finally {
+        // Re-enable on early returns / errors. On success the form is removed by
+        // the optimistic re-render, so re-enabling the detached button is a no-op.
+        _saveBtn._saving = false; _saveBtn.disabled = false; _saveBtn.style.opacity = '';
+      }
+    });
+
+    // Mobile-only: when editing an existing note, the Update (✓) button starts in
+    // archive-mode (visually + behaviorally) and flips to Update on the first
+    // edit. Lets the user tap a note to skim, then tap ✓ to archive without ever
+    // touching a separate Archive button.
+    if (isEdit && window.innerWidth <= 768) {
+      const _saveLabelEl = _saveBtnEl0.querySelector('.nft-label');
+      const _isFinishedTodo = () => {
+        if (currentType !== 'todo') return false;
+        const rows = [...form.querySelectorAll('.note-cl-row')];
+        const withText = rows.filter(row => (row.querySelector('.note-cl-text')?.value || '').trim());
+        return withText.length > 0 && withText.every(row => row.classList.contains('done'));
+      };
+      const _enterArchive = () => {
+        _saveBtnEl0.classList.add('archive-mode');
+        const label = _isFinishedTodo() ? 'Finish' : 'Archive';
+        if (_saveLabelEl) _saveLabelEl.textContent = label;
+        _saveBtnEl0.title = label;
+      };
+      const _enterUpdate = () => {
+        if (!_saveBtnEl0.classList.contains('archive-mode')) return;
+        _saveBtnEl0.classList.remove('archive-mode');
+        if (_saveLabelEl) _saveLabelEl.textContent = 'Update';
+        _saveBtnEl0.title = 'Update';
+      };
+      _enterArchive();
+      form.addEventListener('input', _enterUpdate, true);
+      form.addEventListener('change', _enterUpdate, true);
+      // Checklist dots use a custom control and dispatch their update before
+      // this click bubbles. Re-evaluate afterward so a fully completed todo
+      // offers Finish (which archives/removes it from the active list).
+      form.addEventListener('click', (event) => {
+        if (!event.target.closest('.note-cl-dot')) return;
+        setTimeout(() => {
+          if (_isFinishedTodo()) _enterArchive();
+          else _enterUpdate();
+        }, 0);
+      }, true);
+    }
+
+    // Cancel
+    form.querySelector('.note-form-cancel').addEventListener('click', () => { form._flushDraft?.(); app.setEditingId(null); _renderNotes(); });
+
+    // Archive / Delete : edit-mode-only buttons, mirror the (now-hidden) card actions.
+    form.querySelector('.note-form-archive-btn')?.addEventListener('click', () => {
+      if (!isEdit) return;
+      _archiveNoteById(note.id);
+    });
+    form.querySelector('.note-form-delete-btn')?.addEventListener('click', () => {
+      if (!isEdit) return;
+      return deleteFromEditor(note.id);
+    });
+
+    // Autosave a draft to persistence on every change so unsaved edits
+    // survive connection loss / reload / accidental close.
+    _wireDraftAutosave(form, isEdit ? note.id : '__new__');
+
+    return form;
+  }
+
+  return { _buildForm };
+}
diff --git a/frontend/src/features/notes/ui/filters.js b/frontend/src/features/notes/ui/filters.js
new file mode 100644
index 000000000..49142a260
--- /dev/null
+++ b/frontend/src/features/notes/ui/filters.js
@@ -0,0 +1,139 @@
+/** Label chips, reminder/goal filters and collapsed tag-strip rendering. */
+import { _visibleNoteTags, _nextGoalStep } from '../domain/noteRules.js';
+import { _hasTimeComponent } from '../domain/recurrence.js';
+export function createFilters({
+  NOTES_LABELS_COLLAPSED_KEY,
+  _clearPastReminders,
+  _esc,
+  _isPastReminder,
+  _renderNotes,
+  _userVisibleNotes,
+  app,
+  persistence,
+  state
+}) {
+  function _renderLabels(root = document) {
+    const bar = root.querySelector?.('.notes-labels-bar') || document.querySelector('.notes-labels-bar');
+    if (!bar) return;
+    if (state.labelsCollapsed) {
+      bar.innerHTML = '';
+      bar.style.display = 'none';
+      return;
+    }
+    const visibleNotes = _userVisibleNotes();
+    const labels = new Set();
+    for (const n of visibleNotes) for (const t of _visibleNoteTags(n)) labels.add(t);
+    const sortedLabels = [...labels].sort();
+    // Count active reminders (not archived, has datetime due_date)
+    const reminderCount = visibleNotes.filter(n => !n.archived && n.due_date && _hasTimeComponent(n.due_date)).length;
+    const pastReminderCount = visibleNotes.filter(n => !n.archived && _isPastReminder(n)).length;
+    const defaultCount = visibleNotes.filter(n => !n.archived && _visibleNoteTags(n).length === 0).length;
+    // Active goals = non-archived goal notes. Today view lists pending steps
+    // from each, so we surface the count next to the chip.
+    const goalCount = visibleNotes.filter(n => n.note_type === 'goal' && !n.archived).length;
+    const todayCount = visibleNotes.filter(n => n.note_type === 'goal' && !n.archived && _nextGoalStep(n)).length;
+    const hasUsefulFilters = sortedLabels.length > 0 || reminderCount > 0 || goalCount > 0;
+    const hasActiveFilter = state.activeLabel !== null || state.activeFilter !== null;
+    if (!hasUsefulFilters && !hasActiveFilter) {
+      bar.innerHTML = '';
+      bar.style.display = 'none';
+      return;
+    }
+    bar.style.display = '';
+    const allActive = state.activeLabel === null && state.activeFilter === null;
+    let html = `<button class="notes-label-chip${allActive ? ' active' : ''}" data-action="all">All</button>`;
+    html += `<button class="notes-label-chip${state.activeFilter === 'default' ? ' active' : ''}" data-action="default" title="Show notes without tags">Default <span class="notes-label-chip-count">${defaultCount}</span></button>`;
+    if (todayCount > 0) {
+      const isOn = state.activeFilter === 'today';
+      const icon = '<svg width="10" height="10" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round" style="vertical-align:-1px;margin-right:2px"><rect x="3" y="4" width="18" height="18" rx="2"/><line x1="16" y1="2" x2="16" y2="6"/><line x1="8" y1="2" x2="8" y2="6"/><line x1="3" y1="10" x2="21" y2="10"/></svg>';
+      html += `<button class="notes-label-chip notes-label-chip-today${isOn ? ' active' : ''}" data-action="today" title="Next step from every goal">${icon}Today <span class="notes-label-chip-count">${todayCount}</span></button>`;
+    }
+    if (goalCount > 0) {
+      const isOn = state.activeFilter === 'goals';
+      const icon = '<svg width="10" height="10" viewBox="0 0 24 24" fill="currentColor" style="vertical-align:-1px;margin-right:2px"><path d="M12 0L14.59 8.41L23 12L14.59 15.59L12 24L9.41 15.59L1 12L9.41 8.41Z"/></svg>';
+      html += `<button class="notes-label-chip notes-label-chip-goals${isOn ? ' active' : ''}" data-action="goals" title="Show only goals">${icon}Goals <span class="notes-label-chip-count">${goalCount}</span></button>`;
+    }
+    const isReminderOn = state.activeFilter === 'reminders';
+    const isReminderOff = state.activeFilter === 'no-reminders';
+    const reminderCls = `notes-label-chip notes-label-chip-reminders${isReminderOn ? ' active' : ''}${isReminderOff ? ' active negated' : ''}`;
+    const reminderIcon = isReminderOff
+      // bell-off icon
+      ? '<svg width="10" height="10" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round" style="vertical-align:-1px;margin-right:2px"><path d="M13.73 21a2 2 0 0 1-3.46 0"/><path d="M18.63 13A17.89 17.89 0 0 1 18 8"/><path d="M6.26 6.26A5.86 5.86 0 0 0 6 8c0 7-3 9-3 9h14"/><path d="M18 8a6 6 0 0 0-9.33-5"/><line x1="1" y1="1" x2="23" y2="23"/></svg>'
+      : '<svg width="10" height="10" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round" style="vertical-align:-1px;margin-right:2px"><path d="M18 8A6 6 0 0 0 6 8c0 7-3 9-3 9h18s-3-2-3-9"/><path d="M13.73 21a2 2 0 0 1-3.46 0"/></svg>';
+    html += `<button class="${reminderCls}" data-action="reminders" title="${isReminderOn ? 'Showing only reminders — click to show all' : isReminderOff ? 'Hiding reminders — click to show only reminders' : 'Click to filter reminders'}">${reminderIcon}Reminders <span class="notes-label-chip-count">${reminderCount}</span></button>`;
+    const showingReminders = state.activeFilter === 'reminders';
+    if (showingReminders && pastReminderCount > 0) {
+      html += `<button class="notes-label-chip notes-label-clear-past" data-action="clear-past-reminders" title="Delete reminders whose time has passed"><svg width="10" height="10" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.4" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><polyline points="3 6 5 6 21 6"/><path d="M19 6l-1 14a2 2 0 0 1-2 2H8a2 2 0 0 1-2-2L5 6"/><path d="M8 6V4a2 2 0 0 1 2-2h4a2 2 0 0 1 2 2v2"/></svg>Clear past <span class="notes-label-chip-count">${pastReminderCount}</span></button>`;
+    }
+    for (const lbl of sortedLabels) {
+      html += `<button class="notes-label-chip${state.activeLabel === lbl ? ' active' : ''}" data-label="${_esc(lbl)}">#${_esc(lbl)}</button>`;
+    }
+    bar.innerHTML = html;
+    bar.querySelectorAll('.notes-label-chip').forEach(chip => {
+      chip.addEventListener('click', () => {
+        if (chip.dataset.action === 'all') {
+          app.setActiveLabel(null);
+          app.setActiveFilter(null);
+        } else if (chip.dataset.action === 'today') {
+          app.setActiveLabel(null);
+          app.setActiveFilter((state.activeFilter === 'today') ? null : 'today');
+        } else if (chip.dataset.action === 'goals') {
+          app.setActiveLabel(null);
+          app.setActiveFilter((state.activeFilter === 'goals') ? null : 'goals');
+        } else if (chip.dataset.action === 'default') {
+          app.setActiveLabel(null);
+          app.setActiveFilter((state.activeFilter === 'default') ? null : 'default');
+        } else if (chip.dataset.action === 'reminders') {
+          app.setActiveLabel(null);
+          // Cycle: null → reminders → null → no-reminders → null → reminders → ...
+          if (state.activeFilter === null) {
+            app.setActiveFilter(state.reminderChipNext);
+            app.setReminderChipNext((state.reminderChipNext === 'reminders') ? 'no-reminders' : 'reminders');
+          } else {
+            app.setActiveFilter(null);
+          }
+        } else if (chip.dataset.action === 'clear-past-reminders') {
+          _clearPastReminders();
+          return;
+        } else {
+          app.setActiveFilter(null);
+          app.setActiveLabel(chip.dataset.label || null);
+        }
+        _renderNotes();
+      });
+    });
+  }
+
+  function _renderLabelsInto(_body) {
+    if (!_body) return;
+    const pane = _body.closest('.notes-pane');
+    const toggleHost = pane?.querySelector('.notes-search-bar') || _body;
+    let toggle = toggleHost.querySelector(':scope > .notes-label-toggle');
+    if (!toggle) {
+      toggle = document.createElement('button');
+      toggle.type = 'button';
+      toggle.className = 'notes-label-toggle cal-filter-toggle';
+      toggle.addEventListener('click', () => {
+        app.setLabelsCollapsed(!state.labelsCollapsed);
+        try { persistence.setItem(NOTES_LABELS_COLLAPSED_KEY, state.labelsCollapsed ? '1' : '0'); } catch {}
+        _renderNotes();
+      });
+      const selectButton = toggleHost.querySelector('#notes-select-btn');
+      toggleHost.insertBefore(toggle, selectButton || null);
+    }
+    toggle.textContent = state.labelsCollapsed ? '+ Tags' : '− Tags';
+    toggle.title = state.labelsCollapsed ? 'Show tags' : 'Hide tags';
+    toggle.setAttribute('aria-expanded', state.labelsCollapsed ? 'false' : 'true');
+
+    // The shared chip scroller wraps this row once it is mounted.
+    let bar = _body.querySelector('.notes-labels-bar');
+    if (!bar) {
+      bar = document.createElement('div');
+      bar.className = 'notes-labels-bar';
+      _body.appendChild(bar);
+    }
+    _renderLabels(_body);
+  }
+
+  return { _renderLabels, _renderLabelsInto };
+}
diff --git a/frontend/src/features/notes/ui/layout.js b/frontend/src/features/notes/ui/layout.js
new file mode 100644
index 000000000..8935feff5
--- /dev/null
+++ b/frontend/src/features/notes/ui/layout.js
@@ -0,0 +1,123 @@
+/** Card reflow animation and the owned masonry resize observer. */
+export function createLayout({ isOpen = () => true } = {}) {
+  function _captureCardPositions() {
+    const body = document.querySelector('#notes-pane .notes-pane-body');
+    if (!body) return null;
+    const positions = new Map();
+    body.querySelectorAll('.note-card').forEach(card => {
+      const id = card.dataset.noteId;
+      if (id) positions.set(id, card.getBoundingClientRect());
+    });
+    return positions;
+  }
+
+  function _animateReflow(prevPositions) {
+    if (!prevPositions || !prevPositions.size) return;
+    const body = document.querySelector('#notes-pane .notes-pane-body');
+    if (!body || !body.isConnected) return;
+    body.querySelectorAll('.note-card').forEach(card => {
+      const id = card.dataset.noteId;
+      const prev = prevPositions.get(id);
+      if (!prev) return;
+      const next = card.getBoundingClientRect();
+      const dx = prev.left - next.left;
+      const dy = prev.top - next.top;
+      if (Math.abs(dx) < 1 && Math.abs(dy) < 1) return;
+      // Invert: jump back to old position
+      card.style.transition = 'none';
+      card.style.transform = `translate(${dx}px, ${dy}px)`;
+      // Play: animate to 0
+      requestAnimationFrame(() => {
+        card.style.transition = 'transform 0.25s cubic-bezier(0.34, 1.2, 0.64, 1)';
+        card.style.transform = '';
+        card.addEventListener('transitionend', () => {
+          card.style.transition = '';
+        }, { once: true });
+      });
+    });
+  }
+
+  function _applyMasonry(body) {
+    if (!body || !body.isConnected) return;
+    const pane = body.closest('.notes-pane');
+    const isGrid = pane?.classList.contains('notes-view-grid');
+    const isMobileGrid = isGrid && window.matchMedia('(max-width: 768px)').matches;
+    // Tear down any prior observer (defensive : _renderNotes wipes body.innerHTML).
+    if (_masonryObserver) { try { _masonryObserver.disconnect(); } catch {} _masonryObserver = null; }
+    // A save that resolves after close re-renders the leaving pane; don't
+    // re-create the observer that panel teardown already disposed.
+    if (!isOpen()) return;
+    if (!isGrid) {
+      // Clear any leftover inline spans so list view lays out normally.
+      body.querySelectorAll('.note-card, .notes-label-toggle, .notes-labels-bar, .notes-quick-add, .note-form, .doclib-chip-scroll-frame:has(> .notes-labels-bar)').forEach(c => { c.style.gridRowEnd = ''; });
+      return;
+    }
+    const ROW_PX = 4;
+    const spanForHeight = (h) => Math.max(1, Math.ceil(h / ROW_PX));
+    const recomputeFullRows = () => {
+      const quickAdd = body.querySelector('.notes-quick-add');
+      const labelsToggle = body.querySelector('.notes-label-toggle');
+      const labelsBar = body.querySelector('.notes-labels-bar');
+      const labelsLayout = labelsBar?.parentElement?.classList.contains('doclib-chip-scroll-frame')
+        ? labelsBar.parentElement
+        : labelsBar;
+      if (labelsToggle && getComputedStyle(labelsToggle).display !== 'none') {
+        labelsToggle.style.gridRowEnd = `span ${Math.max(1, spanForHeight(labelsToggle.scrollHeight))}`;
+      }
+      if (labelsLayout && getComputedStyle(labelsLayout).display !== 'none') {
+        const shave = isMobileGrid ? 4 : 0;
+        labelsLayout.style.gridRowEnd = `span ${Math.max(1, spanForHeight(labelsLayout.scrollHeight) - shave)}`;
+      }
+      if (quickAdd) {
+        const shave = isMobileGrid ? 4 : 0;
+        quickAdd.style.gridRowEnd = `span ${Math.max(1, spanForHeight(quickAdd.scrollHeight + 10) - shave)}`;
+      }
+      body.querySelectorAll('.note-form').forEach(form => {
+        form.style.gridColumn = '1 / -1';
+        const isDrawForm = !!form.querySelector('.note-form-type-seg.is-draw');
+        const minSpan = isMobileGrid ? (isDrawForm ? 104 : 64) : 1;
+        const renderedHeight = form.getBoundingClientRect?.().height || 0;
+        const drawReserve = isDrawForm && isMobileGrid ? 12 : 12;
+        const measuredHeight = Math.max(form.scrollHeight, renderedHeight) + drawReserve;
+        form.style.gridRowEnd = `span ${Math.max(minSpan, spanForHeight(measuredHeight))}`;
+      });
+    };
+    const recompute = (card) => {
+      // scrollHeight returns the natural content height : card.getBoundingClientRect()
+      // would return the grid cell height (collapsed to 4px until the span is set,
+      // which is the value we're trying to compute).
+      const h = card.scrollHeight + (isMobileGrid ? 6 : 8);
+      if (h <= 0) return;
+      card.style.gridRowEnd = `span ${spanForHeight(h)}`;
+    };
+    recomputeFullRows();
+    body.querySelectorAll('.note-card').forEach(recompute);
+    // Watch masonry participants : content can grow (image load, todo edits,
+    // quick-add/form expansion), and stale spans are what cause visual merging.
+    if ('ResizeObserver' in window) {
+      _masonryObserver = new ResizeObserver(entries => {
+        let fullRowsChanged = false;
+        for (const e of entries) {
+          if (e.target.classList.contains('note-card')) recompute(e.target);
+          else fullRowsChanged = true;
+        }
+        if (fullRowsChanged) recomputeFullRows();
+      });
+      body.querySelectorAll('.note-card').forEach(c => _masonryObserver.observe(c));
+    body.querySelectorAll('.notes-label-toggle, .notes-quick-add, .note-form').forEach(c => _masonryObserver.observe(c));
+    const labelsBar = body.querySelector('.notes-labels-bar');
+    const labelsLayout = labelsBar?.parentElement?.classList.contains('doclib-chip-scroll-frame')
+      ? labelsBar.parentElement
+      : labelsBar;
+    if (labelsLayout) _masonryObserver.observe(labelsLayout);
+    }
+  }
+
+  let _masonryObserver = null;
+
+  function dispose() {
+    _masonryObserver?.disconnect();
+    _masonryObserver = null;
+  }
+  return { dispose, _captureCardPositions, _animateReflow, _applyMasonry };
+}
diff --git a/frontend/src/features/notes/ui/lifecycle.js b/frontend/src/features/notes/ui/lifecycle.js
new file mode 100644
index 000000000..67a8da199
--- /dev/null
+++ b/frontend/src/features/notes/ui/lifecycle.js
@@ -0,0 +1,36 @@
+/** Notes-owned document/window listeners. Detached editor/menu owners release their resources. */
+export function createNotesLifecycle() {
+    const owners = new Map();
+    let observer = null;
+    function release(owner) {
+      const entry = owners.get(owner);
+      if (!entry) return;
+      owners.delete(owner);
+      for (const remove of entry.removers) remove();
+      if (!owners.size) { observer?.disconnect(); observer = null; }
+    }
+    function onDispose(owner, remove) {
+      if (!owner) throw new Error('Notes listener needs a lifecycle owner');
+      let entry = owners.get(owner);
+      if (!entry) {
+        entry = { connected: owner.isConnected, removers: [] };
+        owners.set(owner, entry);
+      }
+      entry.removers.push(remove);
+      if (!observer) {
+        observer = new MutationObserver(() => {
+          for (const [node, scope] of owners) {
+            if (node.isConnected) scope.connected = true;
+            else if (scope.connected) release(node);
+          }
+        });
+        observer.observe(document.body, { childList: true, subtree: true });
+      }
+    }
+    function listen(owner, target, event, listener, options) {
+      onDispose(owner, () => target.removeEventListener(event, listener, options));
+      target.addEventListener(event, listener, options);
+    }
+    function dispose() { for (const owner of [...owners.keys()]) release(owner); }
+    return { listen, onDispose, release, dispose };
+}
diff --git a/frontend/src/features/notes/ui/mobileEditor.js b/frontend/src/features/notes/ui/mobileEditor.js
new file mode 100644
index 000000000..f751ba7aa
--- /dev/null
+++ b/frontend/src/features/notes/ui/mobileEditor.js
@@ -0,0 +1,257 @@
+/** Mobile fullscreen editing, link reader mode and return to the panel. */
+export function createMobileEditor({
+  _applyDraftToNote,
+  _buildForm,
+  _fetchNotes,
+  _linkify,
+  _renderNotes,
+  _uid,
+  _wireChecklistTouchReorder,
+  _wireRow,
+  app,
+  state,
+  uiModule
+}) {
+  function _isNotesMobileMode() {
+    return ('ontouchstart' in window) && window.innerWidth <= 768;
+  }
+
+  let _mobileFsOverlay = null;
+
+  let _mobileFsNoteId = null;
+
+  function _openMobileFullscreenEdit(id, fromCard) {
+    const note = state.notes.find(n => n.id === id);
+    if (!note) return;
+    // Tear down any previous overlay (defensive).
+    _closeMobileFullscreenEdit({ save: false });
+    _mobileFsNoteId = id;
+    app.setEditingId(id);
+
+    const overlay = document.createElement('div');
+    overlay.className = 'note-fullscreen-overlay';
+    overlay.innerHTML = `
+    <div class="note-fullscreen-header">
+      <button type="button" class="note-fullscreen-back" title="Back">
+        <svg width="22" height="22" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round"><polyline points="15 18 9 12 15 6"></polyline></svg>
+      </button>
+      <div class="note-fullscreen-actions"></div>
+    </div>
+    <div class="note-fullscreen-body"></div>
+  `;
+    const body = overlay.querySelector('.note-fullscreen-body');
+    // Reuse the same edit form the in-place flow builds. Save buttons,
+    // checklist toggles, etc. all work as-is. Restore any unsaved draft.
+    const { note: _n, restored } = _applyDraftToNote(note, id);
+    const form = _buildForm(_n);
+    body.appendChild(form);
+    if (restored) uiModule.showToast('Restored unsaved changes');
+    document.body.appendChild(overlay);
+    _mobileFsOverlay = overlay;
+
+    // Animate up from the tapped tile's position so the transition reads
+    // as a zoom rather than a hard cut.
+    if (fromCard) {
+      const r = fromCard.getBoundingClientRect();
+      const vw = window.innerWidth, vh = window.innerHeight;
+      overlay.style.transformOrigin =
+        `${((r.left + r.width / 2) / vw) * 100}% ${((r.top + r.height / 2) / vh) * 100}%`;
+    }
+    overlay.classList.add('opening');
+    requestAnimationFrame(() => overlay.classList.add('open'));
+
+    // Wire the back button : saves whatever the form has and closes.
+    // mousedown preventDefault so it doesn't blur the input on first tap (which
+    // would eat the tap and require a second one).
+    const _backBtn = overlay.querySelector('.note-fullscreen-back');
+    _backBtn.addEventListener('mousedown', (e) => e.preventDefault());
+    _backBtn.addEventListener('click', () => {
+      _closeMobileFullscreenEdit({ save: true });
+    });
+
+    // The form's built-in Cancel only resets the in-place edit state; in
+    // the overlay context it does nothing visible. Replace its handler so
+    // Cancel actually dismisses the overlay without saving.
+    const cancelBtn = form.querySelector('.note-form-cancel');
+    if (cancelBtn) {
+      const fresh = cancelBtn.cloneNode(true);
+      cancelBtn.parentNode.replaceChild(fresh, cancelBtn);
+      fresh.addEventListener('mousedown', (e) => e.preventDefault());
+      fresh.addEventListener('click', (e) => {
+        e.preventDefault();
+        e.stopPropagation();
+        _closeMobileFullscreenEdit({ save: false });
+      });
+    }
+    // The built-in Save handler does the API call + refresh, but doesn't
+    // dismiss our overlay. Augment it (do NOT replace : the original is
+    // async and we'd lose the API call) to schedule a close once the
+    // save+render has had time to complete.
+    const saveBtn = form.querySelector('.note-form-save');
+    if (saveBtn) {
+      saveBtn.addEventListener('click', () => {
+        setTimeout(() => _closeMobileFullscreenEdit({ save: false }), 350);
+      });
+    }
+    // Make the checklist row drag handle (⋮⋮) actually work on touch.
+    // The form's default uses HTML5 native draggable which never fires
+    // on iOS/Android. Wire touch-based reorder for any row inside the
+    // overlay's checklist.
+    _wireChecklistTouchReorder(form);
+
+    // For each todo row whose text contains a URL, swap the bare <input>
+    // for a linkified <span> so URLs are tappable. Tapping anywhere that
+    // ISN'T a link flips back to the input for editing.
+    form.querySelectorAll('.note-cl-row').forEach(_addRowReadMode);
+
+    // Move only Delete from the form's footer actions row into the header.
+    // Archive intentionally stays out of the header: the footer Update button
+    // already morphs into the mobile Archive action for an untouched note.
+    const headerActions = overlay.querySelector('.note-fullscreen-actions');
+    const archiveBtn = form.querySelector('.note-form-archive-btn');
+    const deleteBtn  = form.querySelector('.note-form-delete-btn');
+    if (headerActions && deleteBtn) {
+      deleteBtn.classList.remove('note-form-collapsible');
+      headerActions.appendChild(deleteBtn);
+    }
+    // The built-in archive/delete handlers re-render the notes grid but
+    // leave THIS overlay sitting in front of it : looks like nothing
+    // happened. Add follow-up listeners that close the overlay so the
+    // user sees the action take effect.
+    if (archiveBtn) {
+      archiveBtn.addEventListener('click', () => {
+        setTimeout(() => _closeMobileFullscreenEdit({ save: false }), 200);
+      });
+    }
+    if (deleteBtn) {
+      deleteBtn.addEventListener('click', () => {
+        // Delete shows a styled confirm : give it room to resolve before
+        // we try to dismiss the overlay.
+        setTimeout(() => _closeMobileFullscreenEdit({ save: false }), 500);
+      });
+    }
+
+    // Tuck the tags input into the bottom actions row (Cancel / Update),
+    // pinned to the LEFT. Frees the meta row of an extra wrapping line
+    // and groups all the "exit" controls together.
+    const actionsGroup = form.querySelector('.note-form-actions-group');
+    const tagsInput    = form.querySelector('.note-form-label');
+    if (actionsGroup && tagsInput) {
+      actionsGroup.insertBefore(tagsInput, actionsGroup.firstChild);
+    }
+
+    // For checklist-type notes, move the photo (attach image) button into
+    // the same row as the + Add button (right side) : keeps the meta row
+    // tidy and puts the camera within thumb-reach of the active edit.
+    const addBtn   = form.querySelector('.note-cl-add');
+    const photoBtn = form.querySelector('.note-form-photo-btn');
+    if (addBtn && photoBtn) {
+      const addRow = document.createElement('div');
+      addRow.className = 'note-cl-add-row';
+      addBtn.parentNode.insertBefore(addRow, addBtn);
+      addRow.appendChild(addBtn);
+      addRow.appendChild(photoBtn);
+      // Tapping anywhere on the row (the empty gap, the dashed border,
+      // the "+ Add" label) triggers add. The photo button keeps its own
+      // click target so attach-image isn't ambushed.
+      addRow.addEventListener('click', (e) => {
+        if (e.target.closest('.note-form-photo-btn')) return;
+        if (e.target === addBtn || addBtn.contains(e.target)) return;
+        addBtn.click();
+      });
+      // The form's delegated "+ Add" handler does
+      //   inputs.insertBefore(newRow, addBtn)
+      // : but addBtn is no longer a direct child of `.note-checklist-inputs`
+      // now that we wrapped it. Bind a fresh handler that does the same
+      // thing but inserts before the WRAPPING row, and stop propagation
+      // so the broken delegate never runs.
+      addBtn.addEventListener('click', (e) => {
+        e.preventDefault();
+        e.stopPropagation();
+        const inputs = form.querySelector('.note-checklist-inputs');
+        if (!inputs) return;
+        const newRow = document.createElement('div');
+        newRow.className = 'note-cl-row';
+        newRow.draggable = true;
+        newRow.dataset.itemId = _uid();
+        newRow.dataset.indent = '0';
+        newRow.innerHTML = '<span class="note-cl-grip" title="Drag">⋮⋮</span><span class="note-cl-dot"></span><input type="text" class="note-cl-text" placeholder="Item..." /><button type="button" class="note-cl-rm">&times;</button>';
+        inputs.insertBefore(newRow, addRow);
+        _wireRow(newRow, inputs);
+        // Touch reorder on the freshly-added row's grip.
+        _wireChecklistTouchReorder(form);
+        newRow.querySelector('.note-cl-text')?.focus();
+      }, { capture: true });
+    }
+
+    // Read-mode overlay for plain notes: render the content as a div with
+    // clickable hyperlinks, layered above the textarea. Tapping anywhere
+    // in the overlay that ISN'T a link hides the overlay and focuses the
+    // textarea so the user can start editing. Tapping a link opens it.
+    const ta = form.querySelector('.note-form-content');
+    if (ta && (note.content || '').trim()) {
+      const reader = document.createElement('div');
+      reader.className = 'note-form-content-reader';
+      reader.innerHTML = _linkify(note.content || '');
+      ta.style.display = 'none';
+      ta.insertAdjacentElement('beforebegin', reader);
+      reader.addEventListener('click', (e) => {
+        if (e.target.closest('a')) return;  // let links open normally
+        reader.remove();
+        ta.style.display = '';
+        // Let the browser place the cursor naturally : forcing
+        // setSelectionRange right after focus() raced with the underlying
+        // tap event and produced inconsistent cursor positions on mobile.
+        ta.focus({ preventScroll: true });
+      });
+    }
+
+    // Opening an EXISTING note → read mode, no keyboard pop. Only a
+    // brand-new note (created via the + button) should auto-focus an
+    // input field. The user can tap the content to switch to edit.
+    // (New-note creation flows through _createNote, not this function.)
+  }
+
+  function _closeMobileFullscreenEdit(opts = {}) {
+    if (!_mobileFsOverlay) return;
+    const overlay = _mobileFsOverlay;
+    overlay.querySelector('.note-form')?._flushDraft?.();
+    _mobileFsOverlay = null;
+    // If the form has a Save button, click it on close so edits aren't lost
+    // when the user uses the back arrow instead of an explicit Save.
+    if (opts.save) {
+      const saveBtn = overlay.querySelector('.note-form-save, [data-action="save"]');
+      if (saveBtn) try { saveBtn.click(); } catch {}
+    }
+    overlay.classList.remove('open');
+    overlay.classList.add('closing');
+    setTimeout(() => {
+      if (overlay.parentNode) overlay.parentNode.removeChild(overlay);
+      _mobileFsNoteId = null;
+      app.setEditingId(null);
+      // Refresh the grid so any save the user made is reflected.
+      if (opts.save !== false) { _fetchNotes().then(_renderNotes).catch(() => {}); }
+    }, 220);
+  }
+
+  function _addRowReadMode(row) {
+    const txt = row.querySelector('.note-cl-text');
+    if (!txt) return;
+    const val = txt.value || '';
+    if (!/(https?:\/\/|www\.)/i.test(val)) return;
+    if (row.querySelector('.note-cl-text-reader')) return;  // already wired
+    const span = document.createElement('span');
+    span.className = 'note-cl-text-reader';
+    span.innerHTML = _linkify(val);
+    txt.style.display = 'none';
+    txt.insertAdjacentElement('beforebegin', span);
+    span.addEventListener('click', (e) => {
+      if (e.target.closest('a')) return;  // let the link open
+      span.remove();
+      txt.style.display = '';
+      txt.focus({ preventScroll: true });
+    });
+  }
+
+  return { _isNotesMobileMode, _openMobileFullscreenEdit, _closeMobileFullscreenEdit, _addRowReadMode };
+}
diff --git a/frontend/src/features/notes/ui/mobileReorder.js b/frontend/src/features/notes/ui/mobileReorder.js
new file mode 100644
index 000000000..b5f6404d3
--- /dev/null
+++ b/frontend/src/features/notes/ui/mobileReorder.js
@@ -0,0 +1,214 @@
+/** Mobile card long press, placeholder drag and reorder persistence. */
+export function createMobileReorder({
+  lifecycle,
+  _applyMasonry,
+  _enterSelectMode,
+  commitMobileOrder,
+  app,
+}) {
+  function _bindLongPressDrag(card) {
+    let pressTimer = null;
+    let startX = 0, startY = 0;
+    let armed = false;
+    const CANCEL_PX = 8;
+    const HOLD_MS = 450;
+
+    card.addEventListener('touchstart', (e) => {
+      // Don't fight scroll on touchpoints over real interactive children
+      // (in mobile-mode they're CSS-hidden anyway, but be defensive).
+      if (e.target.closest('button, input, a, .note-form')) return;
+      if (e.touches.length !== 1) return;
+      armed = true;
+      startX = e.touches[0].clientX;
+      startY = e.touches[0].clientY;
+      pressTimer = setTimeout(() => {
+        if (!armed) return;
+        try { navigator.vibrate?.(15); } catch {}
+        app.setSuppressNextNoteTapId(card.dataset.noteId);
+        _enterSelectMode(card.dataset.noteId);
+      }, HOLD_MS);
+    }, { passive: true });
+    card.addEventListener('touchmove', (e) => {
+      if (!armed) return;
+      const t = e.touches[0];
+      if (Math.abs(t.clientX - startX) > CANCEL_PX || Math.abs(t.clientY - startY) > CANCEL_PX) {
+        armed = false;
+        if (pressTimer) { clearTimeout(pressTimer); pressTimer = null; }
+      }
+    }, { passive: true });
+    const cancel = () => {
+      armed = false;
+      if (pressTimer) { clearTimeout(pressTimer); pressTimer = null; }
+    };
+    lifecycle.onDispose(card, cancel);
+    card.addEventListener('touchend', cancel, { passive: true });
+    card.addEventListener('touchcancel', cancel, { passive: true });
+  }
+
+  let _dragState = null;
+
+  let _docDragHandlersBound = false;
+
+  function _enterDragMode(initialCard, initialTouch) {
+    document.body.classList.add('notes-drag-mode');
+    document.querySelectorAll('.note-card').forEach(_setupDragForCard);
+    if (!_docDragHandlersBound) {
+      lifecycle.listen(document.getElementById('notes-pane'), document, 'touchmove', _onDocTouchMove, { passive: false });
+      lifecycle.listen(document.getElementById('notes-pane'), document, 'touchend',  _onDocTouchEnd,  { passive: true });
+      lifecycle.listen(document.getElementById('notes-pane'), document, 'touchcancel', _onDocTouchEnd, { passive: true });
+      _docDragHandlersBound = true;
+    }
+    // Auto-grab the card the user long-pressed : they're already holding
+    // their finger on it, so begin the drag straight away. Releasing
+    // (touchend) commits the reorder AND exits drag mode in one motion.
+    if (initialCard && initialTouch) {
+      _beginGrab(initialCard, initialTouch);
+    }
+  }
+
+  function _exitDragMode() {
+    document.body.classList.remove('notes-drag-mode');
+    if (_dragState) {
+      // Defensive: if exit fires while a drag is in flight, snap the card back.
+      _onDocTouchEnd();
+    }
+    // Leave _docDragHandlersBound true so re-entering drag mode reuses them.
+  }
+
+  function _setupDragForCard(card) {
+    if (card.dataset.dragBound === '1') return;
+    card.dataset.dragBound = '1';
+    card.addEventListener('touchstart', (e) => {
+      if (!document.body.classList.contains('notes-drag-mode')) return;
+      if (e.touches.length !== 1) return;
+      if (_dragState) return;
+      e.preventDefault();
+      e.stopPropagation();
+      _beginGrab(card, e.touches[0]);
+    }, { passive: false });
+  }
+
+  function _beginGrab(card, touch) {
+    const rect = card.getBoundingClientRect();
+    const prevStyle = card.getAttribute('style') || '';
+    // Placeholder fills the card's old slot so the grid layout doesn't reflow.
+    const placeholder = document.createElement('div');
+    placeholder.className = 'note-card-placeholder';
+    placeholder.style.width = rect.width + 'px';
+    placeholder.style.height = rect.height + 'px';
+    placeholder.style.margin = getComputedStyle(card).margin;
+    if (card.style.gridRowEnd) placeholder.style.gridRowEnd = card.style.gridRowEnd;
+    const grid = card.parentNode;
+    grid.insertBefore(placeholder, card);
+
+    // Detach the card visually : fixed-position, anchored to the finger.
+    card.classList.add('note-card-dragging');
+    card.style.position = 'fixed';
+    card.style.left = rect.left + 'px';
+    card.style.top  = rect.top + 'px';
+    card.style.width  = rect.width + 'px';
+    card.style.height = rect.height + 'px';
+    card.style.margin = '0';
+    card.style.zIndex = '10001';
+    // pointer-events:none so elementFromPoint sees the card BENEATH the finger
+    card.style.pointerEvents = 'none';
+
+    _dragState = {
+      card, placeholder, grid, prevStyle,
+      grabOffsetX: touch.clientX - rect.left,
+      grabOffsetY: touch.clientY - rect.top,
+    };
+    try { navigator.vibrate?.(8); } catch {}
+  }
+
+  function _onDocTouchMove(e) {
+    if (!_dragState) return;
+    if (e.touches.length !== 1) return;
+    e.preventDefault();
+    const touch = e.touches[0];
+    const { card, placeholder, grid } = _dragState;
+    card.style.left = (touch.clientX - _dragState.grabOffsetX) + 'px';
+    const quickAdd = grid.querySelector('.notes-quick-add');
+    const minTop = quickAdd ? quickAdd.getBoundingClientRect().bottom + 4 : grid.getBoundingClientRect().top;
+    const maxTop = Math.max(minTop, window.innerHeight - card.getBoundingClientRect().height - 8);
+    const nextTop = Math.max(minTop, Math.min(maxTop, touch.clientY - _dragState.grabOffsetY));
+    card.style.top = nextTop + 'px';
+
+    const hitY = Math.max(minTop + 1, Math.min(window.innerHeight - 1, touch.clientY));
+    const under = document.elementFromPoint(touch.clientX, hitY);
+    const target = under && under.closest
+      ? under.closest('.note-card:not(.note-card-dragging)')
+      : null;
+    if (!target || target === card) return;
+    if (target.parentNode !== grid) return;
+
+    // Move the PLACEHOLDER (not the card) above or below the target depending
+    // on which half of the target the finger is in. This is the hysteresis
+    // that stops the oscillation : once the placeholder moves past a card,
+    // the cursor has to cross THAT card's midpoint in the other direction
+    // to swap back.
+    const tRect = target.getBoundingClientRect();
+    const targetMidY = tRect.top + tRect.height / 2;
+    if (touch.clientY < targetMidY) {
+      if (placeholder.nextElementSibling !== target) {
+        grid.insertBefore(placeholder, target);
+      }
+    } else {
+      if (target.nextElementSibling !== placeholder) {
+        grid.insertBefore(placeholder, target.nextElementSibling);
+      }
+    }
+  }
+
+  function _onDocTouchEnd() {
+    if (!_dragState) return;
+    const { card, placeholder, grid, prevStyle } = _dragState;
+    _dragState = null;
+    // Animate the card from its current fixed position to where the
+    // placeholder sits, then re-parent and clear inline styles. Drag
+    // mode auto-exits once the snap finishes : release = done.
+    const phRect = placeholder.getBoundingClientRect();
+    card.style.transition = 'left 0.2s ease, top 0.2s ease';
+    card.style.left = phRect.left + 'px';
+    card.style.top  = phRect.top + 'px';
+    setTimeout(() => {
+      placeholder.parentNode.insertBefore(card, placeholder);
+      placeholder.remove();
+      card.classList.remove('note-card-dragging');
+      // Restore the card's pre-drag inline styles. Mobile masonry stores
+      // grid-row-end inline, and custom backgrounds use inline style too; wiping
+      // cssText made dropped cards collapse into neighboring notes in grid view.
+      if (prevStyle) card.setAttribute('style', prevStyle);
+      else card.removeAttribute('style');
+      _applyMasonry(grid);
+      _commitNoteReorder();
+      // One drag, one exit : release ends the rearrange session entirely.
+      if (document.body.classList.contains('notes-drag-mode')) {
+        document.body.classList.remove('notes-drag-mode');
+      }
+    }, 210);
+  }
+
+  async function _commitNoteReorder() {
+    const grid = document.querySelector('#notes-pane .notes-pane-body');
+    if (!grid) return;
+    const ids = Array.from(grid.querySelectorAll('.note-card')).map(c => c.dataset.noteId).filter(Boolean);
+    if (!ids.length) return;
+    await commitMobileOrder(ids);
+  }
+
+  function dispose() {
+    if (_dragState) {
+      const { card, placeholder, prevStyle } = _dragState;
+      _dragState = null;
+      placeholder.parentNode?.insertBefore(card, placeholder);
+      placeholder.remove();
+      card.classList.remove('note-card-dragging');
+      if (prevStyle) card.setAttribute('style', prevStyle);
+      else card.removeAttribute('style');
+    }
+    document.body.classList.remove('notes-drag-mode');
+    _docDragHandlersBound = false;
+  }
+  return { dispose, _bindLongPressDrag, _enterDragMode, _exitDragMode, _setupDragForCard, _beginGrab, _onDocTouchMove, _onDocTouchEnd, _commitNoteReorder };
+}
diff --git a/frontend/src/features/notes/ui/panel.js b/frontend/src/features/notes/ui/panel.js
new file mode 100644
index 000000000..0a6031233
--- /dev/null
+++ b/frontend/src/features/notes/ui/panel.js
@@ -0,0 +1,506 @@
+/** Panel mounting, keyboard handlers, minimization and note navigation. */
+export function createPanel({
+  wireToolbar,
+  wireSelectionActions,
+  _wireNotesWindow,
+  _restoreNotesSidebarDock,
+  _bringNotesToFront,
+  disposeUI,
+  lifecycle,
+  Modals,
+  NOTES_FIRST_OPEN_HINT_KEY,
+  REMINDER_DISMISSED_AT_KEY,
+  _clearViewedReminderGlows,
+  _closeMobileFullscreenEdit,
+  _commitOpenInPlaceEditor,
+  _copyNote,
+  _enterSelectMode,
+  _exitSelectMode,
+  _fetchNotes,
+  _flushPendingHighlights,
+  _isNotesMobileMode,
+  _popAndRunUndo,
+  _renderLoadingSkeleton,
+  _renderNotes,
+  _startReminderLoop,
+  app,
+  bindTourHintDismiss,
+  dismissOrRemove,
+  persistence,
+  state,
+  workflows
+}) {
+  function _forceCloseNotesPanel() {
+    app.setOpen(false);
+    app.setEditingId(null);
+    try { _commitOpenInPlaceEditor(); } catch {}
+    try { _closeMobileFullscreenEdit({ save: true }); } catch {}
+    try { _clearViewedReminderGlows(); } catch {}
+    if (_notesKeydownHandler) {
+      document.removeEventListener('keydown', _notesKeydownHandler);
+      _notesKeydownHandler = null;
+    }
+    if (_notesSelectEscHandler) {
+      document.removeEventListener('keydown', _notesSelectEscHandler, true);
+      _notesSelectEscHandler = null;
+    }
+    disposeOwnedPortals();
+    disposeUI();
+    document.body.classList.remove('notes-view', 'notes-mobile-mode', 'notes-drag-mode');
+    document.getElementById('tool-notes-btn')?.classList.remove('active');
+    try { Modals.unregister('notes-panel'); } catch {}
+    try { document.getElementById('notes-pane')?.remove(); } catch {}
+    try { document.getElementById('notes-pane-backdrop')?.remove(); } catch {}
+    try { window._restoreSidebarIfRouteCollapsed?.(); } catch {}
+  }
+
+  function _showNotesFirstOpenHint(pane) {
+    if (!pane || typeof persistence === 'undefined') return;
+    try {
+      if (persistence.getItem(NOTES_FIRST_OPEN_HINT_KEY)) return;
+      persistence.setItem(NOTES_FIRST_OPEN_HINT_KEY, '1');
+    } catch {
+      return;
+    }
+
+    dismissOrRemove(document.getElementById('notes-first-open-hint'));
+    const hint = document.createElement('div');
+    hint.id = 'notes-first-open-hint';
+    hint.className = 'tour-hint';
+    hint.innerHTML = `
+    <div class="tour-hint-text"><b>Notes</b> is your basic todo list, and also where reminders are managed.</div>
+    <button type="button" class="tour-hint-dismiss">OK</button>
+  `;
+    document.body.appendChild(hint);
+
+    const place = () => {
+      const r = pane.getBoundingClientRect();
+      const hw = hint.offsetWidth || 260;
+      hint.style.top = Math.max(12, r.top + 58) + 'px';
+      hint.style.left = Math.min(window.innerWidth - hw - 12, Math.max(12, r.left + 18)) + 'px';
+    };
+    requestAnimationFrame(() => {
+      place();
+      hint.classList.add('tour-hint-in');
+    });
+    lifecycle.listen(hint, window, 'resize', place);
+    bindTourHintDismiss(hint, {
+      timeout: 6500,
+      fade: 180,
+      onDismiss: () => window.removeEventListener('resize', place),
+    });
+  }
+
+  function _ensureNotesChipRegistered() {
+    if (Modals.isRegistered('notes-panel')) return;
+    Modals.register('notes-panel', {
+      railBtnId: 'rail-notes',
+      sidebarBtnId: 'tool-notes-btn',
+      restoreFn: () => { openPanel(); },
+      closeFn: () => { _forceCloseNotesPanel(); },
+    });
+  }
+
+  function openPanel() {
+    if (state.open) {
+      _bringNotesToFront();
+      return;
+    }
+    // Notes and the document editor occupy the same primary workspace. Preserve
+    // an open document as a dock chip instead of allowing the two panes to stack
+    // into a broken layout (or closing the user's document outright).
+    try {
+      if (window.documentModule?.isPanelOpen?.()) {
+        window.documentModule.closePanel('down');
+      }
+    } catch (_) {}
+    app.setOpen(true);
+    app.setEditingId(null);
+    app.setSearchQuery('');
+    _clearViewedReminderGlows();
+    app.setFiredDotDismissedAt(Date.now());
+    try { persistence.setItem(REMINDER_DISMISSED_AT_KEY, String(state.firedDotDismissedAt)); } catch {}
+
+    const container = document.getElementById('chat-container');
+    if (!container) return;
+
+    document.body.classList.add('notes-view');
+
+    // On mobile the notes panel takes the whole screen : auto-close the
+    // sidebar so the panel isn't cropped underneath it.
+    if (window.innerWidth <= 768) {
+      const sb = document.getElementById('sidebar');
+      if (sb) sb.classList.add('hidden');
+      document.body.classList.add('sidebar-collapsed');
+    }
+    // Mobile mode: tiles become read-only previews (no inline checkbox /
+    // edit / archive / etc.), tap opens a fullscreen edit overlay,
+    // long-press enters drag-to-reorder mode. See _bindCardEvents +
+    // .notes-mobile-mode CSS rules.
+    if (_isNotesMobileMode()) document.body.classList.add('notes-mobile-mode');
+
+    // Toggle button state
+    const btn = document.getElementById('tool-notes-btn');
+    if (btn) btn.classList.add('active');
+
+    // Create panel
+    const pane = document.createElement('div');
+    pane.id = 'notes-pane';
+    pane.className = 'notes-pane';
+    pane.innerHTML = `
+    <div class="notes-mobile-grabber" id="notes-mobile-grabber" aria-hidden="true"></div>
+    <div class="notes-pane-header">
+      <h4 class="notes-pane-title"><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" style="vertical-align:-2.5px;margin-right:6px"><path d="M5 3h10l4 4v14H5z"/><path d="M15 3v5h5"/><path d="M8 17.5 15.5 10l2.5 2.5L10.5 20H8z"/></svg>Notes</h4>
+      <span style="flex:1"></span>
+      <button id="notes-archive-toggle" class="doc-action-icon-btn notes-header-text-btn" title="View archive" style="opacity:0.8;gap:5px;">
+        <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="2" y="3" width="20" height="5" rx="1"/><path d="M4 8v11a2 2 0 002 2h12a2 2 0 002-2V8"/><path d="M10 12h4"/></svg>
+        <span class="notes-header-btn-label">Archive</span>
+      </button>
+      <button id="notes-view-toggle" class="doc-action-icon-btn notes-header-text-btn" title="Toggle view" style="opacity:0.8;gap:5px;">
+        <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="3" y="3" width="7" height="7"/><rect x="14" y="3" width="7" height="7"/><rect x="3" y="14" width="7" height="7"/><rect x="14" y="14" width="7" height="7"/></svg>
+        <span class="notes-header-btn-label">Toggle</span>
+      </button>
+      <button id="notes-minimize-btn" class="modal-minimize-btn" title="Minimize" aria-label="Minimize notes" style="position:relative;left:2px;"><svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="3.4" stroke-linecap="round" aria-hidden="true"><line x1="6" y1="18" x2="18" y2="18"/></svg></button>
+    </div>
+    <div class="notes-search-bar">
+      <input type="text" id="notes-search" class="memory-search-input" placeholder="Search notes…" autocomplete="off" />
+      <button id="notes-select-btn" class="notes-select-trigger" type="button">Select</button>
+    </div>
+    <div id="notes-bulk-bar" class="memory-bulk-bar hidden">
+      <label class="memory-bulk-check-all"><input type="checkbox" id="notes-select-all" /> All</label>
+      <span id="notes-selected-count">0 Selected</span>
+      <span style="flex:1"></span>
+      <button id="notes-send-agent" class="memory-toolbar-btn" disabled><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" style="vertical-align:-2px;margin-right:5px;opacity:0.6"><path d="M14.7 6.3a1 1 0 0 0 0 1.4l1.6 1.6a1 1 0 0 0 1.4 0l3.77-3.77a6 6 0 0 1-7.94 7.94l-6.91 6.91a2.12 2.12 0 0 1-3-3l6.91-6.91a6 6 0 0 1 7.94-7.94l-3.76 3.76z"></path></svg>Send to Agent</button>
+      <button id="notes-bulk-archive" class="memory-toolbar-btn" disabled>
+        <svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" style="vertical-align:-2px;margin-right:4px;"><rect x="2" y="3" width="20" height="5" rx="1"/><path d="M4 8v11a2 2 0 002 2h12a2 2 0 002-2V8"/><path d="M10 12h4"/></svg>Archive
+      </button>
+      <button id="notes-bulk-delete" class="memory-toolbar-btn danger" disabled>
+        <svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" style="vertical-align:-2px;margin-right:4px;"><polyline points="3 6 5 6 21 6"/><path d="M19 6l-1 14a2 2 0 0 1-2 2H8a2 2 0 0 1-2-2L5 6"/><path d="M8 6V4a2 2 0 0 1 2-2h4a2 2 0 0 1 2 2v2"/><line x1="10" y1="11" x2="10" y2="17"/><line x1="14" y1="11" x2="14" y2="17"/></svg>Delete
+      </button>
+      <button id="notes-bulk-cancel" class="memory-toolbar-btn active" title="Cancel selection" aria-label="Cancel selection">
+        <svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"><line x1="18" y1="6" x2="6" y2="18"/><line x1="6" y1="6" x2="18" y2="18"/></svg>
+      </button>
+    </div>
+    <div class="notes-pane-body"></div>
+  `;
+
+    // On mobile open as a full-screen bottom sheet (slide up), not the desktop
+    // side panel. Set inline so it wins over the base .notes-pane rule regardless
+    // of cascade specifics (the CSS @media override wasn't reliably applying,
+    // which left it as a side panel squeezing the chat).
+    if (window.innerWidth <= 768) {
+      pane.style.position = 'fixed';
+      pane.style.inset = '0';
+      pane.style.width = '100%';
+      pane.style.maxWidth = '100%';
+      pane.style.zIndex = '170';
+      pane.style.borderRadius = '14px 14px 0 0';
+      pane.style.animation = 'sheet-enter 0.25s cubic-bezier(0.2, 0.8, 0.2, 1) both';
+      pane.style.transformOrigin = 'bottom center';
+    }
+
+    // Mount on body so Notes can behave like the other draggable windows. On
+    // desktop it is immediately docked to the right by _restoreNotesSidebarDock.
+    const backdrop = document.createElement('div');
+    backdrop.className = 'notes-pane-backdrop';
+    backdrop.id = 'notes-pane-backdrop';
+    backdrop.addEventListener('click', (ev) => {
+      if (ev.target === backdrop) closePanel('down');
+    });
+    backdrop.appendChild(pane);
+    document.body.appendChild(backdrop);
+    _wireNotesWindow(pane);
+    _restoreNotesSidebarDock(pane);
+    _bringNotesToFront(pane);
+
+    // Events
+    // (Close chevron removed : swipe down on mobile, tool-rail toggle on desktop.)
+
+    // Mobile: swipe the grab handle / header down to dismiss (minimise to chip).
+    // Mirrors the document sheet gesture : finger-following, velocity-based
+    // dismiss, rubber-band on up-drag, spring snap-back.
+    _wireNotesSwipeDismiss(pane.querySelector('.notes-mobile-grabber'), pane);
+    _wireNotesSwipeDismiss(pane.querySelector('.notes-pane-header'), pane);
+
+    pane.addEventListener('pointerdown', () => _bringNotesToFront(pane), true);
+    pane.addEventListener('focusin', () => _bringNotesToFront(pane), true);
+
+    const minBtn = document.getElementById('notes-minimize-btn');
+    if (minBtn) minBtn.addEventListener('click', (e) => {
+      e.preventDefault();
+      e.stopPropagation();
+      closePanel('down');
+    });
+    wireToolbar(pane);
+    // Select mode
+    document.getElementById('notes-select-btn').addEventListener('click', () => {
+      if (state.selectMode) _exitSelectMode(); else _enterSelectMode();
+    });
+    // Esc cancels select mode. Notes uses a toggle "Select" button rather
+    // than a *-bulk-cancel button, so the global Esc-cancel handler in
+    // keyboard-shortcuts.js can't reach it : handle it here. Capture phase
+    // + stopPropagation so Esc cancels select instead of closing the panel.
+    if (_notesSelectEscHandler) {
+      document.removeEventListener('keydown', _notesSelectEscHandler, true);
+    }
+    _notesSelectEscHandler = (e) => {
+      if (e.key === 'Escape' && state.selectMode) {
+        e.preventDefault();
+        e.stopPropagation();
+        _exitSelectMode();
+      }
+    };
+    document.addEventListener('keydown', _notesSelectEscHandler, true);
+    wireSelectionActions();
+    // Escape: exit select mode first (if active), otherwise close the panel.
+    // Skip when the user is editing a form field : those have their own
+    // ESC-to-cancel handlers and we don't want to nuke the whole panel
+    // mid-edit.
+    // Idempotent: remove any previous handler from a prior openPanel so
+    // re-opening doesn't stack multiple handlers.
+    if (_notesKeydownHandler) {
+      document.removeEventListener('keydown', _notesKeydownHandler);
+      _notesKeydownHandler = null;
+    }
+    _notesKeydownHandler = (e) => {
+      if (!state.open) return;
+      const t = e.target;
+      const inField = t && (t.tagName === 'INPUT' || t.tagName === 'TEXTAREA' || t.isContentEditable);
+      // Ctrl/Cmd+Z anywhere in the panel : undo the last note action. Skip when
+      // typing in a field so the browser's normal text-undo still works.
+      if ((e.ctrlKey || e.metaKey) && (e.key === 'z' || e.key === 'Z') && !e.shiftKey) {
+        if (inField) return;
+        if (workflows.undoCount() === 0) return;
+        e.preventDefault();
+        _popAndRunUndo();
+        return;
+      }
+      // Ctrl/Cmd+C while hovering a note card → copy that note. Skip when the
+      // user is editing or has an active text selection (let the browser handle
+      // a real text copy in that case).
+      if ((e.ctrlKey || e.metaKey) && (e.key === 'c' || e.key === 'C') && !e.shiftKey && !e.altKey) {
+        if (inField) return;
+        const sel = window.getSelection?.();
+        if (sel && sel.toString && sel.toString().length > 0) return;
+        const hovered = document.querySelector('.note-card:hover');
+        if (!hovered) return;
+        const id = hovered.dataset.noteId;
+        if (!id) return;
+        e.preventDefault();
+        // Flash the ⋯ menu button (copy now lives in that menu).
+        const btn = hovered.querySelector('.note-card-corner-menu');
+        _copyNote(id, btn);
+        return;
+      }
+      if (e.key !== 'Escape') return;
+      if (inField) return;
+      if (state.selectMode) { _exitSelectMode(); return; }
+      if (state.showingArchived) {
+        // Mirror the archive toggle button: flip back to active notes.
+        document.getElementById('notes-archive-toggle')?.click();
+        return;
+      }
+      _forceCloseNotesPanel();
+    };
+    document.addEventListener('keydown', _notesKeydownHandler);
+
+    // Load : show skeleton immediately, then fetch
+    _renderLoadingSkeleton();
+    // Defer the highlight flush to the next frame so it runs *after* the cards
+    // are committed to the DOM (and any FLIP animations have settled), giving
+    // the querySelector lookups inside something to find.
+    _fetchNotes().then(() => {
+      if (!pane.isConnected || !state.open) { _startReminderLoop(); return; }
+      _renderNotes();
+      requestAnimationFrame(() => _flushPendingHighlights());
+      _startReminderLoop();
+      _showNotesFirstOpenHint(pane);
+    });
+  }
+
+  function closePanel(direction) {
+    if (!state.open) return;
+    app.setOpen(false);
+    app.setEditingId(null);
+    _clearViewedReminderGlows();
+    const _minimize = direction === 'down';
+    if (_minimize) {
+      _ensureNotesChipRegistered();
+    } else if (Modals.isRegistered('notes-panel')) {
+      Modals.unregister('notes-panel');
+    }
+
+    // Drop panel-owned keydown listeners. The reminder interval is page-owned.
+    if (_notesKeydownHandler) {
+      document.removeEventListener('keydown', _notesKeydownHandler);
+      _notesKeydownHandler = null;
+    }
+    if (_notesSelectEscHandler) {
+      document.removeEventListener('keydown', _notesSelectEscHandler, true);
+      _notesSelectEscHandler = null;
+    }
+
+    disposeOwnedPortals();
+    disposeUI();
+    document.body.classList.remove('notes-view');
+    document.body.classList.remove('notes-mobile-mode');
+    document.body.classList.remove('notes-drag-mode');
+    // Closing the panel should PRESERVE in-progress edits, not drop them.
+    // Commit any open in-place editor, and close the mobile fullscreen
+    // overlay with save=true so the note is persisted.
+    try { _commitOpenInPlaceEditor(); } catch {}
+    _closeMobileFullscreenEdit({ save: true });
+    // /notes route may have collapsed the wide sidebar to a rail; restore.
+    try { window._restoreSidebarIfRouteCollapsed?.(); } catch (_) {}
+
+    const btn = document.getElementById('tool-notes-btn');
+    if (btn) btn.classList.remove('active');
+
+    const pane = document.getElementById('notes-pane');
+    const backdrop = document.getElementById('notes-pane-backdrop');
+    if (pane) {
+      // Scale-out + fade. Match the enter animation duration so close feels
+      // like the same gesture played backwards.
+      pane.classList.add('notes-pane-leaving');
+      const _cleanup = () => {
+        try { pane.remove(); } catch {}
+        try { backdrop?.remove(); } catch {}
+      };
+      pane.addEventListener('animationend', _cleanup, { once: true });
+      // Belt-and-braces: if animation is skipped (reduced motion / detached
+      // tab) the listener won't fire; remove after the expected duration.
+      setTimeout(_cleanup, 220);
+    } else if (backdrop) {
+      backdrop.remove();
+    }
+    // Show the dock chip for a swipe-down minimize (tap it to reopen).
+    if (_minimize) { try { Modals.minimize('notes-panel'); } catch {} }
+  }
+
+  function togglePanel() {
+    if (state.open) closePanel();
+    else openPanel();
+  }
+
+  function isPanelOpen() { return state.open; }
+
+  async function openNote(noteId) {
+    const wasOpen = !!(isPanelOpen && isPanelOpen());
+    app.setShowingArchived(false);
+    app.setActiveLabel(null);
+    app.setActiveFilter(null);
+    app.setSearchQuery('');
+    if (!wasOpen) {
+      openPanel();
+    } else {
+      _bringNotesToFront();
+      const searchEl = document.getElementById('notes-search');
+      if (searchEl) searchEl.value = '';
+      const pane = document.getElementById('notes-pane');
+      if (pane) pane.classList.remove('notes-pane-archive');
+      const archiveBtn = document.getElementById('notes-archive-toggle');
+      if (archiveBtn) archiveBtn.classList.remove('active');
+      await _fetchNotes();
+      _renderNotes();
+    }
+    // openPanel() kicks off _fetchNotes() asynchronously, so the cards for
+    // newly-created notes may not be in the DOM yet. Poll until the card exists.
+    if (!noteId) return;
+    let tries = 0;
+    const findAndFlash = () => {
+      const card = document.querySelector(`.note-card[data-note-id="${noteId}"]`)
+        || document.querySelector(`.note-card[data-note-id^="${noteId.slice(0, 8)}"]`);
+      if (card) {
+        _smoothScrollToNoteCard(card);
+        card.classList.add('note-card-flash');
+        setTimeout(() => card.classList.remove('note-card-flash'), 1600);
+        return true;
+      }
+      return false;
+    };
+    const tryNext = () => {
+      if (findAndFlash()) return;
+      if (++tries < 20) setTimeout(tryNext, 200);
+    };
+    setTimeout(tryNext, 120);
+  }
+
+  let _notesKeydownHandler = null;
+
+  let _notesSelectEscHandler = null;
+
+  function _wireNotesSwipeDismiss(el, pane) {
+    if (!el || !pane) return;
+    const DISMISS_THRESHOLD = 50, VELOCITY_THRESHOLD = 0.3, RUBBER = 0.35;
+    let startY = 0, startX = 0, lastY = 0, lastT = 0, velocity = 0;
+    let dragging = false, cancelled = false;
+
+    el.addEventListener('touchstart', (e) => {
+      if (window.innerWidth > 768 || e.touches.length !== 1) return;
+      if (e.target.closest('button, input, select, label, textarea')) return;
+      const t = e.touches[0];
+      startY = t.clientY; startX = t.clientX; lastY = startY; lastT = e.timeStamp;
+      velocity = 0; dragging = false; cancelled = false;
+    }, { passive: true });
+
+    el.addEventListener('touchmove', (e) => {
+      if (cancelled || window.innerWidth > 768) return;
+      const t = e.touches[0];
+      const dx = Math.abs(t.clientX - startX);
+      const dy = t.clientY - startY;
+      if (!dragging) {
+        if (dx > 40 && dx > Math.abs(dy) * 2) { cancelled = true; return; }
+        if (Math.abs(dy) > 8) {
+          dragging = true;
+          pane.style.animation = 'none';
+          pane.style.transition = 'none';
+          pane.style.willChange = 'transform';
+        } else return;
+      }
+      const dt = e.timeStamp - lastT;
+      if (dt > 0) velocity = velocity * 0.6 + ((t.clientY - lastY) / dt) * 0.4;
+      lastY = t.clientY; lastT = e.timeStamp;
+      e.preventDefault();
+      pane.style.transform = dy > 0 ? `translateY(${dy}px)` : `translateY(${dy * RUBBER}px)`;
+    }, { passive: false });
+
+    const endSwipe = () => {
+      if (!dragging) return;
+      dragging = false;
+      pane.style.willChange = '';
+      const dy = lastY - startY;
+      if (dy > DISMISS_THRESHOLD || (dy > 20 && velocity > VELOCITY_THRESHOLD)) {
+        // Slide fully off-screen, then minimise. Keep it translated down (don't
+        // reset) so it doesn't flash back before closePanel removes it.
+        pane.style.transition = 'transform 0.2s cubic-bezier(0.2, 0, 0.4, 1)';
+        pane.style.transform = 'translateY(100%)';
+        setTimeout(() => closePanel('down'), 200);
+      } else {
+        pane.style.transition = 'transform 0.25s cubic-bezier(0.2, 0.9, 0.3, 1.05)';
+        pane.style.transform = '';
+        setTimeout(() => { pane.style.transition = ''; }, 260);
+      }
+    };
+    el.addEventListener('touchend', endSwipe, { passive: true });
+    el.addEventListener('touchcancel', endSwipe, { passive: true });
+  }
+
+  function _smoothScrollToNoteCard(card) {
+    if (!card) return;
+    const scroller = card.closest('.notes-pane-body');
+    if (!scroller) {
+      try { card.scrollIntoView({ block: 'center', behavior: 'smooth' }); } catch (_) {}
+      return;
+    }
+    const scrollerRect = scroller.getBoundingClientRect();
+    const cardRect = card.getBoundingClientRect();
+    const delta = (cardRect.top - scrollerRect.top) - (scroller.clientHeight - cardRect.height) / 2;
+    scroller.scrollTo({ top: Math.max(0, scroller.scrollTop + delta), behavior: 'smooth' });
+  }
+
+  function disposeOwnedPortals() {
+    document.querySelectorAll('.note-reminder-menu, .note-corner-menu-dropdown, #notes-first-open-hint').forEach(dismissOrRemove);
+  }
+
+  return { _forceCloseNotesPanel, openPanel, closePanel, togglePanel, isPanelOpen, openNote, _smoothScrollToNoteCard };
+}
diff --git a/frontend/src/features/notes/ui/quickAdd.js b/frontend/src/features/notes/ui/quickAdd.js
new file mode 100644
index 000000000..3a723fcdc
--- /dev/null
+++ b/frontend/src/features/notes/ui/quickAdd.js
@@ -0,0 +1,170 @@
+/** Quick-add expansion, draft restoration and opening inline editors. */
+export function createQuickAdd({
+  _applyDraftToNote,
+  _applyMasonry,
+  _buildForm,
+  app,
+  openPanel,
+  state,
+  uiModule
+}) {
+  function _renderQuickAdd(body) {
+    const wrap = document.createElement('div');
+    wrap.className = 'notes-quick-add';
+    // 2-pill Note/Todo toggle mirrors the full form's type-seg (minus Draw :
+    // drawing happens in the expanded form). The pill that's active steers
+    // both the placeholder and the type the form opens in.
+    wrap.innerHTML = `
+    <div class="notes-quick-type-seg is-todo" role="group" aria-label="New item type">
+      <button type="button" class="notes-quick-type-pill" data-type="note" aria-label="Note" aria-pressed="false" title="Note">
+        <svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><line x1="4" y1="6" x2="20" y2="6"/><line x1="4" y1="12" x2="20" y2="12"/><line x1="4" y1="18" x2="14" y2="18"/></svg>
+      </button>
+      <button type="button" class="notes-quick-type-pill active" data-type="todo" aria-label="To-do" aria-pressed="true" title="To-do">
+        <svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><polyline points="9 11 12 14 22 4"/><path d="M21 12v7a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2h11"/></svg>
+      </button>
+    </div>
+    <input type="text" class="notes-quick-input" placeholder="Add a to-do…" />
+    <button class="notes-quick-icon" data-action="photo" title="Attach photo">
+      <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="3" y="3" width="18" height="18" rx="2"/><circle cx="8.5" cy="8.5" r="1.5"/><polyline points="21 15 16 10 5 21"/></svg>
+    </button>
+  `;
+    body.appendChild(wrap);
+
+    const input = wrap.querySelector('.notes-quick-input');
+    const seg = wrap.querySelector('.notes-quick-type-seg');
+    let currentType = 'todo';
+    const setType = (t) => {
+      if (t !== 'note' && t !== 'todo') return;
+      currentType = t;
+      seg.classList.toggle('is-todo', t === 'todo');
+      seg.classList.toggle('is-note', t === 'note');
+      seg.querySelectorAll('.notes-quick-type-pill').forEach(p => {
+        const on = p.dataset.type === t;
+        p.classList.toggle('active', on);
+        p.setAttribute('aria-pressed', on ? 'true' : 'false');
+      });
+      input.placeholder = t === 'note' ? 'Add a note…' : 'Add a to-do…';
+    };
+    seg.querySelectorAll('.notes-quick-type-pill').forEach(p => {
+      p.addEventListener('click', (e) => {
+        e.stopPropagation();
+        setType(p.dataset.type);
+      });
+    });
+    // Click input or type → expand to full form
+    const expandToForm = (initialType = 'note', initialText = '') => {
+      app.setEditingId('__new__');
+      const form = _buildForm({ note_type: initialType });
+      form.classList.add('note-form-new');
+      if (initialText) {
+        const titleEl = form.querySelector('.note-form-title');
+        if (titleEl) titleEl.value = initialText;
+      }
+      const mobileGrid = body.closest('.notes-pane')?.classList.contains('notes-view-grid')
+        && window.matchMedia('(max-width: 768px)').matches;
+      if (mobileGrid) {
+        form.style.gridColumn = '1 / -1';
+        form.style.gridRowEnd = 'span 64';
+      }
+      wrap.replaceWith(form);
+      _applyMasonry(body);
+      requestAnimationFrame(() => _applyMasonry(body));
+      const titleEl = form.querySelector('.note-form-title');
+      if (titleEl) {
+        titleEl.focus();
+        // Move caret to end
+        titleEl.setSelectionRange(titleEl.value.length, titleEl.value.length);
+      }
+    };
+    // Expand only on real intent: a click directly on the input, or actual
+    // typing. Focus alone : including focus stolen from a missed nearby
+    // click : no longer creates an empty form.
+    input.addEventListener('click', () => expandToForm(currentType, input.value));
+    input.addEventListener('input', () => expandToForm(currentType, input.value));
+    wrap.querySelector('[data-action="photo"]').addEventListener('click', (e) => {
+      e.stopPropagation();
+      expandToForm(currentType);
+      // Trigger photo input on the new form
+      setTimeout(() => document.querySelector('.note-form-photo-btn')?.click(), 50);
+    });
+  }
+
+  function _createNote(type = 'todo') {
+    const body = document.querySelector('#notes-pane .notes-pane-body');
+    if (!body || state.editingId === '__new__') return;
+    app.setEditingId('__new__');
+    // Restore an unsaved new-note draft if one survived a prior close/loss.
+    const { note: _n, restored } = _applyDraftToNote({ note_type: type }, '__new__');
+    const form = _buildForm(_n);
+    form.classList.add('note-form-new');
+    body.prepend(form);
+    const initialField = type === 'note'
+      ? form.querySelector('.note-form-content')
+      : form.querySelector('.note-cl-text, .note-form-title');
+    initialField?.focus();
+    if (restored) uiModule.showToast('Restored unsaved note');
+  }
+
+  function newNote() {
+    if (!state.open) openPanel();
+    requestAnimationFrame(() => _createNote('note'));
+  }
+
+  function _editNote(id) {
+    const note = state.notes.find(n => n.id === id);
+    if (!note) return;
+    app.setEditingId(id);
+    const card = document.querySelector(`.note-card[data-note-id="${id}"]`);
+    if (!card) return;
+    // Restore an unsaved draft (from a prior connection loss / close) over
+    // the saved note so the user picks up where they left off.
+    const { note: _n, restored } = _applyDraftToNote(note, id);
+    const form = _buildForm(_n);
+    card.replaceWith(form);
+    if (restored) uiModule.showToast('Restored unsaved changes');
+    // Pinned notes live in the first masonry column : the edit form has
+    // column-span:all, which can leave the form rendered above the fold or
+    // visually buried under neighboring pinned cards. Bring it into view
+    // (and onto a higher stacking context) so editing a pinned note always
+    // pops to the top.
+    form.style.position = 'relative';
+    form.style.zIndex = '5';
+    // Grid view: the form keeps the CSS default `grid-row-end: span 16` (64px)
+    // after replaceWith, which is much shorter than the actual form. Recompute
+    // masonry so the form gets the correct row span and cards below stop
+    // overlapping it. ResizeObserver inside _applyMasonry keeps it in sync as
+    // the user types / adds checklist items.
+    const _body = form.closest('.notes-pane-body');
+    if (_body) {
+      _applyMasonry(_body);
+      requestAnimationFrame(() => _applyMasonry(_body));
+    }
+    requestAnimationFrame(() => {
+      try { form.scrollIntoView({ block: 'center', behavior: 'smooth' }); }
+      catch { form.scrollIntoView(); }
+    });
+    // Pick the most useful field to focus. On phones especially, the user
+    // taps Edit to type : landing in the title when there's already a title
+    // (and likely a body to extend) loses momentum. Prefer the body textarea
+    // for plain notes, the first checklist item for todos, fall back to title.
+    const _focusBest = () => {
+      if (note.note_type === 'note' || !note.note_type) {
+        const ta = form.querySelector('.note-form-content');
+        if (ta) { ta.focus(); try { ta.setSelectionRange(ta.value.length, ta.value.length); } catch {} return; }
+      }
+      if (note.note_type === 'todo' || note.note_type === 'goal' || note.note_type === 'checklist') {
+        // Last non-empty checklist row, or the first row if all empty.
+        const rows = form.querySelectorAll('.note-cl-row .note-cl-text');
+        let target = null;
+        for (const inp of rows) { if ((inp.value || '').trim()) target = inp; }
+        target = target || rows[0];
+        if (target) { target.focus(); try { target.setSelectionRange(target.value.length, target.value.length); } catch {} return; }
+      }
+      const titleEl = form.querySelector('.note-form-title');
+      if (titleEl) titleEl.focus();
+    };
+    _focusBest();
+  }
+
+  return { _renderQuickAdd, _createNote, newNote, _editNote };
+}
diff --git a/frontend/src/features/notes/ui/reminderDisplay.js b/frontend/src/features/notes/ui/reminderDisplay.js
new file mode 100644
index 000000000..5f6507d46
--- /dev/null
+++ b/frontend/src/features/notes/ui/reminderDisplay.js
@@ -0,0 +1,129 @@
+/** Reminder badges, sticky card highlights and entry scrolling. */
+import { _isNoteFullyDone } from '../domain/noteRules.js';
+import { _hasTimeComponent } from '../domain/recurrence.js';
+export function createReminderDisplay({
+  _countFiredReminders,
+  _hasActiveReminder,
+  _loadActiveHighlights,
+  _loadGlowedReminders,
+  _loadPendingHighlights,
+  _saveActiveHighlights,
+  _saveGlowedReminders,
+  _savePendingHighlights,
+  _smoothScrollToNoteCard,
+  state
+}) {
+  function _clearViewedReminderGlows() {
+    const active = _loadActiveHighlights();
+    if (!active.size) return;
+    _saveActiveHighlights(new Set());
+    document.querySelectorAll('.note-card-reminder-fired-sticky').forEach(card => {
+      card.classList.remove('note-card-reminder-fired-sticky');
+    });
+  }
+
+  function _setReminderCardGlow(noteId, on = true) {
+    if (!noteId) return;
+    const active = _loadActiveHighlights();
+    if (on) active.add(noteId);
+    else active.delete(noteId);
+    _saveActiveHighlights(active);
+    document.querySelectorAll(`.note-card[data-note-id="${noteId}"]`).forEach(card => {
+      card.classList.toggle('note-card-reminder-fired-sticky', on);
+    });
+  }
+
+  function _queuePendingHighlight(noteId) {
+    const set = _loadPendingHighlights();
+    set.add(noteId);
+    _savePendingHighlights(set);
+  }
+
+  function _flushPendingHighlights() {
+    // Fresh firings (queued by the background loop while the panel was closed)
+    // glow unconditionally : a notification just told the user something
+    // happened, so we always point at the note even if it was glowed before.
+    const queued = _loadPendingHighlights();
+    const glowed = _loadGlowedReminders();
+    const toGlow = new Set(queued);
+    // For notes that are merely overdue at open time (no fresh firing event),
+    // only glow the ones we haven't already shown : otherwise reopening the
+    // panel keeps lighting up old reminders forever.
+    for (const n of state.notes) {
+      if (!_hasActiveReminder(n) || !_hasTimeComponent(n.due_date)) continue;
+      if (queued.has(n.id) || !glowed.has(n.id)) toGlow.add(n.id);
+    }
+    // Always consume the queue.
+    _savePendingHighlights(new Set());
+    if (!toGlow.size) return;
+    let firstCard = null;
+    for (const id of toGlow) {
+      const card = document.querySelector(`.note-card[data-note-id="${id}"]`);
+      if (!card) continue;
+      _setReminderCardGlow(id, true);
+      if (!firstCard) firstCard = card;
+      glowed.add(id);
+    }
+    _saveGlowedReminders(glowed);
+    // Bring the first one into view so it can't get buried below the fold.
+    if (firstCard) {
+      requestAnimationFrame(() => {
+        _smoothScrollToNoteCard(firstCard);
+      });
+    }
+  }
+
+  function _updateRailBadge() {
+    const fired = _countFiredReminders();
+    // Rail (mini sidebar) : only show the count when reminders have ACTUALLY
+    // fired since the last dismissal (i.e. you haven't opened notes yet).
+    // Showing every overdue note forever made the badge feel permanent.
+    const railBtn = document.getElementById('rail-notes');
+    if (railBtn) {
+      let badge = railBtn.querySelector('.rail-notes-badge');
+      if (fired > 0) {
+        if (!badge) {
+          badge = document.createElement('span');
+          badge.className = 'rail-notes-badge';
+          railBtn.appendChild(badge);
+        }
+        badge.textContent = fired > 99 ? '99+' : String(fired);
+        badge.classList.add('fired');
+      } else if (badge) {
+        badge.remove();
+      }
+    }
+    // Main sidebar button
+    const sidebarBtn = document.getElementById('tool-notes-btn');
+    if (sidebarBtn) {
+      let dot = sidebarBtn.querySelector('.tool-notes-dot');
+      if (fired > 0) {
+        if (!dot) {
+          dot = document.createElement('span');
+          dot.className = 'tool-notes-dot';
+          const newNoteBtn = sidebarBtn.querySelector('#notes-new-note-btn');
+          sidebarBtn.insertBefore(dot, newNoteBtn || null);
+        }
+      } else if (dot) {
+        dot.remove();
+      }
+    }
+    // Individual note cards : pulse ones with fired reminders
+    document.querySelectorAll('.note-card').forEach(card => {
+      const id = card.dataset.noteId;
+      const note = state.notes.find(n => n.id === id);
+      if (!note || note.archived || _isNoteFullyDone(note)) {
+        card.classList.remove('note-card-reminder-due');
+        return;
+      }
+      if (note.due_date && _hasTimeComponent(note.due_date)) {
+        const t = new Date(note.due_date).getTime();
+        card.classList.toggle('note-card-reminder-due', !isNaN(t) && t <= Date.now());
+      } else {
+        card.classList.remove('note-card-reminder-due');
+      }
+    });
+  }
+
+  return { _clearViewedReminderGlows, _setReminderCardGlow, _queuePendingHighlight, _flushPendingHighlights, _updateRailBadge };
+}
diff --git a/frontend/src/features/notes/ui/reminderPicker.js b/frontend/src/features/notes/ui/reminderPicker.js
new file mode 100644
index 000000000..da9d00398
--- /dev/null
+++ b/frontend/src/features/notes/ui/reminderPicker.js
@@ -0,0 +1,335 @@
+/** Reminder date presets and recurrence picker interactions. */
+import { _formatRepeatLabel, _toLocalDatetimeStr, _normalizeRepeat, _DAYS, _ORDINALS } from '../domain/recurrence.js';
+export function createReminderPicker({
+  lifecycle,
+  _ensureNotificationPermission,
+  _esc,
+  _formatReminderTag,
+  _laterTodayDate,
+  _nextWeekDate,
+  _snapToRepeat,
+  _tomorrowDate,
+  bindMenuDismiss,
+  dismissOrRemove
+}) {
+  function _wireReminderPicker(form) {
+    // Reminder bell : opens dropdown menu
+    const remindBtn = form.querySelector('.note-form-remind-btn');
+    const dueInput = form.querySelector('.note-form-due');
+    const repeatInput = form.querySelector('.note-form-repeat');
+    const tagsEl = form.querySelector('.note-form-reminder-tags');
+
+    function _renderReminderTag() {
+      if (!tagsEl) return;
+      const v = dueInput.value;
+      const rep = repeatInput.value || 'none';
+      if (!v) { tagsEl.innerHTML = ''; return; }
+      const label = _formatReminderTag(v);
+      const repLabel = rep !== 'none' ? ` · ${_formatRepeatLabel(rep, new Date(v))}` : '';
+      tagsEl.innerHTML = `<button class="note-reminder-tag" type="button" title="Edit reminder">
+      <svg width="11" height="11" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round"><path d="M18 8A6 6 0 0 0 6 8c0 7-3 9-3 9h18s-3-2-3-9"/><path d="M13.73 21a2 2 0 0 1-3.46 0"/></svg>
+      <span>${_esc(label)}${_esc(repLabel)}</span>
+      <span class="note-reminder-tag-x" title="Remove">×</span>
+    </button>`;
+      tagsEl.querySelector('.note-reminder-tag').addEventListener('click', (e) => {
+        if (e.target.classList.contains('note-reminder-tag-x')) {
+          dueInput.value = '';
+          repeatInput.value = 'none';
+          _renderReminderTag();
+          return;
+        }
+        _openReminderMenu(remindBtn || tagsEl, true);
+      });
+    }
+
+    function _openReminderMenu(anchor, isEdit = false) {
+      // Close any existing menu
+      document.querySelectorAll('.note-reminder-menu').forEach(m => m.remove());
+      const menu = document.createElement('div');
+      menu.className = 'note-reminder-menu';
+      document.body.appendChild(menu);
+
+      const presetItems = [
+        { label: 'Later today', sub: _laterTodayDate().toLocaleTimeString([], { hour: 'numeric', minute: '2-digit' }), action: () => _setReminder(_toLocalDatetimeStr(_laterTodayDate())) },
+        { label: 'Tomorrow', sub: _tomorrowDate().toLocaleTimeString([], { hour: 'numeric', minute: '2-digit' }), action: () => _setReminder(_toLocalDatetimeStr(_tomorrowDate())) },
+        { label: 'Next week', sub: _nextWeekDate().toLocaleDateString([], { weekday: 'short' }) + ' ' + _nextWeekDate().toLocaleTimeString([], { hour: 'numeric', minute: '2-digit' }), action: () => _setReminder(_toLocalDatetimeStr(_nextWeekDate())) },
+        { label: 'Select date and time', sub: '', action: () => _pickCustomDate() },
+      ];
+
+      // Sub-page state for the repeat picker. null = top page.
+      // 'weekly' | 'monthly' | 'monthly_nth'
+      let subMode = null;
+      // Temporary state for monthly_nth so user can click N then weekday (or vice versa)
+      // before committing.
+      let nthDraft = { n: 0, w: -1 };
+
+      const DAY_SHORT = ['S', 'M', 'T', 'W', 'T', 'F', 'S'];
+
+      function getNorm() {
+        if (!dueInput.value) return 'none';
+        return _normalizeRepeat(repeatInput.value || 'none', new Date(dueInput.value));
+      }
+
+      function commit(val) {
+        repeatInput.value = val;
+        _renderReminderTag();
+        menu.remove();
+      }
+
+      // Like commit, but first snaps dueInput.value forward to the next matching
+      // slot for the chosen recurrence. Use for weekly/monthly variants where the
+      // current due date may not match the chosen pattern (e.g. user picks
+      // "weekly on Mondays" while the date is a Wednesday).
+      function snapAndCommit(val) {
+        if (dueInput.value) {
+          const cur = new Date(dueInput.value);
+          const norm = _normalizeRepeat(val, cur);
+          const snapped = _snapToRepeat(cur, norm);
+          if (snapped) {
+            dueInput.value = _toLocalDatetimeStr(snapped);
+            if (remindBtn) remindBtn.classList.add('has-date');
+          }
+        }
+        commit(val);
+      }
+
+      function reposition() {
+        const rect = anchor.getBoundingClientRect();
+        const vw = window.innerWidth;
+        const vh = window.innerHeight;
+        const mw = menu.offsetWidth || 220;
+        const mh = menu.offsetHeight || 280;
+        let top = rect.bottom + 4;
+        let left = rect.left;
+        if (top + mh > vh - 8) top = Math.max(8, rect.top - mh - 4);
+        if (left + mw > vw - 8) left = Math.max(8, vw - mw - 8);
+        if (left < 8) left = 8;
+        menu.style.top = top + 'px';
+        menu.style.left = left + 'px';
+      }
+
+      function render() {
+        let html = '';
+
+        if (subMode === null) {
+          html += '<div class="note-reminder-menu-title">Remind me later</div>';
+          for (let i = 0; i < presetItems.length; i++) {
+            const it = presetItems[i];
+            html += `<button class="note-reminder-menu-item" data-action="preset" data-i="${i}"><span>${it.label}</span><span class="note-reminder-menu-sub">${it.sub}</span></button>`;
+          }
+          if (isEdit && dueInput.value) {
+            const norm = getNorm();
+            html += '<div class="note-reminder-menu-divider"></div>';
+            html += '<div class="note-reminder-menu-title">Repeat</div>';
+            // None
+            html += `<button class="note-reminder-menu-item${norm === 'none' ? ' active' : ''}" data-action="set" data-val="none"><span>Doesn't repeat</span>${norm === 'none' ? '<span class="note-reminder-menu-check">✓</span>' : ''}</button>`;
+            // Daily
+            html += `<button class="note-reminder-menu-item${norm === 'daily' ? ' active' : ''}" data-action="set" data-val="daily"><span>Daily</span>${norm === 'daily' ? '<span class="note-reminder-menu-check">✓</span>' : ''}</button>`;
+            // Weekly →
+            {
+              const isW = norm.startsWith('weekly:');
+              const wd = isW ? parseInt(norm.split(':')[1], 10) : null;
+              const sub = isW && !isNaN(wd) ? `<span class="note-reminder-menu-sub">${_DAYS[wd]}</span>` : '';
+              html += `<button class="note-reminder-menu-item${isW ? ' active' : ''}" data-action="sub" data-sub="weekly"><span>Weekly</span>${sub}<span class="note-reminder-menu-arrow">›</span></button>`;
+            }
+            // Monthly →
+            {
+              const isM = norm.startsWith('monthly:');
+              const sub = isM ? `<span class="note-reminder-menu-sub">${_monthlyShortDescriptor(norm)}</span>` : '';
+              html += `<button class="note-reminder-menu-item${isM ? ' active' : ''}" data-action="sub" data-sub="monthly"><span>Monthly</span>${sub}<span class="note-reminder-menu-arrow">›</span></button>`;
+            }
+            // Yearly
+            html += `<button class="note-reminder-menu-item${norm === 'yearly' ? ' active' : ''}" data-action="set" data-val="yearly"><span>Yearly</span>${norm === 'yearly' ? '<span class="note-reminder-menu-check">✓</span>' : ''}</button>`;
+          }
+        } else if (subMode === 'weekly') {
+          const norm = getNorm();
+          const curWd = norm.startsWith('weekly:') ? parseInt(norm.split(':')[1], 10) : -1;
+          html += `<button class="note-reminder-menu-back" data-action="back"><span class="note-reminder-menu-arrow-back">‹</span> Repeat</button>`;
+          html += '<div class="note-reminder-menu-title">Weekly on…</div>';
+          html += '<div class="note-reminder-weekday-row">';
+          for (let i = 0; i < 7; i++) {
+            html += `<button class="note-reminder-day-chip${curWd === i ? ' active' : ''}" data-action="weekly-pick" data-wd="${i}" title="${_DAYS[i]}">${DAY_SHORT[i]}</button>`;
+          }
+          html += '</div>';
+        } else if (subMode === 'monthly') {
+          const norm = getNorm();
+          const dueDate = new Date(dueInput.value);
+          const dayN = dueDate.getDate();
+          html += `<button class="note-reminder-menu-back" data-action="back"><span class="note-reminder-menu-arrow-back">‹</span> Repeat</button>`;
+          html += '<div class="note-reminder-menu-title">Monthly on…</div>';
+          // Day N : uses the chosen date's day. Always offered.
+          const dayVal = `monthly:day:${dayN}`;
+          html += `<button class="note-reminder-menu-item${norm === dayVal ? ' active' : ''}" data-action="set" data-val="${dayVal}"><span>Day ${dayN} every month</span>${norm === dayVal ? '<span class="note-reminder-menu-check">✓</span>' : ''}</button>`;
+          // Nth weekday →
+          {
+            const isNth = norm.startsWith('monthly:nth:');
+            const sub = isNth ? `<span class="note-reminder-menu-sub">${_monthlyShortDescriptor(norm)}</span>` : '';
+            html += `<button class="note-reminder-menu-item${isNth ? ' active' : ''}" data-action="sub" data-sub="monthly_nth"><span>Nth weekday</span>${sub}<span class="note-reminder-menu-arrow">›</span></button>`;
+          }
+        } else if (subMode === 'monthly_nth') {
+          // Pick ordinal (1..4) and weekday (0..6); commit when both chosen.
+          html += `<button class="note-reminder-menu-back" data-action="back-monthly"><span class="note-reminder-menu-arrow-back">‹</span> Monthly</button>`;
+          html += '<div class="note-reminder-menu-title">Nth weekday of month</div>';
+          html += '<div class="note-reminder-menu-sublabel">Which one</div>';
+          html += '<div class="note-reminder-weekday-row">';
+          for (let i = 1; i <= 4; i++) {
+            html += `<button class="note-reminder-day-chip wide${nthDraft.n === i ? ' active' : ''}" data-action="nth-n" data-n="${i}">${_ORDINALS[i - 1]}</button>`;
+          }
+          html += '</div>';
+          html += '<div class="note-reminder-menu-sublabel">Weekday</div>';
+          html += '<div class="note-reminder-weekday-row">';
+          for (let i = 0; i < 7; i++) {
+            html += `<button class="note-reminder-day-chip${nthDraft.w === i ? ' active' : ''}" data-action="nth-w" data-wd="${i}" title="${_DAYS[i]}">${DAY_SHORT[i]}</button>`;
+          }
+          html += '</div>';
+          html += '<div class="note-reminder-menu-divider"></div>';
+          const ready = nthDraft.n > 0 && nthDraft.w >= 0;
+          const lbl = ready ? `Save: ${_ORDINALS[nthDraft.n - 1]} ${_DAYS[nthDraft.w]}` : 'Pick week and weekday';
+          html += `<button class="note-reminder-menu-item note-reminder-menu-confirm${ready ? '' : ' disabled'}" data-action="nth-save" ${ready ? '' : 'disabled'}><span>${lbl}</span></button>`;
+        }
+
+        menu.innerHTML = html;
+        reposition();
+        wire();
+      }
+
+      function wire() {
+        menu.querySelectorAll('[data-action]').forEach(el => {
+          el.addEventListener('click', (e) => {
+            e.stopPropagation();
+            const a = el.dataset.action;
+            if (a === 'preset') {
+              const it = presetItems[parseInt(el.dataset.i, 10)];
+              it.action();
+              menu.remove();
+            } else if (a === 'set') {
+              snapAndCommit(el.dataset.val);
+            } else if (a === 'sub') {
+              subMode = el.dataset.sub;
+              // Seed nth draft from saved value only on first entry : preserve
+              // in-progress picks across back-trips (Nth → back → Nth again).
+              if (subMode === 'monthly_nth' && nthDraft.n === 0 && nthDraft.w === -1) {
+                const norm = getNorm();
+                const m = norm.match(/^monthly:nth:(\d):(\d)$/);
+                if (m) nthDraft = { n: parseInt(m[1], 10), w: parseInt(m[2], 10) };
+              }
+              render();
+            } else if (a === 'back') {
+              subMode = null;
+              render();
+            } else if (a === 'back-monthly') {
+              subMode = 'monthly';
+              render();
+            } else if (a === 'weekly-pick') {
+              snapAndCommit(`weekly:${el.dataset.wd}`);
+            } else if (a === 'nth-n') {
+              nthDraft.n = parseInt(el.dataset.n, 10);
+              render();
+            } else if (a === 'nth-w') {
+              nthDraft.w = parseInt(el.dataset.wd, 10);
+              render();
+            } else if (a === 'nth-save') {
+              if (nthDraft.n > 0 && nthDraft.w >= 0) {
+                snapAndCommit(`monthly:nth:${nthDraft.n}:${nthDraft.w}`);
+              }
+            }
+          });
+        });
+      }
+
+      render();
+      // Click outside to close (single global handler attached after first paint)
+      setTimeout(() => {
+        const close = (e) => {
+          if (!menu.isConnected) { document.removeEventListener('click', close); return; }
+          if (!menu.contains(e.target)) { menu.remove(); document.removeEventListener('click', close); }
+        };
+        if (menu.isConnected) lifecycle.listen(menu, document, 'click', close);
+      }, 0);
+    }
+
+    function _monthlyShortDescriptor(norm) {
+      const parts = norm.split(':');
+      if (parts[1] === 'day') return `Day ${parts[2]}`;
+      if (parts[1] === 'nth') {
+        const n = parseInt(parts[2], 10);
+        const wd = parseInt(parts[3], 10);
+        return `${_ORDINALS[n - 1] || `${n}th`} ${_DAYS[wd].slice(0, 3)}`;
+      }
+      if (parts[1] === 'last') {
+        const wd = parseInt(parts[2], 10);
+        return `Last ${_DAYS[wd].slice(0, 3)}`;
+      }
+      return '';
+    }
+
+    function _setReminder(datetimeLocalStr) {
+      dueInput.value = datetimeLocalStr;
+      if (remindBtn) {
+        remindBtn.classList.add('has-date');
+        // Jingle the bell. CSS handles the animation; remove + reflow + re-add
+        // so it replays every time the user sets/changes a reminder.
+        const _bell = remindBtn.querySelector('svg');
+        if (_bell) {
+          _bell.classList.remove('jingling');
+          void _bell.offsetWidth;
+          _bell.classList.add('jingling');
+          setTimeout(() => _bell.classList.remove('jingling'), 700);
+        }
+      }
+      _renderReminderTag();
+      _ensureNotificationPermission();
+    }
+
+    function _pickCustomDate() {
+      // Replace the dropdown menu with a small inline picker
+      document.querySelectorAll('.note-reminder-menu').forEach(dismissOrRemove);
+      const menu = document.createElement('div');
+      menu.className = 'note-reminder-menu';
+      const initial = dueInput.value || _toLocalDatetimeStr(_tomorrowDate());
+      menu.innerHTML = `
+      <div class="note-reminder-menu-title">Pick date and time</div>
+      <div class="note-reminder-menu-picker">
+        <input type="datetime-local" class="note-reminder-date-input" />
+      </div>
+      <div class="note-reminder-menu-divider"></div>
+      <button class="note-reminder-menu-item note-reminder-menu-confirm">
+        <span>Save</span>
+      </button>
+    `;
+      document.body.appendChild(menu);
+      // Position next to the bell button
+      const anchor = remindBtn || form.querySelector('.note-form-reminder-tags');
+      const rect = anchor.getBoundingClientRect();
+      const vw = window.innerWidth;
+      const vh = window.innerHeight;
+      const mw = menu.offsetWidth || 240;
+      const mh = menu.offsetHeight || 200;
+      let top = rect.bottom + 4;
+      let left = rect.left;
+      if (top + mh > vh - 8) top = Math.max(8, rect.top - mh - 4);
+      if (left + mw > vw - 8) left = Math.max(8, vw - mw - 8);
+      if (left < 8) left = 8;
+      menu.style.top = top + 'px';
+      menu.style.left = left + 'px';
+      const dInput = menu.querySelector('.note-reminder-date-input');
+      dInput.value = initial;
+      dInput.focus();
+      if (typeof dInput.showPicker === 'function') {
+        try { dInput.showPicker(); } catch {}
+      }
+      const close = bindMenuDismiss(menu, () => { menu.remove(); });
+      menu.querySelector('.note-reminder-menu-confirm').addEventListener('click', () => {
+        if (dInput.value) _setReminder(dInput.value);
+        close();
+      });
+    }
+
+    if (remindBtn) remindBtn.addEventListener('click', (e) => { e.stopPropagation(); _openReminderMenu(remindBtn, !!dueInput.value); });
+    _renderReminderTag();
+
+
+  }
+
+  return { _wireReminderPicker };
+}
diff --git a/frontend/src/features/notes/ui/selection.js b/frontend/src/features/notes/ui/selection.js
new file mode 100644
index 000000000..e64549dff
--- /dev/null
+++ b/frontend/src/features/notes/ui/selection.js
@@ -0,0 +1,61 @@
+/** Selection controls and view feedback for accepted attachments. */
+export function createSelection({
+  operations,
+  _renderNotes,
+  app,
+  state
+}) {
+  function _enterSelectMode(initialId = null) {
+    app.setSelectMode(true);
+    app.clearSelection();
+    if (initialId) app.selectId(initialId);
+    const bar = document.getElementById('notes-bulk-bar');
+    const btn = document.getElementById('notes-select-btn');
+    if (bar) bar.classList.remove('hidden');
+    if (btn) { btn.classList.add('active'); btn.textContent = 'Cancel'; }
+    _renderNotes();
+    _updateBulkBar();
+  }
+
+  function _exitSelectMode() {
+    app.setSelectMode(false);
+    app.clearSelection();
+    const bar = document.getElementById('notes-bulk-bar');
+    const btn = document.getElementById('notes-select-btn');
+    const all = document.getElementById('notes-select-all');
+    if (bar) bar.classList.add('hidden');
+    if (btn) { btn.classList.remove('active'); btn.textContent = 'Select'; }
+    if (all) all.checked = false;
+    _renderNotes();
+  }
+
+  function _updateBulkBar() {
+    const count = state.selectedIds.size;
+    const countEl = document.getElementById('notes-selected-count');
+    const sendAgentBtn = document.getElementById('notes-send-agent');
+    const archiveBtn = document.getElementById('notes-bulk-archive');
+    const deleteBtn = document.getElementById('notes-bulk-delete');
+    const allEl = document.getElementById('notes-select-all');
+    if (countEl) countEl.textContent = `${count} Selected`;
+    if (sendAgentBtn) sendAgentBtn.disabled = count === 0;
+    if (archiveBtn) archiveBtn.disabled = count === 0;
+    if (deleteBtn) deleteBtn.disabled = count === 0;
+    if (allEl) allEl.checked = state.notes.length > 0 && state.notes.every(n => state.selectedIds.has(n.id));
+    // Toggle select-mode class so todo dots don't react to hover
+    const pane = document.getElementById('notes-pane');
+    if (pane) pane.classList.toggle('notes-select-mode', count > 0);
+  }
+
+  function wireSelectionActions() {
+    document.getElementById('notes-select-all').addEventListener('change', e => {
+      if (e.target.checked) state.notes.forEach(n => app.selectId(n.id));
+      else app.clearSelection();
+      _renderNotes(); _updateBulkBar();
+    });
+    document.getElementById('notes-send-agent').addEventListener('click', operations.attachSelected);
+    document.getElementById('notes-bulk-archive').addEventListener('click', operations.archiveSelected);
+    document.getElementById('notes-bulk-delete').addEventListener('click', operations.deleteSelected);
+    document.getElementById('notes-bulk-cancel').addEventListener('click', _exitSelectMode);
+  }
+  return { wireSelectionActions, _enterSelectMode, _exitSelectMode, _updateBulkBar };
+}
diff --git a/frontend/src/features/notes/ui/text.js b/frontend/src/features/notes/ui/text.js
new file mode 100644
index 000000000..75ecbaf78
--- /dev/null
+++ b/frontend/src/features/notes/ui/text.js
@@ -0,0 +1,39 @@
+/** Escaping, safe image sources and link rendering. */
+export function createText({
+  uiModule
+}) {
+  function _esc(s) { return uiModule.esc ? uiModule.esc(s || '') : (s || '').replace(/</g, '&lt;').replace(/>/g, '&gt;'); }
+
+  function _attrEsc(s) {
+    return String(s || '')
+      .replace(/"/g, '&quot;')
+      .replace(/'/g, '&#39;')
+      .replace(/</g, '&lt;')
+      .replace(/>/g, '&gt;')
+      .replace(/`/g, '&#96;');
+  }
+
+  function _safeImgSrc(s) {
+    const v = (s || '').trim();
+    if (!v) return '';
+    if (v.startsWith('/') || v.startsWith('./') || v.startsWith('../')) return v;
+    if (/^https?:\/\//i.test(v) || /^data:image\/(?:png|jpe?g|gif|webp);base64,/i.test(v)) return v;
+    return '';
+  }
+
+  function _linkify(s) {
+    const escaped = _esc(s);
+    const urlRe = /\b((?:https?:\/\/|www\.)[^\s<>"']+[^\s<>"'.,;:!?\]])/g;
+    return escaped.replace(urlRe, (m) => {
+      let url = m;
+      // Trim a trailing ')' that doesn't have a matching '(' inside the URL
+      if (url.endsWith(')') && (url.match(/\(/g) || []).length < (url.match(/\)/g) || []).length) {
+        url = url.slice(0, -1);
+      }
+      const href = url.startsWith('www.') ? `https://${url}` : url;
+      return `<a href="${_attrEsc(href)}" class="note-link" target="_blank" rel="noopener noreferrer" onclick="event.stopPropagation()">${url}</a>` + (url !== m ? m.slice(url.length) : '');
+    });
+  }
+
+  return { _esc, _attrEsc, _safeImgSrc, _linkify };
+}
diff --git a/frontend/src/features/notes/ui/toolbar.js b/frontend/src/features/notes/ui/toolbar.js
new file mode 100644
index 000000000..3c3c9fe58
--- /dev/null
+++ b/frontend/src/features/notes/ui/toolbar.js
@@ -0,0 +1,78 @@
+/** Panel search, archive and list/grid controls. */
+export function createToolbar({
+  app,
+  state,
+  persistence,
+  _renderNotes,
+  _fetchNotes,
+  _applyMasonry
+}) {
+  function wireToolbar(pane) {
+    // Search
+    const searchEl = document.getElementById('notes-search');
+    if (searchEl) {
+      searchEl.addEventListener('input', () => {
+        app.setSearchQuery(searchEl.value.trim().toLowerCase());
+        _renderNotes();
+      });
+    }
+
+    // View toggle
+    const archiveBtn = document.getElementById('notes-archive-toggle');
+    if (archiveBtn) {
+      const ARCHIVE_ICON = '<svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="2" y="3" width="20" height="5" rx="1"/><path d="M4 8v11a2 2 0 002 2h12a2 2 0 002-2V8"/><path d="M10 12h4"/></svg><span class="notes-header-btn-label">Archive</span>';
+      const CLOSE_ICON   = '<svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.4" stroke-linecap="round" stroke-linejoin="round"><line x1="6" y1="6" x2="18" y2="18"/><line x1="18" y1="6" x2="6" y2="18"/></svg><span class="notes-header-btn-label">Archive</span>';
+      const syncArchiveBtn = () => {
+        archiveBtn.classList.toggle('active', state.showingArchived);
+        archiveBtn.title = state.showingArchived ? 'Exit archive' : 'View archive';
+        archiveBtn.style.opacity = state.showingArchived ? '1' : '0.8';
+        // Swap to an X while in archive view so it doubles as a close-back-
+        // to-active-notes toggle.
+        archiveBtn.innerHTML = state.showingArchived ? CLOSE_ICON : ARCHIVE_ICON;
+        // Tint the whole pane so it's obvious you're not in the active list.
+        pane.classList.toggle('notes-pane-archive', state.showingArchived);
+      };
+      syncArchiveBtn();
+      archiveBtn.addEventListener('click', async () => {
+        app.setShowingArchived(!state.showingArchived);
+        app.clearSelection();
+        syncArchiveBtn();
+        // Brief fade so the body content swap doesn't snap : the bg-tint
+        // change is already eased by CSS transitions on .notes-pane*.
+        const _bodyEl = document.querySelector('#notes-pane .notes-pane-body');
+        if (_bodyEl) {
+          _bodyEl.style.transition = 'opacity 0.18s ease';
+          _bodyEl.style.opacity = '0.25';
+        }
+        await _fetchNotes();
+        _renderNotes();
+        if (_bodyEl) {
+          requestAnimationFrame(() => {
+            _bodyEl.style.opacity = '';
+            _bodyEl.addEventListener('transitionend', () => { _bodyEl.style.transition = ''; }, { once: true });
+          });
+        }
+      });
+    }
+    const viewBtn = document.getElementById('notes-view-toggle');
+    if (viewBtn) {
+      pane.classList.toggle('notes-view-grid', state.viewMode === 'grid');
+      // Label shows what you'll switch TO : "Grid" while in list, "List" while in grid.
+      const _setViewLabel = () => {
+        const lbl = viewBtn.querySelector('.notes-header-btn-label');
+        if (lbl) lbl.textContent = state.viewMode === 'grid' ? 'List' : 'Grid';
+      };
+      _setViewLabel();
+      requestAnimationFrame(() => _applyMasonry(document.querySelector('#notes-pane .notes-pane-body')));
+      viewBtn.addEventListener('click', () => {
+        app.setViewMode(state.viewMode === 'grid' ? 'list' : 'grid');
+        try { persistence.setItem('odysseus-notes-view', state.viewMode); } catch {}
+        pane.classList.toggle('notes-view-grid', state.viewMode === 'grid');
+        _setViewLabel();
+        requestAnimationFrame(() => _applyMasonry(document.querySelector('#notes-pane .notes-pane-body')));
+      });
+    }
+
+  }
+  return { wireToolbar };
+}
diff --git a/frontend/src/features/notes/ui/windowLayout.js b/frontend/src/features/notes/ui/windowLayout.js
new file mode 100644
index 000000000..9e9173a47
--- /dev/null
+++ b/frontend/src/features/notes/ui/windowLayout.js
@@ -0,0 +1,114 @@
+/** Shared-window integration: safe fullscreen bounds, docking and stacking. */
+export function createWindowLayout({
+  makeWindowDraggable,
+  snapModalToZone,
+  clearDockSide,
+  applyEdgeDock,
+  topToolWindowZ
+}) {
+  function _notesFullscreenSafeRect() {
+    const vw = window.innerWidth || document.documentElement.clientWidth || 0;
+    const vh = window.innerHeight || document.documentElement.clientHeight || 0;
+    let left = 0;
+    let right = vw;
+
+    const sidebar = document.getElementById('sidebar');
+    const rail = document.getElementById('icon-rail');
+    const hamburgerRight = document.body.classList.contains('hamburger-right')
+      || sidebar?.classList.contains('right-side')
+      || rail?.classList.contains('right-side');
+
+    const reserve = (el) => {
+      if (!el || getComputedStyle(el).display === 'none') return;
+      const rect = el.getBoundingClientRect();
+      if (rect.width <= 0 || rect.height <= 0) return;
+      if (hamburgerRight) right = Math.min(right, rect.left);
+      else left = Math.max(left, rect.right);
+    };
+
+    if (sidebar && !sidebar.classList.contains('hidden')) reserve(sidebar);
+    reserve(rail);
+
+    // The fixed hamburger can remain visible even when the rail/sidebar is
+    // collapsed. Reserve its strip too so fullscreen Notes does not sit beneath it.
+    const hamburger = document.getElementById('hamburger-btn');
+    if (hamburger && getComputedStyle(hamburger).display !== 'none') {
+      const rect = hamburger.getBoundingClientRect();
+      const pad = 8;
+      if (hamburgerRight) right = Math.min(right, rect.left - pad);
+      else left = Math.max(left, rect.right + pad);
+    }
+
+    left = Math.max(0, Math.min(left, vw - 80));
+    right = Math.max(left + 80, Math.min(right, vw));
+    return { left, top: 0, width: right - left, height: vh };
+  }
+
+  function _wireNotesWindow(pane) {
+    if (!pane || pane.dataset.windowDragWired === '1') return;
+    const header = pane.querySelector('.notes-pane-header');
+    if (!header) return;
+    pane.dataset.windowDragWired = '1';
+    makeWindowDraggable(pane, {
+      content: pane,
+      header,
+      fsClass: 'notes-window-fullscreen',
+      skipSelector: 'button, input, select, textarea, label, .notes-mobile-grabber',
+      enableDock: true,
+      enableLeftDock: true,
+      onEnterFullscreen: () => {
+        pane.classList.add('notes-window-fullscreen');
+        snapModalToZone(pane, {
+          name: 'fullscreen',
+          rect: _notesFullscreenSafeRect(),
+        });
+      },
+      onExitFullscreen: () => {
+        _restoreNotesSidebarDock(pane);
+      },
+    });
+  }
+
+  function _clearNotesSnapStyles(pane) {
+    if (!pane) return;
+    const hadLeft = pane.classList.contains('modal-left-docked');
+    const hadRight = pane.classList.contains('modal-right-docked');
+    pane.classList.remove('notes-window-fullscreen', 'modal-left-docked', 'modal-right-docked');
+    if (hadLeft) clearDockSide('left', pane);
+    if (hadRight) clearDockSide('right', pane);
+    ['position', 'left', 'top', 'right', 'bottom', 'width', 'max-width', 'height',
+      'max-height', 'margin', 'transform', 'border-radius']
+      .forEach((prop) => pane.style.removeProperty(prop));
+    delete pane.dataset._tilePreSnap;
+    delete pane.dataset._tileZone;
+    delete pane._preDockSnapshot;
+    delete pane._dockSide;
+    delete pane._dockSuspended;
+  }
+
+  function _restoreNotesSidebarDock(pane) {
+    if (!pane || window.innerWidth <= 768) return;
+    _clearNotesSnapStyles(pane);
+    if (!pane.isConnected) return;
+    applyEdgeDock(pane, 'right');
+  }
+
+  function _topToolWindowZ(exclude = null) {
+    return topToolWindowZ({ exclude });
+  }
+
+  function _bringNotesToFront(pane = document.getElementById('notes-pane')) {
+    if (!pane) return;
+    const backdrop = document.getElementById('notes-pane-backdrop') || pane.parentElement;
+    const z = _topToolWindowZ(backdrop) + 1;
+    if (backdrop) backdrop.style.setProperty('z-index', String(z), 'important');
+    try {
+      window.dispatchEvent(new CustomEvent('odysseus:modal-opened', {
+        detail: { id: 'notes-panel', modal: pane },
+      }));
+    } catch (_) {}
+  }
+
+
+  return { _wireNotesWindow, _restoreNotesSidebarDock, _bringNotesToFront };
+}
diff --git a/frontend/src/shared/ui/confetti.js b/frontend/src/shared/ui/confetti.js
new file mode 100644
index 000000000..205f9acdc
--- /dev/null
+++ b/frontend/src/shared/ui/confetti.js
@@ -0,0 +1,28 @@
+/** Stateless celebration renderer shared by Notes and Compare. */
+export function spawnConfetti(cx, cy, count) {
+  const colors = ['#ffd700', '#ff6b6b', '#5b8def', '#51cf66', '#ff922b', '#cc5de8', '#22b8cf', '#fff'];
+  for (let i = 0; i < count; i++) {
+    const el = document.createElement('div');
+    el.className = 'confetti-piece';
+    const color = colors[Math.floor(Math.random() * colors.length)];
+    const size = 5 + Math.random() * 8;
+    const isCircle = Math.random() > 0.5;
+    el.style.width = size + 'px';
+    el.style.height = (isCircle ? size : size * 0.6) + 'px';
+    el.style.background = color;
+    el.style.borderRadius = isCircle ? '50%' : '2px';
+    el.style.left = cx + 'px';
+    el.style.top = cy + 'px';
+    const angle = Math.random() * Math.PI * 2;
+    const speed = 60 + Math.random() * 160;
+    const dx = Math.cos(angle) * speed;
+    const dy = Math.sin(angle) * speed - 100;
+    const duration = 1.0 + Math.random() * 1.0;
+    el.animate([
+      { transform: 'translate(0, 0) rotate(0deg) scale(1)', opacity: 1 },
+      { transform: `translate(${dx}px, ${dy + 200}px) rotate(${400 + Math.random() * 400}deg) scale(0)`, opacity: 0 }
+    ], { duration: duration * 1000, easing: 'cubic-bezier(0.15, 0.6, 0.35, 1)', fill: 'forwards' });
+    document.body.appendChild(el);
+    setTimeout(() => el.remove(), duration * 1000 + 50);
+  }
+}
diff --git a/scripts/verify_frontend_runtime.py b/scripts/verify_frontend_runtime.py
index 07b0bb3dd..2a960c32a 100644
--- a/scripts/verify_frontend_runtime.py
+++ b/scripts/verify_frontend_runtime.py
@@ -1,6 +1,7 @@
 #!/usr/bin/env python3
 """Verify the current Python runtime from an isolated distribution without frontend tooling."""
 import os
+import json
 from pathlib import Path
 import shutil
 import socket
@@ -13,12 +14,20 @@ ROOT = Path(__file__).resolve().parents[1]
 PROBE = """
 from pathlib import Path
 import shutil
+import json
+import sys
 from starlette.testclient import TestClient
 from app import app
 assert not Path('frontend').exists()
 assert not Path('node_modules').exists()
 assert shutil.which('node') is None
 with TestClient(app) as client:
+    for output in json.loads(sys.argv[1]):
+        asset = client.get('/static/' + output)
+        assert asset.status_code == 200, (output, asset.status_code)
+        assert asset.content == Path('static', output).read_bytes(), output
+        assert asset.headers['content-type'].startswith('text/javascript'), output
+        assert asset.headers['cache-control'] == 'no-cache', output
     response = client.get('/static/js/actionMenuOrder.js')
     assert response.status_code == 200, response.status_code
     assert response.content == Path('static/js/actionMenuOrder.js').read_bytes()
@@ -58,7 +67,10 @@ def main() -> int:
         )
         # A caller's Python search path must not import the original checkout.
         env.pop("PYTHONPATH", None)
-        result = subprocess.run([sys.executable, "-c", PROBE], cwd=target, env=env, capture_output=True, text=True, timeout=60)
+        outputs = [entry['deployment'] for entry in json.loads(
+            (ROOT / 'frontend/modules.json').read_text(encoding='utf-8')
+        )['modules']]
+        result = subprocess.run([sys.executable, "-c", PROBE, json.dumps(outputs)], cwd=target, env=env, capture_output=True, text=True, timeout=60)
         print(result.stdout, end="")
         if result.returncode:
             print(result.stderr[-8000:], file=sys.stderr)
diff --git a/scripts/verify_notes_browser_runtime.py b/scripts/verify_notes_browser_runtime.py
new file mode 100644
index 000000000..5fedbaf33
--- /dev/null
+++ b/scripts/verify_notes_browser_runtime.py
@@ -0,0 +1,76 @@
+#!/usr/bin/env python3
+"""Run real Notes UI and API against a disposable native distribution and database."""
+import os
+from pathlib import Path
+import shutil
+import socket
+import subprocess
+import sys
+import tempfile
+import time
+from urllib.request import urlopen
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+def main():
+    with tempfile.TemporaryDirectory(prefix="ody-notes-native-") as directory, socket.socket() as chroma_guard:
+        target = Path(directory)
+        for name in ("app.py", "HARNESS_VERSION"):
+            shutil.copy2(ROOT / name, target / name)
+        for name in ("core", "routes", "src", "services", "resources", "mcp_servers", "companion", "config", "static"):
+            shutil.copytree(ROOT / name, target / name, ignore=shutil.ignore_patterns("__pycache__", ".env", "secrets.env*", "*.db", "*.sqlite*"))
+        chroma_guard.bind(("127.0.0.1", 0))
+        with socket.socket() as app_port:
+            app_port.bind(("127.0.0.1", 0))
+            port = app_port.getsockname()[1]
+        env = dict(os.environ)
+        env.update(
+            ODYSSEUS_DATA_DIR=str(target / "data"),
+            DATABASE_URL="sqlite:///" + str(target / "notes.db"), AUTH_ENABLED="true",
+            ODYSSEUS_STARTUP_WARMUPS="0", ODYSSEUS_TOOL_INDEX_PREWARM="0",
+            CHROMADB_HOST="127.0.0.1", CHROMADB_PORT=str(chroma_guard.getsockname()[1]),
+            FASTEMBED_CACHE_PATH=str(target / "fastembed"),
+        )
+        env.pop("PYTHONPATH", None)
+        server = subprocess.Popen(
+            [sys.executable, "-m", "uvicorn", "app:app", "--host", "127.0.0.1", "--port", str(port)],
+            cwd=target, env=env, stdout=subprocess.PIPE, stderr=subprocess.STDOUT, text=True,
+        )
+        result = None
+        try:
+            origin = f"http://127.0.0.1:{port}"
+            deadline = time.monotonic() + 45
+            while time.monotonic() < deadline:
+                if server.poll() is not None:
+                    raise RuntimeError("Disposable Notes server exited during startup")
+                try:
+                    with urlopen(origin + "/", timeout=1) as response:
+                        if response.status == 200:
+                            break
+                except OSError:
+                    time.sleep(0.1)
+            else:
+                raise RuntimeError("Disposable Notes server did not become ready")
+            result = subprocess.run(
+                ["node", "tests/browser/notesNative.mjs"], cwd=ROOT,
+                env=dict(os.environ, ODYSSEUS_NOTES_RUNTIME_ORIGIN=origin, NOTES_TEST_PYTHON=sys.executable),
+                capture_output=True, text=True, timeout=120,
+            )
+            print(result.stdout, end="")
+            if result.returncode:
+                print(result.stderr, file=sys.stderr)
+            return result.returncode
+        finally:
+            server.terminate()
+            try:
+                logs, _ = server.communicate(timeout=10)
+            except subprocess.TimeoutExpired:
+                server.kill()
+                logs, _ = server.communicate()
+            if result is None or result.returncode:
+                print(logs[-8000:], file=sys.stderr)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/static/js/compare/vote.js b/static/js/compare/vote.js
index cece556e8..dcf5ecee7 100644
--- a/static/js/compare/vote.js
+++ b/static/js/compare/vote.js
@@ -1,4 +1,5 @@
 // compare/vote.js — voting, revealing, confetti
+import { spawnConfetti } from '../shared/ui/confetti.js';
 import Storage from '../storage.js';
 import state from './state.js';
 import { _modelDisplayNames } from './models.js';
@@ -222,33 +223,4 @@ function handleVote(winnerIdx) {
   }
 }
 
-/** Spawn confetti particles from a point. */
-function spawnConfetti(cx, cy, count) {
-  const colors = ['#ffd700', '#ff6b6b', '#5b8def', '#51cf66', '#ff922b', '#cc5de8', '#22b8cf', '#fff'];
-  for (let i = 0; i < count; i++) {
-    const el = document.createElement('div');
-    el.className = 'confetti-piece';
-    const color = colors[Math.floor(Math.random() * colors.length)];
-    const size = 5 + Math.random() * 8;
-    const isCircle = Math.random() > 0.5;
-    el.style.width = size + 'px';
-    el.style.height = (isCircle ? size : size * 0.6) + 'px';
-    el.style.background = color;
-    el.style.borderRadius = isCircle ? '50%' : '2px';
-    el.style.left = cx + 'px';
-    el.style.top = cy + 'px';
-    const angle = Math.random() * Math.PI * 2;
-    const speed = 60 + Math.random() * 160;
-    const dx = Math.cos(angle) * speed;
-    const dy = Math.sin(angle) * speed - 100;
-    const duration = 1.0 + Math.random() * 1.0;
-    el.animate([
-      { transform: 'translate(0, 0) rotate(0deg) scale(1)', opacity: 1 },
-      { transform: `translate(${dx}px, ${dy + 200}px) rotate(${400 + Math.random() * 400}deg) scale(0)`, opacity: 0 }
-    ], { duration: duration * 1000, easing: 'cubic-bezier(0.15, 0.6, 0.35, 1)', fill: 'forwards' });
-    document.body.appendChild(el);
-    setTimeout(() => el.remove(), duration * 1000 + 50);
-  }
-}
-
 export { _saveVote, handleVote, buildVoteBar, addFinishBadge, spawnConfetti, registerCompareActions };
diff --git a/static/js/features/notes/application/agentActions.js b/static/js/features/notes/application/agentActions.js
new file mode 100644
index 000000000..d96828211
--- /dev/null
+++ b/static/js/features/notes/application/agentActions.js
@@ -0,0 +1,67 @@
+/** Create an agent session, link it to a note and drain its background stream. */
+import { _noteToAgentPrompt } from '../domain/noteRules.js';
+export function createAgentActions({
+  _patchNote,
+  _renderNotes,
+  api,
+  app,
+  createFormData,
+  state,
+  streamComplete,
+  uiModule
+}) {
+  async function _agentSolveNote(id) {
+    const note = state.notes.find(n => n.id === id);
+    if (!note) return;
+    const prompt = _noteToAgentPrompt(note);
+    if (!prompt) { uiModule.showToast('Nothing to solve — note is empty'); return; }
+    try {
+      const dc = await (await api.defaultChat()).json();
+      if (!dc.endpoint_url || !dc.model) { uiModule.showError('No default chat model configured'); return; }
+
+      // 1. Create the session server-side (no UI switch). skip_validation
+      //    avoids re-probing : the default-chat endpoint is already known good.
+      const label = (note.title || (Array.isArray(note.items) && note.items[0]?.text) || 'todo').slice(0, 40);
+      const csFd = createFormData();
+      csFd.append('name', 'Agent: ' + label);
+      csFd.append('endpoint_url', dc.endpoint_url);
+      csFd.append('model', dc.model);
+      if (dc.endpoint_id) csFd.append('endpoint_id', dc.endpoint_id);
+      csFd.append('skip_validation', 'true');
+      const csRes = await api.createSession(csFd);
+      if (!csRes.ok) { uiModule.showError('Could not create agent session'); return; }
+      const sess = await csRes.json();
+      const sid = sess.id;
+
+      // 2. Link the session to the note right away so the tag appears.
+      const n = state.notes.find(x => x.id === id);
+      if (n) app.mergeNote(n, { agent_session_id: sid });
+      _renderNotes();
+      _patchNote(id, { agent_session_id: sid }).catch(() => {});
+
+      // 3. Kick off the agent run in the background. POST to chat_stream in
+      //    agent mode and drain the SSE so the server runs the loop to
+      //    completion + saves : without rendering anything in the chat UI.
+      const fd = createFormData();
+      fd.append('message', prompt);
+      fd.append('session', sid);
+      fd.append('mode', 'agent');
+      fd.append('disabled_tools', JSON.stringify(['manage_notes']));
+      api.startChat(fd)
+        .then(async (res) => {
+          if (!res.ok || !res.body) return;
+          const reader = res.body.getReader();
+          // Drain to completion (server finishes + persists the run).
+          while (true) { const { done } = await reader.read(); if (done) break; }
+          streamComplete(sid);
+        })
+        .catch(() => {});
+
+      uiModule.showToast('Agent working in background — tap the Agent tag when ready');
+    } catch (e) {
+      uiModule.showError('Agent failed: ' + (e.message || e));
+    }
+  }
+
+  return { _agentSolveNote };
+}
diff --git a/static/js/features/notes/application/cardOperations.js b/static/js/features/notes/application/cardOperations.js
new file mode 100644
index 000000000..1131d2ec0
--- /dev/null
+++ b/static/js/features/notes/application/cardOperations.js
@@ -0,0 +1,79 @@
+/** Optimistic card mutations and rollback. Animation completion is a UI-supplied boundary. */
+export function createCardOperations({
+  app,
+  api,
+  effects,
+  pushUndo,
+  undoArchive
+}) {
+    const state = app.state;
+    function togglePin(id) {
+      const note = state.notes.find(n => n.id === id);
+      if (!note) return;
+      const prevPinned = note.pinned, prevSortOrder = note.sort_order;
+      app.mergeNote(note, { pinned: !prevPinned });
+      const patch = { pinned: note.pinned };
+      if (note.pinned) {
+        const minPinned = state.notes.filter(n => n.pinned && n.id !== id).reduce((m, n) => Math.min(m, n.sort_order || 0), 0);
+        app.mergeNote(note, { sort_order: minPinned - 1 });
+        patch.sort_order = note.sort_order;
+      }
+      effects.render();
+      api.patchNote(id, patch).catch(() => {
+        app.mergeNote(note, { pinned: prevPinned, sort_order: prevSortOrder });
+        effects.render(); effects.showError('Failed to pin');
+      });
+    }
+    async function updateColor(id, color) {
+      try {
+        await api.patchNote(id, { color: color || null });
+        const note = state.notes.find(n => n.id === id);
+        if (note) app.mergeNote(note, { color });
+      } catch { effects.showError('Failed to update color'); }
+    }
+    function stageArchive(id) {
+      const index = state.notes.findIndex(n => n.id === id);
+      if (index < 0) return null;
+      const removed = app.removeNoteAt(index);
+      const undo = () => undoArchive(removed, index);
+      pushUndo({ label: 'archive', run: undo });
+      return () => {
+        effects.render();
+        api.patchNote(id, { archived: true }).then(() => effects.archived(undo)).catch(() => {
+          app.insertNoteAt(index, removed); effects.render(); effects.showError('Failed to archive');
+        });
+      };
+    }
+    function unarchive(id) {
+      const index = state.notes.findIndex(n => n.id === id);
+      if (index < 0) return;
+      const removed = app.removeNoteAt(index);
+      effects.render();
+      api.patchNote(id, { archived: false }).then(() => effects.showToast('Unarchived')).catch(() => {
+        app.insertNoteAt(index, removed); effects.render(); effects.showError('Failed to unarchive');
+      });
+    }
+    function deleteOptimistically(id, toast = false) {
+      const index = state.notes.findIndex(n => n.id === id);
+      if (index < 0) return;
+      const removed = app.removeNoteAt(index);
+      effects.render();
+      const deletion = api.deleteNote(id);
+      const completion = toast ? deletion.then(() => effects.showToast('Deleted')) : deletion;
+      completion.catch(() => {
+        app.insertNoteAt(index, removed); effects.render(); effects.showError('Failed to delete');
+      });
+    }
+    // Desktop deliberately persists without updating local sort_order, as before.
+    function persistOrder(ids) { return api.reorder(ids); }
+    async function commitMobileOrder(ids) {
+      try {
+        await api.reorder(ids);
+        ids.forEach((id, index) => {
+          const note = state.notes.find(note => note.id === id);
+          if (note) app.mergeNote(note, { sort_order: index });
+        });
+      } catch (error) { console.warn('reorder failed', error); }
+    }
+    return { togglePin, updateColor, stageArchive, unarchive, deleteOptimistically, persistOrder, commitMobileOrder };
+}
diff --git a/static/js/features/notes/application/checklistOperations.js b/static/js/features/notes/application/checklistOperations.js
new file mode 100644
index 000000000..b4a596b04
--- /dev/null
+++ b/static/js/features/notes/application/checklistOperations.js
@@ -0,0 +1,68 @@
+/** Checklist item workflows. Supplied feedback callbacks update the invoking view. */
+export function createChecklistOperations({
+  app,
+  api,
+  effects,
+  uid
+}) {
+    const state = app.state;
+    function itemNote(id, index) {
+      const note = state.notes.find(n => n.id === id);
+      return note && Array.isArray(note.items) && note.items[index] ? note : null;
+    }
+    function removeItem(id, index) {
+      const note = itemNote(id, index);
+      if (!note) return;
+      const removed = note.items[index];
+      app.mergeNote(note, { items: note.items.filter((_, i) => i !== index) });
+      effects.render();
+      api.patchNote(id, { items: note.items }).catch(() => {
+        app.spliceItems(note, index, 0, removed); effects.render(); effects.showError('Failed to remove item');
+      });
+    }
+    function editItem(note, index, text) {
+      const oldText = (note.items[index].text || '').trim();
+      if (text === oldText) { effects.render(); return; }
+      const oldItem = note.items[index];
+      if (!text) app.spliceItems(note, index, 1);
+      else app.updateItem(note, index, { text });
+      api.patchNote(note.id, { items: note.items }).catch(() => {
+        if (!text) app.spliceItems(note, index, 0, oldItem);
+        else app.updateItem(note, index, { text: oldText });
+        effects.render(); effects.showError('Failed to update item');
+      });
+      effects.render();
+    }
+    function addItem(id, text, added) {
+      const note = state.notes.find(n => n.id === id);
+      if (!note) return;
+      const items = Array.isArray(note.items) ? [...note.items] : [];
+      items.push({ id: uid(), text, done: false });
+      app.mergeNote(note, { items });
+      added(); effects.render();
+      return () => api.patchNote(id, { items }).catch(() => {
+        app.mergeNote(note, { items: items.slice(0, -1) }); effects.render(); effects.showError('Failed to add item');
+      });
+    }
+    function toggleItem(id, index, changed, completed) {
+      const note = itemNote(id, index);
+      if (!note) return;
+      const wasDone = note.items.length > 0 && note.items.every(it => it.done);
+      app.updateItem(note, index, { done: !note.items[index].done });
+      changed(note.items[index].done);
+      if (!wasDone && note.items.length > 0 && note.items.every(it => it.done)) completed();
+      api.patchNote(id, { items: note.items }).catch(() => {
+        app.updateItem(note, index, { done: !note.items[index].done }); changed(note.items[index].done);
+      });
+    }
+    async function toggleTodayStep(id, index, changed, completed) {
+      const note = itemNote(id, index);
+      if (!note) return;
+      app.updateItem(note, index, { done: !note.items[index].done }); changed();
+      try {
+        await api.patchNote(id, { items: note.items }); effects.render();
+        if (note.items.every(it => it.done)) completed();
+      } catch { app.updateItem(note, index, { done: !note.items[index].done }); }
+    }
+    return { removeItem, editItem, addItem, toggleItem, toggleTodayStep };
+}
diff --git a/static/js/features/notes/application/deletion.js b/static/js/features/notes/application/deletion.js
new file mode 100644
index 000000000..e31e9b422
--- /dev/null
+++ b/static/js/features/notes/application/deletion.js
@@ -0,0 +1,51 @@
+/** Confirmed deletion and past-reminder clearing workflows. */
+export function createDeletion({
+  app,
+  _deleteNoteApi,
+  _fetchNotes,
+  _isPastReminder,
+  _renderNotes,
+  effects,
+  state
+}) {
+  async function _deleteNote(id) {
+    const ok = effects.styledConfirm
+      ? await effects.styledConfirm('Delete this note?', { confirmText: 'Delete', danger: true })
+      : effects.confirm('Delete this note?');
+    if (!ok) return;
+    try { await _deleteNoteApi(id); await _fetchNotes(); _renderNotes(); effects.showToast('Deleted'); }
+    catch (err) { effects.showError(err.message); }
+  }
+
+  async function _clearPastReminders() {
+    const targets = state.notes.filter(n => !n.archived && _isPastReminder(n));
+    if (!targets.length) {
+      effects.showToast?.('No past reminders to clear');
+      return;
+    }
+    const ok = effects.styledConfirm
+      ? await effects.styledConfirm(`Delete ${targets.length} past reminder${targets.length === 1 ? '' : 's'}?`, { confirmText: 'Delete', danger: true })
+      : effects.confirm(`Delete ${targets.length} past reminder${targets.length === 1 ? '' : 's'}?`);
+    if (!ok) return;
+    await Promise.all(targets.map(n => _deleteNoteApi(n.id).catch(() => {})));
+    await _fetchNotes();
+    _renderNotes();
+    effects.showToast?.(`Cleared ${targets.length} past reminder${targets.length === 1 ? '' : 's'}`);
+  }
+
+  async function deleteFromEditor(id) {
+    const ok = effects.styledConfirm
+      ? await effects.styledConfirm('Delete this note?', { confirmText: 'Delete', danger: true })
+      : effects.confirm('Delete this note?');
+    if (!ok) return;
+    const index = state.notes.findIndex(note => note.id === id);
+    if (index >= 0) app.removeNoteAt(index);
+    app.setEditingId(null);
+    _renderNotes();
+    _deleteNoteApi(id).then(() => effects.showToast('Deleted')).catch(() => {
+      effects.showError('Failed to delete');
+      _fetchNotes().then(() => _renderNotes());
+    });
+  }
+  return { _deleteNote, _clearPastReminders, deleteFromEditor };
+}
diff --git a/static/js/features/notes/application/drafts.js b/static/js/features/notes/application/drafts.js
new file mode 100644
index 000000000..4f7a4715d
--- /dev/null
+++ b/static/js/features/notes/application/drafts.js
@@ -0,0 +1,55 @@
+/** Serialized autosave and synchronous local draft backup. DOM collection is a supplied port. */
+export function createNotesDrafts({
+  app,
+  api,
+  persistence,
+  scheduler,
+  effects
+}) {
+  const state = app.state;
+  const { _draftKey, _clearDraft } = persistence;
+  function bindDraft({ collect, id, view }) {
+    let t = null;
+    let pending = Promise.resolve();
+    let stopped = false;
+    let warned = false;
+    const save = () => {
+      const d = collect();
+      // An empty edit can be intentional: don't restore stale server text over it.
+      try { persistence.setItem(_draftKey(id), JSON.stringify(d)); }
+      catch {
+        if (!warned) effects.showError('Draft backup unavailable. Keep this note open until saved.');
+        warned = true;
+      }
+      return d;
+    };
+    const persist = (d) => {
+      if (!id || id === '__new__' || d.note_type === 'draw') return pending;
+      const { _ts, ...payload } = d;
+      payload.label = [...new Set(payload.label.split(/\s+/).map(s => s.replace(/^#+/, '')).filter(Boolean))].join(' ') || null;
+      pending = pending.then(async () => {
+        try {
+          await api.patchNote(id, payload);
+          view.failed = false;
+          const note = state.notes.find(n => n.id === id);
+          if (note) app.mergeNote(note, payload);
+          if (persistence.getItem(_draftKey(id)) === JSON.stringify(d)) _clearDraft(id);
+        } catch {
+          if (!view.failed) effects.showError('Note not synced. Your edits are kept on this device; retry Save.');
+          view.failed = true;
+        }
+      });
+      return pending;
+    };
+    const flush = () => { scheduler.clearTimeout(t); return save(); };
+    const stop = () => { stopped = true; scheduler.clearTimeout(t); return pending; };
+    const sched = () => {
+      const d = save();
+      if (stopped) return;
+      scheduler.clearTimeout(t);
+      t = scheduler.setTimeout(() => persist(d), 500);
+    };
+    return { flush, stop, schedule: sched };
+  }
+  return { bindDraft };
+}
diff --git a/static/js/features/notes/application/queries.js b/static/js/features/notes/application/queries.js
new file mode 100644
index 000000000..6a92250c9
--- /dev/null
+++ b/static/js/features/notes/application/queries.js
@@ -0,0 +1,66 @@
+/** Application-owned filtering, searching and note ordering. */
+import { _noteTags, _visibleNoteTags, _nextGoalStep, _isCalendarReminderNote } from '../domain/noteRules.js';
+import { _hasTimeComponent } from '../domain/recurrence.js';
+export function createQueries({
+  _hasActiveReminder,
+  state
+}) {
+  function _sortedVisibleNotes() {
+    const displayNotes = _userVisibleNotes();
+    let filtered = state.activeLabel ? displayNotes.filter(n => _noteTags(n).includes(state.activeLabel)) : displayNotes;
+    if (state.activeFilter === 'reminders') {
+      filtered = filtered.filter(n => n.due_date && _hasTimeComponent(n.due_date));
+    } else if (state.activeFilter === 'no-reminders') {
+      filtered = filtered.filter(n => !(n.due_date && _hasTimeComponent(n.due_date)));
+    } else if (state.activeFilter === 'default') {
+      filtered = filtered.filter(n => _visibleNoteTags(n).length === 0);
+    } else if (state.activeFilter === 'goals') {
+      filtered = filtered.filter(n => n.note_type === 'goal' && !n.archived);
+    } else if (state.activeFilter === 'today') {
+      // Today view: only goals that still have an unchecked step.
+      filtered = filtered.filter(n => n.note_type === 'goal' && !n.archived && _nextGoalStep(n));
+    }
+    if (state.searchQuery) {
+      filtered = filtered.filter(n => {
+        const q = state.searchQuery;
+        if ((n.title || '').toLowerCase().includes(q)) return true;
+        if ((n.content || '').toLowerCase().includes(q)) return true;
+        if ((n.label || '').toLowerCase().includes(q)) return true;
+        if (Array.isArray(n.items) && n.items.some(it => (it.text || '').toLowerCase().includes(q))) return true;
+        return false;
+      });
+    }
+    const sorted = [...filtered].sort((a, b) => {
+      // In reminders view: sort by due date ascending (soonest first)
+      if (state.activeFilter === 'reminders') {
+        const da = new Date(a.due_date || 0).getTime();
+        const db = new Date(b.due_date || 0).getTime();
+        return da - db;
+      }
+      // Archived view: newest archived first (ignore manual sort_order).
+      if (state.showingArchived) {
+        return new Date(b.updated_at || 0) - new Date(a.updated_at || 0);
+      }
+      if (a.pinned && !b.pinned) return -1;
+      if (!a.pinned && b.pinned) return 1;
+      // Active reminders (due date in the past, not done/archived) rank
+      // immediately under the pinned block.
+      const aActive = _hasActiveReminder(a);
+      const bActive = _hasActiveReminder(b);
+      if (aActive && !bActive) return -1;
+      if (!aActive && bActive) return 1;
+      const so = (a.sort_order || 0) - (b.sort_order || 0);
+      if (so !== 0) return so;
+      return new Date(b.updated_at || 0) - new Date(a.updated_at || 0);
+    });
+
+
+  return sorted;
+  }
+
+  function _userVisibleNotes() {
+    return state.notes.filter(n => !_isCalendarReminderNote(n));
+  }
+
+  return { _sortedVisibleNotes, _userVisibleNotes };
+}
diff --git a/static/js/features/notes/application/reminders.js b/static/js/features/notes/application/reminders.js
new file mode 100644
index 000000000..5e2475993
--- /dev/null
+++ b/static/js/features/notes/application/reminders.js
@@ -0,0 +1,182 @@
+/** Page-owned reminder scheduler and notification delivery workflow. */
+import { _hasTimeComponent, _isDueTodayOrOverdue, _advanceRecurring } from '../domain/recurrence.js';
+export function createNotesReminders({
+  app,
+  api,
+  persistence,
+  notifications,
+  clock,
+  scheduler,
+  effects,
+  fetchNotes,
+  isNoteFullyDone,
+  hasItems,
+  dismissedKey
+}) {
+  const state = app.state;
+  const { _loadFiredReminders, _saveFiredReminders } = persistence;
+  const _patchNote = api.patchNote;
+  const _fetchNotes = fetchNotes;
+  const _isNoteFullyDone = isNoteFullyDone;
+  const _hasItems = hasItems;
+  const REMINDER_DISMISSED_AT_KEY = dismissedKey;
+  const _updateRailBadge = effects.badge;
+  let _reminderTimer = null;
+  let startupTimer = null;
+  let started = false;
+  let disposed = false;
+  function _checkReminders() {
+    if (!state.notes.length) return;
+    const now = clock.now();
+    const fired = _loadFiredReminders();
+    let changed = false;
+    for (const note of state.notes) {
+      if (!note.due_date || note.archived) continue;
+      if (!_hasTimeComponent(note.due_date)) continue;
+      if (fired.has(note.id)) continue;
+      const due = new Date(note.due_date).getTime();
+      if (isNaN(due)) continue;
+      if (due <= now && due > now - 60000) {
+        _fireReminder(note);
+        // Recurring? advance the due_date instead of marking as fired
+        if (note.repeat && note.repeat !== 'none') {
+          const next = _advanceRecurring(note.due_date, note.repeat, clock);
+          if (next) {
+            app.mergeNote(note, { due_date: next });
+            _patchNote(note.id, { due_date: next }).catch(() => {});
+            // Don't add to fired : new due_date is in the future
+            continue;
+          }
+        }
+        fired.add(note.id);
+        changed = true;
+      } else if (due <= now - 60000) {
+        // Past, never seen : silently advance recurring or mark fired
+        if (note.repeat && note.repeat !== 'none') {
+          const next = _advanceRecurring(note.due_date, note.repeat, clock);
+          if (next) {
+            app.mergeNote(note, { due_date: next });
+            _patchNote(note.id, { due_date: next }).catch(() => {});
+            continue;
+          }
+        }
+        fired.add(note.id);
+        changed = true;
+      }
+    }
+    if (changed) _saveFiredReminders(fired);
+    // Always refresh badge : fired state may have changed visually without note mutation
+    _updateRailBadge();
+  }
+
+  function _fireReminder(note) {
+    const title = note.title || 'Note reminder';
+    // Include the verbatim note content so the email/notification actually
+    // shows what to do, not just a count. Cap the per-item lines (8 max) and
+    // total length so the body stays inbox-friendly.
+    let rawBody;
+    if (_hasItems(note)) {
+      const pending = (note.items || [])
+        .filter(i => !i.done && !i.checked)
+        .map(i => (i.text || '').trim())
+        .filter(Boolean);
+      if (pending.length) {
+        const shown = pending.slice(0, 8).map(t => `- ${t}`).join('\n');
+        const extra = pending.length > 8 ? `\n…and ${pending.length - 8} more` : '';
+        rawBody = `Pending (${pending.length}):\n${shown}${extra}`;
+      } else {
+        rawBody = `${(note.items || []).length} item${(note.items || []).length === 1 ? '' : 's'}`;
+      }
+    } else {
+      rawBody = (note.content || '').slice(0, 400);
+    }
+
+    // Ask the server to dispatch according to user settings. The server may
+    // return an LLM-written synthesis line and/or send an email. We still show
+    // a local browser notification so the user gets immediate feedback even if
+    // the server path is disabled or slow.
+    const showLocal = body => notifications.show(title, body, note.id);
+
+    // Fire-and-forget server dispatch. If synthesis comes back quickly enough,
+    // use it as the notification body; otherwise the local notification has
+    // already shown with the raw body.
+    let shown = false;
+    const timer = scheduler.setTimeout(() => { if (!shown) { shown = true; showLocal(rawBody); } }, 1500);
+
+    api.fireReminder({ note_id: note.id, title, body: rawBody })
+      .then(r => r.ok ? r.json() : null)
+      .then(data => {
+        scheduler.clearTimeout(timer);
+        if (shown) return;
+        shown = true;
+        const body = (data && data.synthesis) ? data.synthesis : rawBody;
+        showLocal(body);
+      })
+      .catch(() => {
+        scheduler.clearTimeout(timer);
+        if (!shown) { shown = true; showLocal(rawBody); }
+      });
+
+    // Pulse the card if visible; otherwise queue it so the next time the user
+    // opens the notes panel the card gets a brief glow.
+    effects.highlight(note.id);
+  }
+
+  function _startReminderLoop() {
+    if (disposed || _reminderTimer) return;
+    _reminderTimer = scheduler.setInterval(_checkReminders, 30000);
+    _checkReminders(); // run once immediately
+  }
+
+  function _countDueReminders() {
+    return state.notes.filter(n => !n.archived && _isDueTodayOrOverdue(n.due_date, clock) && !_isNoteFullyDone(n)).length;
+  }
+
+  function _countFiredReminders() {
+    // Reminders whose time has actually passed (not just date-today),
+    // and which fired after the last user dismissal.
+    const now = clock.now();
+    return state.notes.filter(n => {
+      if (n.archived || _isNoteFullyDone(n)) return false;
+      if (!n.due_date || !_hasTimeComponent(n.due_date)) return false;
+      const t = new Date(n.due_date).getTime();
+      if (isNaN(t) || t > now) return false;
+      return t > state.firedDotDismissedAt;
+    }).length;
+  }
+
+  function dismissFiredReminderDot() {
+    app.setFiredDotDismissedAt(clock.now());
+    try { persistence.setItem(REMINDER_DISMISSED_AT_KEY, String(state.firedDotDismissedAt)); } catch {}
+    _updateRailBadge();
+  }
+
+  async function refreshDueBadge(opts = {}) {
+    // Usually lightweight, but callers that just created a note reminder can
+    // force a refresh so the background reminder loop sees it immediately.
+    if (opts.force || state.notes.length === 0) {
+      try {
+        const wasArchived = state.showingArchived;
+        app.setShowingArchived(false);
+        await _fetchNotes();
+        app.setShowingArchived(wasArchived);
+      } catch {}
+    }
+    _updateRailBadge();
+  }
+
+  async function _initReminders() {
+    try {
+      const res = await api.listNotes(false);
+      if (res.ok && !disposed) {
+        const data = await res.json();
+        app.replaceNotes(data.notes || data || []);
+        _startReminderLoop();
+      }
+    } catch {}
+  }
+
+  function start() { if (started || disposed) return; started = true; startupTimer = scheduler.setTimeout(_initReminders, 3000); }
+  function dispose() { disposed = true; scheduler.clearTimeout(startupTimer); scheduler.clearInterval(_reminderTimer); _reminderTimer = null; }
+  return { start, dispose, _checkReminders, _fireReminder, _startReminderLoop, _countDueReminders, _countFiredReminders, dismissFiredReminderDot, refreshDueBadge, _initReminders };
+}
diff --git a/static/js/features/notes/application/selection.js b/static/js/features/notes/application/selection.js
new file mode 100644
index 000000000..6017025e2
--- /dev/null
+++ b/static/js/features/notes/application/selection.js
@@ -0,0 +1,39 @@
+/** Selected-note attachment retains synchronous acceptance; bulk requests retain partial-failure behavior. */
+export function createSelectionOperations({
+  app,
+  api,
+  effects,
+  sendContext,
+  exitSelection,
+  fetchNotes
+}) {
+    const state = app.state;
+    function attachSelected() {
+      const ids = [...state.selectedIds];
+      if (!ids.length) return;
+      const detail = { noteIds: ids, accepted: false };
+      sendContext(detail);
+      if (!detail.accepted) {
+        effects.showToast('Choose a chat or model before attaching notes');
+        return;
+      }
+      exitSelection();
+    }
+    async function archiveSelected() {
+      const ids = [...state.selectedIds];
+      if (!ids.length) return;
+      await Promise.all(ids.map(id => api.patchNote(id, { archived: true }).catch(() => {})));
+      exitSelection(); await fetchNotes(); effects.render(); effects.showToast(`Archived ${ids.length}`);
+    }
+    async function deleteSelected() {
+      const ids = [...state.selectedIds];
+      if (!ids.length) return;
+      if (effects.styledConfirm) {
+        const ok = await effects.styledConfirm(`Delete ${ids.length} note${ids.length === 1 ? '' : 's'}?`, { confirmText: 'Delete', danger: true });
+        if (!ok) return;
+      }
+      await Promise.all(ids.map(id => api.deleteNote(id).catch(() => {})));
+      exitSelection(); await fetchNotes(); effects.render(); effects.showToast(`Deleted ${ids.length}`);
+    }
+    return { attachSelected, archiveSelected, deleteSelected };
+}
diff --git a/static/js/features/notes/application/state.js b/static/js/features/notes/application/state.js
new file mode 100644
index 000000000..b87ef11c4
--- /dev/null
+++ b/static/js/features/notes/application/state.js
@@ -0,0 +1,83 @@
+/** The sole Notes state owner. Views have live read-only access; writes use operations. */
+export function createNotesState(initial = {}) {
+    const values = {
+      open: false, notes: [], editingId: null, selectedIds: new Set(),
+      activeLabel: null, activeFilter: null, reminderChipNext: 'reminders', searchQuery: '',
+      viewMode: initial.viewMode || 'list', showingArchived: false, selectMode: false,
+      suppressNextNoteTapId: null, labelsCollapsed: !!initial.labelsCollapsed,
+      loading: false, firedDotDismissedAt: initial.firedDotDismissedAt || 0,
+    };
+    // Preserve captured note identity across asynchronous completions without
+    // giving a view a writable reference to the application store.
+    const views = new WeakMap(), targets = new WeakMap();
+    const unwrap = value => targets.get(value) || value;
+    // Copies built from views (spread, filter, map) still hold nested views;
+    // store only raw data so the owner never keeps its own read-only views.
+    function unwrapDeep(value, seen = new WeakSet()) {
+      if (!value || typeof value !== 'object') return value;
+      if (targets.has(value)) return targets.get(value);
+      if (seen.has(value)) return value;
+      seen.add(value);
+      if (Array.isArray(value)) value.forEach((item, index) => { value[index] = unwrapDeep(item, seen); });
+      else if (Object.getPrototypeOf(value) === Object.prototype) for (const key of Object.keys(value)) value[key] = unwrapDeep(value[key], seen);
+      return value;
+    }
+    function readonly(value) {
+      if (!value || typeof value !== 'object') return value;
+      if (targets.has(value)) return value;
+      if (views.has(value)) return views.get(value);
+      const view = new Proxy(value, {
+        get(target, key) {
+          if (target instanceof Set) {
+            if (['add', 'delete', 'clear'].includes(key)) return () => { throw new TypeError('Use Notes selection operations'); };
+            if (key === 'valueOf') return () => views.get(target);
+            if (key === 'forEach') return (callback, thisArg) => target.forEach(value => callback.call(thisArg, value, value, views.get(target)));
+            const member = Reflect.get(target, key, target);
+            return typeof member === 'function' ? member.bind(target) : member;
+          }
+          return readonly(Reflect.get(target, key));
+        },
+        set() { throw new TypeError('Use Notes state operations'); },
+        deleteProperty() { throw new TypeError('Use Notes state operations'); },
+        defineProperty() { throw new TypeError('Use Notes state operations'); },
+        setPrototypeOf() { throw new TypeError('Use Notes state operations'); },
+        preventExtensions() { throw new TypeError('Use Notes state operations'); },
+        getOwnPropertyDescriptor(target, key) {
+          const descriptor = Reflect.getOwnPropertyDescriptor(target, key);
+          if (descriptor && 'value' in descriptor) return { ...descriptor, value: readonly(descriptor.value) };
+          return descriptor;
+        },
+      });
+      views.set(value, view); targets.set(view, value);
+      return view;
+    }
+    const state = Object.freeze(Object.fromEntries(Object.keys(values).map(key => [key, () => readonly(values[key])])));
+    const view = Object.freeze(Object.defineProperties({}, Object.fromEntries(Object.entries(state).map(([key, get]) => [key, { get, enumerable: true }]))));
+    return {
+      state: view,
+      setOpen: value => { values.open = value; },
+      setEditingId: value => { values.editingId = value; },
+      setActiveLabel: value => { values.activeLabel = value; },
+      setActiveFilter: value => { values.activeFilter = value; },
+      setReminderChipNext: value => { values.reminderChipNext = value; },
+      setSearchQuery: value => { values.searchQuery = value; },
+      setViewMode: value => { values.viewMode = value; },
+      setShowingArchived: value => { values.showingArchived = value; },
+      setSelectMode: value => { values.selectMode = value; },
+      setSuppressNextNoteTapId: value => { values.suppressNextNoteTapId = value; },
+      setLabelsCollapsed: value => { values.labelsCollapsed = value; },
+      setLoading: value => { values.loading = value; },
+      setFiredDotDismissedAt: value => { values.firedDotDismissedAt = value; },
+      replaceNotes: notes => { values.notes = notes; },
+      removeNoteAt: index => readonly(values.notes.splice(index, 1)[0]),
+      insertNoteAt: (index, note) => { values.notes.splice(index, 0, unwrapDeep(note)); },
+      prependNote: note => { values.notes.unshift(unwrapDeep(note)); },
+      replaceNoteAt: (index, note) => { values.notes[index] = unwrapDeep(note); },
+      mergeNote: (note, patch) => { for (const [key, value] of Object.entries(patch)) unwrap(note)[key] = unwrapDeep(value); },
+      updateItem: (note, index, patch) => { Object.assign(unwrap(unwrap(note).items[index]), unwrapDeep({ ...patch })); },
+      spliceItems: (note, ...args) => unwrap(unwrap(note).items).splice(...args.map(arg => unwrapDeep(arg))),
+      selectId: id => { values.selectedIds.add(id); },
+      deselectId: id => values.selectedIds.delete(id),
+      clearSelection: () => values.selectedIds.clear(),
+    };
+}
diff --git a/static/js/features/notes/application/submission.js b/static/js/features/notes/application/submission.js
new file mode 100644
index 000000000..4703eb7c1
--- /dev/null
+++ b/static/js/features/notes/application/submission.js
@@ -0,0 +1,69 @@
+/** Editor submission ordering, optimistic state, reminder rearming and save recovery. */
+export function createNotesSubmission({
+  app,
+  api,
+  persistence,
+  clock,
+  uid,
+  effects,
+  fetchNotes
+}) {
+  const state = app.state;
+  const { _loadFiredReminders, _saveFiredReminders, _loadGlowedReminders, _saveGlowedReminders, _loadDraft, _clearDraft } = persistence;
+  function submitNote(payload, note, isEdit) {
+      // Reset fired reminder if due_date changed (so re-arm works), and also
+      // clear the entry-glow seen flag so the new firing glows again on the
+      // next time the user opens the panel.
+      if (isEdit && note.due_date !== payload.due_date) {
+        const fired = _loadFiredReminders();
+        fired.delete(note.id);
+        _saveFiredReminders(fired);
+        const glowed = _loadGlowedReminders();
+        glowed.delete(note.id);
+        _saveGlowedReminders(glowed);
+        effects.clearGlow(note.id);
+      }
+      // Edited notes move to the top of their section (under pinned). Compute
+      // sort_order = (min unpinned sort_order) - 1 so the saved note sorts above
+      // siblings; the pin block keeps its own ordering above this.
+      if (!payload.pinned) {
+        // Both edits AND newly-created notes anchor above the rest of the
+        // unpinned section. Without this, freshly created notes sit at the
+        // bottom because manually-reordered siblings already carry negative
+        // sort_order values.
+        const minUnpinned = state.notes
+          .filter(n => !n.pinned && (!isEdit || n.id !== note.id))
+          .reduce((m, n) => Math.min(m, n.sort_order || 0), 0);
+        payload.sort_order = minUnpinned - 1;
+      }
+      // Optimistic update : update local state first, render, then save in background
+      app.setEditingId(null);
+      const draftId = isEdit ? note.id : '__new__';
+      const submittedDraft = JSON.stringify(_loadDraft(draftId));
+      if (isEdit) {
+        const idx = state.notes.findIndex(n => n.id === note.id);
+        if (idx >= 0) app.replaceNoteAt(idx, { ...state.notes[idx], ...payload });
+      } else {
+        app.prependNote({ ...payload, id: 'tmp_' + uid(), created_at: new Date(clock.now()).toISOString(), updated_at: new Date(clock.now()).toISOString() });
+      }
+      effects.render();
+      // Background save
+      api.saveNote(payload).then(saved => {
+        if (JSON.stringify(_loadDraft(draftId)) === submittedDraft) _clearDraft(draftId);
+        if (!isEdit && saved && saved.id) {
+          // Replace temp ID with real one from server. AND re-render : the
+          // existing card's `data-note-id="tmp_xxx"` is stale after Object.assign
+          // bumps the in-memory id, so all subsequent clicks (edit, done, copy,
+          // archive, delete) silently fail to find the note in `_notes`.
+          const tmp = state.notes.find(n => n.id.startsWith('tmp_'));
+          if (tmp) app.mergeNote(tmp, saved);
+          effects.render();
+        }
+      }).catch(err => {
+        effects.showError('Save failed: ' + err.message);
+        fetchNotes().then(() => effects.render());
+      });
+
+  }
+  return { submitNote };
+}
diff --git a/static/js/features/notes/application/workflows.js b/static/js/features/notes/application/workflows.js
new file mode 100644
index 000000000..018cbf8aa
--- /dev/null
+++ b/static/js/features/notes/application/workflows.js
@@ -0,0 +1,78 @@
+/** Notes CRUD, optimistic archive and in-memory undo workflows. */
+export function createNotesWorkflows({
+  app,
+  api,
+  effects
+}) {
+  const state = app.state;
+  const _undoStack = [];
+  const _renderNotes = effects.render;
+  const _patchNote = api.patchNote;
+  const uiModule = effects;
+  function _pushUndo(entry) {
+    _undoStack.push(entry);
+    if (_undoStack.length > 20) _undoStack.shift();
+  }
+
+  function _popAndRunUndo() {
+    const entry = _undoStack.pop();
+    if (entry) entry.run();
+    return !!entry;
+  }
+
+  function _undoArchive(note, prevIdx) {
+    // Re-insert at original position and clear archived flag on the server.
+    const safeIdx = Math.min(Math.max(prevIdx, 0), state.notes.length);
+    app.insertNoteAt(safeIdx, { ...note, archived: false });
+    _renderNotes();
+    _patchNote(note.id, { archived: false }).catch(() => {
+      // Roll back local insertion if the server refuses
+      const i = state.notes.findIndex(n => n.id === note.id);
+      if (i >= 0) app.removeNoteAt(i);
+      _renderNotes();
+      uiModule.showError('Undo failed');
+    });
+  }
+
+  function _archiveNoteById(id, { card = null, celebrate = false } = {}) {
+    if (!id) return false;
+    const idx = state.notes.findIndex(n => n.id === id);
+    if (idx < 0) return false;
+    const note = state.notes[idx];
+    if (celebrate && card && note) effects.celebrateArchive(note, card);
+    const removed = app.removeNoteAt(idx);
+    app.setEditingId(null);
+    _renderNotes();
+    const undo = () => _undoArchive(removed, idx);
+    _pushUndo({ label: 'archive', run: undo });
+    _patchNote(id, { archived: true }).then(() => {
+      effects.archived(undo);
+    }).catch(() => {
+      app.insertNoteAt(idx, removed);
+      _renderNotes();
+      uiModule.showError('Failed to archive');
+    });
+    return true;
+  }
+
+  async function _fetchNotes() {
+    app.setLoading(true);
+    try {
+      const res = await api.listNotes(state.showingArchived);
+      if (!res.ok) { app.replaceNotes([]); return; }
+      const data = await res.json();
+      app.replaceNotes(data.notes || data || []);
+    } catch (e) {
+      console.error('Failed to fetch notes:', e);
+      app.replaceNotes([]);
+    } finally {
+      app.setLoading(false);
+    }
+  }
+
+  function _saveNote(note) { return api.saveNote(note); }
+
+  function _deleteNoteApi(id) { return api.deleteNote(id); }
+
+  return { _pushUndo, _popAndRunUndo, _undoArchive, _archiveNoteById, _fetchNotes, _saveNote, _deleteNoteApi, _patchNote, undoCount: () => _undoStack.length };
+}
diff --git a/static/js/features/notes/domain/noteRules.js b/static/js/features/notes/domain/noteRules.js
new file mode 100644
index 000000000..ba3f8ae2f
--- /dev/null
+++ b/static/js/features/notes/domain/noteRules.js
@@ -0,0 +1,87 @@
+/** Pure Notes completion, tags, reminder and serialization rules. */
+import { _hasTimeComponent } from './recurrence.js';
+export function _isCalendarReminderNote(n) {
+  return n && n.source === 'calendar' && n.label === 'calendar';
+}
+
+export function _hasActiveReminder(n, clock) {
+  if (!n || n.archived || _isNoteFullyDone(n)) return false;
+  if (!n.due_date) return false;
+  const t = new Date(n.due_date).getTime();
+  return !isNaN(t) && t <= clock.now();
+}
+
+export function _isNoteFullyDone(note) {
+  if (_hasItems(note) && Array.isArray(note.items) && note.items.length > 0) {
+    return note.items.every(it => it.done);
+  }
+  return false;
+}
+
+export function _hasItems(note) {
+  return note && (note.note_type === 'todo' || note.note_type === 'goal' || note.note_type === 'checklist');
+}
+
+export function _goalProgress(note) {
+  if (!Array.isArray(note?.items) || note.items.length === 0) return '';
+  const done = note.items.filter(it => it.done).length;
+  return ` ${done}/${note.items.length}`;
+}
+
+export function _nextGoalStep(note) {
+  if (!Array.isArray(note?.items)) return null;
+  for (let i = 0; i < note.items.length; i++) {
+    if (!note.items[i].done) return { idx: i, item: note.items[i] };
+  }
+  return null;
+}
+
+export function _noteTags(n) {
+  const tags = [];
+  if (n?.label) tags.push(...n.label.trim().split(/\s+/).filter(Boolean));
+  if (n?.due_date && _hasTimeComponent(n.due_date)) tags.push('reminder');
+  return [...new Set(tags.map(t => t.replace(/^#+/, '').trim()).filter(Boolean))];
+}
+
+export function _visibleNoteTags(n) {
+  return _noteTags(n).filter(t => t !== 'reminder');
+}
+
+export function _isPastReminder(n, clock) {
+  if (!n?.due_date || !_hasTimeComponent(n.due_date)) return false;
+  const due = new Date(n.due_date).getTime();
+  return !isNaN(due) && due <= clock.now();
+}
+
+export function _serializeNoteForCopy(note) {
+  const lines = [];
+  if (note.title) lines.push(note.title);
+  if (note.content) lines.push(note.content);
+  if (Array.isArray(note.items) && note.items.length) {
+    if (lines.length) lines.push('');
+    for (const it of note.items) {
+      if (!it || !(it.text || '').trim()) continue;
+      lines.push(`- [${it.done ? 'x' : ' '}] ${(it.text || '').trim()}`);
+    }
+  }
+  return lines.join('\n').trim();
+}
+
+export function _noteToAgentPrompt(note) {
+  const parts = [];
+  if ((note.title || '').trim()) parts.push(note.title.trim());
+  if ((note.content || '').trim()) parts.push(note.content.trim());
+  if (Array.isArray(note.items)) {
+    note.items.filter(it => !it.done && (it.text || '').trim())
+      .forEach(it => parts.push('- ' + it.text.trim()));
+  }
+  const body = parts.join('\n');
+  return body ? `Help me get this done:\n\n${body}\n\nThe source note is read-only. Do not edit, replace, or update it.` : '';
+}
+
+export function _standardVisualVariant(note) {
+  const source = String(note?.id || note?.title || note?.created_at || 'standard-note');
+  let hash = 0;
+  for (let i = 0; i < source.length; i++) hash = ((hash << 5) - hash + source.charCodeAt(i)) | 0;
+  return Math.abs(hash) % 5;
+}
diff --git a/static/js/features/notes/domain/recurrence.js b/static/js/features/notes/domain/recurrence.js
new file mode 100644
index 000000000..f72498fbb
--- /dev/null
+++ b/static/js/features/notes/domain/recurrence.js
@@ -0,0 +1,269 @@
+// Local-time date and recurrence rules. Callers supply the clock at the original read sites.
+export const _ORDINALS = ['1st', '2nd', '3rd', '4th', '5th'];
+export const _DAYS = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'];
+export function _hasTimeComponent(dateStr) {
+  return typeof dateStr === 'string' && /T\d{2}:\d{2}/.test(dateStr);
+}
+
+export function _formatDueDate(dateStr, clock) {
+  if (!dateStr) return '';
+  const d = new Date(dateStr);
+  if (isNaN(d)) return '';
+  const now = new Date(clock.now());
+  const hasTime = _hasTimeComponent(dateStr);
+  const today = new Date(now.getFullYear(), now.getMonth(), now.getDate());
+  const due = new Date(d.getFullYear(), d.getMonth(), d.getDate());
+  const diffDays = Math.round((due - today) / 86400000);
+  const timeStr = hasTime ? d.toLocaleTimeString([], { hour: 'numeric', minute: '2-digit' }) : '';
+  if (hasTime && d < now) return 'overdue';
+  if (!hasTime && diffDays < 0) return 'overdue';
+  if (diffDays === 0) return hasTime ? timeStr : 'today';
+  if (diffDays === 1) return hasTime ? `tmrw ${timeStr}` : 'tomorrow';
+  const dateLabel = d.toLocaleDateString([], { month: 'short', day: 'numeric' });
+  return hasTime ? `${dateLabel} ${timeStr}` : dateLabel;
+}
+
+export function _isDueOverdue(dateStr, clock) {
+  if (!dateStr) return false;
+  const d = new Date(dateStr);
+  if (isNaN(d)) return false;
+  if (_hasTimeComponent(dateStr)) return d < new Date(clock.now());
+  return d < new Date(new Date(clock.now()).toDateString());
+}
+
+export function _isDueTodayOrOverdue(dateStr, clock) {
+  if (!dateStr) return false;
+  const d = new Date(dateStr);
+  const now = new Date(clock.now());
+  const today = new Date(now.getFullYear(), now.getMonth(), now.getDate());
+  const due = new Date(d.getFullYear(), d.getMonth(), d.getDate());
+  return due <= today;
+}
+
+export function _laterTodayDate(clock) {
+  const now = new Date(clock.now());
+  const eight = new Date(now.getFullYear(), now.getMonth(), now.getDate(), 18, 0); // 6pm today
+  // If less than 1 hour before 6pm, push to "in 3 hours" instead
+  if (eight - now < 60 * 60 * 1000) return new Date(now.getTime() + 3 * 60 * 60 * 1000);
+  return eight;
+}
+
+export function _tomorrowDate(clock) {
+  const t = new Date(clock.now());
+  t.setDate(t.getDate() + 1);
+  t.setHours(8, 0, 0, 0);
+  return t;
+}
+
+export function _nextWeekDate(clock) {
+  const t = new Date(clock.now());
+  const daysUntilMon = (8 - t.getDay()) % 7 || 7;
+  t.setDate(t.getDate() + daysUntilMon);
+  t.setHours(8, 0, 0, 0);
+  return t;
+}
+
+export function _toLocalDatetimeStr(d) {
+  // Format as YYYY-MM-DDTHH:MM (local, no TZ)
+  const pad = n => String(n).padStart(2, '0');
+  return `${d.getFullYear()}-${pad(d.getMonth()+1)}-${pad(d.getDate())}T${pad(d.getHours())}:${pad(d.getMinutes())}`;
+}
+
+export function _formatReminderTag(dateStr, clock) {
+  if (!dateStr) return '';
+  const d = new Date(dateStr);
+  if (isNaN(d)) return '';
+  const now = new Date(clock.now());
+  const sameDay = d.toDateString() === now.toDateString();
+  const tomorrow = new Date(now); tomorrow.setDate(tomorrow.getDate() + 1);
+  const isTomorrow = d.toDateString() === tomorrow.toDateString();
+  const time = d.toLocaleTimeString([], { hour: 'numeric', minute: '2-digit' });
+  if (sameDay) return `Today, ${time}`;
+  if (isTomorrow) return `Tomorrow, ${time}`;
+  const dateLabel = d.toLocaleDateString([], { month: 'short', day: 'numeric' });
+  return `${dateLabel}, ${time}`;
+}
+
+export function _nthWeekdayLabel(d) {
+  const n = Math.ceil(d.getDate() / 7); // 1..5
+  return `${_ORDINALS[n - 1] || `${n}th`} ${_DAYS[d.getDay()]}`;
+}
+
+export function _isLastWeekdayOfMonth(d) {
+  const test = new Date(d);
+  test.setDate(d.getDate() + 7);
+  return test.getMonth() !== d.getMonth();
+}
+
+export function _nthWeekdayOfMonth(year, month, weekday, n) {
+  const first = new Date(year, month, 1);
+  const offset = (weekday - first.getDay() + 7) % 7;
+  let day = 1 + offset + (n - 1) * 7;
+  // Last day of month
+  const lastDay = new Date(year, month + 1, 0).getDate();
+  if (day > lastDay) day -= 7;
+  return new Date(year, month, day, 0, 0, 0);
+}
+
+export function _lastWeekdayOfMonth(year, month, weekday) {
+  const lastDay = new Date(year, month + 1, 0);
+  const back = (lastDay.getDay() - weekday + 7) % 7;
+  return new Date(year, month, lastDay.getDate() - back, 0, 0, 0);
+}
+
+export function _snapToRepeat(currentDate, normRepeat, clock) {
+  const hh = currentDate.getHours();
+  const mm = currentDate.getMinutes();
+  const now = clock.now();
+  const anchor = currentDate.getTime() > now ? currentDate : new Date(clock.now());
+  const parts = normRepeat.split(':');
+  const kind = parts[0];
+  if (kind === 'weekly') {
+    const targetWd = parseInt(parts[1], 10);
+    if (isNaN(targetWd)) return null;
+    const d = new Date(anchor.getFullYear(), anchor.getMonth(), anchor.getDate(), hh, mm, 0, 0);
+    const delta = (targetWd - d.getDay() + 7) % 7;
+    d.setDate(d.getDate() + delta);
+    if (d.getTime() <= now) d.setDate(d.getDate() + 7);
+    return d;
+  }
+  if (kind === 'monthly') {
+    const sub = parts[1];
+    let y = anchor.getFullYear();
+    let m = anchor.getMonth();
+    // Walk forward up to 14 months to find the next matching slot.
+    for (let tries = 0; tries < 14; tries++) {
+      let target;
+      if (sub === 'day') {
+        const wantDay = parseInt(parts[2], 10);
+        if (isNaN(wantDay)) return null;
+        const lastDay = new Date(y, m + 1, 0).getDate();
+        target = new Date(y, m, Math.min(wantDay, lastDay));
+      } else if (sub === 'nth') {
+        const n = parseInt(parts[2], 10);
+        const wd = parseInt(parts[3], 10);
+        if (isNaN(n) || isNaN(wd)) return null;
+        target = _nthWeekdayOfMonth(y, m, wd, n);
+      } else if (sub === 'last') {
+        const wd = parseInt(parts[2], 10);
+        if (isNaN(wd)) return null;
+        target = _lastWeekdayOfMonth(y, m, wd);
+      } else {
+        return null;
+      }
+      target.setHours(hh, mm, 0, 0);
+      if (target.getTime() > now && target.getTime() >= anchor.getTime()) return target;
+      m++;
+      if (m > 11) { m = 0; y++; }
+    }
+    return null;
+  }
+  return null;
+}
+
+export function _formatRepeatLabel(repeat, originalDate) {
+  if (!repeat || repeat === 'none') return '';
+  const norm = _normalizeRepeat(repeat, originalDate);
+  if (norm === 'daily') return 'Daily';
+  if (norm === 'yearly') return 'Yearly';
+  const parts = norm.split(':');
+  if (parts[0] === 'weekly') {
+    const wd = parseInt(parts[1], 10);
+    if (isNaN(wd)) return 'Weekly';
+    return `Weekly on ${_DAYS[wd]}s`;
+  }
+  if (parts[0] === 'monthly') {
+    if (parts[1] === 'day') return `Monthly on day ${parts[2]}`;
+    if (parts[1] === 'nth') {
+      const n = parseInt(parts[2], 10);
+      const wd = parseInt(parts[3], 10);
+      return `Monthly on ${_ORDINALS[n - 1] || `${n}th`} ${_DAYS[wd]}`;
+    }
+    if (parts[1] === 'last') {
+      const wd = parseInt(parts[2], 10);
+      return `Monthly on last ${_DAYS[wd]}`;
+    }
+  }
+  return norm;
+}
+
+export function _normalizeRepeat(repeat, originalDate) {
+  if (!repeat || repeat === 'none') return 'none';
+  if (repeat === 'daily' || repeat === 'yearly') return repeat;
+  if (/^(weekly|monthly):/.test(repeat)) return repeat;
+  // Legacy bare values: derive params from the original date
+  const wd = originalDate.getDay();
+  const n = Math.ceil(originalDate.getDate() / 7);
+  if (repeat === 'weekly') return `weekly:${wd}`;
+  if (repeat === 'monthly') return `monthly:day:${originalDate.getDate()}`;
+  if (repeat === 'monthly_nth_weekday') return `monthly:nth:${n}:${wd}`;
+  if (repeat === 'monthly_last_weekday') return `monthly:last:${wd}`;
+  return repeat;
+}
+
+export function _advanceRecurring(dateStr, repeat, clock) {
+  const orig = new Date(dateStr);
+  const hh = orig.getHours();
+  const mm = orig.getMinutes();
+  let d = new Date(orig);
+  const norm = _normalizeRepeat(repeat, orig);
+  if (norm === 'none') return null;
+
+  function step() {
+    if (norm === 'daily') {
+      d.setDate(d.getDate() + 1);
+      return;
+    }
+    if (norm === 'yearly') {
+      d.setFullYear(d.getFullYear() + 1);
+      return;
+    }
+    const parts = norm.split(':');
+    const kind = parts[0];
+    if (kind === 'weekly') {
+      // Snap to the requested weekday in the next 1-7 days
+      const targetWd = parseInt(parts[1], 10);
+      let delta = (targetWd - d.getDay() + 7) % 7;
+      if (delta === 0) delta = 7;
+      d.setDate(d.getDate() + delta);
+      d.setHours(hh, mm, 0, 0);
+      return;
+    }
+    if (kind === 'monthly') {
+      const sub = parts[1];
+      const ny = d.getFullYear() + (d.getMonth() === 11 ? 1 : 0);
+      const nm = (d.getMonth() + 1) % 12;
+      let target;
+      if (sub === 'day') {
+        const wantDay = parseInt(parts[2], 10);
+        const lastDay = new Date(ny, nm + 1, 0).getDate();
+        target = new Date(ny, nm, Math.min(wantDay, lastDay));
+      } else if (sub === 'nth') {
+        const n = parseInt(parts[2], 10);
+        const wd = parseInt(parts[3], 10);
+        target = _nthWeekdayOfMonth(ny, nm, wd, n);
+      } else if (sub === 'last') {
+        const wd = parseInt(parts[2], 10);
+        target = _lastWeekdayOfMonth(ny, nm, wd);
+      } else {
+        d = null; return;
+      }
+      target.setHours(hh, mm, 0, 0);
+      d = target;
+      return;
+    }
+    d = null;
+  }
+
+  step();
+  if (d === null) return null;
+  const now = clock.now();
+  // Cap catch-up to avoid runaway on a malformed/very-old date.
+  let guard = 5000;
+  while (d.getTime() <= now) {
+    if (--guard <= 0) return null;
+    step();
+    if (d === null) return null;
+  }
+  return _toLocalDatetimeStr(d);
+}
diff --git a/static/js/features/notes/index.js b/static/js/features/notes/index.js
new file mode 100644
index 000000000..146844b8a
--- /dev/null
+++ b/static/js/features/notes/index.js
@@ -0,0 +1,503 @@
+/** Notes composition and intentional public API. The legacy entry activates compatibility startup. */
+import { createSelectionOperations } from './application/selection.js';
+import { createToolbar } from './ui/toolbar.js';
+import { createWindowLayout } from './ui/windowLayout.js';
+import { createCardOperations } from './application/cardOperations.js';
+import { createChecklistOperations } from './application/checklistOperations.js';
+import { createNotesSubmission } from './application/submission.js';
+import { createNotesDrafts } from './application/drafts.js';
+import { createNotesLifecycle } from './ui/lifecycle.js';
+import * as noteRules from './domain/noteRules.js';
+import { createText } from './ui/text.js';
+import { createColors } from './ui/colors.js';
+import { createPanel } from './ui/panel.js';
+import { createReminderDisplay } from './ui/reminderDisplay.js';
+import { createSelection } from './ui/selection.js';
+import { createFilters } from './ui/filters.js';
+import { createCardRendering } from './ui/cardRendering.js';
+import { createLayout } from './ui/layout.js';
+import { createQuickAdd } from './ui/quickAdd.js';
+import { createCardInteractions } from './ui/cardInteractions.js';
+import { createCardChecklist } from './ui/cardChecklist.js';
+import { createCardReorder } from './ui/cardReorder.js';
+import { createDraftEditor } from './ui/draftEditor.js';
+import { createEditor } from './ui/editor.js';
+import { createReminderPicker } from './ui/reminderPicker.js';
+import { createChecklist } from './ui/checklist.js';
+import { createDrawing } from './ui/drawing.js';
+import { createClipboard } from './ui/clipboard.js';
+import { createMobileEditor } from './ui/mobileEditor.js';
+import { createMobileReorder } from './ui/mobileReorder.js';
+import { createChecklistReorder } from './ui/checklistReorder.js';
+import { createQueries } from './application/queries.js';
+import { createAgentActions } from './application/agentActions.js';
+import { createDeletion } from './application/deletion.js';
+import { createNotesReminders } from './application/reminders.js';
+import { createNotesNotifications } from './infrastructure/notifications.js';
+import { createNotesState } from './application/state.js';
+import { createNotesWorkflows } from './application/workflows.js';
+import { createNotesApi } from './infrastructure/http.js';
+import { createNotesPersistence, REMINDER_DISMISSED_AT_KEY, NOTES_FIRST_OPEN_HINT_KEY, NOTES_LABELS_COLLAPSED_KEY } from './infrastructure/storage.js';
+import * as dates from './domain/recurrence.js';
+import uiModule from '/static/js/ui.js?v=20260916largetoolscroll1';
+import { spawnConfetti } from '/static/js/shared/ui/confetti.js';
+import * as Modals from '/static/js/modalManager.js';
+import { attachColorPicker } from '/static/js/colorPicker.js?v=20260910eyedropper1';
+import { makeWindowDraggable } from '/static/js/windowDrag.js';
+import { snapModalToZone } from '/static/js/tileManager.js?v=20260910responsivebounds1';
+import { applyEdgeDock, clearDockSide } from '/static/js/modalSnap.js';
+import { topToolWindowZ, topPortalZ } from '/static/js/toolWindowZOrder.js';
+import { bindMenuDismiss, dismissOrRemove } from '/static/js/escMenuStack.js';
+import { bindTourHintDismiss } from '/static/js/tourHintDismiss.js';
+
+const api = createNotesApi({ origin: window.location.origin, request: (...args) => fetch(...args) });
+const persistence = createNotesPersistence({ storage: typeof localStorage === 'undefined' ? undefined : localStorage });
+const { _loadPendingHighlights, _loadGlowedReminders, _saveGlowedReminders, _loadActiveHighlights, _saveActiveHighlights, _savePendingHighlights, _loadFiredReminders, _saveFiredReminders, _draftKey, _loadDraft, _clearDraft } = persistence;
+const clock = { now: () => Date.now() };
+const app = createNotesState({
+ viewMode: (typeof localStorage !== 'undefined' && localStorage.getItem('odysseus-notes-view')) || 'list',
+ labelsCollapsed: typeof localStorage !== 'undefined' && localStorage.getItem(NOTES_LABELS_COLLAPSED_KEY) === '1',
+ firedDotDismissedAt: (() => { try { const v = parseInt(persistence.getItem(REMINDER_DISMISSED_AT_KEY) || '0', 10); return Number.isFinite(v) && v > 0 ? v : 0; } catch { return 0; } })(),
+});
+const state = app.state;
+const lifecycle = createNotesLifecycle();
+const scheduler = { setTimeout: (...args) => setTimeout(...args), clearTimeout: id => clearTimeout(id), setInterval: (...args) => setInterval(...args), clearInterval: id => clearInterval(id) };
+const notifications = createNotesNotifications({ browser: window, notify: window.Notification, openPanel: () => openPanel(), toast: title => uiModule?.showToast?.(title) });
+const reminders = createNotesReminders({
+  app,
+  api,
+  persistence,
+  notifications,
+  clock,
+  scheduler,
+  fetchNotes: () => _fetchNotes(),
+  isNoteFullyDone: note => _isNoteFullyDone(note),
+  hasItems: note => _hasItems(note),
+  dismissedKey: REMINDER_DISMISSED_AT_KEY,
+  effects: { badge: () => _updateRailBadge(), highlight: id => {
+ _setReminderCardGlow(id, true);
+ const card = document.querySelector(`.note-card[data-note-id="${id}"]`);
+ if (card) { card.classList.add('note-card-reminder-fired'); setTimeout(() => card.classList.remove('note-card-reminder-fired'), 3000); }
+ else _queuePendingHighlight(id);
+} }
+});
+const workflows = createNotesWorkflows({
+  app,
+  api,
+  effects: {
+ render: () => _renderNotes(),
+ showError: (...args) => uiModule.showError(...args),
+ archived: undo => uiModule.showToast('Archived', { duration: 6000, action: 'Undo', actionIcon: _NOTE_UNDO_ICON, onAction: undo, actionHint: 'Ctrl+Z' }),
+ celebrateArchive: (note, card) => { if (_hasItems(note) && !(note.items || []).some(i => !i.done)) { const r = card.getBoundingClientRect(); spawnConfetti(r.left + r.width / 2, r.top + r.height / 2, 80); } },
+}
+});
+const _NOTE_UNDO_ICON = '<svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round" style="vertical-align:middle;"><polyline points="9 14 4 9 9 4"/><path d="M4 9h11a5 5 0 0 1 5 5v0a5 5 0 0 1-5 5H9"/></svg>';
+function _pushUndo(entry) { return workflows._pushUndo(entry); }
+function _popAndRunUndo() { return workflows._popAndRunUndo(); }
+function _undoArchive(note, prevIdx) { return workflows._undoArchive(note, prevIdx); }
+function _archiveNoteById(id, options) { return workflows._archiveNoteById(id, options); }
+function _fetchNotes() { return workflows._fetchNotes(); }
+
+function _deleteNoteApi(id) { return workflows._deleteNoteApi(id); }
+function _patchNote(id, patch) { return workflows._patchNote(id, patch); }
+function _uid() { return Math.random().toString(36).slice(2, 10); }
+function _formatDueDate(dateStr) { return dates._formatDueDate(dateStr, clock); }
+function _isDueOverdue(dateStr) { return dates._isDueOverdue(dateStr, clock); }
+
+function _laterTodayDate() { return dates._laterTodayDate(clock); }
+function _tomorrowDate() { return dates._tomorrowDate(clock); }
+function _nextWeekDate() { return dates._nextWeekDate(clock); }
+function _formatReminderTag(dateStr) { return dates._formatReminderTag(dateStr, clock); }
+function _snapToRepeat(currentDate, normRepeat) { return dates._snapToRepeat(currentDate, normRepeat, clock); }
+function _ensureNotificationPermission() { return notifications.ensurePermission(); }
+
+function _startReminderLoop() { return reminders._startReminderLoop(); }
+
+function _countFiredReminders() { return reminders._countFiredReminders(); }
+
+function _hasActiveReminder(...args) { return noteRules._hasActiveReminder(...args, clock); }
+const _isNoteFullyDone = noteRules._isNoteFullyDone;
+const _hasItems = noteRules._hasItems;
+function _isPastReminder(...args) { return noteRules._isPastReminder(...args, clock); }
+function _esc(...args) { return text._esc(...args); }
+
+function _safeImgSrc(...args) { return text._safeImgSrc(...args); }
+function _linkify(...args) { return text._linkify(...args); }
+function _isBgImage(...args) { return colors._isBgImage(...args); }
+
+function _dotBg(...args) { return colors._dotBg(...args); }
+function _dotIsActive(...args) { return colors._dotIsActive(...args); }
+function _customColorStyle(...args) { return colors._customColorStyle(...args); }
+function _pickCustomBgImage(...args) { return colors._pickCustomBgImage(...args); }
+function _wireFormColors(...args) { return colors._wireFormColors(...args); }
+
+function openPanel(...args) { return panel.openPanel(...args); }
+
+function _smoothScrollToNoteCard(...args) { return panel._smoothScrollToNoteCard(...args); }
+function _clearViewedReminderGlows(...args) { return reminderDisplay._clearViewedReminderGlows(...args); }
+function _setReminderCardGlow(...args) { return reminderDisplay._setReminderCardGlow(...args); }
+function _queuePendingHighlight(...args) { return reminderDisplay._queuePendingHighlight(...args); }
+function _flushPendingHighlights(...args) { return reminderDisplay._flushPendingHighlights(...args); }
+function _updateRailBadge(...args) { return reminderDisplay._updateRailBadge(...args); }
+function _enterSelectMode(...args) { return selection._enterSelectMode(...args); }
+function _exitSelectMode(...args) { return selection._exitSelectMode(...args); }
+function _updateBulkBar(...args) { return selection._updateBulkBar(...args); }
+
+function _renderLabelsInto(...args) { return filters._renderLabelsInto(...args); }
+function _renderLoadingSkeleton(...args) { return cardRendering._renderLoadingSkeleton(...args); }
+function _renderNotes(...args) { return cardRendering._renderNotes(...args); }
+function _captureCardPositions(...args) { return layout._captureCardPositions(...args); }
+function _animateReflow(...args) { return layout._animateReflow(...args); }
+function _applyMasonry(...args) { return layout._applyMasonry(...args); }
+function _renderQuickAdd(...args) { return quickAdd._renderQuickAdd(...args); }
+
+function _editNote(...args) { return quickAdd._editNote(...args); }
+function _bindCardEvents(...args) { return cardInteractions._bindCardEvents(...args); }
+function _wireCardChecklist(...args) { return cardChecklist._wireCardChecklist(...args); }
+function _wireTodayView(...args) { return cardChecklist._wireTodayView(...args); }
+function _wireCardReorder(...args) { return cardReorder._wireCardReorder(...args); }
+
+function _wireDraftAutosave(...args) { return draftEditor._wireDraftAutosave(...args); }
+function _commitOpenInPlaceEditor(...args) { return draftEditor._commitOpenInPlaceEditor(...args); }
+function _applyDraftToNote(...args) { return draftEditor._applyDraftToNote(...args); }
+function _buildForm(...args) { return editor._buildForm(...args); }
+function _wireReminderPicker(...args) { return reminderPicker._wireReminderPicker(...args); }
+function _buildGoalHtml(...args) { return checklist._buildGoalHtml(...args); }
+function _wireGoalForm(...args) { return checklist._wireGoalForm(...args); }
+function _buildChecklistHtml(...args) { return checklist._buildChecklistHtml(...args); }
+function _wireRow(...args) { return checklist._wireRow(...args); }
+function _wireChecklist(...args) { return checklist._wireChecklist(...args); }
+function _collectItems(...args) { return checklist._collectItems(...args); }
+function _buildDrawHtml(...args) { return drawing._buildDrawHtml(...args); }
+function _wireCanvas(...args) { return drawing._wireCanvas(...args); }
+function _uploadCanvasAsPng(...args) { return drawing._uploadCanvasAsPng(...args); }
+function _openNoteCornerMenu(...args) { return clipboard._openNoteCornerMenu(...args); }
+function _copyNote(...args) { return clipboard._copyNote(...args); }
+function _isNotesMobileMode(...args) { return mobileEditor._isNotesMobileMode(...args); }
+function _openMobileFullscreenEdit(...args) { return mobileEditor._openMobileFullscreenEdit(...args); }
+function _closeMobileFullscreenEdit(...args) { return mobileEditor._closeMobileFullscreenEdit(...args); }
+
+function _bindLongPressDrag(...args) { return mobileReorder._bindLongPressDrag(...args); }
+
+function _wireChecklistTouchReorder(...args) { return checklistReorder._wireChecklistTouchReorder(...args); }
+
+function _sortedVisibleNotes(...args) { return queries._sortedVisibleNotes(...args); }
+function _userVisibleNotes(...args) { return queries._userVisibleNotes(...args); }
+function _agentSolveNote(...args) { return agentActions._agentSolveNote(...args); }
+
+function _clearPastReminders(...args) { return deletion._clearPastReminders(...args); }
+const text = createText({
+  uiModule
+});
+const colors = createColors({
+  api
+});
+const { COLORS, COLOR_HEX } = colors;
+const windowLayout = createWindowLayout({
+  makeWindowDraggable,
+  snapModalToZone,
+  clearDockSide,
+  applyEdgeDock,
+  topToolWindowZ
+});
+const toolbar = createToolbar({
+  app,
+  state,
+  persistence,
+  _renderNotes,
+  _fetchNotes,
+  _applyMasonry
+});
+const panel = createPanel({
+  wireToolbar: toolbar.wireToolbar,
+  wireSelectionActions: () => selection.wireSelectionActions(),
+  _wireNotesWindow: windowLayout._wireNotesWindow,
+  _restoreNotesSidebarDock: windowLayout._restoreNotesSidebarDock,
+  _bringNotesToFront: windowLayout._bringNotesToFront,
+  disposeUI: () => { layout.dispose(); mobileReorder.dispose(); checklistReorder.dispose(); lifecycle.dispose(); },
+  lifecycle,
+  Modals,
+  NOTES_FIRST_OPEN_HINT_KEY,
+  REMINDER_DISMISSED_AT_KEY,
+  _clearViewedReminderGlows,
+  _closeMobileFullscreenEdit,
+  _commitOpenInPlaceEditor,
+  _copyNote,
+  _enterSelectMode,
+  _exitSelectMode,
+  _fetchNotes,
+  _flushPendingHighlights,
+  _isNotesMobileMode,
+  _popAndRunUndo,
+  _renderLoadingSkeleton,
+  _renderNotes,
+  _startReminderLoop,
+  app,
+  bindTourHintDismiss,
+  dismissOrRemove,
+  persistence,
+  state,
+  workflows
+});
+const reminderDisplay = createReminderDisplay({
+  _countFiredReminders,
+  _hasActiveReminder,
+  _loadActiveHighlights,
+  _loadGlowedReminders,
+  _loadPendingHighlights,
+  _saveActiveHighlights,
+  _saveGlowedReminders,
+  _savePendingHighlights,
+  _smoothScrollToNoteCard,
+  state
+});
+const selectionOperations = createSelectionOperations({
+  app,
+  api,
+  fetchNotes: _fetchNotes,
+  exitSelection: _exitSelectMode,
+  sendContext: detail => window.dispatchEvent(new CustomEvent('odysseus:notes-context-selected', { detail })),
+  effects: { render: _renderNotes, styledConfirm: uiModule.styledConfirm, showToast: (...args) => uiModule.showToast(...args) }
+});
+const selection = createSelection({
+  operations: selectionOperations,
+  _renderNotes,
+  app,
+  state
+});
+const filters = createFilters({
+  NOTES_LABELS_COLLAPSED_KEY,
+  _clearPastReminders,
+  _esc,
+  _isPastReminder,
+  _renderNotes,
+  _userVisibleNotes,
+  app,
+  persistence,
+  state
+});
+const cardRendering = createCardRendering({
+  COLORS,
+  COLOR_HEX,
+  _animateReflow,
+  _applyMasonry,
+  _bindCardEvents,
+  _captureCardPositions,
+  _customColorStyle,
+  _dotBg,
+  _dotIsActive,
+  _esc,
+  _formatDueDate,
+  _formatReminderTag,
+  _hasActiveReminder,
+  _isBgImage,
+  _isDueOverdue,
+  _isNotesMobileMode,
+  _linkify,
+  _loadActiveHighlights,
+  _renderLabelsInto,
+  _renderQuickAdd,
+  _safeImgSrc,
+  _sortedVisibleNotes,
+  _updateRailBadge,
+  _wireTodayView,
+  state,
+  uiModule
+});
+const layout = createLayout({
+  isOpen: () => state.open
+});
+const quickAdd = createQuickAdd({
+  _applyDraftToNote,
+  _applyMasonry,
+  _buildForm,
+  app,
+  openPanel,
+  state,
+  uiModule
+});
+const cardOperations = createCardOperations({
+  app,
+  api,
+  pushUndo: _pushUndo,
+  undoArchive: _undoArchive,
+  effects: { render: _renderNotes, showError: (...args) => uiModule.showError(...args), showToast: (...args) => uiModule.showToast(...args), archived: undo => uiModule.showToast('Archived', { duration: 6000, action: 'Undo', actionIcon: _NOTE_UNDO_ICON, onAction: undo, actionHint: 'Ctrl+Z' }) }
+});
+const checklistOperations = createChecklistOperations({
+  app,
+  api,
+  uid: _uid,
+  effects: { render: _renderNotes, showError: (...args) => uiModule.showError(...args) }
+});
+const cardInteractions = createCardInteractions({
+  cardOperations,
+  COLORS,
+  _archiveNoteById,
+  _bindLongPressDrag,
+  _customColorStyle,
+  _dotBg,
+  _dotIsActive,
+  _editNote,
+  _isBgImage,
+  _isNotesMobileMode,
+  _openMobileFullscreenEdit,
+  _openNoteCornerMenu,
+  _pickCustomBgImage,
+  _renderNotes,
+  _setReminderCardGlow,
+  _smoothScrollToNoteCard,
+  _updateBulkBar,
+  _wireCardChecklist,
+  _wireCardReorder,
+  app,
+  spawnConfetti,
+  state,
+  uiModule
+});
+const cardChecklist = createCardChecklist({
+  checklistOperations,
+  _editNote,
+  _renderNotes,
+  app,
+  spawnConfetti,
+  state
+});
+const cardReorder = createCardReorder({
+  persistOrder: cardOperations.persistOrder,
+  lifecycle,
+  _isNotesMobileMode,
+  state
+});
+const draftEditor = createDraftEditor({
+  bindDraft: (...args) => drafts.bindDraft(...args),
+  _collectItems,
+  _loadDraft
+});
+const editor = createEditor({
+  deleteFromEditor: id => deletion.deleteFromEditor(id),
+  submitNote: (...args) => submission.submitNote(...args),
+  COLORS,
+  _applyMasonry,
+  _archiveNoteById,
+  _buildChecklistHtml,
+  _buildDrawHtml,
+  _buildGoalHtml,
+  _collectItems,
+  _customColorStyle,
+  _dotBg,
+  _dotIsActive,
+  _esc,
+  _isBgImage,
+  _renderNotes,
+  _safeImgSrc,
+  _uid,
+  _uploadCanvasAsPng,
+  _wireCanvas,
+  _wireChecklist,
+  _wireDraftAutosave,
+  _wireFormColors,
+  _wireGoalForm,
+  _wireReminderPicker,
+  api,
+  app,
+  state,
+  uiModule
+});
+const reminderPicker = createReminderPicker({
+  lifecycle,
+  _ensureNotificationPermission,
+  _esc,
+  _formatReminderTag,
+  _laterTodayDate,
+  _nextWeekDate,
+  _snapToRepeat,
+  _tomorrowDate,
+  bindMenuDismiss,
+  dismissOrRemove
+});
+const checklist = createChecklist({
+  _esc,
+  _uid,
+  spawnConfetti
+});
+const drawing = createDrawing({
+  lifecycle,
+  _safeImgSrc,
+  api,
+  attachColorPicker
+});
+const clipboard = createClipboard({
+  _agentSolveNote,
+  bindMenuDismiss,
+  dismissOrRemove,
+  state,
+  topPortalZ,
+  uiModule
+});
+const mobileEditor = createMobileEditor({
+  _applyDraftToNote,
+  _buildForm,
+  _fetchNotes,
+  _linkify,
+  _renderNotes,
+  _uid,
+  _wireChecklistTouchReorder,
+  _wireRow,
+  app,
+  state,
+  uiModule
+});
+const mobileReorder = createMobileReorder({
+  commitMobileOrder: cardOperations.commitMobileOrder,
+  lifecycle,
+  _applyMasonry,
+  _enterSelectMode,
+  app
+});
+const checklistReorder = createChecklistReorder({
+  lifecycle
+});
+const queries = createQueries({
+  _hasActiveReminder,
+  state
+});
+const agentActions = createAgentActions({
+  _patchNote,
+  _renderNotes,
+  api,
+  app,
+  createFormData: () => new FormData(),
+  state,
+  streamComplete: sid => { try { window.sessionModule?.markStreamComplete?.(sid); } catch {} },
+  uiModule
+});
+const deletion = createDeletion({
+  app,
+  _deleteNoteApi,
+  _fetchNotes,
+  _isPastReminder,
+  _renderNotes,
+  effects: { styledConfirm: uiModule.styledConfirm, confirm: message => confirm(message), showToast: (...args) => uiModule.showToast(...args), showError: (...args) => uiModule.showError(...args) },
+  state
+});
+const notesModule = { openPanel: panel.openPanel, closePanel: panel.closePanel, togglePanel: panel.togglePanel, isPanelOpen: panel.isPanelOpen, openNote: panel.openNote, newNote: quickAdd.newNote, openNotes: panel.openPanel, closeNotes: panel.closePanel, isNotesOpen: panel.isPanelOpen, refreshDueBadge: reminders.refreshDueBadge };
+const publicOpenPanel = panel.openPanel, publicClosePanel = panel.closePanel, publicTogglePanel = panel.togglePanel, publicIsPanelOpen = panel.isPanelOpen, publicOpenNote = panel.openNote, publicNewNote = quickAdd.newNote, publicRefreshDueBadge = reminders.refreshDueBadge, publicDismissFiredReminderDot = reminders.dismissFiredReminderDot;
+export { publicOpenPanel as openPanel, publicClosePanel as closePanel, publicTogglePanel as togglePanel, publicIsPanelOpen as isPanelOpen, publicOpenNote as openNote, publicNewNote as newNote, publicRefreshDueBadge as refreshDueBadge, publicDismissFiredReminderDot as dismissFiredReminderDot, publicOpenPanel as openNotes, publicClosePanel as closeNotes, publicIsPanelOpen as isNotesOpen };
+export function startNotesBackground() { reminders.start(); }
+export default notesModule;
+const submission = createNotesSubmission({
+  app,
+  api,
+  persistence,
+  clock,
+  uid: _uid,
+  fetchNotes: _fetchNotes,
+  effects: { render: _renderNotes, showError: (...args) => uiModule.showError(...args), clearGlow: id => _setReminderCardGlow(id, false) }
+});
+const drafts = createNotesDrafts({
+  app,
+  api,
+  persistence,
+  scheduler,
+  effects: { showError: (...args) => uiModule.showError(...args) }
+});
diff --git a/static/js/features/notes/infrastructure/http.js b/static/js/features/notes/infrastructure/http.js
new file mode 100644
index 000000000..eeafd1b0f
--- /dev/null
+++ b/static/js/features/notes/infrastructure/http.js
@@ -0,0 +1,29 @@
+/** Notes HTTP port. Response interpretation stays with the owning workflow. */
+export function createNotesApi({ origin, request }) {
+  const json = (method, body) => ({ method, credentials: 'same-origin', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(body) });
+  async function saveNote(note) {
+    const response = await request(note.id ? `${origin}/api/notes/${note.id}` : `${origin}/api/notes`, json(note.id ? 'PUT' : 'POST', note));
+    if (!response.ok) throw new Error('Failed to save note');
+    return await response.json();
+  }
+  async function patchNote(id, patch) {
+    const response = await request(`${origin}/api/notes/${id}`, json('PUT', patch));
+    if (!response.ok) throw new Error('Failed to update note');
+    return await response.json();
+  }
+  async function deleteNote(id) {
+    const response = await request(`${origin}/api/notes/${id}`, { method: 'DELETE', credentials: 'same-origin' });
+    if (!response.ok) throw new Error('HTTP ' + response.status);
+  }
+  return {
+    saveNote, patchNote, deleteNote,
+    listNotes: archived => request(`${origin}/api/notes${archived ? '?archived=true' : ''}`, { credentials: 'same-origin' }),
+    reorder: ids => request(`${origin}/api/notes/reorder`, json('POST', { ids })),
+    upload: body => request(`${origin}/api/upload`, { method: 'POST', body, credentials: 'same-origin' }),
+    uploadUrl: id => `${origin}/api/upload/${id}`,
+    fireReminder: body => request('/api/notes/fire-reminder', json('POST', body)),
+    defaultChat: () => request(`${origin}/api/default-chat`, { credentials: 'same-origin' }),
+    createSession: body => request(`${origin}/api/session`, { method: 'POST', body, credentials: 'same-origin' }),
+    startChat: body => request(`${origin}/api/chat_stream`, { method: 'POST', body, credentials: 'same-origin' }),
+  };
+}
diff --git a/static/js/features/notes/infrastructure/notifications.js b/static/js/features/notes/infrastructure/notifications.js
new file mode 100644
index 000000000..cd98eb702
--- /dev/null
+++ b/static/js/features/notes/infrastructure/notifications.js
@@ -0,0 +1,20 @@
+/** Browser notification permission/display port, independent of Notes rendering. */
+export function createNotesNotifications({ browser, notify, openPanel, toast }) {
+  async function ensurePermission() {
+    if (!('Notification' in browser)) return false;
+    if (notify.permission === 'granted') return true;
+    if (notify.permission === 'denied') return false;
+    try { return await notify.requestPermission() === 'granted'; }
+    catch { return false; }
+  }
+  function show(title, body, noteId) {
+    if ('Notification' in browser && notify.permission === 'granted') {
+      try {
+        const notification = new notify(title, { body, tag: 'note-' + noteId, icon: '/static/favicon.ico' });
+        notification.onclick = () => { browser.focus(); openPanel(); notification.close(); };
+      } catch {}
+    }
+    toast(title);
+  }
+  return { ensurePermission, show };
+}
diff --git a/static/js/features/notes/infrastructure/storage.js b/static/js/features/notes/infrastructure/storage.js
new file mode 100644
index 000000000..06aaa01ab
--- /dev/null
+++ b/static/js/features/notes/infrastructure/storage.js
@@ -0,0 +1,63 @@
+/** Browser persistence and unchanged Notes key/serialization contracts. */
+export const REMINDER_FIRED_KEY = 'odysseus-notes-reminder-fired';
+export const REMINDER_GLOWED_KEY = 'odysseus-notes-reminder-glowed';
+export const REMINDER_PENDING_HIGHLIGHT_KEY = 'odysseus-notes-reminder-pending-highlight';
+export const REMINDER_ACTIVE_HIGHLIGHT_KEY = 'odysseus-notes-reminder-active-highlight';
+export const REMINDER_DISMISSED_AT_KEY = 'odysseus-notes-reminder-dismissed-at';
+export const NOTES_FIRST_OPEN_HINT_KEY = 'odysseus-notes-first-open-hint-v1';
+export const NOTES_LABELS_COLLAPSED_KEY = 'odysseus-notes-labels-collapsed';
+export const _DRAFT_PREFIX = 'odysseus-note-draft-';
+
+export function createNotesPersistence({ storage: localStorage }) {
+function _loadPendingHighlights() {
+  try { return new Set(JSON.parse(localStorage.getItem(REMINDER_PENDING_HIGHLIGHT_KEY) || '[]')); }
+  catch { return new Set(); }
+}
+
+function _loadGlowedReminders() {
+  try { return new Set(JSON.parse(localStorage.getItem(REMINDER_GLOWED_KEY) || '[]')); }
+  catch { return new Set(); }
+}
+
+function _saveGlowedReminders(set) {
+  try { localStorage.setItem(REMINDER_GLOWED_KEY, JSON.stringify([...set])); } catch {}
+}
+
+function _loadActiveHighlights() {
+  try { return new Set(JSON.parse(localStorage.getItem(REMINDER_ACTIVE_HIGHLIGHT_KEY) || '[]')); }
+  catch { return new Set(); }
+}
+
+function _saveActiveHighlights(set) {
+  try { localStorage.setItem(REMINDER_ACTIVE_HIGHLIGHT_KEY, JSON.stringify([...set])); } catch {}
+}
+
+function _savePendingHighlights(set) {
+  try { localStorage.setItem(REMINDER_PENDING_HIGHLIGHT_KEY, JSON.stringify([...set])); }
+  catch {}
+}
+
+function _loadFiredReminders() {
+  try { return new Set(JSON.parse(localStorage.getItem(REMINDER_FIRED_KEY) || '[]')); }
+  catch { return new Set(); }
+}
+
+function _saveFiredReminders(set) {
+  try { localStorage.setItem(REMINDER_FIRED_KEY, JSON.stringify([...set])); }
+  catch {}
+}
+
+function _draftKey(id) { return _DRAFT_PREFIX + (id || '__new__'); }
+
+function _loadDraft(id) {
+  try { return JSON.parse(localStorage.getItem(_draftKey(id)) || 'null'); } catch { return null; }
+}
+
+function _clearDraft(id) { try { localStorage.removeItem(_draftKey(id)); } catch {} }
+
+return { _loadPendingHighlights, _loadGlowedReminders, _saveGlowedReminders, _loadActiveHighlights, _saveActiveHighlights, _savePendingHighlights, _loadFiredReminders, _saveFiredReminders, _draftKey, _loadDraft, _clearDraft,
+  getItem: key => localStorage.getItem(key),
+  setItem: (key, value) => localStorage.setItem(key, value),
+  removeItem: key => localStorage.removeItem(key),
+};
+}
diff --git a/static/js/features/notes/ui/cardChecklist.js b/static/js/features/notes/ui/cardChecklist.js
new file mode 100644
index 000000000..6bbf39326
--- /dev/null
+++ b/static/js/features/notes/ui/cardChecklist.js
@@ -0,0 +1,148 @@
+/** Card checklist editing and Today-step interactions. */
+export function createCardChecklist({
+  checklistOperations,
+  _editNote,
+  _renderNotes,
+  app,
+  spawnConfetti,
+  state
+}) {
+  function _wireCardChecklist(body) {
+    // Remove a single checklist item (hover X)
+    body.querySelectorAll('.note-checkbox-rm').forEach(btn => {
+      btn.addEventListener('click', (e) => {
+        e.stopPropagation();
+        if (state.selectMode) return;
+        const noteId = btn.dataset.noteId;
+        const idx = parseInt(btn.dataset.idx);
+        checklistOperations.removeItem(noteId, idx);
+      });
+    });
+
+    function _startChecklistItemEdit(noteId, idx, span) {
+      if (span.isContentEditable) return;
+      const note = state.notes.find(n => n.id === noteId);
+      if (!note || !Array.isArray(note.items) || !note.items[idx]) return;
+
+      span.textContent = note.items[idx].text || '';
+      span.contentEditable = "true";
+      span.spellcheck = false;
+      span.focus();
+
+      const selection = window.getSelection();
+      const range = document.createRange();
+      range.selectNodeContents(span);
+      selection.removeAllRanges();
+      selection.addRange(range);
+
+      const save = () => {
+        if (!span.isContentEditable) return;
+        span.contentEditable = "false";
+        const newText = span.textContent.trim();
+        checklistOperations.editItem(note, idx, newText);
+      };
+
+      const onKeydown = (e) => {
+        if (e.key === 'Enter') {
+          e.preventDefault();
+          save();
+        } else if (e.key === 'Escape') {
+          e.preventDefault();
+          span.contentEditable = "false";
+          _renderNotes();
+        }
+      };
+
+      span.addEventListener('blur', save, { once: true });
+      span.addEventListener('keydown', onKeydown);
+    }
+
+    // Edit a single checklist item (hover Edit button)
+    body.querySelectorAll('.note-checkbox-edit').forEach(btn => {
+      btn.addEventListener('click', (e) => {
+        e.stopPropagation();
+        if (state.selectMode) return;
+        const noteId = btn.dataset.noteId;
+        const idx = parseInt(btn.dataset.idx);
+        const span = btn.parentElement.querySelector('.note-check-text');
+        if (span) _startChecklistItemEdit(noteId, idx, span);
+      });
+    });
+
+    // Prevent clicks from toggling the row while actively editing inline
+    body.querySelectorAll('.note-check-text').forEach(span => {
+      span.addEventListener('click', (e) => {
+        if (span.isContentEditable) {
+          e.stopPropagation();
+        }
+      });
+    });
+
+    // Quick-add new checklist item (hover input at bottom of todo cards)
+    body.querySelectorAll('.note-cl-quickadd-input').forEach(input => {
+      input.addEventListener('click', (e) => e.stopPropagation());
+      input.addEventListener('keydown', async (e) => {
+        e.stopPropagation();
+        if (e.key !== 'Enter') return;
+        e.preventDefault();
+        const text = input.value.trim();
+        if (!text) return;
+        const noteId = input.dataset.noteId;
+        const persist = checklistOperations.addItem(noteId, text, () => { input.value = ''; });
+        if (!persist) return;
+        // Refocus the input on the same card
+        setTimeout(() => {
+          const next = document.querySelector(`.note-cl-quickadd-input[data-note-id="${noteId}"]`);
+          if (next) next.focus();
+        }, 0);
+        persist();
+      });
+    });
+
+    // Checkboxes (dot toggle, optimistic) : disabled in select mode
+    body.querySelectorAll('.note-checkbox').forEach(el => {
+      el.addEventListener('click', (e) => {
+        if (state.selectMode) return; // let card-level handler take over
+        e.preventDefault();
+        e.stopPropagation();
+        const noteId = el.dataset.noteId;
+        const idx = parseInt(el.dataset.idx);
+        checklistOperations.toggleItem(noteId, idx, done => el.classList.toggle('done', done), () => {
+          const card = el.closest('.note-card');
+          if (card) { const r = card.getBoundingClientRect(); spawnConfetti(r.left + r.width / 2, r.top + r.height / 2, 60); }
+        });
+      });
+    });
+
+
+  }
+
+  function _wireTodayView(body) {
+    body.querySelectorAll('.notes-today-row .note-check-dot').forEach(dot => {
+      dot.addEventListener('click', async (e) => {
+        e.stopPropagation();
+        const id = dot.dataset.noteId;
+        const idx = parseInt(dot.dataset.idx);
+        const row = dot.closest('.notes-today-row');
+        await checklistOperations.toggleTodayStep(id, idx, () => row?.classList.add('done'), () => {
+          const r = (row || dot).getBoundingClientRect();
+          spawnConfetti(r.left + r.width / 2, r.top + r.height / 2, 60);
+        });
+      });
+    });
+    body.querySelectorAll('.notes-today-title').forEach(el => {
+      el.addEventListener('click', () => {
+        const id = el.dataset.noteId;
+        if (!id) return;
+        // Drop the Today filter first so the regular card list is rendered;
+        // _editNote needs to find a .note-card in the DOM to replace with
+        // the editor form.
+        app.setActiveFilter(null);
+        _renderNotes();
+        _editNote(id);
+      });
+    });
+  }
+
+  return { _wireCardChecklist, _wireTodayView };
+}
diff --git a/static/js/features/notes/ui/cardInteractions.js b/static/js/features/notes/ui/cardInteractions.js
new file mode 100644
index 000000000..09e083c41
--- /dev/null
+++ b/static/js/features/notes/ui/cardInteractions.js
@@ -0,0 +1,337 @@
+/** Card taps, pin/color controls, menus and archive animation. */
+export function createCardInteractions({
+  cardOperations,
+  COLORS,
+  _archiveNoteById,
+  _bindLongPressDrag,
+  _customColorStyle,
+  _dotBg,
+  _dotIsActive,
+  _editNote,
+  _isBgImage,
+  _isNotesMobileMode,
+  _openMobileFullscreenEdit,
+  _openNoteCornerMenu,
+  _pickCustomBgImage,
+  _renderNotes,
+  _setReminderCardGlow,
+  _smoothScrollToNoteCard,
+  _updateBulkBar,
+  _wireCardChecklist,
+  _wireCardReorder,
+  app,
+  spawnConfetti,
+  state,
+  uiModule
+}) {
+  function _bindCardEvents(body) {
+    // Skip completed leading rows so the first unfinished checklist item is
+    // visible when a note preview has its own scroll area.
+    requestAnimationFrame(() => {
+      body.querySelectorAll('.note-checklist-preview').forEach(preview => {
+        const firstPending = preview.querySelector('.note-checkbox:not(.done)');
+        if (firstPending) preview.scrollTop = Math.max(0, firstPending.offsetTop - 4);
+      });
+    });
+    const tapToEditOrSelect = (cardEl) => {
+      const id = cardEl.dataset.noteId;
+      // A long-press enters select mode and re-renders the card. Ignore the
+      // synthetic click that mobile browsers emit when that same touch ends.
+      if (state.suppressNextNoteTapId === id) {
+        app.setSuppressNextNoteTapId(null);
+        return;
+      }
+      if (state.selectMode) {
+        const cb = cardEl.querySelector('.note-card-cb');
+        if (cb) {
+          cb.checked = !cb.checked;
+          cb.dispatchEvent(new Event('change'));
+        }
+      } else if (_isNotesMobileMode()) {
+        // Mobile: open the per-note fullscreen edit overlay instead of the
+        // in-place form. Tiles on mobile are read-only previews.
+        _openMobileFullscreenEdit(id, cardEl);
+      } else {
+        _editNote(id);
+      }
+    };
+    // Mobile: long-press anywhere on a note card → enter Select mode and
+    // select that card. Cancelled by movement (so it doesn't interfere with
+    // vertical scrolling) or by lifting the finger before the timer fires.
+    if (_isNotesMobileMode()) {
+      body.querySelectorAll('.note-card').forEach(card => _bindLongPressDrag(card));
+    }
+    body.querySelectorAll('.note-card.note-card-reminder-fired-sticky').forEach(card => {
+      card.addEventListener('click', () => _setReminderCardGlow(card.dataset.noteId, false), true);
+    });
+    // Click title : edit, or toggle select in select mode
+    body.querySelectorAll('.note-card-title[data-action="edit"]').forEach(el => {
+      el.addEventListener('click', (e) => {
+        e.stopPropagation();
+        _smoothScrollToNoteCard(el.closest('.note-card'));
+        tapToEditOrSelect(el.closest('.note-card'));
+      });
+    });
+    // Click content : edit, or toggle select in select mode
+    body.querySelectorAll('.note-content-preview').forEach(el => {
+      el.addEventListener('click', (e) => { e.stopPropagation(); tapToEditOrSelect(el.closest('.note-card')); });
+    });
+    // A saved drawing is the note's primary content. Open its editor directly
+    // when the preview is clicked, matching title/content preview behavior.
+    body.querySelectorAll('.note-card-drawing .note-card-image').forEach(el => {
+      el.addEventListener('click', (e) => {
+        e.stopPropagation();
+        tapToEditOrSelect(el.closest('.note-card'));
+      });
+    });
+    // Click empty area of checklist preview (not on checkbox/X) : edit
+    body.querySelectorAll('.note-checklist-preview').forEach(el => {
+      el.addEventListener('wheel', (e) => {
+        const atTop = el.scrollTop <= 0;
+        const atBottom = el.scrollTop + el.clientHeight >= el.scrollHeight - 1;
+        if ((e.deltaY < 0 && atTop) || (e.deltaY > 0 && atBottom)) {
+          const pane = el.closest('.notes-pane-body');
+          if (pane) {
+            pane.scrollTop += e.deltaY;
+            e.preventDefault();
+          }
+        }
+      }, { passive: false });
+      el.addEventListener('click', (e) => {
+        if (e.target.closest('.note-checkbox, .note-checkbox-rm, .note-cl-quickadd, input')) return;
+        e.stopPropagation();
+        tapToEditOrSelect(el.closest('.note-card'));
+      });
+    });
+    // Clicking todo item text now toggles its checkbox : let the click bubble
+    // up to the parent .note-checkbox row handler. To open the editor, the
+    // user clicks the pencil corner.
+    // (No-op block kept as a marker : removing the listener entirely means
+    // clicks naturally bubble to the row toggle below.)
+    // In select mode, clicking anywhere on the card toggles selection
+    if (state.selectMode) {
+      body.querySelectorAll('.note-card').forEach(card => {
+        card.addEventListener('click', (e) => {
+          if (e.target.closest('.note-card-cb')) return; // checkbox handles itself
+          e.stopPropagation();
+          tapToEditOrSelect(card);
+        });
+      });
+    }
+    // Mobile, non-select: tapping anywhere on the card body (not on an
+    // interactive child : buttons, pin, checkbox, color dot, reminder pill,
+    // agent tag, links) opens the fullscreen editor. Previously only the
+    // title / content preview triggered edit, so padding + empty gutters were
+    // dead zones that felt broken on mobile.
+    if (_isNotesMobileMode() && !state.selectMode) {
+      const _INTERACTIVE = 'button, a, input, label, .note-card-color-dot, .note-checkbox, .note-checkbox-rm, .note-cl-quickadd, .note-agent-tag, .note-card-pin, .note-card-corner-trash, .note-card-corner-menu, .note-card-corner-unarchive, .note-card-edit-corner, .note-card-reminder, .note-card-cb';
+      body.querySelectorAll('.note-card').forEach(card => {
+        card.addEventListener('click', (e) => {
+          if (e.target.closest(_INTERACTIVE)) return;
+          e.stopPropagation();
+          tapToEditOrSelect(card);
+        });
+      });
+    }
+    // Multi-select checkbox (only in select mode)
+    body.querySelectorAll('.note-card-cb').forEach(cb => {
+      cb.addEventListener('click', (e) => e.stopPropagation());
+      cb.addEventListener('change', () => {
+        const id = cb.dataset.noteId;
+        if (cb.checked) app.selectId(id);
+        else app.deselectId(id);
+        cb.closest('.note-card').classList.toggle('note-card-selected', cb.checked);
+        _updateBulkBar();
+      });
+    });
+    // Pin toggle (optimistic)
+    body.querySelectorAll('.note-card-pin').forEach(btn => {
+      btn.addEventListener('click', (e) => {
+        e.stopPropagation();
+        const id = btn.dataset.noteId;
+        cardOperations.togglePin(id);
+      });
+    });
+    // Color picker
+    const _applyCardColor = async (card, id, newColor) => {
+      const isBg = _isBgImage(newColor);
+      COLORS.forEach(c => { if (c.value && c.value !== 'custom') card.classList.remove('note-color-' + c.value); });
+      if (newColor && !isBg) card.classList.add('note-color-' + newColor);
+      if (isBg) card.setAttribute('style', _customColorStyle(newColor));
+      else card.removeAttribute('style');
+      card.querySelectorAll('.note-card-color-dot').forEach(d => {
+        d.classList.toggle('active', _dotIsActive(d.dataset.color, newColor));
+        d.style.background = _dotBg(d.dataset.color, newColor);
+      });
+      await cardOperations.updateColor(id, newColor);
+    };
+    body.querySelectorAll('.note-card-color-dot').forEach(dot => {
+      dot.addEventListener('click', (e) => {
+        e.stopPropagation();
+        const card = dot.closest('.note-card');
+        const id = card.dataset.noteId;
+        if (dot.dataset.color === 'custom') {
+          _pickCustomBgImage().then(url => { if (url) _applyCardColor(card, id, 'bg:' + url); });
+          return;
+        }
+        _applyCardColor(card, id, dot.dataset.color);
+      });
+    });
+    // Plain pencil corner → open editor. The unarchive corner shares the
+    // .note-card-edit-corner class for styling, so :not() keeps the edit
+    // handler off it.
+    body.querySelectorAll('.note-card-edit-corner:not(.note-card-unarchive-corner)').forEach(btn => {
+      btn.addEventListener('click', (e) => {
+        e.stopPropagation();
+        const id = btn.dataset.noteId;
+        if (id) _editNote(id);
+      });
+    });
+    // Copy corner : bottom-right, just left of the Done check. Shared with
+     // the Ctrl/Cmd+C shortcut wired further down so both code paths run the
+     // same serializer + feedback flash.
+    // ⋯ corner menu : Copy + Agent (solve-this-todo).
+    body.querySelectorAll('.note-card-corner-menu').forEach(btn => {
+      btn.addEventListener('click', (e) => {
+        e.preventDefault();
+        e.stopPropagation();
+        _openNoteCornerMenu(btn);
+      });
+    });
+    body.querySelectorAll('.note-card-label-chip').forEach(chip => {
+      chip.addEventListener('click', (e) => {
+        e.preventDefault();
+        e.stopPropagation();
+        const label = chip.dataset.noteLabelFilter;
+        if (!label) return;
+        if (state.activeLabel === label && state.activeFilter === null) {
+          app.setActiveLabel(null);
+        } else {
+          app.setActiveFilter(null);
+          app.setActiveLabel(label);
+        }
+        _renderNotes();
+      });
+    });
+    // Done (✓) at bottom-right : only visible on hover for active notes.
+    body.querySelectorAll('.note-card-done').forEach(btn => {
+      btn.addEventListener('click', (e) => {
+        e.stopPropagation();
+        const id = btn.dataset.noteId;
+        const card = btn.closest('.note-card');
+        const idx = state.notes.findIndex(n => n.id === id);
+        if (idx < 0) return;
+        // Celebrate completion : same confetti shower the bulk-archive uses.
+        if (card) {
+          const r = card.getBoundingClientRect();
+          spawnConfetti(r.left + r.width / 2, r.top + r.height / 2, 80);
+        }
+        const finish = cardOperations.stageArchive(id);
+        if (!finish) return;
+        if (card) {
+          card.classList.add('note-card-sliding-out');
+          let done = false;
+          const once = () => { if (done) return; done = true; finish(); };
+          card.addEventListener('transitionend', once, { once: true });
+          setTimeout(once, 400);
+        } else {
+          finish();
+        }
+      });
+    });
+    // Unarchive corner : only visible in archive view.
+    body.querySelectorAll('.note-card-corner-unarchive').forEach(btn => {
+      btn.addEventListener('click', (e) => {
+        e.stopPropagation();
+        const id = btn.dataset.noteId;
+        cardOperations.unarchive(id);
+      });
+    });
+    // Trash corner : archive view only. Permanent delete, no confirmation.
+    body.querySelectorAll('.note-card-corner-trash').forEach(btn => {
+      btn.addEventListener('click', (e) => {
+        e.stopPropagation();
+        const id = btn.dataset.noteId;
+        cardOperations.deleteOptimistically(id, true);
+      });
+    });
+
+    body.querySelectorAll('.note-card-archive').forEach(btn => {
+      btn.addEventListener('click', (e) => {
+        e.stopPropagation();
+        const id = btn.dataset.noteId;
+        if (!id) return;
+        const card = btn.closest('.note-card');
+        let done = false;
+        const finishRemove = () => {
+          if (done) return;
+          done = true;
+          _archiveNoteById(id, { card, celebrate: true });
+        };
+        if (card) {
+          card.classList.add('note-card-sliding-out');
+          card.addEventListener('transitionend', finishRemove, { once: true });
+          setTimeout(finishRemove, 400);
+        } else {
+          finishRemove();
+        }
+      });
+    });
+    // Unarchive (optimistic) : only present in archive view
+    body.querySelectorAll('.note-card-unarchive').forEach(btn => {
+      btn.addEventListener('click', (e) => {
+        e.stopPropagation();
+        const id = btn.dataset.noteId;
+        cardOperations.unarchive(id);
+      });
+    });
+    // Delete (optimistic)
+    body.querySelectorAll('.note-card-delete, .note-card-x').forEach(btn => {
+      btn.addEventListener('click', (e) => {
+        e.stopPropagation();
+        const id = btn.dataset.noteId;
+        cardOperations.deleteOptimistically(id);
+      });
+    });
+    // Copy entire checklist (title + items, markdown-style)
+    body.querySelectorAll('.note-card-copy').forEach(btn => {
+      btn.addEventListener('click', async (e) => {
+        e.preventDefault();
+        e.stopPropagation();
+        e.stopImmediatePropagation();
+        const id = btn.dataset.noteId;
+        const note = state.notes.find(n => n.id === id);
+        if (!note) return;
+        const lines = [];
+        if (note.title) lines.push(note.title);
+        if (note.content) lines.push(note.content);
+        if (lines.length) lines.push('');
+        for (const it of (note.items || [])) {
+          if (!it || !(it.text || '').trim()) continue;
+          lines.push(`- [${it.done ? 'x' : ' '}] ${(it.text || '').trim()}`);
+        }
+        const text = lines.join('\n').trim();
+        try {
+          await navigator.clipboard.writeText(text);
+          uiModule.showToast?.(`Copied ${(note.items || []).filter(i => (i?.text || '').trim()).length} items`);
+        } catch {
+          // Fallback for browsers blocking the async API
+          const ta = document.createElement('textarea');
+          ta.value = text;
+          ta.style.position = 'fixed'; ta.style.left = '-9999px';
+          document.body.appendChild(ta);
+          ta.select();
+          try { document.execCommand('copy'); uiModule.showToast?.('Copied'); }
+          catch { uiModule.showError?.('Copy failed'); }
+          ta.remove();
+        }
+      });
+    });
+
+    _wireCardChecklist(body);
+    _wireCardReorder(body);
+
+  }
+
+  return { _bindCardEvents };
+}
diff --git a/static/js/features/notes/ui/cardRendering.js b/static/js/features/notes/ui/cardRendering.js
new file mode 100644
index 000000000..315e47218
--- /dev/null
+++ b/static/js/features/notes/ui/cardRendering.js
@@ -0,0 +1,244 @@
+/** Render note cards from application queries and read-only state. */
+import { _nextGoalStep, _goalProgress, _hasItems, _standardVisualVariant, _visibleNoteTags } from '../domain/noteRules.js';
+import { _hasTimeComponent, _formatRepeatLabel } from '../domain/recurrence.js';
+export function createCardRendering({
+  COLORS,
+  COLOR_HEX,
+  _animateReflow,
+  _applyMasonry,
+  _bindCardEvents,
+  _captureCardPositions,
+  _customColorStyle,
+  _dotBg,
+  _dotIsActive,
+  _esc,
+  _formatDueDate,
+  _formatReminderTag,
+  _hasActiveReminder,
+  _isBgImage,
+  _isDueOverdue,
+  _isNotesMobileMode,
+  _linkify,
+  _loadActiveHighlights,
+  _renderLabelsInto,
+  _renderQuickAdd,
+  _safeImgSrc,
+  _sortedVisibleNotes,
+  _updateRailBadge,
+  _wireTodayView,
+  state,
+  uiModule
+}) {
+  function _renderLoadingSkeleton() {
+    const body = document.querySelector('#notes-pane .notes-pane-body');
+    if (!body) return;
+    body.innerHTML = '';
+    _renderLabelsInto(body);
+    _renderQuickAdd(body);
+    const skel = document.createElement('div');
+    skel.className = 'notes-skeleton';
+    skel.innerHTML = `
+    <div class="notes-skeleton-card"></div>
+    <div class="notes-skeleton-card"></div>
+    <div class="notes-skeleton-card short"></div>
+    <div class="notes-skeleton-card"></div>
+  `;
+    body.appendChild(skel);
+  }
+
+  function _renderNotes() {
+    _updateRailBadge();
+    const body = document.querySelector('#notes-pane .notes-pane-body');
+    if (!body) return;
+    const prevPositions = _captureCardPositions();
+    const activeReminderHighlights = _loadActiveHighlights();
+
+    const sorted = _sortedVisibleNotes();
+
+    let html = '';
+    // Today view: render a compact card listing the next-unchecked step from
+    // each active goal. Tapping a step toggles it done (same idx-based wiring
+    // as regular checkboxes). Tapping the title opens the goal note for full
+    // editing.
+    if (state.activeFilter === 'today') {
+      body.innerHTML = '';
+      _renderLabelsInto(body);
+      _renderQuickAdd(body);
+      if (sorted.length === 0) {
+        body.insertAdjacentHTML('beforeend', `<div class="notes-empty">All caught up — no pending goal steps right now.</div>`);
+      } else {
+        let todayHtml = `<div class="notes-today-wrap">
+        <div class="notes-today-header">
+          <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="3" y="4" width="18" height="18" rx="2"/><line x1="16" y1="2" x2="16" y2="6"/><line x1="8" y1="2" x2="8" y2="6"/><line x1="3" y1="10" x2="21" y2="10"/></svg>
+          <span>Today &middot; one step per goal</span>
+        </div>
+        <div class="notes-today-list">`;
+        for (const note of sorted) {
+          const next = _nextGoalStep(note);
+          if (!next) continue;
+          const progress = _goalProgress(note).trim();
+          todayHtml += `<div class="notes-today-row" data-note-id="${note.id}">
+          <span class="note-check-dot" data-note-id="${note.id}" data-idx="${next.idx}" title="Mark step done"></span>
+          <div class="notes-today-text">
+            <div class="notes-today-title" data-action="edit" data-note-id="${note.id}">${_esc(note.title || '(untitled goal)')}</div>
+            <div class="notes-today-step">${_linkify(next.item.text || '')}</div>
+          </div>
+          <span class="notes-today-progress">${_esc(progress)}</span>
+        </div>`;
+        }
+        todayHtml += `</div></div>`;
+        body.insertAdjacentHTML('beforeend', todayHtml);
+      }
+      _wireTodayView(body);
+      return;
+    }
+    for (const note of sorted) {
+      if (state.editingId === note.id) continue; // skip : form is shown instead
+      const borderColor = COLOR_HEX[note.color || ''] || 'var(--border)';
+      const dueFmt = _formatDueDate(note.due_date);
+      const overdue = _isDueOverdue(note.due_date);
+
+      let contentHtml = '';
+      if (_hasItems(note) && Array.isArray(note.items)) {
+        // Goal notes can carry a free-form description above the step list :
+        // todos rarely do, but the same render works for both.
+        if (note.note_type === 'goal' && (note.content || '').trim()) {
+          const fullText = note.content || '';
+          const preview = fullText.length > 300 ? fullText.slice(0, 300) + '…' : fullText;
+          contentHtml += `<div class="note-goal-desc">${_esc(preview)}</div>`;
+        }
+        contentHtml += '<div class="note-checklist-preview">';
+        // Show ALL items : the preview container is scrollable (CSS caps
+        // its max-height + overflow-y:auto), so there's no need to truncate.
+        for (let i = 0; i < note.items.length; i++) {
+          const item = note.items[i];
+          const doneClass = item.done ? ' done' : '';
+          const indent = Math.min(item.indent || 0, 3);
+          contentHtml += `<div class="note-checkbox${doneClass}" data-note-id="${note.id}" data-idx="${i}" style="padding-left:${indent * 16}px">
+          <span class="note-check-dot" title="Mark done"></span>
+          <span class="note-check-text">${_linkify(item.text)}</span>
+          <button class="note-checkbox-edit" data-note-id="${note.id}" data-idx="${i}" title="Edit item">
+            <svg width="10" height="10" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M11 4H4a2 2 0 0 0-2 2v14a2 2 0 0 0 2 2h14a2 2 0 0 0 2-2v-7"/><path d="M18.5 2.5a2.121 2.121 0 0 1 3 3L12 15l-4 1 1-4 9.5-9.5z"/></svg>
+          </button>
+          <button class="note-checkbox-rm" data-note-id="${note.id}" data-idx="${i}" title="Delete item">
+            <svg width="10" height="10" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round"><line x1="18" y1="6" x2="6" y2="18"/><line x1="6" y1="6" x2="18" y2="18"/></svg>
+          </button>
+        </div>`;
+        }
+        contentHtml += '</div>';
+      } else {
+        const fullText = note.content || '';
+        const preview = fullText.length > 600 ? fullText.slice(0, 600) + '…' : fullText;
+        // _linkify already calls _esc internally, so URLs become clickable
+        // anchors (used by e.g. the "remind me to reply" email deep-link).
+        contentHtml = preview ? `<div class="note-content-preview">${_linkify(preview)}</div>` : '';
+      }
+
+      const isBg = _isBgImage(note.color);
+      const cc = (note.color && !isBg) ? ' note-color-' + note.color : '';
+      const cardStyle = isBg ? ` style="${_customColorStyle(note.color)}"` : '';
+      const isStandard = !note.note_type || note.note_type === 'note';
+      const visualClass = isStandard && !note.color ? ` note-standard note-standard-v${_standardVisualVariant(note)}` : '';
+      const sel = state.selectedIds.has(note.id) ? ' note-card-selected' : '';
+      const reminderTagHtml = note.due_date && _hasTimeComponent(note.due_date)
+        ? `<div class="note-card-reminder${overdue ? ' overdue' : ''}">
+          <svg width="10" height="10" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round"><path d="M18 8A6 6 0 0 0 6 8c0 7-3 9-3 9h18s-3-2-3-9"/><path d="M13.73 21a2 2 0 0 1-3.46 0"/></svg>
+          <span>${_esc(_formatReminderTag(note.due_date))}${note.repeat && note.repeat !== 'none' ? ' · ' + _esc(_formatRepeatLabel(note.repeat, new Date(note.due_date))) : ''}</span>
+        </div>`
+        : '';
+      const noteTags = _visibleNoteTags(note);
+      const dueBadge = dueFmt && !_hasTimeComponent(note.due_date) ? `<span class="note-due-inline${overdue ? ' note-due-overdue' : ''}">${dueFmt}</span>` : '';
+      const colorDots = COLORS.map(c => `<span class="note-card-color-dot${_dotIsActive(c.value, note.color) ? ' active' : ''}" data-color="${c.value}" style="background:${_dotBg(c.value, note.color)}" title="${c.name || 'default'}"></span>`).join('');
+      const goalClass = note.note_type === 'goal' ? ' note-card-goal' : '';
+      const reminderGlowClass = activeReminderHighlights.has(note.id) && _hasActiveReminder(note) ? ' note-card-reminder-fired-sticky' : '';
+      const goalPill = note.note_type === 'goal'
+        ? `<span class="note-goal-pill" title="AI-broken-down goal">
+          <svg width="10" height="10" viewBox="0 0 24 24" fill="currentColor"><path d="M12 0L14.59 8.41L23 12L14.59 15.59L12 24L9.41 15.59L1 12L9.41 8.41Z"/></svg>
+          Goal${_goalProgress(note)}
+        </span>`
+        : '';
+      const drawingClass = note.note_type === 'draw' ? ' note-card-drawing' : '';
+      html += `<div class="note-card${note.pinned ? ' note-card-pinned' : ''}${cc}${visualClass}${sel}${goalClass}${drawingClass}${reminderGlowClass}${state.selectMode ? ' note-card-selectmode' : ''}" draggable="${(state.selectMode || _isNotesMobileMode()) ? 'false' : 'true'}" data-note-id="${note.id}"${cardStyle}>
+      ${state.selectMode ? `<input type="checkbox" class="memory-select-cb note-card-cb" data-note-id="${note.id}" ${state.selectedIds.has(note.id) ? 'checked' : ''} />` : ''}
+      ${goalPill}
+      <button class="note-card-pin${note.pinned ? ' active' : ''}" data-note-id="${note.id}" title="${note.pinned ? 'Unpin' : 'Pin'}">
+        <svg width="16" height="16" viewBox="0 0 24 28" fill="${note.pinned ? 'currentColor' : 'none'}" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"${note.pinned ? ' style="color:var(--accent,var(--red));"' : ''}><g transform="rotate(${note.pinned ? 0 : 45} 12 14)" style="transition:transform 0.2s ease;"><line x1="12" y1="17" x2="12" y2="27"/><path d="M5 17h14v-1.76a2 2 0 0 0-1.11-1.79l-1.78-.9A2 2 0 0 1 15 10.76V6h1a2 2 0 0 0 0-4H8a2 2 0 0 0 0 4h1v4.76a2 2 0 0 1-1.11 1.79l-1.78.9A2 2 0 0 0 5 15.24V17z"/></g></svg>
+      </button>
+      ${state.showingArchived
+          ? `<button class="note-card-corner-trash" data-note-id="${note.id}" title="Delete forever" aria-label="Delete forever">
+            <svg width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><polyline points="3 6 5 6 21 6"/><path d="M19 6l-1 14a2 2 0 0 1-2 2H8a2 2 0 0 1-2-2L5 6"/><path d="M8 6V4a2 2 0 0 1 2-2h4a2 2 0 0 1 2 2v2"/><line x1="10" y1="11" x2="10" y2="17"/><line x1="14" y1="11" x2="14" y2="17"/></svg>
+          </button>
+          <button class="note-card-corner-unarchive" data-note-id="${note.id}" title="Unarchive" aria-label="Unarchive note">
+            <svg width="17" height="17" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round"><path d="M9 14l-5-5 5-5"/><path d="M4 9h11a5 5 0 0 1 5 5v0a5 5 0 0 1-5 5H9"/></svg>
+          </button>`
+          : `<button class="note-card-done" data-note-id="${note.id}" title="Mark done" aria-label="Mark done">
+            <svg width="17" height="17" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.4" stroke-linecap="round" stroke-linejoin="round"><polyline points="20 6 9 17 4 12"/></svg>
+          </button>
+          ${_hasItems(note) ? `<button class="note-card-copy note-card-copy-corner" data-note-id="${note.id}" title="Copy all items" aria-label="Copy all items">
+            <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="9" y="9" width="13" height="13" rx="2"/><path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"/></svg>
+          </button>` : ''}`}
+      <div class="note-card-header">
+        <div class="note-card-title${note.title ? '' : ' empty'}" data-action="edit">${_esc(note.title || '')}</div>
+        ${dueBadge}
+      </div>
+      ${_safeImgSrc(note.image_url) ? `<img class="note-card-image" src="${_esc(_safeImgSrc(note.image_url))}" alt="" draggable="false" />` : ''}
+      ${contentHtml}
+      ${_hasItems(note) ? `<div class="note-cl-quickadd"><input type="text" class="note-cl-quickadd-input" placeholder="+ Add item" data-note-id="${note.id}" /></div>` : ''}
+      ${reminderTagHtml}
+      ${noteTags.length ? `<div class="note-card-label">${noteTags.map(t => `<button type="button" class="note-card-label-chip" data-note-label-filter="${_esc(t)}" title="Filter #${_esc(t)}">#${_esc(t)}</button>`).join(' ')}</div>` : ''}
+      <div class="note-card-actions">
+        <div class="note-card-colors">${colorDots}</div>
+        <span style="flex:1"></span>
+        ${state.showingArchived ? `
+        <button class="note-card-action note-card-delete" data-note-id="${note.id}" title="Delete permanently">
+          <svg width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><polyline points="3 6 5 6 21 6"/><path d="M19 6l-1 14a2 2 0 0 1-2 2H8a2 2 0 0 1-2-2L5 6"/><path d="M8 6V4a2 2 0 0 1 2-2h4a2 2 0 0 1 2 2v2"/><line x1="10" y1="11" x2="10" y2="17"/><line x1="14" y1="11" x2="14" y2="17"/></svg>
+        </button>
+        <button class="note-card-action note-card-unarchive" data-note-id="${note.id}" title="Unarchive">
+          <svg width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M3 12a9 9 0 1 0 3-6.7"/><polyline points="3 4 3 10 9 10"/></svg>
+        </button>` : `
+        ${_hasItems(note) ? `
+        <button class="note-card-action note-card-copy" data-note-id="${note.id}" title="Copy all items">
+          <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="9" y="9" width="13" height="13" rx="2"/><path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"/></svg>
+        </button>` : ''}
+        <button class="note-card-action note-card-archive" data-note-id="${note.id}" title="Save (archive)">
+          <svg width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M19 21H5a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2h11l5 5v11a2 2 0 0 1-2 2z"/><polyline points="17 21 17 13 7 13 7 21"/><polyline points="7 3 7 8 15 8"/></svg>
+        </button>
+        <button class="note-card-action note-card-delete" data-note-id="${note.id}" title="Delete">
+          <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round"><line x1="18" y1="6" x2="6" y2="18"/><line x1="6" y1="6" x2="18" y2="18"/></svg>
+        </button>
+        <button class="note-card-action note-card-corner-menu" data-note-id="${note.id}" title="More" aria-label="More actions">
+          <svg width="16" height="16" viewBox="0 0 24 24" fill="currentColor"><circle cx="5" cy="12" r="1.7"/><circle cx="12" cy="12" r="1.7"/><circle cx="19" cy="12" r="1.7"/></svg>
+        </button>`}
+      </div>
+    </div>`;
+    }
+
+    // Always render quick-add at top (collapsed unless user is typing)
+    const existingForm = body.querySelector('.note-form');
+    if (existingForm && state.editingId === '__new__') {
+      // Keep the expanded form, replace cards after it
+      const next = [...body.children].filter(c => c !== existingForm);
+      next.forEach(c => c.remove());
+      if (sorted.length === 0) {
+        body.insertAdjacentHTML('beforeend', '<div class="notes-empty-msg">No notes <span style="vertical-align:-3px;margin-left:4px;">' + uiModule.emptyStateIcon('smiley') + '</span></div>');
+      } else {
+        existingForm.insertAdjacentHTML('afterend', html);
+      }
+    } else {
+      body.innerHTML = '';
+      _renderLabelsInto(body);
+      _renderQuickAdd(body);
+      if (sorted.length === 0) {
+        body.insertAdjacentHTML('beforeend', '<div class="notes-empty-msg">No notes yet <span style="vertical-align:-3px;margin-left:4px;">' + uiModule.emptyStateIcon('smiley') + '</span></div>');
+      } else {
+        body.insertAdjacentHTML('beforeend', html);
+      }
+    }
+
+    _bindCardEvents(body);
+    _animateReflow(prevPositions);
+    _applyMasonry(body);
+  }
+
+  return { _renderLoadingSkeleton, _renderNotes };
+}
diff --git a/static/js/features/notes/ui/cardReorder.js b/static/js/features/notes/ui/cardReorder.js
new file mode 100644
index 000000000..dd32d517c
--- /dev/null
+++ b/static/js/features/notes/ui/cardReorder.js
@@ -0,0 +1,181 @@
+/** Desktop and large-touch-device card reorder gestures. */
+export function createCardReorder({
+  lifecycle,
+  _isNotesMobileMode,
+  persistOrder,
+  state
+}) {
+  function _wireCardReorder(body) {
+    lifecycle.release(body);
+    // Drag-reorder notes on pointer/mouse devices. Mobile uses the custom
+    // placeholder sorter below `_bindLongPressDrag`; native HTML5 dragging is
+    // unreliable on touch browsers and can compete with the long-press flow.
+    if (!_isNotesMobileMode()) {
+      body.querySelectorAll('.note-card').forEach(card => {
+        card.addEventListener('dragstart', (e) => {
+          if (e.target.closest('.note-checkbox, .note-card-x, .note-card-select, .note-card-pin, .note-card-action, .note-card-color-dot, .note-card-title, .note-card-edit, .note-card-edit-corner, .note-card-done, .note-card-corner-menu, .note-agent-tag, .note-card-label-chip')) {
+            e.preventDefault();
+            return;
+          }
+          card.classList.add('dragging');
+          body.classList.add('drag-active');
+          e.dataTransfer.effectAllowed = 'move';
+          try { e.dataTransfer.setData('text/plain', card.dataset.noteId); } catch {}
+        });
+        card.addEventListener('dragend', async () => {
+          card.classList.remove('dragging');
+          body.classList.remove('drag-active');
+          body.querySelectorAll('.drop-before, .drop-after').forEach(el => el.classList.remove('drop-before', 'drop-after'));
+          const ids = [...body.querySelectorAll('.note-card')].map(c => c.dataset.noteId);
+          try { await persistOrder(ids); }
+          catch {}
+        });
+      });
+    }
+    // Track which card we last swapped with so a single hover-over triggers
+    // one swap, not a jitter as the pointer keeps moving inside the same card.
+    let _lastSwapId = null;
+    function _maybeSwap(dragging, clientX, clientY) {
+      const target = document.elementFromPoint(clientX, clientY)?.closest('.note-card');
+      if (!target || target === dragging || !body.contains(target)) return;
+      const id = target.dataset.noteId;
+      if (id === _lastSwapId) return;
+      // FLIP across ALL siblings. In list view only `target` moves visually, but
+      // in grid view (2-col) and when the pinned-section grid-column-start rule
+      // shifts, several cards reflow at once. Capture every card's pre-swap rect,
+      // do the DOM swap, then animate any that actually moved. The dragging card
+      // is excluded : it's already finger-tracked via translate3d.
+      const cards = [...body.querySelectorAll('.note-card')].filter(c => c !== dragging);
+      const prevRects = new Map(cards.map(c => [c, c.getBoundingClientRect()]));
+      const draggingNext = dragging.nextSibling === target ? dragging : dragging.nextSibling;
+      body.insertBefore(dragging, target);
+      body.insertBefore(target, draggingNext);
+      for (const c of cards) {
+        const prev = prevRects.get(c);
+        const next = c.getBoundingClientRect();
+        const dx = prev.left - next.left;
+        const dy = prev.top - next.top;
+        if (Math.abs(dx) < 0.5 && Math.abs(dy) < 0.5) continue;
+        c.style.transition = 'none';
+        c.style.transform = `translate(${dx}px, ${dy}px)`;
+        requestAnimationFrame(() => {
+          c.style.transition = 'transform 0.22s cubic-bezier(0.34, 1.2, 0.64, 1)';
+          c.style.transform = '';
+          c.addEventListener('transitionend', () => { c.style.transition = ''; }, { once: true });
+        });
+      }
+      _lastSwapId = id;
+    }
+    lifecycle.listen(body, body, 'dragover', (e) => {
+      e.preventDefault();
+      const dragging = body.querySelector('.note-card.dragging');
+      if (!dragging) return;
+      _maybeSwap(dragging, e.clientX, e.clientY);
+    });
+    lifecycle.listen(body, body, 'dragend', () => { _lastSwapId = null; });
+
+    // Legacy touch drag for larger touch devices only. Phone-sized Notes uses
+    // the placeholder sorter wired by `_bindLongPressDrag`; running both flows
+    // makes one press start two independent drag sessions.
+    if (!_isNotesMobileMode() && 'ontouchstart' in window) {
+      let dragCard = null;
+      let isDragging = false;
+      let longPressTimer = null;
+      let startX = 0, startY = 0;
+      const LONG_PRESS_MS = 350;
+      const MOVE_THRESHOLD_PX = 8;
+      const _selectorSkip = '.note-checkbox, .note-card-x, .note-card-select, .note-card-pin, .note-card-action, .note-card-color-dot, .note-card-title, .note-card-edit, .note-card-edit-corner, .note-card-done, .note-card-corner-menu, .note-agent-tag, .note-card-label-chip, input, textarea, button, a';
+
+      // Anchor for the finger-follow transform. Recomputed after every swap so
+      // the card stays under the finger across reorderings.
+      let anchorX = 0, anchorY = 0;
+      const _follow = (clientX, clientY) => {
+        if (!dragCard) return;
+        const dx = clientX - anchorX;
+        const dy = clientY - anchorY;
+        // Compose with the CSS .dragging transform (scale + rotate).
+        dragCard.style.transform = `translate3d(${dx}px, ${dy}px, 0) scale(1.03) rotate(-0.6deg)`;
+      };
+      const _reanchor = (clientX, clientY) => {
+        if (!dragCard) return;
+        // Clear any prior translate so the card resettles in its natural slot,
+        // then anchor at the finger's current position. Subsequent _follow calls
+        // translate by (finger - anchor), keeping the finger at the same relative
+        // spot on the card it had when we re-anchored.
+        dragCard.style.transform = '';
+        anchorX = clientX;
+        anchorY = clientY;
+      };
+
+      const _endDrag = (committed) => {
+        clearTimeout(longPressTimer);
+        longPressTimer = null;
+        if (dragCard) {
+          dragCard.classList.remove('dragging');
+          dragCard.style.transform = '';
+        }
+        body.classList.remove('drag-active');
+        _lastSwapId = null;
+        if (isDragging) {
+          document.documentElement.style.touchAction = '';
+          if (committed) {
+            const ids = [...body.querySelectorAll('.note-card')].map(c => c.dataset.noteId);
+            persistOrder(ids).catch(() => {});
+          }
+        }
+        dragCard = null;
+        isDragging = false;
+      };
+      lifecycle.onDispose(body, () => _endDrag(false));
+
+      lifecycle.listen(body, body, 'touchstart', (e) => {
+        if (state.selectMode) return;
+        const card = e.target.closest('.note-card');
+        if (!card) return;
+        if (e.target.closest(_selectorSkip)) return;
+        const t = e.touches[0];
+        startX = t.clientX; startY = t.clientY;
+        dragCard = card;
+        longPressTimer = setTimeout(() => {
+          if (!dragCard) return;
+          isDragging = true;
+          dragCard.classList.add('dragging');
+          body.classList.add('drag-active');
+          document.documentElement.style.touchAction = 'none';
+          _reanchor(startX, startY);
+          try { if (navigator.vibrate) navigator.vibrate(15); } catch {}
+        }, LONG_PRESS_MS);
+      }, { passive: true });
+
+      lifecycle.listen(body, body, 'touchmove', (e) => {
+        if (!dragCard) return;
+        const t = e.touches[0];
+        if (!isDragging) {
+          // Movement before long-press fires = user is scrolling; cancel pickup.
+          if (Math.abs(t.clientX - startX) > MOVE_THRESHOLD_PX || Math.abs(t.clientY - startY) > MOVE_THRESHOLD_PX) {
+            clearTimeout(longPressTimer);
+            longPressTimer = null;
+            dragCard = null;
+          }
+          return;
+        }
+        e.preventDefault();
+        // Live-follow the finger first, then check for a swap. After a swap the
+        // card's natural slot moves, so we re-anchor and re-apply the offset.
+        _follow(t.clientX, t.clientY);
+        const before = dragCard.parentNode && [...dragCard.parentNode.children].indexOf(dragCard);
+        _maybeSwap(dragCard, t.clientX, t.clientY);
+        const after = dragCard.parentNode && [...dragCard.parentNode.children].indexOf(dragCard);
+        if (before !== after) {
+          _reanchor(t.clientX, t.clientY);
+          _follow(t.clientX, t.clientY);
+        }
+      }, { passive: false });
+
+      lifecycle.listen(body, body, 'touchend', () => _endDrag(true));
+      lifecycle.listen(body, body, 'touchcancel', () => _endDrag(false));
+    }
+  }
+
+  return { _wireCardReorder };
+}
diff --git a/static/js/features/notes/ui/checklist.js b/static/js/features/notes/ui/checklist.js
new file mode 100644
index 000000000..59a01aaa4
--- /dev/null
+++ b/static/js/features/notes/ui/checklist.js
@@ -0,0 +1,190 @@
+/** Checklist rows, goal forms, keyboard input and item collection. */
+export function createChecklist({
+  _esc,
+  _uid,
+  spawnConfetti
+}) {
+  function _buildGoalHtml(note, items) {
+    const desc = (note?.content || '').toString();
+    return `
+    <div class="note-form-goal">
+      <textarea class="note-form-goal-desc" placeholder="Description (optional)" rows="3">${_esc(desc)}</textarea>
+      ${_buildChecklistHtml(items)}
+    </div>
+  `;
+  }
+
+  function _wireGoalForm(form, container) {
+    if (!container) return;
+    // _wireHashtag is a closure inside _buildForm : out of scope here. Inline
+    // the same behavior (type "#foo " in the description → tag added to the
+    // form's label input) so editing a goal note doesn't ReferenceError.
+    const desc = container.querySelector('.note-form-goal-desc');
+    const labelInput = form?.querySelector('.note-form-label');
+    if (desc && labelInput) {
+      const tagRe = /(^|\s)#([A-Za-z0-9][\w-]*)\s$/;
+      desc.addEventListener('input', () => {
+        const m = tagRe.exec(desc.value);
+        if (!m) return;
+        const tag = m[2];
+        // Same dedup-after-stripping fix as the plain note hashtag handler.
+        const existing = labelInput.value.trim().split(/\s+/).filter(Boolean);
+        const stripped = existing.map(t => t.replace(/^#+/, ''));
+        if (!stripped.includes(tag)) {
+          existing.push('#' + tag);
+          labelInput.value = existing.join(' ');
+          labelInput.classList.add('flash-once');
+          setTimeout(() => labelInput.classList.remove('flash-once'), 600);
+        }
+        const cut = desc.value.length - m[0].length + m[1].length;
+        desc.value = desc.value.slice(0, cut);
+      });
+    }
+    // Always wire the checklist. The previous gate on a `note-form-goal-fresh`
+    // class was dead code : nothing ever set that class, so the editor never
+    // hooked up add/drag/Tab.
+    _wireChecklist(container);
+  }
+
+  function _buildChecklistHtml(items) {
+    let html = '<div class="note-checklist-inputs">';
+    for (const item of items) {
+      const indent = Math.min(item.indent || 0, 3);
+      html += `<div class="note-cl-row${item.done ? ' done' : ''}" draggable="true" data-item-id="${item.id || _uid()}" data-indent="${indent}" style="padding-left:${indent * 16}px">
+      <span class="note-cl-grip" title="Drag to reorder">⋮⋮</span>
+      <span class="note-cl-dot"></span>
+      <input type="text" class="note-cl-text" value="${_esc(item.text)}" placeholder="Item..." />
+      <button type="button" class="note-cl-rm">&times;</button>
+    </div>`;
+    }
+    // `type="button"` matters on mobile : without it some browsers treat
+    // bare <button> as form-submit and the click handler never fires inside
+    // certain containers. Also bumped tap target so fingers don't miss.
+    html += `<button type="button" class="note-cl-add">+ Add</button></div>`;
+    return html;
+  }
+
+  function _wireRow(row, container) {
+    row.querySelector('.note-cl-rm')?.addEventListener('click', () => row.remove());
+    row.querySelector('.note-cl-dot')?.addEventListener('click', () => {
+      const wasDone = row.classList.contains('done');
+      row.classList.toggle('done');
+      // The custom dot has no native input/change event. Notify the form so
+      // mobile edit mode switches its action from Archive back to Update.
+      container.dispatchEvent(new Event('input', { bubbles: true }));
+      const becameDone = !wasDone;  // we just flipped it
+      const dot = row.querySelector('.note-cl-dot');
+      const dRect = (dot || row).getBoundingClientRect();
+      // Small confetti burst on each fresh check so the user gets a
+      // "well done" beat per item, not just the grand-finale on all-done.
+      if (becameDone) {
+        spawnConfetti(dRect.left + dRect.width / 2, dRect.top + dRect.height / 2, 16);
+      }
+      // Bigger burst when the whole list is now done.
+      const rows = [...container.querySelectorAll('.note-cl-row')];
+      const hasText = rows.some(r => (r.querySelector('.note-cl-text')?.value || '').trim().length > 0);
+      if (hasText && rows.every(r => r.classList.contains('done') || !(r.querySelector('.note-cl-text')?.value || '').trim())) {
+        spawnConfetti(dRect.left + dRect.width / 2, dRect.top + dRect.height / 2, 60);
+      }
+    });
+    const txt = row.querySelector('.note-cl-text');
+    txt?.addEventListener('keydown', (e) => {
+      if (e.key === 'Enter') { e.preventDefault(); container.querySelector('.note-cl-add')?.click(); }
+      else if (e.key === 'Tab') {
+        e.preventDefault();
+        const cur = parseInt(row.dataset.indent || '0');
+        const next = e.shiftKey ? Math.max(0, cur - 1) : Math.min(3, cur + 1);
+        row.dataset.indent = String(next);
+        row.style.paddingLeft = (next * 16) + 'px';
+      } else if (e.key === 'Backspace' && txt.value === '') {
+        e.preventDefault();
+        const prev = row.previousElementSibling;
+        row.remove();
+        if (prev && prev.classList.contains('note-cl-row')) prev.querySelector('.note-cl-text')?.focus();
+      }
+    });
+    // Drag handlers
+    row.addEventListener('dragstart', (e) => {
+      row.classList.add('dragging');
+      e.dataTransfer.effectAllowed = 'move';
+      try { e.dataTransfer.setData('text/plain', row.dataset.itemId); } catch {}
+    });
+    row.addEventListener('dragend', () => {
+      row.classList.remove('dragging');
+      container.querySelectorAll('.drop-before, .drop-after').forEach(el => el.classList.remove('drop-before', 'drop-after'));
+    });
+  }
+
+  function _wireChecklist(container) {
+    if (!container) return;
+    // Delegate the + Add click off the container so re-renders + mobile
+    // touch quirks don't leave the button dead. The previous direct
+    // `addEventListener` on the button silently broke on mobile when
+    // _wireChecklist ran more than once (or before the button was in DOM).
+    if (!container._addDelegated) {
+      container._addDelegated = true;
+      container.addEventListener('click', (ev) => {
+        const addBtn = ev.target.closest('.note-cl-add');
+        if (!addBtn || !container.contains(addBtn)) return;
+        ev.preventDefault();
+        ev.stopPropagation();
+        const inputs = container.querySelector('.note-checklist-inputs');
+        if (!inputs) return;
+        const row = document.createElement('div');
+        row.className = 'note-cl-row';
+        row.draggable = true;
+        row.dataset.itemId = _uid();
+        row.dataset.indent = '0';
+        row.innerHTML = `<span class="note-cl-grip" title="Drag">⋮⋮</span><span class="note-cl-dot"></span><input type="text" class="note-cl-text" placeholder="Item..." /><button type="button" class="note-cl-rm">&times;</button>`;
+        inputs.insertBefore(row, addBtn);
+        row.querySelector('.note-cl-text').focus();
+        _wireRow(row, container);
+      });
+    }
+    container.querySelectorAll('.note-cl-row').forEach(row => _wireRow(row, container));
+
+    // Drag-over handler on the inputs container
+    const inputs = container.querySelector('.note-checklist-inputs');
+    if (inputs) {
+      inputs.addEventListener('dragover', (e) => {
+        e.preventDefault();
+        const dragging = inputs.querySelector('.note-cl-row.dragging');
+        if (!dragging) return;
+        inputs.querySelectorAll('.drop-before, .drop-after').forEach(el => el.classList.remove('drop-before', 'drop-after'));
+        const rows = [...inputs.querySelectorAll('.note-cl-row:not(.dragging)')];
+        const after = rows.find(r => {
+          const box = r.getBoundingClientRect();
+          return e.clientY < box.top + box.height / 2;
+        });
+        if (after) {
+          after.classList.add('drop-before');
+          inputs.insertBefore(dragging, after);
+        } else if (rows.length) {
+          rows[rows.length - 1].classList.add('drop-after');
+          inputs.insertBefore(dragging, container.querySelector('.note-cl-add'));
+        }
+      });
+      inputs.addEventListener('dragleave', (e) => {
+        if (!inputs.contains(e.relatedTarget)) {
+          inputs.querySelectorAll('.drop-before, .drop-after').forEach(el => el.classList.remove('drop-before', 'drop-after'));
+        }
+      });
+    }
+  }
+
+  function _collectItems(form) {
+    const items = [];
+    form.querySelectorAll('.note-cl-row').forEach(row => {
+      const text = row.querySelector('.note-cl-text')?.value?.trim();
+      if (text) items.push({
+        id: row.dataset.itemId || _uid(),
+        text,
+        done: row.classList.contains('done'),
+        indent: parseInt(row.dataset.indent || '0'),
+      });
+    });
+    return items;
+  }
+
+  return { _buildGoalHtml, _wireGoalForm, _buildChecklistHtml, _wireRow, _wireChecklist, _collectItems };
+}
diff --git a/static/js/features/notes/ui/checklistReorder.js b/static/js/features/notes/ui/checklistReorder.js
new file mode 100644
index 000000000..c5c7e1101
--- /dev/null
+++ b/static/js/features/notes/ui/checklistReorder.js
@@ -0,0 +1,111 @@
+/** Mobile checklist grip dragging and document listener ownership. */
+export function createChecklistReorder({
+  lifecycle
+}) {
+  let _clDrag = null;
+
+  let _clDocBound = false;
+  let _clOwner = null;
+
+  function _wireChecklistTouchReorder(form) {
+    const container = form.querySelector('.note-checklist-inputs');
+    if (!container) return;
+    container.querySelectorAll('.note-cl-grip').forEach(grip => {
+      if (grip.dataset.touchBound === '1') return;
+      grip.dataset.touchBound = '1';
+      grip.addEventListener('touchstart', (e) => {
+        if (e.touches.length !== 1) return;
+        e.preventDefault();
+        const row = grip.closest('.note-cl-row');
+        if (!row) return;
+        _beginChecklistGrab(row, container, e.touches[0]);
+      }, { passive: false });
+    });
+    if (!_clDocBound || _clOwner !== form) {
+      if (_clOwner) lifecycle.release(_clOwner);
+      _clOwner = form;
+      lifecycle.listen(form, document, 'touchmove', _onClTouchMove, { passive: false });
+      lifecycle.listen(form, document, 'touchend',  _onClTouchEnd,  { passive: true });
+      lifecycle.listen(form, document, 'touchcancel', _onClTouchEnd, { passive: true });
+      _clDocBound = true;
+    }
+  }
+
+  function _beginChecklistGrab(row, container, touch) {
+    if (_clDrag) return;
+    const rect = row.getBoundingClientRect();
+    const placeholder = document.createElement('div');
+    placeholder.className = 'note-cl-row-placeholder';
+    placeholder.style.height = rect.height + 'px';
+    container.insertBefore(placeholder, row);
+
+    row.classList.add('note-cl-row-dragging');
+    row.style.position = 'fixed';
+    row.style.left = rect.left + 'px';
+    row.style.top  = rect.top + 'px';
+    row.style.width = rect.width + 'px';
+    row.style.zIndex = '10002';
+    row.style.pointerEvents = 'none';
+
+    _clDrag = {
+      row, placeholder, container,
+      grabOffsetX: touch.clientX - rect.left,
+      grabOffsetY: touch.clientY - rect.top,
+    };
+    try { navigator.vibrate?.(8); } catch {}
+  }
+
+  function _onClTouchMove(e) {
+    if (!_clDrag) return;
+    if (e.touches.length !== 1) return;
+    e.preventDefault();
+    const t = e.touches[0];
+    const { row, placeholder, container } = _clDrag;
+    row.style.left = (t.clientX - _clDrag.grabOffsetX) + 'px';
+    row.style.top  = (t.clientY - _clDrag.grabOffsetY) + 'px';
+
+    const under = document.elementFromPoint(t.clientX, t.clientY);
+    const target = under && under.closest
+      ? under.closest('.note-cl-row:not(.note-cl-row-dragging)')
+      : null;
+    if (!target || target === row) return;
+    if (target.parentNode !== container) return;
+
+    const tRect = target.getBoundingClientRect();
+    const targetMidY = tRect.top + tRect.height / 2;
+    if (t.clientY < targetMidY) {
+      if (placeholder.nextElementSibling !== target) {
+        container.insertBefore(placeholder, target);
+      }
+    } else {
+      if (target.nextElementSibling !== placeholder) {
+        container.insertBefore(placeholder, target.nextElementSibling);
+      }
+    }
+  }
+
+  function _onClTouchEnd() {
+    if (!_clDrag) return;
+    const { row, placeholder } = _clDrag;
+    _clDrag = null;
+    const phRect = placeholder.getBoundingClientRect();
+    row.style.transition = 'left 0.18s ease, top 0.18s ease';
+    row.style.left = phRect.left + 'px';
+    row.style.top  = phRect.top + 'px';
+    setTimeout(() => {
+      placeholder.parentNode.insertBefore(row, placeholder);
+      placeholder.remove();
+      row.classList.remove('note-cl-row-dragging');
+      row.style.cssText = '';
+      // Order is persisted as part of the form's normal save (rows are
+      // re-serialized in DOM order via _collectItems).
+    }, 200);
+  }
+
+  function dispose() {
+    if (_clDrag) _onClTouchEnd();
+    _clDocBound = false;
+    _clOwner = null;
+  }
+  return { dispose, _wireChecklistTouchReorder, _beginChecklistGrab, _onClTouchMove, _onClTouchEnd };
+}
diff --git a/static/js/features/notes/ui/clipboard.js b/static/js/features/notes/ui/clipboard.js
new file mode 100644
index 000000000..1dab84258
--- /dev/null
+++ b/static/js/features/notes/ui/clipboard.js
@@ -0,0 +1,82 @@
+/** Note clipboard feedback and the Copy/Agent corner menu. */
+import { _serializeNoteForCopy } from '../domain/noteRules.js';
+export function createClipboard({
+  _agentSolveNote,
+  bindMenuDismiss,
+  dismissOrRemove,
+  state,
+  topPortalZ,
+  uiModule
+}) {
+  function _openNoteCornerMenu(btn) {
+    document.querySelectorAll('.note-corner-menu-dropdown').forEach(dismissOrRemove);
+    const id = btn.dataset.noteId;
+    const note = state.notes.find(n => n.id === id);
+    if (!note) return;
+    const menu = document.createElement('div');
+    menu.className = 'note-corner-menu-dropdown';
+    menu.innerHTML = `
+    <button type="button" class="ncm-item" data-act="copy">
+      <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="9" y="9" width="13" height="13" rx="2"/><path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"/></svg>
+      <span>Copy</span>
+    </button>
+    <button type="button" class="ncm-item" data-act="agent">
+      <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M12 8V4H8"/><rect x="4" y="8" width="16" height="12" rx="2"/><path d="M2 14h2M20 14h2M15 13v2M9 13v2"/></svg>
+      <span>${note.agent_session_id ? 'Re-run agent' : 'Agent: solve this'}</span>
+    </button>`;
+    document.body.appendChild(menu);
+    const r = btn.getBoundingClientRect();
+    // Right-align to the ⋯ button, clamped to the viewport.
+    const mw = 168;
+    let left = Math.min(r.right - mw, window.innerWidth - mw - 8);
+    left = Math.max(8, left);
+    // Drop down by default; flip up if there isn't room below (the button
+    // sits at the card's bottom edge now).
+    const mh = menu.offsetHeight || 96;
+    const below = window.innerHeight - r.bottom;
+    const top = (below < mh + 8 && r.top > mh + 8) ? (r.top - mh - 4) : (r.bottom + 4);
+    menu.style.cssText += `position:fixed;z-index:${topPortalZ()};top:${Math.round(top)}px;left:${Math.round(left)}px;`;
+    const close = bindMenuDismiss(menu, () => { menu.remove(); });
+    menu.querySelector('[data-act="copy"]').addEventListener('click', () => { close(); _copyNote(id, btn); });
+    menu.querySelector('[data-act="agent"]').addEventListener('click', () => { close(); _agentSolveNote(id); });
+  }
+
+  async function _copyNote(noteId, btnEl) {
+    const note = state.notes.find(n => n.id === noteId);
+    if (!note) return false;
+    const text = _serializeNoteForCopy(note);
+    if (!text) return false;
+    let ok = false;
+    try {
+      await navigator.clipboard.writeText(text);
+      ok = true;
+    } catch {
+      const ta = document.createElement('textarea');
+      ta.value = text;
+      ta.style.position = 'fixed'; ta.style.left = '-9999px';
+      document.body.appendChild(ta);
+      ta.select();
+      try { ok = document.execCommand('copy'); } catch { ok = false; }
+      ta.remove();
+    }
+    if (ok) {
+      if (btnEl && !btnEl._copyFlashing) {
+        const original = btnEl.innerHTML;
+        btnEl._copyFlashing = true;
+        btnEl.innerHTML = '<svg width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.4" stroke-linecap="round" stroke-linejoin="round"><polyline points="20 6 9 17 4 12"/></svg>';
+        btnEl.classList.add('copied');
+        setTimeout(() => {
+          btnEl.innerHTML = original;
+          btnEl.classList.remove('copied');
+          btnEl._copyFlashing = false;
+        }, 1200);
+      }
+      uiModule.showToast?.('Copied');
+    } else {
+      uiModule.showError?.('Copy failed');
+    }
+    return ok;
+  }
+
+  return { _openNoteCornerMenu, _copyNote };
+}
diff --git a/static/js/features/notes/ui/colors.js b/static/js/features/notes/ui/colors.js
new file mode 100644
index 000000000..0a9503cfb
--- /dev/null
+++ b/static/js/features/notes/ui/colors.js
@@ -0,0 +1,111 @@
+/** Note colors, custom background selection and form color controls. */
+export function createColors({
+  api
+}) {
+  const COLORS = [
+    { name: 'none',    value: '' },
+    { name: 'red',     value: 'red' },
+    { name: 'orange',  value: 'orange' },
+    { name: 'yellow',  value: 'yellow' },
+    { name: 'green',   value: 'green' },
+    { name: 'blue',    value: 'blue' },
+    { name: 'purple',  value: 'purple' },
+    { name: 'custom',  value: 'custom' },  // sentinel : clicking opens native color picker
+  ];
+
+  const COLOR_HEX = {
+    '':       'var(--border)',
+    // Pale/pastel palette : matches the calendar event color picker.
+    red:      '#f0b5ba',
+    orange:   '#e8ccb2',
+    yellow:   '#f2dfbd',
+    green:    '#cce0bc',
+    blue:     '#b0d7f7',
+    purple:   '#e2bcee',
+  };
+
+  const _CUSTOM_GRADIENT = 'conic-gradient(from 0deg, #e06c75, #d19a66, #e5c07b, #98c379, #61afef, #c678dd, #e06c75)';
+
+  function _isBgImage(c) { return typeof c === 'string' && c.startsWith('bg:'); }
+
+  function _bgImageUrl(c) { return _isBgImage(c) ? c.slice(3) : ''; }
+
+  function _dotBg(value, noteColor) {
+    if (value === 'custom') {
+      const url = _bgImageUrl(noteColor);
+      return url ? `center/cover no-repeat url('${url}')` : _CUSTOM_GRADIENT;
+    }
+    return COLOR_HEX[value];
+  }
+
+  function _dotIsActive(value, noteColor) {
+    if (value === 'custom') return _isBgImage(noteColor);
+    return value === (noteColor || '');
+  }
+
+  function _customColorStyle(c) {
+    if (!_isBgImage(c)) return '';
+    const url = _bgImageUrl(c);
+    return `background-image: linear-gradient(color-mix(in srgb, var(--panel) 60%, transparent), color-mix(in srgb, var(--panel) 60%, transparent)), url('${url}'); background-size: cover; background-position: center; border-color: color-mix(in srgb, var(--fg) 25%, var(--border));`;
+  }
+
+  function _pickCustomBgImage() {
+    return new Promise(resolve => {
+      const input = document.createElement('input');
+      input.type = 'file';
+      input.accept = 'image/*';
+      input.style.cssText = 'position:fixed; left:-9999px; top:-9999px;';
+      document.body.appendChild(input);
+      let done = false;
+      const finish = (v) => { if (done) return; done = true; input.remove(); resolve(v); };
+      input.addEventListener('change', async () => {
+        const file = input.files?.[0];
+        if (!file) return finish(null);
+        const fd = new FormData();
+        fd.append('files', file);
+        try {
+          const res = await api.upload(fd);
+          const data = await res.json();
+          const fileId = data.files?.[0]?.id;
+          if (!fileId) throw new Error('Upload failed');
+          finish(api.uploadUrl(fileId));
+        } catch { finish(null); }
+      });
+      // Best-effort cleanup if user dismisses the dialog.
+      setTimeout(() => { if (!done && !input.files?.length) finish(null); }, 30000);
+      input.click();
+    });
+  }
+
+  function _wireFormColors(form, setColor) {
+    // Color dots : apply to entire form immediately
+    const _applyFormColor = (newColor) => {
+      const currentColor = newColor || '';
+      setColor(currentColor);
+      form.dataset.noteColor = currentColor;
+      const isBg = _isBgImage(currentColor);
+      COLORS.forEach(c => { if (c.value && c.value !== 'custom') form.classList.remove('note-color-' + c.value); });
+      if (currentColor && !isBg) form.classList.add('note-color-' + currentColor);
+      if (isBg) form.setAttribute('style', _customColorStyle(currentColor));
+      else form.removeAttribute('style');
+      form.querySelectorAll('.note-color-dot').forEach(d => {
+        d.classList.toggle('active', _dotIsActive(d.dataset.color, currentColor));
+        d.style.background = _dotBg(d.dataset.color, currentColor);
+      });
+      form.dispatchEvent(new Event('change', { bubbles: true }));
+    };
+    form.querySelectorAll('.note-color-dot').forEach(dot => {
+      dot.addEventListener('click', () => {
+        if (dot.dataset.color === 'custom') {
+          _pickCustomBgImage().then(url => { if (url) _applyFormColor('bg:' + url); });
+          return;
+        }
+        _applyFormColor(dot.dataset.color);
+      });
+    });
+
+
+  }
+
+  return { COLORS, COLOR_HEX, _isBgImage, _bgImageUrl, _dotBg, _dotIsActive, _customColorStyle, _pickCustomBgImage, _wireFormColors };
+}
diff --git a/static/js/features/notes/ui/draftEditor.js b/static/js/features/notes/ui/draftEditor.js
new file mode 100644
index 000000000..09df33b79
--- /dev/null
+++ b/static/js/features/notes/ui/draftEditor.js
@@ -0,0 +1,67 @@
+/** Collect editor drafts, restore them and wire the autosave workflow. */
+export function createDraftEditor({
+  bindDraft,
+  _collectItems,
+  _loadDraft
+}) {
+  function _collectFormDraft(form) {
+    if (!form) return null;
+    const type = form.querySelector('.note-form-type-pill.active')?.dataset.type || form.dataset.noteType || 'note';
+    const d = {
+      _ts: Date.now(),
+      note_type: type,
+      color: form.dataset.noteColor || '',
+      title: form.querySelector('.note-form-title')?.value || '',
+      label: form.querySelector('.note-form-label')?.value || '',
+      due_date: form.querySelector('.note-form-due')?.value || null,
+      repeat: form.querySelector('.note-form-repeat')?.value || 'none',
+    };
+    if (type === 'note') d.content = form.querySelector('.note-form-content')?.value || '';
+    else if (type === 'goal') { d.content = form.querySelector('.note-form-goal-desc')?.value || ''; d.items = _collectItems(form); }
+    else d.items = _collectItems(form);
+    return d;
+  }
+
+  function _isDraftEmpty(d) {
+    if (!d) return true;
+    if ((d.title || '').trim()) return false;
+    if ((d.content || '').trim()) return false;
+    if (Array.isArray(d.items) && d.items.some(it => (it.text || '').trim())) return false;
+    return true;
+  }
+
+  function _wireDraftAutosave(form, id) {
+    const view = {
+      get failed() { return form._autosaveFailed; },
+      set failed(value) { form._autosaveFailed = value; },
+    };
+    const draft = bindDraft({ collect: () => _collectFormDraft(form), id, view });
+    form._flushDraft = draft.flush;
+    form._stopDraftAutosave = draft.stop;
+    form.addEventListener('input', draft.schedule);
+    form.addEventListener('change', draft.schedule);
+    form.addEventListener('click', event => {
+      if (event.target.closest('.note-cl-dot, .note-cl-rm')) draft.schedule();
+    });
+  }
+
+  function _commitOpenInPlaceEditor() {
+    const form = document.querySelector('#notes-pane .note-form');
+    if (!form) return;
+    const d = _collectFormDraft(form);
+    if (_isDraftEmpty(d)) { form.querySelector('.note-form-cancel')?.click(); return; }
+    form.querySelector('.note-form-save')?.click();
+  }
+
+  function _applyDraftToNote(note, id) {
+    const d = _loadDraft(id);
+    if (!d) return { note, restored: false };
+    const merged = { ...(note || {}) };
+    ['note_type', 'color', 'title', 'label', 'due_date', 'repeat', 'content', 'items'].forEach(k => {
+      if (d[k] !== undefined) merged[k] = d[k];
+    });
+    return { note: merged, restored: true };
+  }
+
+  return { _collectFormDraft, _isDraftEmpty, _wireDraftAutosave, _commitOpenInPlaceEditor, _applyDraftToNote };
+}
diff --git a/static/js/features/notes/ui/drawing.js b/static/js/features/notes/ui/drawing.js
new file mode 100644
index 000000000..da33c9236
--- /dev/null
+++ b/static/js/features/notes/ui/drawing.js
@@ -0,0 +1,442 @@
+/** Canvas drawing tools, local drawing undo and PNG uploads. */
+export function createDrawing({
+  lifecycle,
+  _safeImgSrc,
+  api,
+  attachColorPicker
+}) {
+  function _buildDrawHtml() {
+    return `
+    <div class="note-form-draw-wrap">
+      <canvas class="note-form-canvas" width="600" height="320"></canvas>
+      <div class="note-form-draw-toolbar">
+        <input type="color" class="note-form-draw-color" title="Stroke color" value="#222222" />
+        <label class="note-form-draw-tool note-form-draw-size-wrap" title="Stroke size">
+          <input type="range" class="note-form-draw-size" min="1" max="24" value="3" />
+        </label>
+        <div class="note-form-draw-be" role="group">
+          <button type="button" class="note-form-draw-be-btn note-form-draw-brush active" data-mode="pen" title="Brush">
+            <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M9.06 11.9l8.07-8.06a2.85 2.85 0 1 1 4.03 4.03l-8.06 8.08"/><path d="M7.07 14.94c-1.66 0-3 1.35-3 3.02 0 1.33-2.5 1.52-2 2.02 1.08 1.1 2.49 2.02 4 2.02 2.2 0 4-1.8 4-4.04 0-1.67-1.34-3.02-3-3.02z"/></svg>
+          </button>
+          <button type="button" class="note-form-draw-be-btn note-form-draw-eraser" data-mode="eraser" title="Eraser">
+            <svg width="22" height="22" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="m7 21-4.3-4.3c-1-1-1-2.5 0-3.4l9.6-9.6c1-1 2.5-1 3.4 0l5.6 5.6c1 1 1 2.5 0 3.4L13 21"/><path d="M22 21H7"/><path d="m5 11 9 9"/></svg>
+          </button>
+        </div>
+        <button type="button" class="note-form-draw-undo" title="Undo" aria-label="Undo">
+          <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><polyline points="9 14 4 9 9 4"></polyline><path d="M4 9h11a5 5 0 0 1 5 5v0a5 5 0 0 1-5 5H9"></path></svg>
+        </button>
+        <button type="button" class="note-form-draw-text" title="Add text — click to cycle size" aria-label="Add text">T<span class="note-form-draw-text-badge"></span></button>
+        <button type="button" class="note-form-draw-line" title="Line — click to cycle size">
+          <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><line x1="4" y1="20" x2="20" y2="4"/></svg>
+          <span class="note-form-draw-shape-badge"></span>
+        </button>
+        <button type="button" class="note-form-draw-circle" title="Circle — click to cycle size">
+          <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="12" cy="12" r="9"/></svg>
+          <span class="note-form-draw-shape-badge"></span>
+        </button>
+      </div>
+    </div>
+  `;
+  }
+
+  function _wireCanvas(container, initialImageUrl) {
+    const canvas = container.querySelector('.note-form-canvas');
+    if (!canvas) return;
+    const resolveThemeColor = (expression, fallback) => {
+      const probe = document.createElement('span');
+      probe.style.color = expression;
+      probe.style.position = 'fixed';
+      probe.style.visibility = 'hidden';
+      document.body.appendChild(probe);
+      const resolved = getComputedStyle(probe).color || fallback;
+      probe.remove();
+      return resolved;
+    };
+    const colorToHex = (color, fallback) => {
+      try {
+        const probe = document.createElement('canvas');
+        probe.width = probe.height = 1;
+        const probeCtx = probe.getContext('2d');
+        probeCtx.fillStyle = color;
+        probeCtx.fillRect(0, 0, 1, 1);
+        const [r, g, b] = probeCtx.getImageData(0, 0, 1, 1).data;
+        return `#${[r, g, b].map(v => v.toString(16).padStart(2, '0')).join('')}`;
+      } catch { return fallback; }
+    };
+    const surfaceColor = resolveThemeColor('var(--panel, var(--bg))', '#282c34');
+    const surfaceColorHex = colorToHex(surfaceColor, '#282c34');
+    const highlightColor = colorToHex(
+      resolveThemeColor('var(--accent, var(--red))', '#e06c75'),
+      '#e06c75',
+    );
+    const colorInput = container.querySelector('.note-form-draw-color');
+    if (colorInput) colorInput.value = highlightColor;
+    // Bump the backing-store resolution for retina displays so strokes stay
+    // crisp. Set only style.width : leaving style.height to auto so the canvas
+    // scales uniformly via its intrinsic aspect ratio. If both CSS dimensions
+    // are pinned, max-width:100% shrinks the width only, leaving rasterized
+    // glyphs visibly stretched relative to their on-screen input.
+    const dpr = Math.min(window.devicePixelRatio || 1, 2);
+    const cssW = canvas.width;
+    const cssH = canvas.height;
+    // Fill the container up to the logical width (don't pin a hard 600px,
+    // which on a narrow phone forces the card wider than the viewport and
+    // pushes the drawing outside the note). _pos() scales pointer coords by
+    // the actual displayed width, so accuracy is preserved at any size.
+    canvas.style.width = '100%';
+    canvas.style.maxWidth = cssW + 'px';
+    canvas.style.height = 'auto';
+    canvas.style.aspectRatio = cssW + ' / ' + cssH;
+    canvas.width = cssW * dpr;
+    canvas.height = cssH * dpr;
+    const ctx = canvas.getContext('2d');
+    ctx.scale(dpr, dpr);
+    ctx.fillStyle = surfaceColor;
+    ctx.fillRect(0, 0, cssW, cssH);
+    ctx.lineCap = 'round';
+    ctx.lineJoin = 'round';
+
+    // Load prior drawing as starting point so consecutive edits compose.
+    const safeInitialImageUrl = _safeImgSrc(initialImageUrl);
+    if (safeInitialImageUrl) {
+      const img = new Image();
+      img.crossOrigin = 'anonymous';
+      img.onload = () => { try { ctx.drawImage(img, 0, 0, cssW, cssH); } catch {} };
+      img.src = safeInitialImageUrl;
+      // Float an X over the canvas so the user can blank it out and go back to
+      // a clean draw surface. Removes itself once clicked.
+      const wrap = container.querySelector('.note-form-draw-wrap');
+      if (wrap && !wrap.querySelector('.note-form-draw-bg-rm')) {
+        const rm = document.createElement('button');
+        rm.type = 'button';
+        rm.className = 'note-form-draw-bg-rm';
+        rm.title = 'Clear photo (regular draw)';
+        rm.innerHTML = '&times;';
+        rm.addEventListener('click', (e) => {
+          e.preventDefault();
+          e.stopPropagation();
+          ctx.fillStyle = surfaceColor;
+          ctx.fillRect(0, 0, cssW, cssH);
+          rm.remove();
+        });
+        wrap.appendChild(rm);
+      }
+    }
+
+    // Swap the native browser color dialog for the in-house HSV picker
+    // (same one used by Themes + the gallery editor). Existing `input` event
+    // listeners + .value reads keep working : see colorPicker.js.
+    if (colorInput) attachColorPicker(colorInput);
+    const sizeInput = container.querySelector('.note-form-draw-size');
+    const beSeg = container.querySelector('.note-form-draw-be');
+    const brushBtn = container.querySelector('.note-form-draw-brush');
+    const eraserBtn = container.querySelector('.note-form-draw-eraser');
+    const textBtn = container.querySelector('.note-form-draw-text');
+    const lineBtn = container.querySelector('.note-form-draw-line');
+    const circleBtn = container.querySelector('.note-form-draw-circle');
+    const undoBtn = container.querySelector('.note-form-draw-undo');
+    // Single source of truth for what clicks/drags do. Other booleans are
+    // derived from this so we never end up with conflicting "eraser AND text"
+    // states (the bug that made T appear broken after using the eraser).
+    // Modes: 'pen' | 'eraser' | 'text-s' | 'text-m' | 'text-l' | 'line' | 'circle'
+    let mode = 'pen';
+    let drawing = false;
+    let last = null;
+    // The text tool has three preset sizes (CSS px font-size).
+    const TEXT_SIZES = { 's': 16, 'm': 26, 'l': 40 };
+    // Line / circle stroke widths in logical pixels : three crisp options.
+    const SHAPE_WIDTHS = { 's': 2, 'm': 5, 'l': 10 };
+    // Snapshot taken at the start of a shape drag so the preview can repaint
+    // cleanly on each move without accumulating intermediate strokes.
+    let _shapeSnapshot = null;
+
+    // Per-canvas undo stack. We snapshot the bitmap (as ImageData) BEFORE each
+    // operation : stroke, text commit, or future operations : and pop+restore
+    // on Undo. Cap to 30 to keep memory bounded.
+    const _undoStack = [];
+    const UNDO_LIMIT = 30;
+    const _syncUndoButton = () => {
+      const available = _undoStack.length > 0;
+      undoBtn?.classList.toggle('has-undo', available);
+      undoBtn?.toggleAttribute('disabled', !available);
+      undoBtn?.setAttribute('aria-disabled', available ? 'false' : 'true');
+    };
+    const _markCanvasDirty = () => container.dispatchEvent(new Event('input', { bubbles: true }));
+    const _snapshot = () => {
+      try {
+        const w = canvas.width, h = canvas.height;
+        _undoStack.push(ctx.getImageData(0, 0, w, h));
+        if (_undoStack.length > UNDO_LIMIT) _undoStack.shift();
+        _syncUndoButton();
+      } catch {}
+    };
+    const _undo = () => {
+      const prev = _undoStack.pop();
+      if (!prev) { _syncUndoButton(); return; }
+      // Restore against the raw backing store: temporarily reset the active
+      // ctx scale, paint the snapshot 1:1, then reapply our standard transform.
+      ctx.save();
+      ctx.setTransform(1, 0, 0, 1, 0, 0);
+      ctx.putImageData(prev, 0, 0);
+      ctx.restore();
+      _markCanvasDirty();
+      _syncUndoButton();
+    };
+
+    const _pos = (e) => {
+      // CSS can shrink the canvas (max-width:100%) without changing its logical
+      // size, so compute the displayed-to-logical scale per axis. Pointer coords
+      // are in CSS pixels; the dpr-scaled ctx expects logical (cssW × cssH).
+      const r = canvas.getBoundingClientRect();
+      const sx = cssW / r.width;
+      const sy = cssH / r.height;
+      const t = e.touches ? e.touches[0] : e;
+      return { x: (t.clientX - r.left) * sx, y: (t.clientY - r.top) * sy };
+    };
+    const _begin = (e) => {
+      if (mode.startsWith('text-')) {
+        // Stop the event so the browser doesn't synthesize a follow-up click
+        // that would blur the input we're about to create.
+        e.preventDefault?.();
+        e.stopPropagation?.();
+        _openTextInput(e);
+        return;
+      }
+      _snapshot();
+      last = _pos(e);
+      drawing = true;
+      if (mode.startsWith('line-') || mode.startsWith('circle-')) {
+        // Capture the backing pixels so the preview can replay each move from
+        // the same starting state (otherwise live shapes accumulate).
+        try { _shapeSnapshot = ctx.getImageData(0, 0, canvas.width, canvas.height); } catch {}
+        return;
+      }
+      ctx.beginPath();
+      ctx.moveTo(last.x, last.y);
+    };
+
+    // Drop an HTML input at the click position so the user can type, then
+    // rasterize the text onto the canvas at blur/Enter. Mirrors how PDF form
+    // annotations work in our doc editor.
+    let _activeTextInput = null;
+    const _openTextInput = (e) => {
+      // Commit any prior pending input before starting a new one : otherwise
+      // the first click leaves an orphaned input the user thinks "didn't work".
+      if (_activeTextInput) { try { _activeTextInput.blur(); } catch {} }
+      const r = canvas.getBoundingClientRect();
+      const t = e.touches ? e.touches[0] : e;
+      // Position is anchored to the wrap, not the canvas; since the canvas is
+      // the first child of the wrap and the wrap has no padding, they share an
+      // origin, so we offset from the canvas rect directly.
+      const px = t.clientX - r.left;
+      const py = t.clientY - r.top;
+      const logical = _pos(e);
+      // Size is decided by which T variant is active (S/M/L), not the stroke
+      // slider : those are independent dials.
+      const sizeKey = mode.startsWith('text-') ? mode.slice(-1) : 'm';
+      const sizeCss = TEXT_SIZES[sizeKey] || TEXT_SIZES.m;
+      const wrap = container.querySelector('.note-form-draw-wrap');
+      if (!wrap) return;
+      if (getComputedStyle(wrap).position === 'static') wrap.style.position = 'relative';
+      const input = document.createElement('input');
+      input.type = 'text';
+      input.className = 'note-form-draw-textinput';
+      input.placeholder = 'type then Enter';
+      const color = colorInput?.value || '#222';
+      const maxW = Math.max(120, Math.floor(r.width - px - 4));
+      input.style.cssText = [
+        'position:absolute',
+        `left:${px}px`,
+        `top:${Math.max(0, py - sizeCss * 0.7)}px`,
+        `font:${sizeCss}px Arial, sans-serif`,
+        `color:${color}`,
+        'background:#ffffff',
+        'border:2px solid var(--accent)',
+        'border-radius:4px',
+        'outline:none',
+        'padding:2px 6px',
+        'min-width:120px',
+        `max-width:${maxW}px`,
+        'z-index:1000',
+        'box-shadow:0 2px 8px rgba(0,0,0,0.25)',
+        'pointer-events:auto',
+      ].join(';');
+      wrap.appendChild(input);
+      _activeTextInput = input;
+      // Focus synchronously so the call still counts as inside the user gesture
+      // on iOS / Android, then re-focus on the next frame in case a competing
+      // synthetic event (touch → click) moved focus away.
+      input.focus();
+      requestAnimationFrame(() => { if (document.activeElement !== input) input.focus(); });
+      let committed = false;
+      const commit = () => {
+        if (committed) return;
+        committed = true;
+        const text = input.value;
+        if (_activeTextInput === input) _activeTextInput = null;
+        input.remove();
+        if (!text) return;
+        // Snapshot BEFORE rasterizing so Undo removes the text in one step.
+        _snapshot();
+        ctx.save();
+        ctx.globalCompositeOperation = 'source-over';
+        ctx.fillStyle = color;
+        // Canvas now scales uniformly (style.height: auto), so a single ratio
+        // suffices for picking the logical font size that matches what the
+        // user just saw in the HTML input.
+        const sx = cssW / r.width;
+        const logicalSize = sizeCss * sx;
+        ctx.font = `${logicalSize}px sans-serif`;
+        ctx.textBaseline = 'top';
+        ctx.fillText(text, logical.x, logical.y - logicalSize * 0.7);
+        ctx.restore();
+        _markCanvasDirty();
+      };
+      input.addEventListener('blur', commit);
+      input.addEventListener('keydown', (ev) => {
+        if (ev.key === 'Enter') { ev.preventDefault(); input.blur(); }
+        else if (ev.key === 'Escape') { input.value = ''; input.blur(); }
+      });
+    };
+    const _move = (e) => {
+      if (!drawing) return;
+      e.preventDefault?.();
+      const p = _pos(e);
+      if (mode.startsWith('line-') || mode.startsWith('circle-')) {
+        // Restore the pre-shape bitmap, then redraw the preview shape from
+        // anchor → current pointer.
+        if (_shapeSnapshot) {
+          ctx.save();
+          ctx.setTransform(1, 0, 0, 1, 0, 0);
+          ctx.putImageData(_shapeSnapshot, 0, 0);
+          ctx.restore();
+        }
+        ctx.globalCompositeOperation = 'source-over';
+        ctx.strokeStyle = colorInput?.value || '#222';
+        const sizeKey = mode.slice(-1);
+        ctx.lineWidth = SHAPE_WIDTHS[sizeKey] || SHAPE_WIDTHS.m;
+        ctx.beginPath();
+        if (mode.startsWith('line-')) {
+          ctx.moveTo(last.x, last.y);
+          ctx.lineTo(p.x, p.y);
+        } else {
+          const dx = p.x - last.x;
+          const dy = p.y - last.y;
+          const radius = Math.hypot(dx, dy);
+          ctx.arc(last.x, last.y, radius, 0, Math.PI * 2);
+        }
+        ctx.stroke();
+        return;
+      }
+      const erasing = mode === 'eraser';
+      ctx.globalCompositeOperation = 'source-over';
+      ctx.strokeStyle = erasing ? surfaceColor : (colorInput?.value || highlightColor);
+      ctx.lineWidth = Number(sizeInput?.value || 3) * (erasing ? 2.5 : 1);
+      ctx.lineTo(p.x, p.y);
+      ctx.stroke();
+      last = p;
+    };
+    const _end = () => {
+      if (drawing) _markCanvasDirty();
+      drawing = false; last = null; _shapeSnapshot = null;
+    };
+
+    canvas.addEventListener('mousedown', _begin);
+    canvas.addEventListener('mousemove', _move);
+    lifecycle.listen(canvas, window, 'mouseup', _end);
+    // Non-passive so text mode can preventDefault : otherwise the synthetic
+    // mousedown/click that follows a touch can blur the freshly-created text
+    // input on iOS Safari, making T look like a no-op.
+    canvas.addEventListener('touchstart', (e) => { if (mode.startsWith('text-')) e.preventDefault(); _begin(e); }, { passive: false });
+    canvas.addEventListener('touchmove', _move, { passive: false });
+    canvas.addEventListener('touchend', _end);
+    canvas.addEventListener('touchcancel', _end);
+
+    // Single mode setter : keeps the toolbar, swatch, and cursor in sync, and
+    // makes sure exiting the eraser restores the user's chosen color whether
+    // they exit by clicking another tool or by toggling eraser off.
+    let _preEraseColor = null;
+    const _setMode = (next) => {
+      const wasEraser = mode === 'eraser';
+      mode = next;
+      const isEraser = next === 'eraser';
+      const isPen = next === 'pen';
+      const isText = next.startsWith('text-');
+      // Swatch: theme surface while erasing, restored when leaving that mode.
+      if (isEraser && !wasEraser && colorInput) {
+        _preEraseColor = colorInput.value;
+        colorInput.value = surfaceColorHex;
+      } else if (!isEraser && wasEraser && colorInput && _preEraseColor) {
+        colorInput.value = _preEraseColor;
+        _preEraseColor = null;
+      }
+      // Brush/Eraser segmented pill : slides to the active side. When a non-
+      // pen/eraser tool (T / line / circle) is active, neither half is
+      // highlighted, but the pill still indicates which side the user was on
+      // last so they can return with one click.
+      const isLine = next.startsWith('line-');
+      const isCircle = next.startsWith('circle-');
+      beSeg?.classList.toggle('is-eraser', isEraser);
+      brushBtn?.classList.toggle('active', isPen);
+      eraserBtn?.classList.toggle('active', isEraser);
+      textBtn?.classList.toggle('active', isText);
+      lineBtn?.classList.toggle('active', isLine);
+      circleBtn?.classList.toggle('active', isCircle);
+      // Per-button size badges (S/M/L), driven off the mode suffix.
+      const tBadge = textBtn?.querySelector('.note-form-draw-text-badge');
+      if (tBadge) tBadge.textContent = isText ? next.slice(-1).toUpperCase() : '';
+      const lBadge = lineBtn?.querySelector('.note-form-draw-shape-badge');
+      if (lBadge) lBadge.textContent = isLine ? next.slice(-1).toUpperCase() : '';
+      const cBadge = circleBtn?.querySelector('.note-form-draw-shape-badge');
+      if (cBadge) cBadge.textContent = isCircle ? next.slice(-1).toUpperCase() : '';
+      // Reflect the chosen size in the icon itself : thicker line/circle stroke
+      // for M+L, larger T glyph for M+L. CSS rules read `.size-s/.size-m/.size-l`.
+      const _sz = next.slice(-1);
+      [textBtn, lineBtn, circleBtn].forEach(b => b?.classList.remove('size-s', 'size-m', 'size-l'));
+      if (isText && /[sml]/.test(_sz)) textBtn?.classList.add('size-' + _sz);
+      if (isLine && /[sml]/.test(_sz)) lineBtn?.classList.add('size-' + _sz);
+      if (isCircle && /[sml]/.test(_sz)) circleBtn?.classList.add('size-' + _sz);
+      canvas.style.cursor = isText ? 'text' : 'crosshair';
+    };
+    brushBtn?.addEventListener('click', () => _setMode('pen'));
+    eraserBtn?.addEventListener('click', () => _setMode('eraser'));
+    // T / Line / Circle: each cycles its own three sizes, then back to pen.
+    const _cycle = (prefix) => {
+      const seq = ['s', 'm', 'l'];
+      if (!mode.startsWith(prefix)) return prefix + 's';
+      const cur = mode.slice(-1);
+      const next = seq[seq.indexOf(cur) + 1];
+      return next ? prefix + next : 'pen';
+    };
+    textBtn?.addEventListener('click', () => _setMode(_cycle('text-')));
+    lineBtn?.addEventListener('click', () => _setMode(_cycle('line-')));
+    circleBtn?.addEventListener('click', () => _setMode(_cycle('circle-')));
+    undoBtn?.addEventListener('click', () => _undo());
+    _syncUndoButton();
+
+    // Stash so the save handler can read it later without re-resolving DOM.
+    canvas._cssW = cssW;
+    canvas._cssH = cssH;
+    return canvas;
+  }
+
+  async function _uploadCanvasAsPng(canvas, galleryId = null) {
+    if (!canvas) return null;
+    const blob = await new Promise(r => canvas.toBlob(r, 'image/png'));
+    if (!blob) return null;
+    const fd = new FormData();
+    fd.append('files', blob, 'drawing.png');
+    if (galleryId) fd.append('gallery_id', galleryId);
+    try {
+      const res = await api.upload(fd);
+      const data = await res.json();
+      const id = data.files?.[0]?.id;
+      return id ? {
+        url: api.uploadUrl(id),
+        galleryId: data.files?.[0]?.gallery_id || null,
+      } : null;
+    } catch { return null; }
+  }
+
+  return { _buildDrawHtml, _wireCanvas, _uploadCanvasAsPng };
+}
diff --git a/static/js/features/notes/ui/editor.js b/static/js/features/notes/ui/editor.js
new file mode 100644
index 000000000..f5bdc7c9f
--- /dev/null
+++ b/static/js/features/notes/ui/editor.js
@@ -0,0 +1,518 @@
+/** Build and wire note, checklist, goal and drawing editor forms. */
+export function createEditor({
+  deleteFromEditor,
+  submitNote,
+  COLORS,
+  _applyMasonry,
+  _archiveNoteById,
+  _buildChecklistHtml,
+  _buildDrawHtml,
+  _buildGoalHtml,
+  _collectItems,
+  _customColorStyle,
+  _dotBg,
+  _dotIsActive,
+  _esc,
+  _isBgImage,
+  _renderNotes,
+  _safeImgSrc,
+  _uid,
+  _uploadCanvasAsPng,
+  _wireCanvas,
+  _wireChecklist,
+  _wireDraftAutosave,
+  _wireFormColors,
+  _wireGoalForm,
+  _wireReminderPicker,
+  api,
+  app,
+  state,
+  uiModule
+}) {
+  function _buildForm(note = null) {
+    const isEdit = note && note.id;
+    const type = note?.note_type === 'checklist' ? 'todo' : (note?.note_type || 'note');
+    const color = note?.color || '';
+    const items = note?.items || [{ id: _uid(), text: '', done: false }];
+
+    const form = document.createElement('div');
+    form.className = 'note-form';
+    form.dataset.noteType = type;
+    form.dataset.noteColor = color || '';
+    if (color && !_isBgImage(color)) form.classList.add('note-color-' + color);
+    if (_isBgImage(color)) form.setAttribute('style', _customColorStyle(color));
+    let currentImageUrl = _safeImgSrc(note?.image_url || '');
+    form.innerHTML = `
+    <div class="note-form-header">
+      <input type="text" class="note-form-title" placeholder="Title" value="${_esc(note?.title || '')}" />
+      <button type="button" class="note-form-icon-btn note-form-remind-btn${note?.due_date ? ' has-date' : ''}" title="Remind me">
+        <svg width="31" height="31" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M18 8A6 6 0 0 0 6 8c0 7-3 9-3 9h18s-3-2-3-9"/><path d="M13.73 21a2 2 0 0 1-3.46 0"/></svg>
+      </button>
+      <input type="hidden" class="note-form-due" value="${note?.due_date || ''}" />
+      <input type="hidden" class="note-form-repeat" value="${note?.repeat || 'none'}" />
+    </div>
+    ${currentImageUrl && type !== 'draw' ? `<div class="note-form-image-wrap"><img class="note-form-image" src="${_esc(currentImageUrl)}" draggable="false" /><button class="note-form-image-rm" title="Remove">&times;</button></div>` : ''}
+    <div class="note-form-body">
+      ${type === 'note'
+          ? `<textarea class="note-form-content" placeholder="Take a note..." rows="4">${_esc(note?.content || '')}</textarea>`
+          : type === 'draw'
+          ? _buildDrawHtml()
+          : type === 'goal'
+          ? _buildGoalHtml(note, items)
+          : _buildChecklistHtml(items)}
+    </div>
+    <div class="note-form-reminder-tags"></div>
+    <div class="note-form-meta">
+      <div class="note-form-type-seg${type === 'todo' ? ' is-todo' : type === 'draw' ? ' is-draw' : ''}" role="group">
+        <button type="button" class="note-form-type-pill${type === 'note' ? ' active' : ''}" data-type="note">
+          <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><line x1="4" y1="6" x2="20" y2="6"/><line x1="4" y1="12" x2="20" y2="12"/><line x1="4" y1="18" x2="14" y2="18"/></svg>
+          <span>Note</span>
+        </button>
+        <button type="button" class="note-form-type-pill${type === 'todo' ? ' active' : ''}" data-type="todo">
+          <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><polyline points="9 11 12 14 22 4"/><path d="M21 12v7a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2h11"/></svg>
+          <span>Todo</span>
+        </button>
+        <button type="button" class="note-form-type-pill${type === 'draw' ? ' active' : ''}" data-type="draw">
+          <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M12 19l7-7 3 3-7 7-3-3z"/><path d="M18 13l-1.5-7.5L2 2l3.5 14.5L13 18l5-5z"/><path d="M2 2l7.586 7.586"/><circle cx="11" cy="11" r="2"/></svg>
+          <span>Draw</span>
+        </button>
+      </div>
+      <button class="note-form-photo-btn" title="Attach photo">
+        <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="3" y="3" width="18" height="18" rx="2"/><circle cx="8.5" cy="8.5" r="1.5"/><polyline points="21 15 16 10 5 21"/></svg>
+      </button>
+      <input type="file" class="note-form-photo-input" accept="image/*" capture="environment" style="display:none" />
+      <div class="note-color-picker">
+        ${COLORS.map(c => `<span class="note-color-dot${_dotIsActive(c.value, color) ? ' active' : ''}" data-color="${c.value}" style="background:${_dotBg(c.value, color)}" title="${c.name || 'default'}"></span>`).join('')}
+      </div>
+      <input type="text" class="note-form-label" value="${_esc(note?.label || '')}" placeholder="#tag1 #tag2" title="Tag(s) — space-separated" />
+      <div class="note-form-actions-group">
+        ${isEdit ? `
+        <button type="button" class="note-form-text-btn note-form-archive-btn note-form-collapsible" title="Archive">
+          <svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="2" y="3" width="20" height="5" rx="1"/><path d="M4 8v11a2 2 0 002 2h12a2 2 0 002-2V8"/><path d="M10 12h4"/></svg><span class="nft-label">Archive</span>
+        </button>
+        <button type="button" class="note-form-text-btn note-form-delete-btn note-form-collapsible danger" title="Delete">
+          <svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><polyline points="3 6 5 6 21 6"/><path d="M19 6l-1 14a2 2 0 0 1-2 2H8a2 2 0 0 1-2-2L5 6"/><path d="M8 6V4a2 2 0 0 1 2-2h4a2 2 0 0 1 2 2v2"/><line x1="10" y1="11" x2="10" y2="17"/><line x1="14" y1="11" x2="14" y2="17"/></svg><span class="nft-label">Delete</span>
+        </button>
+        ` : ''}
+        <span class="note-form-actions-spacer"></span>
+        <button class="note-form-cancel note-form-text-btn note-form-collapsible" title="Close (keep changes)">
+          <svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.2" stroke-linecap="round"><line x1="6" y1="6" x2="18" y2="18"/><line x1="18" y1="6" x2="6" y2="18"/></svg><span class="nft-label">Close</span>
+        </button>
+        <button class="note-form-save note-form-text-btn" title="${isEdit ? 'Update' : 'Save'}">
+          <svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.4" stroke-linecap="round" stroke-linejoin="round"><polyline points="20 6 9 17 4 12"/></svg><span class="nft-label">${isEdit ? 'Update' : 'Save'}</span>
+        </button>
+      </div>
+    </div>
+  `;
+
+    let currentType = type;
+    let currentColor = color;
+    // Stash original-form values so round-trips (Note→Todo→Note) restore the
+    // user's hand-formatted text instead of a join of generated items. Same the
+    // other way: if you started in todo, switch to note, switch back, items
+    // come back unchanged.
+    let _stashedNoteText = (type === 'note') ? (note?.content || '') : null;
+    let _stashedTodoItems = (type === 'todo' && Array.isArray(note?.items)) ? note.items.slice() : null;
+    // Goal mode kept its own pair of stashes (description + steps) so a
+    // Todo→Goal→Todo round-trip wouldn't lose either side. The Goal pill in
+    // the type picker was later removed, so the only entry point now is
+    // *editing* an existing goal-typed note : but the switch handler still
+    // accepts Goal→Todo/Note transitions (downgrading legacy goals), so
+    // these stashes still earn their keep.
+    let _stashedGoalDesc = (type === 'goal') ? (note?.content || '') : null;
+    let _stashedGoalItems = (type === 'goal' && Array.isArray(note?.items)) ? note.items.slice() : null;
+
+    // Drawing also stashes the saved image URL so it survives Note↔Draw flips.
+    let _stashedDrawUrl = (type === 'draw') ? (_safeImgSrc(note?.image_url) || null) : null;
+    const _refreshFormLayout = () => {
+      const body = form.closest('.notes-pane-body');
+      if (!body) return;
+      _applyMasonry(body);
+      requestAnimationFrame(() => {
+        _applyMasonry(body);
+        requestAnimationFrame(() => _applyMasonry(body));
+      });
+    };
+
+    // Type segmented control : Note | Todo | Draw
+    form.querySelectorAll('.note-form-type-pill').forEach(pill => {
+      pill.addEventListener('click', () => {
+        const newType = pill.dataset.type;
+        if (newType === currentType) return;
+        const bodyEl = form.querySelector('.note-form-body');
+        // Stash whatever the user has in the current mode before swapping it
+        // out, so a subsequent flip back restores their work.
+        if (currentType === 'note') {
+          _stashedNoteText = form.querySelector('.note-form-content')?.value || '';
+        } else if (currentType === 'todo') {
+          _stashedTodoItems = _collectItems(form);
+        } else if (currentType === 'goal') {
+          _stashedGoalDesc = form.querySelector('.note-form-goal-desc')?.value || '';
+          _stashedGoalItems = _collectItems(form);
+        } else if (currentType === 'draw') {
+          const c = form.querySelector('.note-form-canvas');
+          if (c) { try { _stashedDrawUrl = c.toDataURL('image/png'); } catch {} }
+        }
+        // Render the new mode's body and re-wire its inputs.
+        if (newType === 'todo') {
+          let nextItems;
+          if (_stashedTodoItems && _stashedTodoItems.length) {
+            nextItems = _stashedTodoItems;
+          } else if (_stashedGoalItems && _stashedGoalItems.length) {
+            // Going Goal→Todo keeps the AI-generated steps as a plain checklist.
+            nextItems = _stashedGoalItems;
+          } else if (_stashedNoteText) {
+            const lines = _stashedNoteText.split('\n').map(s => s.trim()).filter(Boolean);
+            nextItems = lines.length ? lines.map(t => ({ id: _uid(), text: t, done: false })) : [{ id: _uid(), text: '', done: false }];
+          } else {
+            nextItems = [{ id: _uid(), text: '', done: false }];
+          }
+          bodyEl.innerHTML = _buildChecklistHtml(nextItems);
+          _wireChecklist(bodyEl);
+        } else if (newType === 'draw') {
+          bodyEl.innerHTML = _buildDrawHtml();
+          // If the user just attached a photo (via the photo button) and then
+          // toggled to Draw, paint that photo onto the canvas so they can draw
+          // on top of it. _stashedDrawUrl wins if they were drawing earlier in
+          // the same edit session.
+          _wireCanvas(bodyEl, _stashedDrawUrl || currentImageUrl || _safeImgSrc(note?.image_url) || null);
+        } else {
+          const text = (_stashedNoteText !== null && _stashedNoteText !== undefined && _stashedNoteText !== '')
+            ? _stashedNoteText
+            : (_stashedGoalDesc && _stashedGoalDesc)
+            || (_stashedTodoItems || _stashedGoalItems || []).map(i => i.text).join('\n');
+          bodyEl.innerHTML = `<textarea class="note-form-content" placeholder="Take a note..." rows="4">${_esc(text)}</textarea>`;
+          _wireHashtag(bodyEl.querySelector('.note-form-content'));
+        }
+        const focusEl = newType === 'note'
+          ? bodyEl.querySelector('.note-form-content')
+          : newType === 'todo'
+            ? bodyEl.querySelector('.note-cl-text')
+            : null;
+        if (focusEl) {
+          requestAnimationFrame(() => {
+            focusEl.focus({ preventScroll: true });
+            try {
+              const end = focusEl.value.length;
+              focusEl.setSelectionRange(end, end);
+            } catch {}
+          });
+        }
+        currentType = newType;
+        const seg = form.querySelector('.note-form-type-seg');
+        seg?.classList.toggle('is-todo', newType === 'todo');
+        seg?.classList.toggle('is-draw', newType === 'draw');
+        form.querySelectorAll('.note-form-type-pill').forEach(p => p.classList.toggle('active', p.dataset.type === newType));
+        // The standalone image preview (form-image-wrap) and the canvas would
+        // otherwise both show the same image_url when editing a drawn note.
+        // Hide it in draw mode, restore it when leaving draw mode.
+        const imgWrap = form.querySelector('.note-form-image-wrap');
+        if (imgWrap) imgWrap.style.display = (newType === 'draw') ? 'none' : '';
+        // The background-color dots set the note card's bg : they make no sense
+        // for a drawn note (the canvas image IS the card content), so hide them.
+        const bgPicker = form.querySelector('.note-color-picker');
+        if (bgPicker) bgPicker.style.display = (newType === 'draw') ? 'none' : '';
+        if (form.closest('.notes-pane.notes-view-grid') && window.matchMedia('(max-width: 768px)').matches) {
+          form.style.gridColumn = '1 / -1';
+          form.style.gridRowEnd = newType === 'draw' ? 'span 152' : 'span 64';
+        }
+        _refreshFormLayout();
+      });
+    });
+
+    // Slide a finger across the Note/Todo/Draw control to switch modes (mobile).
+    // On touchmove we find the pill under the finger and click it : reusing the
+    // pill click handler above, so the body re-renders + content stashing all
+    // work. Only fires when crossing into a *different* pill.
+    const _typeSeg = form.querySelector('.note-form-type-seg');
+    if (_typeSeg) {
+      let _sliding = false;
+      const _activateAt = (x, y) => {
+        const pill = document.elementFromPoint(x, y)?.closest?.('.note-form-type-pill');
+        if (pill && !pill.classList.contains('active')) pill.click();
+      };
+      _typeSeg.addEventListener('touchstart', () => { _sliding = true; }, { passive: true });
+      _typeSeg.addEventListener('touchmove', (e) => {
+        if (_sliding && e.touches[0]) _activateAt(e.touches[0].clientX, e.touches[0].clientY);
+      }, { passive: true });
+      _typeSeg.addEventListener('touchend', () => { _sliding = false; });
+      _typeSeg.addEventListener('touchcancel', () => { _sliding = false; });
+    }
+
+    _wireFormColors(form, value => { currentColor = value; });
+
+    if (currentType === 'todo') _wireChecklist(form.querySelector('.note-form-body'));
+    if (currentType === 'goal') _wireGoalForm(form, form.querySelector('.note-form-body'));
+    if (currentType === 'draw') {
+      _wireCanvas(form.querySelector('.note-form-body'), _safeImgSrc(note?.image_url) || null);
+      // Same hides we apply on type-switch : keep them consistent on initial open.
+      const _ip = form.querySelector('.note-form-image-wrap'); if (_ip) _ip.style.display = 'none';
+      const _cp = form.querySelector('.note-color-picker'); if (_cp) _cp.style.display = 'none';
+    }
+
+    // Auto-grow the plain-note textarea so editing longer notes is
+    // comfortable : it expands with the content (up to a cap) instead of
+    // staying a cramped 4-row box. The user can still drag-resize too.
+    const _contentTa = form.querySelector('.note-form-content');
+    if (_contentTa) {
+      const _grow = () => {
+        _contentTa.style.height = 'auto';
+        // Inline form: cap at ~50vh so a huge note doesn't push the action
+        // buttons off-screen. Fullscreen mobile overlay: the body scrolls and
+        // there are no inline buttons crowding, so allow nearly the full height
+        // : capping at 50vh there clipped longer notes ("part disappears").
+        const inFullscreen = !!_contentTa.closest('.note-fullscreen-overlay');
+        const max = Math.round(window.innerHeight * (inFullscreen ? 0.9 : 0.5));
+        _contentTa.style.height = Math.min(_contentTa.scrollHeight, max) + 'px';
+      };
+      _contentTa.addEventListener('input', _grow);
+      // Grow on open so existing content is fully visible. Run again after the
+      // fullscreen overlay's open animation settles : measuring mid-animation
+      // (the overlay starts scaled/transitioning) can under-size the box.
+      setTimeout(_grow, 0);
+      setTimeout(_grow, 360);
+    }
+
+    _wireReminderPicker(form);
+
+    // Photo upload
+    const photoBtn = form.querySelector('.note-form-photo-btn');
+    const photoInput = form.querySelector('.note-form-photo-input');
+    if (photoBtn && photoInput) {
+      photoBtn.addEventListener('click', () => photoInput.click());
+      photoInput.addEventListener('change', async () => {
+        const file = photoInput.files?.[0];
+        if (!file) return;
+        const fd = new FormData();
+        fd.append('files', file);
+        try {
+          const res = await api.upload(fd);
+          const data = await res.json();
+          const fileId = data.files?.[0]?.id;
+          if (!fileId) throw new Error('Upload failed');
+          currentImageUrl = api.uploadUrl(fileId);
+          // Only ever keep the latest attached photo : drop any existing wrap
+          // before inserting a fresh one. Picking a second photo replaces the
+          // first instead of stacking.
+          form.querySelector('.note-form-image-wrap')?.remove();
+          const wrap = document.createElement('div');
+          wrap.className = 'note-form-image-wrap';
+          wrap.innerHTML = `<img class="note-form-image" draggable="false" /><button class="note-form-image-rm" title="Remove">&times;</button>`;
+          // Insert AFTER the whole header (a flex-row), not after the
+          // title input itself : otherwise the image lands as a sibling
+          // of the title inside the header and flex puts them side-by-side.
+          form.querySelector('.note-form-header').after(wrap);
+          wrap.querySelector('.note-form-image-rm').addEventListener('click', () => { wrap.remove(); currentImageUrl = ''; });
+          wrap.querySelector('img').src = currentImageUrl;
+        } catch (err) { uiModule.showError('Image upload failed'); }
+        photoInput.value = '';
+      });
+    }
+    // Existing image remove
+    form.querySelector('.note-form-image-rm')?.addEventListener('click', () => {
+      form.querySelector('.note-form-image-wrap')?.remove();
+      currentImageUrl = '';
+    });
+
+    // Title Enter -> focus body (textarea or first checklist item)
+    form.querySelector('.note-form-title').addEventListener('keydown', (e) => {
+      if (e.key === 'Enter' && !e.shiftKey && !e.ctrlKey && !e.metaKey) {
+        e.preventDefault();
+        const ta = form.querySelector('.note-form-content');
+        if (ta) { ta.focus(); return; }
+        const firstItem = form.querySelector('.note-cl-text');
+        if (firstItem) firstItem.focus();
+      }
+    });
+
+    // Hashtag → label: typing "#foo " in title/content appends "foo" to the
+    // space-separated tag list. Repeats are deduplicated, so #foo #foo only
+    // keeps one. Tags already present in the label field are left alone.
+    const labelInput = form.querySelector('.note-form-label');
+    const _hashtagRe = /(^|\s)#([A-Za-z0-9][\w-]*)\s$/;
+    function _wireHashtag(el) {
+      if (!el || !labelInput) return;
+      el.addEventListener('input', () => {
+        const m = _hashtagRe.exec(el.value);
+        if (!m) return;
+        const tag = m[2];
+        // Dedup against the stripped form : labelInput may already hold `#tag`
+        // (after Enter normalised), so includes(tag) on the raw split would
+        // miss the duplicate and append a bare `tag` next to `#tag`.
+        const existing = labelInput.value.trim().split(/\s+/).filter(Boolean);
+        const stripped = existing.map(t => t.replace(/^#+/, ''));
+        if (!stripped.includes(tag)) {
+          existing.push('#' + tag);
+          labelInput.value = existing.join(' ');
+          labelInput.classList.add('flash-once');
+          setTimeout(() => labelInput.classList.remove('flash-once'), 600);
+        }
+        const cut = el.value.length - m[0].length + m[1].length;
+        el.value = el.value.slice(0, cut);
+      });
+    }
+    _wireHashtag(form.querySelector('.note-form-title'));
+    _wireHashtag(form.querySelector('.note-form-content'));
+    // Pressing Enter in the tag field commits the current word as its own tag
+    // and parks the cursor after a trailing space, so the next word becomes a
+    // separate tag rather than overwriting the previous one.
+    labelInput?.addEventListener('keydown', (e) => {
+      if (e.key !== 'Enter' || e.shiftKey || e.ctrlKey || e.metaKey) return;
+      e.preventDefault();
+      e.stopPropagation();
+      // Strip any leading #s the user typed, dedupe, then re-prepend exactly
+      // one #. So typing "foo" or "#foo" both end up as "#foo " in the input;
+      // the save handler keeps stripping #s before storing so DB stays clean.
+      const tags = [...new Set(labelInput.value.split(/\s+/).map(t => t.replace(/^#+/, '').trim()).filter(Boolean))];
+      if (!tags.length) return;
+      labelInput.value = tags.map(t => '#' + t).join(' ') + ' ';
+      labelInput.setSelectionRange(labelInput.value.length, labelInput.value.length);
+      labelInput.classList.add('flash-once');
+      setTimeout(() => labelInput.classList.remove('flash-once'), 600);
+    });
+
+    // Shift+Enter (or Cmd/Ctrl+Enter) anywhere in the form -> save
+    // Escape -> cancel edit
+    form.addEventListener('keydown', (e) => {
+      if (e.key === 'Enter' && (e.shiftKey || e.ctrlKey || e.metaKey)) {
+        e.preventDefault();
+        form.querySelector('.note-form-save')?.click();
+      } else if (e.key === 'Escape') {
+        e.preventDefault();
+        e.stopPropagation();
+        form.querySelector('.note-form-cancel')?.click();
+      }
+    });
+
+    // Save. Prevent the button from stealing focus on press: on mobile, the
+    // first tap would otherwise just blur the focused textarea/input (closing
+    // the keyboard and shifting layout), so the tap never reached the button and
+    // you had to tap "Done" twice. mousedown preventDefault keeps focus put while
+    // still letting the click fire.
+    const _saveBtnEl0 = form.querySelector('.note-form-save');
+    _saveBtnEl0.addEventListener('mousedown', (e) => e.preventDefault());
+    _saveBtnEl0.addEventListener('click', async () => {
+      // Guard against spam-clicks: the drawing save AWAITS a canvas upload before
+      // the optimistic re-render removes the form, so without this a slow upload
+      // let repeated clicks create duplicate notes.
+      const _saveBtn = form.querySelector('.note-form-save');
+      if (_saveBtn._saving) return;
+      // Mobile: when an existing note is opened and closed without edits, the
+      // Update (✓) button morphs into Archive (set up below). Route the click
+      // directly through the archive flow. Using a DOM .click() proxy here was
+      // fragile on mobile because the real archive button can move from the
+      // footer to the fullscreen header.
+      if (_saveBtn.classList.contains('archive-mode')) {
+        _archiveNoteById(note?.id);
+        return;
+      }
+      _saveBtn._saving = true; _saveBtn.disabled = true; _saveBtn.style.opacity = '0.5';
+      try {
+      form._flushDraft?.();
+      await form._stopDraftAutosave?.();
+      form._flushDraft?.();
+      const title = form.querySelector('.note-form-title').value.trim();
+      // Normalize tag input: split on whitespace, strip leading #s, dedupe,
+      // re-join with single spaces. Empty → null.
+      const _rawLabel = form.querySelector('.note-form-label')?.value || '';
+      const _tags = [...new Set(_rawLabel.split(/\s+/).map(t => t.replace(/^#+/, '').trim()).filter(Boolean))];
+      if (form.querySelector('.note-form-due').value && !_tags.includes('reminder')) _tags.push('reminder');
+      const labelVal = _tags.length ? _tags.join(' ') : null;
+      const payload = {
+        title,
+        note_type: currentType,
+        color: currentColor,
+        label: labelVal,
+        due_date: form.querySelector('.note-form-due').value || null,
+        repeat: form.querySelector('.note-form-repeat')?.value || 'none',
+        image_url: currentImageUrl || null,
+      };
+      if (currentType === 'note') {
+        payload.content = form.querySelector('.note-form-content')?.value || '';
+      } else if (currentType === 'draw') {
+        // Upload the canvas PNG before saving so image_url points to a
+        // persistent file. We block the save until upload completes : drawings
+        // can't be re-rendered later without the URL.
+        const canvas = form.querySelector('.note-form-canvas');
+        const upload = await _uploadCanvasAsPng(canvas, note?.gallery_id || null);
+        if (!upload?.url) { uiModule.showError('Failed to save drawing'); return; }
+        payload.image_url = upload.url;
+        if (upload.galleryId) payload.gallery_id = upload.galleryId;
+      } else if (currentType === 'goal') {
+        // Legacy: existing goal-type notes still edit through this branch.
+        // No AI involvement : save as a normal note with description + items.
+        payload.content = form.querySelector('.note-form-goal-desc')?.value || '';
+        payload.items = _collectItems(form);
+      } else {
+        payload.items = _collectItems(form);
+      }
+      if (isEdit) payload.id = note.id;
+      submitNote(payload, note, isEdit);
+      } finally {
+        // Re-enable on early returns / errors. On success the form is removed by
+        // the optimistic re-render, so re-enabling the detached button is a no-op.
+        _saveBtn._saving = false; _saveBtn.disabled = false; _saveBtn.style.opacity = '';
+      }
+    });
+
+    // Mobile-only: when editing an existing note, the Update (✓) button starts in
+    // archive-mode (visually + behaviorally) and flips to Update on the first
+    // edit. Lets the user tap a note to skim, then tap ✓ to archive without ever
+    // touching a separate Archive button.
+    if (isEdit && window.innerWidth <= 768) {
+      const _saveLabelEl = _saveBtnEl0.querySelector('.nft-label');
+      const _isFinishedTodo = () => {
+        if (currentType !== 'todo') return false;
+        const rows = [...form.querySelectorAll('.note-cl-row')];
+        const withText = rows.filter(row => (row.querySelector('.note-cl-text')?.value || '').trim());
+        return withText.length > 0 && withText.every(row => row.classList.contains('done'));
+      };
+      const _enterArchive = () => {
+        _saveBtnEl0.classList.add('archive-mode');
+        const label = _isFinishedTodo() ? 'Finish' : 'Archive';
+        if (_saveLabelEl) _saveLabelEl.textContent = label;
+        _saveBtnEl0.title = label;
+      };
+      const _enterUpdate = () => {
+        if (!_saveBtnEl0.classList.contains('archive-mode')) return;
+        _saveBtnEl0.classList.remove('archive-mode');
+        if (_saveLabelEl) _saveLabelEl.textContent = 'Update';
+        _saveBtnEl0.title = 'Update';
+      };
+      _enterArchive();
+      form.addEventListener('input', _enterUpdate, true);
+      form.addEventListener('change', _enterUpdate, true);
+      // Checklist dots use a custom control and dispatch their update before
+      // this click bubbles. Re-evaluate afterward so a fully completed todo
+      // offers Finish (which archives/removes it from the active list).
+      form.addEventListener('click', (event) => {
+        if (!event.target.closest('.note-cl-dot')) return;
+        setTimeout(() => {
+          if (_isFinishedTodo()) _enterArchive();
+          else _enterUpdate();
+        }, 0);
+      }, true);
+    }
+
+    // Cancel
+    form.querySelector('.note-form-cancel').addEventListener('click', () => { form._flushDraft?.(); app.setEditingId(null); _renderNotes(); });
+
+    // Archive / Delete : edit-mode-only buttons, mirror the (now-hidden) card actions.
+    form.querySelector('.note-form-archive-btn')?.addEventListener('click', () => {
+      if (!isEdit) return;
+      _archiveNoteById(note.id);
+    });
+    form.querySelector('.note-form-delete-btn')?.addEventListener('click', () => {
+      if (!isEdit) return;
+      return deleteFromEditor(note.id);
+    });
+
+    // Autosave a draft to persistence on every change so unsaved edits
+    // survive connection loss / reload / accidental close.
+    _wireDraftAutosave(form, isEdit ? note.id : '__new__');
+
+    return form;
+  }
+
+  return { _buildForm };
+}
diff --git a/static/js/features/notes/ui/filters.js b/static/js/features/notes/ui/filters.js
new file mode 100644
index 000000000..49142a260
--- /dev/null
+++ b/static/js/features/notes/ui/filters.js
@@ -0,0 +1,139 @@
+/** Label chips, reminder/goal filters and collapsed tag-strip rendering. */
+import { _visibleNoteTags, _nextGoalStep } from '../domain/noteRules.js';
+import { _hasTimeComponent } from '../domain/recurrence.js';
+export function createFilters({
+  NOTES_LABELS_COLLAPSED_KEY,
+  _clearPastReminders,
+  _esc,
+  _isPastReminder,
+  _renderNotes,
+  _userVisibleNotes,
+  app,
+  persistence,
+  state
+}) {
+  function _renderLabels(root = document) {
+    const bar = root.querySelector?.('.notes-labels-bar') || document.querySelector('.notes-labels-bar');
+    if (!bar) return;
+    if (state.labelsCollapsed) {
+      bar.innerHTML = '';
+      bar.style.display = 'none';
+      return;
+    }
+    const visibleNotes = _userVisibleNotes();
+    const labels = new Set();
+    for (const n of visibleNotes) for (const t of _visibleNoteTags(n)) labels.add(t);
+    const sortedLabels = [...labels].sort();
+    // Count active reminders (not archived, has datetime due_date)
+    const reminderCount = visibleNotes.filter(n => !n.archived && n.due_date && _hasTimeComponent(n.due_date)).length;
+    const pastReminderCount = visibleNotes.filter(n => !n.archived && _isPastReminder(n)).length;
+    const defaultCount = visibleNotes.filter(n => !n.archived && _visibleNoteTags(n).length === 0).length;
+    // Active goals = non-archived goal notes. Today view lists pending steps
+    // from each, so we surface the count next to the chip.
+    const goalCount = visibleNotes.filter(n => n.note_type === 'goal' && !n.archived).length;
+    const todayCount = visibleNotes.filter(n => n.note_type === 'goal' && !n.archived && _nextGoalStep(n)).length;
+    const hasUsefulFilters = sortedLabels.length > 0 || reminderCount > 0 || goalCount > 0;
+    const hasActiveFilter = state.activeLabel !== null || state.activeFilter !== null;
+    if (!hasUsefulFilters && !hasActiveFilter) {
+      bar.innerHTML = '';
+      bar.style.display = 'none';
+      return;
+    }
+    bar.style.display = '';
+    const allActive = state.activeLabel === null && state.activeFilter === null;
+    let html = `<button class="notes-label-chip${allActive ? ' active' : ''}" data-action="all">All</button>`;
+    html += `<button class="notes-label-chip${state.activeFilter === 'default' ? ' active' : ''}" data-action="default" title="Show notes without tags">Default <span class="notes-label-chip-count">${defaultCount}</span></button>`;
+    if (todayCount > 0) {
+      const isOn = state.activeFilter === 'today';
+      const icon = '<svg width="10" height="10" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round" style="vertical-align:-1px;margin-right:2px"><rect x="3" y="4" width="18" height="18" rx="2"/><line x1="16" y1="2" x2="16" y2="6"/><line x1="8" y1="2" x2="8" y2="6"/><line x1="3" y1="10" x2="21" y2="10"/></svg>';
+      html += `<button class="notes-label-chip notes-label-chip-today${isOn ? ' active' : ''}" data-action="today" title="Next step from every goal">${icon}Today <span class="notes-label-chip-count">${todayCount}</span></button>`;
+    }
+    if (goalCount > 0) {
+      const isOn = state.activeFilter === 'goals';
+      const icon = '<svg width="10" height="10" viewBox="0 0 24 24" fill="currentColor" style="vertical-align:-1px;margin-right:2px"><path d="M12 0L14.59 8.41L23 12L14.59 15.59L12 24L9.41 15.59L1 12L9.41 8.41Z"/></svg>';
+      html += `<button class="notes-label-chip notes-label-chip-goals${isOn ? ' active' : ''}" data-action="goals" title="Show only goals">${icon}Goals <span class="notes-label-chip-count">${goalCount}</span></button>`;
+    }
+    const isReminderOn = state.activeFilter === 'reminders';
+    const isReminderOff = state.activeFilter === 'no-reminders';
+    const reminderCls = `notes-label-chip notes-label-chip-reminders${isReminderOn ? ' active' : ''}${isReminderOff ? ' active negated' : ''}`;
+    const reminderIcon = isReminderOff
+      // bell-off icon
+      ? '<svg width="10" height="10" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round" style="vertical-align:-1px;margin-right:2px"><path d="M13.73 21a2 2 0 0 1-3.46 0"/><path d="M18.63 13A17.89 17.89 0 0 1 18 8"/><path d="M6.26 6.26A5.86 5.86 0 0 0 6 8c0 7-3 9-3 9h14"/><path d="M18 8a6 6 0 0 0-9.33-5"/><line x1="1" y1="1" x2="23" y2="23"/></svg>'
+      : '<svg width="10" height="10" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round" style="vertical-align:-1px;margin-right:2px"><path d="M18 8A6 6 0 0 0 6 8c0 7-3 9-3 9h18s-3-2-3-9"/><path d="M13.73 21a2 2 0 0 1-3.46 0"/></svg>';
+    html += `<button class="${reminderCls}" data-action="reminders" title="${isReminderOn ? 'Showing only reminders — click to show all' : isReminderOff ? 'Hiding reminders — click to show only reminders' : 'Click to filter reminders'}">${reminderIcon}Reminders <span class="notes-label-chip-count">${reminderCount}</span></button>`;
+    const showingReminders = state.activeFilter === 'reminders';
+    if (showingReminders && pastReminderCount > 0) {
+      html += `<button class="notes-label-chip notes-label-clear-past" data-action="clear-past-reminders" title="Delete reminders whose time has passed"><svg width="10" height="10" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.4" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><polyline points="3 6 5 6 21 6"/><path d="M19 6l-1 14a2 2 0 0 1-2 2H8a2 2 0 0 1-2-2L5 6"/><path d="M8 6V4a2 2 0 0 1 2-2h4a2 2 0 0 1 2 2v2"/></svg>Clear past <span class="notes-label-chip-count">${pastReminderCount}</span></button>`;
+    }
+    for (const lbl of sortedLabels) {
+      html += `<button class="notes-label-chip${state.activeLabel === lbl ? ' active' : ''}" data-label="${_esc(lbl)}">#${_esc(lbl)}</button>`;
+    }
+    bar.innerHTML = html;
+    bar.querySelectorAll('.notes-label-chip').forEach(chip => {
+      chip.addEventListener('click', () => {
+        if (chip.dataset.action === 'all') {
+          app.setActiveLabel(null);
+          app.setActiveFilter(null);
+        } else if (chip.dataset.action === 'today') {
+          app.setActiveLabel(null);
+          app.setActiveFilter((state.activeFilter === 'today') ? null : 'today');
+        } else if (chip.dataset.action === 'goals') {
+          app.setActiveLabel(null);
+          app.setActiveFilter((state.activeFilter === 'goals') ? null : 'goals');
+        } else if (chip.dataset.action === 'default') {
+          app.setActiveLabel(null);
+          app.setActiveFilter((state.activeFilter === 'default') ? null : 'default');
+        } else if (chip.dataset.action === 'reminders') {
+          app.setActiveLabel(null);
+          // Cycle: null → reminders → null → no-reminders → null → reminders → ...
+          if (state.activeFilter === null) {
+            app.setActiveFilter(state.reminderChipNext);
+            app.setReminderChipNext((state.reminderChipNext === 'reminders') ? 'no-reminders' : 'reminders');
+          } else {
+            app.setActiveFilter(null);
+          }
+        } else if (chip.dataset.action === 'clear-past-reminders') {
+          _clearPastReminders();
+          return;
+        } else {
+          app.setActiveFilter(null);
+          app.setActiveLabel(chip.dataset.label || null);
+        }
+        _renderNotes();
+      });
+    });
+  }
+
+  function _renderLabelsInto(_body) {
+    if (!_body) return;
+    const pane = _body.closest('.notes-pane');
+    const toggleHost = pane?.querySelector('.notes-search-bar') || _body;
+    let toggle = toggleHost.querySelector(':scope > .notes-label-toggle');
+    if (!toggle) {
+      toggle = document.createElement('button');
+      toggle.type = 'button';
+      toggle.className = 'notes-label-toggle cal-filter-toggle';
+      toggle.addEventListener('click', () => {
+        app.setLabelsCollapsed(!state.labelsCollapsed);
+        try { persistence.setItem(NOTES_LABELS_COLLAPSED_KEY, state.labelsCollapsed ? '1' : '0'); } catch {}
+        _renderNotes();
+      });
+      const selectButton = toggleHost.querySelector('#notes-select-btn');
+      toggleHost.insertBefore(toggle, selectButton || null);
+    }
+    toggle.textContent = state.labelsCollapsed ? '+ Tags' : '− Tags';
+    toggle.title = state.labelsCollapsed ? 'Show tags' : 'Hide tags';
+    toggle.setAttribute('aria-expanded', state.labelsCollapsed ? 'false' : 'true');
+
+    // The shared chip scroller wraps this row once it is mounted.
+    let bar = _body.querySelector('.notes-labels-bar');
+    if (!bar) {
+      bar = document.createElement('div');
+      bar.className = 'notes-labels-bar';
+      _body.appendChild(bar);
+    }
+    _renderLabels(_body);
+  }
+
+  return { _renderLabels, _renderLabelsInto };
+}
diff --git a/static/js/features/notes/ui/layout.js b/static/js/features/notes/ui/layout.js
new file mode 100644
index 000000000..8935feff5
--- /dev/null
+++ b/static/js/features/notes/ui/layout.js
@@ -0,0 +1,123 @@
+/** Card reflow animation and the owned masonry resize observer. */
+export function createLayout({ isOpen = () => true } = {}) {
+  function _captureCardPositions() {
+    const body = document.querySelector('#notes-pane .notes-pane-body');
+    if (!body) return null;
+    const positions = new Map();
+    body.querySelectorAll('.note-card').forEach(card => {
+      const id = card.dataset.noteId;
+      if (id) positions.set(id, card.getBoundingClientRect());
+    });
+    return positions;
+  }
+
+  function _animateReflow(prevPositions) {
+    if (!prevPositions || !prevPositions.size) return;
+    const body = document.querySelector('#notes-pane .notes-pane-body');
+    if (!body || !body.isConnected) return;
+    body.querySelectorAll('.note-card').forEach(card => {
+      const id = card.dataset.noteId;
+      const prev = prevPositions.get(id);
+      if (!prev) return;
+      const next = card.getBoundingClientRect();
+      const dx = prev.left - next.left;
+      const dy = prev.top - next.top;
+      if (Math.abs(dx) < 1 && Math.abs(dy) < 1) return;
+      // Invert: jump back to old position
+      card.style.transition = 'none';
+      card.style.transform = `translate(${dx}px, ${dy}px)`;
+      // Play: animate to 0
+      requestAnimationFrame(() => {
+        card.style.transition = 'transform 0.25s cubic-bezier(0.34, 1.2, 0.64, 1)';
+        card.style.transform = '';
+        card.addEventListener('transitionend', () => {
+          card.style.transition = '';
+        }, { once: true });
+      });
+    });
+  }
+
+  function _applyMasonry(body) {
+    if (!body || !body.isConnected) return;
+    const pane = body.closest('.notes-pane');
+    const isGrid = pane?.classList.contains('notes-view-grid');
+    const isMobileGrid = isGrid && window.matchMedia('(max-width: 768px)').matches;
+    // Tear down any prior observer (defensive : _renderNotes wipes body.innerHTML).
+    if (_masonryObserver) { try { _masonryObserver.disconnect(); } catch {} _masonryObserver = null; }
+    // A save that resolves after close re-renders the leaving pane; don't
+    // re-create the observer that panel teardown already disposed.
+    if (!isOpen()) return;
+    if (!isGrid) {
+      // Clear any leftover inline spans so list view lays out normally.
+      body.querySelectorAll('.note-card, .notes-label-toggle, .notes-labels-bar, .notes-quick-add, .note-form, .doclib-chip-scroll-frame:has(> .notes-labels-bar)').forEach(c => { c.style.gridRowEnd = ''; });
+      return;
+    }
+    const ROW_PX = 4;
+    const spanForHeight = (h) => Math.max(1, Math.ceil(h / ROW_PX));
+    const recomputeFullRows = () => {
+      const quickAdd = body.querySelector('.notes-quick-add');
+      const labelsToggle = body.querySelector('.notes-label-toggle');
+      const labelsBar = body.querySelector('.notes-labels-bar');
+      const labelsLayout = labelsBar?.parentElement?.classList.contains('doclib-chip-scroll-frame')
+        ? labelsBar.parentElement
+        : labelsBar;
+      if (labelsToggle && getComputedStyle(labelsToggle).display !== 'none') {
+        labelsToggle.style.gridRowEnd = `span ${Math.max(1, spanForHeight(labelsToggle.scrollHeight))}`;
+      }
+      if (labelsLayout && getComputedStyle(labelsLayout).display !== 'none') {
+        const shave = isMobileGrid ? 4 : 0;
+        labelsLayout.style.gridRowEnd = `span ${Math.max(1, spanForHeight(labelsLayout.scrollHeight) - shave)}`;
+      }
+      if (quickAdd) {
+        const shave = isMobileGrid ? 4 : 0;
+        quickAdd.style.gridRowEnd = `span ${Math.max(1, spanForHeight(quickAdd.scrollHeight + 10) - shave)}`;
+      }
+      body.querySelectorAll('.note-form').forEach(form => {
+        form.style.gridColumn = '1 / -1';
+        const isDrawForm = !!form.querySelector('.note-form-type-seg.is-draw');
+        const minSpan = isMobileGrid ? (isDrawForm ? 104 : 64) : 1;
+        const renderedHeight = form.getBoundingClientRect?.().height || 0;
+        const drawReserve = isDrawForm && isMobileGrid ? 12 : 12;
+        const measuredHeight = Math.max(form.scrollHeight, renderedHeight) + drawReserve;
+        form.style.gridRowEnd = `span ${Math.max(minSpan, spanForHeight(measuredHeight))}`;
+      });
+    };
+    const recompute = (card) => {
+      // scrollHeight returns the natural content height : card.getBoundingClientRect()
+      // would return the grid cell height (collapsed to 4px until the span is set,
+      // which is the value we're trying to compute).
+      const h = card.scrollHeight + (isMobileGrid ? 6 : 8);
+      if (h <= 0) return;
+      card.style.gridRowEnd = `span ${spanForHeight(h)}`;
+    };
+    recomputeFullRows();
+    body.querySelectorAll('.note-card').forEach(recompute);
+    // Watch masonry participants : content can grow (image load, todo edits,
+    // quick-add/form expansion), and stale spans are what cause visual merging.
+    if ('ResizeObserver' in window) {
+      _masonryObserver = new ResizeObserver(entries => {
+        let fullRowsChanged = false;
+        for (const e of entries) {
+          if (e.target.classList.contains('note-card')) recompute(e.target);
+          else fullRowsChanged = true;
+        }
+        if (fullRowsChanged) recomputeFullRows();
+      });
+      body.querySelectorAll('.note-card').forEach(c => _masonryObserver.observe(c));
+    body.querySelectorAll('.notes-label-toggle, .notes-quick-add, .note-form').forEach(c => _masonryObserver.observe(c));
+    const labelsBar = body.querySelector('.notes-labels-bar');
+    const labelsLayout = labelsBar?.parentElement?.classList.contains('doclib-chip-scroll-frame')
+      ? labelsBar.parentElement
+      : labelsBar;
+    if (labelsLayout) _masonryObserver.observe(labelsLayout);
+    }
+  }
+
+  let _masonryObserver = null;
+
+  function dispose() {
+    _masonryObserver?.disconnect();
+    _masonryObserver = null;
+  }
+  return { dispose, _captureCardPositions, _animateReflow, _applyMasonry };
+}
diff --git a/static/js/features/notes/ui/lifecycle.js b/static/js/features/notes/ui/lifecycle.js
new file mode 100644
index 000000000..67a8da199
--- /dev/null
+++ b/static/js/features/notes/ui/lifecycle.js
@@ -0,0 +1,36 @@
+/** Notes-owned document/window listeners. Detached editor/menu owners release their resources. */
+export function createNotesLifecycle() {
+    const owners = new Map();
+    let observer = null;
+    function release(owner) {
+      const entry = owners.get(owner);
+      if (!entry) return;
+      owners.delete(owner);
+      for (const remove of entry.removers) remove();
+      if (!owners.size) { observer?.disconnect(); observer = null; }
+    }
+    function onDispose(owner, remove) {
+      if (!owner) throw new Error('Notes listener needs a lifecycle owner');
+      let entry = owners.get(owner);
+      if (!entry) {
+        entry = { connected: owner.isConnected, removers: [] };
+        owners.set(owner, entry);
+      }
+      entry.removers.push(remove);
+      if (!observer) {
+        observer = new MutationObserver(() => {
+          for (const [node, scope] of owners) {
+            if (node.isConnected) scope.connected = true;
+            else if (scope.connected) release(node);
+          }
+        });
+        observer.observe(document.body, { childList: true, subtree: true });
+      }
+    }
+    function listen(owner, target, event, listener, options) {
+      onDispose(owner, () => target.removeEventListener(event, listener, options));
+      target.addEventListener(event, listener, options);
+    }
+    function dispose() { for (const owner of [...owners.keys()]) release(owner); }
+    return { listen, onDispose, release, dispose };
+}
diff --git a/static/js/features/notes/ui/mobileEditor.js b/static/js/features/notes/ui/mobileEditor.js
new file mode 100644
index 000000000..f751ba7aa
--- /dev/null
+++ b/static/js/features/notes/ui/mobileEditor.js
@@ -0,0 +1,257 @@
+/** Mobile fullscreen editing, link reader mode and return to the panel. */
+export function createMobileEditor({
+  _applyDraftToNote,
+  _buildForm,
+  _fetchNotes,
+  _linkify,
+  _renderNotes,
+  _uid,
+  _wireChecklistTouchReorder,
+  _wireRow,
+  app,
+  state,
+  uiModule
+}) {
+  function _isNotesMobileMode() {
+    return ('ontouchstart' in window) && window.innerWidth <= 768;
+  }
+
+  let _mobileFsOverlay = null;
+
+  let _mobileFsNoteId = null;
+
+  function _openMobileFullscreenEdit(id, fromCard) {
+    const note = state.notes.find(n => n.id === id);
+    if (!note) return;
+    // Tear down any previous overlay (defensive).
+    _closeMobileFullscreenEdit({ save: false });
+    _mobileFsNoteId = id;
+    app.setEditingId(id);
+
+    const overlay = document.createElement('div');
+    overlay.className = 'note-fullscreen-overlay';
+    overlay.innerHTML = `
+    <div class="note-fullscreen-header">
+      <button type="button" class="note-fullscreen-back" title="Back">
+        <svg width="22" height="22" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round"><polyline points="15 18 9 12 15 6"></polyline></svg>
+      </button>
+      <div class="note-fullscreen-actions"></div>
+    </div>
+    <div class="note-fullscreen-body"></div>
+  `;
+    const body = overlay.querySelector('.note-fullscreen-body');
+    // Reuse the same edit form the in-place flow builds. Save buttons,
+    // checklist toggles, etc. all work as-is. Restore any unsaved draft.
+    const { note: _n, restored } = _applyDraftToNote(note, id);
+    const form = _buildForm(_n);
+    body.appendChild(form);
+    if (restored) uiModule.showToast('Restored unsaved changes');
+    document.body.appendChild(overlay);
+    _mobileFsOverlay = overlay;
+
+    // Animate up from the tapped tile's position so the transition reads
+    // as a zoom rather than a hard cut.
+    if (fromCard) {
+      const r = fromCard.getBoundingClientRect();
+      const vw = window.innerWidth, vh = window.innerHeight;
+      overlay.style.transformOrigin =
+        `${((r.left + r.width / 2) / vw) * 100}% ${((r.top + r.height / 2) / vh) * 100}%`;
+    }
+    overlay.classList.add('opening');
+    requestAnimationFrame(() => overlay.classList.add('open'));
+
+    // Wire the back button : saves whatever the form has and closes.
+    // mousedown preventDefault so it doesn't blur the input on first tap (which
+    // would eat the tap and require a second one).
+    const _backBtn = overlay.querySelector('.note-fullscreen-back');
+    _backBtn.addEventListener('mousedown', (e) => e.preventDefault());
+    _backBtn.addEventListener('click', () => {
+      _closeMobileFullscreenEdit({ save: true });
+    });
+
+    // The form's built-in Cancel only resets the in-place edit state; in
+    // the overlay context it does nothing visible. Replace its handler so
+    // Cancel actually dismisses the overlay without saving.
+    const cancelBtn = form.querySelector('.note-form-cancel');
+    if (cancelBtn) {
+      const fresh = cancelBtn.cloneNode(true);
+      cancelBtn.parentNode.replaceChild(fresh, cancelBtn);
+      fresh.addEventListener('mousedown', (e) => e.preventDefault());
+      fresh.addEventListener('click', (e) => {
+        e.preventDefault();
+        e.stopPropagation();
+        _closeMobileFullscreenEdit({ save: false });
+      });
+    }
+    // The built-in Save handler does the API call + refresh, but doesn't
+    // dismiss our overlay. Augment it (do NOT replace : the original is
+    // async and we'd lose the API call) to schedule a close once the
+    // save+render has had time to complete.
+    const saveBtn = form.querySelector('.note-form-save');
+    if (saveBtn) {
+      saveBtn.addEventListener('click', () => {
+        setTimeout(() => _closeMobileFullscreenEdit({ save: false }), 350);
+      });
+    }
+    // Make the checklist row drag handle (⋮⋮) actually work on touch.
+    // The form's default uses HTML5 native draggable which never fires
+    // on iOS/Android. Wire touch-based reorder for any row inside the
+    // overlay's checklist.
+    _wireChecklistTouchReorder(form);
+
+    // For each todo row whose text contains a URL, swap the bare <input>
+    // for a linkified <span> so URLs are tappable. Tapping anywhere that
+    // ISN'T a link flips back to the input for editing.
+    form.querySelectorAll('.note-cl-row').forEach(_addRowReadMode);
+
+    // Move only Delete from the form's footer actions row into the header.
+    // Archive intentionally stays out of the header: the footer Update button
+    // already morphs into the mobile Archive action for an untouched note.
+    const headerActions = overlay.querySelector('.note-fullscreen-actions');
+    const archiveBtn = form.querySelector('.note-form-archive-btn');
+    const deleteBtn  = form.querySelector('.note-form-delete-btn');
+    if (headerActions && deleteBtn) {
+      deleteBtn.classList.remove('note-form-collapsible');
+      headerActions.appendChild(deleteBtn);
+    }
+    // The built-in archive/delete handlers re-render the notes grid but
+    // leave THIS overlay sitting in front of it : looks like nothing
+    // happened. Add follow-up listeners that close the overlay so the
+    // user sees the action take effect.
+    if (archiveBtn) {
+      archiveBtn.addEventListener('click', () => {
+        setTimeout(() => _closeMobileFullscreenEdit({ save: false }), 200);
+      });
+    }
+    if (deleteBtn) {
+      deleteBtn.addEventListener('click', () => {
+        // Delete shows a styled confirm : give it room to resolve before
+        // we try to dismiss the overlay.
+        setTimeout(() => _closeMobileFullscreenEdit({ save: false }), 500);
+      });
+    }
+
+    // Tuck the tags input into the bottom actions row (Cancel / Update),
+    // pinned to the LEFT. Frees the meta row of an extra wrapping line
+    // and groups all the "exit" controls together.
+    const actionsGroup = form.querySelector('.note-form-actions-group');
+    const tagsInput    = form.querySelector('.note-form-label');
+    if (actionsGroup && tagsInput) {
+      actionsGroup.insertBefore(tagsInput, actionsGroup.firstChild);
+    }
+
+    // For checklist-type notes, move the photo (attach image) button into
+    // the same row as the + Add button (right side) : keeps the meta row
+    // tidy and puts the camera within thumb-reach of the active edit.
+    const addBtn   = form.querySelector('.note-cl-add');
+    const photoBtn = form.querySelector('.note-form-photo-btn');
+    if (addBtn && photoBtn) {
+      const addRow = document.createElement('div');
+      addRow.className = 'note-cl-add-row';
+      addBtn.parentNode.insertBefore(addRow, addBtn);
+      addRow.appendChild(addBtn);
+      addRow.appendChild(photoBtn);
+      // Tapping anywhere on the row (the empty gap, the dashed border,
+      // the "+ Add" label) triggers add. The photo button keeps its own
+      // click target so attach-image isn't ambushed.
+      addRow.addEventListener('click', (e) => {
+        if (e.target.closest('.note-form-photo-btn')) return;
+        if (e.target === addBtn || addBtn.contains(e.target)) return;
+        addBtn.click();
+      });
+      // The form's delegated "+ Add" handler does
+      //   inputs.insertBefore(newRow, addBtn)
+      // : but addBtn is no longer a direct child of `.note-checklist-inputs`
+      // now that we wrapped it. Bind a fresh handler that does the same
+      // thing but inserts before the WRAPPING row, and stop propagation
+      // so the broken delegate never runs.
+      addBtn.addEventListener('click', (e) => {
+        e.preventDefault();
+        e.stopPropagation();
+        const inputs = form.querySelector('.note-checklist-inputs');
+        if (!inputs) return;
+        const newRow = document.createElement('div');
+        newRow.className = 'note-cl-row';
+        newRow.draggable = true;
+        newRow.dataset.itemId = _uid();
+        newRow.dataset.indent = '0';
+        newRow.innerHTML = '<span class="note-cl-grip" title="Drag">⋮⋮</span><span class="note-cl-dot"></span><input type="text" class="note-cl-text" placeholder="Item..." /><button type="button" class="note-cl-rm">&times;</button>';
+        inputs.insertBefore(newRow, addRow);
+        _wireRow(newRow, inputs);
+        // Touch reorder on the freshly-added row's grip.
+        _wireChecklistTouchReorder(form);
+        newRow.querySelector('.note-cl-text')?.focus();
+      }, { capture: true });
+    }
+
+    // Read-mode overlay for plain notes: render the content as a div with
+    // clickable hyperlinks, layered above the textarea. Tapping anywhere
+    // in the overlay that ISN'T a link hides the overlay and focuses the
+    // textarea so the user can start editing. Tapping a link opens it.
+    const ta = form.querySelector('.note-form-content');
+    if (ta && (note.content || '').trim()) {
+      const reader = document.createElement('div');
+      reader.className = 'note-form-content-reader';
+      reader.innerHTML = _linkify(note.content || '');
+      ta.style.display = 'none';
+      ta.insertAdjacentElement('beforebegin', reader);
+      reader.addEventListener('click', (e) => {
+        if (e.target.closest('a')) return;  // let links open normally
+        reader.remove();
+        ta.style.display = '';
+        // Let the browser place the cursor naturally : forcing
+        // setSelectionRange right after focus() raced with the underlying
+        // tap event and produced inconsistent cursor positions on mobile.
+        ta.focus({ preventScroll: true });
+      });
+    }
+
+    // Opening an EXISTING note → read mode, no keyboard pop. Only a
+    // brand-new note (created via the + button) should auto-focus an
+    // input field. The user can tap the content to switch to edit.
+    // (New-note creation flows through _createNote, not this function.)
+  }
+
+  function _closeMobileFullscreenEdit(opts = {}) {
+    if (!_mobileFsOverlay) return;
+    const overlay = _mobileFsOverlay;
+    overlay.querySelector('.note-form')?._flushDraft?.();
+    _mobileFsOverlay = null;
+    // If the form has a Save button, click it on close so edits aren't lost
+    // when the user uses the back arrow instead of an explicit Save.
+    if (opts.save) {
+      const saveBtn = overlay.querySelector('.note-form-save, [data-action="save"]');
+      if (saveBtn) try { saveBtn.click(); } catch {}
+    }
+    overlay.classList.remove('open');
+    overlay.classList.add('closing');
+    setTimeout(() => {
+      if (overlay.parentNode) overlay.parentNode.removeChild(overlay);
+      _mobileFsNoteId = null;
+      app.setEditingId(null);
+      // Refresh the grid so any save the user made is reflected.
+      if (opts.save !== false) { _fetchNotes().then(_renderNotes).catch(() => {}); }
+    }, 220);
+  }
+
+  function _addRowReadMode(row) {
+    const txt = row.querySelector('.note-cl-text');
+    if (!txt) return;
+    const val = txt.value || '';
+    if (!/(https?:\/\/|www\.)/i.test(val)) return;
+    if (row.querySelector('.note-cl-text-reader')) return;  // already wired
+    const span = document.createElement('span');
+    span.className = 'note-cl-text-reader';
+    span.innerHTML = _linkify(val);
+    txt.style.display = 'none';
+    txt.insertAdjacentElement('beforebegin', span);
+    span.addEventListener('click', (e) => {
+      if (e.target.closest('a')) return;  // let the link open
+      span.remove();
+      txt.style.display = '';
+      txt.focus({ preventScroll: true });
+    });
+  }
+
+  return { _isNotesMobileMode, _openMobileFullscreenEdit, _closeMobileFullscreenEdit, _addRowReadMode };
+}
diff --git a/static/js/features/notes/ui/mobileReorder.js b/static/js/features/notes/ui/mobileReorder.js
new file mode 100644
index 000000000..b5f6404d3
--- /dev/null
+++ b/static/js/features/notes/ui/mobileReorder.js
@@ -0,0 +1,214 @@
+/** Mobile card long press, placeholder drag and reorder persistence. */
+export function createMobileReorder({
+  lifecycle,
+  _applyMasonry,
+  _enterSelectMode,
+  commitMobileOrder,
+  app,
+}) {
+  function _bindLongPressDrag(card) {
+    let pressTimer = null;
+    let startX = 0, startY = 0;
+    let armed = false;
+    const CANCEL_PX = 8;
+    const HOLD_MS = 450;
+
+    card.addEventListener('touchstart', (e) => {
+      // Don't fight scroll on touchpoints over real interactive children
+      // (in mobile-mode they're CSS-hidden anyway, but be defensive).
+      if (e.target.closest('button, input, a, .note-form')) return;
+      if (e.touches.length !== 1) return;
+      armed = true;
+      startX = e.touches[0].clientX;
+      startY = e.touches[0].clientY;
+      pressTimer = setTimeout(() => {
+        if (!armed) return;
+        try { navigator.vibrate?.(15); } catch {}
+        app.setSuppressNextNoteTapId(card.dataset.noteId);
+        _enterSelectMode(card.dataset.noteId);
+      }, HOLD_MS);
+    }, { passive: true });
+    card.addEventListener('touchmove', (e) => {
+      if (!armed) return;
+      const t = e.touches[0];
+      if (Math.abs(t.clientX - startX) > CANCEL_PX || Math.abs(t.clientY - startY) > CANCEL_PX) {
+        armed = false;
+        if (pressTimer) { clearTimeout(pressTimer); pressTimer = null; }
+      }
+    }, { passive: true });
+    const cancel = () => {
+      armed = false;
+      if (pressTimer) { clearTimeout(pressTimer); pressTimer = null; }
+    };
+    lifecycle.onDispose(card, cancel);
+    card.addEventListener('touchend', cancel, { passive: true });
+    card.addEventListener('touchcancel', cancel, { passive: true });
+  }
+
+  let _dragState = null;
+
+  let _docDragHandlersBound = false;
+
+  function _enterDragMode(initialCard, initialTouch) {
+    document.body.classList.add('notes-drag-mode');
+    document.querySelectorAll('.note-card').forEach(_setupDragForCard);
+    if (!_docDragHandlersBound) {
+      lifecycle.listen(document.getElementById('notes-pane'), document, 'touchmove', _onDocTouchMove, { passive: false });
+      lifecycle.listen(document.getElementById('notes-pane'), document, 'touchend',  _onDocTouchEnd,  { passive: true });
+      lifecycle.listen(document.getElementById('notes-pane'), document, 'touchcancel', _onDocTouchEnd, { passive: true });
+      _docDragHandlersBound = true;
+    }
+    // Auto-grab the card the user long-pressed : they're already holding
+    // their finger on it, so begin the drag straight away. Releasing
+    // (touchend) commits the reorder AND exits drag mode in one motion.
+    if (initialCard && initialTouch) {
+      _beginGrab(initialCard, initialTouch);
+    }
+  }
+
+  function _exitDragMode() {
+    document.body.classList.remove('notes-drag-mode');
+    if (_dragState) {
+      // Defensive: if exit fires while a drag is in flight, snap the card back.
+      _onDocTouchEnd();
+    }
+    // Leave _docDragHandlersBound true so re-entering drag mode reuses them.
+  }
+
+  function _setupDragForCard(card) {
+    if (card.dataset.dragBound === '1') return;
+    card.dataset.dragBound = '1';
+    card.addEventListener('touchstart', (e) => {
+      if (!document.body.classList.contains('notes-drag-mode')) return;
+      if (e.touches.length !== 1) return;
+      if (_dragState) return;
+      e.preventDefault();
+      e.stopPropagation();
+      _beginGrab(card, e.touches[0]);
+    }, { passive: false });
+  }
+
+  function _beginGrab(card, touch) {
+    const rect = card.getBoundingClientRect();
+    const prevStyle = card.getAttribute('style') || '';
+    // Placeholder fills the card's old slot so the grid layout doesn't reflow.
+    const placeholder = document.createElement('div');
+    placeholder.className = 'note-card-placeholder';
+    placeholder.style.width = rect.width + 'px';
+    placeholder.style.height = rect.height + 'px';
+    placeholder.style.margin = getComputedStyle(card).margin;
+    if (card.style.gridRowEnd) placeholder.style.gridRowEnd = card.style.gridRowEnd;
+    const grid = card.parentNode;
+    grid.insertBefore(placeholder, card);
+
+    // Detach the card visually : fixed-position, anchored to the finger.
+    card.classList.add('note-card-dragging');
+    card.style.position = 'fixed';
+    card.style.left = rect.left + 'px';
+    card.style.top  = rect.top + 'px';
+    card.style.width  = rect.width + 'px';
+    card.style.height = rect.height + 'px';
+    card.style.margin = '0';
+    card.style.zIndex = '10001';
+    // pointer-events:none so elementFromPoint sees the card BENEATH the finger
+    card.style.pointerEvents = 'none';
+
+    _dragState = {
+      card, placeholder, grid, prevStyle,
+      grabOffsetX: touch.clientX - rect.left,
+      grabOffsetY: touch.clientY - rect.top,
+    };
+    try { navigator.vibrate?.(8); } catch {}
+  }
+
+  function _onDocTouchMove(e) {
+    if (!_dragState) return;
+    if (e.touches.length !== 1) return;
+    e.preventDefault();
+    const touch = e.touches[0];
+    const { card, placeholder, grid } = _dragState;
+    card.style.left = (touch.clientX - _dragState.grabOffsetX) + 'px';
+    const quickAdd = grid.querySelector('.notes-quick-add');
+    const minTop = quickAdd ? quickAdd.getBoundingClientRect().bottom + 4 : grid.getBoundingClientRect().top;
+    const maxTop = Math.max(minTop, window.innerHeight - card.getBoundingClientRect().height - 8);
+    const nextTop = Math.max(minTop, Math.min(maxTop, touch.clientY - _dragState.grabOffsetY));
+    card.style.top = nextTop + 'px';
+
+    const hitY = Math.max(minTop + 1, Math.min(window.innerHeight - 1, touch.clientY));
+    const under = document.elementFromPoint(touch.clientX, hitY);
+    const target = under && under.closest
+      ? under.closest('.note-card:not(.note-card-dragging)')
+      : null;
+    if (!target || target === card) return;
+    if (target.parentNode !== grid) return;
+
+    // Move the PLACEHOLDER (not the card) above or below the target depending
+    // on which half of the target the finger is in. This is the hysteresis
+    // that stops the oscillation : once the placeholder moves past a card,
+    // the cursor has to cross THAT card's midpoint in the other direction
+    // to swap back.
+    const tRect = target.getBoundingClientRect();
+    const targetMidY = tRect.top + tRect.height / 2;
+    if (touch.clientY < targetMidY) {
+      if (placeholder.nextElementSibling !== target) {
+        grid.insertBefore(placeholder, target);
+      }
+    } else {
+      if (target.nextElementSibling !== placeholder) {
+        grid.insertBefore(placeholder, target.nextElementSibling);
+      }
+    }
+  }
+
+  function _onDocTouchEnd() {
+    if (!_dragState) return;
+    const { card, placeholder, grid, prevStyle } = _dragState;
+    _dragState = null;
+    // Animate the card from its current fixed position to where the
+    // placeholder sits, then re-parent and clear inline styles. Drag
+    // mode auto-exits once the snap finishes : release = done.
+    const phRect = placeholder.getBoundingClientRect();
+    card.style.transition = 'left 0.2s ease, top 0.2s ease';
+    card.style.left = phRect.left + 'px';
+    card.style.top  = phRect.top + 'px';
+    setTimeout(() => {
+      placeholder.parentNode.insertBefore(card, placeholder);
+      placeholder.remove();
+      card.classList.remove('note-card-dragging');
+      // Restore the card's pre-drag inline styles. Mobile masonry stores
+      // grid-row-end inline, and custom backgrounds use inline style too; wiping
+      // cssText made dropped cards collapse into neighboring notes in grid view.
+      if (prevStyle) card.setAttribute('style', prevStyle);
+      else card.removeAttribute('style');
+      _applyMasonry(grid);
+      _commitNoteReorder();
+      // One drag, one exit : release ends the rearrange session entirely.
+      if (document.body.classList.contains('notes-drag-mode')) {
+        document.body.classList.remove('notes-drag-mode');
+      }
+    }, 210);
+  }
+
+  async function _commitNoteReorder() {
+    const grid = document.querySelector('#notes-pane .notes-pane-body');
+    if (!grid) return;
+    const ids = Array.from(grid.querySelectorAll('.note-card')).map(c => c.dataset.noteId).filter(Boolean);
+    if (!ids.length) return;
+    await commitMobileOrder(ids);
+  }
+
+  function dispose() {
+    if (_dragState) {
+      const { card, placeholder, prevStyle } = _dragState;
+      _dragState = null;
+      placeholder.parentNode?.insertBefore(card, placeholder);
+      placeholder.remove();
+      card.classList.remove('note-card-dragging');
+      if (prevStyle) card.setAttribute('style', prevStyle);
+      else card.removeAttribute('style');
+    }
+    document.body.classList.remove('notes-drag-mode');
+    _docDragHandlersBound = false;
+  }
+  return { dispose, _bindLongPressDrag, _enterDragMode, _exitDragMode, _setupDragForCard, _beginGrab, _onDocTouchMove, _onDocTouchEnd, _commitNoteReorder };
+}
diff --git a/static/js/features/notes/ui/panel.js b/static/js/features/notes/ui/panel.js
new file mode 100644
index 000000000..0a6031233
--- /dev/null
+++ b/static/js/features/notes/ui/panel.js
@@ -0,0 +1,506 @@
+/** Panel mounting, keyboard handlers, minimization and note navigation. */
+export function createPanel({
+  wireToolbar,
+  wireSelectionActions,
+  _wireNotesWindow,
+  _restoreNotesSidebarDock,
+  _bringNotesToFront,
+  disposeUI,
+  lifecycle,
+  Modals,
+  NOTES_FIRST_OPEN_HINT_KEY,
+  REMINDER_DISMISSED_AT_KEY,
+  _clearViewedReminderGlows,
+  _closeMobileFullscreenEdit,
+  _commitOpenInPlaceEditor,
+  _copyNote,
+  _enterSelectMode,
+  _exitSelectMode,
+  _fetchNotes,
+  _flushPendingHighlights,
+  _isNotesMobileMode,
+  _popAndRunUndo,
+  _renderLoadingSkeleton,
+  _renderNotes,
+  _startReminderLoop,
+  app,
+  bindTourHintDismiss,
+  dismissOrRemove,
+  persistence,
+  state,
+  workflows
+}) {
+  function _forceCloseNotesPanel() {
+    app.setOpen(false);
+    app.setEditingId(null);
+    try { _commitOpenInPlaceEditor(); } catch {}
+    try { _closeMobileFullscreenEdit({ save: true }); } catch {}
+    try { _clearViewedReminderGlows(); } catch {}
+    if (_notesKeydownHandler) {
+      document.removeEventListener('keydown', _notesKeydownHandler);
+      _notesKeydownHandler = null;
+    }
+    if (_notesSelectEscHandler) {
+      document.removeEventListener('keydown', _notesSelectEscHandler, true);
+      _notesSelectEscHandler = null;
+    }
+    disposeOwnedPortals();
+    disposeUI();
+    document.body.classList.remove('notes-view', 'notes-mobile-mode', 'notes-drag-mode');
+    document.getElementById('tool-notes-btn')?.classList.remove('active');
+    try { Modals.unregister('notes-panel'); } catch {}
+    try { document.getElementById('notes-pane')?.remove(); } catch {}
+    try { document.getElementById('notes-pane-backdrop')?.remove(); } catch {}
+    try { window._restoreSidebarIfRouteCollapsed?.(); } catch {}
+  }
+
+  function _showNotesFirstOpenHint(pane) {
+    if (!pane || typeof persistence === 'undefined') return;
+    try {
+      if (persistence.getItem(NOTES_FIRST_OPEN_HINT_KEY)) return;
+      persistence.setItem(NOTES_FIRST_OPEN_HINT_KEY, '1');
+    } catch {
+      return;
+    }
+
+    dismissOrRemove(document.getElementById('notes-first-open-hint'));
+    const hint = document.createElement('div');
+    hint.id = 'notes-first-open-hint';
+    hint.className = 'tour-hint';
+    hint.innerHTML = `
+    <div class="tour-hint-text"><b>Notes</b> is your basic todo list, and also where reminders are managed.</div>
+    <button type="button" class="tour-hint-dismiss">OK</button>
+  `;
+    document.body.appendChild(hint);
+
+    const place = () => {
+      const r = pane.getBoundingClientRect();
+      const hw = hint.offsetWidth || 260;
+      hint.style.top = Math.max(12, r.top + 58) + 'px';
+      hint.style.left = Math.min(window.innerWidth - hw - 12, Math.max(12, r.left + 18)) + 'px';
+    };
+    requestAnimationFrame(() => {
+      place();
+      hint.classList.add('tour-hint-in');
+    });
+    lifecycle.listen(hint, window, 'resize', place);
+    bindTourHintDismiss(hint, {
+      timeout: 6500,
+      fade: 180,
+      onDismiss: () => window.removeEventListener('resize', place),
+    });
+  }
+
+  function _ensureNotesChipRegistered() {
+    if (Modals.isRegistered('notes-panel')) return;
+    Modals.register('notes-panel', {
+      railBtnId: 'rail-notes',
+      sidebarBtnId: 'tool-notes-btn',
+      restoreFn: () => { openPanel(); },
+      closeFn: () => { _forceCloseNotesPanel(); },
+    });
+  }
+
+  function openPanel() {
+    if (state.open) {
+      _bringNotesToFront();
+      return;
+    }
+    // Notes and the document editor occupy the same primary workspace. Preserve
+    // an open document as a dock chip instead of allowing the two panes to stack
+    // into a broken layout (or closing the user's document outright).
+    try {
+      if (window.documentModule?.isPanelOpen?.()) {
+        window.documentModule.closePanel('down');
+      }
+    } catch (_) {}
+    app.setOpen(true);
+    app.setEditingId(null);
+    app.setSearchQuery('');
+    _clearViewedReminderGlows();
+    app.setFiredDotDismissedAt(Date.now());
+    try { persistence.setItem(REMINDER_DISMISSED_AT_KEY, String(state.firedDotDismissedAt)); } catch {}
+
+    const container = document.getElementById('chat-container');
+    if (!container) return;
+
+    document.body.classList.add('notes-view');
+
+    // On mobile the notes panel takes the whole screen : auto-close the
+    // sidebar so the panel isn't cropped underneath it.
+    if (window.innerWidth <= 768) {
+      const sb = document.getElementById('sidebar');
+      if (sb) sb.classList.add('hidden');
+      document.body.classList.add('sidebar-collapsed');
+    }
+    // Mobile mode: tiles become read-only previews (no inline checkbox /
+    // edit / archive / etc.), tap opens a fullscreen edit overlay,
+    // long-press enters drag-to-reorder mode. See _bindCardEvents +
+    // .notes-mobile-mode CSS rules.
+    if (_isNotesMobileMode()) document.body.classList.add('notes-mobile-mode');
+
+    // Toggle button state
+    const btn = document.getElementById('tool-notes-btn');
+    if (btn) btn.classList.add('active');
+
+    // Create panel
+    const pane = document.createElement('div');
+    pane.id = 'notes-pane';
+    pane.className = 'notes-pane';
+    pane.innerHTML = `
+    <div class="notes-mobile-grabber" id="notes-mobile-grabber" aria-hidden="true"></div>
+    <div class="notes-pane-header">
+      <h4 class="notes-pane-title"><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" style="vertical-align:-2.5px;margin-right:6px"><path d="M5 3h10l4 4v14H5z"/><path d="M15 3v5h5"/><path d="M8 17.5 15.5 10l2.5 2.5L10.5 20H8z"/></svg>Notes</h4>
+      <span style="flex:1"></span>
+      <button id="notes-archive-toggle" class="doc-action-icon-btn notes-header-text-btn" title="View archive" style="opacity:0.8;gap:5px;">
+        <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="2" y="3" width="20" height="5" rx="1"/><path d="M4 8v11a2 2 0 002 2h12a2 2 0 002-2V8"/><path d="M10 12h4"/></svg>
+        <span class="notes-header-btn-label">Archive</span>
+      </button>
+      <button id="notes-view-toggle" class="doc-action-icon-btn notes-header-text-btn" title="Toggle view" style="opacity:0.8;gap:5px;">
+        <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="3" y="3" width="7" height="7"/><rect x="14" y="3" width="7" height="7"/><rect x="3" y="14" width="7" height="7"/><rect x="14" y="14" width="7" height="7"/></svg>
+        <span class="notes-header-btn-label">Toggle</span>
+      </button>
+      <button id="notes-minimize-btn" class="modal-minimize-btn" title="Minimize" aria-label="Minimize notes" style="position:relative;left:2px;"><svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="3.4" stroke-linecap="round" aria-hidden="true"><line x1="6" y1="18" x2="18" y2="18"/></svg></button>
+    </div>
+    <div class="notes-search-bar">
+      <input type="text" id="notes-search" class="memory-search-input" placeholder="Search notes…" autocomplete="off" />
+      <button id="notes-select-btn" class="notes-select-trigger" type="button">Select</button>
+    </div>
+    <div id="notes-bulk-bar" class="memory-bulk-bar hidden">
+      <label class="memory-bulk-check-all"><input type="checkbox" id="notes-select-all" /> All</label>
+      <span id="notes-selected-count">0 Selected</span>
+      <span style="flex:1"></span>
+      <button id="notes-send-agent" class="memory-toolbar-btn" disabled><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" style="vertical-align:-2px;margin-right:5px;opacity:0.6"><path d="M14.7 6.3a1 1 0 0 0 0 1.4l1.6 1.6a1 1 0 0 0 1.4 0l3.77-3.77a6 6 0 0 1-7.94 7.94l-6.91 6.91a2.12 2.12 0 0 1-3-3l6.91-6.91a6 6 0 0 1 7.94-7.94l-3.76 3.76z"></path></svg>Send to Agent</button>
+      <button id="notes-bulk-archive" class="memory-toolbar-btn" disabled>
+        <svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" style="vertical-align:-2px;margin-right:4px;"><rect x="2" y="3" width="20" height="5" rx="1"/><path d="M4 8v11a2 2 0 002 2h12a2 2 0 002-2V8"/><path d="M10 12h4"/></svg>Archive
+      </button>
+      <button id="notes-bulk-delete" class="memory-toolbar-btn danger" disabled>
+        <svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" style="vertical-align:-2px;margin-right:4px;"><polyline points="3 6 5 6 21 6"/><path d="M19 6l-1 14a2 2 0 0 1-2 2H8a2 2 0 0 1-2-2L5 6"/><path d="M8 6V4a2 2 0 0 1 2-2h4a2 2 0 0 1 2 2v2"/><line x1="10" y1="11" x2="10" y2="17"/><line x1="14" y1="11" x2="14" y2="17"/></svg>Delete
+      </button>
+      <button id="notes-bulk-cancel" class="memory-toolbar-btn active" title="Cancel selection" aria-label="Cancel selection">
+        <svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"><line x1="18" y1="6" x2="6" y2="18"/><line x1="6" y1="6" x2="18" y2="18"/></svg>
+      </button>
+    </div>
+    <div class="notes-pane-body"></div>
+  `;
+
+    // On mobile open as a full-screen bottom sheet (slide up), not the desktop
+    // side panel. Set inline so it wins over the base .notes-pane rule regardless
+    // of cascade specifics (the CSS @media override wasn't reliably applying,
+    // which left it as a side panel squeezing the chat).
+    if (window.innerWidth <= 768) {
+      pane.style.position = 'fixed';
+      pane.style.inset = '0';
+      pane.style.width = '100%';
+      pane.style.maxWidth = '100%';
+      pane.style.zIndex = '170';
+      pane.style.borderRadius = '14px 14px 0 0';
+      pane.style.animation = 'sheet-enter 0.25s cubic-bezier(0.2, 0.8, 0.2, 1) both';
+      pane.style.transformOrigin = 'bottom center';
+    }
+
+    // Mount on body so Notes can behave like the other draggable windows. On
+    // desktop it is immediately docked to the right by _restoreNotesSidebarDock.
+    const backdrop = document.createElement('div');
+    backdrop.className = 'notes-pane-backdrop';
+    backdrop.id = 'notes-pane-backdrop';
+    backdrop.addEventListener('click', (ev) => {
+      if (ev.target === backdrop) closePanel('down');
+    });
+    backdrop.appendChild(pane);
+    document.body.appendChild(backdrop);
+    _wireNotesWindow(pane);
+    _restoreNotesSidebarDock(pane);
+    _bringNotesToFront(pane);
+
+    // Events
+    // (Close chevron removed : swipe down on mobile, tool-rail toggle on desktop.)
+
+    // Mobile: swipe the grab handle / header down to dismiss (minimise to chip).
+    // Mirrors the document sheet gesture : finger-following, velocity-based
+    // dismiss, rubber-band on up-drag, spring snap-back.
+    _wireNotesSwipeDismiss(pane.querySelector('.notes-mobile-grabber'), pane);
+    _wireNotesSwipeDismiss(pane.querySelector('.notes-pane-header'), pane);
+
+    pane.addEventListener('pointerdown', () => _bringNotesToFront(pane), true);
+    pane.addEventListener('focusin', () => _bringNotesToFront(pane), true);
+
+    const minBtn = document.getElementById('notes-minimize-btn');
+    if (minBtn) minBtn.addEventListener('click', (e) => {
+      e.preventDefault();
+      e.stopPropagation();
+      closePanel('down');
+    });
+    wireToolbar(pane);
+    // Select mode
+    document.getElementById('notes-select-btn').addEventListener('click', () => {
+      if (state.selectMode) _exitSelectMode(); else _enterSelectMode();
+    });
+    // Esc cancels select mode. Notes uses a toggle "Select" button rather
+    // than a *-bulk-cancel button, so the global Esc-cancel handler in
+    // keyboard-shortcuts.js can't reach it : handle it here. Capture phase
+    // + stopPropagation so Esc cancels select instead of closing the panel.
+    if (_notesSelectEscHandler) {
+      document.removeEventListener('keydown', _notesSelectEscHandler, true);
+    }
+    _notesSelectEscHandler = (e) => {
+      if (e.key === 'Escape' && state.selectMode) {
+        e.preventDefault();
+        e.stopPropagation();
+        _exitSelectMode();
+      }
+    };
+    document.addEventListener('keydown', _notesSelectEscHandler, true);
+    wireSelectionActions();
+    // Escape: exit select mode first (if active), otherwise close the panel.
+    // Skip when the user is editing a form field : those have their own
+    // ESC-to-cancel handlers and we don't want to nuke the whole panel
+    // mid-edit.
+    // Idempotent: remove any previous handler from a prior openPanel so
+    // re-opening doesn't stack multiple handlers.
+    if (_notesKeydownHandler) {
+      document.removeEventListener('keydown', _notesKeydownHandler);
+      _notesKeydownHandler = null;
+    }
+    _notesKeydownHandler = (e) => {
+      if (!state.open) return;
+      const t = e.target;
+      const inField = t && (t.tagName === 'INPUT' || t.tagName === 'TEXTAREA' || t.isContentEditable);
+      // Ctrl/Cmd+Z anywhere in the panel : undo the last note action. Skip when
+      // typing in a field so the browser's normal text-undo still works.
+      if ((e.ctrlKey || e.metaKey) && (e.key === 'z' || e.key === 'Z') && !e.shiftKey) {
+        if (inField) return;
+        if (workflows.undoCount() === 0) return;
+        e.preventDefault();
+        _popAndRunUndo();
+        return;
+      }
+      // Ctrl/Cmd+C while hovering a note card → copy that note. Skip when the
+      // user is editing or has an active text selection (let the browser handle
+      // a real text copy in that case).
+      if ((e.ctrlKey || e.metaKey) && (e.key === 'c' || e.key === 'C') && !e.shiftKey && !e.altKey) {
+        if (inField) return;
+        const sel = window.getSelection?.();
+        if (sel && sel.toString && sel.toString().length > 0) return;
+        const hovered = document.querySelector('.note-card:hover');
+        if (!hovered) return;
+        const id = hovered.dataset.noteId;
+        if (!id) return;
+        e.preventDefault();
+        // Flash the ⋯ menu button (copy now lives in that menu).
+        const btn = hovered.querySelector('.note-card-corner-menu');
+        _copyNote(id, btn);
+        return;
+      }
+      if (e.key !== 'Escape') return;
+      if (inField) return;
+      if (state.selectMode) { _exitSelectMode(); return; }
+      if (state.showingArchived) {
+        // Mirror the archive toggle button: flip back to active notes.
+        document.getElementById('notes-archive-toggle')?.click();
+        return;
+      }
+      _forceCloseNotesPanel();
+    };
+    document.addEventListener('keydown', _notesKeydownHandler);
+
+    // Load : show skeleton immediately, then fetch
+    _renderLoadingSkeleton();
+    // Defer the highlight flush to the next frame so it runs *after* the cards
+    // are committed to the DOM (and any FLIP animations have settled), giving
+    // the querySelector lookups inside something to find.
+    _fetchNotes().then(() => {
+      if (!pane.isConnected || !state.open) { _startReminderLoop(); return; }
+      _renderNotes();
+      requestAnimationFrame(() => _flushPendingHighlights());
+      _startReminderLoop();
+      _showNotesFirstOpenHint(pane);
+    });
+  }
+
+  function closePanel(direction) {
+    if (!state.open) return;
+    app.setOpen(false);
+    app.setEditingId(null);
+    _clearViewedReminderGlows();
+    const _minimize = direction === 'down';
+    if (_minimize) {
+      _ensureNotesChipRegistered();
+    } else if (Modals.isRegistered('notes-panel')) {
+      Modals.unregister('notes-panel');
+    }
+
+    // Drop panel-owned keydown listeners. The reminder interval is page-owned.
+    if (_notesKeydownHandler) {
+      document.removeEventListener('keydown', _notesKeydownHandler);
+      _notesKeydownHandler = null;
+    }
+    if (_notesSelectEscHandler) {
+      document.removeEventListener('keydown', _notesSelectEscHandler, true);
+      _notesSelectEscHandler = null;
+    }
+
+    disposeOwnedPortals();
+    disposeUI();
+    document.body.classList.remove('notes-view');
+    document.body.classList.remove('notes-mobile-mode');
+    document.body.classList.remove('notes-drag-mode');
+    // Closing the panel should PRESERVE in-progress edits, not drop them.
+    // Commit any open in-place editor, and close the mobile fullscreen
+    // overlay with save=true so the note is persisted.
+    try { _commitOpenInPlaceEditor(); } catch {}
+    _closeMobileFullscreenEdit({ save: true });
+    // /notes route may have collapsed the wide sidebar to a rail; restore.
+    try { window._restoreSidebarIfRouteCollapsed?.(); } catch (_) {}
+
+    const btn = document.getElementById('tool-notes-btn');
+    if (btn) btn.classList.remove('active');
+
+    const pane = document.getElementById('notes-pane');
+    const backdrop = document.getElementById('notes-pane-backdrop');
+    if (pane) {
+      // Scale-out + fade. Match the enter animation duration so close feels
+      // like the same gesture played backwards.
+      pane.classList.add('notes-pane-leaving');
+      const _cleanup = () => {
+        try { pane.remove(); } catch {}
+        try { backdrop?.remove(); } catch {}
+      };
+      pane.addEventListener('animationend', _cleanup, { once: true });
+      // Belt-and-braces: if animation is skipped (reduced motion / detached
+      // tab) the listener won't fire; remove after the expected duration.
+      setTimeout(_cleanup, 220);
+    } else if (backdrop) {
+      backdrop.remove();
+    }
+    // Show the dock chip for a swipe-down minimize (tap it to reopen).
+    if (_minimize) { try { Modals.minimize('notes-panel'); } catch {} }
+  }
+
+  function togglePanel() {
+    if (state.open) closePanel();
+    else openPanel();
+  }
+
+  function isPanelOpen() { return state.open; }
+
+  async function openNote(noteId) {
+    const wasOpen = !!(isPanelOpen && isPanelOpen());
+    app.setShowingArchived(false);
+    app.setActiveLabel(null);
+    app.setActiveFilter(null);
+    app.setSearchQuery('');
+    if (!wasOpen) {
+      openPanel();
+    } else {
+      _bringNotesToFront();
+      const searchEl = document.getElementById('notes-search');
+      if (searchEl) searchEl.value = '';
+      const pane = document.getElementById('notes-pane');
+      if (pane) pane.classList.remove('notes-pane-archive');
+      const archiveBtn = document.getElementById('notes-archive-toggle');
+      if (archiveBtn) archiveBtn.classList.remove('active');
+      await _fetchNotes();
+      _renderNotes();
+    }
+    // openPanel() kicks off _fetchNotes() asynchronously, so the cards for
+    // newly-created notes may not be in the DOM yet. Poll until the card exists.
+    if (!noteId) return;
+    let tries = 0;
+    const findAndFlash = () => {
+      const card = document.querySelector(`.note-card[data-note-id="${noteId}"]`)
+        || document.querySelector(`.note-card[data-note-id^="${noteId.slice(0, 8)}"]`);
+      if (card) {
+        _smoothScrollToNoteCard(card);
+        card.classList.add('note-card-flash');
+        setTimeout(() => card.classList.remove('note-card-flash'), 1600);
+        return true;
+      }
+      return false;
+    };
+    const tryNext = () => {
+      if (findAndFlash()) return;
+      if (++tries < 20) setTimeout(tryNext, 200);
+    };
+    setTimeout(tryNext, 120);
+  }
+
+  let _notesKeydownHandler = null;
+
+  let _notesSelectEscHandler = null;
+
+  function _wireNotesSwipeDismiss(el, pane) {
+    if (!el || !pane) return;
+    const DISMISS_THRESHOLD = 50, VELOCITY_THRESHOLD = 0.3, RUBBER = 0.35;
+    let startY = 0, startX = 0, lastY = 0, lastT = 0, velocity = 0;
+    let dragging = false, cancelled = false;
+
+    el.addEventListener('touchstart', (e) => {
+      if (window.innerWidth > 768 || e.touches.length !== 1) return;
+      if (e.target.closest('button, input, select, label, textarea')) return;
+      const t = e.touches[0];
+      startY = t.clientY; startX = t.clientX; lastY = startY; lastT = e.timeStamp;
+      velocity = 0; dragging = false; cancelled = false;
+    }, { passive: true });
+
+    el.addEventListener('touchmove', (e) => {
+      if (cancelled || window.innerWidth > 768) return;
+      const t = e.touches[0];
+      const dx = Math.abs(t.clientX - startX);
+      const dy = t.clientY - startY;
+      if (!dragging) {
+        if (dx > 40 && dx > Math.abs(dy) * 2) { cancelled = true; return; }
+        if (Math.abs(dy) > 8) {
+          dragging = true;
+          pane.style.animation = 'none';
+          pane.style.transition = 'none';
+          pane.style.willChange = 'transform';
+        } else return;
+      }
+      const dt = e.timeStamp - lastT;
+      if (dt > 0) velocity = velocity * 0.6 + ((t.clientY - lastY) / dt) * 0.4;
+      lastY = t.clientY; lastT = e.timeStamp;
+      e.preventDefault();
+      pane.style.transform = dy > 0 ? `translateY(${dy}px)` : `translateY(${dy * RUBBER}px)`;
+    }, { passive: false });
+
+    const endSwipe = () => {
+      if (!dragging) return;
+      dragging = false;
+      pane.style.willChange = '';
+      const dy = lastY - startY;
+      if (dy > DISMISS_THRESHOLD || (dy > 20 && velocity > VELOCITY_THRESHOLD)) {
+        // Slide fully off-screen, then minimise. Keep it translated down (don't
+        // reset) so it doesn't flash back before closePanel removes it.
+        pane.style.transition = 'transform 0.2s cubic-bezier(0.2, 0, 0.4, 1)';
+        pane.style.transform = 'translateY(100%)';
+        setTimeout(() => closePanel('down'), 200);
+      } else {
+        pane.style.transition = 'transform 0.25s cubic-bezier(0.2, 0.9, 0.3, 1.05)';
+        pane.style.transform = '';
+        setTimeout(() => { pane.style.transition = ''; }, 260);
+      }
+    };
+    el.addEventListener('touchend', endSwipe, { passive: true });
+    el.addEventListener('touchcancel', endSwipe, { passive: true });
+  }
+
+  function _smoothScrollToNoteCard(card) {
+    if (!card) return;
+    const scroller = card.closest('.notes-pane-body');
+    if (!scroller) {
+      try { card.scrollIntoView({ block: 'center', behavior: 'smooth' }); } catch (_) {}
+      return;
+    }
+    const scrollerRect = scroller.getBoundingClientRect();
+    const cardRect = card.getBoundingClientRect();
+    const delta = (cardRect.top - scrollerRect.top) - (scroller.clientHeight - cardRect.height) / 2;
+    scroller.scrollTo({ top: Math.max(0, scroller.scrollTop + delta), behavior: 'smooth' });
+  }
+
+  function disposeOwnedPortals() {
+    document.querySelectorAll('.note-reminder-menu, .note-corner-menu-dropdown, #notes-first-open-hint').forEach(dismissOrRemove);
+  }
+
+  return { _forceCloseNotesPanel, openPanel, closePanel, togglePanel, isPanelOpen, openNote, _smoothScrollToNoteCard };
+}
diff --git a/static/js/features/notes/ui/quickAdd.js b/static/js/features/notes/ui/quickAdd.js
new file mode 100644
index 000000000..3a723fcdc
--- /dev/null
+++ b/static/js/features/notes/ui/quickAdd.js
@@ -0,0 +1,170 @@
+/** Quick-add expansion, draft restoration and opening inline editors. */
+export function createQuickAdd({
+  _applyDraftToNote,
+  _applyMasonry,
+  _buildForm,
+  app,
+  openPanel,
+  state,
+  uiModule
+}) {
+  function _renderQuickAdd(body) {
+    const wrap = document.createElement('div');
+    wrap.className = 'notes-quick-add';
+    // 2-pill Note/Todo toggle mirrors the full form's type-seg (minus Draw :
+    // drawing happens in the expanded form). The pill that's active steers
+    // both the placeholder and the type the form opens in.
+    wrap.innerHTML = `
+    <div class="notes-quick-type-seg is-todo" role="group" aria-label="New item type">
+      <button type="button" class="notes-quick-type-pill" data-type="note" aria-label="Note" aria-pressed="false" title="Note">
+        <svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><line x1="4" y1="6" x2="20" y2="6"/><line x1="4" y1="12" x2="20" y2="12"/><line x1="4" y1="18" x2="14" y2="18"/></svg>
+      </button>
+      <button type="button" class="notes-quick-type-pill active" data-type="todo" aria-label="To-do" aria-pressed="true" title="To-do">
+        <svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><polyline points="9 11 12 14 22 4"/><path d="M21 12v7a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2h11"/></svg>
+      </button>
+    </div>
+    <input type="text" class="notes-quick-input" placeholder="Add a to-do…" />
+    <button class="notes-quick-icon" data-action="photo" title="Attach photo">
+      <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="3" y="3" width="18" height="18" rx="2"/><circle cx="8.5" cy="8.5" r="1.5"/><polyline points="21 15 16 10 5 21"/></svg>
+    </button>
+  `;
+    body.appendChild(wrap);
+
+    const input = wrap.querySelector('.notes-quick-input');
+    const seg = wrap.querySelector('.notes-quick-type-seg');
+    let currentType = 'todo';
+    const setType = (t) => {
+      if (t !== 'note' && t !== 'todo') return;
+      currentType = t;
+      seg.classList.toggle('is-todo', t === 'todo');
+      seg.classList.toggle('is-note', t === 'note');
+      seg.querySelectorAll('.notes-quick-type-pill').forEach(p => {
+        const on = p.dataset.type === t;
+        p.classList.toggle('active', on);
+        p.setAttribute('aria-pressed', on ? 'true' : 'false');
+      });
+      input.placeholder = t === 'note' ? 'Add a note…' : 'Add a to-do…';
+    };
+    seg.querySelectorAll('.notes-quick-type-pill').forEach(p => {
+      p.addEventListener('click', (e) => {
+        e.stopPropagation();
+        setType(p.dataset.type);
+      });
+    });
+    // Click input or type → expand to full form
+    const expandToForm = (initialType = 'note', initialText = '') => {
+      app.setEditingId('__new__');
+      const form = _buildForm({ note_type: initialType });
+      form.classList.add('note-form-new');
+      if (initialText) {
+        const titleEl = form.querySelector('.note-form-title');
+        if (titleEl) titleEl.value = initialText;
+      }
+      const mobileGrid = body.closest('.notes-pane')?.classList.contains('notes-view-grid')
+        && window.matchMedia('(max-width: 768px)').matches;
+      if (mobileGrid) {
+        form.style.gridColumn = '1 / -1';
+        form.style.gridRowEnd = 'span 64';
+      }
+      wrap.replaceWith(form);
+      _applyMasonry(body);
+      requestAnimationFrame(() => _applyMasonry(body));
+      const titleEl = form.querySelector('.note-form-title');
+      if (titleEl) {
+        titleEl.focus();
+        // Move caret to end
+        titleEl.setSelectionRange(titleEl.value.length, titleEl.value.length);
+      }
+    };
+    // Expand only on real intent: a click directly on the input, or actual
+    // typing. Focus alone : including focus stolen from a missed nearby
+    // click : no longer creates an empty form.
+    input.addEventListener('click', () => expandToForm(currentType, input.value));
+    input.addEventListener('input', () => expandToForm(currentType, input.value));
+    wrap.querySelector('[data-action="photo"]').addEventListener('click', (e) => {
+      e.stopPropagation();
+      expandToForm(currentType);
+      // Trigger photo input on the new form
+      setTimeout(() => document.querySelector('.note-form-photo-btn')?.click(), 50);
+    });
+  }
+
+  function _createNote(type = 'todo') {
+    const body = document.querySelector('#notes-pane .notes-pane-body');
+    if (!body || state.editingId === '__new__') return;
+    app.setEditingId('__new__');
+    // Restore an unsaved new-note draft if one survived a prior close/loss.
+    const { note: _n, restored } = _applyDraftToNote({ note_type: type }, '__new__');
+    const form = _buildForm(_n);
+    form.classList.add('note-form-new');
+    body.prepend(form);
+    const initialField = type === 'note'
+      ? form.querySelector('.note-form-content')
+      : form.querySelector('.note-cl-text, .note-form-title');
+    initialField?.focus();
+    if (restored) uiModule.showToast('Restored unsaved note');
+  }
+
+  function newNote() {
+    if (!state.open) openPanel();
+    requestAnimationFrame(() => _createNote('note'));
+  }
+
+  function _editNote(id) {
+    const note = state.notes.find(n => n.id === id);
+    if (!note) return;
+    app.setEditingId(id);
+    const card = document.querySelector(`.note-card[data-note-id="${id}"]`);
+    if (!card) return;
+    // Restore an unsaved draft (from a prior connection loss / close) over
+    // the saved note so the user picks up where they left off.
+    const { note: _n, restored } = _applyDraftToNote(note, id);
+    const form = _buildForm(_n);
+    card.replaceWith(form);
+    if (restored) uiModule.showToast('Restored unsaved changes');
+    // Pinned notes live in the first masonry column : the edit form has
+    // column-span:all, which can leave the form rendered above the fold or
+    // visually buried under neighboring pinned cards. Bring it into view
+    // (and onto a higher stacking context) so editing a pinned note always
+    // pops to the top.
+    form.style.position = 'relative';
+    form.style.zIndex = '5';
+    // Grid view: the form keeps the CSS default `grid-row-end: span 16` (64px)
+    // after replaceWith, which is much shorter than the actual form. Recompute
+    // masonry so the form gets the correct row span and cards below stop
+    // overlapping it. ResizeObserver inside _applyMasonry keeps it in sync as
+    // the user types / adds checklist items.
+    const _body = form.closest('.notes-pane-body');
+    if (_body) {
+      _applyMasonry(_body);
+      requestAnimationFrame(() => _applyMasonry(_body));
+    }
+    requestAnimationFrame(() => {
+      try { form.scrollIntoView({ block: 'center', behavior: 'smooth' }); }
+      catch { form.scrollIntoView(); }
+    });
+    // Pick the most useful field to focus. On phones especially, the user
+    // taps Edit to type : landing in the title when there's already a title
+    // (and likely a body to extend) loses momentum. Prefer the body textarea
+    // for plain notes, the first checklist item for todos, fall back to title.
+    const _focusBest = () => {
+      if (note.note_type === 'note' || !note.note_type) {
+        const ta = form.querySelector('.note-form-content');
+        if (ta) { ta.focus(); try { ta.setSelectionRange(ta.value.length, ta.value.length); } catch {} return; }
+      }
+      if (note.note_type === 'todo' || note.note_type === 'goal' || note.note_type === 'checklist') {
+        // Last non-empty checklist row, or the first row if all empty.
+        const rows = form.querySelectorAll('.note-cl-row .note-cl-text');
+        let target = null;
+        for (const inp of rows) { if ((inp.value || '').trim()) target = inp; }
+        target = target || rows[0];
+        if (target) { target.focus(); try { target.setSelectionRange(target.value.length, target.value.length); } catch {} return; }
+      }
+      const titleEl = form.querySelector('.note-form-title');
+      if (titleEl) titleEl.focus();
+    };
+    _focusBest();
+  }
+
+  return { _renderQuickAdd, _createNote, newNote, _editNote };
+}
diff --git a/static/js/features/notes/ui/reminderDisplay.js b/static/js/features/notes/ui/reminderDisplay.js
new file mode 100644
index 000000000..5f6507d46
--- /dev/null
+++ b/static/js/features/notes/ui/reminderDisplay.js
@@ -0,0 +1,129 @@
+/** Reminder badges, sticky card highlights and entry scrolling. */
+import { _isNoteFullyDone } from '../domain/noteRules.js';
+import { _hasTimeComponent } from '../domain/recurrence.js';
+export function createReminderDisplay({
+  _countFiredReminders,
+  _hasActiveReminder,
+  _loadActiveHighlights,
+  _loadGlowedReminders,
+  _loadPendingHighlights,
+  _saveActiveHighlights,
+  _saveGlowedReminders,
+  _savePendingHighlights,
+  _smoothScrollToNoteCard,
+  state
+}) {
+  function _clearViewedReminderGlows() {
+    const active = _loadActiveHighlights();
+    if (!active.size) return;
+    _saveActiveHighlights(new Set());
+    document.querySelectorAll('.note-card-reminder-fired-sticky').forEach(card => {
+      card.classList.remove('note-card-reminder-fired-sticky');
+    });
+  }
+
+  function _setReminderCardGlow(noteId, on = true) {
+    if (!noteId) return;
+    const active = _loadActiveHighlights();
+    if (on) active.add(noteId);
+    else active.delete(noteId);
+    _saveActiveHighlights(active);
+    document.querySelectorAll(`.note-card[data-note-id="${noteId}"]`).forEach(card => {
+      card.classList.toggle('note-card-reminder-fired-sticky', on);
+    });
+  }
+
+  function _queuePendingHighlight(noteId) {
+    const set = _loadPendingHighlights();
+    set.add(noteId);
+    _savePendingHighlights(set);
+  }
+
+  function _flushPendingHighlights() {
+    // Fresh firings (queued by the background loop while the panel was closed)
+    // glow unconditionally : a notification just told the user something
+    // happened, so we always point at the note even if it was glowed before.
+    const queued = _loadPendingHighlights();
+    const glowed = _loadGlowedReminders();
+    const toGlow = new Set(queued);
+    // For notes that are merely overdue at open time (no fresh firing event),
+    // only glow the ones we haven't already shown : otherwise reopening the
+    // panel keeps lighting up old reminders forever.
+    for (const n of state.notes) {
+      if (!_hasActiveReminder(n) || !_hasTimeComponent(n.due_date)) continue;
+      if (queued.has(n.id) || !glowed.has(n.id)) toGlow.add(n.id);
+    }
+    // Always consume the queue.
+    _savePendingHighlights(new Set());
+    if (!toGlow.size) return;
+    let firstCard = null;
+    for (const id of toGlow) {
+      const card = document.querySelector(`.note-card[data-note-id="${id}"]`);
+      if (!card) continue;
+      _setReminderCardGlow(id, true);
+      if (!firstCard) firstCard = card;
+      glowed.add(id);
+    }
+    _saveGlowedReminders(glowed);
+    // Bring the first one into view so it can't get buried below the fold.
+    if (firstCard) {
+      requestAnimationFrame(() => {
+        _smoothScrollToNoteCard(firstCard);
+      });
+    }
+  }
+
+  function _updateRailBadge() {
+    const fired = _countFiredReminders();
+    // Rail (mini sidebar) : only show the count when reminders have ACTUALLY
+    // fired since the last dismissal (i.e. you haven't opened notes yet).
+    // Showing every overdue note forever made the badge feel permanent.
+    const railBtn = document.getElementById('rail-notes');
+    if (railBtn) {
+      let badge = railBtn.querySelector('.rail-notes-badge');
+      if (fired > 0) {
+        if (!badge) {
+          badge = document.createElement('span');
+          badge.className = 'rail-notes-badge';
+          railBtn.appendChild(badge);
+        }
+        badge.textContent = fired > 99 ? '99+' : String(fired);
+        badge.classList.add('fired');
+      } else if (badge) {
+        badge.remove();
+      }
+    }
+    // Main sidebar button
+    const sidebarBtn = document.getElementById('tool-notes-btn');
+    if (sidebarBtn) {
+      let dot = sidebarBtn.querySelector('.tool-notes-dot');
+      if (fired > 0) {
+        if (!dot) {
+          dot = document.createElement('span');
+          dot.className = 'tool-notes-dot';
+          const newNoteBtn = sidebarBtn.querySelector('#notes-new-note-btn');
+          sidebarBtn.insertBefore(dot, newNoteBtn || null);
+        }
+      } else if (dot) {
+        dot.remove();
+      }
+    }
+    // Individual note cards : pulse ones with fired reminders
+    document.querySelectorAll('.note-card').forEach(card => {
+      const id = card.dataset.noteId;
+      const note = state.notes.find(n => n.id === id);
+      if (!note || note.archived || _isNoteFullyDone(note)) {
+        card.classList.remove('note-card-reminder-due');
+        return;
+      }
+      if (note.due_date && _hasTimeComponent(note.due_date)) {
+        const t = new Date(note.due_date).getTime();
+        card.classList.toggle('note-card-reminder-due', !isNaN(t) && t <= Date.now());
+      } else {
+        card.classList.remove('note-card-reminder-due');
+      }
+    });
+  }
+
+  return { _clearViewedReminderGlows, _setReminderCardGlow, _queuePendingHighlight, _flushPendingHighlights, _updateRailBadge };
+}
diff --git a/static/js/features/notes/ui/reminderPicker.js b/static/js/features/notes/ui/reminderPicker.js
new file mode 100644
index 000000000..da9d00398
--- /dev/null
+++ b/static/js/features/notes/ui/reminderPicker.js
@@ -0,0 +1,335 @@
+/** Reminder date presets and recurrence picker interactions. */
+import { _formatRepeatLabel, _toLocalDatetimeStr, _normalizeRepeat, _DAYS, _ORDINALS } from '../domain/recurrence.js';
+export function createReminderPicker({
+  lifecycle,
+  _ensureNotificationPermission,
+  _esc,
+  _formatReminderTag,
+  _laterTodayDate,
+  _nextWeekDate,
+  _snapToRepeat,
+  _tomorrowDate,
+  bindMenuDismiss,
+  dismissOrRemove
+}) {
+  function _wireReminderPicker(form) {
+    // Reminder bell : opens dropdown menu
+    const remindBtn = form.querySelector('.note-form-remind-btn');
+    const dueInput = form.querySelector('.note-form-due');
+    const repeatInput = form.querySelector('.note-form-repeat');
+    const tagsEl = form.querySelector('.note-form-reminder-tags');
+
+    function _renderReminderTag() {
+      if (!tagsEl) return;
+      const v = dueInput.value;
+      const rep = repeatInput.value || 'none';
+      if (!v) { tagsEl.innerHTML = ''; return; }
+      const label = _formatReminderTag(v);
+      const repLabel = rep !== 'none' ? ` · ${_formatRepeatLabel(rep, new Date(v))}` : '';
+      tagsEl.innerHTML = `<button class="note-reminder-tag" type="button" title="Edit reminder">
+      <svg width="11" height="11" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round"><path d="M18 8A6 6 0 0 0 6 8c0 7-3 9-3 9h18s-3-2-3-9"/><path d="M13.73 21a2 2 0 0 1-3.46 0"/></svg>
+      <span>${_esc(label)}${_esc(repLabel)}</span>
+      <span class="note-reminder-tag-x" title="Remove">×</span>
+    </button>`;
+      tagsEl.querySelector('.note-reminder-tag').addEventListener('click', (e) => {
+        if (e.target.classList.contains('note-reminder-tag-x')) {
+          dueInput.value = '';
+          repeatInput.value = 'none';
+          _renderReminderTag();
+          return;
+        }
+        _openReminderMenu(remindBtn || tagsEl, true);
+      });
+    }
+
+    function _openReminderMenu(anchor, isEdit = false) {
+      // Close any existing menu
+      document.querySelectorAll('.note-reminder-menu').forEach(m => m.remove());
+      const menu = document.createElement('div');
+      menu.className = 'note-reminder-menu';
+      document.body.appendChild(menu);
+
+      const presetItems = [
+        { label: 'Later today', sub: _laterTodayDate().toLocaleTimeString([], { hour: 'numeric', minute: '2-digit' }), action: () => _setReminder(_toLocalDatetimeStr(_laterTodayDate())) },
+        { label: 'Tomorrow', sub: _tomorrowDate().toLocaleTimeString([], { hour: 'numeric', minute: '2-digit' }), action: () => _setReminder(_toLocalDatetimeStr(_tomorrowDate())) },
+        { label: 'Next week', sub: _nextWeekDate().toLocaleDateString([], { weekday: 'short' }) + ' ' + _nextWeekDate().toLocaleTimeString([], { hour: 'numeric', minute: '2-digit' }), action: () => _setReminder(_toLocalDatetimeStr(_nextWeekDate())) },
+        { label: 'Select date and time', sub: '', action: () => _pickCustomDate() },
+      ];
+
+      // Sub-page state for the repeat picker. null = top page.
+      // 'weekly' | 'monthly' | 'monthly_nth'
+      let subMode = null;
+      // Temporary state for monthly_nth so user can click N then weekday (or vice versa)
+      // before committing.
+      let nthDraft = { n: 0, w: -1 };
+
+      const DAY_SHORT = ['S', 'M', 'T', 'W', 'T', 'F', 'S'];
+
+      function getNorm() {
+        if (!dueInput.value) return 'none';
+        return _normalizeRepeat(repeatInput.value || 'none', new Date(dueInput.value));
+      }
+
+      function commit(val) {
+        repeatInput.value = val;
+        _renderReminderTag();
+        menu.remove();
+      }
+
+      // Like commit, but first snaps dueInput.value forward to the next matching
+      // slot for the chosen recurrence. Use for weekly/monthly variants where the
+      // current due date may not match the chosen pattern (e.g. user picks
+      // "weekly on Mondays" while the date is a Wednesday).
+      function snapAndCommit(val) {
+        if (dueInput.value) {
+          const cur = new Date(dueInput.value);
+          const norm = _normalizeRepeat(val, cur);
+          const snapped = _snapToRepeat(cur, norm);
+          if (snapped) {
+            dueInput.value = _toLocalDatetimeStr(snapped);
+            if (remindBtn) remindBtn.classList.add('has-date');
+          }
+        }
+        commit(val);
+      }
+
+      function reposition() {
+        const rect = anchor.getBoundingClientRect();
+        const vw = window.innerWidth;
+        const vh = window.innerHeight;
+        const mw = menu.offsetWidth || 220;
+        const mh = menu.offsetHeight || 280;
+        let top = rect.bottom + 4;
+        let left = rect.left;
+        if (top + mh > vh - 8) top = Math.max(8, rect.top - mh - 4);
+        if (left + mw > vw - 8) left = Math.max(8, vw - mw - 8);
+        if (left < 8) left = 8;
+        menu.style.top = top + 'px';
+        menu.style.left = left + 'px';
+      }
+
+      function render() {
+        let html = '';
+
+        if (subMode === null) {
+          html += '<div class="note-reminder-menu-title">Remind me later</div>';
+          for (let i = 0; i < presetItems.length; i++) {
+            const it = presetItems[i];
+            html += `<button class="note-reminder-menu-item" data-action="preset" data-i="${i}"><span>${it.label}</span><span class="note-reminder-menu-sub">${it.sub}</span></button>`;
+          }
+          if (isEdit && dueInput.value) {
+            const norm = getNorm();
+            html += '<div class="note-reminder-menu-divider"></div>';
+            html += '<div class="note-reminder-menu-title">Repeat</div>';
+            // None
+            html += `<button class="note-reminder-menu-item${norm === 'none' ? ' active' : ''}" data-action="set" data-val="none"><span>Doesn't repeat</span>${norm === 'none' ? '<span class="note-reminder-menu-check">✓</span>' : ''}</button>`;
+            // Daily
+            html += `<button class="note-reminder-menu-item${norm === 'daily' ? ' active' : ''}" data-action="set" data-val="daily"><span>Daily</span>${norm === 'daily' ? '<span class="note-reminder-menu-check">✓</span>' : ''}</button>`;
+            // Weekly →
+            {
+              const isW = norm.startsWith('weekly:');
+              const wd = isW ? parseInt(norm.split(':')[1], 10) : null;
+              const sub = isW && !isNaN(wd) ? `<span class="note-reminder-menu-sub">${_DAYS[wd]}</span>` : '';
+              html += `<button class="note-reminder-menu-item${isW ? ' active' : ''}" data-action="sub" data-sub="weekly"><span>Weekly</span>${sub}<span class="note-reminder-menu-arrow">›</span></button>`;
+            }
+            // Monthly →
+            {
+              const isM = norm.startsWith('monthly:');
+              const sub = isM ? `<span class="note-reminder-menu-sub">${_monthlyShortDescriptor(norm)}</span>` : '';
+              html += `<button class="note-reminder-menu-item${isM ? ' active' : ''}" data-action="sub" data-sub="monthly"><span>Monthly</span>${sub}<span class="note-reminder-menu-arrow">›</span></button>`;
+            }
+            // Yearly
+            html += `<button class="note-reminder-menu-item${norm === 'yearly' ? ' active' : ''}" data-action="set" data-val="yearly"><span>Yearly</span>${norm === 'yearly' ? '<span class="note-reminder-menu-check">✓</span>' : ''}</button>`;
+          }
+        } else if (subMode === 'weekly') {
+          const norm = getNorm();
+          const curWd = norm.startsWith('weekly:') ? parseInt(norm.split(':')[1], 10) : -1;
+          html += `<button class="note-reminder-menu-back" data-action="back"><span class="note-reminder-menu-arrow-back">‹</span> Repeat</button>`;
+          html += '<div class="note-reminder-menu-title">Weekly on…</div>';
+          html += '<div class="note-reminder-weekday-row">';
+          for (let i = 0; i < 7; i++) {
+            html += `<button class="note-reminder-day-chip${curWd === i ? ' active' : ''}" data-action="weekly-pick" data-wd="${i}" title="${_DAYS[i]}">${DAY_SHORT[i]}</button>`;
+          }
+          html += '</div>';
+        } else if (subMode === 'monthly') {
+          const norm = getNorm();
+          const dueDate = new Date(dueInput.value);
+          const dayN = dueDate.getDate();
+          html += `<button class="note-reminder-menu-back" data-action="back"><span class="note-reminder-menu-arrow-back">‹</span> Repeat</button>`;
+          html += '<div class="note-reminder-menu-title">Monthly on…</div>';
+          // Day N : uses the chosen date's day. Always offered.
+          const dayVal = `monthly:day:${dayN}`;
+          html += `<button class="note-reminder-menu-item${norm === dayVal ? ' active' : ''}" data-action="set" data-val="${dayVal}"><span>Day ${dayN} every month</span>${norm === dayVal ? '<span class="note-reminder-menu-check">✓</span>' : ''}</button>`;
+          // Nth weekday →
+          {
+            const isNth = norm.startsWith('monthly:nth:');
+            const sub = isNth ? `<span class="note-reminder-menu-sub">${_monthlyShortDescriptor(norm)}</span>` : '';
+            html += `<button class="note-reminder-menu-item${isNth ? ' active' : ''}" data-action="sub" data-sub="monthly_nth"><span>Nth weekday</span>${sub}<span class="note-reminder-menu-arrow">›</span></button>`;
+          }
+        } else if (subMode === 'monthly_nth') {
+          // Pick ordinal (1..4) and weekday (0..6); commit when both chosen.
+          html += `<button class="note-reminder-menu-back" data-action="back-monthly"><span class="note-reminder-menu-arrow-back">‹</span> Monthly</button>`;
+          html += '<div class="note-reminder-menu-title">Nth weekday of month</div>';
+          html += '<div class="note-reminder-menu-sublabel">Which one</div>';
+          html += '<div class="note-reminder-weekday-row">';
+          for (let i = 1; i <= 4; i++) {
+            html += `<button class="note-reminder-day-chip wide${nthDraft.n === i ? ' active' : ''}" data-action="nth-n" data-n="${i}">${_ORDINALS[i - 1]}</button>`;
+          }
+          html += '</div>';
+          html += '<div class="note-reminder-menu-sublabel">Weekday</div>';
+          html += '<div class="note-reminder-weekday-row">';
+          for (let i = 0; i < 7; i++) {
+            html += `<button class="note-reminder-day-chip${nthDraft.w === i ? ' active' : ''}" data-action="nth-w" data-wd="${i}" title="${_DAYS[i]}">${DAY_SHORT[i]}</button>`;
+          }
+          html += '</div>';
+          html += '<div class="note-reminder-menu-divider"></div>';
+          const ready = nthDraft.n > 0 && nthDraft.w >= 0;
+          const lbl = ready ? `Save: ${_ORDINALS[nthDraft.n - 1]} ${_DAYS[nthDraft.w]}` : 'Pick week and weekday';
+          html += `<button class="note-reminder-menu-item note-reminder-menu-confirm${ready ? '' : ' disabled'}" data-action="nth-save" ${ready ? '' : 'disabled'}><span>${lbl}</span></button>`;
+        }
+
+        menu.innerHTML = html;
+        reposition();
+        wire();
+      }
+
+      function wire() {
+        menu.querySelectorAll('[data-action]').forEach(el => {
+          el.addEventListener('click', (e) => {
+            e.stopPropagation();
+            const a = el.dataset.action;
+            if (a === 'preset') {
+              const it = presetItems[parseInt(el.dataset.i, 10)];
+              it.action();
+              menu.remove();
+            } else if (a === 'set') {
+              snapAndCommit(el.dataset.val);
+            } else if (a === 'sub') {
+              subMode = el.dataset.sub;
+              // Seed nth draft from saved value only on first entry : preserve
+              // in-progress picks across back-trips (Nth → back → Nth again).
+              if (subMode === 'monthly_nth' && nthDraft.n === 0 && nthDraft.w === -1) {
+                const norm = getNorm();
+                const m = norm.match(/^monthly:nth:(\d):(\d)$/);
+                if (m) nthDraft = { n: parseInt(m[1], 10), w: parseInt(m[2], 10) };
+              }
+              render();
+            } else if (a === 'back') {
+              subMode = null;
+              render();
+            } else if (a === 'back-monthly') {
+              subMode = 'monthly';
+              render();
+            } else if (a === 'weekly-pick') {
+              snapAndCommit(`weekly:${el.dataset.wd}`);
+            } else if (a === 'nth-n') {
+              nthDraft.n = parseInt(el.dataset.n, 10);
+              render();
+            } else if (a === 'nth-w') {
+              nthDraft.w = parseInt(el.dataset.wd, 10);
+              render();
+            } else if (a === 'nth-save') {
+              if (nthDraft.n > 0 && nthDraft.w >= 0) {
+                snapAndCommit(`monthly:nth:${nthDraft.n}:${nthDraft.w}`);
+              }
+            }
+          });
+        });
+      }
+
+      render();
+      // Click outside to close (single global handler attached after first paint)
+      setTimeout(() => {
+        const close = (e) => {
+          if (!menu.isConnected) { document.removeEventListener('click', close); return; }
+          if (!menu.contains(e.target)) { menu.remove(); document.removeEventListener('click', close); }
+        };
+        if (menu.isConnected) lifecycle.listen(menu, document, 'click', close);
+      }, 0);
+    }
+
+    function _monthlyShortDescriptor(norm) {
+      const parts = norm.split(':');
+      if (parts[1] === 'day') return `Day ${parts[2]}`;
+      if (parts[1] === 'nth') {
+        const n = parseInt(parts[2], 10);
+        const wd = parseInt(parts[3], 10);
+        return `${_ORDINALS[n - 1] || `${n}th`} ${_DAYS[wd].slice(0, 3)}`;
+      }
+      if (parts[1] === 'last') {
+        const wd = parseInt(parts[2], 10);
+        return `Last ${_DAYS[wd].slice(0, 3)}`;
+      }
+      return '';
+    }
+
+    function _setReminder(datetimeLocalStr) {
+      dueInput.value = datetimeLocalStr;
+      if (remindBtn) {
+        remindBtn.classList.add('has-date');
+        // Jingle the bell. CSS handles the animation; remove + reflow + re-add
+        // so it replays every time the user sets/changes a reminder.
+        const _bell = remindBtn.querySelector('svg');
+        if (_bell) {
+          _bell.classList.remove('jingling');
+          void _bell.offsetWidth;
+          _bell.classList.add('jingling');
+          setTimeout(() => _bell.classList.remove('jingling'), 700);
+        }
+      }
+      _renderReminderTag();
+      _ensureNotificationPermission();
+    }
+
+    function _pickCustomDate() {
+      // Replace the dropdown menu with a small inline picker
+      document.querySelectorAll('.note-reminder-menu').forEach(dismissOrRemove);
+      const menu = document.createElement('div');
+      menu.className = 'note-reminder-menu';
+      const initial = dueInput.value || _toLocalDatetimeStr(_tomorrowDate());
+      menu.innerHTML = `
+      <div class="note-reminder-menu-title">Pick date and time</div>
+      <div class="note-reminder-menu-picker">
+        <input type="datetime-local" class="note-reminder-date-input" />
+      </div>
+      <div class="note-reminder-menu-divider"></div>
+      <button class="note-reminder-menu-item note-reminder-menu-confirm">
+        <span>Save</span>
+      </button>
+    `;
+      document.body.appendChild(menu);
+      // Position next to the bell button
+      const anchor = remindBtn || form.querySelector('.note-form-reminder-tags');
+      const rect = anchor.getBoundingClientRect();
+      const vw = window.innerWidth;
+      const vh = window.innerHeight;
+      const mw = menu.offsetWidth || 240;
+      const mh = menu.offsetHeight || 200;
+      let top = rect.bottom + 4;
+      let left = rect.left;
+      if (top + mh > vh - 8) top = Math.max(8, rect.top - mh - 4);
+      if (left + mw > vw - 8) left = Math.max(8, vw - mw - 8);
+      if (left < 8) left = 8;
+      menu.style.top = top + 'px';
+      menu.style.left = left + 'px';
+      const dInput = menu.querySelector('.note-reminder-date-input');
+      dInput.value = initial;
+      dInput.focus();
+      if (typeof dInput.showPicker === 'function') {
+        try { dInput.showPicker(); } catch {}
+      }
+      const close = bindMenuDismiss(menu, () => { menu.remove(); });
+      menu.querySelector('.note-reminder-menu-confirm').addEventListener('click', () => {
+        if (dInput.value) _setReminder(dInput.value);
+        close();
+      });
+    }
+
+    if (remindBtn) remindBtn.addEventListener('click', (e) => { e.stopPropagation(); _openReminderMenu(remindBtn, !!dueInput.value); });
+    _renderReminderTag();
+
+
+  }
+
+  return { _wireReminderPicker };
+}
diff --git a/static/js/features/notes/ui/selection.js b/static/js/features/notes/ui/selection.js
new file mode 100644
index 000000000..e64549dff
--- /dev/null
+++ b/static/js/features/notes/ui/selection.js
@@ -0,0 +1,61 @@
+/** Selection controls and view feedback for accepted attachments. */
+export function createSelection({
+  operations,
+  _renderNotes,
+  app,
+  state
+}) {
+  function _enterSelectMode(initialId = null) {
+    app.setSelectMode(true);
+    app.clearSelection();
+    if (initialId) app.selectId(initialId);
+    const bar = document.getElementById('notes-bulk-bar');
+    const btn = document.getElementById('notes-select-btn');
+    if (bar) bar.classList.remove('hidden');
+    if (btn) { btn.classList.add('active'); btn.textContent = 'Cancel'; }
+    _renderNotes();
+    _updateBulkBar();
+  }
+
+  function _exitSelectMode() {
+    app.setSelectMode(false);
+    app.clearSelection();
+    const bar = document.getElementById('notes-bulk-bar');
+    const btn = document.getElementById('notes-select-btn');
+    const all = document.getElementById('notes-select-all');
+    if (bar) bar.classList.add('hidden');
+    if (btn) { btn.classList.remove('active'); btn.textContent = 'Select'; }
+    if (all) all.checked = false;
+    _renderNotes();
+  }
+
+  function _updateBulkBar() {
+    const count = state.selectedIds.size;
+    const countEl = document.getElementById('notes-selected-count');
+    const sendAgentBtn = document.getElementById('notes-send-agent');
+    const archiveBtn = document.getElementById('notes-bulk-archive');
+    const deleteBtn = document.getElementById('notes-bulk-delete');
+    const allEl = document.getElementById('notes-select-all');
+    if (countEl) countEl.textContent = `${count} Selected`;
+    if (sendAgentBtn) sendAgentBtn.disabled = count === 0;
+    if (archiveBtn) archiveBtn.disabled = count === 0;
+    if (deleteBtn) deleteBtn.disabled = count === 0;
+    if (allEl) allEl.checked = state.notes.length > 0 && state.notes.every(n => state.selectedIds.has(n.id));
+    // Toggle select-mode class so todo dots don't react to hover
+    const pane = document.getElementById('notes-pane');
+    if (pane) pane.classList.toggle('notes-select-mode', count > 0);
+  }
+
+  function wireSelectionActions() {
+    document.getElementById('notes-select-all').addEventListener('change', e => {
+      if (e.target.checked) state.notes.forEach(n => app.selectId(n.id));
+      else app.clearSelection();
+      _renderNotes(); _updateBulkBar();
+    });
+    document.getElementById('notes-send-agent').addEventListener('click', operations.attachSelected);
+    document.getElementById('notes-bulk-archive').addEventListener('click', operations.archiveSelected);
+    document.getElementById('notes-bulk-delete').addEventListener('click', operations.deleteSelected);
+    document.getElementById('notes-bulk-cancel').addEventListener('click', _exitSelectMode);
+  }
+  return { wireSelectionActions, _enterSelectMode, _exitSelectMode, _updateBulkBar };
+}
diff --git a/static/js/features/notes/ui/text.js b/static/js/features/notes/ui/text.js
new file mode 100644
index 000000000..75ecbaf78
--- /dev/null
+++ b/static/js/features/notes/ui/text.js
@@ -0,0 +1,39 @@
+/** Escaping, safe image sources and link rendering. */
+export function createText({
+  uiModule
+}) {
+  function _esc(s) { return uiModule.esc ? uiModule.esc(s || '') : (s || '').replace(/</g, '&lt;').replace(/>/g, '&gt;'); }
+
+  function _attrEsc(s) {
+    return String(s || '')
+      .replace(/"/g, '&quot;')
+      .replace(/'/g, '&#39;')
+      .replace(/</g, '&lt;')
+      .replace(/>/g, '&gt;')
+      .replace(/`/g, '&#96;');
+  }
+
+  function _safeImgSrc(s) {
+    const v = (s || '').trim();
+    if (!v) return '';
+    if (v.startsWith('/') || v.startsWith('./') || v.startsWith('../')) return v;
+    if (/^https?:\/\//i.test(v) || /^data:image\/(?:png|jpe?g|gif|webp);base64,/i.test(v)) return v;
+    return '';
+  }
+
+  function _linkify(s) {
+    const escaped = _esc(s);
+    const urlRe = /\b((?:https?:\/\/|www\.)[^\s<>"']+[^\s<>"'.,;:!?\]])/g;
+    return escaped.replace(urlRe, (m) => {
+      let url = m;
+      // Trim a trailing ')' that doesn't have a matching '(' inside the URL
+      if (url.endsWith(')') && (url.match(/\(/g) || []).length < (url.match(/\)/g) || []).length) {
+        url = url.slice(0, -1);
+      }
+      const href = url.startsWith('www.') ? `https://${url}` : url;
+      return `<a href="${_attrEsc(href)}" class="note-link" target="_blank" rel="noopener noreferrer" onclick="event.stopPropagation()">${url}</a>` + (url !== m ? m.slice(url.length) : '');
+    });
+  }
+
+  return { _esc, _attrEsc, _safeImgSrc, _linkify };
+}
diff --git a/static/js/features/notes/ui/toolbar.js b/static/js/features/notes/ui/toolbar.js
new file mode 100644
index 000000000..3c3c9fe58
--- /dev/null
+++ b/static/js/features/notes/ui/toolbar.js
@@ -0,0 +1,78 @@
+/** Panel search, archive and list/grid controls. */
+export function createToolbar({
+  app,
+  state,
+  persistence,
+  _renderNotes,
+  _fetchNotes,
+  _applyMasonry
+}) {
+  function wireToolbar(pane) {
+    // Search
+    const searchEl = document.getElementById('notes-search');
+    if (searchEl) {
+      searchEl.addEventListener('input', () => {
+        app.setSearchQuery(searchEl.value.trim().toLowerCase());
+        _renderNotes();
+      });
+    }
+
+    // View toggle
+    const archiveBtn = document.getElementById('notes-archive-toggle');
+    if (archiveBtn) {
+      const ARCHIVE_ICON = '<svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="2" y="3" width="20" height="5" rx="1"/><path d="M4 8v11a2 2 0 002 2h12a2 2 0 002-2V8"/><path d="M10 12h4"/></svg><span class="notes-header-btn-label">Archive</span>';
+      const CLOSE_ICON   = '<svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.4" stroke-linecap="round" stroke-linejoin="round"><line x1="6" y1="6" x2="18" y2="18"/><line x1="18" y1="6" x2="6" y2="18"/></svg><span class="notes-header-btn-label">Archive</span>';
+      const syncArchiveBtn = () => {
+        archiveBtn.classList.toggle('active', state.showingArchived);
+        archiveBtn.title = state.showingArchived ? 'Exit archive' : 'View archive';
+        archiveBtn.style.opacity = state.showingArchived ? '1' : '0.8';
+        // Swap to an X while in archive view so it doubles as a close-back-
+        // to-active-notes toggle.
+        archiveBtn.innerHTML = state.showingArchived ? CLOSE_ICON : ARCHIVE_ICON;
+        // Tint the whole pane so it's obvious you're not in the active list.
+        pane.classList.toggle('notes-pane-archive', state.showingArchived);
+      };
+      syncArchiveBtn();
+      archiveBtn.addEventListener('click', async () => {
+        app.setShowingArchived(!state.showingArchived);
+        app.clearSelection();
+        syncArchiveBtn();
+        // Brief fade so the body content swap doesn't snap : the bg-tint
+        // change is already eased by CSS transitions on .notes-pane*.
+        const _bodyEl = document.querySelector('#notes-pane .notes-pane-body');
+        if (_bodyEl) {
+          _bodyEl.style.transition = 'opacity 0.18s ease';
+          _bodyEl.style.opacity = '0.25';
+        }
+        await _fetchNotes();
+        _renderNotes();
+        if (_bodyEl) {
+          requestAnimationFrame(() => {
+            _bodyEl.style.opacity = '';
+            _bodyEl.addEventListener('transitionend', () => { _bodyEl.style.transition = ''; }, { once: true });
+          });
+        }
+      });
+    }
+    const viewBtn = document.getElementById('notes-view-toggle');
+    if (viewBtn) {
+      pane.classList.toggle('notes-view-grid', state.viewMode === 'grid');
+      // Label shows what you'll switch TO : "Grid" while in list, "List" while in grid.
+      const _setViewLabel = () => {
+        const lbl = viewBtn.querySelector('.notes-header-btn-label');
+        if (lbl) lbl.textContent = state.viewMode === 'grid' ? 'List' : 'Grid';
+      };
+      _setViewLabel();
+      requestAnimationFrame(() => _applyMasonry(document.querySelector('#notes-pane .notes-pane-body')));
+      viewBtn.addEventListener('click', () => {
+        app.setViewMode(state.viewMode === 'grid' ? 'list' : 'grid');
+        try { persistence.setItem('odysseus-notes-view', state.viewMode); } catch {}
+        pane.classList.toggle('notes-view-grid', state.viewMode === 'grid');
+        _setViewLabel();
+        requestAnimationFrame(() => _applyMasonry(document.querySelector('#notes-pane .notes-pane-body')));
+      });
+    }
+
+  }
+  return { wireToolbar };
+}
diff --git a/static/js/features/notes/ui/windowLayout.js b/static/js/features/notes/ui/windowLayout.js
new file mode 100644
index 000000000..9e9173a47
--- /dev/null
+++ b/static/js/features/notes/ui/windowLayout.js
@@ -0,0 +1,114 @@
+/** Shared-window integration: safe fullscreen bounds, docking and stacking. */
+export function createWindowLayout({
+  makeWindowDraggable,
+  snapModalToZone,
+  clearDockSide,
+  applyEdgeDock,
+  topToolWindowZ
+}) {
+  function _notesFullscreenSafeRect() {
+    const vw = window.innerWidth || document.documentElement.clientWidth || 0;
+    const vh = window.innerHeight || document.documentElement.clientHeight || 0;
+    let left = 0;
+    let right = vw;
+
+    const sidebar = document.getElementById('sidebar');
+    const rail = document.getElementById('icon-rail');
+    const hamburgerRight = document.body.classList.contains('hamburger-right')
+      || sidebar?.classList.contains('right-side')
+      || rail?.classList.contains('right-side');
+
+    const reserve = (el) => {
+      if (!el || getComputedStyle(el).display === 'none') return;
+      const rect = el.getBoundingClientRect();
+      if (rect.width <= 0 || rect.height <= 0) return;
+      if (hamburgerRight) right = Math.min(right, rect.left);
+      else left = Math.max(left, rect.right);
+    };
+
+    if (sidebar && !sidebar.classList.contains('hidden')) reserve(sidebar);
+    reserve(rail);
+
+    // The fixed hamburger can remain visible even when the rail/sidebar is
+    // collapsed. Reserve its strip too so fullscreen Notes does not sit beneath it.
+    const hamburger = document.getElementById('hamburger-btn');
+    if (hamburger && getComputedStyle(hamburger).display !== 'none') {
+      const rect = hamburger.getBoundingClientRect();
+      const pad = 8;
+      if (hamburgerRight) right = Math.min(right, rect.left - pad);
+      else left = Math.max(left, rect.right + pad);
+    }
+
+    left = Math.max(0, Math.min(left, vw - 80));
+    right = Math.max(left + 80, Math.min(right, vw));
+    return { left, top: 0, width: right - left, height: vh };
+  }
+
+  function _wireNotesWindow(pane) {
+    if (!pane || pane.dataset.windowDragWired === '1') return;
+    const header = pane.querySelector('.notes-pane-header');
+    if (!header) return;
+    pane.dataset.windowDragWired = '1';
+    makeWindowDraggable(pane, {
+      content: pane,
+      header,
+      fsClass: 'notes-window-fullscreen',
+      skipSelector: 'button, input, select, textarea, label, .notes-mobile-grabber',
+      enableDock: true,
+      enableLeftDock: true,
+      onEnterFullscreen: () => {
+        pane.classList.add('notes-window-fullscreen');
+        snapModalToZone(pane, {
+          name: 'fullscreen',
+          rect: _notesFullscreenSafeRect(),
+        });
+      },
+      onExitFullscreen: () => {
+        _restoreNotesSidebarDock(pane);
+      },
+    });
+  }
+
+  function _clearNotesSnapStyles(pane) {
+    if (!pane) return;
+    const hadLeft = pane.classList.contains('modal-left-docked');
+    const hadRight = pane.classList.contains('modal-right-docked');
+    pane.classList.remove('notes-window-fullscreen', 'modal-left-docked', 'modal-right-docked');
+    if (hadLeft) clearDockSide('left', pane);
+    if (hadRight) clearDockSide('right', pane);
+    ['position', 'left', 'top', 'right', 'bottom', 'width', 'max-width', 'height',
+      'max-height', 'margin', 'transform', 'border-radius']
+      .forEach((prop) => pane.style.removeProperty(prop));
+    delete pane.dataset._tilePreSnap;
+    delete pane.dataset._tileZone;
+    delete pane._preDockSnapshot;
+    delete pane._dockSide;
+    delete pane._dockSuspended;
+  }
+
+  function _restoreNotesSidebarDock(pane) {
+    if (!pane || window.innerWidth <= 768) return;
+    _clearNotesSnapStyles(pane);
+    if (!pane.isConnected) return;
+    applyEdgeDock(pane, 'right');
+  }
+
+  function _topToolWindowZ(exclude = null) {
+    return topToolWindowZ({ exclude });
+  }
+
+  function _bringNotesToFront(pane = document.getElementById('notes-pane')) {
+    if (!pane) return;
+    const backdrop = document.getElementById('notes-pane-backdrop') || pane.parentElement;
+    const z = _topToolWindowZ(backdrop) + 1;
+    if (backdrop) backdrop.style.setProperty('z-index', String(z), 'important');
+    try {
+      window.dispatchEvent(new CustomEvent('odysseus:modal-opened', {
+        detail: { id: 'notes-panel', modal: pane },
+      }));
+    } catch (_) {}
+  }
+
+
+  return { _wireNotesWindow, _restoreNotesSidebarDock, _bringNotesToFront };
+}
diff --git a/static/js/notes.js b/static/js/notes.js
index 8db829706..38bf3d7e6 100644
--- a/static/js/notes.js
+++ b/static/js/notes.js
@@ -1,5470 +1,5 @@
-/**
- * Notes Module — Google Keep-style notes and todos.
- * Renders as a sidebar panel (like document editor), not a modal.
- */
-
-import uiModule from './ui.js?v=20260916largetoolscroll1';
-import { spawnConfetti } from './compare/vote.js?v=20260828resendcaldrag1';
-import * as Modals from './modalManager.js';
-import { attachColorPicker } from './colorPicker.js?v=20260910eyedropper1';
-import { makeWindowDraggable } from './windowDrag.js';
-import { snapModalToZone } from './tileManager.js?v=20260910responsivebounds1';
-import { applyEdgeDock, clearDockSide } from './modalSnap.js';
-import { topToolWindowZ, topPortalZ } from './toolWindowZOrder.js';
-import { bindMenuDismiss, dismissOrRemove } from './escMenuStack.js';
-import { bindTourHintDismiss } from './tourHintDismiss.js';
-
-const API_BASE = window.location.origin;
-let _open = false;
-let _notes = [];
-let _editingId = null;
-let _selectedIds = new Set();
-let _activeLabel = null;
-let _activeFilter = null; // null | 'default' | 'reminders' | 'no-reminders'
-// Cycle order for the Reminders chip: each click on it advances reminders →
-// null → no-reminders → null → reminders → ... This var tracks which non-null
-// state the next click should land on after passing through null.
-let _reminderChipNext = 'reminders';
-let _searchQuery = '';
-let _viewMode = (typeof localStorage !== 'undefined' && localStorage.getItem('odysseus-notes-view')) || 'list'; // 'list' or 'grid'
-let _showingArchived = false;
-let _selectMode = false;
-let _suppressNextNoteTapId = null;
-let _reminderTimer = null;
-// Tracks the global keydown listener so closePanel can remove it
-// (previously leaked one per openPanel; on multi-open sessions this
-// stacked dozens of identical handlers).
-let _notesKeydownHandler = null;
-// Capture-phase "Esc cancels select mode" listener on document — tracked so it
-// is removed on close instead of leaking +1 per panel open/close cycle.
-let _notesSelectEscHandler = null;
-const REMINDER_FIRED_KEY = 'odysseus-notes-reminder-fired';
-// Note IDs already shown with the entry-glow once. Re-set when the user
-// reschedules the reminder so the new firing glows again on next open.
-const REMINDER_GLOWED_KEY = 'odysseus-notes-reminder-glowed';
-// IDs of notes whose reminders fired while the notes panel was closed. On the
-// next open of the panel we briefly glow those cards so the user can spot them.
-const REMINDER_PENDING_HIGHLIGHT_KEY = 'odysseus-notes-reminder-pending-highlight';
-const REMINDER_ACTIVE_HIGHLIGHT_KEY = 'odysseus-notes-reminder-active-highlight';
-// Timestamp of the last time the user opened the notes panel — used to gate
-// the rail "fired" badge so old reminders don't re-fire on every page reload.
-const REMINDER_DISMISSED_AT_KEY = 'odysseus-notes-reminder-dismissed-at';
-const NOTES_FIRST_OPEN_HINT_KEY = 'odysseus-notes-first-open-hint-v1';
-const NOTES_LABELS_COLLAPSED_KEY = 'odysseus-notes-labels-collapsed';
-let _labelsCollapsed = (typeof localStorage !== 'undefined' && localStorage.getItem(NOTES_LABELS_COLLAPSED_KEY) === '1');
-
-function _forceCloseNotesPanel() {
-  _open = false;
-  _editingId = null;
-  try { _commitOpenInPlaceEditor(); } catch {}
-  try { _closeMobileFullscreenEdit({ save: true }); } catch {}
-  try { _clearViewedReminderGlows(); } catch {}
-  if (_notesKeydownHandler) {
-    document.removeEventListener('keydown', _notesKeydownHandler);
-    _notesKeydownHandler = null;
-  }
-  if (_notesSelectEscHandler) {
-    document.removeEventListener('keydown', _notesSelectEscHandler, true);
-    _notesSelectEscHandler = null;
-  }
-  if (_reminderTimer) {
-    clearInterval(_reminderTimer);
-    _reminderTimer = null;
-  }
-  document.body.classList.remove('notes-view', 'notes-mobile-mode', 'notes-drag-mode');
-  document.getElementById('tool-notes-btn')?.classList.remove('active');
-  try { Modals.unregister('notes-panel'); } catch {}
-  try { document.getElementById('notes-pane')?.remove(); } catch {}
-  try { document.getElementById('notes-pane-backdrop')?.remove(); } catch {}
-  try { window._restoreSidebarIfRouteCollapsed?.(); } catch {}
-}
-
-function _showNotesFirstOpenHint(pane) {
-  if (!pane || typeof localStorage === 'undefined') return;
-  try {
-    if (localStorage.getItem(NOTES_FIRST_OPEN_HINT_KEY)) return;
-    localStorage.setItem(NOTES_FIRST_OPEN_HINT_KEY, '1');
-  } catch {
-    return;
-  }
-
-  dismissOrRemove(document.getElementById('notes-first-open-hint'));
-  const hint = document.createElement('div');
-  hint.id = 'notes-first-open-hint';
-  hint.className = 'tour-hint';
-  hint.innerHTML = `
-    <div class="tour-hint-text"><b>Notes</b> is your basic todo list, and also where reminders are managed.</div>
-    <button type="button" class="tour-hint-dismiss">OK</button>
-  `;
-  document.body.appendChild(hint);
-
-  const place = () => {
-    const r = pane.getBoundingClientRect();
-    const hw = hint.offsetWidth || 260;
-    hint.style.top = Math.max(12, r.top + 58) + 'px';
-    hint.style.left = Math.min(window.innerWidth - hw - 12, Math.max(12, r.left + 18)) + 'px';
-  };
-  requestAnimationFrame(() => {
-    place();
-    hint.classList.add('tour-hint-in');
-  });
-  window.addEventListener('resize', place);
-  bindTourHintDismiss(hint, {
-    timeout: 6500,
-    fade: 180,
-    onDismiss: () => window.removeEventListener('resize', place),
-  });
-}
-
-function _notesFullscreenSafeRect() {
-  const vw = window.innerWidth || document.documentElement.clientWidth || 0;
-  const vh = window.innerHeight || document.documentElement.clientHeight || 0;
-  let left = 0;
-  let right = vw;
-
-  const sidebar = document.getElementById('sidebar');
-  const rail = document.getElementById('icon-rail');
-  const hamburgerRight = document.body.classList.contains('hamburger-right')
-    || sidebar?.classList.contains('right-side')
-    || rail?.classList.contains('right-side');
-
-  const reserve = (el) => {
-    if (!el || getComputedStyle(el).display === 'none') return;
-    const rect = el.getBoundingClientRect();
-    if (rect.width <= 0 || rect.height <= 0) return;
-    if (hamburgerRight) right = Math.min(right, rect.left);
-    else left = Math.max(left, rect.right);
-  };
-
-  if (sidebar && !sidebar.classList.contains('hidden')) reserve(sidebar);
-  reserve(rail);
-
-  // The fixed hamburger can remain visible even when the rail/sidebar is
-  // collapsed. Reserve its strip too so fullscreen Notes does not sit beneath it.
-  const hamburger = document.getElementById('hamburger-btn');
-  if (hamburger && getComputedStyle(hamburger).display !== 'none') {
-    const rect = hamburger.getBoundingClientRect();
-    const pad = 8;
-    if (hamburgerRight) right = Math.min(right, rect.left - pad);
-    else left = Math.max(left, rect.right + pad);
-  }
-
-  left = Math.max(0, Math.min(left, vw - 80));
-  right = Math.max(left + 80, Math.min(right, vw));
-  return { left, top: 0, width: right - left, height: vh };
-}
-
-function _wireNotesWindow(pane) {
-  if (!pane || pane.dataset.windowDragWired === '1') return;
-  const header = pane.querySelector('.notes-pane-header');
-  if (!header) return;
-  pane.dataset.windowDragWired = '1';
-  makeWindowDraggable(pane, {
-    content: pane,
-    header,
-    fsClass: 'notes-window-fullscreen',
-    skipSelector: 'button, input, select, textarea, label, .notes-mobile-grabber',
-    enableDock: true,
-    enableLeftDock: true,
-    onEnterFullscreen: () => {
-      pane.classList.add('notes-window-fullscreen');
-      snapModalToZone(pane, {
-        name: 'fullscreen',
-        rect: _notesFullscreenSafeRect(),
-      });
-    },
-    onExitFullscreen: () => {
-      _restoreNotesSidebarDock(pane);
-    },
-  });
-}
-
-function _clearNotesSnapStyles(pane) {
-  if (!pane) return;
-  const hadLeft = pane.classList.contains('modal-left-docked');
-  const hadRight = pane.classList.contains('modal-right-docked');
-  pane.classList.remove('notes-window-fullscreen', 'modal-left-docked', 'modal-right-docked');
-  if (hadLeft) clearDockSide('left', pane);
-  if (hadRight) clearDockSide('right', pane);
-  ['position', 'left', 'top', 'right', 'bottom', 'width', 'max-width', 'height',
-    'max-height', 'margin', 'transform', 'border-radius']
-    .forEach((prop) => pane.style.removeProperty(prop));
-  delete pane.dataset._tilePreSnap;
-  delete pane.dataset._tileZone;
-  delete pane._preDockSnapshot;
-  delete pane._dockSide;
-  delete pane._dockSuspended;
-}
-
-function _restoreNotesSidebarDock(pane) {
-  if (!pane || window.innerWidth <= 768) return;
-  _clearNotesSnapStyles(pane);
-  if (!pane.isConnected) return;
-  applyEdgeDock(pane, 'right');
-}
-
-// Notes is not a `.modal`; its backdrop is the top-level stacking surface.
-function _topToolWindowZ(exclude = null) {
-  return topToolWindowZ({ exclude });
-}
-
-function _bringNotesToFront(pane = document.getElementById('notes-pane')) {
-  if (!pane) return;
-  const backdrop = document.getElementById('notes-pane-backdrop') || pane.parentElement;
-  const z = _topToolWindowZ(backdrop) + 1;
-  if (backdrop) backdrop.style.setProperty('z-index', String(z), 'important');
-  try {
-    window.dispatchEvent(new CustomEvent('odysseus:modal-opened', {
-      detail: { id: 'notes-panel', modal: pane },
-    }));
-  } catch (_) {}
-}
-
-function _loadPendingHighlights() {
-  try { return new Set(JSON.parse(localStorage.getItem(REMINDER_PENDING_HIGHLIGHT_KEY) || '[]')); }
-  catch { return new Set(); }
-}
-function _loadGlowedReminders() {
-  try { return new Set(JSON.parse(localStorage.getItem(REMINDER_GLOWED_KEY) || '[]')); }
-  catch { return new Set(); }
-}
-function _saveGlowedReminders(set) {
-  try { localStorage.setItem(REMINDER_GLOWED_KEY, JSON.stringify([...set])); } catch {}
-}
-function _loadActiveHighlights() {
-  try { return new Set(JSON.parse(localStorage.getItem(REMINDER_ACTIVE_HIGHLIGHT_KEY) || '[]')); }
-  catch { return new Set(); }
-}
-function _saveActiveHighlights(set) {
-  try { localStorage.setItem(REMINDER_ACTIVE_HIGHLIGHT_KEY, JSON.stringify([...set])); } catch {}
-}
-
-function _isCalendarReminderNote(n) {
-  return n && n.source === 'calendar' && n.label === 'calendar';
-}
-
-function _userVisibleNotes() {
-  return _notes.filter(n => !_isCalendarReminderNote(n));
-}
-
-function _clearViewedReminderGlows() {
-  const active = _loadActiveHighlights();
-  if (!active.size) return;
-  _saveActiveHighlights(new Set());
-  document.querySelectorAll('.note-card-reminder-fired-sticky').forEach(card => {
-    card.classList.remove('note-card-reminder-fired-sticky');
-  });
-}
-function _setReminderCardGlow(noteId, on = true) {
-  if (!noteId) return;
-  const active = _loadActiveHighlights();
-  if (on) active.add(noteId);
-  else active.delete(noteId);
-  _saveActiveHighlights(active);
-  document.querySelectorAll(`.note-card[data-note-id="${noteId}"]`).forEach(card => {
-    card.classList.toggle('note-card-reminder-fired-sticky', on);
-  });
-}
-// A note has an active reminder when its due time has passed and the user
-// hasn't archived or fully completed it. Used for both sorting (bumped above
-// the rest of the unpinned section) and the entry-glow flush.
-function _hasActiveReminder(n) {
-  if (!n || n.archived || _isNoteFullyDone(n)) return false;
-  if (!n.due_date) return false;
-  const t = new Date(n.due_date).getTime();
-  return !isNaN(t) && t <= Date.now();
-}
-function _savePendingHighlights(set) {
-  try { localStorage.setItem(REMINDER_PENDING_HIGHLIGHT_KEY, JSON.stringify([...set])); }
-  catch {}
-}
-function _queuePendingHighlight(noteId) {
-  const set = _loadPendingHighlights();
-  set.add(noteId);
-  _savePendingHighlights(set);
-}
-function _flushPendingHighlights() {
-  // Fresh firings (queued by the background loop while the panel was closed)
-  // glow unconditionally — a notification just told the user something
-  // happened, so we always point at the note even if it was glowed before.
-  const queued = _loadPendingHighlights();
-  const glowed = _loadGlowedReminders();
-  const toGlow = new Set(queued);
-  // For notes that are merely overdue at open time (no fresh firing event),
-  // only glow the ones we haven't already shown — otherwise reopening the
-  // panel keeps lighting up old reminders forever.
-  for (const n of _notes) {
-    if (!_hasActiveReminder(n) || !_hasTimeComponent(n.due_date)) continue;
-    if (queued.has(n.id) || !glowed.has(n.id)) toGlow.add(n.id);
-  }
-  // Always consume the queue.
-  _savePendingHighlights(new Set());
-  if (!toGlow.size) return;
-  let firstCard = null;
-  for (const id of toGlow) {
-    const card = document.querySelector(`.note-card[data-note-id="${id}"]`);
-    if (!card) continue;
-    _setReminderCardGlow(id, true);
-    if (!firstCard) firstCard = card;
-    glowed.add(id);
-  }
-  _saveGlowedReminders(glowed);
-  // Bring the first one into view so it can't get buried below the fold.
-  if (firstCard) {
-    requestAnimationFrame(() => {
-      _smoothScrollToNoteCard(firstCard);
-    });
-  }
-}
-
-const COLORS = [
-  { name: 'none',    value: '' },
-  { name: 'red',     value: 'red' },
-  { name: 'orange',  value: 'orange' },
-  { name: 'yellow',  value: 'yellow' },
-  { name: 'green',   value: 'green' },
-  { name: 'blue',    value: 'blue' },
-  { name: 'purple',  value: 'purple' },
-  { name: 'custom',  value: 'custom' },  // sentinel — clicking opens native color picker
-];
-
-const _CUSTOM_GRADIENT = 'conic-gradient(from 0deg, #e06c75, #d19a66, #e5c07b, #98c379, #61afef, #c678dd, #e06c75)';
-
-// A note's color is one of: '' (none), a preset name (red/orange/…), or a
-// sentinel "bg:<image-url>" for a custom background image uploaded by the user.
-function _isBgImage(c) { return typeof c === 'string' && c.startsWith('bg:'); }
-function _bgImageUrl(c) { return _isBgImage(c) ? c.slice(3) : ''; }
-
-function _dotBg(value, noteColor) {
-  if (value === 'custom') {
-    const url = _bgImageUrl(noteColor);
-    return url ? `center/cover no-repeat url('${url}')` : _CUSTOM_GRADIENT;
-  }
-  return COLOR_HEX[value];
-}
-
-function _dotIsActive(value, noteColor) {
-  if (value === 'custom') return _isBgImage(noteColor);
-  return value === (noteColor || '');
-}
-
-// Inline style for a note card/form when color is a custom bg image.
-function _customColorStyle(c) {
-  if (!_isBgImage(c)) return '';
-  const url = _bgImageUrl(c);
-  return `background-image: linear-gradient(color-mix(in srgb, var(--panel) 60%, transparent), color-mix(in srgb, var(--panel) 60%, transparent)), url('${url}'); background-size: cover; background-position: center; border-color: color-mix(in srgb, var(--fg) 25%, var(--border));`;
-}
-
-// Open a file picker, upload the chosen image, and resolve with the URL.
-function _pickCustomBgImage() {
-  return new Promise(resolve => {
-    const input = document.createElement('input');
-    input.type = 'file';
-    input.accept = 'image/*';
-    input.style.cssText = 'position:fixed; left:-9999px; top:-9999px;';
-    document.body.appendChild(input);
-    let done = false;
-    const finish = (v) => { if (done) return; done = true; input.remove(); resolve(v); };
-    input.addEventListener('change', async () => {
-      const file = input.files?.[0];
-      if (!file) return finish(null);
-      const fd = new FormData();
-      fd.append('files', file);
-      try {
-        const res = await fetch(`${API_BASE}/api/upload`, { method: 'POST', body: fd, credentials: 'same-origin' });
-        const data = await res.json();
-        const fileId = data.files?.[0]?.id;
-        if (!fileId) throw new Error('Upload failed');
-        finish(`${API_BASE}/api/upload/${fileId}`);
-      } catch { finish(null); }
-    });
-    // Best-effort cleanup if user dismisses the dialog.
-    setTimeout(() => { if (!done && !input.files?.length) finish(null); }, 30000);
-    input.click();
-  });
-}
-
-const COLOR_HEX = {
-  '':       'var(--border)',
-  // Pale/pastel palette — matches the calendar event color picker.
-  red:      '#f0b5ba',
-  orange:   '#e8ccb2',
-  yellow:   '#f2dfbd',
-  green:    '#cce0bc',
-  blue:     '#b0d7f7',
-  purple:   '#e2bcee',
-};
-
-// Plain notes get a stable visual variant derived from their identity. This
-// adds recognition without changing a color the user explicitly selected.
-function _standardVisualVariant(note) {
-  const source = String(note?.id || note?.title || note?.created_at || 'standard-note');
-  let hash = 0;
-  for (let i = 0; i < source.length; i++) hash = ((hash << 5) - hash + source.charCodeAt(i)) | 0;
-  return Math.abs(hash) % 5;
-}
-
-// ---- API ----
-
-let _loading = false;
-// Undo stack — most recent action is at the end. We cap it small because the
-// only entries that survive a panel reload are in-memory anyway.
-const _undoStack = [];
-const _NOTE_UNDO_ICON = '<svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round" style="vertical-align:middle;"><polyline points="9 14 4 9 9 4"/><path d="M4 9h11a5 5 0 0 1 5 5v0a5 5 0 0 1-5 5H9"/></svg>';
-function _pushUndo(entry) {
-  _undoStack.push(entry);
-  if (_undoStack.length > 20) _undoStack.shift();
-}
-function _popAndRunUndo() {
-  const entry = _undoStack.pop();
-  if (entry) entry.run();
-  return !!entry;
-}
-
-function _undoArchive(note, prevIdx) {
-  // Re-insert at original position and clear archived flag on the server.
-  const safeIdx = Math.min(Math.max(prevIdx, 0), _notes.length);
-  _notes.splice(safeIdx, 0, { ...note, archived: false });
-  _renderNotes();
-  _patchNote(note.id, { archived: false }).catch(() => {
-    // Roll back local insertion if the server refuses
-    const i = _notes.findIndex(n => n.id === note.id);
-    if (i >= 0) _notes.splice(i, 1);
-    _renderNotes();
-    uiModule.showError('Undo failed');
-  });
-}
-
-function _archiveNoteById(id, { card = null, celebrate = false } = {}) {
-  if (!id) return false;
-  const idx = _notes.findIndex(n => n.id === id);
-  if (idx < 0) return false;
-  const note = _notes[idx];
-  if (celebrate && card && note && _hasItems(note)) {
-    const undone = (note.items || []).filter(i => !i.done);
-    if (undone.length === 0) {
-      const r = card.getBoundingClientRect();
-      spawnConfetti(r.left + r.width / 2, r.top + r.height / 2, 80);
-    }
-  }
-  const removed = _notes.splice(idx, 1)[0];
-  _editingId = null;
-  _renderNotes();
-  const undo = () => _undoArchive(removed, idx);
-  _pushUndo({ label: 'archive', run: undo });
-  _patchNote(id, { archived: true }).then(() => {
-    uiModule.showToast('Archived', { duration: 6000, action: 'Undo', actionIcon: _NOTE_UNDO_ICON, onAction: undo, actionHint: 'Ctrl+Z' });
-  }).catch(() => {
-    _notes.splice(idx, 0, removed);
-    _renderNotes();
-    uiModule.showError('Failed to archive');
-  });
-  return true;
-}
-
-async function _fetchNotes() {
-  _loading = true;
-  try {
-    const url = `${API_BASE}/api/notes${_showingArchived ? '?archived=true' : ''}`;
-    const res = await fetch(url, { credentials: 'same-origin' });
-    if (!res.ok) { _notes = []; return; }
-    const data = await res.json();
-    _notes = data.notes || data || [];
-  } catch (e) {
-    console.error('Failed to fetch notes:', e);
-    _notes = [];
-  } finally {
-    _loading = false;
-  }
-}
-
-async function _saveNote(note) {
-  const method = note.id ? 'PUT' : 'POST';
-  const url = note.id ? `${API_BASE}/api/notes/${note.id}` : `${API_BASE}/api/notes`;
-  const res = await fetch(url, {
-    method, credentials: 'same-origin',
-    headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify(note),
-  });
-  if (!res.ok) throw new Error('Failed to save note');
-  return await res.json();
-}
-
-async function _deleteNoteApi(id) {
-  // v2 review — used to swallow 4xx/5xx silently. Throw so callers can
-  // distinguish success vs failure and toast accordingly.
-  const r = await fetch(`${API_BASE}/api/notes/${id}`, { method: 'DELETE', credentials: 'same-origin' });
-  if (!r.ok) throw new Error('HTTP ' + r.status);
-}
-
-async function _patchNote(id, patch) {
-  const res = await fetch(`${API_BASE}/api/notes/${id}`, {
-    method: 'PUT', credentials: 'same-origin',
-    headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify(patch),
-  });
-  if (!res.ok) throw new Error('Failed to update note');
-  return await res.json();
-}
-
-// ---- Helpers ----
-
-function _esc(s) { return uiModule.esc ? uiModule.esc(s || '') : (s || '').replace(/</g, '&lt;').replace(/>/g, '&gt;'); }
-function _attrEsc(s) {
-  return String(s || '')
-    .replace(/"/g, '&quot;')
-    .replace(/'/g, '&#39;')
-    .replace(/</g, '&lt;')
-    .replace(/>/g, '&gt;')
-    .replace(/`/g, '&#96;');
-}
-// Image src guard — reject anything that isn't a relative path, http(s), or
-// raster data URL so an AI-saved note can't slip script-capable media into the
-// rendered <img>.
-function _safeImgSrc(s) {
-  const v = (s || '').trim();
-  if (!v) return '';
-  if (v.startsWith('/') || v.startsWith('./') || v.startsWith('../')) return v;
-  if (/^https?:\/\//i.test(v) || /^data:image\/(?:png|jpe?g|gif|webp);base64,/i.test(v)) return v;
-  return '';
-}
-
-// Escape then turn http(s)://... URLs into clickable anchors. XSS-safe.
-// Allow balanced `(...)` inside the URL (Wikipedia, MD links) by accepting
-// `(` in the body, then trim a trailing unmatched `)` afterwards.
-function _linkify(s) {
-  const escaped = _esc(s);
-  const urlRe = /\b((?:https?:\/\/|www\.)[^\s<>"']+[^\s<>"'.,;:!?\]])/g;
-  return escaped.replace(urlRe, (m) => {
-    let url = m;
-    // Trim a trailing ')' that doesn't have a matching '(' inside the URL
-    if (url.endsWith(')') && (url.match(/\(/g) || []).length < (url.match(/\)/g) || []).length) {
-      url = url.slice(0, -1);
-    }
-    const href = url.startsWith('www.') ? `https://${url}` : url;
-    return `<a href="${_attrEsc(href)}" class="note-link" target="_blank" rel="noopener noreferrer" onclick="event.stopPropagation()">${url}</a>` + (url !== m ? m.slice(url.length) : '');
-  });
-}
-function _uid() { return Math.random().toString(36).slice(2, 10); }
-
-// Mobile swipe-to-dismiss for the notes sheet. Mirrors the document panel
-// gesture (finger-following, velocity-based dismiss, rubber-band, snap-back)
-// so both sheets feel identical; dismisses via the notes closePanel('down').
-function _wireNotesSwipeDismiss(el, pane) {
-  if (!el || !pane) return;
-  const DISMISS_THRESHOLD = 50, VELOCITY_THRESHOLD = 0.3, RUBBER = 0.35;
-  let startY = 0, startX = 0, lastY = 0, lastT = 0, velocity = 0;
-  let dragging = false, cancelled = false;
-
-  el.addEventListener('touchstart', (e) => {
-    if (window.innerWidth > 768 || e.touches.length !== 1) return;
-    if (e.target.closest('button, input, select, label, textarea')) return;
-    const t = e.touches[0];
-    startY = t.clientY; startX = t.clientX; lastY = startY; lastT = e.timeStamp;
-    velocity = 0; dragging = false; cancelled = false;
-  }, { passive: true });
-
-  el.addEventListener('touchmove', (e) => {
-    if (cancelled || window.innerWidth > 768) return;
-    const t = e.touches[0];
-    const dx = Math.abs(t.clientX - startX);
-    const dy = t.clientY - startY;
-    if (!dragging) {
-      if (dx > 40 && dx > Math.abs(dy) * 2) { cancelled = true; return; }
-      if (Math.abs(dy) > 8) {
-        dragging = true;
-        pane.style.animation = 'none';
-        pane.style.transition = 'none';
-        pane.style.willChange = 'transform';
-      } else return;
-    }
-    const dt = e.timeStamp - lastT;
-    if (dt > 0) velocity = velocity * 0.6 + ((t.clientY - lastY) / dt) * 0.4;
-    lastY = t.clientY; lastT = e.timeStamp;
-    e.preventDefault();
-    pane.style.transform = dy > 0 ? `translateY(${dy}px)` : `translateY(${dy * RUBBER}px)`;
-  }, { passive: false });
-
-  const endSwipe = () => {
-    if (!dragging) return;
-    dragging = false;
-    pane.style.willChange = '';
-    const dy = lastY - startY;
-    if (dy > DISMISS_THRESHOLD || (dy > 20 && velocity > VELOCITY_THRESHOLD)) {
-      // Slide fully off-screen, then minimise. Keep it translated down (don't
-      // reset) so it doesn't flash back before closePanel removes it.
-      pane.style.transition = 'transform 0.2s cubic-bezier(0.2, 0, 0.4, 1)';
-      pane.style.transform = 'translateY(100%)';
-      setTimeout(() => closePanel('down'), 200);
-    } else {
-      pane.style.transition = 'transform 0.25s cubic-bezier(0.2, 0.9, 0.3, 1.05)';
-      pane.style.transform = '';
-      setTimeout(() => { pane.style.transition = ''; }, 260);
-    }
-  };
-  el.addEventListener('touchend', endSwipe, { passive: true });
-  el.addEventListener('touchcancel', endSwipe, { passive: true });
-}
-
-function _hasTimeComponent(dateStr) {
-  return typeof dateStr === 'string' && /T\d{2}:\d{2}/.test(dateStr);
-}
-
-function _formatDueDate(dateStr) {
-  if (!dateStr) return '';
-  const d = new Date(dateStr);
-  if (isNaN(d)) return '';
-  const now = new Date();
-  const hasTime = _hasTimeComponent(dateStr);
-  const today = new Date(now.getFullYear(), now.getMonth(), now.getDate());
-  const due = new Date(d.getFullYear(), d.getMonth(), d.getDate());
-  const diffDays = Math.round((due - today) / 86400000);
-  const timeStr = hasTime ? d.toLocaleTimeString([], { hour: 'numeric', minute: '2-digit' }) : '';
-  if (hasTime && d < now) return 'overdue';
-  if (!hasTime && diffDays < 0) return 'overdue';
-  if (diffDays === 0) return hasTime ? timeStr : 'today';
-  if (diffDays === 1) return hasTime ? `tmrw ${timeStr}` : 'tomorrow';
-  const dateLabel = d.toLocaleDateString([], { month: 'short', day: 'numeric' });
-  return hasTime ? `${dateLabel} ${timeStr}` : dateLabel;
-}
-
-function _isDueOverdue(dateStr) {
-  if (!dateStr) return false;
-  const d = new Date(dateStr);
-  if (isNaN(d)) return false;
-  if (_hasTimeComponent(dateStr)) return d < new Date();
-  return d < new Date(new Date().toDateString());
-}
-
-function _isDueTodayOrOverdue(dateStr) {
-  if (!dateStr) return false;
-  const d = new Date(dateStr);
-  const now = new Date();
-  const today = new Date(now.getFullYear(), now.getMonth(), now.getDate());
-  const due = new Date(d.getFullYear(), d.getMonth(), d.getDate());
-  return due <= today;
-}
-
-function _isNoteFullyDone(note) {
-  if (_hasItems(note) && Array.isArray(note.items) && note.items.length > 0) {
-    return note.items.every(it => it.done);
-  }
-  return false;
-}
-
-// A "checklist note" — todo or goal — has structured items[] that the cards
-// render as checkboxes and that "fully done" / progress logic reads from.
-function _hasItems(note) {
-  return note && (note.note_type === 'todo' || note.note_type === 'goal' || note.note_type === 'checklist');
-}
-
-// Compact " N/M" progress string for a goal's checklist. Empty when the goal
-// has no steps yet (e.g. AI breakdown is still in flight or was cancelled).
-function _goalProgress(note) {
-  if (!Array.isArray(note?.items) || note.items.length === 0) return '';
-  const done = note.items.filter(it => it.done).length;
-  return ` ${done}/${note.items.length}`;
-}
-
-// The next unchecked step in a goal, or null if all done / no items.
-function _nextGoalStep(note) {
-  if (!Array.isArray(note?.items)) return null;
-  for (let i = 0; i < note.items.length; i++) {
-    if (!note.items[i].done) return { idx: i, item: note.items[i] };
-  }
-  return null;
-}
-
-// ---- Reminder presets ----
-
-function _laterTodayDate() {
-  const now = new Date();
-  const eight = new Date(now.getFullYear(), now.getMonth(), now.getDate(), 18, 0); // 6pm today
-  // If less than 1 hour before 6pm, push to "in 3 hours" instead
-  if (eight - now < 60 * 60 * 1000) return new Date(now.getTime() + 3 * 60 * 60 * 1000);
-  return eight;
-}
-function _tomorrowDate() {
-  const t = new Date();
-  t.setDate(t.getDate() + 1);
-  t.setHours(8, 0, 0, 0);
-  return t;
-}
-function _nextWeekDate() {
-  const t = new Date();
-  const daysUntilMon = (8 - t.getDay()) % 7 || 7;
-  t.setDate(t.getDate() + daysUntilMon);
-  t.setHours(8, 0, 0, 0);
-  return t;
-}
-function _toLocalDatetimeStr(d) {
-  // Format as YYYY-MM-DDTHH:MM (local, no TZ)
-  const pad = n => String(n).padStart(2, '0');
-  return `${d.getFullYear()}-${pad(d.getMonth()+1)}-${pad(d.getDate())}T${pad(d.getHours())}:${pad(d.getMinutes())}`;
-}
-function _formatReminderTag(dateStr) {
-  if (!dateStr) return '';
-  const d = new Date(dateStr);
-  if (isNaN(d)) return '';
-  const now = new Date();
-  const sameDay = d.toDateString() === now.toDateString();
-  const tomorrow = new Date(now); tomorrow.setDate(tomorrow.getDate() + 1);
-  const isTomorrow = d.toDateString() === tomorrow.toDateString();
-  const time = d.toLocaleTimeString([], { hour: 'numeric', minute: '2-digit' });
-  if (sameDay) return `Today, ${time}`;
-  if (isTomorrow) return `Tomorrow, ${time}`;
-  const dateLabel = d.toLocaleDateString([], { month: 'short', day: 'numeric' });
-  return `${dateLabel}, ${time}`;
-}
-// Build a human label for a date's nth-weekday-of-month, e.g. "2nd Tuesday"
-const _ORDINALS = ['1st', '2nd', '3rd', '4th', '5th'];
-const _DAYS = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'];
-function _nthWeekdayLabel(d) {
-  const n = Math.ceil(d.getDate() / 7); // 1..5
-  return `${_ORDINALS[n - 1] || `${n}th`} ${_DAYS[d.getDay()]}`;
-}
-function _isLastWeekdayOfMonth(d) {
-  const test = new Date(d);
-  test.setDate(d.getDate() + 7);
-  return test.getMonth() !== d.getMonth();
-}
-// Find the Nth occurrence of `weekday` in a given year/month. n=1..5.
-// If n=5 and there's no 5th occurrence, returns the 4th (so "5th Monday" still works).
-function _nthWeekdayOfMonth(year, month, weekday, n) {
-  const first = new Date(year, month, 1);
-  const offset = (weekday - first.getDay() + 7) % 7;
-  let day = 1 + offset + (n - 1) * 7;
-  // Last day of month
-  const lastDay = new Date(year, month + 1, 0).getDate();
-  if (day > lastDay) day -= 7;
-  return new Date(year, month, day, 0, 0, 0);
-}
-function _lastWeekdayOfMonth(year, month, weekday) {
-  const lastDay = new Date(year, month + 1, 0);
-  const back = (lastDay.getDay() - weekday + 7) % 7;
-  return new Date(year, month, lastDay.getDate() - back, 0, 0, 0);
-}
-
-// Snap a chosen datetime forward to the next slot matching a normalized
-// recurrence pattern (preserving time-of-day, strictly in the future).
-// Anchors to the user's chosen date when it's in the future (so picking a
-// recurrence on a far-future date doesn't drag it back to today); otherwise
-// anchors to "now". Returns null for daily/yearly/none.
-function _snapToRepeat(currentDate, normRepeat) {
-  const hh = currentDate.getHours();
-  const mm = currentDate.getMinutes();
-  const now = Date.now();
-  const anchor = currentDate.getTime() > now ? currentDate : new Date();
-  const parts = normRepeat.split(':');
-  const kind = parts[0];
-  if (kind === 'weekly') {
-    const targetWd = parseInt(parts[1], 10);
-    if (isNaN(targetWd)) return null;
-    const d = new Date(anchor.getFullYear(), anchor.getMonth(), anchor.getDate(), hh, mm, 0, 0);
-    const delta = (targetWd - d.getDay() + 7) % 7;
-    d.setDate(d.getDate() + delta);
-    if (d.getTime() <= now) d.setDate(d.getDate() + 7);
-    return d;
-  }
-  if (kind === 'monthly') {
-    const sub = parts[1];
-    let y = anchor.getFullYear();
-    let m = anchor.getMonth();
-    // Walk forward up to 14 months to find the next matching slot.
-    for (let tries = 0; tries < 14; tries++) {
-      let target;
-      if (sub === 'day') {
-        const wantDay = parseInt(parts[2], 10);
-        if (isNaN(wantDay)) return null;
-        const lastDay = new Date(y, m + 1, 0).getDate();
-        target = new Date(y, m, Math.min(wantDay, lastDay));
-      } else if (sub === 'nth') {
-        const n = parseInt(parts[2], 10);
-        const wd = parseInt(parts[3], 10);
-        if (isNaN(n) || isNaN(wd)) return null;
-        target = _nthWeekdayOfMonth(y, m, wd, n);
-      } else if (sub === 'last') {
-        const wd = parseInt(parts[2], 10);
-        if (isNaN(wd)) return null;
-        target = _lastWeekdayOfMonth(y, m, wd);
-      } else {
-        return null;
-      }
-      target.setHours(hh, mm, 0, 0);
-      if (target.getTime() > now && target.getTime() >= anchor.getTime()) return target;
-      m++;
-      if (m > 11) { m = 0; y++; }
-    }
-    return null;
-  }
-  return null;
-}
-
-// Render a repeat value as a human-readable label.
-// originalDate is required only to interpret legacy bare values ("weekly", "monthly", ...).
-// All call sites pass it; missing it would silently misinterpret legacy values.
-function _formatRepeatLabel(repeat, originalDate) {
-  if (!repeat || repeat === 'none') return '';
-  const norm = _normalizeRepeat(repeat, originalDate);
-  if (norm === 'daily') return 'Daily';
-  if (norm === 'yearly') return 'Yearly';
-  const parts = norm.split(':');
-  if (parts[0] === 'weekly') {
-    const wd = parseInt(parts[1], 10);
-    if (isNaN(wd)) return 'Weekly';
-    return `Weekly on ${_DAYS[wd]}s`;
-  }
-  if (parts[0] === 'monthly') {
-    if (parts[1] === 'day') return `Monthly on day ${parts[2]}`;
-    if (parts[1] === 'nth') {
-      const n = parseInt(parts[2], 10);
-      const wd = parseInt(parts[3], 10);
-      return `Monthly on ${_ORDINALS[n - 1] || `${n}th`} ${_DAYS[wd]}`;
-    }
-    if (parts[1] === 'last') {
-      const wd = parseInt(parts[2], 10);
-      return `Monthly on last ${_DAYS[wd]}`;
-    }
-  }
-  return norm;
-}
-
-// ---- Reminders ----
-
-function _loadFiredReminders() {
-  try { return new Set(JSON.parse(localStorage.getItem(REMINDER_FIRED_KEY) || '[]')); }
-  catch { return new Set(); }
-}
-
-function _saveFiredReminders(set) {
-  try { localStorage.setItem(REMINDER_FIRED_KEY, JSON.stringify([...set])); }
-  catch {}
-}
-
-async function _ensureNotificationPermission() {
-  if (!('Notification' in window)) return false;
-  if (Notification.permission === 'granted') return true;
-  if (Notification.permission === 'denied') return false;
-  try { const p = await Notification.requestPermission(); return p === 'granted'; }
-  catch { return false; }
-}
-
-// Repeat format:
-//   none
-//   daily
-//   weekly:W              W = 0-6 (Sun..Sat)
-//   monthly:day:D         D = 1-31 (calendar day)
-//   monthly:nth:N:W       N = 1-4 (1st..4th), W = 0-6 (weekday)
-//   monthly:last:W        W = 0-6 (last weekday of month)
-//   yearly
-// Legacy "weekly", "monthly", "monthly_nth_weekday", "monthly_last_weekday"
-// are normalized using the original due_date's weekday/Nth.
-function _normalizeRepeat(repeat, originalDate) {
-  if (!repeat || repeat === 'none') return 'none';
-  if (repeat === 'daily' || repeat === 'yearly') return repeat;
-  if (/^(weekly|monthly):/.test(repeat)) return repeat;
-  // Legacy bare values — derive params from the original date
-  const wd = originalDate.getDay();
-  const n = Math.ceil(originalDate.getDate() / 7);
-  if (repeat === 'weekly') return `weekly:${wd}`;
-  if (repeat === 'monthly') return `monthly:day:${originalDate.getDate()}`;
-  if (repeat === 'monthly_nth_weekday') return `monthly:nth:${n}:${wd}`;
-  if (repeat === 'monthly_last_weekday') return `monthly:last:${wd}`;
-  return repeat;
-}
-
-function _advanceRecurring(dateStr, repeat) {
-  const orig = new Date(dateStr);
-  const hh = orig.getHours();
-  const mm = orig.getMinutes();
-  let d = new Date(orig);
-  const norm = _normalizeRepeat(repeat, orig);
-  if (norm === 'none') return null;
-
-  function step() {
-    if (norm === 'daily') {
-      d.setDate(d.getDate() + 1);
-      return;
-    }
-    if (norm === 'yearly') {
-      d.setFullYear(d.getFullYear() + 1);
-      return;
-    }
-    const parts = norm.split(':');
-    const kind = parts[0];
-    if (kind === 'weekly') {
-      // Snap to the requested weekday in the next 1-7 days
-      const targetWd = parseInt(parts[1], 10);
-      let delta = (targetWd - d.getDay() + 7) % 7;
-      if (delta === 0) delta = 7;
-      d.setDate(d.getDate() + delta);
-      d.setHours(hh, mm, 0, 0);
-      return;
-    }
-    if (kind === 'monthly') {
-      const sub = parts[1];
-      const ny = d.getFullYear() + (d.getMonth() === 11 ? 1 : 0);
-      const nm = (d.getMonth() + 1) % 12;
-      let target;
-      if (sub === 'day') {
-        const wantDay = parseInt(parts[2], 10);
-        const lastDay = new Date(ny, nm + 1, 0).getDate();
-        target = new Date(ny, nm, Math.min(wantDay, lastDay));
-      } else if (sub === 'nth') {
-        const n = parseInt(parts[2], 10);
-        const wd = parseInt(parts[3], 10);
-        target = _nthWeekdayOfMonth(ny, nm, wd, n);
-      } else if (sub === 'last') {
-        const wd = parseInt(parts[2], 10);
-        target = _lastWeekdayOfMonth(ny, nm, wd);
-      } else {
-        d = null; return;
-      }
-      target.setHours(hh, mm, 0, 0);
-      d = target;
-      return;
-    }
-    d = null;
-  }
-
-  step();
-  if (d === null) return null;
-  const now = Date.now();
-  // Cap catch-up to avoid runaway on a malformed/very-old date.
-  let guard = 5000;
-  while (d.getTime() <= now) {
-    if (--guard <= 0) return null;
-    step();
-    if (d === null) return null;
-  }
-  return _toLocalDatetimeStr(d);
-}
-
-function _checkReminders() {
-  if (!_notes.length) return;
-  const now = Date.now();
-  const fired = _loadFiredReminders();
-  let changed = false;
-  for (const note of _notes) {
-    if (!note.due_date || note.archived) continue;
-    if (!_hasTimeComponent(note.due_date)) continue;
-    if (fired.has(note.id)) continue;
-    const due = new Date(note.due_date).getTime();
-    if (isNaN(due)) continue;
-    if (due <= now && due > now - 60000) {
-      _fireReminder(note);
-      // Recurring? advance the due_date instead of marking as fired
-      if (note.repeat && note.repeat !== 'none') {
-        const next = _advanceRecurring(note.due_date, note.repeat);
-        if (next) {
-          note.due_date = next;
-          _patchNote(note.id, { due_date: next }).catch(() => {});
-          // Don't add to fired — new due_date is in the future
-          continue;
-        }
-      }
-      fired.add(note.id);
-      changed = true;
-    } else if (due <= now - 60000) {
-      // Past, never seen — silently advance recurring or mark fired
-      if (note.repeat && note.repeat !== 'none') {
-        const next = _advanceRecurring(note.due_date, note.repeat);
-        if (next) {
-          note.due_date = next;
-          _patchNote(note.id, { due_date: next }).catch(() => {});
-          continue;
-        }
-      }
-      fired.add(note.id);
-      changed = true;
-    }
-  }
-  if (changed) _saveFiredReminders(fired);
-  // Always refresh badge — fired state may have changed visually without note mutation
-  _updateRailBadge();
-}
-
-function _fireReminder(note) {
-  const title = note.title || 'Note reminder';
-  // Include the verbatim note content so the email/notification actually
-  // shows what to do, not just a count. Cap the per-item lines (8 max) and
-  // total length so the body stays inbox-friendly.
-  let rawBody;
-  if (_hasItems(note)) {
-    const pending = (note.items || [])
-      .filter(i => !i.done && !i.checked)
-      .map(i => (i.text || '').trim())
-      .filter(Boolean);
-    if (pending.length) {
-      const shown = pending.slice(0, 8).map(t => `- ${t}`).join('\n');
-      const extra = pending.length > 8 ? `\n…and ${pending.length - 8} more` : '';
-      rawBody = `Pending (${pending.length}):\n${shown}${extra}`;
-    } else {
-      rawBody = `${(note.items || []).length} item${(note.items || []).length === 1 ? '' : 's'}`;
-    }
-  } else {
-    rawBody = (note.content || '').slice(0, 400);
-  }
-
-  // Ask the server to dispatch according to user settings. The server may
-  // return an LLM-written synthesis line and/or send an email. We still show
-  // a local browser notification so the user gets immediate feedback even if
-  // the server path is disabled or slow.
-  const showLocal = (body) => {
-    if ('Notification' in window && Notification.permission === 'granted') {
-      try {
-        const n = new Notification(title, { body, tag: 'note-' + note.id, icon: '/static/favicon.ico' });
-        n.onclick = () => { window.focus(); openPanel(); n.close(); };
-      } catch {}
-    }
-    if (uiModule?.showToast) uiModule.showToast(title);
-  };
-
-  // Fire-and-forget server dispatch. If synthesis comes back quickly enough,
-  // use it as the notification body; otherwise the local notification has
-  // already shown with the raw body.
-  let shown = false;
-  const timer = setTimeout(() => { if (!shown) { shown = true; showLocal(rawBody); } }, 1500);
-
-  fetch('/api/notes/fire-reminder', {
-    method: 'POST',
-    credentials: 'same-origin',
-    headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({ note_id: note.id, title, body: rawBody }),
-  })
-    .then(r => r.ok ? r.json() : null)
-    .then(data => {
-      clearTimeout(timer);
-      if (shown) return;
-      shown = true;
-      const body = (data && data.synthesis) ? data.synthesis : rawBody;
-      showLocal(body);
-    })
-    .catch(() => {
-      clearTimeout(timer);
-      if (!shown) { shown = true; showLocal(rawBody); }
-    });
-
-  // Pulse the card if visible; otherwise queue it so the next time the user
-  // opens the notes panel the card gets a brief glow.
-  _setReminderCardGlow(note.id, true);
-  const card = document.querySelector(`.note-card[data-note-id="${note.id}"]`);
-  if (card) {
-    card.classList.add('note-card-reminder-fired');
-    setTimeout(() => card.classList.remove('note-card-reminder-fired'), 3000);
-  } else {
-    _queuePendingHighlight(note.id);
-  }
-}
-
-function _startReminderLoop() {
-  if (_reminderTimer) return;
-  _reminderTimer = setInterval(_checkReminders, 30000);
-  _checkReminders(); // run once immediately
-}
-
-function _countDueReminders() {
-  return _notes.filter(n => !n.archived && _isDueTodayOrOverdue(n.due_date) && !_isNoteFullyDone(n)).length;
-}
-
-let _firedDotDismissedAt = (() => {
-  try {
-    const v = parseInt(localStorage.getItem(REMINDER_DISMISSED_AT_KEY) || '0', 10);
-    return Number.isFinite(v) && v > 0 ? v : 0;
-  } catch { return 0; }
-})();
-
-function _countFiredReminders() {
-  // Reminders whose time has actually passed (not just date-today),
-  // and which fired after the last user dismissal.
-  const now = Date.now();
-  return _notes.filter(n => {
-    if (n.archived || _isNoteFullyDone(n)) return false;
-    if (!n.due_date || !_hasTimeComponent(n.due_date)) return false;
-    const t = new Date(n.due_date).getTime();
-    if (isNaN(t) || t > now) return false;
-    return t > _firedDotDismissedAt;
-  }).length;
-}
-
-export function dismissFiredReminderDot() {
-  _firedDotDismissedAt = Date.now();
-  try { localStorage.setItem(REMINDER_DISMISSED_AT_KEY, String(_firedDotDismissedAt)); } catch {}
-  _updateRailBadge();
-}
-
-function _updateRailBadge() {
-  const fired = _countFiredReminders();
-  // Rail (mini sidebar) — only show the count when reminders have ACTUALLY
-  // fired since the last dismissal (i.e. you haven't opened notes yet).
-  // Showing every overdue note forever made the badge feel permanent.
-  const railBtn = document.getElementById('rail-notes');
-  if (railBtn) {
-    let badge = railBtn.querySelector('.rail-notes-badge');
-    if (fired > 0) {
-      if (!badge) {
-        badge = document.createElement('span');
-        badge.className = 'rail-notes-badge';
-        railBtn.appendChild(badge);
-      }
-      badge.textContent = fired > 99 ? '99+' : String(fired);
-      badge.classList.add('fired');
-    } else if (badge) {
-      badge.remove();
-    }
-  }
-  // Main sidebar button
-  const sidebarBtn = document.getElementById('tool-notes-btn');
-  if (sidebarBtn) {
-    let dot = sidebarBtn.querySelector('.tool-notes-dot');
-    if (fired > 0) {
-      if (!dot) {
-        dot = document.createElement('span');
-        dot.className = 'tool-notes-dot';
-        const newNoteBtn = sidebarBtn.querySelector('#notes-new-note-btn');
-        sidebarBtn.insertBefore(dot, newNoteBtn || null);
-      }
-    } else if (dot) {
-      dot.remove();
-    }
-  }
-  // Individual note cards — pulse ones with fired reminders
-  document.querySelectorAll('.note-card').forEach(card => {
-    const id = card.dataset.noteId;
-    const note = _notes.find(n => n.id === id);
-    if (!note || note.archived || _isNoteFullyDone(note)) {
-      card.classList.remove('note-card-reminder-due');
-      return;
-    }
-    if (note.due_date && _hasTimeComponent(note.due_date)) {
-      const t = new Date(note.due_date).getTime();
-      card.classList.toggle('note-card-reminder-due', !isNaN(t) && t <= Date.now());
-    } else {
-      card.classList.remove('note-card-reminder-due');
-    }
-  });
-}
-
-export async function refreshDueBadge(opts = {}) {
-  // Usually lightweight, but callers that just created a note reminder can
-  // force a refresh so the background reminder loop sees it immediately.
-  if (opts.force || _notes.length === 0) {
-    try {
-      const wasArchived = _showingArchived;
-      _showingArchived = false;
-      await _fetchNotes();
-      _showingArchived = wasArchived;
-    } catch {}
-  }
-  _updateRailBadge();
-}
-
-// ---- Panel ----
-
-export function openPanel() {
-  if (_open) {
-    _bringNotesToFront();
-    return;
-  }
-  // Notes and the document editor occupy the same primary workspace. Preserve
-  // an open document as a dock chip instead of allowing the two panes to stack
-  // into a broken layout (or closing the user's document outright).
-  try {
-    if (window.documentModule?.isPanelOpen?.()) {
-      window.documentModule.closePanel('down');
-    }
-  } catch (_) {}
-  _open = true;
-  _editingId = null;
-  _searchQuery = '';
-  _clearViewedReminderGlows();
-  _firedDotDismissedAt = Date.now();
-  try { localStorage.setItem(REMINDER_DISMISSED_AT_KEY, String(_firedDotDismissedAt)); } catch {}
-
-  const container = document.getElementById('chat-container');
-  if (!container) return;
-
-  document.body.classList.add('notes-view');
-
-  // On mobile the notes panel takes the whole screen — auto-close the
-  // sidebar so the panel isn't cropped underneath it.
-  if (window.innerWidth <= 768) {
-    const sb = document.getElementById('sidebar');
-    if (sb) sb.classList.add('hidden');
-    document.body.classList.add('sidebar-collapsed');
-  }
-  // Mobile mode: tiles become read-only previews (no inline checkbox /
-  // edit / archive / etc.), tap opens a fullscreen edit overlay,
-  // long-press enters drag-to-reorder mode. See _bindCardEvents +
-  // .notes-mobile-mode CSS rules.
-  if (_isNotesMobileMode()) document.body.classList.add('notes-mobile-mode');
-
-  // Toggle button state
-  const btn = document.getElementById('tool-notes-btn');
-  if (btn) btn.classList.add('active');
-
-  // Create panel
-  const pane = document.createElement('div');
-  pane.id = 'notes-pane';
-  pane.className = 'notes-pane';
-  pane.innerHTML = `
-    <div class="notes-mobile-grabber" id="notes-mobile-grabber" aria-hidden="true"></div>
-    <div class="notes-pane-header">
-      <h4 class="notes-pane-title"><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" style="vertical-align:-2.5px;margin-right:6px"><path d="M5 3h10l4 4v14H5z"/><path d="M15 3v5h5"/><path d="M8 17.5 15.5 10l2.5 2.5L10.5 20H8z"/></svg>Notes</h4>
-      <span style="flex:1"></span>
-      <button id="notes-archive-toggle" class="doc-action-icon-btn notes-header-text-btn" title="View archive" style="opacity:0.8;gap:5px;">
-        <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="2" y="3" width="20" height="5" rx="1"/><path d="M4 8v11a2 2 0 002 2h12a2 2 0 002-2V8"/><path d="M10 12h4"/></svg>
-        <span class="notes-header-btn-label">Archive</span>
-      </button>
-      <button id="notes-view-toggle" class="doc-action-icon-btn notes-header-text-btn" title="Toggle view" style="opacity:0.8;gap:5px;">
-        <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="3" y="3" width="7" height="7"/><rect x="14" y="3" width="7" height="7"/><rect x="3" y="14" width="7" height="7"/><rect x="14" y="14" width="7" height="7"/></svg>
-        <span class="notes-header-btn-label">Toggle</span>
-      </button>
-      <button id="notes-minimize-btn" class="modal-minimize-btn" title="Minimize" aria-label="Minimize notes" style="position:relative;left:2px;"><svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="3.4" stroke-linecap="round" aria-hidden="true"><line x1="6" y1="18" x2="18" y2="18"/></svg></button>
-    </div>
-    <div class="notes-search-bar">
-      <input type="text" id="notes-search" class="memory-search-input" placeholder="Search notes…" autocomplete="off" />
-      <button id="notes-select-btn" class="notes-select-trigger" type="button">Select</button>
-    </div>
-    <div id="notes-bulk-bar" class="memory-bulk-bar hidden">
-      <label class="memory-bulk-check-all"><input type="checkbox" id="notes-select-all" /> All</label>
-      <span id="notes-selected-count">0 Selected</span>
-      <span style="flex:1"></span>
-      <button id="notes-send-agent" class="memory-toolbar-btn" disabled><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" style="vertical-align:-2px;margin-right:5px;opacity:0.6"><path d="M14.7 6.3a1 1 0 0 0 0 1.4l1.6 1.6a1 1 0 0 0 1.4 0l3.77-3.77a6 6 0 0 1-7.94 7.94l-6.91 6.91a2.12 2.12 0 0 1-3-3l6.91-6.91a6 6 0 0 1 7.94-7.94l-3.76 3.76z"></path></svg>Send to Agent</button>
-      <button id="notes-bulk-archive" class="memory-toolbar-btn" disabled>
-        <svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" style="vertical-align:-2px;margin-right:4px;"><rect x="2" y="3" width="20" height="5" rx="1"/><path d="M4 8v11a2 2 0 002 2h12a2 2 0 002-2V8"/><path d="M10 12h4"/></svg>Archive
-      </button>
-      <button id="notes-bulk-delete" class="memory-toolbar-btn danger" disabled>
-        <svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" style="vertical-align:-2px;margin-right:4px;"><polyline points="3 6 5 6 21 6"/><path d="M19 6l-1 14a2 2 0 0 1-2 2H8a2 2 0 0 1-2-2L5 6"/><path d="M8 6V4a2 2 0 0 1 2-2h4a2 2 0 0 1 2 2v2"/><line x1="10" y1="11" x2="10" y2="17"/><line x1="14" y1="11" x2="14" y2="17"/></svg>Delete
-      </button>
-      <button id="notes-bulk-cancel" class="memory-toolbar-btn active" title="Cancel selection" aria-label="Cancel selection">
-        <svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"><line x1="18" y1="6" x2="6" y2="18"/><line x1="6" y1="6" x2="18" y2="18"/></svg>
-      </button>
-    </div>
-    <div class="notes-pane-body"></div>
-  `;
-
-  // On mobile open as a full-screen bottom sheet (slide up), not the desktop
-  // side panel. Set inline so it wins over the base .notes-pane rule regardless
-  // of cascade specifics (the CSS @media override wasn't reliably applying,
-  // which left it as a side panel squeezing the chat).
-  if (window.innerWidth <= 768) {
-    pane.style.position = 'fixed';
-    pane.style.inset = '0';
-    pane.style.width = '100%';
-    pane.style.maxWidth = '100%';
-    pane.style.zIndex = '170';
-    pane.style.borderRadius = '14px 14px 0 0';
-    pane.style.animation = 'sheet-enter 0.25s cubic-bezier(0.2, 0.8, 0.2, 1) both';
-    pane.style.transformOrigin = 'bottom center';
-  }
-
-  // Mount on body so Notes can behave like the other draggable windows. On
-  // desktop it is immediately docked to the right by _restoreNotesSidebarDock.
-  const backdrop = document.createElement('div');
-  backdrop.className = 'notes-pane-backdrop';
-  backdrop.id = 'notes-pane-backdrop';
-  backdrop.addEventListener('click', (ev) => {
-    if (ev.target === backdrop) closePanel('down');
-  });
-  backdrop.appendChild(pane);
-  document.body.appendChild(backdrop);
-  _wireNotesWindow(pane);
-  _restoreNotesSidebarDock(pane);
-  _bringNotesToFront(pane);
-
-  // Events
-  // (Close chevron removed — swipe down on mobile, tool-rail toggle on desktop.)
-
-  // Mobile: swipe the grab handle / header down to dismiss (minimise to chip).
-  // Mirrors the document sheet gesture — finger-following, velocity-based
-  // dismiss, rubber-band on up-drag, spring snap-back.
-  _wireNotesSwipeDismiss(pane.querySelector('.notes-mobile-grabber'), pane);
-  _wireNotesSwipeDismiss(pane.querySelector('.notes-pane-header'), pane);
-
-  pane.addEventListener('pointerdown', () => _bringNotesToFront(pane), true);
-  pane.addEventListener('focusin', () => _bringNotesToFront(pane), true);
-
-  const minBtn = document.getElementById('notes-minimize-btn');
-  if (minBtn) minBtn.addEventListener('click', (e) => {
-    e.preventDefault();
-    e.stopPropagation();
-    closePanel('down');
-  });
-  // Search
-  const searchEl = document.getElementById('notes-search');
-  if (searchEl) {
-    searchEl.addEventListener('input', () => {
-      _searchQuery = searchEl.value.trim().toLowerCase();
-      _renderNotes();
-    });
-  }
-
-  // View toggle
-  const archiveBtn = document.getElementById('notes-archive-toggle');
-  if (archiveBtn) {
-    const ARCHIVE_ICON = '<svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="2" y="3" width="20" height="5" rx="1"/><path d="M4 8v11a2 2 0 002 2h12a2 2 0 002-2V8"/><path d="M10 12h4"/></svg><span class="notes-header-btn-label">Archive</span>';
-    const CLOSE_ICON   = '<svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.4" stroke-linecap="round" stroke-linejoin="round"><line x1="6" y1="6" x2="18" y2="18"/><line x1="18" y1="6" x2="6" y2="18"/></svg><span class="notes-header-btn-label">Archive</span>';
-    const syncArchiveBtn = () => {
-      archiveBtn.classList.toggle('active', _showingArchived);
-      archiveBtn.title = _showingArchived ? 'Exit archive' : 'View archive';
-      archiveBtn.style.opacity = _showingArchived ? '1' : '0.8';
-      // Swap to an X while in archive view so it doubles as a close-back-
-      // to-active-notes toggle.
-      archiveBtn.innerHTML = _showingArchived ? CLOSE_ICON : ARCHIVE_ICON;
-      // Tint the whole pane so it's obvious you're not in the active list.
-      pane.classList.toggle('notes-pane-archive', _showingArchived);
-    };
-    syncArchiveBtn();
-    archiveBtn.addEventListener('click', async () => {
-      _showingArchived = !_showingArchived;
-      _selectedIds.clear();
-      syncArchiveBtn();
-      // Brief fade so the body content swap doesn't snap — the bg-tint
-      // change is already eased by CSS transitions on .notes-pane*.
-      const _bodyEl = document.querySelector('#notes-pane .notes-pane-body');
-      if (_bodyEl) {
-        _bodyEl.style.transition = 'opacity 0.18s ease';
-        _bodyEl.style.opacity = '0.25';
-      }
-      await _fetchNotes();
-      _renderNotes();
-      if (_bodyEl) {
-        requestAnimationFrame(() => {
-          _bodyEl.style.opacity = '';
-          _bodyEl.addEventListener('transitionend', () => { _bodyEl.style.transition = ''; }, { once: true });
-        });
-      }
-    });
-  }
-  const viewBtn = document.getElementById('notes-view-toggle');
-  if (viewBtn) {
-    pane.classList.toggle('notes-view-grid', _viewMode === 'grid');
-    // Label shows what you'll switch TO — "Grid" while in list, "List" while in grid.
-    const _setViewLabel = () => {
-      const lbl = viewBtn.querySelector('.notes-header-btn-label');
-      if (lbl) lbl.textContent = _viewMode === 'grid' ? 'List' : 'Grid';
-    };
-    _setViewLabel();
-    requestAnimationFrame(() => _applyMasonry(document.querySelector('#notes-pane .notes-pane-body')));
-    viewBtn.addEventListener('click', () => {
-      _viewMode = _viewMode === 'grid' ? 'list' : 'grid';
-      try { localStorage.setItem('odysseus-notes-view', _viewMode); } catch {}
-      pane.classList.toggle('notes-view-grid', _viewMode === 'grid');
-      _setViewLabel();
-      requestAnimationFrame(() => _applyMasonry(document.querySelector('#notes-pane .notes-pane-body')));
-    });
-  }
-  // Select mode
-  document.getElementById('notes-select-btn').addEventListener('click', () => {
-    if (_selectMode) _exitSelectMode(); else _enterSelectMode();
-  });
-  // Esc cancels select mode. Notes uses a toggle "Select" button rather
-  // than a *-bulk-cancel button, so the global Esc-cancel handler in
-  // keyboard-shortcuts.js can't reach it — handle it here. Capture phase
-  // + stopPropagation so Esc cancels select instead of closing the panel.
-  if (_notesSelectEscHandler) {
-    document.removeEventListener('keydown', _notesSelectEscHandler, true);
-  }
-  _notesSelectEscHandler = (e) => {
-    if (e.key === 'Escape' && _selectMode) {
-      e.preventDefault();
-      e.stopPropagation();
-      _exitSelectMode();
-    }
-  };
-  document.addEventListener('keydown', _notesSelectEscHandler, true);
-  document.getElementById('notes-select-all').addEventListener('change', (e) => {
-    if (e.target.checked) _notes.forEach(n => _selectedIds.add(n.id));
-    else _selectedIds.clear();
-    _renderNotes();
-    _updateBulkBar();
-  });
-  document.getElementById('notes-send-agent').addEventListener('click', async () => {
-    const ids = [..._selectedIds];
-    if (!ids.length) return;
-    const detail = { noteIds: ids, accepted: false };
-    window.dispatchEvent(new CustomEvent('odysseus:notes-context-selected', { detail }));
-    if (!detail.accepted) {
-      uiModule.showToast('Choose a chat or model before attaching notes');
-      return;
-    }
-    _exitSelectMode();
-  })
-  document.getElementById('notes-bulk-archive').addEventListener('click', async () => {
-    const ids = [..._selectedIds];
-    if (!ids.length) return;
-    await Promise.all(ids.map(id => _patchNote(id, { archived: true }).catch(() => {})));
-    _exitSelectMode();
-    await _fetchNotes();
-    _renderNotes();
-    uiModule.showToast(`Archived ${ids.length}`);
-  });
-  document.getElementById('notes-bulk-delete').addEventListener('click', async () => {
-    const ids = [..._selectedIds];
-    if (!ids.length) return;
-    if (uiModule && uiModule.styledConfirm) {
-      const ok = await uiModule.styledConfirm(`Delete ${ids.length} note${ids.length === 1 ? '' : 's'}?`, { confirmText: 'Delete', danger: true });
-      if (!ok) return;
-    }
-    await Promise.all(ids.map(id => _deleteNoteApi(id).catch(() => {})));
-    _exitSelectMode();
-    await _fetchNotes();
-    _renderNotes();
-    uiModule.showToast(`Deleted ${ids.length}`);
-  });
-  document.getElementById('notes-bulk-cancel').addEventListener('click', _exitSelectMode);
-  // Escape: exit select mode first (if active), otherwise close the panel.
-  // Skip when the user is editing a form field — those have their own
-  // ESC-to-cancel handlers and we don't want to nuke the whole panel
-  // mid-edit.
-  // Idempotent: remove any previous handler from a prior openPanel so
-  // re-opening doesn't stack multiple handlers.
-  if (_notesKeydownHandler) {
-    document.removeEventListener('keydown', _notesKeydownHandler);
-    _notesKeydownHandler = null;
-  }
-  _notesKeydownHandler = (e) => {
-    if (!_open) return;
-    const t = e.target;
-    const inField = t && (t.tagName === 'INPUT' || t.tagName === 'TEXTAREA' || t.isContentEditable);
-    // Ctrl/Cmd+Z anywhere in the panel — undo the last note action. Skip when
-    // typing in a field so the browser's normal text-undo still works.
-    if ((e.ctrlKey || e.metaKey) && (e.key === 'z' || e.key === 'Z') && !e.shiftKey) {
-      if (inField) return;
-      if (_undoStack.length === 0) return;
-      e.preventDefault();
-      _popAndRunUndo();
-      return;
-    }
-    // Ctrl/Cmd+C while hovering a note card → copy that note. Skip when the
-    // user is editing or has an active text selection (let the browser handle
-    // a real text copy in that case).
-    if ((e.ctrlKey || e.metaKey) && (e.key === 'c' || e.key === 'C') && !e.shiftKey && !e.altKey) {
-      if (inField) return;
-      const sel = window.getSelection?.();
-      if (sel && sel.toString && sel.toString().length > 0) return;
-      const hovered = document.querySelector('.note-card:hover');
-      if (!hovered) return;
-      const id = hovered.dataset.noteId;
-      if (!id) return;
-      e.preventDefault();
-      // Flash the ⋯ menu button (copy now lives in that menu).
-      const btn = hovered.querySelector('.note-card-corner-menu');
-      _copyNote(id, btn);
-      return;
-    }
-    if (e.key !== 'Escape') return;
-    if (inField) return;
-    if (_selectMode) { _exitSelectMode(); return; }
-    if (_showingArchived) {
-      // Mirror the archive toggle button: flip back to active notes.
-      document.getElementById('notes-archive-toggle')?.click();
-      return;
-    }
-    _forceCloseNotesPanel();
-  };
-  document.addEventListener('keydown', _notesKeydownHandler);
-
-  // Load — show skeleton immediately, then fetch
-  _renderLoadingSkeleton();
-  // Defer the highlight flush to the next frame so it runs *after* the cards
-  // are committed to the DOM (and any FLIP animations have settled), giving
-  // the querySelector lookups inside something to find.
-  _fetchNotes().then(() => {
-    _renderNotes();
-    requestAnimationFrame(() => _flushPendingHighlights());
-    _startReminderLoop();
-    _showNotesFirstOpenHint(pane);
-  });
-}
-
-function _renderLoadingSkeleton() {
-  const body = document.querySelector('#notes-pane .notes-pane-body');
-  if (!body) return;
-  body.innerHTML = '';
-  _renderLabelsInto(body);
-  _renderQuickAdd(body);
-  const skel = document.createElement('div');
-  skel.className = 'notes-skeleton';
-  skel.innerHTML = `
-    <div class="notes-skeleton-card"></div>
-    <div class="notes-skeleton-card"></div>
-    <div class="notes-skeleton-card short"></div>
-    <div class="notes-skeleton-card"></div>
-  `;
-  body.appendChild(skel);
-}
-
-function _enterSelectMode(initialId = null) {
-  _selectMode = true;
-  _selectedIds.clear();
-  if (initialId) _selectedIds.add(initialId);
-  const bar = document.getElementById('notes-bulk-bar');
-  const btn = document.getElementById('notes-select-btn');
-  if (bar) bar.classList.remove('hidden');
-  if (btn) { btn.classList.add('active'); btn.textContent = 'Cancel'; }
-  _renderNotes();
-  _updateBulkBar();
-}
-
-function _exitSelectMode() {
-  _selectMode = false;
-  _selectedIds.clear();
-  const bar = document.getElementById('notes-bulk-bar');
-  const btn = document.getElementById('notes-select-btn');
-  const all = document.getElementById('notes-select-all');
-  if (bar) bar.classList.add('hidden');
-  if (btn) { btn.classList.remove('active'); btn.textContent = 'Select'; }
-  if (all) all.checked = false;
-  _renderNotes();
-}
-
-function _updateBulkBar() {
-  const count = _selectedIds.size;
-  const countEl = document.getElementById('notes-selected-count');
-  const sendAgentBtn = document.getElementById('notes-send-agent');
-  const archiveBtn = document.getElementById('notes-bulk-archive');
-  const deleteBtn = document.getElementById('notes-bulk-delete');
-  const allEl = document.getElementById('notes-select-all');
-  if (countEl) countEl.textContent = `${count} Selected`;
-  if (sendAgentBtn) sendAgentBtn.disabled = count === 0;
-  if (archiveBtn) archiveBtn.disabled = count === 0;
-  if (deleteBtn) deleteBtn.disabled = count === 0;
-  if (allEl) allEl.checked = _notes.length > 0 && _notes.every(n => _selectedIds.has(n.id));
-  // Toggle select-mode class so todo dots don't react to hover
-  const pane = document.getElementById('notes-pane');
-  if (pane) pane.classList.toggle('notes-select-mode', count > 0);
-}
-
-// A note's label field may hold multiple space-separated tags. Split + dedupe.
-function _noteTags(n) {
-  const tags = [];
-  if (n?.label) tags.push(...n.label.trim().split(/\s+/).filter(Boolean));
-  if (n?.due_date && _hasTimeComponent(n.due_date)) tags.push('reminder');
-  return [...new Set(tags.map(t => t.replace(/^#+/, '').trim()).filter(Boolean))];
-}
-
-function _visibleNoteTags(n) {
-  return _noteTags(n).filter(t => t !== 'reminder');
-}
-
-function _isPastReminder(n) {
-  if (!n?.due_date || !_hasTimeComponent(n.due_date)) return false;
-  const due = new Date(n.due_date).getTime();
-  return !isNaN(due) && due <= Date.now();
-}
-
-async function _clearPastReminders() {
-  const targets = _notes.filter(n => !n.archived && _isPastReminder(n));
-  if (!targets.length) {
-    uiModule.showToast?.('No past reminders to clear');
-    return;
-  }
-  const ok = uiModule?.styledConfirm
-    ? await uiModule.styledConfirm(`Delete ${targets.length} past reminder${targets.length === 1 ? '' : 's'}?`, { confirmText: 'Delete', danger: true })
-    : confirm(`Delete ${targets.length} past reminder${targets.length === 1 ? '' : 's'}?`);
-  if (!ok) return;
-  await Promise.all(targets.map(n => _deleteNoteApi(n.id).catch(() => {})));
-  await _fetchNotes();
-  _renderNotes();
-  uiModule.showToast?.(`Cleared ${targets.length} past reminder${targets.length === 1 ? '' : 's'}`);
-}
-
-function _renderLabels(root = document) {
-  const bar = root.querySelector?.('.notes-labels-bar') || document.querySelector('.notes-labels-bar');
-  if (!bar) return;
-  if (_labelsCollapsed) {
-    bar.innerHTML = '';
-    bar.style.display = 'none';
-    return;
-  }
-  const visibleNotes = _userVisibleNotes();
-  const labels = new Set();
-  for (const n of visibleNotes) for (const t of _visibleNoteTags(n)) labels.add(t);
-  const sortedLabels = [...labels].sort();
-  // Count active reminders (not archived, has datetime due_date)
-  const reminderCount = visibleNotes.filter(n => !n.archived && n.due_date && _hasTimeComponent(n.due_date)).length;
-  const pastReminderCount = visibleNotes.filter(n => !n.archived && _isPastReminder(n)).length;
-  const defaultCount = visibleNotes.filter(n => !n.archived && _visibleNoteTags(n).length === 0).length;
-  // Active goals = non-archived goal notes. Today view lists pending steps
-  // from each, so we surface the count next to the chip.
-  const goalCount = visibleNotes.filter(n => n.note_type === 'goal' && !n.archived).length;
-  const todayCount = visibleNotes.filter(n => n.note_type === 'goal' && !n.archived && _nextGoalStep(n)).length;
-  const hasUsefulFilters = sortedLabels.length > 0 || reminderCount > 0 || goalCount > 0;
-  const hasActiveFilter = _activeLabel !== null || _activeFilter !== null;
-  if (!hasUsefulFilters && !hasActiveFilter) {
-    bar.innerHTML = '';
-    bar.style.display = 'none';
-    return;
-  }
-  bar.style.display = '';
-  const allActive = _activeLabel === null && _activeFilter === null;
-  let html = `<button class="notes-label-chip${allActive ? ' active' : ''}" data-action="all">All</button>`;
-  html += `<button class="notes-label-chip${_activeFilter === 'default' ? ' active' : ''}" data-action="default" title="Show notes without tags">Default <span class="notes-label-chip-count">${defaultCount}</span></button>`;
-  if (todayCount > 0) {
-    const isOn = _activeFilter === 'today';
-    const icon = '<svg width="10" height="10" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round" style="vertical-align:-1px;margin-right:2px"><rect x="3" y="4" width="18" height="18" rx="2"/><line x1="16" y1="2" x2="16" y2="6"/><line x1="8" y1="2" x2="8" y2="6"/><line x1="3" y1="10" x2="21" y2="10"/></svg>';
-    html += `<button class="notes-label-chip notes-label-chip-today${isOn ? ' active' : ''}" data-action="today" title="Next step from every goal">${icon}Today <span class="notes-label-chip-count">${todayCount}</span></button>`;
-  }
-  if (goalCount > 0) {
-    const isOn = _activeFilter === 'goals';
-    const icon = '<svg width="10" height="10" viewBox="0 0 24 24" fill="currentColor" style="vertical-align:-1px;margin-right:2px"><path d="M12 0L14.59 8.41L23 12L14.59 15.59L12 24L9.41 15.59L1 12L9.41 8.41Z"/></svg>';
-    html += `<button class="notes-label-chip notes-label-chip-goals${isOn ? ' active' : ''}" data-action="goals" title="Show only goals">${icon}Goals <span class="notes-label-chip-count">${goalCount}</span></button>`;
-  }
-  const isReminderOn = _activeFilter === 'reminders';
-  const isReminderOff = _activeFilter === 'no-reminders';
-  const reminderCls = `notes-label-chip notes-label-chip-reminders${isReminderOn ? ' active' : ''}${isReminderOff ? ' active negated' : ''}`;
-  const reminderIcon = isReminderOff
-    // bell-off icon
-    ? '<svg width="10" height="10" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round" style="vertical-align:-1px;margin-right:2px"><path d="M13.73 21a2 2 0 0 1-3.46 0"/><path d="M18.63 13A17.89 17.89 0 0 1 18 8"/><path d="M6.26 6.26A5.86 5.86 0 0 0 6 8c0 7-3 9-3 9h14"/><path d="M18 8a6 6 0 0 0-9.33-5"/><line x1="1" y1="1" x2="23" y2="23"/></svg>'
-    : '<svg width="10" height="10" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round" style="vertical-align:-1px;margin-right:2px"><path d="M18 8A6 6 0 0 0 6 8c0 7-3 9-3 9h18s-3-2-3-9"/><path d="M13.73 21a2 2 0 0 1-3.46 0"/></svg>';
-  html += `<button class="${reminderCls}" data-action="reminders" title="${isReminderOn ? 'Showing only reminders — click to show all' : isReminderOff ? 'Hiding reminders — click to show only reminders' : 'Click to filter reminders'}">${reminderIcon}Reminders <span class="notes-label-chip-count">${reminderCount}</span></button>`;
-  const showingReminders = _activeFilter === 'reminders';
-  if (showingReminders && pastReminderCount > 0) {
-    html += `<button class="notes-label-chip notes-label-clear-past" data-action="clear-past-reminders" title="Delete reminders whose time has passed"><svg width="10" height="10" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.4" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><polyline points="3 6 5 6 21 6"/><path d="M19 6l-1 14a2 2 0 0 1-2 2H8a2 2 0 0 1-2-2L5 6"/><path d="M8 6V4a2 2 0 0 1 2-2h4a2 2 0 0 1 2 2v2"/></svg>Clear past <span class="notes-label-chip-count">${pastReminderCount}</span></button>`;
-  }
-  for (const lbl of sortedLabels) {
-    html += `<button class="notes-label-chip${_activeLabel === lbl ? ' active' : ''}" data-label="${_esc(lbl)}">#${_esc(lbl)}</button>`;
-  }
-  bar.innerHTML = html;
-  bar.querySelectorAll('.notes-label-chip').forEach(chip => {
-    chip.addEventListener('click', () => {
-      if (chip.dataset.action === 'all') {
-        _activeLabel = null;
-        _activeFilter = null;
-      } else if (chip.dataset.action === 'today') {
-        _activeLabel = null;
-        _activeFilter = (_activeFilter === 'today') ? null : 'today';
-      } else if (chip.dataset.action === 'goals') {
-        _activeLabel = null;
-        _activeFilter = (_activeFilter === 'goals') ? null : 'goals';
-      } else if (chip.dataset.action === 'default') {
-        _activeLabel = null;
-        _activeFilter = (_activeFilter === 'default') ? null : 'default';
-      } else if (chip.dataset.action === 'reminders') {
-        _activeLabel = null;
-        // Cycle: null → reminders → null → no-reminders → null → reminders → ...
-        if (_activeFilter === null) {
-          _activeFilter = _reminderChipNext;
-          _reminderChipNext = (_reminderChipNext === 'reminders') ? 'no-reminders' : 'reminders';
-        } else {
-          _activeFilter = null;
-        }
-      } else if (chip.dataset.action === 'clear-past-reminders') {
-        _clearPastReminders();
-        return;
-      } else {
-        _activeFilter = null;
-        _activeLabel = chip.dataset.label || null;
-      }
-      _renderNotes();
-    });
-  });
-}
-
-function _renderLabelsInto(_body) {
-  if (!_body) return;
-  const pane = _body.closest('.notes-pane');
-  const toggleHost = pane?.querySelector('.notes-search-bar') || _body;
-  let toggle = toggleHost.querySelector(':scope > .notes-label-toggle');
-  if (!toggle) {
-    toggle = document.createElement('button');
-    toggle.type = 'button';
-    toggle.className = 'notes-label-toggle cal-filter-toggle';
-    toggle.addEventListener('click', () => {
-      _labelsCollapsed = !_labelsCollapsed;
-      try { localStorage.setItem(NOTES_LABELS_COLLAPSED_KEY, _labelsCollapsed ? '1' : '0'); } catch {}
-      _renderNotes();
-    });
-    const selectButton = toggleHost.querySelector('#notes-select-btn');
-    toggleHost.insertBefore(toggle, selectButton || null);
-  }
-  toggle.textContent = _labelsCollapsed ? '+ Tags' : '− Tags';
-  toggle.title = _labelsCollapsed ? 'Show tags' : 'Hide tags';
-  toggle.setAttribute('aria-expanded', _labelsCollapsed ? 'false' : 'true');
-
-  // The shared chip scroller wraps this row once it is mounted.
-  let bar = _body.querySelector('.notes-labels-bar');
-  if (!bar) {
-    bar = document.createElement('div');
-    bar.className = 'notes-labels-bar';
-    _body.appendChild(bar);
-  }
-  _renderLabels(_body);
-}
-
-function _ensureNotesChipRegistered() {
-  if (Modals.isRegistered('notes-panel')) return;
-  Modals.register('notes-panel', {
-    railBtnId: 'rail-notes',
-    sidebarBtnId: 'tool-notes-btn',
-    restoreFn: () => { openPanel(); },
-    closeFn: () => { _forceCloseNotesPanel(); },
-  });
-}
-
-// `direction === 'down'` (mobile swipe-down) MINIMIZES the panel to a
-// dock chip instead of fully closing — tapping the chip reopens it.
-// Any other call (close button, programmatic) is a full close.
-export function closePanel(direction) {
-  if (!_open) return;
-  _open = false;
-  _editingId = null;
-  _clearViewedReminderGlows();
-  const _minimize = direction === 'down';
-  if (_minimize) {
-    _ensureNotesChipRegistered();
-  } else if (Modals.isRegistered('notes-panel')) {
-    Modals.unregister('notes-panel');
-  }
-
-  // Drop the document keydown listener and the 30s reminder interval —
-  // both leaked across open/close cycles in the v2 review.
-  if (_notesKeydownHandler) {
-    document.removeEventListener('keydown', _notesKeydownHandler);
-    _notesKeydownHandler = null;
-  }
-  if (_notesSelectEscHandler) {
-    document.removeEventListener('keydown', _notesSelectEscHandler, true);
-    _notesSelectEscHandler = null;
-  }
-  if (_reminderTimer) {
-    clearInterval(_reminderTimer);
-    _reminderTimer = null;
-  }
-
-  document.body.classList.remove('notes-view');
-  document.body.classList.remove('notes-mobile-mode');
-  document.body.classList.remove('notes-drag-mode');
-  // Closing the panel should PRESERVE in-progress edits, not drop them.
-  // Commit any open in-place editor, and close the mobile fullscreen
-  // overlay with save=true so the note is persisted.
-  try { _commitOpenInPlaceEditor(); } catch {}
-  _closeMobileFullscreenEdit({ save: true });
-  // /notes route may have collapsed the wide sidebar to a rail; restore.
-  try { window._restoreSidebarIfRouteCollapsed?.(); } catch (_) {}
-
-  const btn = document.getElementById('tool-notes-btn');
-  if (btn) btn.classList.remove('active');
-
-  const pane = document.getElementById('notes-pane');
-  const backdrop = document.getElementById('notes-pane-backdrop');
-  if (pane) {
-    // Scale-out + fade. Match the enter animation duration so close feels
-    // like the same gesture played backwards.
-    pane.classList.add('notes-pane-leaving');
-    const _cleanup = () => {
-      try { pane.remove(); } catch {}
-      try { backdrop?.remove(); } catch {}
-    };
-    pane.addEventListener('animationend', _cleanup, { once: true });
-    // Belt-and-braces: if animation is skipped (reduced motion / detached
-    // tab) the listener won't fire; remove after the expected duration.
-    setTimeout(_cleanup, 220);
-  } else if (backdrop) {
-    backdrop.remove();
-  }
-  // Show the dock chip for a swipe-down minimize (tap it to reopen).
-  if (_minimize) { try { Modals.minimize('notes-panel'); } catch {} }
-}
-
-export function togglePanel() {
-  if (_open) closePanel();
-  else openPanel();
-}
-
-export function isPanelOpen() { return _open; }
-
-// ---- Render ----
-
-// FLIP animation — capture positions before render, animate back after
-function _captureCardPositions() {
-  const body = document.querySelector('#notes-pane .notes-pane-body');
-  if (!body) return null;
-  const positions = new Map();
-  body.querySelectorAll('.note-card').forEach(card => {
-    const id = card.dataset.noteId;
-    if (id) positions.set(id, card.getBoundingClientRect());
-  });
-  return positions;
-}
-
-function _animateReflow(prevPositions) {
-  if (!prevPositions || !prevPositions.size) return;
-  const body = document.querySelector('#notes-pane .notes-pane-body');
-  if (!body) return;
-  body.querySelectorAll('.note-card').forEach(card => {
-    const id = card.dataset.noteId;
-    const prev = prevPositions.get(id);
-    if (!prev) return;
-    const next = card.getBoundingClientRect();
-    const dx = prev.left - next.left;
-    const dy = prev.top - next.top;
-    if (Math.abs(dx) < 1 && Math.abs(dy) < 1) return;
-    // Invert: jump back to old position
-    card.style.transition = 'none';
-    card.style.transform = `translate(${dx}px, ${dy}px)`;
-    // Play: animate to 0
-    requestAnimationFrame(() => {
-      card.style.transition = 'transform 0.25s cubic-bezier(0.34, 1.2, 0.64, 1)';
-      card.style.transform = '';
-      card.addEventListener('transitionend', () => {
-        card.style.transition = '';
-      }, { once: true });
-    });
-  });
-}
-
-function _renderNotes() {
-  _updateRailBadge();
-  const body = document.querySelector('#notes-pane .notes-pane-body');
-  if (!body) return;
-  const prevPositions = _captureCardPositions();
-  const activeReminderHighlights = _loadActiveHighlights();
-
-  const displayNotes = _userVisibleNotes();
-  let filtered = _activeLabel ? displayNotes.filter(n => _noteTags(n).includes(_activeLabel)) : displayNotes;
-  if (_activeFilter === 'reminders') {
-    filtered = filtered.filter(n => n.due_date && _hasTimeComponent(n.due_date));
-  } else if (_activeFilter === 'no-reminders') {
-    filtered = filtered.filter(n => !(n.due_date && _hasTimeComponent(n.due_date)));
-  } else if (_activeFilter === 'default') {
-    filtered = filtered.filter(n => _visibleNoteTags(n).length === 0);
-  } else if (_activeFilter === 'goals') {
-    filtered = filtered.filter(n => n.note_type === 'goal' && !n.archived);
-  } else if (_activeFilter === 'today') {
-    // Today view: only goals that still have an unchecked step.
-    filtered = filtered.filter(n => n.note_type === 'goal' && !n.archived && _nextGoalStep(n));
-  }
-  if (_searchQuery) {
-    filtered = filtered.filter(n => {
-      const q = _searchQuery;
-      if ((n.title || '').toLowerCase().includes(q)) return true;
-      if ((n.content || '').toLowerCase().includes(q)) return true;
-      if ((n.label || '').toLowerCase().includes(q)) return true;
-      if (Array.isArray(n.items) && n.items.some(it => (it.text || '').toLowerCase().includes(q))) return true;
-      return false;
-    });
-  }
-  const sorted = [...filtered].sort((a, b) => {
-    // In reminders view: sort by due date ascending (soonest first)
-    if (_activeFilter === 'reminders') {
-      const da = new Date(a.due_date || 0).getTime();
-      const db = new Date(b.due_date || 0).getTime();
-      return da - db;
-    }
-    // Archived view: newest archived first (ignore manual sort_order).
-    if (_showingArchived) {
-      return new Date(b.updated_at || 0) - new Date(a.updated_at || 0);
-    }
-    if (a.pinned && !b.pinned) return -1;
-    if (!a.pinned && b.pinned) return 1;
-    // Active reminders (due date in the past, not done/archived) rank
-    // immediately under the pinned block.
-    const aActive = _hasActiveReminder(a);
-    const bActive = _hasActiveReminder(b);
-    if (aActive && !bActive) return -1;
-    if (!aActive && bActive) return 1;
-    const so = (a.sort_order || 0) - (b.sort_order || 0);
-    if (so !== 0) return so;
-    return new Date(b.updated_at || 0) - new Date(a.updated_at || 0);
-  });
-
-  let html = '';
-  // Today view: render a compact card listing the next-unchecked step from
-  // each active goal. Tapping a step toggles it done (same idx-based wiring
-  // as regular checkboxes). Tapping the title opens the goal note for full
-  // editing.
-  if (_activeFilter === 'today') {
-    body.innerHTML = '';
-    _renderLabelsInto(body);
-    _renderQuickAdd(body);
-    if (sorted.length === 0) {
-      body.insertAdjacentHTML('beforeend', `<div class="notes-empty">All caught up — no pending goal steps right now.</div>`);
-    } else {
-      let todayHtml = `<div class="notes-today-wrap">
-        <div class="notes-today-header">
-          <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="3" y="4" width="18" height="18" rx="2"/><line x1="16" y1="2" x2="16" y2="6"/><line x1="8" y1="2" x2="8" y2="6"/><line x1="3" y1="10" x2="21" y2="10"/></svg>
-          <span>Today &middot; one step per goal</span>
-        </div>
-        <div class="notes-today-list">`;
-      for (const note of sorted) {
-        const next = _nextGoalStep(note);
-        if (!next) continue;
-        const progress = _goalProgress(note).trim();
-        todayHtml += `<div class="notes-today-row" data-note-id="${note.id}">
-          <span class="note-check-dot" data-note-id="${note.id}" data-idx="${next.idx}" title="Mark step done"></span>
-          <div class="notes-today-text">
-            <div class="notes-today-title" data-action="edit" data-note-id="${note.id}">${_esc(note.title || '(untitled goal)')}</div>
-            <div class="notes-today-step">${_linkify(next.item.text || '')}</div>
-          </div>
-          <span class="notes-today-progress">${_esc(progress)}</span>
-        </div>`;
-      }
-      todayHtml += `</div></div>`;
-      body.insertAdjacentHTML('beforeend', todayHtml);
-    }
-    _wireTodayView(body);
-    return;
-  }
-  for (const note of sorted) {
-    if (_editingId === note.id) continue; // skip — form is shown instead
-    const borderColor = COLOR_HEX[note.color || ''] || 'var(--border)';
-    const dueFmt = _formatDueDate(note.due_date);
-    const overdue = _isDueOverdue(note.due_date);
-
-    let contentHtml = '';
-    if (_hasItems(note) && Array.isArray(note.items)) {
-      // Goal notes can carry a free-form description above the step list —
-      // todos rarely do, but the same render works for both.
-      if (note.note_type === 'goal' && (note.content || '').trim()) {
-        const fullText = note.content || '';
-        const preview = fullText.length > 300 ? fullText.slice(0, 300) + '…' : fullText;
-        contentHtml += `<div class="note-goal-desc">${_esc(preview)}</div>`;
-      }
-      contentHtml += '<div class="note-checklist-preview">';
-      // Show ALL items — the preview container is scrollable (CSS caps
-      // its max-height + overflow-y:auto), so there's no need to truncate.
-      for (let i = 0; i < note.items.length; i++) {
-        const item = note.items[i];
-        const doneClass = item.done ? ' done' : '';
-        const indent = Math.min(item.indent || 0, 3);
-        contentHtml += `<div class="note-checkbox${doneClass}" data-note-id="${note.id}" data-idx="${i}" style="padding-left:${indent * 16}px">
-          <span class="note-check-dot" title="Mark done"></span>
-          <span class="note-check-text">${_linkify(item.text)}</span>
-          <button class="note-checkbox-edit" data-note-id="${note.id}" data-idx="${i}" title="Edit item">
-            <svg width="10" height="10" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M11 4H4a2 2 0 0 0-2 2v14a2 2 0 0 0 2 2h14a2 2 0 0 0 2-2v-7"/><path d="M18.5 2.5a2.121 2.121 0 0 1 3 3L12 15l-4 1 1-4 9.5-9.5z"/></svg>
-          </button>
-          <button class="note-checkbox-rm" data-note-id="${note.id}" data-idx="${i}" title="Delete item">
-            <svg width="10" height="10" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round"><line x1="18" y1="6" x2="6" y2="18"/><line x1="6" y1="6" x2="18" y2="18"/></svg>
-          </button>
-        </div>`;
-      }
-      contentHtml += '</div>';
-    } else {
-      const fullText = note.content || '';
-      const preview = fullText.length > 600 ? fullText.slice(0, 600) + '…' : fullText;
-      // _linkify already calls _esc internally, so URLs become clickable
-      // anchors (used by e.g. the "remind me to reply" email deep-link).
-      contentHtml = preview ? `<div class="note-content-preview">${_linkify(preview)}</div>` : '';
-    }
-
-    const isBg = _isBgImage(note.color);
-    const cc = (note.color && !isBg) ? ' note-color-' + note.color : '';
-    const cardStyle = isBg ? ` style="${_customColorStyle(note.color)}"` : '';
-    const isStandard = !note.note_type || note.note_type === 'note';
-    const visualClass = isStandard && !note.color ? ` note-standard note-standard-v${_standardVisualVariant(note)}` : '';
-    const sel = _selectedIds.has(note.id) ? ' note-card-selected' : '';
-    const reminderTagHtml = note.due_date && _hasTimeComponent(note.due_date)
-      ? `<div class="note-card-reminder${overdue ? ' overdue' : ''}">
-          <svg width="10" height="10" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round"><path d="M18 8A6 6 0 0 0 6 8c0 7-3 9-3 9h18s-3-2-3-9"/><path d="M13.73 21a2 2 0 0 1-3.46 0"/></svg>
-          <span>${_esc(_formatReminderTag(note.due_date))}${note.repeat && note.repeat !== 'none' ? ' · ' + _esc(_formatRepeatLabel(note.repeat, new Date(note.due_date))) : ''}</span>
-        </div>`
-      : '';
-    const noteTags = _visibleNoteTags(note);
-    const dueBadge = dueFmt && !_hasTimeComponent(note.due_date) ? `<span class="note-due-inline${overdue ? ' note-due-overdue' : ''}">${dueFmt}</span>` : '';
-    const colorDots = COLORS.map(c => `<span class="note-card-color-dot${_dotIsActive(c.value, note.color) ? ' active' : ''}" data-color="${c.value}" style="background:${_dotBg(c.value, note.color)}" title="${c.name || 'default'}"></span>`).join('');
-    const goalClass = note.note_type === 'goal' ? ' note-card-goal' : '';
-    const reminderGlowClass = activeReminderHighlights.has(note.id) && _hasActiveReminder(note) ? ' note-card-reminder-fired-sticky' : '';
-    const goalPill = note.note_type === 'goal'
-      ? `<span class="note-goal-pill" title="AI-broken-down goal">
-          <svg width="10" height="10" viewBox="0 0 24 24" fill="currentColor"><path d="M12 0L14.59 8.41L23 12L14.59 15.59L12 24L9.41 15.59L1 12L9.41 8.41Z"/></svg>
-          Goal${_goalProgress(note)}
-        </span>`
-      : '';
-    const drawingClass = note.note_type === 'draw' ? ' note-card-drawing' : '';
-    html += `<div class="note-card${note.pinned ? ' note-card-pinned' : ''}${cc}${visualClass}${sel}${goalClass}${drawingClass}${reminderGlowClass}${_selectMode ? ' note-card-selectmode' : ''}" draggable="${(_selectMode || _isNotesMobileMode()) ? 'false' : 'true'}" data-note-id="${note.id}"${cardStyle}>
-      ${_selectMode ? `<input type="checkbox" class="memory-select-cb note-card-cb" data-note-id="${note.id}" ${_selectedIds.has(note.id) ? 'checked' : ''} />` : ''}
-      ${goalPill}
-      <button class="note-card-pin${note.pinned ? ' active' : ''}" data-note-id="${note.id}" title="${note.pinned ? 'Unpin' : 'Pin'}">
-        <svg width="16" height="16" viewBox="0 0 24 28" fill="${note.pinned ? 'currentColor' : 'none'}" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"${note.pinned ? ' style="color:var(--accent,var(--red));"' : ''}><g transform="rotate(${note.pinned ? 0 : 45} 12 14)" style="transition:transform 0.2s ease;"><line x1="12" y1="17" x2="12" y2="27"/><path d="M5 17h14v-1.76a2 2 0 0 0-1.11-1.79l-1.78-.9A2 2 0 0 1 15 10.76V6h1a2 2 0 0 0 0-4H8a2 2 0 0 0 0 4h1v4.76a2 2 0 0 1-1.11 1.79l-1.78.9A2 2 0 0 0 5 15.24V17z"/></g></svg>
-      </button>
-      ${_showingArchived
-        ? `<button class="note-card-corner-trash" data-note-id="${note.id}" title="Delete forever" aria-label="Delete forever">
-            <svg width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><polyline points="3 6 5 6 21 6"/><path d="M19 6l-1 14a2 2 0 0 1-2 2H8a2 2 0 0 1-2-2L5 6"/><path d="M8 6V4a2 2 0 0 1 2-2h4a2 2 0 0 1 2 2v2"/><line x1="10" y1="11" x2="10" y2="17"/><line x1="14" y1="11" x2="14" y2="17"/></svg>
-          </button>
-          <button class="note-card-corner-unarchive" data-note-id="${note.id}" title="Unarchive" aria-label="Unarchive note">
-            <svg width="17" height="17" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round"><path d="M9 14l-5-5 5-5"/><path d="M4 9h11a5 5 0 0 1 5 5v0a5 5 0 0 1-5 5H9"/></svg>
-          </button>`
-        : `<button class="note-card-done" data-note-id="${note.id}" title="Mark done" aria-label="Mark done">
-            <svg width="17" height="17" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.4" stroke-linecap="round" stroke-linejoin="round"><polyline points="20 6 9 17 4 12"/></svg>
-          </button>
-          ${_hasItems(note) ? `<button class="note-card-copy note-card-copy-corner" data-note-id="${note.id}" title="Copy all items" aria-label="Copy all items">
-            <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="9" y="9" width="13" height="13" rx="2"/><path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"/></svg>
-          </button>` : ''}`}
-      <div class="note-card-header">
-        <div class="note-card-title${note.title ? '' : ' empty'}" data-action="edit">${_esc(note.title || '')}</div>
-        ${dueBadge}
-      </div>
-      ${_safeImgSrc(note.image_url) ? `<img class="note-card-image" src="${_esc(_safeImgSrc(note.image_url))}" alt="" draggable="false" />` : ''}
-      ${contentHtml}
-      ${_hasItems(note) ? `<div class="note-cl-quickadd"><input type="text" class="note-cl-quickadd-input" placeholder="+ Add item" data-note-id="${note.id}" /></div>` : ''}
-      ${reminderTagHtml}
-      ${noteTags.length ? `<div class="note-card-label">${noteTags.map(t => `<button type="button" class="note-card-label-chip" data-note-label-filter="${_esc(t)}" title="Filter #${_esc(t)}">#${_esc(t)}</button>`).join(' ')}</div>` : ''}
-      <div class="note-card-actions">
-        <div class="note-card-colors">${colorDots}</div>
-        <span style="flex:1"></span>
-        ${_showingArchived ? `
-        <button class="note-card-action note-card-delete" data-note-id="${note.id}" title="Delete permanently">
-          <svg width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><polyline points="3 6 5 6 21 6"/><path d="M19 6l-1 14a2 2 0 0 1-2 2H8a2 2 0 0 1-2-2L5 6"/><path d="M8 6V4a2 2 0 0 1 2-2h4a2 2 0 0 1 2 2v2"/><line x1="10" y1="11" x2="10" y2="17"/><line x1="14" y1="11" x2="14" y2="17"/></svg>
-        </button>
-        <button class="note-card-action note-card-unarchive" data-note-id="${note.id}" title="Unarchive">
-          <svg width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M3 12a9 9 0 1 0 3-6.7"/><polyline points="3 4 3 10 9 10"/></svg>
-        </button>` : `
-        ${_hasItems(note) ? `
-        <button class="note-card-action note-card-copy" data-note-id="${note.id}" title="Copy all items">
-          <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="9" y="9" width="13" height="13" rx="2"/><path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"/></svg>
-        </button>` : ''}
-        <button class="note-card-action note-card-archive" data-note-id="${note.id}" title="Save (archive)">
-          <svg width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M19 21H5a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2h11l5 5v11a2 2 0 0 1-2 2z"/><polyline points="17 21 17 13 7 13 7 21"/><polyline points="7 3 7 8 15 8"/></svg>
-        </button>
-        <button class="note-card-action note-card-delete" data-note-id="${note.id}" title="Delete">
-          <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round"><line x1="18" y1="6" x2="6" y2="18"/><line x1="6" y1="6" x2="18" y2="18"/></svg>
-        </button>
-        <button class="note-card-action note-card-corner-menu" data-note-id="${note.id}" title="More" aria-label="More actions">
-          <svg width="16" height="16" viewBox="0 0 24 24" fill="currentColor"><circle cx="5" cy="12" r="1.7"/><circle cx="12" cy="12" r="1.7"/><circle cx="19" cy="12" r="1.7"/></svg>
-        </button>`}
-      </div>
-    </div>`;
-  }
-
-  // Always render quick-add at top (collapsed unless user is typing)
-  const existingForm = body.querySelector('.note-form');
-  if (existingForm && _editingId === '__new__') {
-    // Keep the expanded form, replace cards after it
-    const next = [...body.children].filter(c => c !== existingForm);
-    next.forEach(c => c.remove());
-    if (sorted.length === 0) {
-      body.insertAdjacentHTML('beforeend', '<div class="notes-empty-msg">No notes <span style="vertical-align:-3px;margin-left:4px;">' + uiModule.emptyStateIcon('smiley') + '</span></div>');
-    } else {
-      existingForm.insertAdjacentHTML('afterend', html);
-    }
-  } else {
-    body.innerHTML = '';
-    _renderLabelsInto(body);
-    _renderQuickAdd(body);
-    if (sorted.length === 0) {
-      body.insertAdjacentHTML('beforeend', '<div class="notes-empty-msg">No notes yet <span style="vertical-align:-3px;margin-left:4px;">' + uiModule.emptyStateIcon('smiley') + '</span></div>');
-    } else {
-      body.insertAdjacentHTML('beforeend', html);
-    }
-  }
-
-  _bindCardEvents(body);
-  _animateReflow(prevPositions);
-  _applyMasonry(body);
-}
-
-// In grid view, lay out the cards as masonry by
-// computing each card's `grid-row-end: span N` from its measured height
-// (rows are 4px tall + 8px row gap simulated via card margin-bottom). The
-// grid's `grid-auto-flow: dense` packs columns independently so left/right
-// lanes no longer share row heights.
-//
-// Re-runs on layout-affecting changes via ResizeObserver bound per-card.
-let _masonryObserver = null;
-function _applyMasonry(body) {
-  if (!body) return;
-  const pane = body.closest('.notes-pane');
-  const isGrid = pane?.classList.contains('notes-view-grid');
-  const isMobileGrid = isGrid && window.matchMedia('(max-width: 768px)').matches;
-  // Tear down any prior observer (defensive — _renderNotes wipes body.innerHTML).
-  if (_masonryObserver) { try { _masonryObserver.disconnect(); } catch {} _masonryObserver = null; }
-  if (!isGrid) {
-    // Clear any leftover inline spans so list view lays out normally.
-    body.querySelectorAll('.note-card, .notes-label-toggle, .notes-labels-bar, .notes-quick-add, .note-form, .doclib-chip-scroll-frame:has(> .notes-labels-bar)').forEach(c => { c.style.gridRowEnd = ''; });
-    return;
-  }
-  const ROW_PX = 4;
-  const spanForHeight = (h) => Math.max(1, Math.ceil(h / ROW_PX));
-  const recomputeFullRows = () => {
-    const quickAdd = body.querySelector('.notes-quick-add');
-    const labelsToggle = body.querySelector('.notes-label-toggle');
-    const labelsBar = body.querySelector('.notes-labels-bar');
-    const labelsLayout = labelsBar?.parentElement?.classList.contains('doclib-chip-scroll-frame')
-      ? labelsBar.parentElement
-      : labelsBar;
-    if (labelsToggle && getComputedStyle(labelsToggle).display !== 'none') {
-      labelsToggle.style.gridRowEnd = `span ${Math.max(1, spanForHeight(labelsToggle.scrollHeight))}`;
-    }
-    if (labelsLayout && getComputedStyle(labelsLayout).display !== 'none') {
-      const shave = isMobileGrid ? 4 : 0;
-      labelsLayout.style.gridRowEnd = `span ${Math.max(1, spanForHeight(labelsLayout.scrollHeight) - shave)}`;
-    }
-    if (quickAdd) {
-      const shave = isMobileGrid ? 4 : 0;
-      quickAdd.style.gridRowEnd = `span ${Math.max(1, spanForHeight(quickAdd.scrollHeight + 10) - shave)}`;
-    }
-    body.querySelectorAll('.note-form').forEach(form => {
-      form.style.gridColumn = '1 / -1';
-      const isDrawForm = !!form.querySelector('.note-form-type-seg.is-draw');
-      const minSpan = isMobileGrid ? (isDrawForm ? 104 : 64) : 1;
-      const renderedHeight = form.getBoundingClientRect?.().height || 0;
-      const drawReserve = isDrawForm && isMobileGrid ? 12 : 12;
-      const measuredHeight = Math.max(form.scrollHeight, renderedHeight) + drawReserve;
-      form.style.gridRowEnd = `span ${Math.max(minSpan, spanForHeight(measuredHeight))}`;
-    });
-  };
-  const recompute = (card) => {
-    // scrollHeight returns the natural content height — card.getBoundingClientRect()
-    // would return the grid cell height (collapsed to 4px until the span is set,
-    // which is the value we're trying to compute).
-    const h = card.scrollHeight + (isMobileGrid ? 6 : 8);
-    if (h <= 0) return;
-    card.style.gridRowEnd = `span ${spanForHeight(h)}`;
-  };
-  recomputeFullRows();
-  body.querySelectorAll('.note-card').forEach(recompute);
-  // Watch masonry participants — content can grow (image load, todo edits,
-  // quick-add/form expansion), and stale spans are what cause visual merging.
-  if ('ResizeObserver' in window) {
-    _masonryObserver = new ResizeObserver(entries => {
-      let fullRowsChanged = false;
-      for (const e of entries) {
-        if (e.target.classList.contains('note-card')) recompute(e.target);
-        else fullRowsChanged = true;
-      }
-      if (fullRowsChanged) recomputeFullRows();
-    });
-    body.querySelectorAll('.note-card').forEach(c => _masonryObserver.observe(c));
-  body.querySelectorAll('.notes-label-toggle, .notes-quick-add, .note-form').forEach(c => _masonryObserver.observe(c));
-  const labelsBar = body.querySelector('.notes-labels-bar');
-  const labelsLayout = labelsBar?.parentElement?.classList.contains('doclib-chip-scroll-frame')
-    ? labelsBar.parentElement
-    : labelsBar;
-  if (labelsLayout) _masonryObserver.observe(labelsLayout);
-  }
-}
-
-// Wire the Today aggregated view: tap a step's dot toggles it done; tap
-// the goal title opens the full note for editing. Done steps fade and the
-// next pending step rotates in on the next render.
-function _wireTodayView(body) {
-  body.querySelectorAll('.notes-today-row .note-check-dot').forEach(dot => {
-    dot.addEventListener('click', async (e) => {
-      e.stopPropagation();
-      const id = dot.dataset.noteId;
-      const idx = parseInt(dot.dataset.idx);
-      const note = _notes.find(n => n.id === id);
-      if (!note || !Array.isArray(note.items) || !note.items[idx]) return;
-      note.items[idx].done = !note.items[idx].done;
-      const row = dot.closest('.notes-today-row');
-      if (row) row.classList.add('done');
-      try {
-        await _patchNote(id, { items: note.items });
-        // Re-render so the next pending step bubbles up (or the row drops
-        // out entirely if the goal is fully done now).
-        _renderNotes();
-        // Confetti when ALL items just turned done.
-        if (note.items.every(it => it.done)) {
-          const r = (row || dot).getBoundingClientRect();
-          spawnConfetti(r.left + r.width / 2, r.top + r.height / 2, 60);
-        }
-      } catch {
-        note.items[idx].done = !note.items[idx].done;
-      }
-    });
-  });
-  body.querySelectorAll('.notes-today-title').forEach(el => {
-    el.addEventListener('click', () => {
-      const id = el.dataset.noteId;
-      if (!id) return;
-      // Drop the Today filter first so the regular card list is rendered;
-      // _editNote needs to find a .note-card in the DOM to replace with
-      // the editor form.
-      _activeFilter = null;
-      _renderNotes();
-      _editNote(id);
-    });
-  });
-}
-
-function _renderQuickAdd(body) {
-  const wrap = document.createElement('div');
-  wrap.className = 'notes-quick-add';
-  // 2-pill Note/Todo toggle mirrors the full form's type-seg (minus Draw —
-  // drawing happens in the expanded form). The pill that's active steers
-  // both the placeholder and the type the form opens in.
-  wrap.innerHTML = `
-    <div class="notes-quick-type-seg is-todo" role="group" aria-label="New item type">
-      <button type="button" class="notes-quick-type-pill" data-type="note" aria-label="Note" aria-pressed="false" title="Note">
-        <svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><line x1="4" y1="6" x2="20" y2="6"/><line x1="4" y1="12" x2="20" y2="12"/><line x1="4" y1="18" x2="14" y2="18"/></svg>
-      </button>
-      <button type="button" class="notes-quick-type-pill active" data-type="todo" aria-label="To-do" aria-pressed="true" title="To-do">
-        <svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><polyline points="9 11 12 14 22 4"/><path d="M21 12v7a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2h11"/></svg>
-      </button>
-    </div>
-    <input type="text" class="notes-quick-input" placeholder="Add a to-do…" />
-    <button class="notes-quick-icon" data-action="photo" title="Attach photo">
-      <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="3" y="3" width="18" height="18" rx="2"/><circle cx="8.5" cy="8.5" r="1.5"/><polyline points="21 15 16 10 5 21"/></svg>
-    </button>
-  `;
-  body.appendChild(wrap);
-
-  const input = wrap.querySelector('.notes-quick-input');
-  const seg = wrap.querySelector('.notes-quick-type-seg');
-  let currentType = 'todo';
-  const setType = (t) => {
-    if (t !== 'note' && t !== 'todo') return;
-    currentType = t;
-    seg.classList.toggle('is-todo', t === 'todo');
-    seg.classList.toggle('is-note', t === 'note');
-    seg.querySelectorAll('.notes-quick-type-pill').forEach(p => {
-      const on = p.dataset.type === t;
-      p.classList.toggle('active', on);
-      p.setAttribute('aria-pressed', on ? 'true' : 'false');
-    });
-    input.placeholder = t === 'note' ? 'Add a note…' : 'Add a to-do…';
-  };
-  seg.querySelectorAll('.notes-quick-type-pill').forEach(p => {
-    p.addEventListener('click', (e) => {
-      e.stopPropagation();
-      setType(p.dataset.type);
-    });
-  });
-  // Click input or type → expand to full form
-  const expandToForm = (initialType = 'note', initialText = '') => {
-    _editingId = '__new__';
-    const form = _buildForm({ note_type: initialType });
-    form.classList.add('note-form-new');
-    if (initialText) {
-      const titleEl = form.querySelector('.note-form-title');
-      if (titleEl) titleEl.value = initialText;
-    }
-    const mobileGrid = body.closest('.notes-pane')?.classList.contains('notes-view-grid')
-      && window.matchMedia('(max-width: 768px)').matches;
-    if (mobileGrid) {
-      form.style.gridColumn = '1 / -1';
-      form.style.gridRowEnd = 'span 64';
-    }
-    wrap.replaceWith(form);
-    _applyMasonry(body);
-    requestAnimationFrame(() => _applyMasonry(body));
-    const titleEl = form.querySelector('.note-form-title');
-    if (titleEl) {
-      titleEl.focus();
-      // Move caret to end
-      titleEl.setSelectionRange(titleEl.value.length, titleEl.value.length);
-    }
-  };
-  // Expand only on real intent: a click directly on the input, or actual
-  // typing. Focus alone — including focus stolen from a missed nearby
-  // click — no longer creates an empty form.
-  input.addEventListener('click', () => expandToForm(currentType, input.value));
-  input.addEventListener('input', () => expandToForm(currentType, input.value));
-  wrap.querySelector('[data-action="photo"]').addEventListener('click', (e) => {
-    e.stopPropagation();
-    expandToForm(currentType);
-    // Trigger photo input on the new form
-    setTimeout(() => document.querySelector('.note-form-photo-btn')?.click(), 50);
-  });
-}
-
-function _bindCardEvents(body) {
-  // Skip completed leading rows so the first unfinished checklist item is
-  // visible when a note preview has its own scroll area.
-  requestAnimationFrame(() => {
-    body.querySelectorAll('.note-checklist-preview').forEach(preview => {
-      const firstPending = preview.querySelector('.note-checkbox:not(.done)');
-      if (firstPending) preview.scrollTop = Math.max(0, firstPending.offsetTop - 4);
-    });
-  });
-  const tapToEditOrSelect = (cardEl) => {
-    const id = cardEl.dataset.noteId;
-    // A long-press enters select mode and re-renders the card. Ignore the
-    // synthetic click that mobile browsers emit when that same touch ends.
-    if (_suppressNextNoteTapId === id) {
-      _suppressNextNoteTapId = null;
-      return;
-    }
-    if (_selectMode) {
-      const cb = cardEl.querySelector('.note-card-cb');
-      if (cb) {
-        cb.checked = !cb.checked;
-        cb.dispatchEvent(new Event('change'));
-      }
-    } else if (_isNotesMobileMode()) {
-      // Mobile: open the per-note fullscreen edit overlay instead of the
-      // in-place form. Tiles on mobile are read-only previews.
-      _openMobileFullscreenEdit(id, cardEl);
-    } else {
-      _editNote(id);
-    }
-  };
-  // Mobile: long-press anywhere on a note card → enter Select mode and
-  // select that card. Cancelled by movement (so it doesn't interfere with
-  // vertical scrolling) or by lifting the finger before the timer fires.
-  if (_isNotesMobileMode()) {
-    body.querySelectorAll('.note-card').forEach(card => _bindLongPressDrag(card));
-  }
-  body.querySelectorAll('.note-card.note-card-reminder-fired-sticky').forEach(card => {
-    card.addEventListener('click', () => _setReminderCardGlow(card.dataset.noteId, false), true);
-  });
-  // Click title — edit, or toggle select in select mode
-  body.querySelectorAll('.note-card-title[data-action="edit"]').forEach(el => {
-    el.addEventListener('click', (e) => {
-      e.stopPropagation();
-      _smoothScrollToNoteCard(el.closest('.note-card'));
-      tapToEditOrSelect(el.closest('.note-card'));
-    });
-  });
-  // Click content — edit, or toggle select in select mode
-  body.querySelectorAll('.note-content-preview').forEach(el => {
-    el.addEventListener('click', (e) => { e.stopPropagation(); tapToEditOrSelect(el.closest('.note-card')); });
-  });
-  // A saved drawing is the note's primary content. Open its editor directly
-  // when the preview is clicked, matching title/content preview behavior.
-  body.querySelectorAll('.note-card-drawing .note-card-image').forEach(el => {
-    el.addEventListener('click', (e) => {
-      e.stopPropagation();
-      tapToEditOrSelect(el.closest('.note-card'));
-    });
-  });
-  // Click empty area of checklist preview (not on checkbox/X) — edit
-  body.querySelectorAll('.note-checklist-preview').forEach(el => {
-    el.addEventListener('wheel', (e) => {
-      const atTop = el.scrollTop <= 0;
-      const atBottom = el.scrollTop + el.clientHeight >= el.scrollHeight - 1;
-      if ((e.deltaY < 0 && atTop) || (e.deltaY > 0 && atBottom)) {
-        const pane = el.closest('.notes-pane-body');
-        if (pane) {
-          pane.scrollTop += e.deltaY;
-          e.preventDefault();
-        }
-      }
-    }, { passive: false });
-    el.addEventListener('click', (e) => {
-      if (e.target.closest('.note-checkbox, .note-checkbox-rm, .note-cl-quickadd, input')) return;
-      e.stopPropagation();
-      tapToEditOrSelect(el.closest('.note-card'));
-    });
-  });
-  // Clicking todo item text now toggles its checkbox — let the click bubble
-  // up to the parent .note-checkbox row handler. To open the editor, the
-  // user clicks the pencil corner.
-  // (No-op block kept as a marker — removing the listener entirely means
-  // clicks naturally bubble to the row toggle below.)
-  // In select mode, clicking anywhere on the card toggles selection
-  if (_selectMode) {
-    body.querySelectorAll('.note-card').forEach(card => {
-      card.addEventListener('click', (e) => {
-        if (e.target.closest('.note-card-cb')) return; // checkbox handles itself
-        e.stopPropagation();
-        tapToEditOrSelect(card);
-      });
-    });
-  }
-  // Mobile, non-select: tapping anywhere on the card body (not on an
-  // interactive child — buttons, pin, checkbox, color dot, reminder pill,
-  // agent tag, links) opens the fullscreen editor. Previously only the
-  // title / content preview triggered edit, so padding + empty gutters were
-  // dead zones that felt broken on mobile.
-  if (_isNotesMobileMode() && !_selectMode) {
-    const _INTERACTIVE = 'button, a, input, label, .note-card-color-dot, .note-checkbox, .note-checkbox-rm, .note-cl-quickadd, .note-agent-tag, .note-card-pin, .note-card-corner-trash, .note-card-corner-menu, .note-card-corner-unarchive, .note-card-edit-corner, .note-card-reminder, .note-card-cb';
-    body.querySelectorAll('.note-card').forEach(card => {
-      card.addEventListener('click', (e) => {
-        if (e.target.closest(_INTERACTIVE)) return;
-        e.stopPropagation();
-        tapToEditOrSelect(card);
-      });
-    });
-  }
-  // Multi-select checkbox (only in select mode)
-  body.querySelectorAll('.note-card-cb').forEach(cb => {
-    cb.addEventListener('click', (e) => e.stopPropagation());
-    cb.addEventListener('change', () => {
-      const id = cb.dataset.noteId;
-      if (cb.checked) _selectedIds.add(id);
-      else _selectedIds.delete(id);
-      cb.closest('.note-card').classList.toggle('note-card-selected', cb.checked);
-      _updateBulkBar();
-    });
-  });
-  // Pin toggle (optimistic)
-  body.querySelectorAll('.note-card-pin').forEach(btn => {
-    btn.addEventListener('click', (e) => {
-      e.stopPropagation();
-      const id = btn.dataset.noteId;
-      const note = _notes.find(n => n.id === id);
-      if (!note) return;
-      const prevPinned = note.pinned;
-      const prevSortOrder = note.sort_order;
-      note.pinned = !prevPinned;
-      const patch = { pinned: note.pinned };
-      if (note.pinned) {
-        const minPinned = _notes
-          .filter(n => n.pinned && n.id !== id)
-          .reduce((m, n) => Math.min(m, n.sort_order || 0), 0);
-        note.sort_order = minPinned - 1;
-        patch.sort_order = note.sort_order;
-      }
-      _renderNotes();
-      _patchNote(id, patch).catch(() => {
-        note.pinned = prevPinned;
-        note.sort_order = prevSortOrder;
-        _renderNotes();
-        uiModule.showError('Failed to pin');
-      });
-    });
-  });
-  // Color picker
-  const _applyCardColor = async (card, id, newColor) => {
-    const isBg = _isBgImage(newColor);
-    COLORS.forEach(c => { if (c.value && c.value !== 'custom') card.classList.remove('note-color-' + c.value); });
-    if (newColor && !isBg) card.classList.add('note-color-' + newColor);
-    if (isBg) card.setAttribute('style', _customColorStyle(newColor));
-    else card.removeAttribute('style');
-    card.querySelectorAll('.note-card-color-dot').forEach(d => {
-      d.classList.toggle('active', _dotIsActive(d.dataset.color, newColor));
-      d.style.background = _dotBg(d.dataset.color, newColor);
-    });
-    try { await _patchNote(id, { color: newColor || null }); const note = _notes.find(n => n.id === id); if (note) note.color = newColor; }
-    catch { uiModule.showError('Failed to update color'); }
-  };
-  body.querySelectorAll('.note-card-color-dot').forEach(dot => {
-    dot.addEventListener('click', (e) => {
-      e.stopPropagation();
-      const card = dot.closest('.note-card');
-      const id = card.dataset.noteId;
-      if (dot.dataset.color === 'custom') {
-        _pickCustomBgImage().then(url => { if (url) _applyCardColor(card, id, 'bg:' + url); });
-        return;
-      }
-      _applyCardColor(card, id, dot.dataset.color);
-    });
-  });
-  // Plain pencil corner → open editor. The unarchive corner shares the
-  // .note-card-edit-corner class for styling, so :not() keeps the edit
-  // handler off it.
-  body.querySelectorAll('.note-card-edit-corner:not(.note-card-unarchive-corner)').forEach(btn => {
-    btn.addEventListener('click', (e) => {
-      e.stopPropagation();
-      const id = btn.dataset.noteId;
-      if (id) _editNote(id);
-    });
-  });
-  // Copy corner — bottom-right, just left of the Done check. Shared with
-   // the Ctrl/Cmd+C shortcut wired further down so both code paths run the
-   // same serializer + feedback flash.
-  // ⋯ corner menu — Copy + Agent (solve-this-todo).
-  body.querySelectorAll('.note-card-corner-menu').forEach(btn => {
-    btn.addEventListener('click', (e) => {
-      e.preventDefault();
-      e.stopPropagation();
-      _openNoteCornerMenu(btn);
-    });
-  });
-  body.querySelectorAll('.note-card-label-chip').forEach(chip => {
-    chip.addEventListener('click', (e) => {
-      e.preventDefault();
-      e.stopPropagation();
-      const label = chip.dataset.noteLabelFilter;
-      if (!label) return;
-      if (_activeLabel === label && _activeFilter === null) {
-        _activeLabel = null;
-      } else {
-        _activeFilter = null;
-        _activeLabel = label;
-      }
-      _renderNotes();
-    });
-  });
-  // Done (✓) at bottom-right — only visible on hover for active notes.
-  body.querySelectorAll('.note-card-done').forEach(btn => {
-    btn.addEventListener('click', (e) => {
-      e.stopPropagation();
-      const id = btn.dataset.noteId;
-      const card = btn.closest('.note-card');
-      const idx = _notes.findIndex(n => n.id === id);
-      if (idx < 0) return;
-      // Celebrate completion — same confetti shower the bulk-archive uses.
-      if (card) {
-        const r = card.getBoundingClientRect();
-        spawnConfetti(r.left + r.width / 2, r.top + r.height / 2, 80);
-      }
-      const removed = _notes.splice(idx, 1)[0];
-      const undo = () => _undoArchive(removed, idx);
-      _pushUndo({ label: 'archive', run: undo });
-      const _undoIcon = '<svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round" style="vertical-align:middle;"><polyline points="9 14 4 9 9 4"/><path d="M4 9h11a5 5 0 0 1 5 5v0a5 5 0 0 1-5 5H9"/></svg>';
-      const finish = () => {
-        _renderNotes();
-        _patchNote(id, { archived: true }).then(() => {
-          uiModule.showToast('Archived', { duration: 6000, action: 'Undo', actionIcon: _undoIcon, onAction: undo, actionHint: 'Ctrl+Z' });
-        }).catch(() => {
-          _notes.splice(idx, 0, removed);
-          _renderNotes();
-          uiModule.showError('Failed to archive');
-        });
-      };
-      if (card) {
-        card.classList.add('note-card-sliding-out');
-        let done = false;
-        const once = () => { if (done) return; done = true; finish(); };
-        card.addEventListener('transitionend', once, { once: true });
-        setTimeout(once, 400);
-      } else {
-        finish();
-      }
-    });
-  });
-  // Unarchive corner — only visible in archive view.
-  body.querySelectorAll('.note-card-corner-unarchive').forEach(btn => {
-    btn.addEventListener('click', (e) => {
-      e.stopPropagation();
-      const id = btn.dataset.noteId;
-      const idx = _notes.findIndex(n => n.id === id);
-      if (idx < 0) return;
-      const removed = _notes.splice(idx, 1)[0];
-      _renderNotes();
-      _patchNote(id, { archived: false }).then(() => uiModule.showToast('Unarchived')).catch(() => {
-        _notes.splice(idx, 0, removed);
-        _renderNotes();
-        uiModule.showError('Failed to unarchive');
-      });
-    });
-  });
-  // Trash corner — archive view only. Permanent delete, no confirmation.
-  body.querySelectorAll('.note-card-corner-trash').forEach(btn => {
-    btn.addEventListener('click', (e) => {
-      e.stopPropagation();
-      const id = btn.dataset.noteId;
-      const idx = _notes.findIndex(n => n.id === id);
-      if (idx < 0) return;
-      const removed = _notes.splice(idx, 1)[0];
-      _renderNotes();
-      _deleteNoteApi(id).then(() => uiModule.showToast('Deleted')).catch(() => {
-        _notes.splice(idx, 0, removed);
-        _renderNotes();
-        uiModule.showError('Failed to delete');
-      });
-    });
-  });
-
-  body.querySelectorAll('.note-card-archive').forEach(btn => {
-    btn.addEventListener('click', (e) => {
-      e.stopPropagation();
-      const id = btn.dataset.noteId;
-      if (!id) return;
-      const card = btn.closest('.note-card');
-      let done = false;
-      const finishRemove = () => {
-        if (done) return;
-        done = true;
-        _archiveNoteById(id, { card, celebrate: true });
-      };
-      if (card) {
-        card.classList.add('note-card-sliding-out');
-        card.addEventListener('transitionend', finishRemove, { once: true });
-        setTimeout(finishRemove, 400);
-      } else {
-        finishRemove();
-      }
-    });
-  });
-  // Unarchive (optimistic) — only present in archive view
-  body.querySelectorAll('.note-card-unarchive').forEach(btn => {
-    btn.addEventListener('click', (e) => {
-      e.stopPropagation();
-      const id = btn.dataset.noteId;
-      const idx = _notes.findIndex(n => n.id === id);
-      if (idx < 0) return;
-      const removed = _notes.splice(idx, 1)[0];
-      _renderNotes();
-      _patchNote(id, { archived: false }).then(() => uiModule.showToast('Unarchived')).catch(() => {
-        _notes.splice(idx, 0, removed);
-        _renderNotes();
-        uiModule.showError('Failed to unarchive');
-      });
-    });
-  });
-  // Delete (optimistic)
-  body.querySelectorAll('.note-card-delete, .note-card-x').forEach(btn => {
-    btn.addEventListener('click', (e) => {
-      e.stopPropagation();
-      const id = btn.dataset.noteId;
-      const idx = _notes.findIndex(n => n.id === id);
-      if (idx < 0) return;
-      const removed = _notes.splice(idx, 1)[0];
-      _renderNotes();
-      _deleteNoteApi(id).catch(() => {
-        _notes.splice(idx, 0, removed);
-        _renderNotes();
-        uiModule.showError('Failed to delete');
-      });
-    });
-  });
-  // Copy entire checklist (title + items, markdown-style)
-  body.querySelectorAll('.note-card-copy').forEach(btn => {
-    btn.addEventListener('click', async (e) => {
-      e.preventDefault();
-      e.stopPropagation();
-      e.stopImmediatePropagation();
-      const id = btn.dataset.noteId;
-      const note = _notes.find(n => n.id === id);
-      if (!note) return;
-      const lines = [];
-      if (note.title) lines.push(note.title);
-      if (note.content) lines.push(note.content);
-      if (lines.length) lines.push('');
-      for (const it of (note.items || [])) {
-        if (!it || !(it.text || '').trim()) continue;
-        lines.push(`- [${it.done ? 'x' : ' '}] ${(it.text || '').trim()}`);
-      }
-      const text = lines.join('\n').trim();
-      try {
-        await navigator.clipboard.writeText(text);
-        uiModule.showToast?.(`Copied ${(note.items || []).filter(i => (i?.text || '').trim()).length} items`);
-      } catch {
-        // Fallback for browsers blocking the async API
-        const ta = document.createElement('textarea');
-        ta.value = text;
-        ta.style.position = 'fixed'; ta.style.left = '-9999px';
-        document.body.appendChild(ta);
-        ta.select();
-        try { document.execCommand('copy'); uiModule.showToast?.('Copied'); }
-        catch { uiModule.showError?.('Copy failed'); }
-        ta.remove();
-      }
-    });
-  });
-
-  // Remove a single checklist item (hover X)
-  body.querySelectorAll('.note-checkbox-rm').forEach(btn => {
-    btn.addEventListener('click', (e) => {
-      e.stopPropagation();
-      if (_selectMode) return;
-      const noteId = btn.dataset.noteId;
-      const idx = parseInt(btn.dataset.idx);
-      const note = _notes.find(n => n.id === noteId);
-      if (!note || !Array.isArray(note.items) || !note.items[idx]) return;
-      const removed = note.items[idx];
-      note.items = note.items.filter((_, i) => i !== idx);
-      _renderNotes();
-      _patchNote(noteId, { items: note.items }).catch(() => {
-        note.items.splice(idx, 0, removed);
-        _renderNotes();
-        uiModule.showError('Failed to remove item');
-      });
-    });
-  });
-
-  function _startChecklistItemEdit(noteId, idx, span) {
-    if (span.isContentEditable) return;
-    const note = _notes.find(n => n.id === noteId);
-    if (!note || !Array.isArray(note.items) || !note.items[idx]) return;
-
-    span.textContent = note.items[idx].text || '';
-    span.contentEditable = "true";
-    span.spellcheck = false;
-    span.focus();
-
-    const selection = window.getSelection();
-    const range = document.createRange();
-    range.selectNodeContents(span);
-    selection.removeAllRanges();
-    selection.addRange(range);
-
-    const save = () => {
-      if (!span.isContentEditable) return;
-      span.contentEditable = "false";
-      const newText = span.textContent.trim();
-      const oldText = (note.items[idx].text || '').trim();
-
-      if (newText === oldText) {
-        _renderNotes();
-        return;
-      }
-
-      const oldItem = note.items[idx];
-      if (!newText) {
-        note.items.splice(idx, 1);
-      } else {
-        note.items[idx].text = newText;
-      }
-
-      _patchNote(noteId, { items: note.items }).catch(() => {
-        if (!newText) note.items.splice(idx, 0, oldItem);
-        else note.items[idx].text = oldText;
-        _renderNotes();
-        uiModule.showError('Failed to update item');
-      });
-      _renderNotes();
-    };
-
-    const onKeydown = (e) => {
-      if (e.key === 'Enter') {
-        e.preventDefault();
-        save();
-      } else if (e.key === 'Escape') {
-        e.preventDefault();
-        span.contentEditable = "false";
-        _renderNotes();
-      }
-    };
-
-    span.addEventListener('blur', save, { once: true });
-    span.addEventListener('keydown', onKeydown);
-  }
-
-  // Edit a single checklist item (hover Edit button)
-  body.querySelectorAll('.note-checkbox-edit').forEach(btn => {
-    btn.addEventListener('click', (e) => {
-      e.stopPropagation();
-      if (_selectMode) return;
-      const noteId = btn.dataset.noteId;
-      const idx = parseInt(btn.dataset.idx);
-      const span = btn.parentElement.querySelector('.note-check-text');
-      if (span) _startChecklistItemEdit(noteId, idx, span);
-    });
-  });
-
-  // Prevent clicks from toggling the row while actively editing inline
-  body.querySelectorAll('.note-check-text').forEach(span => {
-    span.addEventListener('click', (e) => {
-      if (span.isContentEditable) {
-        e.stopPropagation();
-      }
-    });
-  });
-
-  // Quick-add new checklist item (hover input at bottom of todo cards)
-  body.querySelectorAll('.note-cl-quickadd-input').forEach(input => {
-    input.addEventListener('click', (e) => e.stopPropagation());
-    input.addEventListener('keydown', async (e) => {
-      e.stopPropagation();
-      if (e.key !== 'Enter') return;
-      e.preventDefault();
-      const text = input.value.trim();
-      if (!text) return;
-      const noteId = input.dataset.noteId;
-      const note = _notes.find(n => n.id === noteId);
-      if (!note) return;
-      const items = Array.isArray(note.items) ? [...note.items] : [];
-      items.push({ id: _uid(), text, done: false });
-      note.items = items;
-      input.value = '';
-      _renderNotes();
-      // Refocus the input on the same card
-      setTimeout(() => {
-        const next = document.querySelector(`.note-cl-quickadd-input[data-note-id="${noteId}"]`);
-        if (next) next.focus();
-      }, 0);
-      _patchNote(noteId, { items }).catch(() => {
-        note.items = items.slice(0, -1);
-        _renderNotes();
-        uiModule.showError('Failed to add item');
-      });
-    });
-  });
-
-  // Checkboxes (dot toggle, optimistic) — disabled in select mode
-  body.querySelectorAll('.note-checkbox').forEach(el => {
-    el.addEventListener('click', (e) => {
-      if (_selectMode) return; // let card-level handler take over
-      e.preventDefault();
-      e.stopPropagation();
-      const noteId = el.dataset.noteId;
-      const idx = parseInt(el.dataset.idx);
-      const note = _notes.find(n => n.id === noteId);
-      if (!note || !note.items || !note.items[idx]) return;
-      const wasAllDone = note.items.length > 0 && note.items.every(it => it.done);
-      note.items[idx].done = !note.items[idx].done;
-      el.classList.toggle('done', note.items[idx].done);
-      const isAllDone = note.items.length > 0 && note.items.every(it => it.done);
-      if (!wasAllDone && isAllDone) {
-        const card = el.closest('.note-card');
-        if (card) {
-          const r = card.getBoundingClientRect();
-          spawnConfetti(r.left + r.width / 2, r.top + r.height / 2, 60);
-        }
-      }
-      _patchNote(noteId, { items: note.items }).catch(() => {
-        note.items[idx].done = !note.items[idx].done;
-        el.classList.toggle('done', note.items[idx].done);
-      });
-    });
-  });
-
-  // Drag-reorder notes on pointer/mouse devices. Mobile uses the custom
-  // placeholder sorter below `_bindLongPressDrag`; native HTML5 dragging is
-  // unreliable on touch browsers and can compete with the long-press flow.
-  if (!_isNotesMobileMode()) {
-    body.querySelectorAll('.note-card').forEach(card => {
-      card.addEventListener('dragstart', (e) => {
-        if (e.target.closest('.note-checkbox, .note-card-x, .note-card-select, .note-card-pin, .note-card-action, .note-card-color-dot, .note-card-title, .note-card-edit, .note-card-edit-corner, .note-card-done, .note-card-corner-menu, .note-agent-tag, .note-card-label-chip')) {
-          e.preventDefault();
-          return;
-        }
-        card.classList.add('dragging');
-        body.classList.add('drag-active');
-        e.dataTransfer.effectAllowed = 'move';
-        try { e.dataTransfer.setData('text/plain', card.dataset.noteId); } catch {}
-      });
-      card.addEventListener('dragend', async () => {
-        card.classList.remove('dragging');
-        body.classList.remove('drag-active');
-        body.querySelectorAll('.drop-before, .drop-after').forEach(el => el.classList.remove('drop-before', 'drop-after'));
-        const ids = [...body.querySelectorAll('.note-card')].map(c => c.dataset.noteId);
-        try { await fetch(`${API_BASE}/api/notes/reorder`, { method: 'POST', credentials: 'same-origin', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ ids }) }); }
-        catch {}
-      });
-    });
-  }
-  // Track which card we last swapped with so a single hover-over triggers
-  // one swap, not a jitter as the pointer keeps moving inside the same card.
-  let _lastSwapId = null;
-  function _maybeSwap(dragging, clientX, clientY) {
-    const target = document.elementFromPoint(clientX, clientY)?.closest('.note-card');
-    if (!target || target === dragging || !body.contains(target)) return;
-    const id = target.dataset.noteId;
-    if (id === _lastSwapId) return;
-    // FLIP across ALL siblings. In list view only `target` moves visually, but
-    // in grid view (2-col) and when the pinned-section grid-column-start rule
-    // shifts, several cards reflow at once. Capture every card's pre-swap rect,
-    // do the DOM swap, then animate any that actually moved. The dragging card
-    // is excluded — it's already finger-tracked via translate3d.
-    const cards = [...body.querySelectorAll('.note-card')].filter(c => c !== dragging);
-    const prevRects = new Map(cards.map(c => [c, c.getBoundingClientRect()]));
-    const draggingNext = dragging.nextSibling === target ? dragging : dragging.nextSibling;
-    body.insertBefore(dragging, target);
-    body.insertBefore(target, draggingNext);
-    for (const c of cards) {
-      const prev = prevRects.get(c);
-      const next = c.getBoundingClientRect();
-      const dx = prev.left - next.left;
-      const dy = prev.top - next.top;
-      if (Math.abs(dx) < 0.5 && Math.abs(dy) < 0.5) continue;
-      c.style.transition = 'none';
-      c.style.transform = `translate(${dx}px, ${dy}px)`;
-      requestAnimationFrame(() => {
-        c.style.transition = 'transform 0.22s cubic-bezier(0.34, 1.2, 0.64, 1)';
-        c.style.transform = '';
-        c.addEventListener('transitionend', () => { c.style.transition = ''; }, { once: true });
-      });
-    }
-    _lastSwapId = id;
-  }
-  body.addEventListener('dragover', (e) => {
-    e.preventDefault();
-    const dragging = body.querySelector('.note-card.dragging');
-    if (!dragging) return;
-    _maybeSwap(dragging, e.clientX, e.clientY);
-  });
-  body.addEventListener('dragend', () => { _lastSwapId = null; });
-
-  // Legacy touch drag for larger touch devices only. Phone-sized Notes uses
-  // the placeholder sorter wired by `_bindLongPressDrag`; running both flows
-  // makes one press start two independent drag sessions.
-  if (!_isNotesMobileMode() && 'ontouchstart' in window && !body.dataset.touchDragBound) {
-    body.dataset.touchDragBound = '1';
-    let dragCard = null;
-    let isDragging = false;
-    let longPressTimer = null;
-    let startX = 0, startY = 0;
-    const LONG_PRESS_MS = 350;
-    const MOVE_THRESHOLD_PX = 8;
-    const _selectorSkip = '.note-checkbox, .note-card-x, .note-card-select, .note-card-pin, .note-card-action, .note-card-color-dot, .note-card-title, .note-card-edit, .note-card-edit-corner, .note-card-done, .note-card-corner-menu, .note-agent-tag, .note-card-label-chip, input, textarea, button, a';
-
-    // Anchor for the finger-follow transform. Recomputed after every swap so
-    // the card stays under the finger across reorderings.
-    let anchorX = 0, anchorY = 0;
-    const _follow = (clientX, clientY) => {
-      if (!dragCard) return;
-      const dx = clientX - anchorX;
-      const dy = clientY - anchorY;
-      // Compose with the CSS .dragging transform (scale + rotate).
-      dragCard.style.transform = `translate3d(${dx}px, ${dy}px, 0) scale(1.03) rotate(-0.6deg)`;
-    };
-    const _reanchor = (clientX, clientY) => {
-      if (!dragCard) return;
-      // Clear any prior translate so the card resettles in its natural slot,
-      // then anchor at the finger's current position. Subsequent _follow calls
-      // translate by (finger - anchor), keeping the finger at the same relative
-      // spot on the card it had when we re-anchored.
-      dragCard.style.transform = '';
-      anchorX = clientX;
-      anchorY = clientY;
-    };
-
-    const _endDrag = (committed) => {
-      clearTimeout(longPressTimer);
-      longPressTimer = null;
-      if (dragCard) {
-        dragCard.classList.remove('dragging');
-        dragCard.style.transform = '';
-      }
-      body.classList.remove('drag-active');
-      _lastSwapId = null;
-      if (isDragging) {
-        document.documentElement.style.touchAction = '';
-        if (committed) {
-          const ids = [...body.querySelectorAll('.note-card')].map(c => c.dataset.noteId);
-          fetch(`${API_BASE}/api/notes/reorder`, { method: 'POST', credentials: 'same-origin', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ ids }) }).catch(() => {});
-        }
-      }
-      dragCard = null;
-      isDragging = false;
-    };
-
-    body.addEventListener('touchstart', (e) => {
-      if (_selectMode) return;
-      const card = e.target.closest('.note-card');
-      if (!card) return;
-      if (e.target.closest(_selectorSkip)) return;
-      const t = e.touches[0];
-      startX = t.clientX; startY = t.clientY;
-      dragCard = card;
-      longPressTimer = setTimeout(() => {
-        if (!dragCard) return;
-        isDragging = true;
-        dragCard.classList.add('dragging');
-        body.classList.add('drag-active');
-        document.documentElement.style.touchAction = 'none';
-        _reanchor(startX, startY);
-        try { if (navigator.vibrate) navigator.vibrate(15); } catch {}
-      }, LONG_PRESS_MS);
-    }, { passive: true });
-
-    body.addEventListener('touchmove', (e) => {
-      if (!dragCard) return;
-      const t = e.touches[0];
-      if (!isDragging) {
-        // Movement before long-press fires = user is scrolling; cancel pickup.
-        if (Math.abs(t.clientX - startX) > MOVE_THRESHOLD_PX || Math.abs(t.clientY - startY) > MOVE_THRESHOLD_PX) {
-          clearTimeout(longPressTimer);
-          longPressTimer = null;
-          dragCard = null;
-        }
-        return;
-      }
-      e.preventDefault();
-      // Live-follow the finger first, then check for a swap. After a swap the
-      // card's natural slot moves, so we re-anchor and re-apply the offset.
-      _follow(t.clientX, t.clientY);
-      const before = dragCard.parentNode && [...dragCard.parentNode.children].indexOf(dragCard);
-      _maybeSwap(dragCard, t.clientX, t.clientY);
-      const after = dragCard.parentNode && [...dragCard.parentNode.children].indexOf(dragCard);
-      if (before !== after) {
-        _reanchor(t.clientX, t.clientY);
-        _follow(t.clientX, t.clientY);
-      }
-    }, { passive: false });
-
-    body.addEventListener('touchend', () => _endDrag(true));
-    body.addEventListener('touchcancel', () => _endDrag(false));
-  }
-}
-
-// ── Draft autosave ──────────────────────────────────────────────────
-// While a note is open in the editor, its form is snapshotted to
-// localStorage on every change. If the connection drops, the
-// tab closes, or the page reloads before Save is hit, reopening that note
-// restores the unsaved text. Clear only after confirmed persistence.
-const _DRAFT_PREFIX = 'odysseus-note-draft-';
-function _draftKey(id) { return _DRAFT_PREFIX + (id || '__new__'); }
-function _loadDraft(id) {
-  try { return JSON.parse(localStorage.getItem(_draftKey(id)) || 'null'); } catch { return null; }
-}
-function _clearDraft(id) { try { localStorage.removeItem(_draftKey(id)); } catch {} }
-function _collectFormDraft(form) {
-  if (!form) return null;
-  const type = form.querySelector('.note-form-type-pill.active')?.dataset.type || form.dataset.noteType || 'note';
-  const d = {
-    _ts: Date.now(),
-    note_type: type,
-    color: form.dataset.noteColor || '',
-    title: form.querySelector('.note-form-title')?.value || '',
-    label: form.querySelector('.note-form-label')?.value || '',
-    due_date: form.querySelector('.note-form-due')?.value || null,
-    repeat: form.querySelector('.note-form-repeat')?.value || 'none',
-  };
-  if (type === 'note') d.content = form.querySelector('.note-form-content')?.value || '';
-  else if (type === 'goal') { d.content = form.querySelector('.note-form-goal-desc')?.value || ''; d.items = _collectItems(form); }
-  else d.items = _collectItems(form);
-  return d;
-}
-function _isDraftEmpty(d) {
-  if (!d) return true;
-  if ((d.title || '').trim()) return false;
-  if ((d.content || '').trim()) return false;
-  if (Array.isArray(d.items) && d.items.some(it => (it.text || '').trim())) return false;
-  return true;
-}
-function _wireDraftAutosave(form, id) {
-  let t = null;
-  let pending = Promise.resolve();
-  let stopped = false;
-  let warned = false;
-  const save = () => {
-    const d = _collectFormDraft(form);
-    // An empty edit can be intentional: don't restore stale server text over it.
-    try { localStorage.setItem(_draftKey(id), JSON.stringify(d)); }
-    catch {
-      if (!warned) uiModule.showError('Draft backup unavailable. Keep this note open until saved.');
-      warned = true;
-    }
-    return d;
-  };
-  const persist = (d) => {
-    if (!id || id === '__new__' || d.note_type === 'draw') return pending;
-    const { _ts, ...payload } = d;
-    payload.label = [...new Set(payload.label.split(/\s+/).map(s => s.replace(/^#+/, '')).filter(Boolean))].join(' ') || null;
-    pending = pending.then(async () => {
-      try {
-        await _patchNote(id, payload);
-        form._autosaveFailed = false;
-        const note = _notes.find(n => n.id === id);
-        if (note) Object.assign(note, payload);
-        if (localStorage.getItem(_draftKey(id)) === JSON.stringify(d)) _clearDraft(id);
-      } catch {
-        if (!form._autosaveFailed) uiModule.showError('Note not synced. Your edits are kept on this device; retry Save.');
-        form._autosaveFailed = true;
-      }
-    });
-    return pending;
-  };
-  form._flushDraft = () => { clearTimeout(t); return save(); };
-  form._stopDraftAutosave = () => { stopped = true; clearTimeout(t); return pending; };
-  const sched = () => {
-    const d = save();
-    if (stopped) return;
-    clearTimeout(t);
-    t = setTimeout(() => persist(d), 500);
-  };
-  form.addEventListener('input', sched);
-  form.addEventListener('change', sched);
-  form.addEventListener('click', (event) => {
-    if (event.target.closest('.note-cl-dot, .note-cl-rm')) sched();
-  });
-}
-
-// Commit whatever in-place editor is open (called when the panel closes
-// or another note is opened) so edits aren't lost when the user navigates
-// away without clicking Save. Empty notes are discarded instead of saved.
-function _commitOpenInPlaceEditor() {
-  const form = document.querySelector('#notes-pane .note-form');
-  if (!form) return;
-  const d = _collectFormDraft(form);
-  if (_isDraftEmpty(d)) { form.querySelector('.note-form-cancel')?.click(); return; }
-  form.querySelector('.note-form-save')?.click();
-}
-// Merge a stored draft over a note so _buildForm renders the unsaved edits.
-function _applyDraftToNote(note, id) {
-  const d = _loadDraft(id);
-  if (!d) return { note, restored: false };
-  const merged = { ...(note || {}) };
-  ['note_type', 'color', 'title', 'label', 'due_date', 'repeat', 'content', 'items'].forEach(k => {
-    if (d[k] !== undefined) merged[k] = d[k];
-  });
-  return { note: merged, restored: true };
-}
-
-// ---- Create / Edit Form ----
-
-function _buildForm(note = null) {
-  const isEdit = note && note.id;
-  const type = note?.note_type === 'checklist' ? 'todo' : (note?.note_type || 'note');
-  const color = note?.color || '';
-  const items = note?.items || [{ id: _uid(), text: '', done: false }];
-
-  const form = document.createElement('div');
-  form.className = 'note-form';
-  form.dataset.noteType = type;
-  form.dataset.noteColor = color || '';
-  if (color && !_isBgImage(color)) form.classList.add('note-color-' + color);
-  if (_isBgImage(color)) form.setAttribute('style', _customColorStyle(color));
-  let currentImageUrl = _safeImgSrc(note?.image_url || '');
-  form.innerHTML = `
-    <div class="note-form-header">
-      <input type="text" class="note-form-title" placeholder="Title" value="${_esc(note?.title || '')}" />
-      <button type="button" class="note-form-icon-btn note-form-remind-btn${note?.due_date ? ' has-date' : ''}" title="Remind me">
-        <svg width="31" height="31" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M18 8A6 6 0 0 0 6 8c0 7-3 9-3 9h18s-3-2-3-9"/><path d="M13.73 21a2 2 0 0 1-3.46 0"/></svg>
-      </button>
-      <input type="hidden" class="note-form-due" value="${note?.due_date || ''}" />
-      <input type="hidden" class="note-form-repeat" value="${note?.repeat || 'none'}" />
-    </div>
-    ${currentImageUrl && type !== 'draw' ? `<div class="note-form-image-wrap"><img class="note-form-image" src="${_esc(currentImageUrl)}" draggable="false" /><button class="note-form-image-rm" title="Remove">&times;</button></div>` : ''}
-    <div class="note-form-body">
-      ${type === 'note'
-        ? `<textarea class="note-form-content" placeholder="Take a note..." rows="4">${_esc(note?.content || '')}</textarea>`
-        : type === 'draw'
-        ? _buildDrawHtml()
-        : type === 'goal'
-        ? _buildGoalHtml(note, items)
-        : _buildChecklistHtml(items)}
-    </div>
-    <div class="note-form-reminder-tags"></div>
-    <div class="note-form-meta">
-      <div class="note-form-type-seg${type === 'todo' ? ' is-todo' : type === 'draw' ? ' is-draw' : ''}" role="group">
-        <button type="button" class="note-form-type-pill${type === 'note' ? ' active' : ''}" data-type="note">
-          <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><line x1="4" y1="6" x2="20" y2="6"/><line x1="4" y1="12" x2="20" y2="12"/><line x1="4" y1="18" x2="14" y2="18"/></svg>
-          <span>Note</span>
-        </button>
-        <button type="button" class="note-form-type-pill${type === 'todo' ? ' active' : ''}" data-type="todo">
-          <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><polyline points="9 11 12 14 22 4"/><path d="M21 12v7a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2h11"/></svg>
-          <span>Todo</span>
-        </button>
-        <button type="button" class="note-form-type-pill${type === 'draw' ? ' active' : ''}" data-type="draw">
-          <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M12 19l7-7 3 3-7 7-3-3z"/><path d="M18 13l-1.5-7.5L2 2l3.5 14.5L13 18l5-5z"/><path d="M2 2l7.586 7.586"/><circle cx="11" cy="11" r="2"/></svg>
-          <span>Draw</span>
-        </button>
-      </div>
-      <button class="note-form-photo-btn" title="Attach photo">
-        <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="3" y="3" width="18" height="18" rx="2"/><circle cx="8.5" cy="8.5" r="1.5"/><polyline points="21 15 16 10 5 21"/></svg>
-      </button>
-      <input type="file" class="note-form-photo-input" accept="image/*" capture="environment" style="display:none" />
-      <div class="note-color-picker">
-        ${COLORS.map(c => `<span class="note-color-dot${_dotIsActive(c.value, color) ? ' active' : ''}" data-color="${c.value}" style="background:${_dotBg(c.value, color)}" title="${c.name || 'default'}"></span>`).join('')}
-      </div>
-      <input type="text" class="note-form-label" value="${_esc(note?.label || '')}" placeholder="#tag1 #tag2" title="Tag(s) — space-separated" />
-      <div class="note-form-actions-group">
-        ${isEdit ? `
-        <button type="button" class="note-form-text-btn note-form-archive-btn note-form-collapsible" title="Archive">
-          <svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="2" y="3" width="20" height="5" rx="1"/><path d="M4 8v11a2 2 0 002 2h12a2 2 0 002-2V8"/><path d="M10 12h4"/></svg><span class="nft-label">Archive</span>
-        </button>
-        <button type="button" class="note-form-text-btn note-form-delete-btn note-form-collapsible danger" title="Delete">
-          <svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><polyline points="3 6 5 6 21 6"/><path d="M19 6l-1 14a2 2 0 0 1-2 2H8a2 2 0 0 1-2-2L5 6"/><path d="M8 6V4a2 2 0 0 1 2-2h4a2 2 0 0 1 2 2v2"/><line x1="10" y1="11" x2="10" y2="17"/><line x1="14" y1="11" x2="14" y2="17"/></svg><span class="nft-label">Delete</span>
-        </button>
-        ` : ''}
-        <span class="note-form-actions-spacer"></span>
-        <button class="note-form-cancel note-form-text-btn note-form-collapsible" title="Close (keep changes)">
-          <svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.2" stroke-linecap="round"><line x1="6" y1="6" x2="18" y2="18"/><line x1="18" y1="6" x2="6" y2="18"/></svg><span class="nft-label">Close</span>
-        </button>
-        <button class="note-form-save note-form-text-btn" title="${isEdit ? 'Update' : 'Save'}">
-          <svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.4" stroke-linecap="round" stroke-linejoin="round"><polyline points="20 6 9 17 4 12"/></svg><span class="nft-label">${isEdit ? 'Update' : 'Save'}</span>
-        </button>
-      </div>
-    </div>
-  `;
-
-  let currentType = type;
-  let currentColor = color;
-  // Stash original-form values so round-trips (Note→Todo→Note) restore the
-  // user's hand-formatted text instead of a join of generated items. Same the
-  // other way: if you started in todo, switch to note, switch back, items
-  // come back unchanged.
-  let _stashedNoteText = (type === 'note') ? (note?.content || '') : null;
-  let _stashedTodoItems = (type === 'todo' && Array.isArray(note?.items)) ? note.items.slice() : null;
-  // Goal mode kept its own pair of stashes (description + steps) so a
-  // Todo→Goal→Todo round-trip wouldn't lose either side. The Goal pill in
-  // the type picker was later removed, so the only entry point now is
-  // *editing* an existing goal-typed note — but the switch handler still
-  // accepts Goal→Todo/Note transitions (downgrading legacy goals), so
-  // these stashes still earn their keep.
-  let _stashedGoalDesc = (type === 'goal') ? (note?.content || '') : null;
-  let _stashedGoalItems = (type === 'goal' && Array.isArray(note?.items)) ? note.items.slice() : null;
-
-  // Drawing also stashes the saved image URL so it survives Note↔Draw flips.
-  let _stashedDrawUrl = (type === 'draw') ? (_safeImgSrc(note?.image_url) || null) : null;
-  const _refreshFormLayout = () => {
-    const body = form.closest('.notes-pane-body');
-    if (!body) return;
-    _applyMasonry(body);
-    requestAnimationFrame(() => {
-      _applyMasonry(body);
-      requestAnimationFrame(() => _applyMasonry(body));
-    });
-  };
-
-  // Type segmented control — Note | Todo | Draw
-  form.querySelectorAll('.note-form-type-pill').forEach(pill => {
-    pill.addEventListener('click', () => {
-      const newType = pill.dataset.type;
-      if (newType === currentType) return;
-      const bodyEl = form.querySelector('.note-form-body');
-      // Stash whatever the user has in the current mode before swapping it
-      // out, so a subsequent flip back restores their work.
-      if (currentType === 'note') {
-        _stashedNoteText = form.querySelector('.note-form-content')?.value || '';
-      } else if (currentType === 'todo') {
-        _stashedTodoItems = _collectItems(form);
-      } else if (currentType === 'goal') {
-        _stashedGoalDesc = form.querySelector('.note-form-goal-desc')?.value || '';
-        _stashedGoalItems = _collectItems(form);
-      } else if (currentType === 'draw') {
-        const c = form.querySelector('.note-form-canvas');
-        if (c) { try { _stashedDrawUrl = c.toDataURL('image/png'); } catch {} }
-      }
-      // Render the new mode's body and re-wire its inputs.
-      if (newType === 'todo') {
-        let nextItems;
-        if (_stashedTodoItems && _stashedTodoItems.length) {
-          nextItems = _stashedTodoItems;
-        } else if (_stashedGoalItems && _stashedGoalItems.length) {
-          // Going Goal→Todo keeps the AI-generated steps as a plain checklist.
-          nextItems = _stashedGoalItems;
-        } else if (_stashedNoteText) {
-          const lines = _stashedNoteText.split('\n').map(s => s.trim()).filter(Boolean);
-          nextItems = lines.length ? lines.map(t => ({ id: _uid(), text: t, done: false })) : [{ id: _uid(), text: '', done: false }];
-        } else {
-          nextItems = [{ id: _uid(), text: '', done: false }];
-        }
-        bodyEl.innerHTML = _buildChecklistHtml(nextItems);
-        _wireChecklist(bodyEl);
-      } else if (newType === 'draw') {
-        bodyEl.innerHTML = _buildDrawHtml();
-        // If the user just attached a photo (via the photo button) and then
-        // toggled to Draw, paint that photo onto the canvas so they can draw
-        // on top of it. _stashedDrawUrl wins if they were drawing earlier in
-        // the same edit session.
-        _wireCanvas(bodyEl, _stashedDrawUrl || currentImageUrl || _safeImgSrc(note?.image_url) || null);
-      } else {
-        const text = (_stashedNoteText !== null && _stashedNoteText !== undefined && _stashedNoteText !== '')
-          ? _stashedNoteText
-          : (_stashedGoalDesc && _stashedGoalDesc)
-          || (_stashedTodoItems || _stashedGoalItems || []).map(i => i.text).join('\n');
-        bodyEl.innerHTML = `<textarea class="note-form-content" placeholder="Take a note..." rows="4">${_esc(text)}</textarea>`;
-        _wireHashtag(bodyEl.querySelector('.note-form-content'));
-      }
-      const focusEl = newType === 'note'
-        ? bodyEl.querySelector('.note-form-content')
-        : newType === 'todo'
-          ? bodyEl.querySelector('.note-cl-text')
-          : null;
-      if (focusEl) {
-        requestAnimationFrame(() => {
-          focusEl.focus({ preventScroll: true });
-          try {
-            const end = focusEl.value.length;
-            focusEl.setSelectionRange(end, end);
-          } catch {}
-        });
-      }
-      currentType = newType;
-      const seg = form.querySelector('.note-form-type-seg');
-      seg?.classList.toggle('is-todo', newType === 'todo');
-      seg?.classList.toggle('is-draw', newType === 'draw');
-      form.querySelectorAll('.note-form-type-pill').forEach(p => p.classList.toggle('active', p.dataset.type === newType));
-      // The standalone image preview (form-image-wrap) and the canvas would
-      // otherwise both show the same image_url when editing a drawn note.
-      // Hide it in draw mode, restore it when leaving draw mode.
-      const imgWrap = form.querySelector('.note-form-image-wrap');
-      if (imgWrap) imgWrap.style.display = (newType === 'draw') ? 'none' : '';
-      // The background-color dots set the note card's bg — they make no sense
-      // for a drawn note (the canvas image IS the card content), so hide them.
-      const bgPicker = form.querySelector('.note-color-picker');
-      if (bgPicker) bgPicker.style.display = (newType === 'draw') ? 'none' : '';
-      if (form.closest('.notes-pane.notes-view-grid') && window.matchMedia('(max-width: 768px)').matches) {
-        form.style.gridColumn = '1 / -1';
-        form.style.gridRowEnd = newType === 'draw' ? 'span 152' : 'span 64';
-      }
-      _refreshFormLayout();
-    });
-  });
-
-  // Slide a finger across the Note/Todo/Draw control to switch modes (mobile).
-  // On touchmove we find the pill under the finger and click it — reusing the
-  // pill click handler above, so the body re-renders + content stashing all
-  // work. Only fires when crossing into a *different* pill.
-  const _typeSeg = form.querySelector('.note-form-type-seg');
-  if (_typeSeg) {
-    let _sliding = false;
-    const _activateAt = (x, y) => {
-      const pill = document.elementFromPoint(x, y)?.closest?.('.note-form-type-pill');
-      if (pill && !pill.classList.contains('active')) pill.click();
-    };
-    _typeSeg.addEventListener('touchstart', () => { _sliding = true; }, { passive: true });
-    _typeSeg.addEventListener('touchmove', (e) => {
-      if (_sliding && e.touches[0]) _activateAt(e.touches[0].clientX, e.touches[0].clientY);
-    }, { passive: true });
-    _typeSeg.addEventListener('touchend', () => { _sliding = false; });
-    _typeSeg.addEventListener('touchcancel', () => { _sliding = false; });
-  }
-
-  // Color dots — apply to entire form immediately
-  const _applyFormColor = (newColor) => {
-    currentColor = newColor || '';
-    form.dataset.noteColor = currentColor;
-    const isBg = _isBgImage(currentColor);
-    COLORS.forEach(c => { if (c.value && c.value !== 'custom') form.classList.remove('note-color-' + c.value); });
-    if (currentColor && !isBg) form.classList.add('note-color-' + currentColor);
-    if (isBg) form.setAttribute('style', _customColorStyle(currentColor));
-    else form.removeAttribute('style');
-    form.querySelectorAll('.note-color-dot').forEach(d => {
-      d.classList.toggle('active', _dotIsActive(d.dataset.color, currentColor));
-      d.style.background = _dotBg(d.dataset.color, currentColor);
-    });
-    form.dispatchEvent(new Event('change', { bubbles: true }));
-  };
-  form.querySelectorAll('.note-color-dot').forEach(dot => {
-    dot.addEventListener('click', () => {
-      if (dot.dataset.color === 'custom') {
-        _pickCustomBgImage().then(url => { if (url) _applyFormColor('bg:' + url); });
-        return;
-      }
-      _applyFormColor(dot.dataset.color);
-    });
-  });
-
-  if (currentType === 'todo') _wireChecklist(form.querySelector('.note-form-body'));
-  if (currentType === 'goal') _wireGoalForm(form, form.querySelector('.note-form-body'));
-  if (currentType === 'draw') {
-    _wireCanvas(form.querySelector('.note-form-body'), _safeImgSrc(note?.image_url) || null);
-    // Same hides we apply on type-switch — keep them consistent on initial open.
-    const _ip = form.querySelector('.note-form-image-wrap'); if (_ip) _ip.style.display = 'none';
-    const _cp = form.querySelector('.note-color-picker'); if (_cp) _cp.style.display = 'none';
-  }
-
-  // Auto-grow the plain-note textarea so editing longer notes is
-  // comfortable — it expands with the content (up to a cap) instead of
-  // staying a cramped 4-row box. The user can still drag-resize too.
-  const _contentTa = form.querySelector('.note-form-content');
-  if (_contentTa) {
-    const _grow = () => {
-      _contentTa.style.height = 'auto';
-      // Inline form: cap at ~50vh so a huge note doesn't push the action
-      // buttons off-screen. Fullscreen mobile overlay: the body scrolls and
-      // there are no inline buttons crowding, so allow nearly the full height
-      // — capping at 50vh there clipped longer notes ("part disappears").
-      const inFullscreen = !!_contentTa.closest('.note-fullscreen-overlay');
-      const max = Math.round(window.innerHeight * (inFullscreen ? 0.9 : 0.5));
-      _contentTa.style.height = Math.min(_contentTa.scrollHeight, max) + 'px';
-    };
-    _contentTa.addEventListener('input', _grow);
-    // Grow on open so existing content is fully visible. Run again after the
-    // fullscreen overlay's open animation settles — measuring mid-animation
-    // (the overlay starts scaled/transitioning) can under-size the box.
-    setTimeout(_grow, 0);
-    setTimeout(_grow, 360);
-  }
-
-  // Reminder bell — opens dropdown menu
-  const remindBtn = form.querySelector('.note-form-remind-btn');
-  const dueInput = form.querySelector('.note-form-due');
-  const repeatInput = form.querySelector('.note-form-repeat');
-  const tagsEl = form.querySelector('.note-form-reminder-tags');
-
-  function _renderReminderTag() {
-    if (!tagsEl) return;
-    const v = dueInput.value;
-    const rep = repeatInput.value || 'none';
-    if (!v) { tagsEl.innerHTML = ''; return; }
-    const label = _formatReminderTag(v);
-    const repLabel = rep !== 'none' ? ` · ${_formatRepeatLabel(rep, new Date(v))}` : '';
-    tagsEl.innerHTML = `<button class="note-reminder-tag" type="button" title="Edit reminder">
-      <svg width="11" height="11" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round"><path d="M18 8A6 6 0 0 0 6 8c0 7-3 9-3 9h18s-3-2-3-9"/><path d="M13.73 21a2 2 0 0 1-3.46 0"/></svg>
-      <span>${_esc(label)}${_esc(repLabel)}</span>
-      <span class="note-reminder-tag-x" title="Remove">×</span>
-    </button>`;
-    tagsEl.querySelector('.note-reminder-tag').addEventListener('click', (e) => {
-      if (e.target.classList.contains('note-reminder-tag-x')) {
-        dueInput.value = '';
-        repeatInput.value = 'none';
-        _renderReminderTag();
-        return;
-      }
-      _openReminderMenu(remindBtn || tagsEl, true);
-    });
-  }
-
-  function _openReminderMenu(anchor, isEdit = false) {
-    // Close any existing menu
-    document.querySelectorAll('.note-reminder-menu').forEach(m => m.remove());
-    const menu = document.createElement('div');
-    menu.className = 'note-reminder-menu';
-    document.body.appendChild(menu);
-
-    const presetItems = [
-      { label: 'Later today', sub: _laterTodayDate().toLocaleTimeString([], { hour: 'numeric', minute: '2-digit' }), action: () => _setReminder(_toLocalDatetimeStr(_laterTodayDate())) },
-      { label: 'Tomorrow', sub: _tomorrowDate().toLocaleTimeString([], { hour: 'numeric', minute: '2-digit' }), action: () => _setReminder(_toLocalDatetimeStr(_tomorrowDate())) },
-      { label: 'Next week', sub: _nextWeekDate().toLocaleDateString([], { weekday: 'short' }) + ' ' + _nextWeekDate().toLocaleTimeString([], { hour: 'numeric', minute: '2-digit' }), action: () => _setReminder(_toLocalDatetimeStr(_nextWeekDate())) },
-      { label: 'Select date and time', sub: '', action: () => _pickCustomDate() },
-    ];
-
-    // Sub-page state for the repeat picker. null = top page.
-    // 'weekly' | 'monthly' | 'monthly_nth'
-    let subMode = null;
-    // Temporary state for monthly_nth so user can click N then weekday (or vice versa)
-    // before committing.
-    let nthDraft = { n: 0, w: -1 };
-
-    const DAY_SHORT = ['S', 'M', 'T', 'W', 'T', 'F', 'S'];
-
-    function getNorm() {
-      if (!dueInput.value) return 'none';
-      return _normalizeRepeat(repeatInput.value || 'none', new Date(dueInput.value));
-    }
-
-    function commit(val) {
-      repeatInput.value = val;
-      _renderReminderTag();
-      menu.remove();
-    }
-
-    // Like commit, but first snaps dueInput.value forward to the next matching
-    // slot for the chosen recurrence. Use for weekly/monthly variants where the
-    // current due date may not match the chosen pattern (e.g. user picks
-    // "weekly on Mondays" while the date is a Wednesday).
-    function snapAndCommit(val) {
-      if (dueInput.value) {
-        const cur = new Date(dueInput.value);
-        const norm = _normalizeRepeat(val, cur);
-        const snapped = _snapToRepeat(cur, norm);
-        if (snapped) {
-          dueInput.value = _toLocalDatetimeStr(snapped);
-          if (remindBtn) remindBtn.classList.add('has-date');
-        }
-      }
-      commit(val);
-    }
-
-    function reposition() {
-      const rect = anchor.getBoundingClientRect();
-      const vw = window.innerWidth;
-      const vh = window.innerHeight;
-      const mw = menu.offsetWidth || 220;
-      const mh = menu.offsetHeight || 280;
-      let top = rect.bottom + 4;
-      let left = rect.left;
-      if (top + mh > vh - 8) top = Math.max(8, rect.top - mh - 4);
-      if (left + mw > vw - 8) left = Math.max(8, vw - mw - 8);
-      if (left < 8) left = 8;
-      menu.style.top = top + 'px';
-      menu.style.left = left + 'px';
-    }
-
-    function render() {
-      let html = '';
-
-      if (subMode === null) {
-        html += '<div class="note-reminder-menu-title">Remind me later</div>';
-        for (let i = 0; i < presetItems.length; i++) {
-          const it = presetItems[i];
-          html += `<button class="note-reminder-menu-item" data-action="preset" data-i="${i}"><span>${it.label}</span><span class="note-reminder-menu-sub">${it.sub}</span></button>`;
-        }
-        if (isEdit && dueInput.value) {
-          const norm = getNorm();
-          html += '<div class="note-reminder-menu-divider"></div>';
-          html += '<div class="note-reminder-menu-title">Repeat</div>';
-          // None
-          html += `<button class="note-reminder-menu-item${norm === 'none' ? ' active' : ''}" data-action="set" data-val="none"><span>Doesn't repeat</span>${norm === 'none' ? '<span class="note-reminder-menu-check">✓</span>' : ''}</button>`;
-          // Daily
-          html += `<button class="note-reminder-menu-item${norm === 'daily' ? ' active' : ''}" data-action="set" data-val="daily"><span>Daily</span>${norm === 'daily' ? '<span class="note-reminder-menu-check">✓</span>' : ''}</button>`;
-          // Weekly →
-          {
-            const isW = norm.startsWith('weekly:');
-            const wd = isW ? parseInt(norm.split(':')[1], 10) : null;
-            const sub = isW && !isNaN(wd) ? `<span class="note-reminder-menu-sub">${_DAYS[wd]}</span>` : '';
-            html += `<button class="note-reminder-menu-item${isW ? ' active' : ''}" data-action="sub" data-sub="weekly"><span>Weekly</span>${sub}<span class="note-reminder-menu-arrow">›</span></button>`;
-          }
-          // Monthly →
-          {
-            const isM = norm.startsWith('monthly:');
-            const sub = isM ? `<span class="note-reminder-menu-sub">${_monthlyShortDescriptor(norm)}</span>` : '';
-            html += `<button class="note-reminder-menu-item${isM ? ' active' : ''}" data-action="sub" data-sub="monthly"><span>Monthly</span>${sub}<span class="note-reminder-menu-arrow">›</span></button>`;
-          }
-          // Yearly
-          html += `<button class="note-reminder-menu-item${norm === 'yearly' ? ' active' : ''}" data-action="set" data-val="yearly"><span>Yearly</span>${norm === 'yearly' ? '<span class="note-reminder-menu-check">✓</span>' : ''}</button>`;
-        }
-      } else if (subMode === 'weekly') {
-        const norm = getNorm();
-        const curWd = norm.startsWith('weekly:') ? parseInt(norm.split(':')[1], 10) : -1;
-        html += `<button class="note-reminder-menu-back" data-action="back"><span class="note-reminder-menu-arrow-back">‹</span> Repeat</button>`;
-        html += '<div class="note-reminder-menu-title">Weekly on…</div>';
-        html += '<div class="note-reminder-weekday-row">';
-        for (let i = 0; i < 7; i++) {
-          html += `<button class="note-reminder-day-chip${curWd === i ? ' active' : ''}" data-action="weekly-pick" data-wd="${i}" title="${_DAYS[i]}">${DAY_SHORT[i]}</button>`;
-        }
-        html += '</div>';
-      } else if (subMode === 'monthly') {
-        const norm = getNorm();
-        const dueDate = new Date(dueInput.value);
-        const dayN = dueDate.getDate();
-        html += `<button class="note-reminder-menu-back" data-action="back"><span class="note-reminder-menu-arrow-back">‹</span> Repeat</button>`;
-        html += '<div class="note-reminder-menu-title">Monthly on…</div>';
-        // Day N — uses the chosen date's day. Always offered.
-        const dayVal = `monthly:day:${dayN}`;
-        html += `<button class="note-reminder-menu-item${norm === dayVal ? ' active' : ''}" data-action="set" data-val="${dayVal}"><span>Day ${dayN} every month</span>${norm === dayVal ? '<span class="note-reminder-menu-check">✓</span>' : ''}</button>`;
-        // Nth weekday →
-        {
-          const isNth = norm.startsWith('monthly:nth:');
-          const sub = isNth ? `<span class="note-reminder-menu-sub">${_monthlyShortDescriptor(norm)}</span>` : '';
-          html += `<button class="note-reminder-menu-item${isNth ? ' active' : ''}" data-action="sub" data-sub="monthly_nth"><span>Nth weekday</span>${sub}<span class="note-reminder-menu-arrow">›</span></button>`;
-        }
-      } else if (subMode === 'monthly_nth') {
-        // Pick ordinal (1..4) and weekday (0..6); commit when both chosen.
-        html += `<button class="note-reminder-menu-back" data-action="back-monthly"><span class="note-reminder-menu-arrow-back">‹</span> Monthly</button>`;
-        html += '<div class="note-reminder-menu-title">Nth weekday of month</div>';
-        html += '<div class="note-reminder-menu-sublabel">Which one</div>';
-        html += '<div class="note-reminder-weekday-row">';
-        for (let i = 1; i <= 4; i++) {
-          html += `<button class="note-reminder-day-chip wide${nthDraft.n === i ? ' active' : ''}" data-action="nth-n" data-n="${i}">${_ORDINALS[i - 1]}</button>`;
-        }
-        html += '</div>';
-        html += '<div class="note-reminder-menu-sublabel">Weekday</div>';
-        html += '<div class="note-reminder-weekday-row">';
-        for (let i = 0; i < 7; i++) {
-          html += `<button class="note-reminder-day-chip${nthDraft.w === i ? ' active' : ''}" data-action="nth-w" data-wd="${i}" title="${_DAYS[i]}">${DAY_SHORT[i]}</button>`;
-        }
-        html += '</div>';
-        html += '<div class="note-reminder-menu-divider"></div>';
-        const ready = nthDraft.n > 0 && nthDraft.w >= 0;
-        const lbl = ready ? `Save: ${_ORDINALS[nthDraft.n - 1]} ${_DAYS[nthDraft.w]}` : 'Pick week and weekday';
-        html += `<button class="note-reminder-menu-item note-reminder-menu-confirm${ready ? '' : ' disabled'}" data-action="nth-save" ${ready ? '' : 'disabled'}><span>${lbl}</span></button>`;
-      }
-
-      menu.innerHTML = html;
-      reposition();
-      wire();
-    }
-
-    function wire() {
-      menu.querySelectorAll('[data-action]').forEach(el => {
-        el.addEventListener('click', (e) => {
-          e.stopPropagation();
-          const a = el.dataset.action;
-          if (a === 'preset') {
-            const it = presetItems[parseInt(el.dataset.i, 10)];
-            it.action();
-            menu.remove();
-          } else if (a === 'set') {
-            snapAndCommit(el.dataset.val);
-          } else if (a === 'sub') {
-            subMode = el.dataset.sub;
-            // Seed nth draft from saved value only on first entry — preserve
-            // in-progress picks across back-trips (Nth → back → Nth again).
-            if (subMode === 'monthly_nth' && nthDraft.n === 0 && nthDraft.w === -1) {
-              const norm = getNorm();
-              const m = norm.match(/^monthly:nth:(\d):(\d)$/);
-              if (m) nthDraft = { n: parseInt(m[1], 10), w: parseInt(m[2], 10) };
-            }
-            render();
-          } else if (a === 'back') {
-            subMode = null;
-            render();
-          } else if (a === 'back-monthly') {
-            subMode = 'monthly';
-            render();
-          } else if (a === 'weekly-pick') {
-            snapAndCommit(`weekly:${el.dataset.wd}`);
-          } else if (a === 'nth-n') {
-            nthDraft.n = parseInt(el.dataset.n, 10);
-            render();
-          } else if (a === 'nth-w') {
-            nthDraft.w = parseInt(el.dataset.wd, 10);
-            render();
-          } else if (a === 'nth-save') {
-            if (nthDraft.n > 0 && nthDraft.w >= 0) {
-              snapAndCommit(`monthly:nth:${nthDraft.n}:${nthDraft.w}`);
-            }
-          }
-        });
-      });
-    }
-
-    render();
-    // Click outside to close (single global handler attached after first paint)
-    setTimeout(() => {
-      const close = (e) => {
-        if (!menu.isConnected) { document.removeEventListener('click', close); return; }
-        if (!menu.contains(e.target)) { menu.remove(); document.removeEventListener('click', close); }
-      };
-      document.addEventListener('click', close);
-    }, 0);
-  }
-
-  function _monthlyShortDescriptor(norm) {
-    const parts = norm.split(':');
-    if (parts[1] === 'day') return `Day ${parts[2]}`;
-    if (parts[1] === 'nth') {
-      const n = parseInt(parts[2], 10);
-      const wd = parseInt(parts[3], 10);
-      return `${_ORDINALS[n - 1] || `${n}th`} ${_DAYS[wd].slice(0, 3)}`;
-    }
-    if (parts[1] === 'last') {
-      const wd = parseInt(parts[2], 10);
-      return `Last ${_DAYS[wd].slice(0, 3)}`;
-    }
-    return '';
-  }
-
-  function _setReminder(datetimeLocalStr) {
-    dueInput.value = datetimeLocalStr;
-    if (remindBtn) {
-      remindBtn.classList.add('has-date');
-      // Jingle the bell. CSS handles the animation; remove + reflow + re-add
-      // so it replays every time the user sets/changes a reminder.
-      const _bell = remindBtn.querySelector('svg');
-      if (_bell) {
-        _bell.classList.remove('jingling');
-        void _bell.offsetWidth;
-        _bell.classList.add('jingling');
-        setTimeout(() => _bell.classList.remove('jingling'), 700);
-      }
-    }
-    _renderReminderTag();
-    _ensureNotificationPermission();
-  }
-
-  function _pickCustomDate() {
-    // Replace the dropdown menu with a small inline picker
-    document.querySelectorAll('.note-reminder-menu').forEach(dismissOrRemove);
-    const menu = document.createElement('div');
-    menu.className = 'note-reminder-menu';
-    const initial = dueInput.value || _toLocalDatetimeStr(_tomorrowDate());
-    menu.innerHTML = `
-      <div class="note-reminder-menu-title">Pick date and time</div>
-      <div class="note-reminder-menu-picker">
-        <input type="datetime-local" class="note-reminder-date-input" value="${initial}" />
-      </div>
-      <div class="note-reminder-menu-divider"></div>
-      <button class="note-reminder-menu-item note-reminder-menu-confirm">
-        <span>Save</span>
-      </button>
-    `;
-    document.body.appendChild(menu);
-    // Position next to the bell button
-    const anchor = remindBtn || form.querySelector('.note-form-reminder-tags');
-    const rect = anchor.getBoundingClientRect();
-    const vw = window.innerWidth;
-    const vh = window.innerHeight;
-    const mw = menu.offsetWidth || 240;
-    const mh = menu.offsetHeight || 200;
-    let top = rect.bottom + 4;
-    let left = rect.left;
-    if (top + mh > vh - 8) top = Math.max(8, rect.top - mh - 4);
-    if (left + mw > vw - 8) left = Math.max(8, vw - mw - 8);
-    if (left < 8) left = 8;
-    menu.style.top = top + 'px';
-    menu.style.left = left + 'px';
-    const dInput = menu.querySelector('.note-reminder-date-input');
-    dInput.focus();
-    if (typeof dInput.showPicker === 'function') {
-      try { dInput.showPicker(); } catch {}
-    }
-    const close = bindMenuDismiss(menu, () => { menu.remove(); });
-    menu.querySelector('.note-reminder-menu-confirm').addEventListener('click', () => {
-      if (dInput.value) _setReminder(dInput.value);
-      close();
-    });
-  }
-
-  if (remindBtn) remindBtn.addEventListener('click', (e) => { e.stopPropagation(); _openReminderMenu(remindBtn, !!dueInput.value); });
-  _renderReminderTag();
-
-  // Photo upload
-  const photoBtn = form.querySelector('.note-form-photo-btn');
-  const photoInput = form.querySelector('.note-form-photo-input');
-  if (photoBtn && photoInput) {
-    photoBtn.addEventListener('click', () => photoInput.click());
-    photoInput.addEventListener('change', async () => {
-      const file = photoInput.files?.[0];
-      if (!file) return;
-      const fd = new FormData();
-      fd.append('files', file);
-      try {
-        const res = await fetch(`${API_BASE}/api/upload`, { method: 'POST', body: fd, credentials: 'same-origin' });
-        const data = await res.json();
-        const fileId = data.files?.[0]?.id;
-        if (!fileId) throw new Error('Upload failed');
-        currentImageUrl = `${API_BASE}/api/upload/${fileId}`;
-        // Only ever keep the latest attached photo — drop any existing wrap
-        // before inserting a fresh one. Picking a second photo replaces the
-        // first instead of stacking.
-        form.querySelector('.note-form-image-wrap')?.remove();
-        const wrap = document.createElement('div');
-        wrap.className = 'note-form-image-wrap';
-        wrap.innerHTML = `<img class="note-form-image" draggable="false" /><button class="note-form-image-rm" title="Remove">&times;</button>`;
-        // Insert AFTER the whole header (a flex-row), not after the
-        // title input itself — otherwise the image lands as a sibling
-        // of the title inside the header and flex puts them side-by-side.
-        form.querySelector('.note-form-header').after(wrap);
-        wrap.querySelector('.note-form-image-rm').addEventListener('click', () => { wrap.remove(); currentImageUrl = ''; });
-        wrap.querySelector('img').src = currentImageUrl;
-      } catch (err) { uiModule.showError('Image upload failed'); }
-      photoInput.value = '';
-    });
-  }
-  // Existing image remove
-  form.querySelector('.note-form-image-rm')?.addEventListener('click', () => {
-    form.querySelector('.note-form-image-wrap')?.remove();
-    currentImageUrl = '';
-  });
-
-  // Title Enter -> focus body (textarea or first checklist item)
-  form.querySelector('.note-form-title').addEventListener('keydown', (e) => {
-    if (e.key === 'Enter' && !e.shiftKey && !e.ctrlKey && !e.metaKey) {
-      e.preventDefault();
-      const ta = form.querySelector('.note-form-content');
-      if (ta) { ta.focus(); return; }
-      const firstItem = form.querySelector('.note-cl-text');
-      if (firstItem) firstItem.focus();
-    }
-  });
-
-  // Hashtag → label: typing "#foo " in title/content appends "foo" to the
-  // space-separated tag list. Repeats are deduplicated, so #foo #foo only
-  // keeps one. Tags already present in the label field are left alone.
-  const labelInput = form.querySelector('.note-form-label');
-  const _hashtagRe = /(^|\s)#([A-Za-z0-9][\w-]*)\s$/;
-  function _wireHashtag(el) {
-    if (!el || !labelInput) return;
-    el.addEventListener('input', () => {
-      const m = _hashtagRe.exec(el.value);
-      if (!m) return;
-      const tag = m[2];
-      // Dedup against the stripped form — labelInput may already hold `#tag`
-      // (after Enter normalised), so includes(tag) on the raw split would
-      // miss the duplicate and append a bare `tag` next to `#tag`.
-      const existing = labelInput.value.trim().split(/\s+/).filter(Boolean);
-      const stripped = existing.map(t => t.replace(/^#+/, ''));
-      if (!stripped.includes(tag)) {
-        existing.push('#' + tag);
-        labelInput.value = existing.join(' ');
-        labelInput.classList.add('flash-once');
-        setTimeout(() => labelInput.classList.remove('flash-once'), 600);
-      }
-      const cut = el.value.length - m[0].length + m[1].length;
-      el.value = el.value.slice(0, cut);
-    });
-  }
-  _wireHashtag(form.querySelector('.note-form-title'));
-  _wireHashtag(form.querySelector('.note-form-content'));
-  // Pressing Enter in the tag field commits the current word as its own tag
-  // and parks the cursor after a trailing space, so the next word becomes a
-  // separate tag rather than overwriting the previous one.
-  labelInput?.addEventListener('keydown', (e) => {
-    if (e.key !== 'Enter' || e.shiftKey || e.ctrlKey || e.metaKey) return;
-    e.preventDefault();
-    e.stopPropagation();
-    // Strip any leading #s the user typed, dedupe, then re-prepend exactly
-    // one #. So typing "foo" or "#foo" both end up as "#foo " in the input;
-    // the save handler keeps stripping #s before storing so DB stays clean.
-    const tags = [...new Set(labelInput.value.split(/\s+/).map(t => t.replace(/^#+/, '').trim()).filter(Boolean))];
-    if (!tags.length) return;
-    labelInput.value = tags.map(t => '#' + t).join(' ') + ' ';
-    labelInput.setSelectionRange(labelInput.value.length, labelInput.value.length);
-    labelInput.classList.add('flash-once');
-    setTimeout(() => labelInput.classList.remove('flash-once'), 600);
-  });
-
-  // Shift+Enter (or Cmd/Ctrl+Enter) anywhere in the form -> save
-  // Escape -> cancel edit
-  form.addEventListener('keydown', (e) => {
-    if (e.key === 'Enter' && (e.shiftKey || e.ctrlKey || e.metaKey)) {
-      e.preventDefault();
-      form.querySelector('.note-form-save')?.click();
-    } else if (e.key === 'Escape') {
-      e.preventDefault();
-      e.stopPropagation();
-      form.querySelector('.note-form-cancel')?.click();
-    }
-  });
-
-  // Save. Prevent the button from stealing focus on press: on mobile, the
-  // first tap would otherwise just blur the focused textarea/input (closing
-  // the keyboard and shifting layout), so the tap never reached the button and
-  // you had to tap "Done" twice. mousedown preventDefault keeps focus put while
-  // still letting the click fire.
-  const _saveBtnEl0 = form.querySelector('.note-form-save');
-  _saveBtnEl0.addEventListener('mousedown', (e) => e.preventDefault());
-  _saveBtnEl0.addEventListener('click', async () => {
-    // Guard against spam-clicks: the drawing save AWAITS a canvas upload before
-    // the optimistic re-render removes the form, so without this a slow upload
-    // let repeated clicks create duplicate notes.
-    const _saveBtn = form.querySelector('.note-form-save');
-    if (_saveBtn._saving) return;
-    // Mobile: when an existing note is opened and closed without edits, the
-    // Update (✓) button morphs into Archive (set up below). Route the click
-    // directly through the archive flow. Using a DOM .click() proxy here was
-    // fragile on mobile because the real archive button can move from the
-    // footer to the fullscreen header.
-    if (_saveBtn.classList.contains('archive-mode')) {
-      _archiveNoteById(note?.id);
-      return;
-    }
-    _saveBtn._saving = true; _saveBtn.disabled = true; _saveBtn.style.opacity = '0.5';
-    try {
-    form._flushDraft?.();
-    await form._stopDraftAutosave?.();
-    form._flushDraft?.();
-    const title = form.querySelector('.note-form-title').value.trim();
-    // Normalize tag input: split on whitespace, strip leading #s, dedupe,
-    // re-join with single spaces. Empty → null.
-    const _rawLabel = form.querySelector('.note-form-label')?.value || '';
-    const _tags = [...new Set(_rawLabel.split(/\s+/).map(t => t.replace(/^#+/, '').trim()).filter(Boolean))];
-    if (form.querySelector('.note-form-due').value && !_tags.includes('reminder')) _tags.push('reminder');
-    const labelVal = _tags.length ? _tags.join(' ') : null;
-    const payload = {
-      title,
-      note_type: currentType,
-      color: currentColor,
-      label: labelVal,
-      due_date: form.querySelector('.note-form-due').value || null,
-      repeat: form.querySelector('.note-form-repeat')?.value || 'none',
-      image_url: currentImageUrl || null,
-    };
-    if (currentType === 'note') {
-      payload.content = form.querySelector('.note-form-content')?.value || '';
-    } else if (currentType === 'draw') {
-      // Upload the canvas PNG before saving so image_url points to a
-      // persistent file. We block the save until upload completes — drawings
-      // can't be re-rendered later without the URL.
-      const canvas = form.querySelector('.note-form-canvas');
-      const upload = await _uploadCanvasAsPng(canvas, note?.gallery_id || null);
-      if (!upload?.url) { uiModule.showError('Failed to save drawing'); return; }
-      payload.image_url = upload.url;
-      if (upload.galleryId) payload.gallery_id = upload.galleryId;
-    } else if (currentType === 'goal') {
-      // Legacy: existing goal-type notes still edit through this branch.
-      // No AI involvement — save as a normal note with description + items.
-      payload.content = form.querySelector('.note-form-goal-desc')?.value || '';
-      payload.items = _collectItems(form);
-    } else {
-      payload.items = _collectItems(form);
-    }
-    if (isEdit) payload.id = note.id;
-    // Reset fired reminder if due_date changed (so re-arm works), and also
-    // clear the entry-glow seen flag so the new firing glows again on the
-    // next time the user opens the panel.
-    if (isEdit && note.due_date !== payload.due_date) {
-      const fired = _loadFiredReminders();
-      fired.delete(note.id);
-      _saveFiredReminders(fired);
-      const glowed = _loadGlowedReminders();
-      glowed.delete(note.id);
-      _saveGlowedReminders(glowed);
-      _setReminderCardGlow(note.id, false);
-    }
-    // Edited notes move to the top of their section (under pinned). Compute
-    // sort_order = (min unpinned sort_order) - 1 so the saved note sorts above
-    // siblings; the pin block keeps its own ordering above this.
-    if (!payload.pinned) {
-      // Both edits AND newly-created notes anchor above the rest of the
-      // unpinned section. Without this, freshly created notes sit at the
-      // bottom because manually-reordered siblings already carry negative
-      // sort_order values.
-      const minUnpinned = _notes
-        .filter(n => !n.pinned && (!isEdit || n.id !== note.id))
-        .reduce((m, n) => Math.min(m, n.sort_order || 0), 0);
-      payload.sort_order = minUnpinned - 1;
-    }
-    // Optimistic update — update local state first, render, then save in background
-    _editingId = null;
-    const draftId = isEdit ? note.id : '__new__';
-    const submittedDraft = JSON.stringify(_loadDraft(draftId));
-    if (isEdit) {
-      const idx = _notes.findIndex(n => n.id === note.id);
-      if (idx >= 0) _notes[idx] = { ..._notes[idx], ...payload };
-    } else {
-      _notes.unshift({ ...payload, id: 'tmp_' + _uid(), created_at: new Date().toISOString(), updated_at: new Date().toISOString() });
-    }
-    _renderNotes();
-    // Background save
-    _saveNote(payload).then(saved => {
-      if (JSON.stringify(_loadDraft(draftId)) === submittedDraft) _clearDraft(draftId);
-      if (!isEdit && saved && saved.id) {
-        // Replace temp ID with real one from server. AND re-render — the
-        // existing card's `data-note-id="tmp_xxx"` is stale after Object.assign
-        // bumps the in-memory id, so all subsequent clicks (edit, done, copy,
-        // archive, delete) silently fail to find the note in `_notes`.
-        const tmp = _notes.find(n => n.id.startsWith('tmp_'));
-        if (tmp) Object.assign(tmp, saved);
-        _renderNotes();
-      }
-    }).catch(err => {
-      uiModule.showError('Save failed: ' + err.message);
-      _fetchNotes().then(() => _renderNotes());
-    });
-    } finally {
-      // Re-enable on early returns / errors. On success the form is removed by
-      // the optimistic re-render, so re-enabling the detached button is a no-op.
-      _saveBtn._saving = false; _saveBtn.disabled = false; _saveBtn.style.opacity = '';
-    }
-  });
-
-  // Mobile-only: when editing an existing note, the Update (✓) button starts in
-  // archive-mode (visually + behaviorally) and flips to Update on the first
-  // edit. Lets the user tap a note to skim, then tap ✓ to archive without ever
-  // touching a separate Archive button.
-  if (isEdit && window.innerWidth <= 768) {
-    const _saveLabelEl = _saveBtnEl0.querySelector('.nft-label');
-    const _isFinishedTodo = () => {
-      if (currentType !== 'todo') return false;
-      const rows = [...form.querySelectorAll('.note-cl-row')];
-      const withText = rows.filter(row => (row.querySelector('.note-cl-text')?.value || '').trim());
-      return withText.length > 0 && withText.every(row => row.classList.contains('done'));
-    };
-    const _enterArchive = () => {
-      _saveBtnEl0.classList.add('archive-mode');
-      const label = _isFinishedTodo() ? 'Finish' : 'Archive';
-      if (_saveLabelEl) _saveLabelEl.textContent = label;
-      _saveBtnEl0.title = label;
-    };
-    const _enterUpdate = () => {
-      if (!_saveBtnEl0.classList.contains('archive-mode')) return;
-      _saveBtnEl0.classList.remove('archive-mode');
-      if (_saveLabelEl) _saveLabelEl.textContent = 'Update';
-      _saveBtnEl0.title = 'Update';
-    };
-    _enterArchive();
-    form.addEventListener('input', _enterUpdate, true);
-    form.addEventListener('change', _enterUpdate, true);
-    // Checklist dots use a custom control and dispatch their update before
-    // this click bubbles. Re-evaluate afterward so a fully completed todo
-    // offers Finish (which archives/removes it from the active list).
-    form.addEventListener('click', (event) => {
-      if (!event.target.closest('.note-cl-dot')) return;
-      setTimeout(() => {
-        if (_isFinishedTodo()) _enterArchive();
-        else _enterUpdate();
-      }, 0);
-    }, true);
-  }
-
-  // Cancel
-  form.querySelector('.note-form-cancel').addEventListener('click', () => { form._flushDraft?.(); _editingId = null; _renderNotes(); });
-
-  // Archive / Delete — edit-mode-only buttons, mirror the (now-hidden) card actions.
-  form.querySelector('.note-form-archive-btn')?.addEventListener('click', () => {
-    if (!isEdit) return;
-    _archiveNoteById(note.id);
-  });
-  form.querySelector('.note-form-delete-btn')?.addEventListener('click', async () => {
-    if (!isEdit) return;
-    const id = note.id;
-    if (uiModule.styledConfirm) {
-      const ok = await uiModule.styledConfirm('Delete this note?', { confirmText: 'Delete', danger: true });
-      if (!ok) return;
-    } else if (!confirm('Delete this note?')) {
-      return;
-    }
-    const idx = _notes.findIndex(n => n.id === id);
-    if (idx >= 0) _notes.splice(idx, 1);
-    _editingId = null;
-    _renderNotes();
-    _deleteNoteApi(id).then(() => uiModule.showToast('Deleted')).catch(() => {
-      uiModule.showError('Failed to delete');
-      _fetchNotes().then(() => _renderNotes());
-    });
-  });
-
-  // Autosave a draft to localStorage on every change so unsaved edits
-  // survive connection loss / reload / accidental close.
-  _wireDraftAutosave(form, isEdit ? note.id : '__new__');
-
-  return form;
-}
-
-// Legacy goal-typed notes still render through this branch so existing
-// data isn't lost. The "Goal" type is no longer exposed in the form picker
-// or quick-add — these notes show with a description + manual checklist
-// editor, just like a regular todo with a body.
-function _buildGoalHtml(note, items) {
-  const desc = (note?.content || '').toString();
-  return `
-    <div class="note-form-goal">
-      <textarea class="note-form-goal-desc" placeholder="Description (optional)" rows="3">${_esc(desc)}</textarea>
-      ${_buildChecklistHtml(items)}
-    </div>
-  `;
-}
-
-function _wireGoalForm(form, container) {
-  if (!container) return;
-  // _wireHashtag is a closure inside _buildForm — out of scope here. Inline
-  // the same behavior (type "#foo " in the description → tag added to the
-  // form's label input) so editing a goal note doesn't ReferenceError.
-  const desc = container.querySelector('.note-form-goal-desc');
-  const labelInput = form?.querySelector('.note-form-label');
-  if (desc && labelInput) {
-    const tagRe = /(^|\s)#([A-Za-z0-9][\w-]*)\s$/;
-    desc.addEventListener('input', () => {
-      const m = tagRe.exec(desc.value);
-      if (!m) return;
-      const tag = m[2];
-      // Same dedup-after-stripping fix as the plain note hashtag handler.
-      const existing = labelInput.value.trim().split(/\s+/).filter(Boolean);
-      const stripped = existing.map(t => t.replace(/^#+/, ''));
-      if (!stripped.includes(tag)) {
-        existing.push('#' + tag);
-        labelInput.value = existing.join(' ');
-        labelInput.classList.add('flash-once');
-        setTimeout(() => labelInput.classList.remove('flash-once'), 600);
-      }
-      const cut = desc.value.length - m[0].length + m[1].length;
-      desc.value = desc.value.slice(0, cut);
-    });
-  }
-  // Always wire the checklist. The previous gate on a `note-form-goal-fresh`
-  // class was dead code — nothing ever set that class, so the editor never
-  // hooked up add/drag/Tab.
-  _wireChecklist(container);
-}
-
-function _buildChecklistHtml(items) {
-  let html = '<div class="note-checklist-inputs">';
-  for (const item of items) {
-    const indent = Math.min(item.indent || 0, 3);
-    html += `<div class="note-cl-row${item.done ? ' done' : ''}" draggable="true" data-item-id="${item.id || _uid()}" data-indent="${indent}" style="padding-left:${indent * 16}px">
-      <span class="note-cl-grip" title="Drag to reorder">⋮⋮</span>
-      <span class="note-cl-dot"></span>
-      <input type="text" class="note-cl-text" value="${_esc(item.text)}" placeholder="Item..." />
-      <button type="button" class="note-cl-rm">&times;</button>
-    </div>`;
-  }
-  // `type="button"` matters on mobile — without it some browsers treat
-  // bare <button> as form-submit and the click handler never fires inside
-  // certain containers. Also bumped tap target so fingers don't miss.
-  html += `<button type="button" class="note-cl-add">+ Add</button></div>`;
-  return html;
-}
-
-function _wireRow(row, container) {
-  row.querySelector('.note-cl-rm')?.addEventListener('click', () => row.remove());
-  row.querySelector('.note-cl-dot')?.addEventListener('click', () => {
-    const wasDone = row.classList.contains('done');
-    row.classList.toggle('done');
-    // The custom dot has no native input/change event. Notify the form so
-    // mobile edit mode switches its action from Archive back to Update.
-    container.dispatchEvent(new Event('input', { bubbles: true }));
-    const becameDone = !wasDone;  // we just flipped it
-    const dot = row.querySelector('.note-cl-dot');
-    const dRect = (dot || row).getBoundingClientRect();
-    // Small confetti burst on each fresh check so the user gets a
-    // "well done" beat per item, not just the grand-finale on all-done.
-    if (becameDone) {
-      spawnConfetti(dRect.left + dRect.width / 2, dRect.top + dRect.height / 2, 16);
-    }
-    // Bigger burst when the whole list is now done.
-    const rows = [...container.querySelectorAll('.note-cl-row')];
-    const hasText = rows.some(r => (r.querySelector('.note-cl-text')?.value || '').trim().length > 0);
-    if (hasText && rows.every(r => r.classList.contains('done') || !(r.querySelector('.note-cl-text')?.value || '').trim())) {
-      spawnConfetti(dRect.left + dRect.width / 2, dRect.top + dRect.height / 2, 60);
-    }
-  });
-  const txt = row.querySelector('.note-cl-text');
-  txt?.addEventListener('keydown', (e) => {
-    if (e.key === 'Enter') { e.preventDefault(); container.querySelector('.note-cl-add')?.click(); }
-    else if (e.key === 'Tab') {
-      e.preventDefault();
-      const cur = parseInt(row.dataset.indent || '0');
-      const next = e.shiftKey ? Math.max(0, cur - 1) : Math.min(3, cur + 1);
-      row.dataset.indent = String(next);
-      row.style.paddingLeft = (next * 16) + 'px';
-    } else if (e.key === 'Backspace' && txt.value === '') {
-      e.preventDefault();
-      const prev = row.previousElementSibling;
-      row.remove();
-      if (prev && prev.classList.contains('note-cl-row')) prev.querySelector('.note-cl-text')?.focus();
-    }
-  });
-  // Drag handlers
-  row.addEventListener('dragstart', (e) => {
-    row.classList.add('dragging');
-    e.dataTransfer.effectAllowed = 'move';
-    try { e.dataTransfer.setData('text/plain', row.dataset.itemId); } catch {}
-  });
-  row.addEventListener('dragend', () => {
-    row.classList.remove('dragging');
-    container.querySelectorAll('.drop-before, .drop-after').forEach(el => el.classList.remove('drop-before', 'drop-after'));
-  });
-}
-
-function _wireChecklist(container) {
-  if (!container) return;
-  // Delegate the + Add click off the container so re-renders + mobile
-  // touch quirks don't leave the button dead. The previous direct
-  // `addEventListener` on the button silently broke on mobile when
-  // _wireChecklist ran more than once (or before the button was in DOM).
-  if (!container._addDelegated) {
-    container._addDelegated = true;
-    container.addEventListener('click', (ev) => {
-      const addBtn = ev.target.closest('.note-cl-add');
-      if (!addBtn || !container.contains(addBtn)) return;
-      ev.preventDefault();
-      ev.stopPropagation();
-      const inputs = container.querySelector('.note-checklist-inputs');
-      if (!inputs) return;
-      const row = document.createElement('div');
-      row.className = 'note-cl-row';
-      row.draggable = true;
-      row.dataset.itemId = _uid();
-      row.dataset.indent = '0';
-      row.innerHTML = `<span class="note-cl-grip" title="Drag">⋮⋮</span><span class="note-cl-dot"></span><input type="text" class="note-cl-text" placeholder="Item..." /><button type="button" class="note-cl-rm">&times;</button>`;
-      inputs.insertBefore(row, addBtn);
-      row.querySelector('.note-cl-text').focus();
-      _wireRow(row, container);
-    });
-  }
-  container.querySelectorAll('.note-cl-row').forEach(row => _wireRow(row, container));
-
-  // Drag-over handler on the inputs container
-  const inputs = container.querySelector('.note-checklist-inputs');
-  if (inputs) {
-    inputs.addEventListener('dragover', (e) => {
-      e.preventDefault();
-      const dragging = inputs.querySelector('.note-cl-row.dragging');
-      if (!dragging) return;
-      inputs.querySelectorAll('.drop-before, .drop-after').forEach(el => el.classList.remove('drop-before', 'drop-after'));
-      const rows = [...inputs.querySelectorAll('.note-cl-row:not(.dragging)')];
-      const after = rows.find(r => {
-        const box = r.getBoundingClientRect();
-        return e.clientY < box.top + box.height / 2;
-      });
-      if (after) {
-        after.classList.add('drop-before');
-        inputs.insertBefore(dragging, after);
-      } else if (rows.length) {
-        rows[rows.length - 1].classList.add('drop-after');
-        inputs.insertBefore(dragging, container.querySelector('.note-cl-add'));
-      }
-    });
-    inputs.addEventListener('dragleave', (e) => {
-      if (!inputs.contains(e.relatedTarget)) {
-        inputs.querySelectorAll('.drop-before, .drop-after').forEach(el => el.classList.remove('drop-before', 'drop-after'));
-      }
-    });
-  }
-}
-
-function _collectItems(form) {
-  const items = [];
-  form.querySelectorAll('.note-cl-row').forEach(row => {
-    const text = row.querySelector('.note-cl-text')?.value?.trim();
-    if (text) items.push({
-      id: row.dataset.itemId || _uid(),
-      text,
-      done: row.classList.contains('done'),
-      indent: parseInt(row.dataset.indent || '0'),
-    });
-  });
-  return items;
-}
-
-// ---- Draw mode (canvas) ----
-
-function _buildDrawHtml() {
-  return `
-    <div class="note-form-draw-wrap">
-      <canvas class="note-form-canvas" width="600" height="320"></canvas>
-      <div class="note-form-draw-toolbar">
-        <input type="color" class="note-form-draw-color" title="Stroke color" value="#222222" />
-        <label class="note-form-draw-tool note-form-draw-size-wrap" title="Stroke size">
-          <input type="range" class="note-form-draw-size" min="1" max="24" value="3" />
-        </label>
-        <div class="note-form-draw-be" role="group">
-          <button type="button" class="note-form-draw-be-btn note-form-draw-brush active" data-mode="pen" title="Brush">
-            <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M9.06 11.9l8.07-8.06a2.85 2.85 0 1 1 4.03 4.03l-8.06 8.08"/><path d="M7.07 14.94c-1.66 0-3 1.35-3 3.02 0 1.33-2.5 1.52-2 2.02 1.08 1.1 2.49 2.02 4 2.02 2.2 0 4-1.8 4-4.04 0-1.67-1.34-3.02-3-3.02z"/></svg>
-          </button>
-          <button type="button" class="note-form-draw-be-btn note-form-draw-eraser" data-mode="eraser" title="Eraser">
-            <svg width="22" height="22" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="m7 21-4.3-4.3c-1-1-1-2.5 0-3.4l9.6-9.6c1-1 2.5-1 3.4 0l5.6 5.6c1 1 1 2.5 0 3.4L13 21"/><path d="M22 21H7"/><path d="m5 11 9 9"/></svg>
-          </button>
-        </div>
-        <button type="button" class="note-form-draw-undo" title="Undo" aria-label="Undo">
-          <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><polyline points="9 14 4 9 9 4"></polyline><path d="M4 9h11a5 5 0 0 1 5 5v0a5 5 0 0 1-5 5H9"></path></svg>
-        </button>
-        <button type="button" class="note-form-draw-text" title="Add text — click to cycle size" aria-label="Add text">T<span class="note-form-draw-text-badge"></span></button>
-        <button type="button" class="note-form-draw-line" title="Line — click to cycle size">
-          <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><line x1="4" y1="20" x2="20" y2="4"/></svg>
-          <span class="note-form-draw-shape-badge"></span>
-        </button>
-        <button type="button" class="note-form-draw-circle" title="Circle — click to cycle size">
-          <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="12" cy="12" r="9"/></svg>
-          <span class="note-form-draw-shape-badge"></span>
-        </button>
-      </div>
-    </div>
-  `;
-}
-
-// Attach drawing handlers to the canvas inside `container`. Optionally loads
-// `initialImageUrl` as a background, so editing an existing drawing keeps it.
-function _wireCanvas(container, initialImageUrl) {
-  const canvas = container.querySelector('.note-form-canvas');
-  if (!canvas) return;
-  const resolveThemeColor = (expression, fallback) => {
-    const probe = document.createElement('span');
-    probe.style.color = expression;
-    probe.style.position = 'fixed';
-    probe.style.visibility = 'hidden';
-    document.body.appendChild(probe);
-    const resolved = getComputedStyle(probe).color || fallback;
-    probe.remove();
-    return resolved;
-  };
-  const colorToHex = (color, fallback) => {
-    try {
-      const probe = document.createElement('canvas');
-      probe.width = probe.height = 1;
-      const probeCtx = probe.getContext('2d');
-      probeCtx.fillStyle = color;
-      probeCtx.fillRect(0, 0, 1, 1);
-      const [r, g, b] = probeCtx.getImageData(0, 0, 1, 1).data;
-      return `#${[r, g, b].map(v => v.toString(16).padStart(2, '0')).join('')}`;
-    } catch { return fallback; }
-  };
-  const surfaceColor = resolveThemeColor('var(--panel, var(--bg))', '#282c34');
-  const surfaceColorHex = colorToHex(surfaceColor, '#282c34');
-  const highlightColor = colorToHex(
-    resolveThemeColor('var(--accent, var(--red))', '#e06c75'),
-    '#e06c75',
-  );
-  const colorInput = container.querySelector('.note-form-draw-color');
-  if (colorInput) colorInput.value = highlightColor;
-  // Bump the backing-store resolution for retina displays so strokes stay
-  // crisp. Set only style.width — leaving style.height to auto so the canvas
-  // scales uniformly via its intrinsic aspect ratio. If both CSS dimensions
-  // are pinned, max-width:100% shrinks the width only, leaving rasterized
-  // glyphs visibly stretched relative to their on-screen input.
-  const dpr = Math.min(window.devicePixelRatio || 1, 2);
-  const cssW = canvas.width;
-  const cssH = canvas.height;
-  // Fill the container up to the logical width (don't pin a hard 600px,
-  // which on a narrow phone forces the card wider than the viewport and
-  // pushes the drawing outside the note). _pos() scales pointer coords by
-  // the actual displayed width, so accuracy is preserved at any size.
-  canvas.style.width = '100%';
-  canvas.style.maxWidth = cssW + 'px';
-  canvas.style.height = 'auto';
-  canvas.style.aspectRatio = cssW + ' / ' + cssH;
-  canvas.width = cssW * dpr;
-  canvas.height = cssH * dpr;
-  const ctx = canvas.getContext('2d');
-  ctx.scale(dpr, dpr);
-  ctx.fillStyle = surfaceColor;
-  ctx.fillRect(0, 0, cssW, cssH);
-  ctx.lineCap = 'round';
-  ctx.lineJoin = 'round';
-
-  // Load prior drawing as starting point so consecutive edits compose.
-  const safeInitialImageUrl = _safeImgSrc(initialImageUrl);
-  if (safeInitialImageUrl) {
-    const img = new Image();
-    img.crossOrigin = 'anonymous';
-    img.onload = () => { try { ctx.drawImage(img, 0, 0, cssW, cssH); } catch {} };
-    img.src = safeInitialImageUrl;
-    // Float an X over the canvas so the user can blank it out and go back to
-    // a clean draw surface. Removes itself once clicked.
-    const wrap = container.querySelector('.note-form-draw-wrap');
-    if (wrap && !wrap.querySelector('.note-form-draw-bg-rm')) {
-      const rm = document.createElement('button');
-      rm.type = 'button';
-      rm.className = 'note-form-draw-bg-rm';
-      rm.title = 'Clear photo (regular draw)';
-      rm.innerHTML = '&times;';
-      rm.addEventListener('click', (e) => {
-        e.preventDefault();
-        e.stopPropagation();
-        ctx.fillStyle = surfaceColor;
-        ctx.fillRect(0, 0, cssW, cssH);
-        rm.remove();
-      });
-      wrap.appendChild(rm);
-    }
-  }
-
-  // Swap the native browser color dialog for the in-house HSV picker
-  // (same one used by Themes + the gallery editor). Existing `input` event
-  // listeners + .value reads keep working — see colorPicker.js.
-  if (colorInput) attachColorPicker(colorInput);
-  const sizeInput = container.querySelector('.note-form-draw-size');
-  const beSeg = container.querySelector('.note-form-draw-be');
-  const brushBtn = container.querySelector('.note-form-draw-brush');
-  const eraserBtn = container.querySelector('.note-form-draw-eraser');
-  const textBtn = container.querySelector('.note-form-draw-text');
-  const lineBtn = container.querySelector('.note-form-draw-line');
-  const circleBtn = container.querySelector('.note-form-draw-circle');
-  const undoBtn = container.querySelector('.note-form-draw-undo');
-  // Single source of truth for what clicks/drags do. Other booleans are
-  // derived from this so we never end up with conflicting "eraser AND text"
-  // states (the bug that made T appear broken after using the eraser).
-  // Modes: 'pen' | 'eraser' | 'text-s' | 'text-m' | 'text-l' | 'line' | 'circle'
-  let mode = 'pen';
-  let drawing = false;
-  let last = null;
-  // The text tool has three preset sizes (CSS px font-size).
-  const TEXT_SIZES = { 's': 16, 'm': 26, 'l': 40 };
-  // Line / circle stroke widths in logical pixels — three crisp options.
-  const SHAPE_WIDTHS = { 's': 2, 'm': 5, 'l': 10 };
-  // Snapshot taken at the start of a shape drag so the preview can repaint
-  // cleanly on each move without accumulating intermediate strokes.
-  let _shapeSnapshot = null;
-
-  // Per-canvas undo stack. We snapshot the bitmap (as ImageData) BEFORE each
-  // operation — stroke, text commit, or future operations — and pop+restore
-  // on Undo. Cap to 30 to keep memory bounded.
-  const _undoStack = [];
-  const UNDO_LIMIT = 30;
-  const _syncUndoButton = () => {
-    const available = _undoStack.length > 0;
-    undoBtn?.classList.toggle('has-undo', available);
-    undoBtn?.toggleAttribute('disabled', !available);
-    undoBtn?.setAttribute('aria-disabled', available ? 'false' : 'true');
-  };
-  const _markCanvasDirty = () => container.dispatchEvent(new Event('input', { bubbles: true }));
-  const _snapshot = () => {
-    try {
-      const w = canvas.width, h = canvas.height;
-      _undoStack.push(ctx.getImageData(0, 0, w, h));
-      if (_undoStack.length > UNDO_LIMIT) _undoStack.shift();
-      _syncUndoButton();
-    } catch {}
-  };
-  const _undo = () => {
-    const prev = _undoStack.pop();
-    if (!prev) { _syncUndoButton(); return; }
-    // Restore against the raw backing store: temporarily reset the active
-    // ctx scale, paint the snapshot 1:1, then reapply our standard transform.
-    ctx.save();
-    ctx.setTransform(1, 0, 0, 1, 0, 0);
-    ctx.putImageData(prev, 0, 0);
-    ctx.restore();
-    _markCanvasDirty();
-    _syncUndoButton();
-  };
-
-  const _pos = (e) => {
-    // CSS can shrink the canvas (max-width:100%) without changing its logical
-    // size, so compute the displayed-to-logical scale per axis. Pointer coords
-    // are in CSS pixels; the dpr-scaled ctx expects logical (cssW × cssH).
-    const r = canvas.getBoundingClientRect();
-    const sx = cssW / r.width;
-    const sy = cssH / r.height;
-    const t = e.touches ? e.touches[0] : e;
-    return { x: (t.clientX - r.left) * sx, y: (t.clientY - r.top) * sy };
-  };
-  const _begin = (e) => {
-    if (mode.startsWith('text-')) {
-      // Stop the event so the browser doesn't synthesize a follow-up click
-      // that would blur the input we're about to create.
-      e.preventDefault?.();
-      e.stopPropagation?.();
-      _openTextInput(e);
-      return;
-    }
-    _snapshot();
-    last = _pos(e);
-    drawing = true;
-    if (mode.startsWith('line-') || mode.startsWith('circle-')) {
-      // Capture the backing pixels so the preview can replay each move from
-      // the same starting state (otherwise live shapes accumulate).
-      try { _shapeSnapshot = ctx.getImageData(0, 0, canvas.width, canvas.height); } catch {}
-      return;
-    }
-    ctx.beginPath();
-    ctx.moveTo(last.x, last.y);
-  };
-
-  // Drop an HTML input at the click position so the user can type, then
-  // rasterize the text onto the canvas at blur/Enter. Mirrors how PDF form
-  // annotations work in our doc editor.
-  let _activeTextInput = null;
-  const _openTextInput = (e) => {
-    // Commit any prior pending input before starting a new one — otherwise
-    // the first click leaves an orphaned input the user thinks "didn't work".
-    if (_activeTextInput) { try { _activeTextInput.blur(); } catch {} }
-    const r = canvas.getBoundingClientRect();
-    const t = e.touches ? e.touches[0] : e;
-    // Position is anchored to the wrap, not the canvas; since the canvas is
-    // the first child of the wrap and the wrap has no padding, they share an
-    // origin, so we offset from the canvas rect directly.
-    const px = t.clientX - r.left;
-    const py = t.clientY - r.top;
-    const logical = _pos(e);
-    // Size is decided by which T variant is active (S/M/L), not the stroke
-    // slider — those are independent dials.
-    const sizeKey = mode.startsWith('text-') ? mode.slice(-1) : 'm';
-    const sizeCss = TEXT_SIZES[sizeKey] || TEXT_SIZES.m;
-    const wrap = container.querySelector('.note-form-draw-wrap');
-    if (!wrap) return;
-    if (getComputedStyle(wrap).position === 'static') wrap.style.position = 'relative';
-    const input = document.createElement('input');
-    input.type = 'text';
-    input.className = 'note-form-draw-textinput';
-    input.placeholder = 'type then Enter';
-    const color = colorInput?.value || '#222';
-    const maxW = Math.max(120, Math.floor(r.width - px - 4));
-    input.style.cssText = [
-      'position:absolute',
-      `left:${px}px`,
-      `top:${Math.max(0, py - sizeCss * 0.7)}px`,
-      `font:${sizeCss}px Arial, sans-serif`,
-      `color:${color}`,
-      'background:#ffffff',
-      'border:2px solid var(--accent)',
-      'border-radius:4px',
-      'outline:none',
-      'padding:2px 6px',
-      'min-width:120px',
-      `max-width:${maxW}px`,
-      'z-index:1000',
-      'box-shadow:0 2px 8px rgba(0,0,0,0.25)',
-      'pointer-events:auto',
-    ].join(';');
-    wrap.appendChild(input);
-    _activeTextInput = input;
-    // Focus synchronously so the call still counts as inside the user gesture
-    // on iOS / Android, then re-focus on the next frame in case a competing
-    // synthetic event (touch → click) moved focus away.
-    input.focus();
-    requestAnimationFrame(() => { if (document.activeElement !== input) input.focus(); });
-    let committed = false;
-    const commit = () => {
-      if (committed) return;
-      committed = true;
-      const text = input.value;
-      if (_activeTextInput === input) _activeTextInput = null;
-      input.remove();
-      if (!text) return;
-      // Snapshot BEFORE rasterizing so Undo removes the text in one step.
-      _snapshot();
-      ctx.save();
-      ctx.globalCompositeOperation = 'source-over';
-      ctx.fillStyle = color;
-      // Canvas now scales uniformly (style.height: auto), so a single ratio
-      // suffices for picking the logical font size that matches what the
-      // user just saw in the HTML input.
-      const sx = cssW / r.width;
-      const logicalSize = sizeCss * sx;
-      ctx.font = `${logicalSize}px sans-serif`;
-      ctx.textBaseline = 'top';
-      ctx.fillText(text, logical.x, logical.y - logicalSize * 0.7);
-      ctx.restore();
-      _markCanvasDirty();
-    };
-    input.addEventListener('blur', commit);
-    input.addEventListener('keydown', (ev) => {
-      if (ev.key === 'Enter') { ev.preventDefault(); input.blur(); }
-      else if (ev.key === 'Escape') { input.value = ''; input.blur(); }
-    });
-  };
-  const _move = (e) => {
-    if (!drawing) return;
-    e.preventDefault?.();
-    const p = _pos(e);
-    if (mode.startsWith('line-') || mode.startsWith('circle-')) {
-      // Restore the pre-shape bitmap, then redraw the preview shape from
-      // anchor → current pointer.
-      if (_shapeSnapshot) {
-        ctx.save();
-        ctx.setTransform(1, 0, 0, 1, 0, 0);
-        ctx.putImageData(_shapeSnapshot, 0, 0);
-        ctx.restore();
-      }
-      ctx.globalCompositeOperation = 'source-over';
-      ctx.strokeStyle = colorInput?.value || '#222';
-      const sizeKey = mode.slice(-1);
-      ctx.lineWidth = SHAPE_WIDTHS[sizeKey] || SHAPE_WIDTHS.m;
-      ctx.beginPath();
-      if (mode.startsWith('line-')) {
-        ctx.moveTo(last.x, last.y);
-        ctx.lineTo(p.x, p.y);
-      } else {
-        const dx = p.x - last.x;
-        const dy = p.y - last.y;
-        const radius = Math.hypot(dx, dy);
-        ctx.arc(last.x, last.y, radius, 0, Math.PI * 2);
-      }
-      ctx.stroke();
-      return;
-    }
-    const erasing = mode === 'eraser';
-    ctx.globalCompositeOperation = 'source-over';
-    ctx.strokeStyle = erasing ? surfaceColor : (colorInput?.value || highlightColor);
-    ctx.lineWidth = Number(sizeInput?.value || 3) * (erasing ? 2.5 : 1);
-    ctx.lineTo(p.x, p.y);
-    ctx.stroke();
-    last = p;
-  };
-  const _end = () => {
-    if (drawing) _markCanvasDirty();
-    drawing = false; last = null; _shapeSnapshot = null;
-  };
-
-  canvas.addEventListener('mousedown', _begin);
-  canvas.addEventListener('mousemove', _move);
-  window.addEventListener('mouseup', _end);
-  // Non-passive so text mode can preventDefault — otherwise the synthetic
-  // mousedown/click that follows a touch can blur the freshly-created text
-  // input on iOS Safari, making T look like a no-op.
-  canvas.addEventListener('touchstart', (e) => { if (mode.startsWith('text-')) e.preventDefault(); _begin(e); }, { passive: false });
-  canvas.addEventListener('touchmove', _move, { passive: false });
-  canvas.addEventListener('touchend', _end);
-  canvas.addEventListener('touchcancel', _end);
-
-  // Single mode setter — keeps the toolbar, swatch, and cursor in sync, and
-  // makes sure exiting the eraser restores the user's chosen color whether
-  // they exit by clicking another tool or by toggling eraser off.
-  let _preEraseColor = null;
-  const _setMode = (next) => {
-    const wasEraser = mode === 'eraser';
-    mode = next;
-    const isEraser = next === 'eraser';
-    const isPen = next === 'pen';
-    const isText = next.startsWith('text-');
-    // Swatch: theme surface while erasing, restored when leaving that mode.
-    if (isEraser && !wasEraser && colorInput) {
-      _preEraseColor = colorInput.value;
-      colorInput.value = surfaceColorHex;
-    } else if (!isEraser && wasEraser && colorInput && _preEraseColor) {
-      colorInput.value = _preEraseColor;
-      _preEraseColor = null;
-    }
-    // Brush/Eraser segmented pill — slides to the active side. When a non-
-    // pen/eraser tool (T / line / circle) is active, neither half is
-    // highlighted, but the pill still indicates which side the user was on
-    // last so they can return with one click.
-    const isLine = next.startsWith('line-');
-    const isCircle = next.startsWith('circle-');
-    beSeg?.classList.toggle('is-eraser', isEraser);
-    brushBtn?.classList.toggle('active', isPen);
-    eraserBtn?.classList.toggle('active', isEraser);
-    textBtn?.classList.toggle('active', isText);
-    lineBtn?.classList.toggle('active', isLine);
-    circleBtn?.classList.toggle('active', isCircle);
-    // Per-button size badges (S/M/L), driven off the mode suffix.
-    const tBadge = textBtn?.querySelector('.note-form-draw-text-badge');
-    if (tBadge) tBadge.textContent = isText ? next.slice(-1).toUpperCase() : '';
-    const lBadge = lineBtn?.querySelector('.note-form-draw-shape-badge');
-    if (lBadge) lBadge.textContent = isLine ? next.slice(-1).toUpperCase() : '';
-    const cBadge = circleBtn?.querySelector('.note-form-draw-shape-badge');
-    if (cBadge) cBadge.textContent = isCircle ? next.slice(-1).toUpperCase() : '';
-    // Reflect the chosen size in the icon itself — thicker line/circle stroke
-    // for M+L, larger T glyph for M+L. CSS rules read `.size-s/.size-m/.size-l`.
-    const _sz = next.slice(-1);
-    [textBtn, lineBtn, circleBtn].forEach(b => b?.classList.remove('size-s', 'size-m', 'size-l'));
-    if (isText && /[sml]/.test(_sz)) textBtn?.classList.add('size-' + _sz);
-    if (isLine && /[sml]/.test(_sz)) lineBtn?.classList.add('size-' + _sz);
-    if (isCircle && /[sml]/.test(_sz)) circleBtn?.classList.add('size-' + _sz);
-    canvas.style.cursor = isText ? 'text' : 'crosshair';
-  };
-  brushBtn?.addEventListener('click', () => _setMode('pen'));
-  eraserBtn?.addEventListener('click', () => _setMode('eraser'));
-  // T / Line / Circle: each cycles its own three sizes, then back to pen.
-  const _cycle = (prefix) => {
-    const seq = ['s', 'm', 'l'];
-    if (!mode.startsWith(prefix)) return prefix + 's';
-    const cur = mode.slice(-1);
-    const next = seq[seq.indexOf(cur) + 1];
-    return next ? prefix + next : 'pen';
-  };
-  textBtn?.addEventListener('click', () => _setMode(_cycle('text-')));
-  lineBtn?.addEventListener('click', () => _setMode(_cycle('line-')));
-  circleBtn?.addEventListener('click', () => _setMode(_cycle('circle-')));
-  undoBtn?.addEventListener('click', () => _undo());
-  _syncUndoButton();
-
-  // Stash so the save handler can read it later without re-resolving DOM.
-  canvas._cssW = cssW;
-  canvas._cssH = cssH;
-  return canvas;
-}
-
-// Export the canvas as a PNG dataURL, upload it via the existing /api/upload
-// endpoint, and resolve to a persistent URL. Returns null on failure.
-async function _uploadCanvasAsPng(canvas, galleryId = null) {
-  if (!canvas) return null;
-  const blob = await new Promise(r => canvas.toBlob(r, 'image/png'));
-  if (!blob) return null;
-  const fd = new FormData();
-  fd.append('files', blob, 'drawing.png');
-  if (galleryId) fd.append('gallery_id', galleryId);
-  try {
-    const res = await fetch(`${API_BASE}/api/upload`, { method: 'POST', body: fd, credentials: 'same-origin' });
-    const data = await res.json();
-    const id = data.files?.[0]?.id;
-    return id ? {
-      url: `${API_BASE}/api/upload/${id}`,
-      galleryId: data.files?.[0]?.gallery_id || null,
-    } : null;
-  } catch { return null; }
-}
-
-// ---- Create / Edit / Delete ----
-
-function _createNote(type = 'todo') {
-  const body = document.querySelector('#notes-pane .notes-pane-body');
-  if (!body || _editingId === '__new__') return;
-  _editingId = '__new__';
-  // Restore an unsaved new-note draft if one survived a prior close/loss.
-  const { note: _n, restored } = _applyDraftToNote({ note_type: type }, '__new__');
-  const form = _buildForm(_n);
-  form.classList.add('note-form-new');
-  body.prepend(form);
-  const initialField = type === 'note'
-    ? form.querySelector('.note-form-content')
-    : form.querySelector('.note-cl-text, .note-form-title');
-  initialField?.focus();
-  if (restored) uiModule.showToast('Restored unsaved note');
-}
-
-export function newNote() {
-  if (!_open) openPanel();
-  requestAnimationFrame(() => _createNote('note'));
-}
-
-// Build the plain-text/markdown form of a note for clipboard copy.
-function _serializeNoteForCopy(note) {
-  const lines = [];
-  if (note.title) lines.push(note.title);
-  if (note.content) lines.push(note.content);
-  if (Array.isArray(note.items) && note.items.length) {
-    if (lines.length) lines.push('');
-    for (const it of note.items) {
-      if (!it || !(it.text || '').trim()) continue;
-      lines.push(`- [${it.done ? 'x' : ' '}] ${(it.text || '').trim()}`);
-    }
-  }
-  return lines.join('\n').trim();
-}
-
-// Copy a note to the clipboard, briefly swap btnEl's icon to a checkmark, and
-// toast. Shared by the corner-copy button click and the Ctrl/Cmd+C shortcut.
-// ── ⋯ corner menu (Copy + Agent) ───────────────────────────────────
-function _openNoteCornerMenu(btn) {
-  document.querySelectorAll('.note-corner-menu-dropdown').forEach(dismissOrRemove);
-  const id = btn.dataset.noteId;
-  const note = _notes.find(n => n.id === id);
-  if (!note) return;
-  const menu = document.createElement('div');
-  menu.className = 'note-corner-menu-dropdown';
-  menu.innerHTML = `
-    <button type="button" class="ncm-item" data-act="copy">
-      <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="9" y="9" width="13" height="13" rx="2"/><path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"/></svg>
-      <span>Copy</span>
-    </button>
-    <button type="button" class="ncm-item" data-act="agent">
-      <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M12 8V4H8"/><rect x="4" y="8" width="16" height="12" rx="2"/><path d="M2 14h2M20 14h2M15 13v2M9 13v2"/></svg>
-      <span>${note.agent_session_id ? 'Re-run agent' : 'Agent: solve this'}</span>
-    </button>`;
-  document.body.appendChild(menu);
-  const r = btn.getBoundingClientRect();
-  // Right-align to the ⋯ button, clamped to the viewport.
-  const mw = 168;
-  let left = Math.min(r.right - mw, window.innerWidth - mw - 8);
-  left = Math.max(8, left);
-  // Drop down by default; flip up if there isn't room below (the button
-  // sits at the card's bottom edge now).
-  const mh = menu.offsetHeight || 96;
-  const below = window.innerHeight - r.bottom;
-  const top = (below < mh + 8 && r.top > mh + 8) ? (r.top - mh - 4) : (r.bottom + 4);
-  menu.style.cssText += `position:fixed;z-index:${topPortalZ()};top:${Math.round(top)}px;left:${Math.round(left)}px;`;
-  const close = bindMenuDismiss(menu, () => { menu.remove(); });
-  menu.querySelector('[data-act="copy"]').addEventListener('click', () => { close(); _copyNote(id, btn); });
-  menu.querySelector('[data-act="agent"]').addEventListener('click', () => { close(); _agentSolveNote(id); });
-}
-
-// Build the prompt the agent gets from a note: title + body, plus any
-// not-yet-done checklist items.
-function _noteToAgentPrompt(note) {
-  const parts = [];
-  if ((note.title || '').trim()) parts.push(note.title.trim());
-  if ((note.content || '').trim()) parts.push(note.content.trim());
-  if (Array.isArray(note.items)) {
-    note.items.filter(it => !it.done && (it.text || '').trim())
-      .forEach(it => parts.push('- ' + it.text.trim()));
-  }
-  const body = parts.join('\n');
-  return body ? `Help me get this done:\n\n${body}\n\nThe source note is read-only. Do not edit, replace, or update it.` : '';
-}
-
-// Agent-solve: create a chat session server-side, kick off an agent run
-// on it IN THE BACKGROUND (the user stays in notes), and link the session
-// to the note via a clickable tag. Tapping the tag later opens the chat.
-async function _agentSolveNote(id) {
-  const note = _notes.find(n => n.id === id);
-  if (!note) return;
-  const prompt = _noteToAgentPrompt(note);
-  if (!prompt) { uiModule.showToast('Nothing to solve — note is empty'); return; }
-  try {
-    const dc = await (await fetch(`${API_BASE}/api/default-chat`, { credentials: 'same-origin' })).json();
-    if (!dc.endpoint_url || !dc.model) { uiModule.showError('No default chat model configured'); return; }
-
-    // 1. Create the session server-side (no UI switch). skip_validation
-    //    avoids re-probing — the default-chat endpoint is already known good.
-    const label = (note.title || (Array.isArray(note.items) && note.items[0]?.text) || 'todo').slice(0, 40);
-    const csFd = new FormData();
-    csFd.append('name', 'Agent: ' + label);
-    csFd.append('endpoint_url', dc.endpoint_url);
-    csFd.append('model', dc.model);
-    if (dc.endpoint_id) csFd.append('endpoint_id', dc.endpoint_id);
-    csFd.append('skip_validation', 'true');
-    const csRes = await fetch(`${API_BASE}/api/session`, { method: 'POST', credentials: 'same-origin', body: csFd });
-    if (!csRes.ok) { uiModule.showError('Could not create agent session'); return; }
-    const sess = await csRes.json();
-    const sid = sess.id;
-
-    // 2. Link the session to the note right away so the tag appears.
-    const n = _notes.find(x => x.id === id);
-    if (n) n.agent_session_id = sid;
-    _renderNotes();
-    _patchNote(id, { agent_session_id: sid }).catch(() => {});
-
-    // 3. Kick off the agent run in the background. POST to chat_stream in
-    //    agent mode and drain the SSE so the server runs the loop to
-    //    completion + saves — without rendering anything in the chat UI.
-    const fd = new FormData();
-    fd.append('message', prompt);
-    fd.append('session', sid);
-    fd.append('mode', 'agent');
-    fd.append('disabled_tools', JSON.stringify(['manage_notes']));
-    fetch(`${API_BASE}/api/chat_stream`, { method: 'POST', credentials: 'same-origin', body: fd })
-      .then(async (res) => {
-        if (!res.ok || !res.body) return;
-        const reader = res.body.getReader();
-        // Drain to completion (server finishes + persists the run).
-        while (true) { const { done } = await reader.read(); if (done) break; }
-        if (window.sessionModule && window.sessionModule.markStreamComplete) {
-          try { window.sessionModule.markStreamComplete(sid); } catch {}
-        }
-      })
-      .catch(() => {});
-
-    uiModule.showToast('Agent working in background — tap the Agent tag when ready');
-  } catch (e) {
-    uiModule.showError('Agent failed: ' + (e.message || e));
-  }
-}
-
-async function _copyNote(noteId, btnEl) {
-  const note = _notes.find(n => n.id === noteId);
-  if (!note) return false;
-  const text = _serializeNoteForCopy(note);
-  if (!text) return false;
-  let ok = false;
-  try {
-    await navigator.clipboard.writeText(text);
-    ok = true;
-  } catch {
-    const ta = document.createElement('textarea');
-    ta.value = text;
-    ta.style.position = 'fixed'; ta.style.left = '-9999px';
-    document.body.appendChild(ta);
-    ta.select();
-    try { ok = document.execCommand('copy'); } catch { ok = false; }
-    ta.remove();
-  }
-  if (ok) {
-    if (btnEl && !btnEl._copyFlashing) {
-      const original = btnEl.innerHTML;
-      btnEl._copyFlashing = true;
-      btnEl.innerHTML = '<svg width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.4" stroke-linecap="round" stroke-linejoin="round"><polyline points="20 6 9 17 4 12"/></svg>';
-      btnEl.classList.add('copied');
-      setTimeout(() => {
-        btnEl.innerHTML = original;
-        btnEl.classList.remove('copied');
-        btnEl._copyFlashing = false;
-      }, 1200);
-    }
-    uiModule.showToast?.('Copied');
-  } else {
-    uiModule.showError?.('Copy failed');
-  }
-  return ok;
-}
-
-function _editNote(id) {
-  const note = _notes.find(n => n.id === id);
-  if (!note) return;
-  _editingId = id;
-  const card = document.querySelector(`.note-card[data-note-id="${id}"]`);
-  if (!card) return;
-  // Restore an unsaved draft (from a prior connection loss / close) over
-  // the saved note so the user picks up where they left off.
-  const { note: _n, restored } = _applyDraftToNote(note, id);
-  const form = _buildForm(_n);
-  card.replaceWith(form);
-  if (restored) uiModule.showToast('Restored unsaved changes');
-  // Pinned notes live in the first masonry column — the edit form has
-  // column-span:all, which can leave the form rendered above the fold or
-  // visually buried under neighboring pinned cards. Bring it into view
-  // (and onto a higher stacking context) so editing a pinned note always
-  // pops to the top.
-  form.style.position = 'relative';
-  form.style.zIndex = '5';
-  // Grid view: the form keeps the CSS default `grid-row-end: span 16` (64px)
-  // after replaceWith, which is much shorter than the actual form. Recompute
-  // masonry so the form gets the correct row span and cards below stop
-  // overlapping it. ResizeObserver inside _applyMasonry keeps it in sync as
-  // the user types / adds checklist items.
-  const _body = form.closest('.notes-pane-body');
-  if (_body) {
-    _applyMasonry(_body);
-    requestAnimationFrame(() => _applyMasonry(_body));
-  }
-  requestAnimationFrame(() => {
-    try { form.scrollIntoView({ block: 'center', behavior: 'smooth' }); }
-    catch { form.scrollIntoView(); }
-  });
-  // Pick the most useful field to focus. On phones especially, the user
-  // taps Edit to type — landing in the title when there's already a title
-  // (and likely a body to extend) loses momentum. Prefer the body textarea
-  // for plain notes, the first checklist item for todos, fall back to title.
-  const _focusBest = () => {
-    if (note.note_type === 'note' || !note.note_type) {
-      const ta = form.querySelector('.note-form-content');
-      if (ta) { ta.focus(); try { ta.setSelectionRange(ta.value.length, ta.value.length); } catch {} return; }
-    }
-    if (note.note_type === 'todo' || note.note_type === 'goal' || note.note_type === 'checklist') {
-      // Last non-empty checklist row, or the first row if all empty.
-      const rows = form.querySelectorAll('.note-cl-row .note-cl-text');
-      let target = null;
-      for (const inp of rows) { if ((inp.value || '').trim()) target = inp; }
-      target = target || rows[0];
-      if (target) { target.focus(); try { target.setSelectionRange(target.value.length, target.value.length); } catch {} return; }
-    }
-    const titleEl = form.querySelector('.note-form-title');
-    if (titleEl) titleEl.focus();
-  };
-  _focusBest();
-}
-
-async function _deleteNote(id) {
-  const ok = uiModule?.styledConfirm
-    ? await uiModule.styledConfirm('Delete this note?', { confirmText: 'Delete', danger: true })
-    : confirm('Delete this note?');
-  if (!ok) return;
-  try { await _deleteNoteApi(id); await _fetchNotes(); _renderNotes(); uiModule.showToast('Deleted'); }
-  catch (err) { uiModule.showError(err.message); }
-}
-
-// ────────────────────────────────────────────────────────────────────
-// MOBILE NOTES UX — fullscreen tap-to-edit + long-press drag-to-reorder.
-// On a touch device ≤768px wide, note tiles become read-only previews;
-// a single tap opens the note in a full-bleed overlay (where all real
-// editing happens), and a long-press flips the whole grid into
-// rearrange mode where tiles can be dragged to a new sort_order.
-// ────────────────────────────────────────────────────────────────────
-
-function _isNotesMobileMode() {
-  return ('ontouchstart' in window) && window.innerWidth <= 768;
-}
-
-// ── Fullscreen single-note edit overlay ──────────────────────────────
-let _mobileFsOverlay = null;
-let _mobileFsNoteId = null;
-
-function _openMobileFullscreenEdit(id, fromCard) {
-  const note = _notes.find(n => n.id === id);
-  if (!note) return;
-  // Tear down any previous overlay (defensive).
-  _closeMobileFullscreenEdit({ save: false });
-  _mobileFsNoteId = id;
-  _editingId = id;
-
-  const overlay = document.createElement('div');
-  overlay.className = 'note-fullscreen-overlay';
-  overlay.innerHTML = `
-    <div class="note-fullscreen-header">
-      <button type="button" class="note-fullscreen-back" title="Back">
-        <svg width="22" height="22" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round"><polyline points="15 18 9 12 15 6"></polyline></svg>
-      </button>
-      <div class="note-fullscreen-actions"></div>
-    </div>
-    <div class="note-fullscreen-body"></div>
-  `;
-  const body = overlay.querySelector('.note-fullscreen-body');
-  // Reuse the same edit form the in-place flow builds. Save buttons,
-  // checklist toggles, etc. all work as-is. Restore any unsaved draft.
-  const { note: _n, restored } = _applyDraftToNote(note, id);
-  const form = _buildForm(_n);
-  body.appendChild(form);
-  if (restored) uiModule.showToast('Restored unsaved changes');
-  document.body.appendChild(overlay);
-  _mobileFsOverlay = overlay;
-
-  // Animate up from the tapped tile's position so the transition reads
-  // as a zoom rather than a hard cut.
-  if (fromCard) {
-    const r = fromCard.getBoundingClientRect();
-    const vw = window.innerWidth, vh = window.innerHeight;
-    overlay.style.transformOrigin =
-      `${((r.left + r.width / 2) / vw) * 100}% ${((r.top + r.height / 2) / vh) * 100}%`;
-  }
-  overlay.classList.add('opening');
-  requestAnimationFrame(() => overlay.classList.add('open'));
-
-  // Wire the back button — saves whatever the form has and closes.
-  // mousedown preventDefault so it doesn't blur the input on first tap (which
-  // would eat the tap and require a second one).
-  const _backBtn = overlay.querySelector('.note-fullscreen-back');
-  _backBtn.addEventListener('mousedown', (e) => e.preventDefault());
-  _backBtn.addEventListener('click', () => {
-    _closeMobileFullscreenEdit({ save: true });
-  });
-
-  // The form's built-in Cancel only resets the in-place edit state; in
-  // the overlay context it does nothing visible. Replace its handler so
-  // Cancel actually dismisses the overlay without saving.
-  const cancelBtn = form.querySelector('.note-form-cancel');
-  if (cancelBtn) {
-    const fresh = cancelBtn.cloneNode(true);
-    cancelBtn.parentNode.replaceChild(fresh, cancelBtn);
-    fresh.addEventListener('mousedown', (e) => e.preventDefault());
-    fresh.addEventListener('click', (e) => {
-      e.preventDefault();
-      e.stopPropagation();
-      _closeMobileFullscreenEdit({ save: false });
-    });
-  }
-  // The built-in Save handler does the API call + refresh, but doesn't
-  // dismiss our overlay. Augment it (do NOT replace — the original is
-  // async and we'd lose the API call) to schedule a close once the
-  // save+render has had time to complete.
-  const saveBtn = form.querySelector('.note-form-save');
-  if (saveBtn) {
-    saveBtn.addEventListener('click', () => {
-      setTimeout(() => _closeMobileFullscreenEdit({ save: false }), 350);
-    });
-  }
-  // Make the checklist row drag handle (⋮⋮) actually work on touch.
-  // The form's default uses HTML5 native draggable which never fires
-  // on iOS/Android. Wire touch-based reorder for any row inside the
-  // overlay's checklist.
-  _wireChecklistTouchReorder(form);
-
-  // For each todo row whose text contains a URL, swap the bare <input>
-  // for a linkified <span> so URLs are tappable. Tapping anywhere that
-  // ISN'T a link flips back to the input for editing.
-  form.querySelectorAll('.note-cl-row').forEach(_addRowReadMode);
-
-  // Move only Delete from the form's footer actions row into the header.
-  // Archive intentionally stays out of the header: the footer Update button
-  // already morphs into the mobile Archive action for an untouched note.
-  const headerActions = overlay.querySelector('.note-fullscreen-actions');
-  const archiveBtn = form.querySelector('.note-form-archive-btn');
-  const deleteBtn  = form.querySelector('.note-form-delete-btn');
-  if (headerActions && deleteBtn) {
-    deleteBtn.classList.remove('note-form-collapsible');
-    headerActions.appendChild(deleteBtn);
-  }
-  // The built-in archive/delete handlers re-render the notes grid but
-  // leave THIS overlay sitting in front of it — looks like nothing
-  // happened. Add follow-up listeners that close the overlay so the
-  // user sees the action take effect.
-  if (archiveBtn) {
-    archiveBtn.addEventListener('click', () => {
-      setTimeout(() => _closeMobileFullscreenEdit({ save: false }), 200);
-    });
-  }
-  if (deleteBtn) {
-    deleteBtn.addEventListener('click', () => {
-      // Delete shows a styled confirm — give it room to resolve before
-      // we try to dismiss the overlay.
-      setTimeout(() => _closeMobileFullscreenEdit({ save: false }), 500);
-    });
-  }
-
-  // Tuck the tags input into the bottom actions row (Cancel / Update),
-  // pinned to the LEFT. Frees the meta row of an extra wrapping line
-  // and groups all the "exit" controls together.
-  const actionsGroup = form.querySelector('.note-form-actions-group');
-  const tagsInput    = form.querySelector('.note-form-label');
-  if (actionsGroup && tagsInput) {
-    actionsGroup.insertBefore(tagsInput, actionsGroup.firstChild);
-  }
-
-  // For checklist-type notes, move the photo (attach image) button into
-  // the same row as the + Add button (right side) — keeps the meta row
-  // tidy and puts the camera within thumb-reach of the active edit.
-  const addBtn   = form.querySelector('.note-cl-add');
-  const photoBtn = form.querySelector('.note-form-photo-btn');
-  if (addBtn && photoBtn) {
-    const addRow = document.createElement('div');
-    addRow.className = 'note-cl-add-row';
-    addBtn.parentNode.insertBefore(addRow, addBtn);
-    addRow.appendChild(addBtn);
-    addRow.appendChild(photoBtn);
-    // Tapping anywhere on the row (the empty gap, the dashed border,
-    // the "+ Add" label) triggers add. The photo button keeps its own
-    // click target so attach-image isn't ambushed.
-    addRow.addEventListener('click', (e) => {
-      if (e.target.closest('.note-form-photo-btn')) return;
-      if (e.target === addBtn || addBtn.contains(e.target)) return;
-      addBtn.click();
-    });
-    // The form's delegated "+ Add" handler does
-    //   inputs.insertBefore(newRow, addBtn)
-    // — but addBtn is no longer a direct child of `.note-checklist-inputs`
-    // now that we wrapped it. Bind a fresh handler that does the same
-    // thing but inserts before the WRAPPING row, and stop propagation
-    // so the broken delegate never runs.
-    addBtn.addEventListener('click', (e) => {
-      e.preventDefault();
-      e.stopPropagation();
-      const inputs = form.querySelector('.note-checklist-inputs');
-      if (!inputs) return;
-      const newRow = document.createElement('div');
-      newRow.className = 'note-cl-row';
-      newRow.draggable = true;
-      newRow.dataset.itemId = _uid();
-      newRow.dataset.indent = '0';
-      newRow.innerHTML = '<span class="note-cl-grip" title="Drag">⋮⋮</span><span class="note-cl-dot"></span><input type="text" class="note-cl-text" placeholder="Item..." /><button type="button" class="note-cl-rm">&times;</button>';
-      inputs.insertBefore(newRow, addRow);
-      _wireRow(newRow, inputs);
-      // Touch reorder on the freshly-added row's grip.
-      _wireChecklistTouchReorder(form);
-      newRow.querySelector('.note-cl-text')?.focus();
-    }, { capture: true });
-  }
-
-  // Read-mode overlay for plain notes: render the content as a div with
-  // clickable hyperlinks, layered above the textarea. Tapping anywhere
-  // in the overlay that ISN'T a link hides the overlay and focuses the
-  // textarea so the user can start editing. Tapping a link opens it.
-  const ta = form.querySelector('.note-form-content');
-  if (ta && (note.content || '').trim()) {
-    const reader = document.createElement('div');
-    reader.className = 'note-form-content-reader';
-    reader.innerHTML = _linkify(note.content || '');
-    ta.style.display = 'none';
-    ta.insertAdjacentElement('beforebegin', reader);
-    reader.addEventListener('click', (e) => {
-      if (e.target.closest('a')) return;  // let links open normally
-      reader.remove();
-      ta.style.display = '';
-      // Let the browser place the cursor naturally — forcing
-      // setSelectionRange right after focus() raced with the underlying
-      // tap event and produced inconsistent cursor positions on mobile.
-      ta.focus({ preventScroll: true });
-    });
-  }
-
-  // Opening an EXISTING note → read mode, no keyboard pop. Only a
-  // brand-new note (created via the + button) should auto-focus an
-  // input field. The user can tap the content to switch to edit.
-  // (New-note creation flows through _createNote, not this function.)
-}
-
-function _closeMobileFullscreenEdit(opts = {}) {
-  if (!_mobileFsOverlay) return;
-  const overlay = _mobileFsOverlay;
-  overlay.querySelector('.note-form')?._flushDraft?.();
-  _mobileFsOverlay = null;
-  // If the form has a Save button, click it on close so edits aren't lost
-  // when the user uses the back arrow instead of an explicit Save.
-  if (opts.save) {
-    const saveBtn = overlay.querySelector('.note-form-save, [data-action="save"]');
-    if (saveBtn) try { saveBtn.click(); } catch {}
-  }
-  overlay.classList.remove('open');
-  overlay.classList.add('closing');
-  setTimeout(() => {
-    if (overlay.parentNode) overlay.parentNode.removeChild(overlay);
-    _mobileFsNoteId = null;
-    _editingId = null;
-    // Refresh the grid so any save the user made is reflected.
-    if (opts.save !== false) { _fetchNotes().then(_renderNotes).catch(() => {}); }
-  }, 220);
-}
-
-// ── Long-press select ────────────────────────────────────────────────
-function _bindLongPressDrag(card) {
-  let pressTimer = null;
-  let startX = 0, startY = 0;
-  let armed = false;
-  const CANCEL_PX = 8;
-  const HOLD_MS = 450;
-
-  card.addEventListener('touchstart', (e) => {
-    // Don't fight scroll on touchpoints over real interactive children
-    // (in mobile-mode they're CSS-hidden anyway, but be defensive).
-    if (e.target.closest('button, input, a, .note-form')) return;
-    if (e.touches.length !== 1) return;
-    armed = true;
-    startX = e.touches[0].clientX;
-    startY = e.touches[0].clientY;
-    pressTimer = setTimeout(() => {
-      if (!armed) return;
-      try { navigator.vibrate?.(15); } catch {}
-      _suppressNextNoteTapId = card.dataset.noteId;
-      _enterSelectMode(card.dataset.noteId);
-    }, HOLD_MS);
-  }, { passive: true });
-  card.addEventListener('touchmove', (e) => {
-    if (!armed) return;
-    const t = e.touches[0];
-    if (Math.abs(t.clientX - startX) > CANCEL_PX || Math.abs(t.clientY - startY) > CANCEL_PX) {
-      armed = false;
-      if (pressTimer) { clearTimeout(pressTimer); pressTimer = null; }
-    }
-  }, { passive: true });
-  const cancel = () => {
-    armed = false;
-    if (pressTimer) { clearTimeout(pressTimer); pressTimer = null; }
-  };
-  card.addEventListener('touchend', cancel, { passive: true });
-  card.addEventListener('touchcancel', cancel, { passive: true });
-}
-
-// Lift-and-placeholder drag implementation. The dragged card detaches
-// from the grid (position:fixed, anchored to the finger) while a same-
-// sized placeholder takes its slot. Only the PLACEHOLDER moves between
-// siblings as the finger crosses midpoints — the card never re-parents
-// during the drag, which eliminates the oscillation/jumping the
-// previous swap-on-every-frame implementation had.
-
-let _dragState = null;          // { card, placeholder, grabOffsetX, grabOffsetY, grid, prevStyle }
-let _docDragHandlersBound = false;
-
-function _enterDragMode(initialCard, initialTouch) {
-  document.body.classList.add('notes-drag-mode');
-  document.querySelectorAll('.note-card').forEach(_setupDragForCard);
-  if (!_docDragHandlersBound) {
-    document.addEventListener('touchmove', _onDocTouchMove, { passive: false });
-    document.addEventListener('touchend',  _onDocTouchEnd,  { passive: true });
-    document.addEventListener('touchcancel', _onDocTouchEnd, { passive: true });
-    _docDragHandlersBound = true;
-  }
-  // Auto-grab the card the user long-pressed — they're already holding
-  // their finger on it, so begin the drag straight away. Releasing
-  // (touchend) commits the reorder AND exits drag mode in one motion.
-  if (initialCard && initialTouch) {
-    _beginGrab(initialCard, initialTouch);
-  }
-}
-
-function _exitDragMode() {
-  document.body.classList.remove('notes-drag-mode');
-  if (_dragState) {
-    // Defensive: if exit fires while a drag is in flight, snap the card back.
-    _onDocTouchEnd();
-  }
-  // Leave _docDragHandlersBound true so re-entering drag mode reuses them.
-}
-
-function _setupDragForCard(card) {
-  if (card.dataset.dragBound === '1') return;
-  card.dataset.dragBound = '1';
-  card.addEventListener('touchstart', (e) => {
-    if (!document.body.classList.contains('notes-drag-mode')) return;
-    if (e.touches.length !== 1) return;
-    if (_dragState) return;
-    e.preventDefault();
-    e.stopPropagation();
-    _beginGrab(card, e.touches[0]);
-  }, { passive: false });
-}
-
-function _beginGrab(card, touch) {
-  const rect = card.getBoundingClientRect();
-  const prevStyle = card.getAttribute('style') || '';
-  // Placeholder fills the card's old slot so the grid layout doesn't reflow.
-  const placeholder = document.createElement('div');
-  placeholder.className = 'note-card-placeholder';
-  placeholder.style.width = rect.width + 'px';
-  placeholder.style.height = rect.height + 'px';
-  placeholder.style.margin = getComputedStyle(card).margin;
-  if (card.style.gridRowEnd) placeholder.style.gridRowEnd = card.style.gridRowEnd;
-  const grid = card.parentNode;
-  grid.insertBefore(placeholder, card);
-
-  // Detach the card visually — fixed-position, anchored to the finger.
-  card.classList.add('note-card-dragging');
-  card.style.position = 'fixed';
-  card.style.left = rect.left + 'px';
-  card.style.top  = rect.top + 'px';
-  card.style.width  = rect.width + 'px';
-  card.style.height = rect.height + 'px';
-  card.style.margin = '0';
-  card.style.zIndex = '10001';
-  // pointer-events:none so elementFromPoint sees the card BENEATH the finger
-  card.style.pointerEvents = 'none';
-
-  _dragState = {
-    card, placeholder, grid, prevStyle,
-    grabOffsetX: touch.clientX - rect.left,
-    grabOffsetY: touch.clientY - rect.top,
-  };
-  try { navigator.vibrate?.(8); } catch {}
-}
-
-function _onDocTouchMove(e) {
-  if (!_dragState) return;
-  if (e.touches.length !== 1) return;
-  e.preventDefault();
-  const touch = e.touches[0];
-  const { card, placeholder, grid } = _dragState;
-  card.style.left = (touch.clientX - _dragState.grabOffsetX) + 'px';
-  const quickAdd = grid.querySelector('.notes-quick-add');
-  const minTop = quickAdd ? quickAdd.getBoundingClientRect().bottom + 4 : grid.getBoundingClientRect().top;
-  const maxTop = Math.max(minTop, window.innerHeight - card.getBoundingClientRect().height - 8);
-  const nextTop = Math.max(minTop, Math.min(maxTop, touch.clientY - _dragState.grabOffsetY));
-  card.style.top = nextTop + 'px';
-
-  const hitY = Math.max(minTop + 1, Math.min(window.innerHeight - 1, touch.clientY));
-  const under = document.elementFromPoint(touch.clientX, hitY);
-  const target = under && under.closest
-    ? under.closest('.note-card:not(.note-card-dragging)')
-    : null;
-  if (!target || target === card) return;
-  if (target.parentNode !== grid) return;
-
-  // Move the PLACEHOLDER (not the card) above or below the target depending
-  // on which half of the target the finger is in. This is the hysteresis
-  // that stops the oscillation — once the placeholder moves past a card,
-  // the cursor has to cross THAT card's midpoint in the other direction
-  // to swap back.
-  const tRect = target.getBoundingClientRect();
-  const targetMidY = tRect.top + tRect.height / 2;
-  if (touch.clientY < targetMidY) {
-    if (placeholder.nextElementSibling !== target) {
-      grid.insertBefore(placeholder, target);
-    }
-  } else {
-    if (target.nextElementSibling !== placeholder) {
-      grid.insertBefore(placeholder, target.nextElementSibling);
-    }
-  }
-}
-
-function _onDocTouchEnd() {
-  if (!_dragState) return;
-  const { card, placeholder, grid, prevStyle } = _dragState;
-  _dragState = null;
-  // Animate the card from its current fixed position to where the
-  // placeholder sits, then re-parent and clear inline styles. Drag
-  // mode auto-exits once the snap finishes — release = done.
-  const phRect = placeholder.getBoundingClientRect();
-  card.style.transition = 'left 0.2s ease, top 0.2s ease';
-  card.style.left = phRect.left + 'px';
-  card.style.top  = phRect.top + 'px';
-  setTimeout(() => {
-    placeholder.parentNode.insertBefore(card, placeholder);
-    placeholder.remove();
-    card.classList.remove('note-card-dragging');
-    // Restore the card's pre-drag inline styles. Mobile masonry stores
-    // grid-row-end inline, and custom backgrounds use inline style too; wiping
-    // cssText made dropped cards collapse into neighboring notes in grid view.
-    if (prevStyle) card.setAttribute('style', prevStyle);
-    else card.removeAttribute('style');
-    _applyMasonry(grid);
-    _commitNoteReorder();
-    // One drag, one exit — release ends the rearrange session entirely.
-    if (document.body.classList.contains('notes-drag-mode')) {
-      document.body.classList.remove('notes-drag-mode');
-    }
-  }, 210);
-}
-
-// Per-row read mode for todo items — replaces the plain <input> with
-// a linkified <span> when the value contains a URL, so tapping a link
-// opens it instead of just placing the caret. Tapping non-link area
-// restores the input for editing.
-function _addRowReadMode(row) {
-  const txt = row.querySelector('.note-cl-text');
-  if (!txt) return;
-  const val = txt.value || '';
-  if (!/(https?:\/\/|www\.)/i.test(val)) return;
-  if (row.querySelector('.note-cl-text-reader')) return;  // already wired
-  const span = document.createElement('span');
-  span.className = 'note-cl-text-reader';
-  span.innerHTML = _linkify(val);
-  txt.style.display = 'none';
-  txt.insertAdjacentElement('beforebegin', span);
-  span.addEventListener('click', (e) => {
-    if (e.target.closest('a')) return;  // let the link open
-    span.remove();
-    txt.style.display = '';
-    txt.focus({ preventScroll: true });
-  });
-}
-
-// ── Checklist row reorder via touch (inside fullscreen edit) ────────
-// The default checklist drag uses HTML5 `draggable="true"`, which is
-// desktop-mouse-only. Wire touch handlers on each `.note-cl-grip` so
-// the user can long-grab a row and drag it to a new position in the
-// checklist. Uses the same lift-and-placeholder pattern as the card
-// drag (no oscillation when hovering between siblings).
-
-let _clDrag = null;          // { row, placeholder, container, grabOffsetX, grabOffsetY }
-let _clDocBound = false;
-
-function _wireChecklistTouchReorder(form) {
-  const container = form.querySelector('.note-checklist-inputs');
-  if (!container) return;
-  container.querySelectorAll('.note-cl-grip').forEach(grip => {
-    if (grip.dataset.touchBound === '1') return;
-    grip.dataset.touchBound = '1';
-    grip.addEventListener('touchstart', (e) => {
-      if (e.touches.length !== 1) return;
-      e.preventDefault();
-      const row = grip.closest('.note-cl-row');
-      if (!row) return;
-      _beginChecklistGrab(row, container, e.touches[0]);
-    }, { passive: false });
-  });
-  if (!_clDocBound) {
-    document.addEventListener('touchmove', _onClTouchMove, { passive: false });
-    document.addEventListener('touchend',  _onClTouchEnd,  { passive: true });
-    document.addEventListener('touchcancel', _onClTouchEnd, { passive: true });
-    _clDocBound = true;
-  }
-}
-
-function _beginChecklistGrab(row, container, touch) {
-  if (_clDrag) return;
-  const rect = row.getBoundingClientRect();
-  const placeholder = document.createElement('div');
-  placeholder.className = 'note-cl-row-placeholder';
-  placeholder.style.height = rect.height + 'px';
-  container.insertBefore(placeholder, row);
-
-  row.classList.add('note-cl-row-dragging');
-  row.style.position = 'fixed';
-  row.style.left = rect.left + 'px';
-  row.style.top  = rect.top + 'px';
-  row.style.width = rect.width + 'px';
-  row.style.zIndex = '10002';
-  row.style.pointerEvents = 'none';
-
-  _clDrag = {
-    row, placeholder, container,
-    grabOffsetX: touch.clientX - rect.left,
-    grabOffsetY: touch.clientY - rect.top,
-  };
-  try { navigator.vibrate?.(8); } catch {}
-}
-
-function _onClTouchMove(e) {
-  if (!_clDrag) return;
-  if (e.touches.length !== 1) return;
-  e.preventDefault();
-  const t = e.touches[0];
-  const { row, placeholder, container } = _clDrag;
-  row.style.left = (t.clientX - _clDrag.grabOffsetX) + 'px';
-  row.style.top  = (t.clientY - _clDrag.grabOffsetY) + 'px';
-
-  const under = document.elementFromPoint(t.clientX, t.clientY);
-  const target = under && under.closest
-    ? under.closest('.note-cl-row:not(.note-cl-row-dragging)')
-    : null;
-  if (!target || target === row) return;
-  if (target.parentNode !== container) return;
-
-  const tRect = target.getBoundingClientRect();
-  const targetMidY = tRect.top + tRect.height / 2;
-  if (t.clientY < targetMidY) {
-    if (placeholder.nextElementSibling !== target) {
-      container.insertBefore(placeholder, target);
-    }
-  } else {
-    if (target.nextElementSibling !== placeholder) {
-      container.insertBefore(placeholder, target.nextElementSibling);
-    }
-  }
-}
-
-function _onClTouchEnd() {
-  if (!_clDrag) return;
-  const { row, placeholder } = _clDrag;
-  _clDrag = null;
-  const phRect = placeholder.getBoundingClientRect();
-  row.style.transition = 'left 0.18s ease, top 0.18s ease';
-  row.style.left = phRect.left + 'px';
-  row.style.top  = phRect.top + 'px';
-  setTimeout(() => {
-    placeholder.parentNode.insertBefore(row, placeholder);
-    placeholder.remove();
-    row.classList.remove('note-cl-row-dragging');
-    row.style.cssText = '';
-    // Order is persisted as part of the form's normal save (rows are
-    // re-serialized in DOM order via _collectItems).
-  }, 200);
-}
-
-async function _commitNoteReorder() {
-  const grid = document.querySelector('#notes-pane .notes-pane-body');
-  if (!grid) return;
-  const ids = Array.from(grid.querySelectorAll('.note-card')).map(c => c.dataset.noteId).filter(Boolean);
-  if (!ids.length) return;
-  try {
-    await fetch(`${API_BASE}/api/notes/reorder`, {
-      method: 'POST',
-      credentials: 'same-origin',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ ids }),
-    });
-    // Update local sort_order so subsequent renders agree with the server.
-    ids.forEach((nid, i) => {
-      const n = _notes.find(nn => nn.id === nid);
-      if (n) n.sort_order = i;
-    });
-  } catch (e) {
-    console.warn('reorder failed', e);
-  }
-}
-
-
-// Background reminder loop — runs whether panel is open or not
-async function _initReminders() {
-  try {
-    const res = await fetch(`${API_BASE}/api/notes`, { credentials: 'same-origin' });
-    if (res.ok) {
-      const data = await res.json();
-      _notes = data.notes || data || [];
-      _startReminderLoop();
-    }
-  } catch {}
-}
-
-// Open the notes panel and scroll/flash the matching note card. Used
-// by chatRenderer.js when the user clicks a [View note](#note-<id>)
-// link the agent emits after a manage_notes create. Falls back to
-// just opening the panel when the card isn't found (panel still
-// loading, note in a different filter, etc.).
-function _smoothScrollToNoteCard(card) {
-  if (!card) return;
-  const scroller = card.closest('.notes-pane-body');
-  if (!scroller) {
-    try { card.scrollIntoView({ block: 'center', behavior: 'smooth' }); } catch (_) {}
-    return;
-  }
-  const scrollerRect = scroller.getBoundingClientRect();
-  const cardRect = card.getBoundingClientRect();
-  const delta = (cardRect.top - scrollerRect.top) - (scroller.clientHeight - cardRect.height) / 2;
-  scroller.scrollTo({ top: Math.max(0, scroller.scrollTop + delta), behavior: 'smooth' });
-}
-
-async function openNote(noteId) {
-  const wasOpen = !!(isPanelOpen && isPanelOpen());
-  _showingArchived = false;
-  _activeLabel = null;
-  _activeFilter = null;
-  _searchQuery = '';
-  if (!wasOpen) {
-    openPanel();
-  } else {
-    _bringNotesToFront();
-    const searchEl = document.getElementById('notes-search');
-    if (searchEl) searchEl.value = '';
-    const pane = document.getElementById('notes-pane');
-    if (pane) pane.classList.remove('notes-pane-archive');
-    const archiveBtn = document.getElementById('notes-archive-toggle');
-    if (archiveBtn) archiveBtn.classList.remove('active');
-    await _fetchNotes();
-    _renderNotes();
-  }
-  // openPanel() kicks off _fetchNotes() asynchronously, so the cards for
-  // newly-created notes may not be in the DOM yet. Poll until the card exists.
-  if (!noteId) return;
-  let tries = 0;
-  const findAndFlash = () => {
-    const card = document.querySelector(`.note-card[data-note-id="${noteId}"]`)
-      || document.querySelector(`.note-card[data-note-id^="${noteId.slice(0, 8)}"]`);
-    if (card) {
-      _smoothScrollToNoteCard(card);
-      card.classList.add('note-card-flash');
-      setTimeout(() => card.classList.remove('note-card-flash'), 1600);
-      return true;
-    }
-    return false;
-  };
-  const tryNext = () => {
-    if (findAndFlash()) return;
-    if (++tries < 20) setTimeout(tryNext, 200);
-  };
-  setTimeout(tryNext, 120);
-}
-
-const notesModule = { openPanel, closePanel, togglePanel, isPanelOpen, openNote, newNote, openNotes: openPanel, closeNotes: closePanel, isNotesOpen: isPanelOpen, refreshDueBadge };
-export default notesModule;
-export { openPanel as openNotes, closePanel as closeNotes, isPanelOpen as isNotesOpen, openNote };
+/** Compatibility URL. All consumers share the canonical Notes feature instance. */
+import notesModule, { startNotesBackground } from './features/notes/index.js';
+export { default, openPanel, closePanel, togglePanel, isPanelOpen, openNote, newNote, refreshDueBadge, dismissFiredReminderDot, openNotes, closeNotes, isNotesOpen } from './features/notes/index.js';
 window.notesModule = notesModule;
-
-// Start reminder loop on module load (after a short delay so app loads first)
-if (typeof window !== 'undefined') {
-  setTimeout(_initReminders, 3000);
-}
+startNotesBackground();
diff --git a/static/js/shared/ui/confetti.js b/static/js/shared/ui/confetti.js
new file mode 100644
index 000000000..205f9acdc
--- /dev/null
+++ b/static/js/shared/ui/confetti.js
@@ -0,0 +1,28 @@
+/** Stateless celebration renderer shared by Notes and Compare. */
+export function spawnConfetti(cx, cy, count) {
+  const colors = ['#ffd700', '#ff6b6b', '#5b8def', '#51cf66', '#ff922b', '#cc5de8', '#22b8cf', '#fff'];
+  for (let i = 0; i < count; i++) {
+    const el = document.createElement('div');
+    el.className = 'confetti-piece';
+    const color = colors[Math.floor(Math.random() * colors.length)];
+    const size = 5 + Math.random() * 8;
+    const isCircle = Math.random() > 0.5;
+    el.style.width = size + 'px';
+    el.style.height = (isCircle ? size : size * 0.6) + 'px';
+    el.style.background = color;
+    el.style.borderRadius = isCircle ? '50%' : '2px';
+    el.style.left = cx + 'px';
+    el.style.top = cy + 'px';
+    const angle = Math.random() * Math.PI * 2;
+    const speed = 60 + Math.random() * 160;
+    const dx = Math.cos(angle) * speed;
+    const dy = Math.sin(angle) * speed - 100;
+    const duration = 1.0 + Math.random() * 1.0;
+    el.animate([
+      { transform: 'translate(0, 0) rotate(0deg) scale(1)', opacity: 1 },
+      { transform: `translate(${dx}px, ${dy + 200}px) rotate(${400 + Math.random() * 400}deg) scale(0)`, opacity: 0 }
+    ], { duration: duration * 1000, easing: 'cubic-bezier(0.15, 0.6, 0.35, 1)', fill: 'forwards' });
+    document.body.appendChild(el);
+    setTimeout(() => el.remove(), duration * 1000 + 50);
+  }
+}
diff --git a/static/sw.js b/static/sw.js
index 53973faf0..1cc5c8a78 100644
--- a/static/sw.js
+++ b/static/sw.js
@@ -7,7 +7,7 @@
 //   - Other static assets (images/fonts/libs): cache-first with bg refresh.
 //   - API / non-GET: never cached.
 // Bump CACHE_NAME whenever the precache list or SW logic changes.
-const CACHE_NAME = 'odysseus-v658-publication-assets-restore';
+const CACHE_NAME = 'odysseus-v659-notes-reference';
 
 // KaTeX resolves these from its own stylesheet, so caching the CSS without them
 // gives offline math fallback glyphs instead of proper typesetting.
@@ -115,6 +115,57 @@ const PRECACHE = [
   // emailInbox.js has always imported this one; it was never precached.
   '/static/js/emailLibrary/replyRecipients.js',
   '/static/js/notes.js?v=20260911notesselectioncancel1',
+  '/static/js/features/notes/domain/recurrence.js',
+  // Exact legacy URLs still reached by the Notes graph.
+  '/static/js/toolWindowZOrder.js',
+  '/static/js/color/hex.js',
+  '/static/js/windowDrag.js',
+  '/static/js/modalSnap.js',
+  '/static/js/windowResize.js',
+  '/static/js/modalManager.js',
+  '/static/js/escMenuStack.js',
+  '/static/js/tourHintDismiss.js',
+  '/static/js/shared/ui/confetti.js',
+  '/static/js/features/notes/application/selection.js',
+  '/static/js/features/notes/ui/toolbar.js',
+  '/static/js/features/notes/ui/windowLayout.js',
+  '/static/js/features/notes/application/cardOperations.js',
+  '/static/js/features/notes/application/checklistOperations.js',
+  '/static/js/features/notes/application/submission.js',
+  '/static/js/features/notes/application/drafts.js',
+  '/static/js/features/notes/ui/lifecycle.js',
+  '/static/js/features/notes/ui/text.js',
+  '/static/js/features/notes/ui/colors.js',
+  '/static/js/features/notes/ui/panel.js',
+  '/static/js/features/notes/ui/reminderDisplay.js',
+  '/static/js/features/notes/ui/selection.js',
+  '/static/js/features/notes/ui/filters.js',
+  '/static/js/features/notes/ui/cardRendering.js',
+  '/static/js/features/notes/ui/layout.js',
+  '/static/js/features/notes/ui/quickAdd.js',
+  '/static/js/features/notes/ui/cardInteractions.js',
+  '/static/js/features/notes/ui/cardChecklist.js',
+  '/static/js/features/notes/ui/cardReorder.js',
+  '/static/js/features/notes/ui/draftEditor.js',
+  '/static/js/features/notes/ui/editor.js',
+  '/static/js/features/notes/ui/reminderPicker.js',
+  '/static/js/features/notes/ui/checklist.js',
+  '/static/js/features/notes/ui/drawing.js',
+  '/static/js/features/notes/ui/clipboard.js',
+  '/static/js/features/notes/ui/mobileEditor.js',
+  '/static/js/features/notes/ui/mobileReorder.js',
+  '/static/js/features/notes/ui/checklistReorder.js',
+  '/static/js/features/notes/application/queries.js',
+  '/static/js/features/notes/application/agentActions.js',
+  '/static/js/features/notes/application/deletion.js',
+  '/static/js/features/notes/domain/noteRules.js',
+  '/static/js/features/notes/index.js',
+  '/static/js/features/notes/application/reminders.js',
+  '/static/js/features/notes/infrastructure/notifications.js',
+  '/static/js/features/notes/application/state.js',
+  '/static/js/features/notes/application/workflows.js',
+  '/static/js/features/notes/infrastructure/http.js',
+  '/static/js/features/notes/infrastructure/storage.js',
   '/static/js/tasks.js?v=20260914taskmodel1',
   '/static/js/calendar.js?v=20260914emailsource11',
   '/static/js/calendar/utils.js',
diff --git a/tests/browser/notesNative.mjs b/tests/browser/notesNative.mjs
new file mode 100644
index 000000000..5270293c3
--- /dev/null
+++ b/tests/browser/notesNative.mjs
@@ -0,0 +1,66 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import { chromium } from 'playwright';
+import { randomUUID } from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+
+const origin = process.env.ODYSSEUS_NOTES_RUNTIME_ORIGIN;
+const evidence = process.env.NOTES_NATIVE_EVIDENCE_DIR;
+if (evidence) fs.mkdirSync(evidence, { recursive: true });
+const browser = await chromium.launch({ headless: true });
+const credentials = { username: 'notes-reference', password: randomUUID() + 'Aa1!' };
+try {
+  for (const mobile of [false, true]) {
+    const context = await browser.newContext({ viewport: mobile ? { width: 390, height: 844 } : { width: 1440, height: 1000 }, hasTouch: mobile, isMobile: mobile });
+    const page = await context.newPage();
+    if (!mobile) {
+      const setup = await context.request.post(`${origin}/api/auth/setup`, { data: credentials });
+      assert.equal(setup.ok(), true, await setup.text());
+    }
+    const login = await context.request.post(`${origin}/api/auth/login`, { data: credentials });
+    assert.equal(login.ok(), true, await login.text());
+    const response = await context.request.post(`${origin}/api/notes`, { data: { title: mobile ? 'Mobile reference' : 'Desktop reference', content: 'Native API draft', note_type: 'note', label: 'reference' } });
+    assert.equal(response.ok(), true, await response.text());
+    const created = await response.json();
+    assert.ok(created.id);
+    assert.equal(created.owner, credentials.username);
+    await page.goto(origin);
+    await page.waitForFunction(() => window.notesModule?.openPanel);
+    await page.evaluate(() => { localStorage.setItem('odysseus-notes-first-open-hint-v1', '1'); window.notesModule.openPanel(); });
+    const card = page.locator(`.note-card[data-note-id="${created.id}"]`);
+    await card.waitFor();
+    if (evidence) await page.screenshot({ path: path.join(evidence, mobile ? 'native-mobile.png' : 'native-desktop.png'), fullPage: true, animations: 'disabled' });
+    await page.locator('#notes-select-btn').click();
+    await card.locator('.note-card-cb').check({ force: mobile });
+    await page.locator('#notes-send-agent').click();
+    assert.ok(await page.locator('.note-card-selectmode').count());
+    await page.evaluate(async () => {
+      const sessions = await import('/static/js/sessions.js');
+      sessions.createDirectChat('http://127.0.0.1:1', 'reference-model', null);
+    });
+    await page.locator('#notes-send-agent').click();
+    assert.equal(await page.locator('.note-card-selectmode').count(), 0);
+    assert.equal(await page.locator('#selected-notes-context-count').textContent(), '1 note selected');
+    await page.evaluate(async () => (await import('/static/js/sessions.js')).createDirectChat('http://127.0.0.1:1', 'another-reference-model', null));
+    assert.equal(await page.locator('#selected-notes-context-count').textContent(), '');
+    if (mobile) await card.locator('.note-card-title').tap();
+    else await card.locator('.note-card-title').click();
+    if (mobile) await page.locator('.note-form-content-reader').tap({ position: { x: 5, y: 5 } });
+    await page.locator('.note-form-content').fill('Saved by the native Notes application');
+    await page.waitForFunction(id => !localStorage.getItem('odysseus-note-draft-' + id), created.id);
+    const fetched = await context.request.get(`${origin}/api/notes`);
+    const notes = (await fetched.json()).notes;
+    assert.equal(notes.find(note => note.id === created.id).content, 'Saved by the native Notes application');
+    await page.evaluate(() => window.notesModule.closePanel());
+    await page.locator('#notes-pane').waitFor({ state: 'detached' });
+    await context.close();
+    console.log(JSON.stringify({ native: true, mobile, noteId: created.id, crud: true, selectedContext: true }));
+  }
+  const smoke = spawnSync(process.env.NOTES_TEST_PYTHON, ['-m', 'pytest', '-q', 'tests/smoke/test_notes_smoke.py'], {
+    env: { ...process.env, APP_PORT: new URL(origin).port, ODYSSEUS_ADMIN_USER: credentials.username, ODYSSEUS_ADMIN_PASSWORD: credentials.password },
+    encoding: 'utf8', timeout: 90000,
+  });
+  assert.equal(smoke.status, 0, smoke.stdout + smoke.stderr);
+  console.log('PASS: original Notes release smoke test against the disposable authenticated instance');
+} finally { await browser.close(); }
diff --git a/tests/browser/notesOffline.mjs b/tests/browser/notesOffline.mjs
new file mode 100644
index 000000000..e8d97bf49
--- /dev/null
+++ b/tests/browser/notesOffline.mjs
@@ -0,0 +1,39 @@
+import assert from 'node:assert/strict';
+import { chromium } from 'playwright';
+import fs from 'node:fs';
+
+const origin = process.env.ODYSSEUS_TEST_STATIC_ORIGIN;
+const manifest = JSON.parse(fs.readFileSync(new URL('../../frontend/modules.json', import.meta.url), 'utf8'));
+const outputs = manifest.modules.map(entry => '/static/' + entry.deployment);
+const browser = await chromium.launch({ headless: true });
+try {
+  const context = await browser.newContext({ serviceWorkers: 'allow' });
+  const page = await context.newPage();
+  await page.goto(`${origin}/static/js/panels.js`);
+  const cached = await page.evaluate(async outputs => {
+    await navigator.serviceWorker.register('/static/sw.js');
+    await navigator.serviceWorker.ready;
+    if (!navigator.serviceWorker.controller) await new Promise(resolve => navigator.serviceWorker.addEventListener('controllerchange', resolve, { once: true }));
+    const missing = [];
+    for (const output of outputs) if (!(await caches.match(output))?.ok) missing.push(output);
+    return missing;
+  }, outputs);
+  assert.deepEqual(cached, []);
+  assert.equal(await page.evaluate(async () => {
+    const shared = await import('/static/js/shared/ui/confetti.js');
+    const compare = await import('/static/js/compare/vote.js?v=20260828resendcaldrag1');
+    return shared.spawnConfetti === compare.spawnConfetti;
+  }), true);
+  await context.setOffline(true);
+  const offline = await context.newPage();
+  offline.on('requestfailed', request => console.log('offline failed:', request.url(), request.failure()));
+  offline.on('console', message => { if (message.type() === 'error') console.log('browser:', message.text()); });
+  await offline.goto(`${origin}/static/js/panels.js`);
+  const result = await offline.evaluate(async () => {
+    const facade = await import('/static/js/notes.js?v=20260911notesselectioncancel1');
+    const feature = await import('/static/js/features/notes/index.js');
+    return { identity: facade.default === feature.default && window.notesModule === feature.default, closed: facade.isPanelOpen() === false, exports: Object.keys(facade).sort() };
+  });
+  assert.equal(result.identity && result.closed, true);
+  console.log(JSON.stringify({ ...result, maintainedPrecache: outputs.length }));
+} finally { await browser.close(); }
diff --git a/tests/browser/notesReference.mjs b/tests/browser/notesReference.mjs
new file mode 100644
index 000000000..9397a0eb3
--- /dev/null
+++ b/tests/browser/notesReference.mjs
@@ -0,0 +1,148 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { chromium } from 'playwright';
+
+const origin = process.env.ODYSSEUS_TEST_STATIC_ORIGIN;
+const evidence = process.env.NOTES_EVIDENCE_DIR;
+if (evidence) fs.mkdirSync(evidence, { recursive: true });
+const baseline = process.env.NOTES_BASELINE === '1';
+const browser = await chromium.launch({ headless: true });
+try {
+  for (const device of ['desktop', 'mobile', 'tablet']) {
+    const mobile = device === 'mobile';
+    const context = await browser.newContext({ viewport: mobile ? { width: 390, height: 844 } : device === 'tablet' ? { width: 1024, height: 800 } : { width: 1440, height: 1000 }, hasTouch: device !== 'desktop', isMobile: mobile });
+    const page = await context.newPage();
+    const errors = [];
+    page.on('pageerror', error => errors.push(error.stack));
+    if (baseline) {
+      const body = execFileSync('git', ['show', '1cc56cb9:static/js/notes.js'], { encoding: 'utf8' });
+      await page.route('**/static/js/notes.js*', route => route.fulfill({ contentType: 'text/javascript', body }));
+    }
+    const requests = [];
+    const notes = [
+      { id: 'plain', title: 'Reference note', note_type: 'note', content: 'Visit https://example.org and keep this draft.', label: 'work', sort_order: 0 },
+      { id: 'todo', title: 'Reference checklist', note_type: 'todo', items: [{ text: 'First task', done: false }, { text: 'Second task', done: true }], sort_order: 1 },
+      { id: 'goal', title: 'Reference goal', note_type: 'goal', content: 'A bounded goal', items: [{ text: 'Next step', done: false }], sort_order: 2 },
+    ];
+    await page.route('**/api/**', async route => {
+      const request = route.request();
+      requests.push({ url: new URL(request.url()).pathname, method: request.method(), body: request.postData() });
+      const id = new URL(request.url()).pathname.split('/').at(-1);
+      if (request.method() === 'PUT') Object.assign(notes.find(n => n.id === id) || {}, request.postDataJSON());
+      await route.fulfill({ json: request.method() === 'GET' ? { notes } : notes.find(n => n.id === id) || {} });
+    });
+    await page.goto(`${origin}/static/js/panels.js`);
+    const shell = fs.readFileSync(new URL('../../static/index.html', import.meta.url), 'utf8');
+    const styles = [...shell.matchAll(/<link[^>]+rel="stylesheet"[^>]*>/g)].map(m => m[0]).join('\n');
+    await page.setContent(`<html><head><meta name="viewport" content="width=device-width,initial-scale=1">${styles}</head><body><div id="chat-container"></div><div id="toast"></div><button id="tool-notes-btn"><span id="notes-new-note-btn"></span></button><button id="rail-notes"></button></body></html>`);
+    await page.evaluate(() => {
+      localStorage.setItem('odysseus-notes-first-open-hint-v1', '1');
+      window.referenceIntervals = [];
+      window.referenceMouseups = new Set();
+      const add = window.addEventListener.bind(window), remove = window.removeEventListener.bind(window);
+      window.addEventListener = (type, fn, options) => { if (type === 'mouseup' && fn.name === '_end') window.referenceMouseups.add(fn); add(type, fn, options); };
+      window.removeEventListener = (type, fn, options) => { if (type === 'mouseup' && fn.name === '_end') window.referenceMouseups.delete(fn); remove(type, fn, options); };
+      const interval = window.setInterval.bind(window);
+      window.setInterval = (fn, ms, ...args) => { const id = interval(fn, ms, ...args); window.referenceIntervals.push({ id, ms }); return id; };
+    });
+    const publicAPI = await page.evaluate(async () => {
+      const mod = await import('/static/js/notes.js?v=20260911notesselectioncancel1');
+      const again = await import('/static/js/notes.js?v=20260911notesselectioncancel1');
+      window.referenceNotes = mod;
+      mod.openPanel();
+      return { names: Object.keys(mod).sort(), defaults: Object.keys(mod.default).sort(), arities: Object.fromEntries(Object.keys(mod).filter(k => k !== 'default').map(k => [k, mod[k].length])), asyncMethods: Object.keys(mod).filter(k => mod[k]?.constructor?.name === 'AsyncFunction').sort(), singleton: again === mod, bridge: window.notesModule === mod.default, aliases: mod.openNotes === mod.openPanel && mod.closeNotes === mod.closePanel && mod.isNotesOpen === mod.isPanelOpen && mod.default.openNotes === mod.openPanel };
+    });
+    assert.equal(publicAPI.singleton && publicAPI.bridge && publicAPI.aliases, true);
+    assert.deepEqual(publicAPI.names, ['closeNotes', 'closePanel', 'default', 'dismissFiredReminderDot', 'isNotesOpen', 'isPanelOpen', 'newNote', 'openNote', 'openNotes', 'openPanel', 'refreshDueBadge', 'togglePanel']);
+    assert.deepEqual(publicAPI.defaults, ['closeNotes', 'closePanel', 'isNotesOpen', 'isPanelOpen', 'newNote', 'openNote', 'openNotes', 'openPanel', 'refreshDueBadge', 'togglePanel']);
+    assert.deepEqual(publicAPI.arities, { closeNotes: 1, closePanel: 1, dismissFiredReminderDot: 0, isNotesOpen: 0, isPanelOpen: 0, newNote: 0, openNote: 1, openNotes: 0, openPanel: 0, refreshDueBadge: 0, togglePanel: 0 });
+    assert.deepEqual(publicAPI.asyncMethods, ['openNote', 'refreshDueBadge']);
+    await page.locator('.note-card').first().waitFor();
+    assert.equal(await page.locator('.note-card').count(), 3);
+    if (evidence) await page.screenshot({ path: path.join(evidence, `notes-${device}.png`), fullPage: true, animations: 'disabled' });
+    await page.locator('#notes-search').fill('checklist');
+    assert.equal(await page.locator('.note-card').count(), 1);
+    await page.locator('#notes-search').fill('');
+    await page.locator('#notes-select-btn').click();
+    await page.locator('.note-card-cb').first().check({ force: mobile });
+    await page.locator('#notes-send-agent').click();
+    assert.equal(await page.locator('.note-card-selectmode').count(), 3, 'rejected selection stays selected');
+    await page.evaluate(() => window.addEventListener('odysseus:notes-context-selected', e => { window.referenceSelected = e.detail.noteIds; e.detail.accepted = true; }, { once: true }));
+    await page.locator('#notes-send-agent').click();
+    assert.equal(await page.locator('.note-card-selectmode').count(), 0);
+    assert.equal((await page.evaluate(() => window.referenceSelected)).length, 1);
+    await page.locator('#notes-search').fill('checklist');
+    await page.evaluate(() => window.referenceNotes.closePanel());
+    await page.locator('#notes-pane').waitFor({ state: 'detached' });
+    await page.evaluate(() => window.referenceNotes.openPanel());
+    await page.locator('.note-card').first().waitFor();
+    assert.equal(await page.locator('#notes-search').inputValue(), '');
+    assert.equal(await page.locator('.note-card').count(), 3);
+    if (!baseline && device !== 'desktop') {
+      const beginTouch = () => page.evaluate(() => {
+        const card = document.querySelector('.note-card');
+        const rect = card.getBoundingClientRect();
+        const touch = new Touch({ identifier: 1, target: card, clientX: rect.left + 5, clientY: rect.top + 5 });
+        card.dispatchEvent(new TouchEvent('touchstart', { touches: [touch], bubbles: true }));
+      });
+      if (device === 'tablet') {
+        await beginTouch();
+        await page.waitForFunction(() => document.querySelector('.note-card.dragging'));
+        await page.evaluate(() => document.querySelector('.note-card.dragging').dispatchEvent(new TouchEvent('touchcancel', { bubbles: true })));
+        await page.locator('#notes-search').fill('checklist');
+        await page.locator('#notes-search').fill('');
+        await beginTouch();
+        await page.waitForFunction(() => document.querySelector('.note-card.dragging'));
+      } else {
+        await beginTouch(); // Close before the selection hold timer can fire.
+      }
+      await page.evaluate(() => window.referenceNotes.closePanel());
+      await page.locator('#notes-pane').waitFor({ state: 'detached' });
+      await page.waitForTimeout(500);
+      assert.equal(await page.evaluate(() => document.documentElement.style.touchAction), '');
+      await page.evaluate(() => window.referenceNotes.openPanel());
+      await page.locator('.note-card').first().waitFor();
+      assert.equal(await page.locator('.note-card-selectmode').count(), 0);
+    }
+    if (mobile) await page.locator('[data-note-id="plain"] .note-card-title').tap();
+    else await page.locator('[data-note-id="plain"] .note-card-title').click();
+    if (mobile) await page.locator('.note-form-content-reader').tap({ position: { x: 5, y: 5 } });
+    await page.locator('.note-form-content').fill('Recovered draft');
+    assert.equal(await page.evaluate(() => JSON.parse(localStorage.getItem('odysseus-note-draft-plain')).content), 'Recovered draft');
+    await page.waitForFunction(() => !localStorage.getItem('odysseus-note-draft-plain'));
+    assert.ok(requests.some(r => r.method === 'PUT' && JSON.parse(r.body).content === 'Recovered draft'));
+    await page.locator('.note-form-type-pill[data-type="draw"]').click();
+    const canvas = page.locator('.note-form-canvas');
+    const box = await canvas.boundingBox();
+    assert.ok(box);
+    await page.mouse.move(box.x + 25, box.y + 25);
+    await page.mouse.down();
+    await page.mouse.move(box.x + 55, box.y + 55, { steps: 5 });
+    await page.mouse.up();
+    await page.locator('.note-form-draw-undo').waitFor();
+    assert.equal(await page.locator('.note-form-draw-undo').isDisabled(), false);
+    await page.locator('.note-form-draw-undo').click();
+    assert.equal(await page.locator('.note-form-draw-undo').isDisabled(), true);
+    await page.locator('.note-form-type-pill[data-type="note"]').click();
+    if (!baseline) await page.waitForFunction(() => window.referenceMouseups.size === 0);
+    await page.locator('.note-form-remind-btn').click();
+    await page.locator('.note-reminder-menu').waitFor();
+    await page.evaluate(() => window.referenceNotes.closePanel());
+    await page.locator('#notes-pane').waitFor({ state: 'detached' });
+    if (!baseline) {
+      assert.equal(await page.locator('.note-reminder-menu').count(), 0);
+      assert.equal(await page.evaluate(() => window.referenceIntervals.filter(t => t.ms === 30000).length), 1);
+      const identity = await page.evaluate(async () => {
+        const feature = await import('/static/js/features/notes/index.js');
+        const unversioned = await import('/static/js/notes.js');
+        return feature.default === window.referenceNotes.default && unversioned.default === feature.default && feature.openPanel === window.referenceNotes.openPanel;
+      });
+      assert.equal(identity, true);
+    }
+    assert.deepEqual(errors, []);
+    await context.close();
+    console.log(JSON.stringify({ device, mobile, ...publicAPI, requests: requests.length }));
+  }
+} finally { await browser.close(); }
diff --git a/tests/fixtures/notesRecurrenceBaseline.mjs b/tests/fixtures/notesRecurrenceBaseline.mjs
new file mode 100644
index 000000000..7f22ef5fe
--- /dev/null
+++ b/tests/fixtures/notesRecurrenceBaseline.mjs
@@ -0,0 +1,269 @@
+// Immutable N0 oracle copied from F1 commit 1cc56cb9; used only for differential tests.
+const _ORDINALS = ['1st', '2nd', '3rd', '4th', '5th'];
+const _DAYS = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'];
+function _hasTimeComponent(dateStr) {
+  return typeof dateStr === 'string' && /T\d{2}:\d{2}/.test(dateStr);
+}
+
+function _formatDueDate(dateStr) {
+  if (!dateStr) return '';
+  const d = new Date(dateStr);
+  if (isNaN(d)) return '';
+  const now = new Date();
+  const hasTime = _hasTimeComponent(dateStr);
+  const today = new Date(now.getFullYear(), now.getMonth(), now.getDate());
+  const due = new Date(d.getFullYear(), d.getMonth(), d.getDate());
+  const diffDays = Math.round((due - today) / 86400000);
+  const timeStr = hasTime ? d.toLocaleTimeString([], { hour: 'numeric', minute: '2-digit' }) : '';
+  if (hasTime && d < now) return 'overdue';
+  if (!hasTime && diffDays < 0) return 'overdue';
+  if (diffDays === 0) return hasTime ? timeStr : 'today';
+  if (diffDays === 1) return hasTime ? `tmrw ${timeStr}` : 'tomorrow';
+  const dateLabel = d.toLocaleDateString([], { month: 'short', day: 'numeric' });
+  return hasTime ? `${dateLabel} ${timeStr}` : dateLabel;
+}
+
+function _isDueOverdue(dateStr) {
+  if (!dateStr) return false;
+  const d = new Date(dateStr);
+  if (isNaN(d)) return false;
+  if (_hasTimeComponent(dateStr)) return d < new Date();
+  return d < new Date(new Date().toDateString());
+}
+
+function _isDueTodayOrOverdue(dateStr) {
+  if (!dateStr) return false;
+  const d = new Date(dateStr);
+  const now = new Date();
+  const today = new Date(now.getFullYear(), now.getMonth(), now.getDate());
+  const due = new Date(d.getFullYear(), d.getMonth(), d.getDate());
+  return due <= today;
+}
+
+function _laterTodayDate() {
+  const now = new Date();
+  const eight = new Date(now.getFullYear(), now.getMonth(), now.getDate(), 18, 0); // 6pm today
+  // If less than 1 hour before 6pm, push to "in 3 hours" instead
+  if (eight - now < 60 * 60 * 1000) return new Date(now.getTime() + 3 * 60 * 60 * 1000);
+  return eight;
+}
+
+function _tomorrowDate() {
+  const t = new Date();
+  t.setDate(t.getDate() + 1);
+  t.setHours(8, 0, 0, 0);
+  return t;
+}
+
+function _nextWeekDate() {
+  const t = new Date();
+  const daysUntilMon = (8 - t.getDay()) % 7 || 7;
+  t.setDate(t.getDate() + daysUntilMon);
+  t.setHours(8, 0, 0, 0);
+  return t;
+}
+
+function _toLocalDatetimeStr(d) {
+  // Format as YYYY-MM-DDTHH:MM (local, no TZ)
+  const pad = n => String(n).padStart(2, '0');
+  return `${d.getFullYear()}-${pad(d.getMonth()+1)}-${pad(d.getDate())}T${pad(d.getHours())}:${pad(d.getMinutes())}`;
+}
+
+function _formatReminderTag(dateStr) {
+  if (!dateStr) return '';
+  const d = new Date(dateStr);
+  if (isNaN(d)) return '';
+  const now = new Date();
+  const sameDay = d.toDateString() === now.toDateString();
+  const tomorrow = new Date(now); tomorrow.setDate(tomorrow.getDate() + 1);
+  const isTomorrow = d.toDateString() === tomorrow.toDateString();
+  const time = d.toLocaleTimeString([], { hour: 'numeric', minute: '2-digit' });
+  if (sameDay) return `Today, ${time}`;
+  if (isTomorrow) return `Tomorrow, ${time}`;
+  const dateLabel = d.toLocaleDateString([], { month: 'short', day: 'numeric' });
+  return `${dateLabel}, ${time}`;
+}
+
+function _nthWeekdayLabel(d) {
+  const n = Math.ceil(d.getDate() / 7); // 1..5
+  return `${_ORDINALS[n - 1] || `${n}th`} ${_DAYS[d.getDay()]}`;
+}
+
+function _isLastWeekdayOfMonth(d) {
+  const test = new Date(d);
+  test.setDate(d.getDate() + 7);
+  return test.getMonth() !== d.getMonth();
+}
+
+function _nthWeekdayOfMonth(year, month, weekday, n) {
+  const first = new Date(year, month, 1);
+  const offset = (weekday - first.getDay() + 7) % 7;
+  let day = 1 + offset + (n - 1) * 7;
+  // Last day of month
+  const lastDay = new Date(year, month + 1, 0).getDate();
+  if (day > lastDay) day -= 7;
+  return new Date(year, month, day, 0, 0, 0);
+}
+
+function _lastWeekdayOfMonth(year, month, weekday) {
+  const lastDay = new Date(year, month + 1, 0);
+  const back = (lastDay.getDay() - weekday + 7) % 7;
+  return new Date(year, month, lastDay.getDate() - back, 0, 0, 0);
+}
+
+function _snapToRepeat(currentDate, normRepeat) {
+  const hh = currentDate.getHours();
+  const mm = currentDate.getMinutes();
+  const now = Date.now();
+  const anchor = currentDate.getTime() > now ? currentDate : new Date();
+  const parts = normRepeat.split(':');
+  const kind = parts[0];
+  if (kind === 'weekly') {
+    const targetWd = parseInt(parts[1], 10);
+    if (isNaN(targetWd)) return null;
+    const d = new Date(anchor.getFullYear(), anchor.getMonth(), anchor.getDate(), hh, mm, 0, 0);
+    const delta = (targetWd - d.getDay() + 7) % 7;
+    d.setDate(d.getDate() + delta);
+    if (d.getTime() <= now) d.setDate(d.getDate() + 7);
+    return d;
+  }
+  if (kind === 'monthly') {
+    const sub = parts[1];
+    let y = anchor.getFullYear();
+    let m = anchor.getMonth();
+    // Walk forward up to 14 months to find the next matching slot.
+    for (let tries = 0; tries < 14; tries++) {
+      let target;
+      if (sub === 'day') {
+        const wantDay = parseInt(parts[2], 10);
+        if (isNaN(wantDay)) return null;
+        const lastDay = new Date(y, m + 1, 0).getDate();
+        target = new Date(y, m, Math.min(wantDay, lastDay));
+      } else if (sub === 'nth') {
+        const n = parseInt(parts[2], 10);
+        const wd = parseInt(parts[3], 10);
+        if (isNaN(n) || isNaN(wd)) return null;
+        target = _nthWeekdayOfMonth(y, m, wd, n);
+      } else if (sub === 'last') {
+        const wd = parseInt(parts[2], 10);
+        if (isNaN(wd)) return null;
+        target = _lastWeekdayOfMonth(y, m, wd);
+      } else {
+        return null;
+      }
+      target.setHours(hh, mm, 0, 0);
+      if (target.getTime() > now && target.getTime() >= anchor.getTime()) return target;
+      m++;
+      if (m > 11) { m = 0; y++; }
+    }
+    return null;
+  }
+  return null;
+}
+
+function _formatRepeatLabel(repeat, originalDate) {
+  if (!repeat || repeat === 'none') return '';
+  const norm = _normalizeRepeat(repeat, originalDate);
+  if (norm === 'daily') return 'Daily';
+  if (norm === 'yearly') return 'Yearly';
+  const parts = norm.split(':');
+  if (parts[0] === 'weekly') {
+    const wd = parseInt(parts[1], 10);
+    if (isNaN(wd)) return 'Weekly';
+    return `Weekly on ${_DAYS[wd]}s`;
+  }
+  if (parts[0] === 'monthly') {
+    if (parts[1] === 'day') return `Monthly on day ${parts[2]}`;
+    if (parts[1] === 'nth') {
+      const n = parseInt(parts[2], 10);
+      const wd = parseInt(parts[3], 10);
+      return `Monthly on ${_ORDINALS[n - 1] || `${n}th`} ${_DAYS[wd]}`;
+    }
+    if (parts[1] === 'last') {
+      const wd = parseInt(parts[2], 10);
+      return `Monthly on last ${_DAYS[wd]}`;
+    }
+  }
+  return norm;
+}
+
+function _normalizeRepeat(repeat, originalDate) {
+  if (!repeat || repeat === 'none') return 'none';
+  if (repeat === 'daily' || repeat === 'yearly') return repeat;
+  if (/^(weekly|monthly):/.test(repeat)) return repeat;
+  // Legacy bare values - derive params from the original date
+  const wd = originalDate.getDay();
+  const n = Math.ceil(originalDate.getDate() / 7);
+  if (repeat === 'weekly') return `weekly:${wd}`;
+  if (repeat === 'monthly') return `monthly:day:${originalDate.getDate()}`;
+  if (repeat === 'monthly_nth_weekday') return `monthly:nth:${n}:${wd}`;
+  if (repeat === 'monthly_last_weekday') return `monthly:last:${wd}`;
+  return repeat;
+}
+
+function _advanceRecurring(dateStr, repeat) {
+  const orig = new Date(dateStr);
+  const hh = orig.getHours();
+  const mm = orig.getMinutes();
+  let d = new Date(orig);
+  const norm = _normalizeRepeat(repeat, orig);
+  if (norm === 'none') return null;
+
+  function step() {
+    if (norm === 'daily') {
+      d.setDate(d.getDate() + 1);
+      return;
+    }
+    if (norm === 'yearly') {
+      d.setFullYear(d.getFullYear() + 1);
+      return;
+    }
+    const parts = norm.split(':');
+    const kind = parts[0];
+    if (kind === 'weekly') {
+      // Snap to the requested weekday in the next 1-7 days
+      const targetWd = parseInt(parts[1], 10);
+      let delta = (targetWd - d.getDay() + 7) % 7;
+      if (delta === 0) delta = 7;
+      d.setDate(d.getDate() + delta);
+      d.setHours(hh, mm, 0, 0);
+      return;
+    }
+    if (kind === 'monthly') {
+      const sub = parts[1];
+      const ny = d.getFullYear() + (d.getMonth() === 11 ? 1 : 0);
+      const nm = (d.getMonth() + 1) % 12;
+      let target;
+      if (sub === 'day') {
+        const wantDay = parseInt(parts[2], 10);
+        const lastDay = new Date(ny, nm + 1, 0).getDate();
+        target = new Date(ny, nm, Math.min(wantDay, lastDay));
+      } else if (sub === 'nth') {
+        const n = parseInt(parts[2], 10);
+        const wd = parseInt(parts[3], 10);
+        target = _nthWeekdayOfMonth(ny, nm, wd, n);
+      } else if (sub === 'last') {
+        const wd = parseInt(parts[2], 10);
+        target = _lastWeekdayOfMonth(ny, nm, wd);
+      } else {
+        d = null; return;
+      }
+      target.setHours(hh, mm, 0, 0);
+      d = target;
+      return;
+    }
+    d = null;
+  }
+
+  step();
+  if (d === null) return null;
+  const now = Date.now();
+  // Cap catch-up to avoid runaway on a malformed/very-old date.
+  let guard = 5000;
+  while (d.getTime() <= now) {
+    if (--guard <= 0) return null;
+    step();
+    if (d === null) return null;
+  }
+  return _toLocalDatetimeStr(d);
+}
diff --git a/tests/helpers/notes_source.py b/tests/helpers/notes_source.py
new file mode 100644
index 000000000..86103975f
--- /dev/null
+++ b/tests/helpers/notes_source.py
@@ -0,0 +1,10 @@
+"""Read deployed Notes responsibilities for source guards; runtime tests execute their real modules."""
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[2]
+
+
+def notes_source(*modules):
+    base = ROOT / "static/js/features/notes"
+    paths = [base / f"{module}.js" for module in modules] if modules else sorted(base.rglob("*.js"))
+    return "\n".join(path.read_text(encoding="utf-8") for path in paths)
diff --git a/tests/notesApplication.test.mjs b/tests/notesApplication.test.mjs
new file mode 100644
index 000000000..8b3ee2eea
--- /dev/null
+++ b/tests/notesApplication.test.mjs
@@ -0,0 +1,93 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { createNotesState } from '../frontend/src/features/notes/application/state.js';
+import { createNotesWorkflows } from '../frontend/src/features/notes/application/workflows.js';
+import { createLayout } from '../frontend/src/features/notes/ui/layout.js';
+
+test('views cannot mutate Notes state, but captured identities observe application updates', () => {
+  const app = createNotesState();
+  app.replaceNotes([{ id: 'a', items: [{ text: 'Task', done: false }] }]);
+  const note = app.state.notes[0];
+  assert.throws(() => { note.items[0].done = true; }, /state operations/);
+  assert.throws(() => app.state.notes.push({ id: 'other' }), /state operations/);
+  assert.throws(() => app.state.selectedIds.add('a'), /selection operations/);
+  assert.throws(() => Object.defineProperty(note, 'title', { value: 'unowned' }), /state operations/);
+  assert.throws(() => Object.preventExtensions(note), /state operations/);
+  assert.throws(() => Object.getOwnPropertyDescriptor(note, 'items').value.push({}), /state operations/);
+  app.updateItem(note, 0, { done: true });
+  assert.equal(note.items[0].done, true);
+  assert.equal(app.selectId('a'), undefined, 'selection operations do not leak the mutable set');
+  assert.deepEqual([...app.state.selectedIds], ['a']);
+  assert.throws(() => app.state.selectedIds.valueOf().clear(), /selection operations/);
+  app.state.selectedIds.forEach((_value, _key, set) => {
+    assert.equal(set, app.state.selectedIds);
+    assert.throws(() => set.clear(), /selection operations/);
+  });
+  app.mergeNote(note, { title: 'Changed' });
+  assert.equal(note.title, 'Changed');
+});
+
+test('fetch preserves archived query, failures clear notes, and successful fallback shapes', async () => {
+  const app = createNotesState(), requests = [];
+  let response = { ok: true, json: async () => [{ id: 'a' }] };
+  const workflows = createNotesWorkflows({ app, api: { listNotes: async archived => { requests.push(archived); return response; } }, effects: {} });
+  app.setShowingArchived(true);
+  await workflows._fetchNotes();
+  assert.deepEqual(requests, [true]);
+  assert.equal(app.state.loading, false);
+  assert.equal(app.state.notes[0].id, 'a');
+  response = { ok: false };
+  await workflows._fetchNotes();
+  assert.equal(app.state.notes.length, 0);
+  response = { ok: true, json: async () => ({ notes: [{ id: 'b' }] }) };
+  await workflows._fetchNotes();
+  assert.equal(app.state.notes[0].id, 'b');
+});
+
+test('fetch completions retain the original last-completion ordering', async () => {
+  const app = createNotesState(), releases = [];
+  const workflows = createNotesWorkflows({ app, api: { listNotes: () => new Promise(resolve => releases.push(resolve)) }, effects: {} });
+  const first = workflows._fetchNotes(), second = workflows._fetchNotes();
+  releases[1]({ ok: true, json: async () => ({ notes: [{ id: 'second' }] }) });
+  await second;
+  assert.equal(app.state.notes[0].id, 'second');
+  releases[0]({ ok: true, json: async () => ({ notes: [{ id: 'first' }] }) });
+  await first;
+  assert.equal(app.state.notes[0].id, 'first');
+});
+
+test('writes built from views store raw data, not read-only views', () => {
+  const app = createNotesState();
+  const raw = [{ id: 'a', items: [{ id: 'x', done: false }, { id: 'y', done: false }] }];
+  app.replaceNotes(raw);
+  const note = app.state.notes[0];
+  app.mergeNote(note, { items: note.items.filter(item => item.id !== 'x') });
+  app.prependNote({ ...note, id: 'b' });
+  app.spliceItems(app.state.notes[1], 1, 0, note.items[0]);
+  assert.doesNotThrow(() => structuredClone(raw));
+  raw[1].items[0].done = true;
+  assert.equal(app.state.notes[1].items[0].done, true);
+  assert.throws(() => { app.state.notes[1].items[0].done = false; }, /state operations/);
+});
+
+test('masonry observer is not re-created once Notes is closed', () => {
+  const created = [];
+  const previous = { window: globalThis.window, ResizeObserver: globalThis.ResizeObserver };
+  class FakeObserver { constructor() { created.push(this); this.live = true; } observe() {} disconnect() { this.live = false; } }
+  globalThis.ResizeObserver = FakeObserver;
+  globalThis.window = { ResizeObserver: FakeObserver, matchMedia: () => ({ matches: false }) };
+  try {
+    let open = true;
+    const layout = createLayout({ isOpen: () => open });
+    const body = { isConnected: true, closest: () => ({ classList: { contains: name => name === 'notes-view-grid' } }), querySelector: () => null, querySelectorAll: () => [] };
+    layout._applyMasonry(body);
+    assert.equal(created.filter(o => o.live).length, 1);
+    layout.dispose();
+    open = false;
+    layout._applyMasonry(body);
+    assert.equal(created.filter(o => o.live).length, 0);
+  } finally {
+    globalThis.window = previous.window;
+    globalThis.ResizeObserver = previous.ResizeObserver;
+  }
+});
diff --git a/tests/notesCharacterization.test.mjs b/tests/notesCharacterization.test.mjs
new file mode 100644
index 000000000..96fb5269e
--- /dev/null
+++ b/tests/notesCharacterization.test.mjs
@@ -0,0 +1,105 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import vm from 'node:vm';
+import { parse } from 'acorn';
+import { createNotesApi } from '../frontend/src/features/notes/infrastructure/http.js';
+import { createNotesState } from '../frontend/src/features/notes/application/state.js';
+import { createNotesWorkflows } from '../frontend/src/features/notes/application/workflows.js';
+
+const source = fs.readFileSync(new URL('../static/js/notes.js', import.meta.url), 'utf8');
+const ast = parse(source, { ecmaVersion: 'latest', sourceType: 'module' });
+const implementation = fs.readFileSync(new URL('../frontend/src/features/notes/index.js', import.meta.url), 'utf8');
+const implementationAST = parse(implementation, { ecmaVersion: 'latest', sourceType: 'module' });
+function functions(names, ports = {}) {
+  const datesSource = fs.readFileSync(new URL('../frontend/src/features/notes/domain/recurrence.js', import.meta.url), 'utf8').replaceAll('export ', '');
+  const context = vm.createContext(ports);
+  const datesContext = vm.createContext({ ...ports, clock: { now: () => (ports.Date || Date).now() } });
+  vm.runInContext(datesSource, datesContext);
+  context.dates = datesContext;
+  context.clock = { now: () => (ports.Date || Date).now() };
+  context.api = createNotesApi({ origin: ports.API_BASE, request: ports.fetch });
+  context._saveNote = context.api.saveNote;
+  context._patchNote = context.api.patchNote;
+  context._deleteNoteApi = context.api.deleteNote;
+  context.workflows = createNotesWorkflows({ app: createNotesState(), api: context.api, effects: {} });
+  for (const statement of implementationAST.body) {
+    const node = statement.declaration || statement;
+    if (node.type === 'FunctionDeclaration' && names.includes(node.id.name)) {
+      vm.runInContext(implementation.slice(node.start, node.end), context);
+    }
+  }
+  return context;
+}
+
+test('legacy public namespace and default API are intentional', () => {
+  const names = [];
+  for (const node of ast.body) {
+    if (node.type !== 'ExportNamedDeclaration') continue;
+    if (node.declaration) names.push(node.declaration.id.name);
+    for (const spec of node.specifiers) if (spec.exported.name !== 'default') names.push(spec.exported.name);
+  }
+  assert.deepEqual(names.sort(), ['closeNotes', 'closePanel', 'dismissFiredReminderDot', 'isNotesOpen', 'isPanelOpen', 'newNote', 'openNote', 'openNotes', 'openPanel', 'refreshDueBadge', 'togglePanel']);
+  assert.match(source, /window.notesModule = notesModule/);
+});
+
+test('CRUD preserves same-origin credentials, payloads and error contracts', async () => {
+  const requests = [];
+  let ok = true;
+  const api = functions(['_saveNote', '_patchNote', '_deleteNoteApi'], {
+    API_BASE: 'https://notes.invalid',
+    fetch: async (url, options) => {
+      requests.push({ url, ...options });
+      return { ok, status: 403, json: async () => ({ id: 'saved' }) };
+    },
+  });
+  await api._saveNote({ title: 'New' });
+  await api._saveNote({ id: 'a', title: '' });
+  await api._patchNote('a', { due_date: null });
+  await api._deleteNoteApi('a');
+  assert.deepEqual(requests.map(r => [r.url, r.method, r.credentials]), [
+    ['https://notes.invalid/api/notes', 'POST', 'same-origin'],
+    ['https://notes.invalid/api/notes/a', 'PUT', 'same-origin'],
+    ['https://notes.invalid/api/notes/a', 'PUT', 'same-origin'],
+    ['https://notes.invalid/api/notes/a', 'DELETE', 'same-origin'],
+  ]);
+  assert.equal(requests[2].body, '{"due_date":null}');
+  ok = false;
+  await assert.rejects(api._saveNote({}), /Failed to save note/);
+  await assert.rejects(api._patchNote('a', {}), /Failed to update note/);
+  await assert.rejects(api._deleteNoteApi('a'), /HTTP 403/);
+});
+
+test('recurrence clock is read after first advancement and never for none', () => {
+  const calls = [];
+  class ClockDate extends Date {
+    static now() { calls.push('clock'); return Date.parse('2024-02-01T12:00'); }
+    setDate(value) { calls.push('step'); return super.setDate(value); }
+  }
+  const domain = functions(['_normalizeRepeat', '_advanceRecurring', '_toLocalDatetimeStr', '_nthWeekdayOfMonth', '_lastWeekdayOfMonth'], { Date: ClockDate });
+  assert.equal(domain.dates._advanceRecurring('2024-02-01T09:00', 'daily', domain.clock), '2024-02-02T09:00');
+  assert.deepEqual(calls, ['step', 'clock']);
+  calls.length = 0;
+  assert.equal(domain.dates._advanceRecurring('2024-02-01T09:00', 'none', domain.clock), null);
+  assert.deepEqual(calls, []);
+});
+
+test('archive failure restores position; undo failure rolls back reinsertion', async () => {
+  const notes = [{ id: 'a' }, { id: 'b' }, { id: 'c' }], errors = [];
+  const stateOwner = createNotesState();
+  stateOwner.replaceNotes(notes);
+  const app = createNotesWorkflows({
+    app: stateOwner,
+    api: { patchNote: async () => { throw new Error('refused'); } },
+    effects: { render: () => {}, showError: e => errors.push(e) },
+  });
+  assert.equal(app._archiveNoteById('b'), true);
+  assert.deepEqual(notes.map(n => n.id), ['a', 'c']);
+  await new Promise(setImmediate);
+  assert.deepEqual(notes.map(n => n.id), ['a', 'b', 'c']);
+  notes.splice(1, 1);
+  app._popAndRunUndo();
+  await new Promise(setImmediate);
+  assert.deepEqual(notes.map(n => n.id), ['a', 'c']);
+  assert.deepEqual(errors, ['Failed to archive', 'Undo failed']);
+});
diff --git a/tests/notesDraftAutosave.test.mjs b/tests/notesDraftAutosave.test.mjs
index c12e73a25..00c41e7a3 100644
--- a/tests/notesDraftAutosave.test.mjs
+++ b/tests/notesDraftAutosave.test.mjs
@@ -1,21 +1,28 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
-import fs from 'node:fs';
-import vm from 'node:vm';
+import { createNotesPersistence } from '../frontend/src/features/notes/infrastructure/storage.js';
+import { createNotesState } from '../frontend/src/features/notes/application/state.js';
+import { createNotesDrafts } from '../frontend/src/features/notes/application/drafts.js';
+import { createDraftEditor } from '../frontend/src/features/notes/ui/draftEditor.js';
 
-const source = fs.readFileSync(new URL('../static/js/notes.js', import.meta.url), 'utf8');
 function harness(patch = async () => ({})) {
   const data = new Map(), timers = new Map(), errors = [];
   let nextTimer = 0;
-  const context = vm.createContext({
+  const context = {
     localStorage: { getItem: k => data.get(k) ?? null, setItem: (k,v) => data.set(k,v), removeItem: k => data.delete(k) },
     setTimeout: f => { timers.set(++nextTimer, f); return nextTimer; },
     clearTimeout: id => timers.delete(id),
     _patchNote: patch, _notes: [{id:'note1'}],
     _collectItems: form => form.items,
     uiModule: {showError: message => errors.push(message)},
-  });
-  vm.runInContext(source.slice(source.indexOf("const _DRAFT_PREFIX"), source.indexOf('// ---- Create / Edit Form ----')), context);
+  };
+  context.persistence = createNotesPersistence({ storage: context.localStorage });
+  context.app = createNotesState();
+  context.app.replaceNotes(context._notes);
+  context.state = context.app.state;
+  Object.assign(context, context.persistence);
+  const drafts = createNotesDrafts({ app: context.app, api: { patchNote: patch }, persistence: context.persistence, scheduler: context, effects: context.uiModule });
+  Object.assign(context, createDraftEditor({ ...context, ...context.persistence, bindDraft: drafts.bindDraft }));
   const fields = {'.note-form-title':{value:'Title'}, '.note-form-content':{value:'Original'}};
   const handlers = {};
   const form = { dataset:{noteType:'note'}, items:[], querySelector: s => fields[s], addEventListener:(n,f) => handlers[n]=f };
diff --git a/tests/notesInfrastructure.test.mjs b/tests/notesInfrastructure.test.mjs
new file mode 100644
index 000000000..601ed8275
--- /dev/null
+++ b/tests/notesInfrastructure.test.mjs
@@ -0,0 +1,47 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { createNotesApi } from '../frontend/src/features/notes/infrastructure/http.js';
+import { createNotesPersistence, REMINDER_FIRED_KEY } from '../frontend/src/features/notes/infrastructure/storage.js';
+
+test('list, reorder, upload, reminder and agent transports retain exact requests', async () => {
+  const calls = [], result = { ok: false, status: 403 };
+  const api = createNotesApi({ origin: 'https://notes.invalid', request: async (...args) => { calls.push(args); return result; } });
+  const body = { opaque: true };
+  assert.equal(await api.listNotes(true), result);
+  await api.listNotes(false); await api.reorder(['b', 'a']); await api.upload(body);
+  await api.fireReminder({ note_id: 'a' }); await api.defaultChat();
+  await api.createSession(body); await api.startChat(body);
+  assert.deepEqual(calls.map(([url, o]) => [url, o.method || 'GET', o.credentials]), [
+    ['https://notes.invalid/api/notes?archived=true', 'GET', 'same-origin'],
+    ['https://notes.invalid/api/notes', 'GET', 'same-origin'],
+    ['https://notes.invalid/api/notes/reorder', 'POST', 'same-origin'],
+    ['https://notes.invalid/api/upload', 'POST', 'same-origin'],
+    ['/api/notes/fire-reminder', 'POST', 'same-origin'],
+    ['https://notes.invalid/api/default-chat', 'GET', 'same-origin'],
+    ['https://notes.invalid/api/session', 'POST', 'same-origin'],
+    ['https://notes.invalid/api/chat_stream', 'POST', 'same-origin'],
+  ]);
+  assert.equal(calls[2][1].body, '{"ids":["b","a"]}');
+  assert.equal(calls[3][1].body, body);
+  assert.equal(api.uploadUrl('file'), 'https://notes.invalid/api/upload/file');
+});
+
+test('draft and marker persistence retain keys, formats and malformed fallback', () => {
+  const values = new Map();
+  const storage = { getItem: key => values.get(key) ?? null, setItem: (key, value) => values.set(key, value), removeItem: key => values.delete(key) };
+  const persistence = createNotesPersistence({ storage });
+  assert.equal(persistence._draftKey(null), 'odysseus-note-draft-__new__');
+  persistence._saveFiredReminders(new Set(['a', 'b']));
+  assert.equal(values.get(REMINDER_FIRED_KEY), '["a","b"]');
+  assert.deepEqual([...persistence._loadFiredReminders()], ['a', 'b']);
+  values.set(REMINDER_FIRED_KEY, '{broken');
+  assert.equal(persistence._loadFiredReminders().size, 0);
+  storage.setItem(persistence._draftKey('a'), '{"content":"","_ts":1}');
+  assert.deepEqual(persistence._loadDraft('a'), { content: '', _ts: 1 });
+  persistence._clearDraft('a');
+  assert.equal(persistence._loadDraft('a'), null);
+  const failing = createNotesPersistence({ storage: { getItem() { throw Error('blocked'); }, setItem() { throw Error('full'); } } });
+  assert.equal(failing._loadDraft('a'), null);
+  assert.doesNotThrow(() => failing._saveFiredReminders(new Set(['a'])));
+  assert.throws(() => failing.setItem('odysseus-note-draft-a', '{}'), /full/, 'draft caller must observe backup failure');
+});
diff --git a/tests/notesRecurrence.test.mjs b/tests/notesRecurrence.test.mjs
new file mode 100644
index 000000000..326a8fbca
--- /dev/null
+++ b/tests/notesRecurrence.test.mjs
@@ -0,0 +1,41 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import vm from 'node:vm';
+import * as rules from '../frontend/src/features/notes/domain/recurrence.js';
+
+const baseline = fs.readFileSync(new URL('./fixtures/notesRecurrenceBaseline.mjs', import.meta.url), 'utf8');
+const timed = new Set(['_formatDueDate', '_isDueOverdue', '_isDueTodayOrOverdue', '_laterTodayDate', '_tomorrowDate', '_nextWeekDate', '_formatReminderTag', '_snapToRepeat', '_advanceRecurring']);
+for (const zone of ['UTC', 'Europe/Lisbon', 'America/New_York', 'Australia/Sydney']) {
+  test(`recurrence differential oracle in ${zone}`, () => {
+    const oldZone = process.env.TZ;
+    process.env.TZ = zone;
+    try {
+      const now = Date.parse('2024-03-10T01:59:00');
+      class FixedDate extends Date { constructor(...args) { super(...(args.length ? args : [now])); } static now() { return now; } }
+      const original = vm.createContext({ Date: FixedDate });
+      vm.runInContext(baseline, original);
+      const compare = (name, args) => {
+        const before = original[name](...args);
+        const after = rules[name](...args, ...(timed.has(name) ? [{ now: () => now }] : []));
+        assert.equal(after instanceof Date ? after.getTime() : after, before instanceof Date ? before.getTime() : before, `${name}(${args})`);
+      };
+      const dates = ['2024-01-31T09:17', '2024-02-29T09:17', '2023-02-28T09:17', '2024-03-09T02:30', '2024-11-02T01:30', '2030-07-31T18:42', '1900-01-01T09:00', 'invalid', '2024-03-10'];
+      const repeats = [null, '', 'none', 'daily', 'weekly', 'monthly', 'yearly', 'monthly_nth_weekday', 'monthly_last_weekday', 'weekly:1', 'weekly:bad', 'monthly:day:31', 'monthly:nth:5:1', 'monthly:last:0', 'monthly:bad', 'unknown'];
+      for (const date of dates) {
+        for (const repeat of repeats) {
+          compare('_advanceRecurring', [date, repeat]);
+          compare('_normalizeRepeat', [repeat, new Date(date)]);
+          compare('_formatRepeatLabel', [repeat, new Date(date)]);
+        }
+        for (const name of ['_hasTimeComponent', '_formatDueDate', '_isDueOverdue', '_isDueTodayOrOverdue', '_formatReminderTag']) compare(name, [date]);
+        for (const repeat of ['weekly:1', 'monthly:day:31', 'monthly:nth:5:1', 'monthly:last:0', 'daily', 'monthly:bad']) compare('_snapToRepeat', [new Date(date), repeat]);
+      }
+      for (const name of ['_laterTodayDate', '_tomorrowDate', '_nextWeekDate']) compare(name, []);
+      for (const year of [2023, 2024]) for (let month = 0; month < 12; month++) for (let wd = 0; wd < 7; wd++) {
+        compare('_nthWeekdayOfMonth', [year, month, wd, 5]);
+        compare('_lastWeekdayOfMonth', [year, month, wd]);
+      }
+    } finally { if (oldZone === undefined) delete process.env.TZ; else process.env.TZ = oldZone; }
+  });
+}
diff --git a/tests/notesReminders.test.mjs b/tests/notesReminders.test.mjs
new file mode 100644
index 000000000..1d5a8c340
--- /dev/null
+++ b/tests/notesReminders.test.mjs
@@ -0,0 +1,90 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { createNotesState } from '../frontend/src/features/notes/application/state.js';
+import { createNotesReminders } from '../frontend/src/features/notes/application/reminders.js';
+import { createNotesNotifications } from '../frontend/src/features/notes/infrastructure/notifications.js';
+import { createNotesPersistence, REMINDER_DISMISSED_AT_KEY } from '../frontend/src/features/notes/infrastructure/storage.js';
+
+function harness(notes = []) {
+  const now = Date.parse('2024-03-10T09:00'), app = createNotesState();
+  app.replaceNotes(notes);
+  const values = new Map(), timeouts = new Map(), intervals = new Map(), fired = [], shown = [], highlighted = [], patches = [];
+  let nextId = 0, response = Promise.resolve({ ok: true, json: async () => ({ synthesis: 'Synthesis' }) });
+  const scheduler = {
+    setTimeout: (fn, ms) => { const id = ++nextId; timeouts.set(id, { fn, ms }); return id; }, clearTimeout: id => timeouts.delete(id),
+    setInterval: (fn, ms) => { const id = ++nextId; intervals.set(id, { fn, ms }); return id; }, clearInterval: id => intervals.delete(id),
+  };
+  const persistence = createNotesPersistence({ storage: { getItem: key => values.get(key), setItem: (key, value) => values.set(key, value) } });
+  const reminders = createNotesReminders({
+    app, clock: { now: () => now }, scheduler, persistence, dismissedKey: REMINDER_DISMISSED_AT_KEY,
+    notifications: { show: (...args) => shown.push(args) }, fetchNotes: async () => {},
+    hasItems: note => ['todo', 'goal', 'checklist'].includes(note.note_type), isNoteFullyDone: () => false,
+    api: { listNotes: async () => ({ ok: true, json: async () => ({ notes }) }), patchNote: async (...args) => patches.push(args), fireReminder: body => { fired.push(body); return response; } },
+    effects: { badge: () => {}, highlight: id => highlighted.push(id) },
+  });
+  return { now, app, reminders, timeouts, intervals, fired, shown, highlighted, patches, persistence, setResponse: value => { response = value; } };
+}
+
+test('startup and loop are idempotent, and panel closure leaves background scheduling alive', async () => {
+  const h = harness();
+  h.reminders.start(); h.reminders.start();
+  assert.deepEqual([...h.timeouts.values()].map(t => t.ms), [3000]);
+  await [...h.timeouts.values()][0].fn();
+  h.reminders._startReminderLoop();
+  assert.deepEqual([...h.intervals.values()].map(t => t.ms), [30000]);
+  h.app.setOpen(false);
+  assert.equal(h.intervals.size, 1);
+  h.reminders.dispose();
+  assert.equal(h.intervals.size, 0);
+  h.reminders._startReminderLoop();
+  assert.equal(h.intervals.size, 0);
+});
+
+test('fresh reminders dispatch once, stale reminders mark silently, recurring reminders advance', async () => {
+  const now = Date.parse('2024-03-10T09:00');
+  const local = value => { const d = new Date(value); return `${d.getFullYear()}-${String(d.getMonth()+1).padStart(2,'0')}-${String(d.getDate()).padStart(2,'0')}T${String(d.getHours()).padStart(2,'0')}:${String(d.getMinutes()).padStart(2,'0')}:30`; };
+  const h = harness([
+    { id: 'fresh', due_date: local(now - 30000), content: 'Body' },
+    { id: 'old', due_date: local(now - 180000) },
+    { id: 'recurring', due_date: local(now - 180000), repeat: 'daily' },
+    { id: 'date', due_date: '2024-03-10' },
+    { id: 'archived', archived: true, due_date: local(now - 30000) },
+  ]);
+  h.reminders._checkReminders(); h.reminders._checkReminders();
+  await new Promise(setImmediate);
+  assert.deepEqual(h.fired.map(n => n.note_id), ['fresh']);
+  assert.deepEqual([...h.persistence._loadFiredReminders()], ['fresh', 'old']);
+  assert.equal(h.patches.length, 1);
+  assert.equal(h.app.state.notes[2].due_date, '2024-03-11T08:57');
+  assert.deepEqual(h.highlighted, ['fresh']);
+  assert.equal(h.shown[0][1], 'Synthesis');
+});
+
+test('slow synthesis and rejected dispatch use the local fallback exactly once', async () => {
+  const h = harness();
+  let resolve;
+  h.setResponse(new Promise(r => { resolve = r; }));
+  h.reminders._fireReminder({ id: 'a', title: 'Title', content: 'Raw' });
+  const timer = [...h.timeouts.values()].find(t => t.ms === 1500);
+  timer.fn();
+  resolve({ ok: true, json: async () => ({ synthesis: 'Too late' }) });
+  await new Promise(setImmediate);
+  assert.deepEqual(h.shown, [['Title', 'Raw', 'a']]);
+  h.setResponse(Promise.reject(Error('offline')));
+  h.reminders._fireReminder({ id: 'b', note_type: 'todo', items: [{ text: 'Task', done: false }] });
+  await new Promise(setImmediate);
+  assert.equal(h.shown.length, 2);
+  assert.equal(h.fired[1].body, 'Pending (1):\n- Task');
+});
+
+test('notification denial, unsupported browsers and permission errors remain fail-safe', async () => {
+  const toast = [];
+  const absent = createNotesNotifications({ browser: {}, toast: title => toast.push(title) });
+  assert.equal(await absent.ensurePermission(), false);
+  absent.show('Title', 'Body', 'a');
+  assert.deepEqual(toast, ['Title']);
+  const denied = createNotesNotifications({ browser: { Notification: true }, notify: { permission: 'denied' } });
+  assert.equal(await denied.ensurePermission(), false);
+  const failed = createNotesNotifications({ browser: { Notification: true }, notify: { permission: 'default', requestPermission: async () => { throw Error('blocked'); } } });
+  assert.equal(await failed.ensurePermission(), false);
+});
diff --git a/tests/notesWorkflows.test.mjs b/tests/notesWorkflows.test.mjs
new file mode 100644
index 000000000..59c39d84f
--- /dev/null
+++ b/tests/notesWorkflows.test.mjs
@@ -0,0 +1,147 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { createNotesState } from '../frontend/src/features/notes/application/state.js';
+import { createCardOperations } from '../frontend/src/features/notes/application/cardOperations.js';
+import { createChecklistOperations } from '../frontend/src/features/notes/application/checklistOperations.js';
+import { createNotesSubmission } from '../frontend/src/features/notes/application/submission.js';
+import { createSelectionOperations } from '../frontend/src/features/notes/application/selection.js';
+import { createNotesPersistence } from '../frontend/src/features/notes/infrastructure/storage.js';
+import { createNotesLifecycle } from '../frontend/src/features/notes/ui/lifecycle.js';
+import { createText } from '../frontend/src/features/notes/ui/text.js';
+import { createDeletion } from '../frontend/src/features/notes/application/deletion.js';
+
+const drain = () => new Promise(setImmediate);
+function owner(notes) { const app = createNotesState(); app.replaceNotes(notes); return app; }
+
+test('reorder retains desktop persistence-only and mobile post-response state ordering', async () => {
+  const app = owner([{ id: 'a', sort_order: 9 }, { id: 'b', sort_order: 8 }]), requests = [];
+  let resolve;
+  const operations = createCardOperations({ app, api: { reorder: ids => { requests.push(ids); return new Promise(done => { resolve = done; }); } } });
+  const desktop = operations.persistOrder(['b', 'a']);
+  resolve({ ok: false }); await desktop;
+  assert.deepEqual(app.state.notes.map(note => note.sort_order), [9, 8]);
+  const mobile = operations.commitMobileOrder(['b', 'a']);
+  assert.deepEqual(app.state.notes.map(note => note.sort_order), [9, 8]);
+  resolve({ ok: false }); await mobile;
+  assert.deepEqual(app.state.notes.map(note => note.sort_order), [1, 0]);
+  assert.deepEqual(requests, [['b', 'a'], ['b', 'a']]);
+});
+
+test('editor deletion waits for confirmation and preserves optimistic failure/refetch timing', async () => {
+  const app = owner([{ id: 'a' }]), events = [];
+  app.setEditingId('a');
+  let confirm, fail;
+  const operations = createDeletion({ app, state: app.state,
+    _deleteNoteApi: id => { events.push('delete:' + id); return new Promise((_resolve, reject) => { fail = reject; }); },
+    _fetchNotes: async () => { events.push('fetch'); app.replaceNotes([{ id: 'a' }]); },
+    _renderNotes: () => events.push('render'),
+    effects: { styledConfirm: () => new Promise(resolve => { confirm = resolve; }), showToast: () => events.push('toast'), showError: error => events.push(error) },
+  });
+  const deletion = operations.deleteFromEditor('a');
+  assert.equal(app.state.notes.length, 1);
+  confirm(false); await deletion;
+  assert.deepEqual(events, []);
+  const accepted = operations.deleteFromEditor('a');
+  confirm(true); await accepted;
+  assert.equal(app.state.notes.length, 0);
+  assert.equal(app.state.editingId, null);
+  assert.deepEqual(events, ['render', 'delete:a']);
+  fail(Error('403')); await drain();
+  assert.equal(app.state.notes[0].id, 'a');
+  assert.deepEqual(events, ['render', 'delete:a', 'Failed to delete', 'fetch', 'render']);
+});
+
+test('pin and delete failures roll back captured state and order', async () => {
+  const app = owner([{ id: 'a', pinned: false, sort_order: 4 }, { id: 'b', pinned: true, sort_order: -3 }]), errors = [];
+  const operations = createCardOperations({ app, api: { patchNote: async () => { throw Error('403'); }, deleteNote: async () => { throw Error('403'); } }, effects: { render() {}, showError: error => errors.push(error) } });
+  operations.togglePin('a');
+  assert.equal(app.state.notes[0].pinned, true);
+  assert.equal(app.state.notes[0].sort_order, -4);
+  await drain();
+  assert.equal(app.state.notes[0].pinned, false);
+  assert.equal(app.state.notes[0].sort_order, 4);
+  operations.deleteOptimistically('a');
+  assert.deepEqual(app.state.notes.map(n => n.id), ['b']);
+  await drain();
+  assert.deepEqual(app.state.notes.map(n => n.id), ['a', 'b']);
+  assert.deepEqual(errors, ['Failed to pin', 'Failed to delete']);
+});
+
+test('item removal, quick add and checkbox errors preserve checklist contents', async () => {
+  const app = owner([{ id: 'a', items: [{ id: 'first', text: 'A', done: false }, { id: 'second', text: 'B', done: true }] }]);
+  const operations = createChecklistOperations({ app, api: { patchNote: async () => { throw Error('offline'); } }, uid: () => 'new', effects: { render() {}, showError() {} } });
+  operations.removeItem('a', 0);
+  assert.equal(app.state.notes[0].items[0].id, 'second');
+  await drain();
+  assert.deepEqual(app.state.notes[0].items.map(it => it.id), ['first', 'second']);
+  const done = [];
+  operations.toggleItem('a', 0, value => done.push(value), () => {});
+  await drain();
+  assert.deepEqual(done, [true, false]);
+  const persist = operations.addItem('a', 'C', () => {});
+  assert.equal(app.state.notes[0].items.length, 3);
+  persist(); await drain();
+  assert.equal(app.state.notes[0].items.length, 2);
+  operations.editItem(app.state.notes[0], 1, 'Changed');
+  await drain();
+  assert.equal(app.state.notes[0].items[1].text, 'B');
+});
+
+test('submission preserves top ordering, server ID replacement and newer draft recovery', async () => {
+  const app = owner([{ id: 'existing', sort_order: -2 }]), values = new Map();
+  const persistence = createNotesPersistence({ storage: { getItem: key => values.get(key), setItem: (key, value) => values.set(key, value), removeItem: key => values.delete(key) } });
+  const draftKey = persistence._draftKey('__new__');
+  values.set(draftKey, '{"content":"submitted"}');
+  let resolve, renders = 0;
+  const operations = createNotesSubmission({ app, persistence, clock: { now: () => 0 }, uid: () => 'id', api: { saveNote: () => new Promise(r => { resolve = r; }) }, effects: { render: () => renders++, showError() {} }, fetchNotes: async () => {} });
+  operations.submitNote({ title: 'New' }, null, false);
+  assert.equal(app.state.notes[0].id, 'tmp_id');
+  assert.equal(app.state.notes[0].sort_order, -3);
+  values.set(draftKey, '{"content":"newer"}');
+  resolve({ id: 'server-id' }); await drain();
+  assert.equal(app.state.notes[0].id, 'server-id');
+  assert.equal(values.get(draftKey), '{"content":"newer"}');
+  assert.equal(renders, 2);
+});
+
+test('selection can exit only after synchronous acceptance', () => {
+  const app = owner([]), order = [];
+  app.selectId('a');
+  let accepted = false;
+  const operations = createSelectionOperations({ app, sendContext: detail => { order.push('dispatch'); detail.accepted = accepted; }, exitSelection: () => order.push('exit'), effects: { showToast: () => order.push('rejected') } });
+  operations.attachSelected();
+  assert.deepEqual(order, ['dispatch', 'rejected']);
+  accepted = true; operations.attachSelected();
+  assert.deepEqual(order, ['dispatch', 'rejected', 'dispatch', 'exit']);
+});
+
+test('listener owners release on replacement and disposal is idempotent', () => {
+  const previous = { document: globalThis.document, MutationObserver: globalThis.MutationObserver };
+  let check, disconnected = 0;
+  globalThis.document = { body: {} };
+  globalThis.MutationObserver = class { constructor(callback) { check = callback; } observe() {} disconnect() { disconnected++; } };
+  try {
+    const lifecycle = createNotesLifecycle(), target = new EventTarget(), canvas = { isConnected: true };
+    let calls = 0;
+    lifecycle.listen(canvas, target, 'mouseup', () => calls++);
+    let released = 0;
+    lifecycle.onDispose(canvas, () => released++);
+    target.dispatchEvent(new Event('mouseup'));
+    canvas.isConnected = false; check();
+    target.dispatchEvent(new Event('mouseup'));
+    lifecycle.dispose(); lifecycle.dispose();
+    assert.equal(calls, 1); assert.equal(disconnected, 1);
+    assert.equal(released, 1);
+  } finally {
+    for (const [name, value] of Object.entries(previous)) if (value === undefined) delete globalThis[name]; else globalThis[name] = value;
+  }
+});
+
+test('render helpers reject script-capable media and escape URL attributes', () => {
+  const helpers = createText({ uiModule: { esc: value => value.replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;') } });
+  for (const value of ['javascript:alert(1)', 'data:image/svg+xml;base64,abc', 'data:text/html;base64,abc']) assert.equal(helpers._safeImgSrc(value), '');
+  assert.equal(helpers._safeImgSrc('data:image/png;base64,abc'), 'data:image/png;base64,abc');
+  assert.equal(helpers._attrEsc('"\'<>`'), '&quot;&#39;&lt;&gt;&#96;');
+  assert.match(helpers._linkify('<script> https://example.org/test'), /&lt;script&gt;/);
+  assert.doesNotMatch(helpers._linkify('<script> https://example.org/test'), /<script>/i);
+});
diff --git a/tests/selectedNotesContext.test.mjs b/tests/selectedNotesContext.test.mjs
index 118f2dd95..6ca7cb6fe 100644
--- a/tests/selectedNotesContext.test.mjs
+++ b/tests/selectedNotesContext.test.mjs
@@ -5,7 +5,7 @@ import vm from 'node:vm';
 
 const chatSource = readFileSync(new URL('../static/js/chat.js', import.meta.url), 'utf8');
 const sessionSource = readFileSync(new URL('../static/js/sessions.js', import.meta.url), 'utf8');
-const notesSource = readFileSync(new URL('../static/js/notes.js', import.meta.url), 'utf8');
+const notesSource = readFileSync(new URL('../static/js/features/notes/application/selection.js', import.meta.url), 'utf8');
 
 function setup() {
   const start = chatSource.indexOf("  window.addEventListener('odysseus:notes-context-selected'");
diff --git a/tests/test_notes_document_mutual_minimize.py b/tests/test_notes_document_mutual_minimize.py
index 88315e5c8..828355adc 100644
--- a/tests/test_notes_document_mutual_minimize.py
+++ b/tests/test_notes_document_mutual_minimize.py
@@ -1,3 +1,4 @@
+from tests.helpers.notes_source import notes_source
 from pathlib import Path
 from tests.helpers.document_source import document_source
 
@@ -6,7 +7,7 @@ ROOT = Path(__file__).resolve().parents[1]
 
 
 def test_opening_notes_minimizes_open_document():
-    script = (ROOT / "static/js/notes.js").read_text()
+    script = notes_source("ui/panel")
 
     assert "window.documentModule?.isPanelOpen?.()" in script
     assert "window.documentModule.closePanel('down')" in script
diff --git a/tests/test_notes_dom_xss_helpers.py b/tests/test_notes_dom_xss_helpers.py
index 92e5d3d81..64f0352ab 100644
--- a/tests/test_notes_dom_xss_helpers.py
+++ b/tests/test_notes_dom_xss_helpers.py
@@ -2,12 +2,14 @@
 
 from pathlib import Path
 
+from tests.helpers.notes_source import notes_source
+
 
 _REPO = Path(__file__).resolve().parent.parent
 
 
 def test_notes_image_src_guard_rejects_script_capable_data_images():
-    src = (_REPO / "static" / "js" / "notes.js").read_text(encoding="utf-8")
+    src = notes_source("ui/text", "ui/editor", "ui/drawing")
 
     assert "function _safeImgSrc(s)" in src
     assert r"^data:image\/(?:png|jpe?g|gif|webp);base64," in src
@@ -15,7 +17,7 @@ def test_notes_image_src_guard_rejects_script_capable_data_images():
 
 
 def test_notes_linkify_escapes_href_attribute():
-    src = (_REPO / "static" / "js" / "notes.js").read_text(encoding="utf-8")
+    src = notes_source("ui/text", "ui/editor", "ui/drawing")
 
     assert "function _attrEsc(s)" in src
     assert 'href="${_attrEsc(href)}"' in src
@@ -23,7 +25,7 @@ def test_notes_linkify_escapes_href_attribute():
 
 
 def test_notes_edit_form_uses_safe_image_src_guard():
-    src = (_REPO / "static" / "js" / "notes.js").read_text(encoding="utf-8")
+    src = notes_source("ui/text", "ui/editor", "ui/drawing")
 
     assert "let currentImageUrl = _safeImgSrc(note?.image_url || '');" in src
     assert "let _stashedDrawUrl = (type === 'draw') ? (_safeImgSrc(note?.image_url) || null) : null;" in src
diff --git a/tests/test_notes_mobile_checklist_toggle_static.py b/tests/test_notes_mobile_checklist_toggle_static.py
index 12ad4a034..d862e57ed 100644
--- a/tests/test_notes_mobile_checklist_toggle_static.py
+++ b/tests/test_notes_mobile_checklist_toggle_static.py
@@ -1,3 +1,4 @@
+from tests.helpers.notes_source import notes_source
 from pathlib import Path
 import re
 
@@ -10,23 +11,23 @@ ROOT = Path(__file__).resolve().parent.parent
 
 def test_mobile_notes_checklist_rows_remain_tappable():
     css = app_css()
-    notes = (ROOT / "static" / "js" / "notes.js").read_text(encoding="utf-8")
+    notes = notes_source("ui/cardChecklist", "ui/checklist", "ui/editor", "ui/mobileEditor", "ui/mobileReorder", "ui/selection", "ui/drawing")
 
     assert "body.notes-mobile-mode .note-card .note-checkbox {" in css
     assert "pointer-events: auto;" in css
     assert "touch-action: manipulation;" in css
     assert "body.notes-mobile-mode .note-card .note-checkbox,\nbody.notes-mobile-mode .note-card .note-checkbox-rm" not in css
-    assert "if (_selectMode) return; // let card-level handler take over\n      e.preventDefault();" in notes
+    assert re.search(r"if \(state.selectMode\) return; // let card-level handler take over\n\s+e.preventDefault\(\);", notes)
 
 
 def test_mobile_edit_checklist_toggle_marks_form_dirty():
-    notes = (ROOT / "static" / "js" / "notes.js").read_text(encoding="utf-8")
+    notes = notes_source("ui/cardChecklist", "ui/checklist", "ui/editor", "ui/mobileEditor", "ui/mobileReorder", "ui/selection", "ui/drawing")
 
     assert "container.dispatchEvent(new Event('input', { bubbles: true }));" in notes
 
 
 def test_completed_mobile_todo_uses_finish_action():
-    notes = (ROOT / "static" / "js" / "notes.js").read_text(encoding="utf-8")
+    notes = notes_source("ui/cardChecklist", "ui/checklist", "ui/editor", "ui/mobileEditor", "ui/mobileReorder", "ui/selection", "ui/drawing")
 
     assert "const _isFinishedTodo = () =>" in notes
     assert "const label = _isFinishedTodo() ? 'Finish' : 'Archive';" in notes
@@ -34,10 +35,10 @@ def test_completed_mobile_todo_uses_finish_action():
 
 
 def test_mobile_long_press_enters_select_mode_for_that_note():
-    notes = (ROOT / "static" / "js" / "notes.js").read_text(encoding="utf-8")
+    notes = notes_source("ui/cardChecklist", "ui/checklist", "ui/editor", "ui/mobileEditor", "ui/mobileReorder", "ui/selection", "ui/drawing")
 
     assert "function _enterSelectMode(initialId = null)" in notes
-    assert "_suppressNextNoteTapId = card.dataset.noteId;" in notes
+    assert "app.setSuppressNextNoteTapId(card.dataset.noteId);" in notes
     assert "_enterSelectMode(card.dataset.noteId);" in notes
 
 
@@ -60,7 +61,7 @@ def test_notes_mobile_checklist_asset_versions_are_bumped():
 
 
 def test_drawing_edits_mark_notes_dirty_and_keep_one_gallery_image():
-    notes = (ROOT / "static" / "js" / "notes.js").read_text(encoding="utf-8")
+    notes = notes_source("ui/cardChecklist", "ui/checklist", "ui/editor", "ui/mobileEditor", "ui/mobileReorder", "ui/selection", "ui/drawing")
     upload = (ROOT / "routes" / "upload_routes.py").read_text(encoding="utf-8")
     note_routes = (ROOT / "routes" / "note" / "note_routes.py").read_text(encoding="utf-8")
 
diff --git a/tests/test_notes_reference_browser.py b/tests/test_notes_reference_browser.py
new file mode 100644
index 000000000..cfb2dbfd1
--- /dev/null
+++ b/tests/test_notes_reference_browser.py
@@ -0,0 +1,23 @@
+"""Execute the real Notes ESM graph and DOM with deterministic API responses."""
+import os
+import subprocess
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+def test_notes_reference_desktop_mobile_and_public_identity(tmp_path):
+    env = dict(os.environ, NOTES_EVIDENCE_DIR=os.environ.get("NOTES_EVIDENCE_DIR", str(tmp_path)))
+    result = subprocess.run(
+        ["node", "tests/browser/notesReference.mjs"], cwd=ROOT, env=env,
+        capture_output=True, text=True, timeout=120,
+    )
+    assert result.returncode == 0, result.stdout + result.stderr
+
+
+def test_notes_complete_graph_imports_first_time_offline():
+    result = subprocess.run(
+        ["node", "tests/browser/notesOffline.mjs"], cwd=ROOT,
+        capture_output=True, text=True, timeout=90,
+    )
+    assert result.returncode == 0, result.stdout + result.stderr
diff --git a/tests/test_notes_reference_contracts_js.py b/tests/test_notes_reference_contracts_js.py
new file mode 100644
index 000000000..f9a814c81
--- /dev/null
+++ b/tests/test_notes_reference_contracts_js.py
@@ -0,0 +1,20 @@
+"""Run deterministic Notes contracts in the authoritative pytest CI shards."""
+import os
+import subprocess
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+def test_notes_domain_application_infrastructure_and_compatibility_contracts():
+    files = [
+        "notesCharacterization", "notesRecurrence", "notesInfrastructure",
+        "notesApplication", "notesReminders", "notesWorkflows", "notesDraftAutosave",
+        "selectedNotesContext", "noteTestOracle",
+    ]
+    result = subprocess.run(
+        ["node", "--test", *[f"tests/{name}.test.mjs" for name in files]], cwd=ROOT,
+        env=dict(os.environ, ENDPOINT_URL="http://127.0.0.1:1"),
+        capture_output=True, text=True, timeout=60,
+    )
+    assert result.returncode == 0, result.stdout + result.stderr
diff --git a/tests/test_notes_search_reset_on_reopen_js.py b/tests/test_notes_search_reset_on_reopen_js.py
index 885ad3dee..3b6a9a183 100644
--- a/tests/test_notes_search_reset_on_reopen_js.py
+++ b/tests/test_notes_search_reset_on_reopen_js.py
@@ -8,32 +8,34 @@ reset is present in openPanel, beside the existing _editingId reset.
 import re
 from pathlib import Path
 
-SRC = Path("static/js/notes.js").read_text(encoding="utf-8")
+from tests.helpers.notes_source import notes_source
+
+SRC = notes_source("ui/panel", "ui/filters", "ui/cardRendering", "ui/cardInteractions", "ui/drawing", "infrastructure/storage", "application/state", "ui/toolbar")
 
 
 def _open_panel_body():
-    start = SRC.index("export function openPanel()")
-    rest = SRC[start + len("export function openPanel()"):]
-    m = re.search(r"\n(?:export\s+)?(?:async\s+)?function ", rest)
+    start = SRC.index("function openPanel()")
+    rest = SRC[start + len("function openPanel()"):]
+    m = re.search(r"\n\s*(?:export\s+)?(?:async\s+)?function ", rest)
     return rest[: m.start()] if m else rest
 
 
 def test_open_panel_resets_search_query():
     body = _open_panel_body()
-    assert "_searchQuery = ''" in body, body[:400]
+    assert "app.setSearchQuery('')" in body, body[:400]
     # reset must sit with the other open-time state resets, before render
-    assert body.index("_searchQuery = ''") < body.index("_renderNotes") if "_renderNotes" in body else True
+    assert body.index("app.setSearchQuery('')") < body.index("_renderNotes") if "_renderNotes" in body else True
 
 
 def test_module_still_declares_search_query():
-    assert "let _searchQuery = ''" in SRC
+    assert "searchQuery: ''" in SRC
 
 
 def test_notes_label_chips_can_be_collapsed_like_calendar_tags():
     assert "NOTES_LABELS_COLLAPSED_KEY = 'odysseus-notes-labels-collapsed'" in SRC
-    assert "_labelsCollapsed = !_labelsCollapsed" in SRC
-    assert "localStorage.setItem(NOTES_LABELS_COLLAPSED_KEY" in SRC
-    assert "toggle.textContent = _labelsCollapsed ? '+ Tags' : '− Tags';" in SRC
+    assert "app.setLabelsCollapsed(!state.labelsCollapsed)" in SRC
+    assert "persistence.setItem(NOTES_LABELS_COLLAPSED_KEY" in SRC
+    assert "toggle.textContent = state.labelsCollapsed ? '+ Tags' : '− Tags';" in SRC
     assert "bar.style.display = 'none';" in SRC
 
 
diff --git a/tests/test_notes_select_esc_listener_js.py b/tests/test_notes_select_esc_listener_js.py
index dedc612a2..68598212d 100644
--- a/tests/test_notes_select_esc_listener_js.py
+++ b/tests/test_notes_select_esc_listener_js.py
@@ -9,7 +9,9 @@ tracked-handler pattern in source.
 """
 from pathlib import Path
 
-SRC = Path("static/js/notes.js").read_text(encoding="utf-8")
+from tests.helpers.notes_source import notes_source
+
+SRC = notes_source("ui/panel")
 
 
 def test_select_esc_listener_is_tracked_not_anonymous():
diff --git a/tests/test_notes_sidebar_new_note.py b/tests/test_notes_sidebar_new_note.py
index 7c78818be..fe69e0e70 100644
--- a/tests/test_notes_sidebar_new_note.py
+++ b/tests/test_notes_sidebar_new_note.py
@@ -1,3 +1,4 @@
+from tests.helpers.notes_source import notes_source
 from pathlib import Path
 from tests.helpers.stylesheets import app_css
 
@@ -17,31 +18,32 @@ def test_notes_sidebar_new_action_matches_library_structure_and_animation():
 
 def test_notes_sidebar_new_action_opens_a_note_without_toggling_panel_closed():
     app = (ROOT / "static/app.js").read_text(encoding="utf-8")
-    notes = (ROOT / "static/js/notes.js").read_text(encoding="utf-8")
+    notes = notes_source("ui/quickAdd", "ui/cardInteractions", "ui/reminderDisplay", "index")
 
     assert "event.stopPropagation()" in app[app.index("const notesNewNoteBtn"):]
     assert "notesModule?.newNote?.()" in app
-    assert "export function newNote()" in notes
+    assert "function newNote()" in notes
     assert "requestAnimationFrame(() => _createNote('note'))" in notes
-    assert "openNote, newNote, openNotes" in notes
+    assert "newNote: quickAdd.newNote" in notes
+    assert "publicNewNote as newNote" in notes
 
 
 def test_sidebar_new_note_focuses_note_body_instead_of_title():
-    notes = (ROOT / "static/js/notes.js").read_text(encoding="utf-8")
+    notes = notes_source("ui/quickAdd", "ui/cardInteractions", "ui/reminderDisplay", "index")
 
     assert "form.querySelector('.note-form-content')" in notes
     assert "initialField?.focus()" in notes
 
 
 def test_notes_reminder_dot_stays_before_new_note_action():
-    notes = (ROOT / "static/js/notes.js").read_text(encoding="utf-8")
+    notes = notes_source("ui/quickAdd", "ui/cardInteractions", "ui/reminderDisplay", "index")
 
     assert "sidebarBtn.querySelector('#notes-new-note-btn')" in notes
     assert "sidebarBtn.insertBefore(dot, newNoteBtn || null)" in notes
 
 
 def test_checklist_preview_starts_at_first_unfinished_item():
-    notes = (ROOT / "static/js/notes.js").read_text(encoding="utf-8")
+    notes = notes_source("ui/quickAdd", "ui/cardInteractions", "ui/reminderDisplay", "index")
     start = notes.index("function _bindCardEvents(body)")
     end = notes.index("const tapToEditOrSelect", start)
     setup = notes[start:end]
@@ -51,7 +53,7 @@ def test_checklist_preview_starts_at_first_unfinished_item():
 
 
 def test_checklist_preview_releases_scroll_at_its_boundaries():
-    notes = (ROOT / "static/js/notes.js").read_text(encoding="utf-8")
+    notes = notes_source("ui/quickAdd", "ui/cardInteractions", "ui/reminderDisplay", "index")
     css = app_css()
 
     assert "el.addEventListener('wheel'" in notes

From b2e717e28fcab9f3b08c68083477d68658959270 Mon Sep 17 00:00:00 2001
From: Alexandre Teixeira <111787685+alteixeira20@users.noreply.github.com>
Date: Thu, 15 Oct 2026 09:30:16 +0100
Subject: [PATCH 18/53] refactor(skills): extract evaluation and audit
 orchestration (#6711)

* refactor(skills): extract evaluation and audit orchestration

* chore(security): scope OpenAPI digest Gitleaks exception

* refactor(skills): establish domain-oriented service boundaries

* refactor(skills): address architecture review feedback

* fix(skills): restore prompt seams and harden signature contracts

* test(skills): restore ReDoS coverage and simplify API baseline
---
 .gitleaks.toml                              |   14 +
 docs/skills-audit-architecture.md           |  379 ++
 docs/skills-audit-second-review.md          |  200 +
 routes/skills_routes.py                     | 1808 +-------
 services/skills/__init__.py                 |    1 +
 services/skills/agent_runner.py             |  308 ++
 services/skills/audit_workflow.py           |  439 ++
 services/skills/dependencies.py             |   35 +
 services/skills/evaluation.py               |  464 ++
 services/skills/job_coordinator.py          |  216 +
 services/skills/model_selection.py          |   75 +
 services/skills/prompts.py                  |   52 +
 services/skills/publication.py              |  349 ++
 tests/fixtures/skills_api_baseline.json     | 4429 +++++++++++++++++++
 tests/fixtures/skills_openapi_baseline.json | 1226 +++++
 tests/test_redos_residual_python.py         |    8 +-
 tests/test_redos_verdict_continuation.py    |    4 +-
 tests/test_skills_audit_characterization.py |  485 ++
 tests/test_skills_audit_services.py         |  402 ++
 19 files changed, 9190 insertions(+), 1704 deletions(-)
 create mode 100644 docs/skills-audit-architecture.md
 create mode 100644 docs/skills-audit-second-review.md
 create mode 100644 services/skills/__init__.py
 create mode 100644 services/skills/agent_runner.py
 create mode 100644 services/skills/audit_workflow.py
 create mode 100644 services/skills/dependencies.py
 create mode 100644 services/skills/evaluation.py
 create mode 100644 services/skills/job_coordinator.py
 create mode 100644 services/skills/model_selection.py
 create mode 100644 services/skills/prompts.py
 create mode 100644 services/skills/publication.py
 create mode 100644 tests/fixtures/skills_api_baseline.json
 create mode 100644 tests/fixtures/skills_openapi_baseline.json
 create mode 100644 tests/test_skills_audit_characterization.py
 create mode 100644 tests/test_skills_audit_services.py

diff --git a/.gitleaks.toml b/.gitleaks.toml
index 3a51ae4c1..0eec3f1ae 100644
--- a/.gitleaks.toml
+++ b/.gitleaks.toml
@@ -21,3 +21,17 @@ regexes = [
   '''^inherits_2\.0\.1$''',
   '''^inherits_2\.0\.3$''',
 ]
+
+
+[[allowlists]]
+description = "Reviewed Skills OpenAPI baseline SHA-256 digest"
+targetRules = ["generic-api-key"]
+condition = "AND"
+paths = [
+  '''(?:^|/)tests/fixtures/skills_api_baseline\.json$''',
+  '''(?:^|/)docs/skills-audit-architecture\.md$''',
+]
+regexTarget = "secret"
+regexes = [
+  '''^7abc5b334a6c3c52dd3eba15d8bc516da728a67f14fb7f56d0bb5992d89a16ca$''',
+]
diff --git a/docs/skills-audit-architecture.md b/docs/skills-audit-architecture.md
new file mode 100644
index 000000000..78227a763
--- /dev/null
+++ b/docs/skills-audit-architecture.md
@@ -0,0 +1,379 @@
+# Skills evaluation and audit architecture
+
+The Skills backend separates HTTP transport, model evaluation, agent execution,
+audit orchestration and publication policy. `services/skills/` coordinates those
+responsibilities; `services/memory/skills.py` remains the canonical persistence
+and lifecycle owner. The extraction preserves the existing HTTP and Python
+contracts. [PR #6711](https://github.com/odysseus-dev/odysseus/pull/6711) tracks
+this boundary change under [issue #6710](https://github.com/odysseus-dev/odysseus/issues/6710).
+
+## Responsibilities and dependency boundaries
+
+| Module | Responsibility |
+| --- | --- |
+| `routes/skills_routes.py` | FastAPI request models, endpoint declarations, authentication, ownership, HTTP errors, exact approval validation and Python compatibility bindings |
+| `services/skills/job_coordinator.py` | Transient job creation, continuation after approval validation, candidate selection, public polling projections and cancellation requests |
+| `services/skills/agent_runner.py` | Manual execution, audit arms, agent loop integration, transcripts, authority propagation, approval pauses and same-task stream closure |
+| `services/skills/audit_workflow.py` | Per-skill audit sequencing, self-edit retries, teacher escalation, sequential batches and scheduled execution |
+| `services/skills/evaluation.py` | Model grading, verdict parsing, necessity and retrieval checks, efficiency fields and markdown improvement generation |
+| `services/skills/publication.py` | Confidence and publishing policy, duplicate rules, batch finalization and markdown updates through SkillsManager |
+| `services/skills/model_selection.py` | Owner-scoped worker/teacher resolution, utility fallback, endpoint selection and credential lookup |
+| `services/skills/prompts.py` | Shared task construction and explicitly untrusted skill context |
+| `services/skills/dependencies.py` | Frozen `AuditDependencies` containing callable bindings and transient registry references |
+| `services/memory/skills.py` | Canonical skill identity, owner isolation, durable storage, indexing, retrieval and lifecycle state |
+
+The package initializer identifies the domain without adding a service facade.
+Evaluation does not schedule jobs or persist skills. Publication computes policy
+and applies updates through the supplied SkillsManager. Services do not import
+`routes.skills_routes`. The existing preferences adapter in `publication.py`
+still imports `routes.prefs_routes`; moving that adapter is a separate change.
+
+```mermaid
+flowchart TD
+    HTTP[Authenticated HTTP requests] --> Routes[skills_routes]
+    Builtins[builtin_actions callers] --> Routes
+    Routes --> Jobs[job_coordinator]
+    Routes --> Models[model_selection]
+    Routes --> Evaluation[evaluation]
+    Routes --> Runner[agent_runner]
+    Routes --> Workflow[audit_workflow]
+    Jobs -->|injected calls| Runner
+    Jobs -->|injected calls| Workflow
+    Workflow -->|injected calls| Runner
+    Workflow -->|injected calls| Evaluation
+    Workflow -->|injected calls| Publication[publication]
+    Runner -->|injected calls| Evaluation
+    Runner --> Runtime[Agent runtime and authority enforcement]
+    Runner --> Prompts[prompts and untrusted context]
+    Jobs --> Prompts
+    Workflow --> Prompts
+    Routes --> Manager[Canonical SkillsManager]
+    Runner --> Manager
+    Workflow --> Manager
+    Publication --> Manager
+    Publication --> Preferences[Existing preferences adapter]
+    Models --> Resolver[Endpoint resolver and owner-scoped credentials]
+```
+
+Arrows include injected calls, rather than only Python imports. The workflow
+imports `SkillAuditUnavailable` from the runner. Route wrappers construct
+`AuditDependencies` on entry from the current route bindings, so existing
+callers and monkeypatches reach the same collaborators without rebinding shared
+service globals.
+
+The manual test registry belongs to `agent_runner.py`; the audit registry belongs
+to `audit_workflow.py`. Routes expose aliases to those dictionaries. Registries
+hold process-local job state and are not durable skill stores. All durable
+metadata, confidence, markdown and publication changes use SkillsManager.
+Published-only retrieval and local exclusion of `remote-only` skills stay in
+the manager/index boundary. Service loggers use their module names; the route
+module retains its own logger. Root handlers supply the existing log output.
+
+## Execution and publication lifecycle
+
+1. The HTTP handler authenticates the caller, verifies ownership and validates
+   the request. Manual model choices retain registered-endpoint validation and
+   owner-scoped credential lookup.
+2. Job coordination creates the owner-keyed transient record and launches the
+   execution coroutine. Replacing a manual test retires its pending approval.
+   Polling exposes only the existing public fields, excluding credentials,
+   private transcripts, continuation state and asyncio tasks.
+3. The runner uses the originating request authority or the consumed sealed
+   approval authority. It captures the transcript and closes the async stream
+   with `aclosing` inside the task that opened it, including early approval
+   pauses, cancellation and exceptions.
+4. Manual approval pauses return to the HTTP validation boundary. Continuation
+   reconstructs context from the original untrusted skill and accumulated
+   untrusted transcript. Manual completion records audit metadata and adjusts
+   confidence (pass .95, needs_work .6, fail .4) without publishing.
+5. An automated audit checks deterministic duplicates, advisory necessity and,
+   when indicated, retrieval precision. It runs skill and no-skill arms on the
+   same task, grades the result, then may self-edit and retry. An optional
+   distinct teacher rewrites the skill; the worker performs the retry.
+6. Publication applies owner preferences, confidence thresholds, necessity,
+   utility and duplicate rules through SkillsManager. A normal sequential batch
+   finalizes its processed results. Cancellation or infrastructure unavailability
+   skips batch finalization and clears task/current state.
+
+A clean audit pass sets confidence to .95, a self-edit pass to .85 and a teacher
+rewrite pass to .8. Continued failure becomes draft at .35. Unknown and
+inconclusive verdicts preserve publication state. Automatic publishing requires
+an enabled owner policy, a passing verdict at or above the configured threshold,
+and no necessity, worse-baseline or duplicate blocker. The default threshold is
+.85; owner values are clamped to [0, 1]. Markdown edits pin the existing skill name
+so usage and audit sidecars remain attached to the same identity.
+
+Per-skill duplicate blocking and batch duplicate finalization have distinct
+selection rules and must not be consolidated without a behavior proposal.
+Batch finalization excludes builtins and binned records, changes only processed
+skills, protects approval-required results, and bins duplicate losers. Duplicate
+similarity uses the existing .38 threshold and name-suffix grouping.
+
+Batches run sequentially per owner, retain current/done/results and timestamps,
+and cap progress logs at 1,000 entries. Ordinary exceptions record inconclusive
+skill audits. Infrastructure failures stop the batch without inventing a skill
+verdict. Scheduled execution skips an active owner job, selects existing lifecycle
+candidates by oldest audit, caps the batch (default eight), and marks model phases
+as background work. These services retain the existing scheduling and
+cancellation semantics.
+
+## Security and approval invariants
+
+HTTP authentication and owner verification remain at the transport boundary.
+Manager reads and writes receive the owner. Ownerless builtins retain their
+existing visibility; an authenticated user cannot access an ownerless ordinary
+skill. Existing ownerless deployment behavior is preserved.
+
+The `/test-approval` handler validates the pending job, approval ID, decision,
+owner and empty session binding, then destructively consumes the sealed approval
+with `allow_continuation=False` before calling the coordinator. Stale, mismatched
+or reused approvals fail with 409. The consumed grant authorizes only its exact
+action. Services do not manufacture approval authority or relax process identity,
+workspace confinement or request-authority enforcement in the agent runtime.
+
+Skill markdown and resumed transcripts remain explicitly untrusted context,
+never trusted system instructions. Audit arms suppress saved skill injection.
+Unattended runs deny encountered approval records instead of leaving reusable
+grants. An initial approval-required audit result preserves the skill's publication
+and confidence and directs the user to manual approval. Retry handling has an
+inherited gap: an approval pause after a rewrite can still lead to demotion.
+Same-task stream closure preserves the originating ContextVar cleanup, but manual
+cancellation can retain private continuation state. These are separate hardening
+items, not guarantees supplied by the extraction.
+
+## Model selection and evaluation
+
+Audit resolution uses an explicit endpoint/model pair when supplied, looking up
+credentials among enabled owner-visible endpoints. A model-only choice uses the
+existing owner-scoped model resolver. Otherwise it resolves the utility model,
+including the resolver's default behavior, then takes the first configured
+utility fallback if the primary result is incomplete. A missing worker raises
+`ValueError`. Served-model normalization keeps an exact match, then a basename
+match, then the first served ID; discovery exceptions keep the resolved choice.
+
+An enabled teacher resolves separately with the same owner. Its credentials are
+not borrowed from the worker. Teacher resolution failure logs the existing warning
+and leaves the teacher absent. Manual tests retain their HTTP endpoint validation
+and registered fallback credentials.
+
+Owner reasoning effort is resolved for each evaluation or rewrite call. Workload
+flags, credentials, retries, prompts and permissive parsing remain unchanged:
+
+| Phase | Token budget | Timeout in seconds |
+| --- | --- | --- |
+| Run review, up to two attempts | 32768 | 180 |
+| Necessity | 8192 | 120 |
+| Retrieval precision | 4096 | 90 |
+| Markdown improvement | 16384 | 180 |
+
+Review parsing retains think-block stripping, trailing-comma recovery, last
+usable verdict selection, prose fallback, bounded fields and unknown outcomes.
+These model outputs are advisory and do not grant execution authority.
+
+## Public HTTP contract
+
+All paths below have prefix `/api/skills`. Successful status defaults to 200.
+Request models and endpoint declaration order remain fixed. A frozen
+OpenAPI and declaration-order fixture records
+the baseline contract independently of the extracted implementation.
+
+| Method and suffix | Successful response | Authorization and errors |
+| --- | --- | --- |
+| GET empty | `skills,count` | Owner-filtered load |
+| GET `/index` | `index,count` | Owner-scoped eligible index |
+| GET `/slash-catalog` | `skills,count` | Owner-scoped index; sorted slash entries |
+| GET `/builtin` | `builtin,count` and optional `error` | Existing shared capability text |
+| GET `/builtin/{name}` | `name,text,default,is_overridden` | 404 missing tool; 500 import failure |
+| PUT `/builtin/{name}` | `ok,name,is_overridden` | Admin; 404 unknown, 400 missing text |
+| DELETE `/builtin/{name}` | `ok,name,is_overridden` | Admin |
+| POST `/import-from-url` | `ok,skill,files` | Admin and current owner; 400 import, 502 HTTP, 500 other failure |
+| POST `/add` | `ok,deduped,skill` | Current owner passed to manager; unchanged old/new request fields |
+| POST `/{skill_id}/invoke` | `ok,type,name,command,message` | Eligible owner index only; 404 unavailable/source missing |
+| GET `/{skill_id}` | Full skill dictionary | Owner load; 404 missing |
+| GET `/{skill_id}/markdown` | `name,markdown` | Owner verification; 404 missing/source missing |
+| POST `/{skill_id}/test` | `ok,status,skill,model` | Owner verification, HTTP request authority, registered fallback credentials; 400 missing/invalid model |
+| POST `/{skill_id}/test-approval` | `ok,status,decision` | User approval request, owner verification, pending ID/owner/empty session match; 400 invalid body/decision, 409 stale/mismatch/consumed |
+| GET `/{skill_id}/test-status` | `status` or `status,task,model,log,verdict,approval` | Owner-keyed lookup; server continuation/credentials omitted |
+| POST `/audit-all` | `ok,status,total` plus running `done,model` or empty `results,log` | Owner-keyed singleton; 400 model resolution |
+| GET `/audit-all/status` | `status` or job progress/result/log/timestamps | Owner-keyed lookup; task and credentials omitted |
+| POST `/audit-all/cancel` | `ok,status` | Owner-keyed lookup and cancellation |
+| POST `/{skill_id}/markdown` | `ok,name` | Owner verification; 400 missing/parse, 404 missing, 500 update |
+| PUT `/{skill_id}` | `ok` | Owner verification and scoped manager update; 404 missing |
+| DELETE `/{skill_id}` | `ok` | Owner verification and scoped manager deletion; 404 missing |
+| POST `/search` | `skills,query,count` | Owner-filtered input; 400 empty query |
+
+Strict owner verification allows an ownerless builtin but denies an ownerless
+ordinary skill for an authenticated user. The existing ownerless deployment
+behavior remains. Global auth middleware is unchanged.
+
+## Python compatibility and frozen contracts
+
+`app.py` imports `setup_skills_routes`. `src/builtin_actions.py` uses the existing
+route helpers and audit registry. Route aliases and wrappers preserve the original
+28 inspectable interfaces, `SkillAuditUnavailable`, registry identity and patchable
+collaborators. Lazy model/agent imports and route-level effort injection keep
+existing offline test seams effective.
+
+The task and message callbacks are bound through `AuditDependencies` at service
+entry. Patches to route-level test tasks and test/baseline messages reach manual
+execution, approval continuation, both audit arms, worker retries and scheduled
+audits. The `_skill_baseline_task` compatibility alias delegates to the current
+route test-task builder. Execution continues to reuse one task for both arms,
+as in the original implementation; it does not independently derive a baseline
+task through that alias.
+
+`tests/fixtures/skills_api_baseline.json` records declaration order and structural
+signatures captured from pre-extraction revision
+`86b886c611338282af6d4a717246ea4e256f58df`. Signature records retain parameter
+names, order, kinds, defaults, default factories and annotations, including
+Pydantic constraint metadata. They compare typing origins and arguments instead
+of Python-version-dependent annotation representations. The expanded records also
+pin field validation aliases, alias priority, discriminators, `validate_default`,
+rebuilt field annotations and model configuration. Field order remains visible
+through the constructor parameter sequence. Only the known builtin factories
+`list`, `tuple`, `dict`, `set` and `frozenset` are supported. Custom factories,
+including closures and factories taking validated data, fail closed without being
+executed. Unsupported metadata/configuration values also raise rather than using
+unstable representations. This is a structural contract for supported interfaces,
+not proof of behavioral equivalence for arbitrary validators or Python code.
+
+The expanded fixture was derived again from the original revision above in a
+detached scratch worktree, with the updated comparator copied in. Python 3.11
+and 3.12 produced byte-identical snapshots. The previous parameter/return records,
+all 28 interface names, all 22 endpoint declarations and the original OpenAPI
+digest were checked unchanged before accepting the new field records.
+
+`tests/fixtures/skills_openapi_baseline.json` is the same baseline's complete
+Skills-router OpenAPI document, generated with a standalone FastAPI application.
+Sorted keys, ASCII escaping, two-space indentation and a final newline make the
+fixture deterministic. Tests require exact canonical equality and print a unified
+diff on mismatch. The redundant digest field and assertions have been removed;
+they provided no independent compatibility guarantee. The fixture pins model
+schemas and constraints. CI reads committed fixtures and needs no Git history
+for these tests. Baseline updates require an intentional compatibility decision, rather
+than regenerating fixtures from a failing implementation.
+
+The narrow `.gitleaks.toml` exception remains necessary for the historical public
+digest in earlier fixture and documentation revisions. It applies to the exact digest,
+the `generic-api-key` rule and the two named paths. Removing a current copy cannot
+remove findings from published history. Keep the exception unless the pinned
+full-history scan proves it unnecessary; do not rewrite history to remove it.
+The checksum-verified 8.30.1 scan without this exception still reports both
+historical copies in commit `a547c4d8`; retaining the exception passes the full
+PR/dev history scan.
+Reconsider it after squash merge only after verifying the resulting reachable
+history with the pinned full-history scan.
+
+The ReDoS source guard scans `services/skills/evaluation.py`, the canonical
+evaluation parser module, as well as the retained route and memory-extractor
+locations. Verdict regex runtime tests import the canonical module directly.
+The source guard must reject reintroducing the lazy think-block expression;
+the ordinary-input and adversarial-flood runtime tests remain in place. An isolated
+source mutation reproduced the old guard's false green for the evaluation module.
+The corrected guard rejected the vulnerable expression in each of the three
+locations and passed again after restoring the temporary copies. The mutated
+regex was never executed, and production parser behavior was not changed.
+
+## Reproducible validation
+
+From the repository root, use a virtual environment with `requirements-dev.txt`
+installed and the repository's frontend dependencies available. The examples use
+`.venv/bin/python`; repeat the contract tests with a Python 3.12 environment as
+well as Python 3.11. Record interpreter/dependency versions with results.
+
+```sh
+.venv/bin/python -m pytest -q \
+  tests/test_skills_audit_characterization.py tests/test_skills_audit_services.py
+.venv/bin/python -m compileall -q app.py core routes src services scripts tests
+.venv/bin/python -c 'import routes.skills_routes; import services.skills.agent_runner; import services.skills.audit_workflow'
+.venv/bin/python scripts/build_frontend.py --check
+node scripts/check_frontend.mjs
+node --test tests/skillsApproval.test.mjs tests/frontendArchitecture.test.mjs
+git diff --check
+```
+
+The focused Skills, authority and approval selection is reproducible with:
+
+```sh
+.venv/bin/python - <<'PYTHON'
+from pathlib import Path
+import subprocess
+import sys
+
+files = set()
+for path in Path("tests").rglob("test_*.py"):
+    text = path.read_text()
+    if ("skill" in path.name or "approval" in path.name
+        or "utility_reasoning" in path.name or "skills_routes" in text
+        or "review_endpoint_credentials" in path.name):
+        files.add(str(path))
+files.update([
+    "tests/test_request_authority.py",
+    "tests/test_endpoint_registered_authority.py",
+    "tests/test_redos_verdict_continuation.py",
+    "tests/test_redos_residual_python.py",
+])
+subprocess.run([sys.executable, "-m", "pytest", "-q", "-rs",
+                "--durations=15", *sorted(files)], check=True)
+PYTHON
+```
+
+The original selection contained 729 cases. Additional characterization cases
+increase that count without removing the original coverage. For the full suite,
+remove a development `APP_PORT` and put the environment's tools on PATH:
+
+```sh
+env -u APP_PORT PATH="$PWD/.venv/bin:$PATH" \
+  PLAYWRIGHT_BROWSERS_PATH="$PWD/.cache/ms-playwright" \
+  .venv/bin/python -m pytest -q -rs --durations=25
+```
+
+Run the checksum-verified Gitleaks binary pinned in
+`.github/workflows/secret-scan.yml` on full reachable history, including the PR
+head and fetched official `dev`. The current workflow pins 8.30.1. Its CI command
+is `gitleaks git --no-banner --redact --verbose .` with a full-history checkout.
+A local checkout can restrict refs to the relevant histories with
+`--log-opts='HEAD upstream/dev'`; do not restrict the commit range to just the
+latest patch. Scan uncommitted fixtures too before committing.
+
+## Historical evidence and validation limits
+
+The initial extraction validation at `a547c4d8` reported 42 characterization and
+service cases, 729 focused cases, 13 relevant Node cases and 17 isolated uvicorn
+HTTP checks passing. The historical repository-wide run reported 13,959 passed,
+60 skipped and three failures. These counts describe the extraction validation,
+not the current revision. The HTTP checks used isolated state and authentication
+and included second-owner denial, but exercised neither a configured live model
+nor an external tool action.
+
+The two containment failures reproduced on unchanged baseline `86b886c6` with
+extra `Failed to create stream fd: No such file or directory` stderr output:
+
+- `test_namespace_handshake_closes_model_stdin`
+- `test_execution_environment_cannot_replace_probed_bwrap[False]`
+
+`test_legacy_cleanup_against_a_private_real_tmux_server` failed under the original
+full-suite load and passed isolated reruns. Its cause was not fully diagnosed.
+These historical failures must be distinguished from new regressions; successful
+CI and maintainer review remain integration gates. Earlier AST comparisons and
+the [maintainer review](https://github.com/odysseus-dev/odysseus/pull/6711#issuecomment-6170115749)
+provide historical extraction evidence, not an independent review of later fixes.
+
+## Known limitations and follow-up boundaries
+
+[Issue #6635](https://github.com/odysseus-dev/odysseus/issues/6635) remains open:
+manual tests without an appropriate workspace can still fail to execute their
+proposed action. Stream cleanup and exact approvals are preserved, but do not
+supply a missing workspace.
+
+Jobs remain process-local and do not survive restarts. Durable jobs, moving the
+preferences adapter below transport, consolidating storage under the domain
+package, or changing duplicate/publication policies need separate designs.
+The canonical manager, skill format/lifecycle modules, provider implementations,
+agent authority enforcement and frontend contracts remain their existing owners.
+
+The [second-review correction report](skills-audit-second-review.md) records the
+restored prompt seams, independently expanded constructor baseline, actual
+validation results and a separate prioritized plan for the six inherited P2
+failure paths. Model-controlled lifecycle fields and preference-load failures
+require maintainer action before automatic rewrite/publication deployment.
diff --git a/docs/skills-audit-second-review.md b/docs/skills-audit-second-review.md
new file mode 100644
index 000000000..91fdaae43
--- /dev/null
+++ b/docs/skills-audit-second-review.md
@@ -0,0 +1,200 @@
+# Skills PR #6711 second-review corrections
+
+The correction scope is route prompt compatibility and structural constructor
+contracts. PR #6711 remains draft. Durable skill ownership stays with
+`SkillsManager`. No publication policy, authority mechanism, provider runtime,
+frontend behavior or protected manager/index implementation was changed.
+
+The reviewed head was `a6a33674ed4facf11f53e7cdd41f882ad0fa8482`. The independent
+original baseline is `86b886c611338282af6d4a717246ea4e256f58df`. Official `dev`
+integration was tested against `c3819e3cbf56c4f899eacc66b21115a77d9c570d`.
+
+## Compatibility corrections
+
+Service-local imports captured prompt builders outside the route namespace.
+Patching the public route symbols therefore stopped affecting execution after
+extraction. `AuditDependencies` now binds the current test-task, test-message and
+baseline-message builders. Manual execution, exact-approval continuation, initial
+audits, baseline arms, self/teacher retries and scheduled batches use those
+bindings. The route `_skill_baseline_task` wrapper again delegates to the current
+route `_skill_test_task`. Both execution arms still use one shared task, matching
+the original behavior. No service imports Skills routes.
+
+The signature checker treated a factory's module/qualified name as its identity
+and omitted Pydantic settings outside the generated Python signature. Closures
+with different captured values and default-validation changes were false
+negatives. New tests additionally demonstrated hidden validation-alias path and
+model-configuration changes. The checker now records public field validation
+settings, rebuilt annotations, defaults and inherited model configuration. See
+the [Pydantic FieldInfo reference](https://docs.pydantic.dev/latest/api/fields/)
+for the distinction between factories, validation aliases and `validate_default`.
+
+Only known builtin factories are supported by identity. Custom factories,
+including factories requiring validated field data, raise `TypeError` without
+being invoked during comparison. Unsupported metadata/configuration values also
+fail closed. No bytecode, arbitrary object representations or factory output is
+serialized. The comparator does not promise equivalence of arbitrary Python
+validators or factory implementations.
+
+The expanded fixture was generated from the original baseline in a new detached
+worktree, with only the revised test comparator copied in. Python 3.11 and 3.12
+produced byte-identical files. Every previous parameter/return record remains
+equal. All 28 interfaces and 22 endpoint declarations remain present. The
+canonical OpenAPI fixture is unchanged, and its original digest is unchanged.
+Independent native `inspect.signature` snapshots also match original versus
+corrected implementations on each interpreter.
+
+## Regression evidence and validation
+
+The new tests were run before production/comparator edits: 12 failed and four
+passed, demonstrating the six signature cases and six broken prompt cases. After
+correction, all 16 added cases pass. The prompt probes capture actual
+`stream_agent_loop` ingress rather than replacing the runners or coordination.
+They cover patched and normal execution, guard escaping and taint metadata,
+owner authority, exact-approval continuation, and worker retries after both
+self and teacher rewrites. The same ten prompt cases pass on the original
+implementation. The six signature cases reject custom factories without calling
+them and detect default validation, alias paths and model validation settings.
+
+Environments: Python 3.11.17 and 3.12.13, FastAPI 0.143.1, Pydantic 2.14.1,
+pytest 9.1.1. Python test commands set `FASTEMBED_MODEL=review-disabled` and
+`HF_HUB_OFFLINE=1` to exercise unavailable optional embeddings without model
+downloads. They do not validate live providers or embedding quality.
+
+| Executed scope | Result |
+| --- | --- |
+| 53-file Skills, approval, authority and lifecycle selection, Python 3.11 | 757 passed |
+| Same selection, Python 3.12 | 757 passed |
+| Both characterization/service files, included above | 70 passed |
+| Original baseline, available focused selection plus revised characterization | 724 passed |
+| Original baseline, revised characterization plus prompt probes, each interpreter | 47 passed |
+| Current-dev combined tree, focused selection plus eight intervening dev test files, each interpreter | 900 passed |
+| Repository-wide suite, Python 3.11 | 13,991 passed, 60 skipped, two inherited environment failures, six subtests passed |
+| Frontend publisher and architecture checks | Passed, zero changed modules |
+| Relevant Node tests | 13 passed |
+| Compilation, both Python versions | Passed |
+| Import graph and fresh service-first/route-first imports, both versions | Passed; acyclic; no reverse Skills route import |
+| Original normalized moved-body comparison | 26 of 26 matched after explicit dependency substitutions |
+| Pinned/checksum-verified Gitleaks 8.30.1, reachable HEAD and official dev histories | No leaks |
+| Same Gitleaks, tracked working files | No leaks |
+| Diff/whitespace and protected-source comparisons | Passed |
+
+The two repository-wide failures are
+`tests/test_containment_enforcement.py::test_namespace_handshake_closes_model_stdin`
+and `test_execution_environment_cannot_replace_probed_bwrap[False]`. Isolated
+reruns on both original and corrected implementations reproduce the same extra
+`Failed to create stream fd: No such file or directory` stderr. The independent
+review traced it to login-profile `im-config` calls to `systemd-cat` inside
+Bubblewrap without the journal stream socket. These environment failures remain;
+they were not hidden by excluding tests. A full Python 3.12 suite was not run.
+
+The combined test tree used the official merge revision `5419ed37`, whose tree
+exactly matches `git merge-tree --write-tree upstream/dev a6a33674`, with the
+correction diff applied in a detached scratch worktree. Published history was
+not rebased, amended, reset or rewritten.
+
+Local commands, independent fixture captures, baseline reproductions and full
+logs are retained under `/tmp/skills-6711-corrections/`. The independent review
+and adversarial probe source remain under `/tmp/skills-6711-second/`. These
+temporary evidence paths are not portable repository fixtures. CI should read
+the committed golden fixtures, not regenerate them from the implementation.
+
+## Separate inherited P2 hardening plan
+
+All six defects demonstrably exist on the official original baseline. The six
+safety assertions in `/tmp/skills-6711-second/test_adversarial.py` fail on both
+the original and corrected trees with the same outcomes. Logs are
+`inherited-original.log` and `inherited-head.log` in the correction evidence
+directory. The original/source body comparison also matches these paths after
+dependency substitutions. There is no demonstrated material worsening from the
+extraction. That finding does not make their security impact acceptable.
+
+Priorities below concern a separate hardening change. Items 1 and 2 are release
+blockers requiring maintainer resolution before deploying automatic skill
+rewrite/publication workflows. This recommendation is independent of whether
+the architecture PR is integrated. No tool-authority bypass or cross-owner
+credential disclosure was demonstrated, and no critical extraction regression
+was found that requires expanding this compatibility correction.
+
+1. **Model-controlled lifecycle/provenance fields.** Current source:
+   [publication.py:328](../services/skills/publication.py#L328), especially line
+   342; the bypassed retrieval condition is
+   [skills.py:703](../services/memory/skills.py#L703). Original source:
+   [routes/skills_routes.py:1039](https://github.com/odysseus-dev/odysseus/blob/86b886c611338282af6d4a717246ea4e256f58df/routes/skills_routes.py#L1039).
+   `test_rewrite_cannot_promote_model_text_to_builtin` uses the real manager and
+   saves model markdown with `source: builtin`, `status: published` and
+   `confidence: 1`. Identity/owner remain pinned, but the lifecycle fields persist
+   and the skill becomes retrieval-eligible without a passing audit. Corrective
+   change: allowlist procedure and approved descriptive/retrieval fields during
+   model rewrites; preserve existing owner, provenance, publication, confidence,
+   audit and teacher lifecycle state. Only verified policy may update those
+   fields. Metadata-only fixes must preserve the procedure or trigger a retest.
+   Add real-manager tests for self, teacher and metadata-only rewrites.
+
+2. **Preference loading fails open for automatic publication.** Current source:
+   [publication.py:13](../services/skills/publication.py#L13) and
+   [skills.py:59](../services/memory/skills.py#L59). Original source:
+   [routes/skills_routes.py:710](https://github.com/odysseus-dev/odysseus/blob/86b886c611338282af6d4a717246ea4e256f58df/routes/skills_routes.py#L710).
+   `test_preferences_read_failure_does_not_enable_auto_publication` makes the
+   loader raise `PermissionError`; automatic publication is enabled rather than
+   preserving the owner's possible opt-out. Corrective change: distinguish a
+   successfully loaded empty preference store from an exception, log the failure
+   and disable automatic publication on exceptions. Align the manager retrieval
+   preference adapter in the separate fix. Test unreadable/malformed existing
+   preference files and the ordinary empty-store default independently.
+
+3. **Manual cancellation retains private credentials and stale running state.**
+   Current source:
+   [agent_runner.py:125](../services/skills/agent_runner.py#L125) and
+   [job_coordinator.py:49](../services/skills/job_coordinator.py#L49). Original:
+   [routes/skills_routes.py:635](https://github.com/odysseus-dev/odysseus/blob/86b886c611338282af6d4a717246ea4e256f58df/routes/skills_routes.py#L635).
+   `test_manual_cancellation_cleans_sensitive_continuation` suspends and cancels
+   the stream. The stream closes in its originating task, but job status remains
+   running and `_run.headers.Authorization` remains resident. Polling still hides
+   these fields; this is retention, not demonstrated disclosure. Corrective
+   change: handle `CancelledError`, mark cancelled, clear private continuation
+   data, retire only the attached exact approval and re-raise. Preserve state on
+   a normal awaiting-approval return. Retain task handles for coordinated
+   replacement/cancellation and test owner/approval isolation.
+
+4. **Approval pauses during retries lead to demotion.** Current source:
+   [audit_workflow.py:244](../services/skills/audit_workflow.py#L244), teacher
+   retry at line 280 and demotion at line 303. Original:
+   [routes/skills_routes.py:1448](https://github.com/odysseus-dev/odysseus/blob/86b886c611338282af6d4a717246ea4e256f58df/routes/skills_routes.py#L1448)
+   and lines 1484/1507. `test_retry_approval_preserves_publication_and_confidence`
+   begins published at .9, fails the first grade, then pauses the rewritten test
+   for approval. The result is flagged/draft/.35. The lower-level approval is
+   correctly denied; state handling afterwards is wrong. Corrective change:
+   immediately recognize `approval_required` after every retry, stop escalation
+   and demotion, and preserve the intended pre-pause lifecycle state. Coordinate
+   with item 1 so model rewrites cannot replace that saved state. Test both
+   self/teacher retries, repeated pauses and batch protection.
+
+5. **Duplicate losers are binned after keeper publication fails.** Current:
+   [publication.py:217](../services/skills/publication.py#L217), including loser
+   writes at line 228. Original:
+   [routes/skills_routes.py:914](https://github.com/odysseus-dev/odysseus/blob/86b886c611338282af6d4a717246ea4e256f58df/routes/skills_routes.py#L914).
+   `test_duplicate_losers_retained_if_keeper_write_fails` raises disk-full during
+   keeper publication and still observes a loser binned. Corrective change:
+   require confirmed keeper persistence before binning losers when automatic
+   publication is enabled. Treat both exceptions and False returns as failure,
+   retain candidates and report recovery information. Preserve existing keeper
+   selection and duplicate scoring rules; add failure/retry tests.
+
+6. **Reported publication status can disagree with canonical storage.** Current:
+   [publication.py:320](../services/skills/publication.py#L320). Original:
+   [routes/skills_routes.py:1017](https://github.com/odysseus-dev/odysseus/blob/86b886c611338282af6d4a717246ea4e256f58df/routes/skills_routes.py#L1017).
+   `test_publication_does_not_report_unpersisted_success` returns False from the
+   manager update; the helper reports published while the stored skill remains
+   draft. Exceptions are also swallowed by the inspected code. Corrective change:
+   check persistence success, log failures and return reloaded canonical state or
+   an explicit persistence error. Test False/exception outcomes and the job/UI
+   projection. Coordinate this change with item 5 without changing publication
+   thresholds or scoring.
+
+Maestrum's read-only triage delegation produced no usable result within its
+usefulness window and was cancelled. Cleanup completed and the session records
+an interrupted result, not a successful review. The coordinator reclaimed the
+remaining report work and verified the source references and reproduction logs
+above. No worker claim was used as proof. No GitHub issue, new PR, maintainer
+comment or PR-description edit was made.
diff --git a/routes/skills_routes.py b/routes/skills_routes.py
index 12f7cdd79..f469fc305 100644
--- a/routes/skills_routes.py
+++ b/routes/skills_routes.py
@@ -8,8 +8,6 @@ The on-disk format is SKILL.md (frontmatter + structured body) under
 """
 
 import logging
-import re
-from contextlib import aclosing
 from typing import List, Optional
 
 import httpx
@@ -19,44 +17,25 @@ from pydantic import BaseModel, Field
 
 from services.memory.skills import SkillsManager
 from src.auth_helpers import get_current_user
-from src.prompt_security import untrusted_context_message
-from src.text_helpers import strip_closed_think_blocks
+from services.skills import evaluation as _evaluation
+from services.skills import agent_runner as _agent_runner
+from services.skills import audit_workflow as _audit_workflow
+from services.skills import model_selection as _model_selection
+from services.skills import prompts as _prompts
+from services.skills import publication as _publication
+from services.skills import job_coordinator as _job_coordinator
+from services.skills.dependencies import AuditDependencies
 from src.utility_effort import effort_for_call
 from core.middleware import require_admin
 
 logger = logging.getLogger(__name__)
 
-# Last-resort verdict extraction from a teacher/verifier model's prose (run when
-# JSON parsing fails). `["\'\s:]*` already consumes whitespace, so the original
-# trailing `\s*` made two adjacent \s-matching quantifiers that backtrack O(n^2)
-# on a `verdict` + whitespace flood in untrusted model output (CodeQL
-# py/polynomial-redos). Without it a single unbounded quantifier remains — the
-# matched text is identical, and the scan is linear.
-_VERDICT_PROSE_RE = re.compile(
-    r'verdict["\'\s:]*["\']?(pass|needs_work|fail|inconclusive)', re.I
-)
+_VERDICT_PROSE_RE = _evaluation._VERDICT_PROSE_RE
 
+_verdict_efficiency = _evaluation.verdict_efficiency
 
-def _verdict_efficiency(verdict: Optional[dict]) -> dict:
-    if not isinstance(verdict, dict):
-        return {}
-    out = {"audit_summary": str(verdict.get("summary") or "")[:2000]}
-    for key in ("saved_turns", "saved_tool_calls"):
-        if key not in verdict:
-            continue
-        try:
-            out[key] = int(verdict.get(key))
-        except (TypeError, ValueError):
-            pass
-    baseline = str(verdict.get("baseline_verdict") or "").lower().strip()
-    if baseline in {"better", "same", "worse", "unknown"}:
-        out["baseline_verdict"] = baseline
-    if "usefulness" in verdict:
-        try:
-            out["usefulness"] = max(0.0, min(1.0, float(verdict.get("usefulness"))))
-        except (TypeError, ValueError):
-            pass
-    return out
+# Compatibility bindings keep existing imports and offline patch targets.
+# Implementations receive current collaborators through _audit_dependencies.
 
 
 class SkillAddRequest(BaseModel):
@@ -116,54 +95,18 @@ class SkillUpdateRequest(BaseModel):
     steps: Optional[List[str]] = None
 
 
-def _skill_test_task(skill: dict) -> str:
-    """Build the one shared task used by both sides of an audit comparison."""
-    if not isinstance(skill, dict):
-        skill = {}
-    ctx = (skill.get("when_to_use") or skill.get("description") or skill.get("name") or "").strip()
-    return (
-        "Complete this task end-to-end. Use this exact task context and do not ask "
-        "the user for more input. If a harmless fixture is needed, create the "
-        "smallest realistic one that satisfies the context, state it explicitly, "
-        "then complete and verify the result. Do not perform destructive or "
-        "externally visible actions. Task context: " + (ctx or "(general)")
-    )
+_skill_test_task = _prompts._skill_test_task
 
 
 def _skill_baseline_task(skill: dict) -> str:
-    """Backward-compatible alias; both audit arms must receive identical text."""
+    """Compatibility alias using the currently bound shared task builder."""
     return _skill_test_task(skill)
 
 
-def _skill_test_messages(md: str, task: str) -> list[dict]:
-    """Keep user-editable skill text out of the trusted system role."""
-    return [
-        {
-            "role": "system",
-            "content": (
-                "You are TESTING a skill. Follow the supplied reusable procedure "
-                "to complete the user's task for real, using available tools step "
-                "by step. If the skill is wrong, unclear, or references tools that "
-                "do not exist, do your best; the problems will be reviewed afterward."
-            ),
-        },
-        untrusted_context_message("skill under test", md),
-        {"role": "user", "content": task},
-    ]
+_skill_test_messages = _prompts._skill_test_messages
 
 
-def _skill_baseline_messages(task: str) -> list[dict]:
-    return [
-        {
-            "role": "system",
-            "content": (
-                "You are completing a baseline audit run. Do not use any saved "
-                "skill text. Solve the user's task using only your normal tools "
-                "and reasoning."
-            ),
-        },
-        {"role": "user", "content": task},
-    ]
+_skill_baseline_messages = _prompts._skill_baseline_messages
 
 
 async def _eval_skill_run(skill_md: str, task: str, transcript: str,
@@ -172,358 +115,38 @@ async def _eval_skill_run(skill_md: str, task: str, transcript: str,
                           skill_stats: Optional[dict] = None,
                           baseline_stats: Optional[dict] = None,
                           workload: str = "foreground", owner: Optional[str] = None) -> dict:
-    """LLM-as-judge: grade a skill test run from its transcript. Advisory only.
-
-    Robust against local reasoning models (strips <think>, lenient JSON,
-    generous token budget) — same defensive parsing used elsewhere.
-    """
-    import json as _json
-    import re as _re
-    from src.llm_core import llm_call_async
-
-    sys_prompt = (
-        "You are a strict QA reviewer judging whether an AI 'skill' (a reusable "
-        "procedure) actually works. You are given the SKILL, the TASK it was tested "
-        "on, and the TRANSCRIPT of the agent's run.\n\n"
-        "Judge honestly:\n"
-        "- The functional verdict judges ONLY whether the SKILL RUN completed the "
-        "task correctly and whether the skill procedure is usable. A correct skill "
-        "run is pass even when the baseline is equally good. Record comparative "
-        "value separately in baseline_verdict/usefulness.\n"
-        "- Did following the skill accomplish the task accurately?\n"
-        "- Are the steps clear, correct, and reproducible?\n"
-        "- Did it reference tools/commands that don't exist or that errored?\n"
-        "- Separately, compared with the baseline run WITHOUT the skill, did the skill make "
-        "the agent more accurate, use fewer turns/tool calls, or avoid avoidable "
-        "thrashing?\n"
-        "- Do NOT penalize a skill merely for being broad or generic. A broad "
-        "skill is useful if it makes the agent finish correctly in fewer turns "
-        "or with fewer tools than baseline.\n"
-        "- METADATA: do the frontmatter fields match what the skill actually does? "
-        "Flag wrong/misleading/missing tags, a wrong category, a when_to_use that "
-        "doesn't describe the real trigger, or a description that oversells or "
-        "mismatches the body. List each metadata problem in 'issues' (prefix it "
-        "with 'metadata:'). Metadata problems alone do NOT make the verdict 'fail' "
-        "if the procedure works — note them as issues on an otherwise-passing run.\n\n"
-        "Never use inconclusive merely because the baseline was the same or better. "
-        "IMPORTANT — fairness rule: if the SKILL RUN could NOT proceed because it lacked "
-        "an input or target the test never provided (e.g. there was no document/"
-        "email/data to act on, so the agent reasonably asked for it), that is NOT "
-        "the skill's fault. Return verdict \"inconclusive\" — do NOT mark it fail "
-        "or needs_work. Only judge the skill's PROCEDURE; reserve fail/needs_work "
-        "for when the steps themselves are wrong, vague, or reference missing tools.\n\n"
-        "If you need to reason, do it inside <think></think> FIRST. Then output "
-        "ONLY this JSON (no fences):\n"
-        'Set baseline_verdict to how the SKILL RUN compares to the BASELINE RUN.\n\n'
-        '{"verdict": "pass" | "needs_work" | "fail" | "inconclusive", '
-        '"confidence": 0.0-1.0, "summary": "one short sentence", '
-        '"issues": ["short issue", ...], '
-        '"baseline_verdict": "better" | "same" | "worse" | "unknown", '
-        '"usefulness": 0.0-1.0, "saved_turns": integer, "saved_tool_calls": integer}'
+    return await _evaluation.evaluate_run(
+        skill_md, task, transcript, url, model, headers, baseline_transcript,
+        skill_stats, baseline_stats, workload, owner, _effort_for_call=effort_for_call,
     )
-    # Give the judge plenty of transcript, and when it must trim, keep the TAIL
-    # (the final result lives at the end) plus a bit of the head — truncating to
-    # a short prefix made the judge wrongly call complete runs "incomplete /
-    # missing sections" because it never saw the end.
-    def _clip(t: str, limit: int = 24000) -> str:
-        t = (t or "").strip() or "(no output produced)"
-        if len(t) <= limit:
-            return t
-        head = limit // 4
-        return t[:head] + "\n\n…[transcript trimmed for length]…\n\n" + t[-(limit - head):]
-    skill_stats = skill_stats or {}
-    baseline_stats = baseline_stats or {}
-    user_msg = (
-        f"=== SKILL ===\n{(skill_md or '')[:4000]}\n\n"
-        f"=== TASK ===\n{task}\n\n"
-        f"=== SKILL RUN STATS ===\n"
-        f"turns={skill_stats.get('turns', 'unknown')} "
-        f"tool_calls={skill_stats.get('tool_calls', 'unknown')}\n\n"
-        f"=== SKILL RUN TRANSCRIPT ===\n{_clip(transcript)}\n\n"
-        f"=== BASELINE RUN WITHOUT SKILL STATS ===\n"
-        f"turns={baseline_stats.get('turns', 'unknown')} "
-        f"tool_calls={baseline_stats.get('tool_calls', 'unknown')}\n\n"
-        f"=== BASELINE RUN WITHOUT SKILL TRANSCRIPT ===\n{_clip(baseline_transcript)}"
-    )
-    _VERDICTS = ("pass", "needs_work", "fail", "inconclusive")
-
-    def _parse(raw: str):
-        """Return a final result dict on success, or None if unparseable."""
-        text = (raw or '')
-        # Strip closed think blocks. If a <think> was opened but never closed
-        # (the model ran out of budget mid-reasoning), drop everything from it
-        # onward so its stray braces don't poison JSON extraction.
-        text = strip_closed_think_blocks(text)
-        text = _re.sub(r'<think(?:ing)?>[\s\S]*$', '', text, flags=_re.I).strip()
-
-        def _coerce(d):
-            return d if (isinstance(d, dict) and "verdict" in d) else None
-
-        data = None
-        # Scan every balanced {...} candidate and keep the LAST one that parses
-        # and carries a "verdict" — the transcript is full of JSON API bodies,
-        # so a naive first-brace/last-brace span almost never parses.
-        for m in _re.finditer(r'\{[\s\S]*?\}', text):
-            frag = m.group(0)
-            for cand in (frag, _re.sub(r',(\s*[}\]])', r'\1', frag)):
-                try:
-                    d = _coerce(_json.loads(cand))
-                except Exception:
-                    d = None
-                if d is not None:
-                    data = d
-        # Fallback to the greedy outermost span (handles nested objects the
-        # non-greedy scan above splits apart).
-        if data is None:
-            a, b = text.find('{'), text.rfind('}')
-            if a >= 0 and b > a:
-                frag = text[a:b + 1]
-                for cand in (frag, _re.sub(r',(\s*[}\]])', r'\1', frag)):
-                    try:
-                        d = _coerce(_json.loads(cand))
-                    except Exception:
-                        d = None
-                    if d is not None:
-                        data = d
-                        break
-
-        v = str(data.get("verdict", "")).lower().strip() if isinstance(data, dict) else None
-        # Last resort: pull the verdict keyword straight out of the prose so a
-        # clearly-decided run isn't thrown away as "unparseable".
-        if v not in _VERDICTS:
-            km = _VERDICT_PROSE_RE.search(text)
-            if km:
-                v = km.group(1).lower()
-                if data is None:
-                    data = {}
-        if not isinstance(data, dict) or v not in _VERDICTS:
-            return None
-        try:
-            conf = float(data.get("confidence", 0))
-        except (TypeError, ValueError):
-            conf = 0
-        try:
-            usefulness = float(data.get("usefulness", 0.0))
-        except (TypeError, ValueError):
-            usefulness = 0.0
-        try:
-            saved_turns = int(data.get("saved_turns", 0))
-        except (TypeError, ValueError):
-            saved_turns = 0
-        try:
-            saved_tool_calls = int(data.get("saved_tool_calls", 0))
-        except (TypeError, ValueError):
-            saved_tool_calls = 0
-        return {
-            "verdict": v,
-            "confidence": max(0.0, min(1.0, conf)),
-            "summary": str(data.get("summary", ""))[:400],
-            "issues": [str(x)[:200] for x in (data.get("issues") or []) if str(x).strip()][:8],
-            "baseline_verdict": (
-                str(data.get("baseline_verdict", "unknown")).lower().strip()
-                if str(data.get("baseline_verdict", "unknown")).lower().strip() in {"better", "same", "worse", "unknown"}
-                else "unknown"
-            ),
-            "usefulness": max(0.0, min(1.0, usefulness)),
-            "saved_turns": saved_turns,
-            "saved_tool_calls": saved_tool_calls,
-        }
-
-    # Two attempts: the first lets the judge reason; if a heavy reasoning model
-    # burns its budget inside <think> and never emits the JSON, the second
-    # forbids thinking and demands the JSON immediately.
-    last_text = ""
-    last_err = None
-    for attempt in range(2):
-        msgs = [{"role": "system", "content": sys_prompt},
-                {"role": "user", "content": user_msg}]
-        if attempt == 1:
-            msgs[0]["content"] = (
-                sys_prompt + "\n\nDO NOT use <think> or any reasoning. Your reply "
-                "must START with '{' and be ONLY the JSON object, nothing else."
-            )
-        try:
-            raw = await llm_call_async(
-                # Generous budget so a heavy reasoner can think AND still have
-                # room to emit the JSON afterwards (reasoning tokens come out of
-                # this same cap; the server clamps to its own max).
-                url, model, msgs,
-                temperature=0.1, max_tokens=32768, headers=headers, timeout=180,
-                workload=workload,
-                reasoning_effort=effort_for_call(url, model, owner),
-            )
-        except Exception as e:
-            # Don't give up on a transient first-attempt error — let the second
-            # (no-think) attempt run before reporting failure.
-            last_err = e
-            continue
-        last_text = (raw or '')
-        parsed = _parse(raw)
-        if parsed is not None:
-            return parsed
-
-    if last_err is not None and not last_text:
-        return {"verdict": "unknown", "confidence": 0, "summary": f"Review call failed: {last_err}", "issues": []}
-    return {"verdict": "unknown", "confidence": 0,
-            "summary": "Reviewer returned unparseable output.", "issues": [], "raw": last_text[:300]}
 
 
 async def _eval_skill_necessity(skill_md: str, others: list, url: str, model: str,
                                 headers: Optional[dict],
                                 workload: str = "foreground", owner: Optional[str] = None) -> Optional[dict]:
-    """Advisory judge: is this skill worth keeping, or is it redundant / trivially
-    unnecessary? Sees the OTHER skills' names+descriptions so it can spot
-    duplicates. Returns {necessary, redundant_with, reason} or None. Never acts —
-    purely a flag the UI surfaces."""
-    import json as _json
-    import re as _re
-    from src.llm_core import llm_call_async
-
-    catalog = "\n".join(f"- {o.get('name')}: {o.get('description', '')}" for o in others) or "(no other skills)"
-    sys_prompt = (
-        "You assess whether a reusable AI 'skill' (a saved procedure) is worth keeping. "
-        "A skill is UNNECESSARY if it essentially duplicates another skill in the library. "
-        "Do NOT call a skill unnecessary merely because it is broad or generic; broad "
-        "skills can be worth keeping when they make a capable assistant finish accurately "
-        "with fewer turns or fewer tool calls than it would without the skill. A skill IS "
-        "necessary if it captures a reusable trigger, procedure, tool sequence, or "
-        "hard-won detail that could improve future runs.\n\n"
-        "Be conservative: only call it unnecessary when you're confident. Reason in "
-        "<think></think> first if needed, then output ONLY this JSON:\n"
-        '{"necessary": true|false, "redundant_with": ["skill-name", ...], '
-        '"reason": "one short sentence"}'
+    return await _evaluation.evaluate_necessity(
+        skill_md, others, url, model, headers, workload, owner,
+        _effort_for_call=effort_for_call,
     )
-    user_msg = (
-        f"=== SKILL UNDER REVIEW ===\n{(skill_md or '')[:3000]}\n\n"
-        f"=== OTHER SKILLS IN THE LIBRARY ===\n{catalog[:4000]}"
-    )
-    try:
-        raw = await llm_call_async(
-            url, model,
-            [{"role": "system", "content": sys_prompt}, {"role": "user", "content": user_msg}],
-            temperature=0.1, max_tokens=8192, headers=headers, timeout=120,
-            workload=workload,
-            reasoning_effort=effort_for_call(url, model, owner),
-        )
-    except Exception as e:
-        logger.warning(f"Necessity check failed: {e}")
-        return None
-    text = strip_closed_think_blocks(raw or '')
-    text = _re.sub(r'<think(?:ing)?>[\s\S]*$', '', text, flags=_re.I).strip()
-    data = None
-    a, b = text.find('{'), text.rfind('}')
-    if a >= 0 and b > a:
-        frag = text[a:b + 1]
-        for cand in (frag, _re.sub(r',(\s*[}\]])', r'\1', frag)):
-            try:
-                data = _json.loads(cand)
-                break
-            except Exception:
-                continue
-    if not isinstance(data, dict) or "necessary" not in data:
-        return None
-    return {
-        "necessary": bool(data.get("necessary", True)),
-        "redundant_with": [str(x)[:80] for x in (data.get("redundant_with") or []) if str(x).strip()][:6],
-        "reason": str(data.get("reason", ""))[:200],
-    }
 
 
-def _should_check_retrieval_precision(skill: dict) -> bool:
-    """Cheap prefilter for the expensive retrieval-precision judge.
-
-    Skills with broad tags like "network" or "document" are the ones most likely
-    to over-inject. Narrow command/vendor tags alone are fine.
-    """
-    broad = {
-        "arch", "arch linux", "linux", "network", "networking", "wifi",
-        "installation", "install", "system", "ssh", "document", "documents",
-        "search", "email", "calendar", "gpu", "server", "python",
-    }
-    if not isinstance(skill, dict):
-        return False
-    tags = {str(t or "").strip().lower() for t in (skill.get("tags") or [])}
-    if tags & broad:
-        return True
-    text = " ".join([
-        str(skill.get("name") or ""),
-        str(skill.get("description") or ""),
-        str(skill.get("when_to_use") or ""),
-    ]).lower()
-    return sum(1 for t in broad if t in text) >= 2
+_should_check_retrieval_precision = _evaluation.should_check_retrieval_precision
 
 
 async def _eval_skill_retrieval_precision(skill_md: str, others: list,
                                           url: str, model: str,
                                           headers: Optional[dict],
                                           workload: str = "foreground", owner: Optional[str] = None) -> Optional[dict]:
-    """Advisory judge: would this skill's metadata make retrieval over-select it?
-
-    This is distinct from "does the procedure work?". It asks whether tags,
-    description, and when_to_use are specific enough that the skill won't be
-    injected into adjacent but wrong tasks.
-    """
-    import json as _json
-    import re as _re
-    from src.llm_core import llm_call_async
-
-    catalog = "\n".join(f"- {o.get('name')}: {o.get('description', '')}" for o in others[:80]) or "(no other skills)"
-    sys_prompt = (
-        "You are auditing retrieval metadata for a reusable AI skill. The app selects "
-        "skills by matching user requests against the skill name, description, tags, "
-        "when_to_use, and procedure text. Judge whether this skill is likely to be "
-        "over-selected for nearby but wrong requests.\n\n"
-        "Focus ONLY on metadata/retrieval precision, not whether the procedure works. "
-        "Flag broad tags such as network, installation, system, document, search, ssh, "
-        "python, gpu, or server when they would cause this narrow skill to match too "
-        "many adjacent tasks. Recommend narrower tags/when_to_use wording. Compare "
-        "against the other skills to spot boundaries.\n\n"
-        "Return ok=true only when the trigger metadata is narrow enough. If not ok, "
-        "issues MUST start with 'metadata: retrieval:' and be actionable. Output ONLY JSON:\n"
-        '{"ok": true|false, "summary": "one short sentence", "issues": ["metadata: retrieval: ..."]}'
+    return await _evaluation.evaluate_retrieval_precision(
+        skill_md, others, url, model, headers, workload, owner,
+        _effort_for_call=effort_for_call,
     )
-    user_msg = (
-        f"=== SKILL UNDER REVIEW ===\n{(skill_md or '')[:5000]}\n\n"
-        f"=== OTHER SKILLS IN LIBRARY ===\n{catalog[:5000]}\n\n"
-        "Decide if this skill's retrieval metadata should be narrowed so it only "
-        "fires for its intended scenario and not for adjacent skills above."
-    )
-    try:
-        raw = await llm_call_async(
-            url, model,
-            [{"role": "system", "content": sys_prompt}, {"role": "user", "content": user_msg}],
-            temperature=0.1, max_tokens=4096, headers=headers, timeout=90,
-            workload=workload,
-            reasoning_effort=effort_for_call(url, model, owner),
-        )
-    except Exception as e:
-        logger.warning(f"Retrieval precision check failed: {e}")
-        return None
-    text = strip_closed_think_blocks(raw or '')
-    text = _re.sub(r'<think(?:ing)?>[\s\S]*$', '', text, flags=_re.I).strip()
-    data = None
-    a, b = text.find('{'), text.rfind('}')
-    if a >= 0 and b > a:
-        frag = text[a:b + 1]
-        for cand in (frag, _re.sub(r',(\s*[}\]])', r'\1', frag)):
-            try:
-                data = _json.loads(cand)
-                break
-            except Exception:
-                continue
-    if not isinstance(data, dict) or "ok" not in data:
-        return None
-    return {
-        "ok": bool(data.get("ok")),
-        "summary": str(data.get("summary", ""))[:300],
-        "issues": [str(x)[:220] for x in (data.get("issues") or []) if str(x).strip()][:6],
-    }
 
 
 # In-memory skill-test jobs, keyed by (owner, skill_name). Runs server-side so
 # the test survives the modal being closed; the UI polls /test-status. (Not
 # persisted across restart — it's a "come back in a bit" convenience.)
-_skill_test_jobs: dict = {}
+_skill_test_jobs = _agent_runner._skill_test_jobs
 
 
 async def _run_skill_test_job(
@@ -542,1175 +165,125 @@ async def _run_skill_test_job(
     exact_approval=None,
     request_authority=None,
 ):
-    """Background coroutine: run the skill in an agent loop, capture a condensed
-    log + transcript, then have the judge grade it. Writes into _skill_test_jobs."""
-    import json as _json
-    from src.agent_loop import stream_agent_loop
-    from src.agent_runtime.authority import RequestAuthority
-
-    job = _skill_test_jobs.get(key)
-    if job is None:
-        return
-    log = job["log"]
-    transcript = transcript if isinstance(transcript, list) else []
-    say_buf = []
-    skill_stats = {"turns": 0, "tool_calls": 0}
-
-    def _flush_say():
-        if say_buf:
-            log.append({"type": "say", "text": "".join(say_buf)})
-            say_buf.clear()
-
-    messages = list(messages) if isinstance(messages, list) else _skill_test_messages(md, task)
-    try:
-        # aclosing: pausing for an approval leaves this loop early, and the
-        # stream's ContextVar cleanup must run in this task, not in asyncio's
-        # finalizer (#6635).
-        async with aclosing(stream_agent_loop(
-            url, model, messages, headers=headers,
-            temperature=0.3, max_tokens=0, max_rounds=8, owner=owner,
-            exact_approval=exact_approval,
-            request_authority=(request_authority or (
-                exact_approval.pending.request_authority if exact_approval is not None else None
-            ) or RequestAuthority.empty(owner=owner)),
-        )) as stream:
-            async for chunk in stream:
-                if not chunk.startswith("data: ") or chunk.strip() == "data: [DONE]":
-                    continue
-                try:
-                    d = _json.loads(chunk[6:])
-                except Exception:
-                    continue
-                if d.get("delta"):
-                    say_buf.append(d["delta"]); transcript.append(d["delta"])
-                elif d.get("type") == "tool_start":
-                    _flush_say()
-                    skill_stats["tool_calls"] += 1
-                    cmd = str(d.get("command") or d.get("args") or "")[:300]
-                    log.append({"type": "tool_start", "tool": d.get("tool"), "command": cmd})
-                    transcript.append(f"\n[tool {d.get('tool')}] {cmd}\n")
-                elif d.get("type") == "tool_output":
-                    _flush_say()
-                    out = str(d.get("output") or "")[:600]
-                    tool_log = {"type": "tool_output", "output": out}
-                    approval = d.get("ask_user")
-                    if isinstance(approval, dict):
-                        tool_log["ask_user"] = approval
-                    log.append(tool_log)
-                    transcript.append(f"[output] {out}\n")
-                    if (
-                        isinstance(approval, dict)
-                        and approval.get("kind") == "tool_approval"
-                        and approval.get("approval_id")
-                    ):
-                        # Manual skill tests have their own polling UI instead of a
-                        # chat session. Pause the run and retain only server-side
-                        # continuation state until the same owner approves/denies
-                        # this exact sealed action.
-                        job["status"] = "awaiting_approval"
-                        job["approval"] = approval
-                        job["_transcript"] = transcript
-                        return
-                elif d.get("type") == "agent_step":
-                    _flush_say()
-                    try:
-                        skill_stats["turns"] = max(skill_stats["turns"], int(d.get("round") or 0))
-                    except (TypeError, ValueError):
-                        pass
-                    log.append({"type": "agent_step", "round": d.get("round")})
-                    transcript.append(f"\n--- round {d.get('round')} ---\n")
-                elif d.get("type") == "metrics":
-                    data = d.get("data") or {}
-                    try:
-                        skill_stats["turns"] = max(skill_stats["turns"], int(data.get("agent_rounds") or 0))
-                    except (TypeError, ValueError):
-                        pass
-                    try:
-                        skill_stats["tool_calls"] = max(skill_stats["tool_calls"], int(data.get("tool_calls") or 0))
-                    except (TypeError, ValueError):
-                        pass
-                if len(log) > 600:
-                    del log[0:len(log) - 600]
-        _flush_say()
-    except Exception as e:
-        _flush_say()
-        log.append({"type": "error", "error": str(e)})
-
-    job.pop("approval", None)
-    job.pop("_transcript", None)
-    job.pop("_run", None)
-    log.append({"type": "evaluating"})
-    try:
-        baseline_task = task
-        log.append({"type": "agent_step", "round": "baseline"})
-        baseline_transcript, baseline_stats, baseline_approval = await _run_skill_audit_arm(
-            _skill_baseline_messages(baseline_task),
-            url,
-            model,
-            headers,
-            owner,
-        )
-        if baseline_approval is not None:
-            try:
-                from src.tool_approvals import tool_approval_store
-                tool_approval_store.consume(
-                    baseline_approval.get("approval_id"),
-                    decision="deny",
-                    owner=owner,
-                    session_id=None,
-                )
-            except Exception:
-                logger.debug("Could not retire manual-test baseline approval", exc_info=True)
-        job["verdict"] = await _eval_skill_run(
-            md,
-            task,
-            "".join(transcript),
-            url,
-            model,
-            headers,
-            baseline_transcript=baseline_transcript,
-            skill_stats=skill_stats,
-            baseline_stats=baseline_stats,
-            owner=owner,
-        )
-    except Exception as e:
-        job["verdict"] = {"verdict": "unknown", "confidence": 0, "summary": f"Eval failed: {e}", "issues": []}
-    # Record the result so the card shows a 'verified' check (a manual test
-    # never involves the teacher) and nudge the confidence score to match the
-    # verdict — same scale as Audit-all's pass=0.95. inconclusive/unknown leave
-    # the score alone (missing-fixture or parse failures shouldn't punish it).
-    if skills_manager is not None:
-        v = (job["verdict"] or {}).get("verdict") or "unknown"
-        try:
-            skills_manager.set_audit(
-                name,
-                v,
-                by_teacher=False,
-                worker_model=model,
-                owner=owner,
-                **_verdict_efficiency(job.get("verdict")),
-            )
-        except Exception:
-            pass
-        conf = {"pass": 0.95, "needs_work": 0.6, "fail": 0.4}.get(v)
-        if conf is not None:
-            try:
-                skills_manager.update_skill(name, {"confidence": conf}, owner=owner)
-            except Exception:
-                pass
-    job["status"] = "done"
+    return await _agent_runner.run_test_job(
+        key, name, md, task, url, model, headers, owner, skills_manager,
+        messages=messages, transcript=transcript, exact_approval=exact_approval,
+        request_authority=request_authority, deps=_audit_dependencies(),
+    )
 
 
 # ── Autonomous skill audit: test → judge → self-edit → retry → teacher → flag ──
-_skill_audit_jobs: dict = {}
+_skill_audit_jobs = _audit_workflow._skill_audit_jobs
 
 
-def _audit_auto_publish_policy(owner) -> tuple[bool, float]:
-    """Return (auto_publish_enabled, minimum_confidence) for audit finalization."""
-    try:
-        from routes.prefs_routes import _load_for_user
-        prefs = _load_for_user(owner) or {}
-    except Exception:
-        prefs = {}
-    try:
-        from src.settings import get_setting
-        default_min = get_setting("skill_autosave_min_confidence", 0.85)
-    except Exception:
-        default_min = 0.85
-    enabled = bool(prefs.get("auto_approve_skills", True))
-    try:
-        min_conf = float(prefs.get("skill_min_confidence", default_min))
-    except (TypeError, ValueError):
-        min_conf = 0.85
-    return enabled, max(0.0, min(1.0, min_conf))
+_audit_auto_publish_policy = _publication.auto_publish_policy
 
 
-def _skill_duplicate_blocker(skills_manager, name: str, owner) -> Optional[str]:
-    """Cheap duplicate guard matching the UI's duplicate grouping.
-
-    The LLM necessity check catches semantic redundancy, but the UI also has a
-    cheap similarity pass. Use the same broad signal before auto-publishing so
-    a high-scoring lower-priority duplicate stays draft.
-    """
-    import re as _re
-
-    def _tokens(sk: dict) -> set[str]:
-        text = " ".join([
-            str(sk.get("name") or ""),
-            str(sk.get("description") or ""),
-            str(sk.get("when_to_use") or ""),
-            " ".join(sk.get("procedure") or []),
-            " ".join(sk.get("tags") or []),
-        ]).lower()
-        text = _re.sub(r"-\d+\b", "", text)
-        return {
-            t for t in _re.split(r"[^a-z0-9]+", text)
-            if len(t) > 2 and t not in {"the", "and", "with", "for", "from", "using"}
-        }
-
-    def _sim(a: dict, b: dict) -> float:
-        A, B = _tokens(a), _tokens(b)
-        if not A or not B:
-            return 0.0
-        return len(A & B) / max(1, len(A | B))
-
-    def _base(n: str) -> str:
-        return _re.sub(r"-\d+$", "", str(n or ""))
-
-    def _score(sk: dict) -> float:
-        return (
-            (100000 if (sk.get("status") == "published") else 0)
-            + int(sk.get("uses") or 0) * 100
-            + round(float(sk.get("confidence") or 0) * 100)
-            + (-5 if sk.get("audit_by_teacher") else 0)
-            - (len(str(sk.get("name") or "")) / 1000)
-        )
-
-    skills = [s for s in skills_manager.load(owner=owner) if s.get("status") != "binned"]
-    current = next((s for s in skills if (s.get("name") or s.get("id")) == name), None)
-    if not current:
-        return None
-    duplicates = []
-    cur_name = current.get("name") or current.get("id") or name
-    for other in skills:
-        other_name = other.get("name") or other.get("id")
-        if not other_name or other_name == cur_name:
-            continue
-        if _base(cur_name) == _base(other_name) or _sim(current, other) >= 0.38:
-            duplicates.append(other)
-    if not duplicates:
-        return None
-    keeper = sorted([current, *duplicates], key=_score, reverse=True)[0]
-    keeper_name = keeper.get("name") or keeper.get("id") or ""
-    if keeper_name and keeper_name != cur_name:
-        try:
-            skills_manager.set_necessity(
-                cur_name,
-                False,
-                [keeper_name],
-                f"Lower-priority duplicate of {keeper_name}",
-                owner=owner,
-            )
-        except Exception:
-            pass
-        return keeper_name
-    return None
+_skill_duplicate_blocker = _publication.duplicate_blocker
 
 
 def _finalize_audit_batch(skills_manager, results: list[dict], owner, log) -> None:
-    """Draft audited failures, bin duplicate losers, and publish the best copy.
-
-    Binned skills remain on disk for recovery and inspection, but the Skills
-    manager excludes them from retrieval. Only skills actually processed by
-    this audit job are changed here; an unrelated existing skill is never
-    moved just because it resembles an audited one.
-    """
-    import re as _re
-
-    auto_publish, min_conf = _audit_auto_publish_policy(owner)
-    current = [
-        s for s in skills_manager.load(owner=owner)
-        if s.get("source") != "builtin" and s.get("status") != "binned"
-    ]
-    by_name = {s.get("name"): s for s in current if s.get("name")}
-    processed = {str(r.get("skill")) for r in results if r.get("skill")}
-    protected = {
-        str(r.get("skill")) for r in results
-        if r.get("skill") and r.get("result") == "approval_required"
-    }
-
-    def tokens(sk: dict) -> set[str]:
-        text = " ".join([
-            str(sk.get("name") or ""), str(sk.get("description") or ""),
-            str(sk.get("when_to_use") or ""), " ".join(sk.get("procedure") or []),
-            " ".join(sk.get("tags") or []),
-        ]).lower()
-        text = _re.sub(r"-\d+\b", "", text)
-        return {
-            t for t in _re.split(r"[^a-z0-9]+", text)
-            if len(t) > 2 and t not in {"the", "and", "with", "for", "from", "using"}
-        }
-
-    def similar(a: dict, b: dict) -> float:
-        left, right = tokens(a), tokens(b)
-        return len(left & right) / max(1, len(left | right)) if left and right else 0.0
-
-    def base(name: str) -> str:
-        return _re.sub(r"-\d+$", "", str(name or ""))
-
-    def score(sk: dict) -> float:
-        try:
-            confidence = float(sk.get("confidence") or 0)
-        except (TypeError, ValueError):
-            confidence = 0.0
-        return (
-            (100000 if sk.get("status") == "published" else 0)
-            + int(sk.get("uses") or 0) * 100
-            + round(confidence * 100)
-            + (-5 if sk.get("audit_by_teacher") else 0)
-            - len(str(sk.get("name") or "")) / 1000
-        )
-
-    # Anything that does not clear the configured policy stays a draft. Drafts
-    # are excluded from retrieval/injection by SkillsManager.index_for().
-    for name in processed - protected:
-        skill = by_name.get(name)
-        if not skill:
-            continue
-        verdict = str(skill.get("audit_verdict") or "").lower()
-        try:
-            confidence = float(skill.get("confidence") or 0)
-        except (TypeError, ValueError):
-            confidence = 0.0
-        if verdict in {"needs_work", "fail"} or (
-            verdict == "pass" and confidence < min_conf
-        ):
-            try:
-                skills_manager.update_skill(name, {"status": "draft"}, owner=owner)
-                log(f"{name}: kept as draft after audit")
-            except Exception:
-                logger.warning("Could not bin audited skill %s", name, exc_info=True)
-
-    # Build the same connected duplicate groups shown by the UI.
-    parent = {s["name"]: s["name"] for s in current}
-
-    def find(name: str) -> str:
-        while parent[name] != name:
-            parent[name] = parent[parent[name]]
-            name = parent[name]
-        return name
-
-    def unite(left: str, right: str) -> None:
-        left, right = find(left), find(right)
-        if left != right:
-            parent[right] = left
-
-    for index, left in enumerate(current):
-        for right in current[index + 1:]:
-            if base(left["name"]) == base(right["name"]) or similar(left, right) >= 0.38:
-                unite(left["name"], right["name"])
-    groups: dict[str, list[dict]] = {}
-    for skill in current:
-        groups.setdefault(find(skill["name"]), []).append(skill)
-
-    for group in groups.values():
-        if len(group) < 2:
-            continue
-        passing = []
-        for skill in group:
-            if skill["name"] not in processed or skill["name"] in protected:
-                continue
-            if str(skill.get("audit_verdict") or "").lower() != "pass":
-                continue
-            try:
-                confidence = float(skill.get("confidence") or 0)
-            except (TypeError, ValueError):
-                confidence = 0.0
-            if confidence >= min_conf:
-                passing.append(skill)
-        if not passing:
-            continue
-        keeper = max(passing, key=score)
-        if auto_publish:
-            try:
-                skills_manager.update_skill(keeper["name"], {"status": "published"}, owner=owner)
-                log(f"{keeper['name']}: auto-approved as best passing duplicate")
-            except Exception:
-                logger.warning("Could not auto-approve skill %s", keeper["name"], exc_info=True)
-        for skill in group:
-            name = skill["name"]
-            if name == keeper["name"] or name not in processed or name in protected:
-                continue
-            try:
-                skills_manager.update_skill(name, {"status": "binned"}, owner=owner)
-                log(f"{name}: moved to bin as duplicate of {keeper['name']}")
-            except Exception:
-                logger.warning("Could not bin duplicate skill %s", name, exc_info=True)
-
-
-def _audit_flag_text(*parts) -> str:
-    text_parts = []
-    for part in parts:
-        if isinstance(part, dict):
-            text_parts.extend(str(v or "") for v in part.values())
-        elif isinstance(part, (list, tuple, set)):
-            text_parts.extend(str(v or "") for v in part)
-        else:
-            text_parts.append(str(part or ""))
-    return " ".join(text_parts).lower()
-
-
-def _audit_utility_blocker(skill: Optional[dict], necessity: Optional[dict],
-                           verdict_data: Optional[dict]) -> Optional[str]:
-    """Return a short reason when a passing skill still should stay draft.
-
-    Broad/generic wording is not a blocker by itself. The blocker is whether
-    the skill failed to improve the agent versus a no-skill baseline, or whether
-    it duplicates another skill.
-    """
-    generic_re = re.compile(
-        r"\b(duplicat\w*|redundan\w*|overlap\w*|same skill|same procedure)\b",
-        re.I,
+    return _publication.finalize_batch(
+        skills_manager, results, owner, log, deps=_audit_dependencies(),
     )
-    if isinstance(necessity, dict):
-        reason = str(necessity.get("reason") or "")
-        if necessity.get("necessary") is False and generic_re.search(reason):
-            return reason or "Duplicate or redundant skill"
 
-    if isinstance(verdict_data, dict):
-        baseline_verdict = str(verdict_data.get("baseline_verdict") or "unknown").lower()
-        try:
-            usefulness = float(verdict_data.get("usefulness", 0.0) or 0.0)
-        except (TypeError, ValueError):
-            usefulness = 0.0
-        try:
-            saved_turns = int(verdict_data.get("saved_turns", 0) or 0)
-        except (TypeError, ValueError):
-            saved_turns = 0
-        try:
-            saved_tool_calls = int(verdict_data.get("saved_tool_calls", 0) or 0)
-        except (TypeError, ValueError):
-            saved_tool_calls = 0
-        if baseline_verdict == "worse":
-            return "Skill performed worse than the no-skill baseline"
-        verdict_text = _audit_flag_text(
-            verdict_data.get("summary"),
-            verdict_data.get("issues") or [],
-        )
-        if generic_re.search(verdict_text):
-            return "Audit flagged the skill as duplicate or redundant"
-    return None
+
+_audit_flag_text = _publication.audit_flag_text
+
+
+_audit_utility_blocker = _publication.utility_blocker
 
 
 def _audit_finalize_status(skills_manager, name: str, owner, verdict: str,
                            confidence: Optional[float], necessity: Optional[dict] = None,
                            verdict_data: Optional[dict] = None) -> str:
-    """Apply the user's audit publishing policy.
-
-    Audit is the final pass: skills that pass at/above the threshold are
-    published; failing or unnecessary/redundant skills are returned to draft.
-    Inconclusive runs preserve the existing state because they provide no
-    evidence either way. The completed batch moves duplicate losers to the bin.
-    """
-    auto_publish, min_conf = _audit_auto_publish_policy(owner)
-    necessary = True
-    current = next((s for s in skills_manager.load(owner=owner) if s.get("name") == name), None)
-    if verdict in {"inconclusive", "unknown"}:
-        return (current or {}).get("status") or "draft"
-    utility_reason = _audit_utility_blocker(current, necessity, verdict_data)
-    if (
-        isinstance(necessity, dict)
-        and necessity.get("necessary") is False
-        and necessity.get("redundant_with")
-    ):
-        necessary = False
-    if utility_reason:
-        necessary = False
-        try:
-            skills_manager.set_necessity(name, False, [], utility_reason, owner=owner)
-        except Exception:
-            pass
-    duplicate_of = _skill_duplicate_blocker(skills_manager, name, owner) if verdict == "pass" else None
-    if duplicate_of:
-        necessary = False
-    c = float(confidence or 0.0)
-    status = "published" if (auto_publish and necessary and verdict == "pass" and c >= min_conf) else "draft"
-    try:
-        skills_manager.update_skill(name, {"status": status}, owner=owner)
-    except Exception:
-        pass
-    return status
+    return _publication.finalize_status(
+        skills_manager, name, owner, verdict, confidence, necessity, verdict_data,
+        deps=_audit_dependencies(),
+    )
 
 
-def _apply_skill_md(skills_manager, name: str, md: str, owner) -> bool:
-    """Parse + persist an edited SKILL.md. Returns True on success."""
-    try:
-        from services.memory.skill_format import Skill, slugify
-        sk = Skill.from_markdown(md)
-        # Pin the identity: the audit's fixer is now allowed to edit frontmatter
-        # (tags/category/when_to_use/description), but it must NEVER rename the
-        # skill — a changed `name` would move the dir and orphan the usage/audit
-        # sidecar entries that the caller keeps writing under the original name.
-        sk.name = name
-        return bool(skills_manager.update_skill(name, {
-            "name": sk.name, "description": sk.description, "version": sk.version,
-            "category": sk.category, "tags": sk.tags, "platforms": sk.platforms,
-            "requires_toolsets": sk.requires_toolsets, "fallback_for_toolsets": sk.fallback_for_toolsets,
-            "status": sk.status, "confidence": sk.confidence, "source": sk.source,
-            "teacher_model": sk.teacher_model, "owner": sk.owner or owner,
-            "when_to_use": sk.when_to_use, "procedure": sk.procedure,
-            "pitfalls": sk.pitfalls, "verification": sk.verification, "body_extra": sk.body_extra,
-        }, owner=owner))
-    except Exception as e:
-        logger.warning(f"Audit: could not save edited skill {name}: {e}")
-        return False
+_apply_skill_md = _publication.apply_markdown
 
 
-class SkillAuditUnavailable(RuntimeError):
-    """The test infrastructure failed; this is not evidence about a skill."""
+SkillAuditUnavailable = _agent_runner.SkillAuditUnavailable
 
 
 async def _run_skill_audit_arm(messages: list[dict], url, model, headers, owner,
                                workload: str = "foreground") -> tuple[str, dict, Optional[dict]]:
-    """Run one audit arm in the agent loop; return transcript, stats, approval."""
-    import json as _json
-    from src.agent_loop import stream_agent_loop
-    from src.agent_runtime.authority import RequestAuthority, active_request_authority
-    transcript = []
-    approval_required = None
-    stats = {"turns": 0, "tool_calls": 0}
-    try:
-        # max_tokens explicitly set: passing 0 lets some upstreams (Ollama,
-        # OpenAI-compat) generate an empty completion, which manifested as
-        # the skill test returning nothing while chat (which carries its
-        # preset's max_tokens) worked. 4096 matches the chat default.
-        # aclosing: stopping for an approval leaves this loop early (#6635).
-        async with aclosing(stream_agent_loop(
-            url, model, messages, headers=headers,
-            temperature=0.3, max_tokens=4096, max_rounds=8,
-            owner=owner, workload=workload, suppress_skills=True,
-            request_authority=(active_request_authority() or RequestAuthority.empty(owner=owner)),
-        )) as stream:
-            async for chunk in stream:
-                # Streams can include an SSE event line before the data line,
-                # notably `event: error`. Do not silently discard those failures.
-                payload = next((line[6:] for line in chunk.splitlines() if line.startswith("data: ")), None)
-                if payload is None or payload == "[DONE]":
-                    continue
-                try:
-                    d = _json.loads(payload)
-                except Exception:
-                    continue
-                if d.get("error") or d.get("type") == "error":
-                    raise SkillAuditUnavailable(str(d.get("error") or d.get("message") or "Audit stream failed"))
-                if d.get("delta"):
-                    transcript.append(d["delta"])
-                elif d.get("type") == "tool_start":
-                    stats["tool_calls"] += 1
-                    transcript.append(f"\n[tool {d.get('tool')}] {str(d.get('command') or d.get('args') or '')[:300]}\n")
-                elif d.get("type") == "tool_output":
-                    transcript.append(f"[output] {str(d.get('output') or '')[:600]}\n")
-                    approval = d.get("ask_user")
-                    if (
-                        isinstance(approval, dict)
-                        and approval.get("kind") == "tool_approval"
-                    ):
-                        approval_required = approval
-                        break
-                elif d.get("type") == "agent_step":
-                    try:
-                        stats["turns"] = max(stats["turns"], int(d.get("round") or 0))
-                    except (TypeError, ValueError):
-                        pass
-                    transcript.append(f"\n--- round {d.get('round')} ---\n")
-                elif d.get("type") == "metrics":
-                    data = d.get("data") or {}
-                    try:
-                        stats["turns"] = max(stats["turns"], int(data.get("agent_rounds") or 0))
-                    except (TypeError, ValueError):
-                        pass
-                    try:
-                        stats["tool_calls"] = max(stats["tool_calls"], int(data.get("tool_calls") or 0))
-                    except (TypeError, ValueError):
-                        pass
-    except SkillAuditUnavailable:
-        raise
-    except Exception as e:
-        raise SkillAuditUnavailable(str(e)) from e
-    return "".join(transcript), stats, approval_required
+    return await _agent_runner.run_audit_arm(messages, url, model, headers, owner, workload)
 
 
 async def _run_skill_test_once(md: str, task: str, url, model, headers, owner,
                                workload: str = "foreground") -> tuple:
-    """Run the skill once in the agent loop; return (transcript, verdict)."""
-    messages = _skill_test_messages(md, task)
-    text, stats, approval_required = await _run_skill_audit_arm(
-        messages, url, model, headers, owner, workload=workload,
+    return await _agent_runner.run_test_once(
+        md, task, url, model, headers, owner, workload, deps=_audit_dependencies(),
     )
-    if approval_required is not None:
-        # Unattended audits have no authority to approve and no UI that could
-        # resume this record. Destructively deny it now instead of leaving a
-        # reusable opaque grant pending until TTL/cap eviction.
-        try:
-            from src.tool_approvals import tool_approval_store
-            tool_approval_store.consume(
-                approval_required.get("approval_id"),
-                decision="deny",
-                owner=owner,
-                session_id=None,
-            )
-        except Exception:
-            logger.debug("Could not retire unattended skill approval", exc_info=True)
-        return text, {
-            "verdict": "inconclusive",
-            "confidence": 1.0,
-            "summary": (
-                "This automated audit reached an exact action that requires "
-                "a human approval; no action was executed."
-            ),
-            "issues": [
-                "Run this skill's manual test and review the sealed action."
-            ],
-            "approval_required": True,
-        }
-    verdict = await _eval_skill_run(
-        md,
-        task,
-        text,
-        url,
-        model,
-        headers,
-        skill_stats=stats,
-        workload=workload,
-        owner=owner,
-    )
-    return text, verdict
 
 
 async def _improve_skill_md(skill_md: str, verdict: dict, transcript: str, url, model, headers,
                             workload: str = "foreground", owner: Optional[str] = None):
-    """Have a model rewrite SKILL.md to fix the reviewer's issues. Returns the
-    corrected markdown, or None if it couldn't produce a usable change."""
-    import re as _re
-    from src.llm_core import llm_call_async
-    issues = "\n".join("- " + str(i) for i in (verdict.get("issues") or []))
-    sys_prompt = (
-        "You are improving a reusable AI SKILL written in Markdown (frontmatter + body). "
-        "A QA reviewer found problems after a test run. Rewrite the SKILL.md to fix them: "
-        "make vague steps concrete, correct or remove references to tools that don't exist, "
-        "ensure the procedure is reproducible. "
-        "Keep the `name` field EXACTLY as-is (it is the skill's identity / filename). You MAY "
-        "correct the OTHER frontmatter — tags, category, when_to_use, description — when the "
-        "reviewer flagged them (issues prefixed 'metadata:') or they don't match the body; keep "
-        "retrieval metadata narrow: remove broad tags that would over-select the skill, and make "
-        "`when_to_use` say when NOT to use the skill if adjacent tasks are easy to confuse. Keep "
-        "valid frontmatter structure. Do NOT invent capabilities the agent lacks. Reason in "
-        "<think></think> first if needed, then output ONLY the full corrected SKILL.md (no "
-        "fences, no commentary)."
+    return await _evaluation.improve_markdown(
+        skill_md, verdict, transcript, url, model, headers, workload, owner,
+        _effort_for_call=effort_for_call,
     )
-    user_msg = (
-        f"=== CURRENT SKILL.md ===\n{skill_md}\n\n"
-        f"=== REVIEWER VERDICT ===\n{verdict.get('summary', '')}\nIssues:\n{issues}\n\n"
-        f"=== TEST TRANSCRIPT ===\n{(transcript or '')[:6000]}"
-    )
-    try:
-        raw = await llm_call_async(url, model,
-                                   [{"role": "system", "content": sys_prompt},
-                                    {"role": "user", "content": user_msg}],
-                                   temperature=0.2, max_tokens=16384, headers=headers, timeout=180,
-                                   workload=workload,
-                                   reasoning_effort=effort_for_call(url, model, owner))
-    except Exception as e:
-        logger.warning(f"Audit: improve call failed: {e}")
-        return None
-    text = strip_closed_think_blocks(raw or '')
-    text = _re.sub(r'<think(?:ing)?>[\s\S]*$', '', text, flags=_re.I)
-    text = _re.sub(r'</think(?:ing)?>', '', text, flags=_re.I).strip()
-    if text.startswith("```"):
-        text = text.split("\n", 1)[-1].rsplit("```", 1)[0].strip()
-    # Some reasoning models still prepend analysis or echo the old skill before
-    # the final corrected document. Keep only the last complete-looking
-    # frontmatter document so reviewer prose never gets persisted into SKILL.md.
-    starts = list(_re.finditer(r'(?m)^---\s*\n(?=[\s\S]*?^name\s*:)', text))
-    if starts:
-        text = text[starts[-1].start():].strip()
-    return text or None
 
 
 async def _audit_one_skill(skills_manager, skill, url, model, headers,
                            teacher, owner, log, workload: str = "foreground") -> dict:
-    """Test → judge → self-edit+retry → (teacher edit+retry) → flag. Never deletes;
-    a skill the teacher still can't fix is demoted to draft for manual review.
-    `teacher` is (url, model, headers) or None. `log(msg)` records progress."""
-    name = skill.get("name")
-
-    # Reflect the audit outcome in the skill's confidence so the main list
-    # updates: a clean pass earns high confidence; a pass that needed fixing
-    # earns a bit less; a skill that still fails is marked low.
-    def _set_conf(c):
-        try:
-            skills_manager.update_skill(name, {"confidence": c}, owner=owner)
-        except Exception:
-            pass
-
-    md = skills_manager.read_skill_md(name, owner=owner)
-    if not md:
-        log(f"{name}: no source — skipped")
-        return {"skill": name, "result": "skipped"}
-
-    # Cheap deterministic cleanup first. If this is an obvious lower-priority
-    # duplicate, do not spend LLM turns on necessity, retrieval precision,
-    # skill-vs-baseline testing, self-edit, or teacher escalation.
-    duplicate_of = _skill_duplicate_blocker(skills_manager, name, owner)
-    if duplicate_of:
-        reason = f"Lower-priority duplicate of {duplicate_of}"
-        try:
-            skills_manager.update_skill(name, {"status": "draft", "confidence": 0.35}, owner=owner)
-            skills_manager.set_audit(name, "skipped", by_teacher=False, worker_model=model, owner=owner)
-            skills_manager.set_necessity(name, False, [duplicate_of], reason, owner=owner)
-        except Exception:
-            pass
-        log(f"{name}: draft — skipped audit ({reason[:100]})")
-        return {"skill": name, "result": "skipped_duplicate", "reason": reason, "confidence": 0.35, "status": "draft"}
-
-    # Advisory necessity/redundancy check — runs once, independent of the test
-    # outcome, and only records a flag the UI surfaces (never deletes/demotes).
-    others = []
-    nec = None
-    try:
-        # Only compare against skills the SAME owner can see, so the necessity
-        # judge never sees (or flags "redundant_with") another user's skills.
-        sk_owner = skill.get("owner")
-        others = [
-            {"name": s.get("name"), "description": s.get("description", "")}
-            for s in skills_manager.load(owner=owner)
-            if s.get("name") and s.get("name") != name
-            and (not sk_owner or not s.get("owner") or s.get("owner") == sk_owner)
-        ]
-        nec = await _eval_skill_necessity(
-            md, others, url, model, headers, workload=workload,
-            owner=owner,
-        )
-        if nec is not None:
-            skills_manager.set_necessity(name, nec.get("necessary", True),
-                                         nec.get("redundant_with"), nec.get("reason"),
-                                         owner=owner)
-            if not nec.get("necessary", True):
-                log(f"{name}: possibly unnecessary — {nec.get('reason', '')[:80]}")
-    except Exception as e:
-        log(f"{name}: necessity check skipped — {e}")
-
-    # Retrieval precision check: if broad tags/trigger text would make this
-    # narrow skill over-inject, fix only metadata before the functional test.
-    try:
-        if _should_check_retrieval_precision(skill):
-            rp = await _eval_skill_retrieval_precision(
-                md, others, url, model, headers, workload=workload,
-                owner=owner,
-            )
-            if rp and not rp.get("ok"):
-                issues = rp.get("issues") or ["metadata: retrieval: narrow tags and when_to_use to the intended trigger"]
-                log(f"{name}: narrowing retrieval metadata — {(rp.get('summary') or issues[0])[:80]}")
-                fixed = await _improve_skill_md(md, {
-                    "verdict": "pass",
-                    "confidence": 1.0,
-                    "summary": rp.get("summary") or "Retrieval metadata is too broad.",
-                    "issues": issues,
-                }, "Retrieval audit only: the procedure may work, but matching metadata is too broad.",
-                    url, model, headers, workload=workload, owner=owner)
-                if fixed and fixed.strip() != md.strip() and _apply_skill_md(skills_manager, name, fixed, owner):
-                    md = fixed
-                    refreshed = next((s for s in skills_manager.load(owner=owner) if s.get("name") == name), None)
-                    if refreshed:
-                        skill = refreshed
-    except Exception as e:
-        log(f"{name}: retrieval precision check skipped — {e}")
-
-    task = _skill_test_task(skill)
-    log(f"{name}: testing…")
-    skill_messages = _skill_test_messages(md, task)
-    transcript, skill_stats, approval_required = await _run_skill_audit_arm(
-        skill_messages,
-        url,
-        model,
-        headers,
-        owner,
-        workload=workload,
+    return await _audit_workflow.audit_one_skill(
+        skills_manager, skill, url, model, headers, teacher, owner, log, workload,
+        deps=_audit_dependencies(),
     )
-    if approval_required is not None:
-        try:
-            from src.tool_approvals import tool_approval_store
-            tool_approval_store.consume(
-                approval_required.get("approval_id"),
-                decision="deny",
-                owner=owner,
-                session_id=None,
-            )
-        except Exception:
-            logger.debug("Could not retire unattended skill approval", exc_info=True)
-        verdict = {
-            "verdict": "inconclusive",
-            "confidence": 1.0,
-            "summary": (
-                "This automated audit reached an exact action that requires "
-                "a human approval; no action was executed."
-            ),
-            "issues": [
-                "Run this skill's manual test and review the sealed action."
-            ],
-            "approval_required": True,
-        }
-    else:
-        baseline_task = task
-        log(f"{name}: running no-skill baseline…")
-        baseline_transcript, baseline_stats, baseline_approval = await _run_skill_audit_arm(
-            _skill_baseline_messages(baseline_task),
-            url,
-            model,
-            headers,
-            owner,
-            workload=workload,
-        )
-        if baseline_approval is not None:
-            try:
-                from src.tool_approvals import tool_approval_store
-                tool_approval_store.consume(
-                    baseline_approval.get("approval_id"),
-                    decision="deny",
-                    owner=owner,
-                    session_id=None,
-                )
-            except Exception:
-                logger.debug("Could not retire unattended baseline approval", exc_info=True)
-        verdict = await _eval_skill_run(
-            md,
-            task,
-            transcript,
-            url,
-            model,
-            headers,
-            baseline_transcript=baseline_transcript,
-            skill_stats=skill_stats,
-            baseline_stats=baseline_stats,
-            workload=workload,
-            owner=owner,
-        )
-    v = verdict.get("verdict")
-    log(f"{name}: verdict = {v} ({verdict.get('summary', '')[:80]})")
-    if verdict.get("approval_required"):
-        # An unattended audit is not authority for an action influenced by the
-        # skill under test. Preserve the skill's current publication/confidence
-        # state and route the exact action to the manual test UI instead of
-        # letting a safety pause demote, rewrite, or auto-publish the skill.
-        skills_manager.set_audit(
-            name,
-            "inconclusive",
-            by_teacher=False,
-            worker_model=model,
-            owner=owner,
-            audit_summary=verdict.get("summary") or "The test requires approval for an external action.",
-        )
-        status = skill.get("status") or "draft"
-        log(f"{name}: {status} unchanged — exact action needs manual approval")
-        return {
-            "skill": name,
-            "result": "approval_required",
-            "verdict": verdict,
-            "status": status,
-        }
-    if v == "pass":
-        # Procedure works. If the reviewer still flagged metadata (tags/category/
-        # when_to_use/description), do ONE fixer pass to correct the frontmatter
-        # without re-testing — a metadata-only fix can't break a passing run.
-        meta_issues = [i for i in (verdict.get("issues") or []) if str(i).lower().lstrip().startswith("metadata:")]
-        if meta_issues:
-            log(f"{name}: pass, but fixing {len(meta_issues)} metadata issue(s)…")
-            fixed = await _improve_skill_md(
-                md, verdict, transcript, url, model, headers, workload=workload,
-                owner=owner,
-            )
-            if fixed and fixed.strip() != md.strip():
-                _apply_skill_md(skills_manager, name, fixed, owner)
-        _set_conf(0.95)
-        skills_manager.set_audit(
-            name,
-            "pass",
-            by_teacher=False,
-            worker_model=model,
-            owner=owner,
-            **_verdict_efficiency(verdict),
-        )
-        refreshed = next((s for s in skills_manager.load(owner=owner) if s.get("name") == name), None)
-        status = _audit_finalize_status(skills_manager, name, owner, "pass", 0.95, (refreshed or {}).get("necessity"), verdict)
-        log(f"{name}: {status} — confidence 95%")
-        return {"skill": name, "result": "pass", "verdict": verdict, "confidence": 0.95, "status": status}
-    if v in ("unknown", "inconclusive"):
-        skills_manager.set_audit(
-            name,
-            "inconclusive",
-            by_teacher=False,
-            worker_model=model,
-            owner=owner,
-            **_verdict_efficiency(verdict),
-        )
-        status = _audit_finalize_status(skills_manager, name, owner, "inconclusive", skill.get("confidence") or 0.0, skill.get("necessity"))
-        log(f"{name}: {status} — inconclusive")
-        return {"skill": name, "result": "inconclusive", "verdict": verdict, "status": status}
-
-    # Self-edit + retry.
-    log(f"{name}: self-editing to fix issues…")
-    new_md = await _improve_skill_md(
-        md, verdict, transcript, url, model, headers, workload=workload,
-        owner=owner,
-    )
-    if new_md and new_md.strip() != md.strip() and _apply_skill_md(skills_manager, name, new_md, owner):
-        md = new_md
-        transcript, verdict = await _run_skill_test_once(
-            md, task, url, model, headers, owner, workload=workload,
-        )
-        v = verdict.get("verdict")
-        log(f"{name}: retry (self) = {v}")
-        if v == "pass":
-            _set_conf(0.85)
-            skills_manager.set_audit(
-                name,
-                "pass",
-                by_teacher=False,
-                worker_model=model,
-                owner=owner,
-                **_verdict_efficiency(verdict),
-            )
-            refreshed = next((s for s in skills_manager.load(owner=owner) if s.get("name") == name), None)
-            status = _audit_finalize_status(skills_manager, name, owner, "pass", 0.85, (refreshed or {}).get("necessity"), verdict)
-            log(f"{name}: {status} — confidence 85% after self-edit")
-            return {"skill": name, "result": "pass_after_self_edit", "verdict": verdict, "confidence": 0.85, "status": status}
-
-    # Teacher escalation (if a distinct teacher model is configured). The
-    # teacher only REWRITES the skill — it does NOT run the test. The point is
-    # to verify the regular (student) model can now succeed with the teacher's
-    # improved procedure, so the retry runs on the worker model, not the teacher.
-    teacher_ran = False
-    if teacher and teacher[0] and teacher[1] and (teacher[1] != model or teacher[0] != url):
-        teacher_ran = True
-        t_url, t_model, t_headers = teacher
-        log(f"{name}: teacher {t_model} rewriting the skill…")
-        t_md = await _improve_skill_md(
-            md, verdict, transcript, t_url, t_model, t_headers, workload=workload,
-            owner=owner,
-        )
-        if t_md and t_md.strip() != md.strip() and _apply_skill_md(skills_manager, name, t_md, owner):
-            md = t_md
-        # Re-test with the STUDENT model (the model the skill runs under in use).
-            transcript, verdict = await _run_skill_test_once(
-                md, task, url, model, headers, owner, workload=workload,
-            )
-        v = verdict.get("verdict")
-        log(f"{name}: retry on student after teacher rewrite = {v}")
-        if v == "pass":
-            _set_conf(0.8)
-            skills_manager.set_audit(
-                name,
-                "pass",
-                by_teacher=True,
-                worker_model=model,
-                teacher_model=t_model,
-                owner=owner,
-                **_verdict_efficiency(verdict),
-            )
-            refreshed = next((s for s in skills_manager.load(owner=owner) if s.get("name") == name), None)
-            status = _audit_finalize_status(skills_manager, name, owner, "pass", 0.8, (refreshed or {}).get("necessity"), verdict)
-            log(f"{name}: {status} — confidence 80% after teacher rewrite")
-            return {"skill": name, "result": "pass_after_teacher", "verdict": verdict, "confidence": 0.8, "status": status}
-
-    # Still failing → demote to draft + low confidence + flag (do NOT delete).
-    try:
-        skills_manager.update_skill(name, {"status": "draft", "confidence": 0.35}, owner=owner)
-    except Exception:
-        pass
-    skills_manager.set_audit(
-        name, v or "fail", by_teacher=teacher_ran,
-        worker_model=model,
-        teacher_model=(teacher[1] if teacher_ran and teacher else ""),
-        owner=owner,
-        **_verdict_efficiency(verdict),
-    )
-    log(f"{name}: flagged — confidence lowered, kept as draft for manual review")
-    return {"skill": name, "result": "flagged", "verdict": verdict, "confidence": 0.35}
 
 
 async def _run_audit_all_job(key, skills_manager, names, url, model, headers, teacher, owner,
                              workload: str = "foreground"):
-    """Background: audit each named skill in sequence, recording progress."""
-    import asyncio as _asyncio
-    import time as _time
-
-    job = _skill_audit_jobs.get(key)
-    if job is None:
-        return
-
-    def log(msg):
-        job["log"].append(msg)
-        if len(job["log"]) > 1000:
-            del job["log"][0:len(job["log"]) - 1000]
-
-    cancelled = False
-    try:
-        for nm in names:
-            if job.get("cancel"):
-                cancelled = True
-                log("(cancelled)")
-                break
-            job["current"] = nm
-            skills = skills_manager.load(owner=owner)
-            sk = next((s for s in skills if s.get("name") == nm), None)
-            if not sk:
-                continue
-            try:
-                res = await _audit_one_skill(
-                    skills_manager, sk, url, model, headers, teacher, owner, log,
-                    workload=workload,
-                )
-            except _asyncio.CancelledError:
-                cancelled = True
-                job["cancel"] = True
-                log("(cancelled)")
-                raise
-            except SkillAuditUnavailable as e:
-                job["unavailable"] = str(e)
-                log(f"Audit paused: {e}. Skill verdicts unchanged; retry when the model is available.")
-                break
-            except Exception as e:
-                log(f"{nm}: error — {e}")
-                res = {"skill": nm, "result": "error"}
-                skills_manager.set_audit(nm, "inconclusive", worker_model=model, owner=owner)
-            try:
-                refreshed = next((s for s in skills_manager.load(owner=owner) if s.get("name") == nm), None)
-                if refreshed:
-                    res["skill_state"] = {
-                        "name": refreshed.get("name"),
-                        "status": refreshed.get("status"),
-                        "confidence": refreshed.get("confidence"),
-                        "audit_verdict": refreshed.get("audit_verdict"),
-                        "audit_by_teacher": refreshed.get("audit_by_teacher"),
-                        "audit_worker_model": refreshed.get("audit_worker_model"),
-                        "audit_teacher_model": refreshed.get("audit_teacher_model"),
-                        "audited_at": refreshed.get("audited_at"),
-                        "saved_turns": refreshed.get("saved_turns"),
-                        "saved_tool_calls": refreshed.get("saved_tool_calls"),
-                        "baseline_verdict": refreshed.get("baseline_verdict"),
-                        "usefulness": refreshed.get("usefulness"),
-                        "necessity": refreshed.get("necessity"),
-                    }
-            except Exception:
-                pass
-            job["results"].append(res)
-            job["done"] = len(job["results"])
-    except _asyncio.CancelledError:
-        cancelled = True
-    finally:
-        if not cancelled and not job.get("cancel") and not job.get("unavailable"):
-            try:
-                _finalize_audit_batch(skills_manager, job.get("results") or [], owner, log)
-            except Exception:
-                logger.warning("Could not finalize skills audit batch", exc_info=True)
-        job["current"] = None
-        job["status"] = "cancelled" if cancelled or job.get("cancel") else "error" if job.get("unavailable") else "done"
-        job["finished"] = _time.time()
-        job.pop("task", None)
+    return await _audit_workflow.run_audit_batch(
+        key, skills_manager, names, url, model, headers, teacher, owner, workload,
+        deps=_audit_dependencies(),
+    )
 
 
 def _resolve_audit_models(owner=None, model_spec=None, endpoint_url=None):
-    """Resolve (url, model, headers, teacher) for an audit run from Settings.
-
-    Worker = Utility model (falling back to Default, normalized to a served
-    model id); teacher = the optional Settings → Teacher Model config. Shared
-    by the manual /audit-all route and scheduled/event audits. Raises
-    ValueError if no worker model.
-    """
-    from src.endpoint_resolver import resolve_endpoint, resolve_utility_fallback_candidates
-    if model_spec and endpoint_url:
-        # Scheduled tasks store the endpoint URL and model separately. Resolve
-        # the endpoint directly so an explicit task choice cannot be replaced
-        # by the global Utility setting.
-        from src.endpoint_resolver import build_headers, resolve_endpoint_runtime
-        from src.database import ModelEndpoint, SessionLocal
-        from src.endpoint_resolver import normalize_base, same_endpoint_base
-        from src.auth_helpers import owner_filter
-        url = endpoint_url
-        model = model_spec
-        headers = {}
-        db = SessionLocal()
-        try:
-            query = db.query(ModelEndpoint).filter(ModelEndpoint.is_enabled == True)
-            for ep in owner_filter(query, ModelEndpoint, owner).all():
-                base = normalize_base(getattr(ep, "base_url", "") or "")
-                if same_endpoint_base(url, base):
-                    runtime_base, api_key = resolve_endpoint_runtime(ep, owner=owner)
-                    headers = build_headers(api_key, runtime_base or base)
-                    break
-        finally:
-            db.close()
-    elif model_spec:
-        from src.ai_interaction import _resolve_model
-        url, model, headers = _resolve_model(str(model_spec), owner=owner)
-    else:
-        url, model, headers = resolve_endpoint("utility", owner=owner)
-    if not url or not model:
-        # Utility fallbacks are an explicit part of the user's model
-        # configuration. Audits must use the same chain as other background
-        # work instead of treating an empty primary Utility slot as fatal.
-        for fallback_url, fallback_model, fallback_headers in resolve_utility_fallback_candidates(owner=owner):
-            url, model, headers = fallback_url, fallback_model, fallback_headers
-            break
-    if not url or not model:
-        raise ValueError("No model configured — set a Default or Utility model in Settings.")
-    try:
-        from src.llm_core import list_model_ids
-        import os as _os
-        _avail = list_model_ids(url, headers=headers)
-        if _avail and model not in _avail:
-            _base = _os.path.basename((model or "").rstrip("/"))
-            model = next((a for a in _avail if _os.path.basename(a.rstrip("/")) == _base), None) or _avail[0]
-    except Exception:
-        pass
-
-    teacher = None
-    try:
-        from src.settings import get_setting
-        if get_setting("teacher_enabled", False):
-            spec = (get_setting("teacher_model", "") or "").strip()
-            if spec:
-                from src.ai_interaction import _resolve_model
-                t_url, t_model, t_headers = _resolve_model(spec, owner=owner)
-                if t_url and t_model:
-                    teacher = (t_url, t_model, t_headers)
-    except Exception as e:
-        logger.warning(f"Audit teacher resolve failed: {e}")
-    return url, model, headers, teacher
+    return _model_selection.resolve_audit_models(owner, model_spec, endpoint_url)
 
 
 async def run_scheduled_skill_audit(skills_manager: SkillsManager,
                                     owner: Optional[str] = None,
                                     max_skills: int = 8) -> dict:
-    """Nightly audit pass. Audits the LEAST-recently-audited skills first and
-    caps the batch so it rotates through the library over successive nights
-    instead of re-checking the same ones every run. Reuses the same job store
-    the manual 'Audit all' button uses, so its progress shows in the UI too."""
-    import time as _time
+    return await _audit_workflow.run_scheduled_skill_audit(
+        skills_manager, owner, max_skills, deps=_audit_dependencies(),
+    )
 
-    key = (owner or "",)
-    existing = _skill_audit_jobs.get(key)
-    if existing and existing.get("status") == "running":
-        logger.info("Scheduled skill audit skipped — a run is already active.")
-        return {"status": "running", "skipped": True}
 
-    try:
-        url, model, headers, teacher = _resolve_audit_models(owner=owner)
-    except ValueError as e:
-        logger.info(f"Scheduled skill audit skipped — {e}")
-        return {"status": "skipped", "reason": str(e)}
-
-    from services.memory.skill_lifecycle import automatic_audit_candidates
-    skills = automatic_audit_candidates(skills_manager.load(owner=owner), limit=max_skills)
-    names = [s["name"] for s in skills]
-    if not names:
-        return {"status": "done", "total": 0}
-
-    _skill_audit_jobs[key] = {
-        "status": "running", "scope": "scheduled", "model": model,
-        "teacher": teacher[1] if teacher else None,
-        "total": len(names), "done": 0, "current": None,
-        "results": [], "log": [f"Nightly audit of {len(names)} least-recently-checked skill(s) with {model}"
-                               + (f"; teacher {teacher[1]}" if teacher else "")],
-        "started": _time.time(), "cancel": False,
-    }
-    logger.info(f"Scheduled skill audit starting: {len(names)} skill(s) (owner={owner or 'all'})")
-    await _run_audit_all_job(
-        key, skills_manager, names, url, model, headers, teacher, owner,
-        workload="background",
+def _audit_dependencies() -> AuditDependencies:
+    """Bind current compatibility symbols without shared mutable rebinding."""
+    return AuditDependencies(
+        test_jobs=_skill_test_jobs,
+        audit_jobs=_skill_audit_jobs,
+        test_task=_skill_test_task,
+        test_messages=_skill_test_messages,
+        baseline_messages=_skill_baseline_messages,
+        evaluate_run=_eval_skill_run,
+        evaluate_necessity=_eval_skill_necessity,
+        evaluate_retrieval_precision=_eval_skill_retrieval_precision,
+        should_check_retrieval_precision=_should_check_retrieval_precision,
+        improve_markdown=_improve_skill_md,
+        apply_markdown=_apply_skill_md,
+        duplicate_blocker=_skill_duplicate_blocker,
+        finalize_status=_audit_finalize_status,
+        finalize_batch=_finalize_audit_batch,
+        auto_publish_policy=_audit_auto_publish_policy,
+        utility_blocker=_audit_utility_blocker,
+        verdict_efficiency=_verdict_efficiency,
+        run_test_job=_run_skill_test_job,
+        run_arm=_run_skill_audit_arm,
+        run_test_once=_run_skill_test_once,
+        audit_one=_audit_one_skill,
+        run_batch=_run_audit_all_job,
+        resolve_models=_resolve_audit_models,
     )
-    job = _skill_audit_jobs.get(key, {})
-    return {"status": "done", "total": len(names), "results": job.get("results", [])}
 
 
 def setup_skills_routes(skills_manager: SkillsManager) -> APIRouter:
@@ -2022,8 +595,6 @@ def setup_skills_routes(skills_manager: SkillsManager) -> APIRouter:
         On completion it records the verdict and nudges the skill's confidence
         to match (pass→0.95, needs_work→0.6, fail→0.4; inconclusive/unknown leave
         it untouched). It never changes the skill's published/draft STATUS."""
-        import time as _time
-        import asyncio as _asyncio
         from core.database import SessionLocal
         from src.endpoint_resolver import (
             build_chat_url, build_headers, resolve_endpoint,
@@ -2079,46 +650,14 @@ def setup_skills_routes(skills_manager: SkillsManager) -> APIRouter:
         except Exception as _e:
             logger.warning(f"Skill-test model resolve failed: {_e}")
 
-        key = (user or "", name)
-        previous_job = _skill_test_jobs.get(key) or {}
-        previous_approval = previous_job.get("approval") or {}
-        if previous_approval.get("approval_id"):
-            try:
-                from src.tool_approvals import tool_approval_store
-                tool_approval_store.consume(
-                    previous_approval["approval_id"],
-                    decision="deny",
-                    owner=user,
-                    session_id=None,
-                )
-            except Exception:
-                logger.debug("Could not retire replaced skill approval", exc_info=True)
-        _skill_test_jobs[key] = {
-            "status": "running",
-            "task": task,
-            "model": model,
-            "skill": name,
-            "started": _time.time(),
-            "log": [{"type": "skill_test_start", "task": task, "skill": name, "model": model}],
-            "verdict": None,
-            "_run": {
-                "md": md,
-                "url": url,
-                "model": model,
-                "headers": headers,
-                "owner": user,
-                "request_authority": request_authority,
-            },
-        }
-        _asyncio.create_task(_run_skill_test_job(
-            key, name, md, task, url, model, headers, user, skills_manager,
-            request_authority=request_authority))
-        return {"ok": True, "status": "running", "skill": name, "model": model}
+        return _job_coordinator.start_test_job(
+            name, md, task, url, model, headers, user, skills_manager,
+            request_authority, deps=_audit_dependencies(),
+        )
 
     @router.post("/{skill_id}/test-approval")
     async def approve_skill_test_action(request: Request, skill_id: str):
         """Resume a manual skill test with one exact server-sealed action."""
-        import asyncio as _asyncio
         from src.tool_approvals import tool_approval_store
         from src.agent_runtime.authority import require_user_approval_request
         require_user_approval_request(request)
@@ -2169,74 +708,10 @@ def setup_skills_routes(skills_manager: SkillsManager) -> APIRouter:
 
         if decision == "approve" and exact_approval is None:
             raise HTTPException(409, "This tool approval could not be consumed.")
-        job.pop("approval", None)
-        if decision == "deny":
-            job.pop("_transcript", None)
-            job.pop("_run", None)
-            job["log"].append({
-                "type": "approval_denied",
-                "text": "Exact action denied; the skill test stopped without executing it.",
-            })
-            job["verdict"] = {
-                "verdict": "inconclusive",
-                "confidence": 1.0,
-                "summary": "The test stopped because its exact action was denied.",
-                "issues": [],
-            }
-            job["status"] = "done"
-            return {"ok": True, "status": "done", "decision": "deny"}
-
-        run = job.get("_run") or {}
-        transcript = job.pop("_transcript", [])
-        # stream_agent_loop owns its per-round message list internally. Rebuild
-        # continuation context from the original untrusted skill plus the
-        # accumulated transcript so repeated approvals do not lose earlier
-        # approved results, while keeping every transcript byte tainted.
-        messages = _skill_test_messages(
-            run.get("md", ""),
-            job.get("task", ""),
+        return _job_coordinator.continue_test_job(
+            job, key, name, decision, expected, exact_approval,
+            skills_manager, deps=_audit_dependencies(),
         )
-        if transcript:
-            messages.append(untrusted_context_message(
-                "skill test transcript",
-                "".join(str(item) for item in transcript),
-            ))
-        messages.extend([
-            {
-                "role": "assistant",
-                "content": str(expected.get("question") or "Allow this exact action once?"),
-            },
-            {
-                "role": "user",
-                "content": (
-                    f"Approved the exact {exact_approval.pending.tool_name} "
-                    "action shown above once."
-                ),
-            },
-        ])
-        job["status"] = "running"
-        job["log"].append({
-            "type": "approval_granted",
-            "text": (
-                f"Approved exact {exact_approval.pending.tool_name} action once; "
-                "resuming test."
-            ),
-        })
-        _asyncio.create_task(_run_skill_test_job(
-            key,
-            name,
-            run.get("md", ""),
-            job.get("task", ""),
-            run.get("url"),
-            run.get("model"),
-            run.get("headers"),
-            run.get("owner"),
-            skills_manager,
-            messages=messages,
-            transcript=transcript,
-            exact_approval=exact_approval,
-        ))
-        return {"ok": True, "status": "running", "decision": "approve"}
 
     @router.get("/{skill_id}/test-status")
     async def test_skill_status(request: Request, skill_id: str):
@@ -2245,17 +720,7 @@ def setup_skills_routes(skills_manager: SkillsManager) -> APIRouter:
         skills = skills_manager.load(owner=user)
         match = next((s for s in skills if s.get("name") == skill_id or s.get("id") == skill_id), None)
         name = (match or {}).get("name", skill_id)
-        job = _skill_test_jobs.get((user or "", name))
-        if not job:
-            return {"status": "none"}
-        return {
-            "status": job["status"],
-            "task": job.get("task"),
-            "model": job.get("model"),
-            "log": job.get("log", []),
-            "verdict": job.get("verdict"),
-            "approval": job.get("approval"),
-        }
+        return _job_coordinator.test_status(user, name, deps=_audit_dependencies())
 
     @router.post("/audit-all")
     async def audit_all_skills(request: Request):
@@ -2266,8 +731,6 @@ def setup_skills_routes(skills_manager: SkillsManager) -> APIRouter:
         {scope: 'drafts'|'unchecked'|'all', names?: [...], skip_audited?: bool}. Default 'all'
         means every visible skill, including already-published skills, so audit
         can publish or demote according to the confidence threshold."""
-        import asyncio as _asyncio
-        import time as _time
 
         user = _owner(request)
         body = await request.json() if request.headers.get("content-type", "").startswith("application/json") else {}
@@ -2290,78 +753,23 @@ def setup_skills_routes(skills_manager: SkillsManager) -> APIRouter:
         except ValueError as e:
             raise HTTPException(400, str(e))
 
-        skills = skills_manager.load(owner=user)
-        # Built-ins are tracked, pre-approved application procedures. They do
-        # not consume audit turns and cannot be demoted by an audit result.
-        auditable_skills = [s for s in skills if s.get("source") != "builtin"]
-        by_name = {s.get("name"): s for s in auditable_skills if s.get("name")}
-        if isinstance(requested_names, list):
-            names = []
-            seen = set()
-            for raw in requested_names:
-                nm = str(raw or "").strip()
-                if not nm or nm in seen or nm not in by_name:
-                    continue
-                if scope not in ("all", "selected") and (by_name[nm].get("status") or "draft") == "published":
-                    continue
-                if skip_audited and by_name[nm].get("audit_verdict"):
-                    continue
-                names.append(nm)
-                seen.add(nm)
-            scope = "selected" if requested_names else scope
-        elif scope == "all":
-            names = [
-                s.get("name") for s in auditable_skills
-                if s.get("name") and (not skip_audited or not s.get("audit_verdict"))
-            ]
-        else:
-            scope = "unchecked" if scope == "drafts" else scope
-            names = [
-                s.get("name") for s in auditable_skills
-                if s.get("name")
-                and (s.get("status") or "draft") != "published"
-                and not s.get("audit_verdict")
-            ]
-        if not names:
-            return {"ok": True, "status": "done", "total": 0, "results": [], "log": ["No skills to audit."]}
-
-        _skill_audit_jobs[key] = {
-            "status": "running", "scope": scope, "model": model,
-            "teacher": teacher[1] if teacher else None,
-            "total": len(names), "done": 0, "current": None,
-            "results": [], "log": [f"Auditing {len(names)} skill(s) with {model}" + (f"; teacher {teacher[1]}" if teacher else "")],
-            "started": _time.time(), "cancel": False,
-        }
-        task = _asyncio.create_task(_run_audit_all_job(key, skills_manager, names, url, model, headers, teacher, user))
-        _skill_audit_jobs[key]["task"] = task
-        return {"ok": True, "status": "running", "total": len(names), "model": model}
+        names, scope = _job_coordinator.select_audit_names(
+            skills_manager, user, scope, requested_names, skip_audited,
+        )
+        return _job_coordinator.start_audit_job(
+            key, skills_manager, names, url, model, headers, teacher, user,
+            scope, deps=_audit_dependencies(),
+        )
 
     @router.get("/audit-all/status")
     async def audit_status(request: Request):
         user = _owner(request)
-        job = _skill_audit_jobs.get((user or "",))
-        if not job:
-            return {"status": "none"}
-        return {
-            "status": job["status"], "scope": job.get("scope"),
-            "total": job.get("total", 0), "done": job.get("done", 0),
-            "current": job.get("current"), "model": job.get("model"), "teacher": job.get("teacher"),
-            "results": job.get("results", []), "log": job.get("log", []),
-            "started": job.get("started"), "finished": job.get("finished"),
-        }
+        return _job_coordinator.audit_status(user, deps=_audit_dependencies())
 
     @router.post("/audit-all/cancel")
     async def audit_cancel(request: Request):
         user = _owner(request)
-        job = _skill_audit_jobs.get((user or "",))
-        if job:
-            job["cancel"] = True
-            job["status"] = "cancelled"
-            job["current"] = None
-            task = job.get("task")
-            if task and not task.done():
-                task.cancel()
-        return {"ok": True, "status": "cancelled" if job else "none"}
+        return _job_coordinator.cancel_audit(user, deps=_audit_dependencies())
 
     @router.post("/{skill_id}/markdown")
     async def save_skill_markdown(request: Request, skill_id: str):
diff --git a/services/skills/__init__.py b/services/skills/__init__.py
new file mode 100644
index 000000000..1b6236117
--- /dev/null
+++ b/services/skills/__init__.py
@@ -0,0 +1 @@
+"""Skills domain operations; persistence and lifecycle remain in SkillsManager."""
diff --git a/services/skills/agent_runner.py b/services/skills/agent_runner.py
new file mode 100644
index 000000000..bf81860f1
--- /dev/null
+++ b/services/skills/agent_runner.py
@@ -0,0 +1,308 @@
+"""Agent execution, transcripts and same-task stream cleanup."""
+
+import logging
+from contextlib import aclosing
+from typing import Optional
+
+from .dependencies import AuditDependencies
+
+logger = logging.getLogger(__name__)
+
+_skill_test_jobs: dict = {}
+
+
+class SkillAuditUnavailable(RuntimeError):
+    """The test infrastructure failed; this is not evidence about a skill."""
+
+
+async def run_test_job(
+    key,
+    name,
+    md,
+    task,
+    url,
+    model,
+    headers,
+    owner,
+    skills_manager=None,
+    *,
+    messages=None,
+    transcript=None,
+    exact_approval=None,
+    request_authority=None,
+    deps: AuditDependencies,
+):
+    """Background coroutine: run the skill in an agent loop, capture a condensed
+    log + transcript, then have the judge grade it. Writes into deps.test_jobs."""
+    import json as _json
+    from src.agent_loop import stream_agent_loop
+    from src.agent_runtime.authority import RequestAuthority
+
+    job = deps.test_jobs.get(key)
+    if job is None:
+        return
+    log = job["log"]
+    transcript = transcript if isinstance(transcript, list) else []
+    say_buf = []
+    skill_stats = {"turns": 0, "tool_calls": 0}
+
+    def _flush_say():
+        if say_buf:
+            log.append({"type": "say", "text": "".join(say_buf)})
+            say_buf.clear()
+
+    messages = list(messages) if isinstance(messages, list) else deps.test_messages(md, task)
+    try:
+        # aclosing: pausing for an approval leaves this loop early, and the
+        # stream's ContextVar cleanup must run in this task, not in asyncio's
+        # finalizer (#6635).
+        async with aclosing(stream_agent_loop(
+            url, model, messages, headers=headers,
+            temperature=0.3, max_tokens=0, max_rounds=8, owner=owner,
+            exact_approval=exact_approval,
+            request_authority=(request_authority or (
+                exact_approval.pending.request_authority if exact_approval is not None else None
+            ) or RequestAuthority.empty(owner=owner)),
+        )) as stream:
+            async for chunk in stream:
+                if not chunk.startswith("data: ") or chunk.strip() == "data: [DONE]":
+                    continue
+                try:
+                    d = _json.loads(chunk[6:])
+                except Exception:
+                    continue
+                if d.get("delta"):
+                    say_buf.append(d["delta"]); transcript.append(d["delta"])
+                elif d.get("type") == "tool_start":
+                    _flush_say()
+                    skill_stats["tool_calls"] += 1
+                    cmd = str(d.get("command") or d.get("args") or "")[:300]
+                    log.append({"type": "tool_start", "tool": d.get("tool"), "command": cmd})
+                    transcript.append(f"\n[tool {d.get('tool')}] {cmd}\n")
+                elif d.get("type") == "tool_output":
+                    _flush_say()
+                    out = str(d.get("output") or "")[:600]
+                    tool_log = {"type": "tool_output", "output": out}
+                    approval = d.get("ask_user")
+                    if isinstance(approval, dict):
+                        tool_log["ask_user"] = approval
+                    log.append(tool_log)
+                    transcript.append(f"[output] {out}\n")
+                    if (
+                        isinstance(approval, dict)
+                        and approval.get("kind") == "tool_approval"
+                        and approval.get("approval_id")
+                    ):
+                        # Manual skill tests have their own polling UI instead of a
+                        # chat session. Pause the run and retain only server-side
+                        # continuation state until the same owner approves/denies
+                        # this exact sealed action.
+                        job["status"] = "awaiting_approval"
+                        job["approval"] = approval
+                        job["_transcript"] = transcript
+                        return
+                elif d.get("type") == "agent_step":
+                    _flush_say()
+                    try:
+                        skill_stats["turns"] = max(skill_stats["turns"], int(d.get("round") or 0))
+                    except (TypeError, ValueError):
+                        pass
+                    log.append({"type": "agent_step", "round": d.get("round")})
+                    transcript.append(f"\n--- round {d.get('round')} ---\n")
+                elif d.get("type") == "metrics":
+                    data = d.get("data") or {}
+                    try:
+                        skill_stats["turns"] = max(skill_stats["turns"], int(data.get("agent_rounds") or 0))
+                    except (TypeError, ValueError):
+                        pass
+                    try:
+                        skill_stats["tool_calls"] = max(skill_stats["tool_calls"], int(data.get("tool_calls") or 0))
+                    except (TypeError, ValueError):
+                        pass
+                if len(log) > 600:
+                    del log[0:len(log) - 600]
+        _flush_say()
+    except Exception as e:
+        _flush_say()
+        log.append({"type": "error", "error": str(e)})
+
+    job.pop("approval", None)
+    job.pop("_transcript", None)
+    job.pop("_run", None)
+    log.append({"type": "evaluating"})
+    try:
+        baseline_task = task
+        log.append({"type": "agent_step", "round": "baseline"})
+        baseline_transcript, baseline_stats, baseline_approval = await deps.run_arm(
+            deps.baseline_messages(baseline_task),
+            url,
+            model,
+            headers,
+            owner,
+        )
+        if baseline_approval is not None:
+            try:
+                from src.tool_approvals import tool_approval_store
+                tool_approval_store.consume(
+                    baseline_approval.get("approval_id"),
+                    decision="deny",
+                    owner=owner,
+                    session_id=None,
+                )
+            except Exception:
+                logger.debug("Could not retire manual-test baseline approval", exc_info=True)
+        job["verdict"] = await deps.evaluate_run(
+            md,
+            task,
+            "".join(transcript),
+            url,
+            model,
+            headers,
+            baseline_transcript=baseline_transcript,
+            skill_stats=skill_stats,
+            baseline_stats=baseline_stats,
+            owner=owner,
+        )
+    except Exception as e:
+        job["verdict"] = {"verdict": "unknown", "confidence": 0, "summary": f"Eval failed: {e}", "issues": []}
+    # Record the result so the card shows a 'verified' check (a manual test
+    # never involves the teacher) and nudge the confidence score to match the
+    # verdict — same scale as Audit-all's pass=0.95. inconclusive/unknown leave
+    # the score alone (missing-fixture or parse failures shouldn't punish it).
+    if skills_manager is not None:
+        v = (job["verdict"] or {}).get("verdict") or "unknown"
+        try:
+            skills_manager.set_audit(
+                name,
+                v,
+                by_teacher=False,
+                worker_model=model,
+                owner=owner,
+                **deps.verdict_efficiency(job.get("verdict")),
+            )
+        except Exception:
+            pass
+        conf = {"pass": 0.95, "needs_work": 0.6, "fail": 0.4}.get(v)
+        if conf is not None:
+            try:
+                skills_manager.update_skill(name, {"confidence": conf}, owner=owner)
+            except Exception:
+                pass
+    job["status"] = "done"
+
+
+async def run_audit_arm(messages: list[dict], url, model, headers, owner,
+                               workload: str = "foreground") -> tuple[str, dict, Optional[dict]]:
+    """Run one audit arm in the agent loop; return transcript, stats, approval."""
+    import json as _json
+    from src.agent_loop import stream_agent_loop
+    from src.agent_runtime.authority import RequestAuthority, active_request_authority
+    transcript = []
+    approval_required = None
+    stats = {"turns": 0, "tool_calls": 0}
+    try:
+        # max_tokens explicitly set: passing 0 lets some upstreams (Ollama,
+        # OpenAI-compat) generate an empty completion, which manifested as
+        # the skill test returning nothing while chat (which carries its
+        # preset's max_tokens) worked. 4096 matches the chat default.
+        # aclosing: stopping for an approval leaves this loop early (#6635).
+        async with aclosing(stream_agent_loop(
+            url, model, messages, headers=headers,
+            temperature=0.3, max_tokens=4096, max_rounds=8,
+            owner=owner, workload=workload, suppress_skills=True,
+            request_authority=(active_request_authority() or RequestAuthority.empty(owner=owner)),
+        )) as stream:
+            async for chunk in stream:
+                # Streams can include an SSE event line before the data line,
+                # notably `event: error`. Do not silently discard those failures.
+                payload = next((line[6:] for line in chunk.splitlines() if line.startswith("data: ")), None)
+                if payload is None or payload == "[DONE]":
+                    continue
+                try:
+                    d = _json.loads(payload)
+                except Exception:
+                    continue
+                if d.get("error") or d.get("type") == "error":
+                    raise SkillAuditUnavailable(str(d.get("error") or d.get("message") or "Audit stream failed"))
+                if d.get("delta"):
+                    transcript.append(d["delta"])
+                elif d.get("type") == "tool_start":
+                    stats["tool_calls"] += 1
+                    transcript.append(f"\n[tool {d.get('tool')}] {str(d.get('command') or d.get('args') or '')[:300]}\n")
+                elif d.get("type") == "tool_output":
+                    transcript.append(f"[output] {str(d.get('output') or '')[:600]}\n")
+                    approval = d.get("ask_user")
+                    if (
+                        isinstance(approval, dict)
+                        and approval.get("kind") == "tool_approval"
+                    ):
+                        approval_required = approval
+                        break
+                elif d.get("type") == "agent_step":
+                    try:
+                        stats["turns"] = max(stats["turns"], int(d.get("round") or 0))
+                    except (TypeError, ValueError):
+                        pass
+                    transcript.append(f"\n--- round {d.get('round')} ---\n")
+                elif d.get("type") == "metrics":
+                    data = d.get("data") or {}
+                    try:
+                        stats["turns"] = max(stats["turns"], int(data.get("agent_rounds") or 0))
+                    except (TypeError, ValueError):
+                        pass
+                    try:
+                        stats["tool_calls"] = max(stats["tool_calls"], int(data.get("tool_calls") or 0))
+                    except (TypeError, ValueError):
+                        pass
+    except SkillAuditUnavailable:
+        raise
+    except Exception as e:
+        raise SkillAuditUnavailable(str(e)) from e
+    return "".join(transcript), stats, approval_required
+
+
+async def run_test_once(md: str, task: str, url, model, headers, owner,
+                               workload: str = "foreground", *, deps: AuditDependencies) -> tuple:
+    """Run the skill once in the agent loop; return (transcript, verdict)."""
+    messages = deps.test_messages(md, task)
+    text, stats, approval_required = await deps.run_arm(
+        messages, url, model, headers, owner, workload=workload,
+    )
+    if approval_required is not None:
+        # Unattended audits have no authority to approve and no UI that could
+        # resume this record. Destructively deny it now instead of leaving a
+        # reusable opaque grant pending until TTL/cap eviction.
+        try:
+            from src.tool_approvals import tool_approval_store
+            tool_approval_store.consume(
+                approval_required.get("approval_id"),
+                decision="deny",
+                owner=owner,
+                session_id=None,
+            )
+        except Exception:
+            logger.debug("Could not retire unattended skill approval", exc_info=True)
+        return text, {
+            "verdict": "inconclusive",
+            "confidence": 1.0,
+            "summary": (
+                "This automated audit reached an exact action that requires "
+                "a human approval; no action was executed."
+            ),
+            "issues": [
+                "Run this skill's manual test and review the sealed action."
+            ],
+            "approval_required": True,
+        }
+    verdict = await deps.evaluate_run(
+        md,
+        task,
+        text,
+        url,
+        model,
+        headers,
+        skill_stats=stats,
+        workload=workload,
+        owner=owner,
+    )
+    return text, verdict
diff --git a/services/skills/audit_workflow.py b/services/skills/audit_workflow.py
new file mode 100644
index 000000000..f7af6682f
--- /dev/null
+++ b/services/skills/audit_workflow.py
@@ -0,0 +1,439 @@
+"""Sequential skill audit coordination and transient owner-scoped jobs."""
+
+import logging
+from typing import Optional
+
+from services.memory.skills import SkillsManager
+from .dependencies import AuditDependencies
+
+from .agent_runner import SkillAuditUnavailable
+
+logger = logging.getLogger(__name__)
+
+_skill_audit_jobs: dict = {}
+
+
+async def audit_one_skill(skills_manager, skill, url, model, headers,
+                           teacher, owner, log, workload: str = "foreground", *, deps: AuditDependencies) -> dict:
+    """Test → judge → self-edit+retry → (teacher edit+retry) → flag. Never deletes;
+    a skill the teacher still can't fix is demoted to draft for manual review.
+    `teacher` is (url, model, headers) or None. `log(msg)` records progress."""
+    name = skill.get("name")
+
+    # Reflect the audit outcome in the skill's confidence so the main list
+    # updates: a clean pass earns high confidence; a pass that needed fixing
+    # earns a bit less; a skill that still fails is marked low.
+    def _set_conf(c):
+        try:
+            skills_manager.update_skill(name, {"confidence": c}, owner=owner)
+        except Exception:
+            pass
+
+    md = skills_manager.read_skill_md(name, owner=owner)
+    if not md:
+        log(f"{name}: no source — skipped")
+        return {"skill": name, "result": "skipped"}
+
+    # Cheap deterministic cleanup first. If this is an obvious lower-priority
+    # duplicate, do not spend LLM turns on necessity, retrieval precision,
+    # skill-vs-baseline testing, self-edit, or teacher escalation.
+    duplicate_of = deps.duplicate_blocker(skills_manager, name, owner)
+    if duplicate_of:
+        reason = f"Lower-priority duplicate of {duplicate_of}"
+        try:
+            skills_manager.update_skill(name, {"status": "draft", "confidence": 0.35}, owner=owner)
+            skills_manager.set_audit(name, "skipped", by_teacher=False, worker_model=model, owner=owner)
+            skills_manager.set_necessity(name, False, [duplicate_of], reason, owner=owner)
+        except Exception:
+            pass
+        log(f"{name}: draft — skipped audit ({reason[:100]})")
+        return {"skill": name, "result": "skipped_duplicate", "reason": reason, "confidence": 0.35, "status": "draft"}
+
+    # Advisory necessity/redundancy check — runs once, independent of the test
+    # outcome, and only records a flag the UI surfaces (never deletes/demotes).
+    others = []
+    nec = None
+    try:
+        # Only compare against skills the SAME owner can see, so the necessity
+        # judge never sees (or flags "redundant_with") another user's skills.
+        sk_owner = skill.get("owner")
+        others = [
+            {"name": s.get("name"), "description": s.get("description", "")}
+            for s in skills_manager.load(owner=owner)
+            if s.get("name") and s.get("name") != name
+            and (not sk_owner or not s.get("owner") or s.get("owner") == sk_owner)
+        ]
+        nec = await deps.evaluate_necessity(
+            md, others, url, model, headers, workload=workload,
+            owner=owner,
+        )
+        if nec is not None:
+            skills_manager.set_necessity(name, nec.get("necessary", True),
+                                         nec.get("redundant_with"), nec.get("reason"),
+                                         owner=owner)
+            if not nec.get("necessary", True):
+                log(f"{name}: possibly unnecessary — {nec.get('reason', '')[:80]}")
+    except Exception as e:
+        log(f"{name}: necessity check skipped — {e}")
+
+    # Retrieval precision check: if broad tags/trigger text would make this
+    # narrow skill over-inject, fix only metadata before the functional test.
+    try:
+        if deps.should_check_retrieval_precision(skill):
+            rp = await deps.evaluate_retrieval_precision(
+                md, others, url, model, headers, workload=workload,
+                owner=owner,
+            )
+            if rp and not rp.get("ok"):
+                issues = rp.get("issues") or ["metadata: retrieval: narrow tags and when_to_use to the intended trigger"]
+                log(f"{name}: narrowing retrieval metadata — {(rp.get('summary') or issues[0])[:80]}")
+                fixed = await deps.improve_markdown(md, {
+                    "verdict": "pass",
+                    "confidence": 1.0,
+                    "summary": rp.get("summary") or "Retrieval metadata is too broad.",
+                    "issues": issues,
+                }, "Retrieval audit only: the procedure may work, but matching metadata is too broad.",
+                    url, model, headers, workload=workload, owner=owner)
+                if fixed and fixed.strip() != md.strip() and deps.apply_markdown(skills_manager, name, fixed, owner):
+                    md = fixed
+                    refreshed = next((s for s in skills_manager.load(owner=owner) if s.get("name") == name), None)
+                    if refreshed:
+                        skill = refreshed
+    except Exception as e:
+        log(f"{name}: retrieval precision check skipped — {e}")
+
+    task = deps.test_task(skill)
+    log(f"{name}: testing…")
+    skill_messages = deps.test_messages(md, task)
+    transcript, skill_stats, approval_required = await deps.run_arm(
+        skill_messages,
+        url,
+        model,
+        headers,
+        owner,
+        workload=workload,
+    )
+    if approval_required is not None:
+        try:
+            from src.tool_approvals import tool_approval_store
+            tool_approval_store.consume(
+                approval_required.get("approval_id"),
+                decision="deny",
+                owner=owner,
+                session_id=None,
+            )
+        except Exception:
+            logger.debug("Could not retire unattended skill approval", exc_info=True)
+        verdict = {
+            "verdict": "inconclusive",
+            "confidence": 1.0,
+            "summary": (
+                "This automated audit reached an exact action that requires "
+                "a human approval; no action was executed."
+            ),
+            "issues": [
+                "Run this skill's manual test and review the sealed action."
+            ],
+            "approval_required": True,
+        }
+    else:
+        baseline_task = task
+        log(f"{name}: running no-skill baseline…")
+        baseline_transcript, baseline_stats, baseline_approval = await deps.run_arm(
+            deps.baseline_messages(baseline_task),
+            url,
+            model,
+            headers,
+            owner,
+            workload=workload,
+        )
+        if baseline_approval is not None:
+            try:
+                from src.tool_approvals import tool_approval_store
+                tool_approval_store.consume(
+                    baseline_approval.get("approval_id"),
+                    decision="deny",
+                    owner=owner,
+                    session_id=None,
+                )
+            except Exception:
+                logger.debug("Could not retire unattended baseline approval", exc_info=True)
+        verdict = await deps.evaluate_run(
+            md,
+            task,
+            transcript,
+            url,
+            model,
+            headers,
+            baseline_transcript=baseline_transcript,
+            skill_stats=skill_stats,
+            baseline_stats=baseline_stats,
+            workload=workload,
+            owner=owner,
+        )
+    v = verdict.get("verdict")
+    log(f"{name}: verdict = {v} ({verdict.get('summary', '')[:80]})")
+    if verdict.get("approval_required"):
+        # An unattended audit is not authority for an action influenced by the
+        # skill under test. Preserve the skill's current publication/confidence
+        # state and route the exact action to the manual test UI instead of
+        # letting a safety pause demote, rewrite, or auto-publish the skill.
+        skills_manager.set_audit(
+            name,
+            "inconclusive",
+            by_teacher=False,
+            worker_model=model,
+            owner=owner,
+            audit_summary=verdict.get("summary") or "The test requires approval for an external action.",
+        )
+        status = skill.get("status") or "draft"
+        log(f"{name}: {status} unchanged — exact action needs manual approval")
+        return {
+            "skill": name,
+            "result": "approval_required",
+            "verdict": verdict,
+            "status": status,
+        }
+    if v == "pass":
+        # Procedure works. If the reviewer still flagged metadata (tags/category/
+        # when_to_use/description), do ONE fixer pass to correct the frontmatter
+        # without re-testing — a metadata-only fix can't break a passing run.
+        meta_issues = [i for i in (verdict.get("issues") or []) if str(i).lower().lstrip().startswith("metadata:")]
+        if meta_issues:
+            log(f"{name}: pass, but fixing {len(meta_issues)} metadata issue(s)…")
+            fixed = await deps.improve_markdown(
+                md, verdict, transcript, url, model, headers, workload=workload,
+                owner=owner,
+            )
+            if fixed and fixed.strip() != md.strip():
+                deps.apply_markdown(skills_manager, name, fixed, owner)
+        _set_conf(0.95)
+        skills_manager.set_audit(
+            name,
+            "pass",
+            by_teacher=False,
+            worker_model=model,
+            owner=owner,
+            **deps.verdict_efficiency(verdict),
+        )
+        refreshed = next((s for s in skills_manager.load(owner=owner) if s.get("name") == name), None)
+        status = deps.finalize_status(skills_manager, name, owner, "pass", 0.95, (refreshed or {}).get("necessity"), verdict)
+        log(f"{name}: {status} — confidence 95%")
+        return {"skill": name, "result": "pass", "verdict": verdict, "confidence": 0.95, "status": status}
+    if v in ("unknown", "inconclusive"):
+        skills_manager.set_audit(
+            name,
+            "inconclusive",
+            by_teacher=False,
+            worker_model=model,
+            owner=owner,
+            **deps.verdict_efficiency(verdict),
+        )
+        status = deps.finalize_status(skills_manager, name, owner, "inconclusive", skill.get("confidence") or 0.0, skill.get("necessity"))
+        log(f"{name}: {status} — inconclusive")
+        return {"skill": name, "result": "inconclusive", "verdict": verdict, "status": status}
+
+    # Self-edit + retry.
+    log(f"{name}: self-editing to fix issues…")
+    new_md = await deps.improve_markdown(
+        md, verdict, transcript, url, model, headers, workload=workload,
+        owner=owner,
+    )
+    if new_md and new_md.strip() != md.strip() and deps.apply_markdown(skills_manager, name, new_md, owner):
+        md = new_md
+        transcript, verdict = await deps.run_test_once(
+            md, task, url, model, headers, owner, workload=workload,
+        )
+        v = verdict.get("verdict")
+        log(f"{name}: retry (self) = {v}")
+        if v == "pass":
+            _set_conf(0.85)
+            skills_manager.set_audit(
+                name,
+                "pass",
+                by_teacher=False,
+                worker_model=model,
+                owner=owner,
+                **deps.verdict_efficiency(verdict),
+            )
+            refreshed = next((s for s in skills_manager.load(owner=owner) if s.get("name") == name), None)
+            status = deps.finalize_status(skills_manager, name, owner, "pass", 0.85, (refreshed or {}).get("necessity"), verdict)
+            log(f"{name}: {status} — confidence 85% after self-edit")
+            return {"skill": name, "result": "pass_after_self_edit", "verdict": verdict, "confidence": 0.85, "status": status}
+
+    # Teacher escalation (if a distinct teacher model is configured). The
+    # teacher only REWRITES the skill — it does NOT run the test. The point is
+    # to verify the regular (student) model can now succeed with the teacher's
+    # improved procedure, so the retry runs on the worker model, not the teacher.
+    teacher_ran = False
+    if teacher and teacher[0] and teacher[1] and (teacher[1] != model or teacher[0] != url):
+        teacher_ran = True
+        t_url, t_model, t_headers = teacher
+        log(f"{name}: teacher {t_model} rewriting the skill…")
+        t_md = await deps.improve_markdown(
+            md, verdict, transcript, t_url, t_model, t_headers, workload=workload,
+            owner=owner,
+        )
+        if t_md and t_md.strip() != md.strip() and deps.apply_markdown(skills_manager, name, t_md, owner):
+            md = t_md
+        # Re-test with the STUDENT model (the model the skill runs under in use).
+            transcript, verdict = await deps.run_test_once(
+                md, task, url, model, headers, owner, workload=workload,
+            )
+        v = verdict.get("verdict")
+        log(f"{name}: retry on student after teacher rewrite = {v}")
+        if v == "pass":
+            _set_conf(0.8)
+            skills_manager.set_audit(
+                name,
+                "pass",
+                by_teacher=True,
+                worker_model=model,
+                teacher_model=t_model,
+                owner=owner,
+                **deps.verdict_efficiency(verdict),
+            )
+            refreshed = next((s for s in skills_manager.load(owner=owner) if s.get("name") == name), None)
+            status = deps.finalize_status(skills_manager, name, owner, "pass", 0.8, (refreshed or {}).get("necessity"), verdict)
+            log(f"{name}: {status} — confidence 80% after teacher rewrite")
+            return {"skill": name, "result": "pass_after_teacher", "verdict": verdict, "confidence": 0.8, "status": status}
+
+    # Still failing → demote to draft + low confidence + flag (do NOT delete).
+    try:
+        skills_manager.update_skill(name, {"status": "draft", "confidence": 0.35}, owner=owner)
+    except Exception:
+        pass
+    skills_manager.set_audit(
+        name, v or "fail", by_teacher=teacher_ran,
+        worker_model=model,
+        teacher_model=(teacher[1] if teacher_ran and teacher else ""),
+        owner=owner,
+        **deps.verdict_efficiency(verdict),
+    )
+    log(f"{name}: flagged — confidence lowered, kept as draft for manual review")
+    return {"skill": name, "result": "flagged", "verdict": verdict, "confidence": 0.35}
+
+
+async def run_audit_batch(key, skills_manager, names, url, model, headers, teacher, owner,
+                             workload: str = "foreground", *, deps: AuditDependencies):
+    """Background: audit each named skill in sequence, recording progress."""
+    import asyncio as _asyncio
+    import time as _time
+
+    job = deps.audit_jobs.get(key)
+    if job is None:
+        return
+
+    def log(msg):
+        job["log"].append(msg)
+        if len(job["log"]) > 1000:
+            del job["log"][0:len(job["log"]) - 1000]
+
+    cancelled = False
+    try:
+        for nm in names:
+            if job.get("cancel"):
+                cancelled = True
+                log("(cancelled)")
+                break
+            job["current"] = nm
+            skills = skills_manager.load(owner=owner)
+            sk = next((s for s in skills if s.get("name") == nm), None)
+            if not sk:
+                continue
+            try:
+                res = await deps.audit_one(
+                    skills_manager, sk, url, model, headers, teacher, owner, log,
+                    workload=workload,
+                )
+            except _asyncio.CancelledError:
+                cancelled = True
+                job["cancel"] = True
+                log("(cancelled)")
+                raise
+            except SkillAuditUnavailable as e:
+                job["unavailable"] = str(e)
+                log(f"Audit paused: {e}. Skill verdicts unchanged; retry when the model is available.")
+                break
+            except Exception as e:
+                log(f"{nm}: error — {e}")
+                res = {"skill": nm, "result": "error"}
+                skills_manager.set_audit(nm, "inconclusive", worker_model=model, owner=owner)
+            try:
+                refreshed = next((s for s in skills_manager.load(owner=owner) if s.get("name") == nm), None)
+                if refreshed:
+                    res["skill_state"] = {
+                        "name": refreshed.get("name"),
+                        "status": refreshed.get("status"),
+                        "confidence": refreshed.get("confidence"),
+                        "audit_verdict": refreshed.get("audit_verdict"),
+                        "audit_by_teacher": refreshed.get("audit_by_teacher"),
+                        "audit_worker_model": refreshed.get("audit_worker_model"),
+                        "audit_teacher_model": refreshed.get("audit_teacher_model"),
+                        "audited_at": refreshed.get("audited_at"),
+                        "saved_turns": refreshed.get("saved_turns"),
+                        "saved_tool_calls": refreshed.get("saved_tool_calls"),
+                        "baseline_verdict": refreshed.get("baseline_verdict"),
+                        "usefulness": refreshed.get("usefulness"),
+                        "necessity": refreshed.get("necessity"),
+                    }
+            except Exception:
+                pass
+            job["results"].append(res)
+            job["done"] = len(job["results"])
+    except _asyncio.CancelledError:
+        cancelled = True
+    finally:
+        if not cancelled and not job.get("cancel") and not job.get("unavailable"):
+            try:
+                deps.finalize_batch(skills_manager, job.get("results") or [], owner, log)
+            except Exception:
+                logger.warning("Could not finalize skills audit batch", exc_info=True)
+        job["current"] = None
+        job["status"] = "cancelled" if cancelled or job.get("cancel") else "error" if job.get("unavailable") else "done"
+        job["finished"] = _time.time()
+        job.pop("task", None)
+
+
+async def run_scheduled_skill_audit(skills_manager: SkillsManager,
+                                    owner: Optional[str] = None,
+                                    max_skills: int = 8, *, deps: AuditDependencies) -> dict:
+    """Nightly audit pass. Audits the LEAST-recently-audited skills first and
+    caps the batch so it rotates through the library over successive nights
+    instead of re-checking the same ones every run. Reuses the same job store
+    the manual 'Audit all' button uses, so its progress shows in the UI too."""
+    import time as _time
+
+    key = (owner or "",)
+    existing = deps.audit_jobs.get(key)
+    if existing and existing.get("status") == "running":
+        logger.info("Scheduled skill audit skipped — a run is already active.")
+        return {"status": "running", "skipped": True}
+
+    try:
+        url, model, headers, teacher = deps.resolve_models(owner=owner)
+    except ValueError as e:
+        logger.info(f"Scheduled skill audit skipped — {e}")
+        return {"status": "skipped", "reason": str(e)}
+
+    from services.memory.skill_lifecycle import automatic_audit_candidates
+    skills = automatic_audit_candidates(skills_manager.load(owner=owner), limit=max_skills)
+    names = [s["name"] for s in skills]
+    if not names:
+        return {"status": "done", "total": 0}
+
+    deps.audit_jobs[key] = {
+        "status": "running", "scope": "scheduled", "model": model,
+        "teacher": teacher[1] if teacher else None,
+        "total": len(names), "done": 0, "current": None,
+        "results": [], "log": [f"Nightly audit of {len(names)} least-recently-checked skill(s) with {model}"
+                               + (f"; teacher {teacher[1]}" if teacher else "")],
+        "started": _time.time(), "cancel": False,
+    }
+    logger.info(f"Scheduled skill audit starting: {len(names)} skill(s) (owner={owner or 'all'})")
+    await deps.run_batch(
+        key, skills_manager, names, url, model, headers, teacher, owner,
+        workload="background",
+    )
+    job = deps.audit_jobs.get(key, {})
+    return {"status": "done", "total": len(names), "results": job.get("results", [])}
diff --git a/services/skills/dependencies.py b/services/skills/dependencies.py
new file mode 100644
index 000000000..5ff669a8b
--- /dev/null
+++ b/services/skills/dependencies.py
@@ -0,0 +1,35 @@
+"""Explicit collaborators for execution and audit coordination.
+
+The transport compatibility bindings supply the original patchable functions.
+Services never import the skills transport module or copy credentials into a
+second state store.
+"""
+from dataclasses import dataclass
+from typing import Callable
+
+
+@dataclass(frozen=True)
+class AuditDependencies:
+    test_jobs: dict
+    audit_jobs: dict
+    test_task: Callable
+    test_messages: Callable
+    baseline_messages: Callable
+    evaluate_run: Callable
+    evaluate_necessity: Callable
+    evaluate_retrieval_precision: Callable
+    should_check_retrieval_precision: Callable
+    improve_markdown: Callable
+    apply_markdown: Callable
+    duplicate_blocker: Callable
+    finalize_status: Callable
+    finalize_batch: Callable
+    auto_publish_policy: Callable
+    utility_blocker: Callable
+    verdict_efficiency: Callable
+    run_test_job: Callable
+    run_arm: Callable
+    run_test_once: Callable
+    audit_one: Callable
+    run_batch: Callable
+    resolve_models: Callable
diff --git a/services/skills/evaluation.py b/services/skills/evaluation.py
new file mode 100644
index 000000000..85ebeeadf
--- /dev/null
+++ b/services/skills/evaluation.py
@@ -0,0 +1,464 @@
+"""Model grading and advisory skill assessment with explicit offline call seams."""
+
+import logging
+import re
+from typing import Optional
+
+from src.text_helpers import strip_closed_think_blocks
+from src.utility_effort import effort_for_call
+
+logger = logging.getLogger(__name__)
+
+# Last-resort verdict extraction from a teacher/verifier model's prose (run when
+# JSON parsing fails). `["\'\s:]*` already consumes whitespace, so the original
+# trailing `\s*` made two adjacent \s-matching quantifiers that backtrack O(n^2)
+# on a `verdict` + whitespace flood in untrusted model output (CodeQL
+# py/polynomial-redos). Without it a single unbounded quantifier remains — the
+# matched text is identical, and the scan is linear.
+_VERDICT_PROSE_RE = re.compile(
+    r'verdict["\'\s:]*["\']?(pass|needs_work|fail|inconclusive)', re.I
+)
+
+
+def verdict_efficiency(verdict: Optional[dict]) -> dict:
+    if not isinstance(verdict, dict):
+        return {}
+    out = {"audit_summary": str(verdict.get("summary") or "")[:2000]}
+    for key in ("saved_turns", "saved_tool_calls"):
+        if key not in verdict:
+            continue
+        try:
+            out[key] = int(verdict.get(key))
+        except (TypeError, ValueError):
+            pass
+    baseline = str(verdict.get("baseline_verdict") or "").lower().strip()
+    if baseline in {"better", "same", "worse", "unknown"}:
+        out["baseline_verdict"] = baseline
+    if "usefulness" in verdict:
+        try:
+            out["usefulness"] = max(0.0, min(1.0, float(verdict.get("usefulness"))))
+        except (TypeError, ValueError):
+            pass
+    return out
+
+
+def parse_run_verdict(raw: str):
+    """Return a final result dict on success, or None if unparseable."""
+    import json as _json
+    import re as _re
+    _VERDICTS = ("pass", "needs_work", "fail", "inconclusive")
+
+    text = (raw or '')
+    # Strip closed think blocks. If a <think> was opened but never closed
+    # (the model ran out of budget mid-reasoning), drop everything from it
+    # onward so its stray braces don't poison JSON extraction.
+    text = strip_closed_think_blocks(text)
+    text = _re.sub(r'<think(?:ing)?>[\s\S]*$', '', text, flags=_re.I).strip()
+
+    def _coerce(d):
+        return d if (isinstance(d, dict) and "verdict" in d) else None
+
+    data = None
+    # Scan every balanced {...} candidate and keep the LAST one that parses
+    # and carries a "verdict" — the transcript is full of JSON API bodies,
+    # so a naive first-brace/last-brace span almost never parses.
+    for m in _re.finditer(r'\{[\s\S]*?\}', text):
+        frag = m.group(0)
+        for cand in (frag, _re.sub(r',(\s*[}\]])', r'\1', frag)):
+            try:
+                d = _coerce(_json.loads(cand))
+            except Exception:
+                d = None
+            if d is not None:
+                data = d
+    # Fallback to the greedy outermost span (handles nested objects the
+    # non-greedy scan above splits apart).
+    if data is None:
+        a, b = text.find('{'), text.rfind('}')
+        if a >= 0 and b > a:
+            frag = text[a:b + 1]
+            for cand in (frag, _re.sub(r',(\s*[}\]])', r'\1', frag)):
+                try:
+                    d = _coerce(_json.loads(cand))
+                except Exception:
+                    d = None
+                if d is not None:
+                    data = d
+                    break
+
+    v = str(data.get("verdict", "")).lower().strip() if isinstance(data, dict) else None
+    # Last resort: pull the verdict keyword straight out of the prose so a
+    # clearly-decided run isn't thrown away as "unparseable".
+    if v not in _VERDICTS:
+        km = _VERDICT_PROSE_RE.search(text)
+        if km:
+            v = km.group(1).lower()
+            if data is None:
+                data = {}
+    if not isinstance(data, dict) or v not in _VERDICTS:
+        return None
+    try:
+        conf = float(data.get("confidence", 0))
+    except (TypeError, ValueError):
+        conf = 0
+    try:
+        usefulness = float(data.get("usefulness", 0.0))
+    except (TypeError, ValueError):
+        usefulness = 0.0
+    try:
+        saved_turns = int(data.get("saved_turns", 0))
+    except (TypeError, ValueError):
+        saved_turns = 0
+    try:
+        saved_tool_calls = int(data.get("saved_tool_calls", 0))
+    except (TypeError, ValueError):
+        saved_tool_calls = 0
+    return {
+        "verdict": v,
+        "confidence": max(0.0, min(1.0, conf)),
+        "summary": str(data.get("summary", ""))[:400],
+        "issues": [str(x)[:200] for x in (data.get("issues") or []) if str(x).strip()][:8],
+        "baseline_verdict": (
+            str(data.get("baseline_verdict", "unknown")).lower().strip()
+            if str(data.get("baseline_verdict", "unknown")).lower().strip() in {"better", "same", "worse", "unknown"}
+            else "unknown"
+        ),
+        "usefulness": max(0.0, min(1.0, usefulness)),
+        "saved_turns": saved_turns,
+        "saved_tool_calls": saved_tool_calls,
+    }
+
+
+async def evaluate_run(skill_md: str, task: str, transcript: str,
+                          url: str, model: str, headers: Optional[dict],
+                          baseline_transcript: str = "",
+                          skill_stats: Optional[dict] = None,
+                          baseline_stats: Optional[dict] = None,
+                          workload: str = "foreground", owner: Optional[str] = None,
+                          *, _llm_call=None, _effort_for_call=None) -> dict:
+    """LLM-as-judge: grade a skill test run from its transcript. Advisory only.
+
+    Robust against local reasoning models (strips <think>, lenient JSON,
+    generous token budget) — same defensive parsing used elsewhere.
+    """
+    if _llm_call is None:
+        from src.llm_core import llm_call_async
+        _llm_call = llm_call_async
+    _effort_for_call = _effort_for_call or effort_for_call
+
+    sys_prompt = (
+        "You are a strict QA reviewer judging whether an AI 'skill' (a reusable "
+        "procedure) actually works. You are given the SKILL, the TASK it was tested "
+        "on, and the TRANSCRIPT of the agent's run.\n\n"
+        "Judge honestly:\n"
+        "- The functional verdict judges ONLY whether the SKILL RUN completed the "
+        "task correctly and whether the skill procedure is usable. A correct skill "
+        "run is pass even when the baseline is equally good. Record comparative "
+        "value separately in baseline_verdict/usefulness.\n"
+        "- Did following the skill accomplish the task accurately?\n"
+        "- Are the steps clear, correct, and reproducible?\n"
+        "- Did it reference tools/commands that don't exist or that errored?\n"
+        "- Separately, compared with the baseline run WITHOUT the skill, did the skill make "
+        "the agent more accurate, use fewer turns/tool calls, or avoid avoidable "
+        "thrashing?\n"
+        "- Do NOT penalize a skill merely for being broad or generic. A broad "
+        "skill is useful if it makes the agent finish correctly in fewer turns "
+        "or with fewer tools than baseline.\n"
+        "- METADATA: do the frontmatter fields match what the skill actually does? "
+        "Flag wrong/misleading/missing tags, a wrong category, a when_to_use that "
+        "doesn't describe the real trigger, or a description that oversells or "
+        "mismatches the body. List each metadata problem in 'issues' (prefix it "
+        "with 'metadata:'). Metadata problems alone do NOT make the verdict 'fail' "
+        "if the procedure works — note them as issues on an otherwise-passing run.\n\n"
+        "Never use inconclusive merely because the baseline was the same or better. "
+        "IMPORTANT — fairness rule: if the SKILL RUN could NOT proceed because it lacked "
+        "an input or target the test never provided (e.g. there was no document/"
+        "email/data to act on, so the agent reasonably asked for it), that is NOT "
+        "the skill's fault. Return verdict \"inconclusive\" — do NOT mark it fail "
+        "or needs_work. Only judge the skill's PROCEDURE; reserve fail/needs_work "
+        "for when the steps themselves are wrong, vague, or reference missing tools.\n\n"
+        "If you need to reason, do it inside <think></think> FIRST. Then output "
+        "ONLY this JSON (no fences):\n"
+        'Set baseline_verdict to how the SKILL RUN compares to the BASELINE RUN.\n\n'
+        '{"verdict": "pass" | "needs_work" | "fail" | "inconclusive", '
+        '"confidence": 0.0-1.0, "summary": "one short sentence", '
+        '"issues": ["short issue", ...], '
+        '"baseline_verdict": "better" | "same" | "worse" | "unknown", '
+        '"usefulness": 0.0-1.0, "saved_turns": integer, "saved_tool_calls": integer}'
+    )
+    # Give the judge plenty of transcript, and when it must trim, keep the TAIL
+    # (the final result lives at the end) plus a bit of the head — truncating to
+    # a short prefix made the judge wrongly call complete runs "incomplete /
+    # missing sections" because it never saw the end.
+    def _clip(t: str, limit: int = 24000) -> str:
+        t = (t or "").strip() or "(no output produced)"
+        if len(t) <= limit:
+            return t
+        head = limit // 4
+        return t[:head] + "\n\n…[transcript trimmed for length]…\n\n" + t[-(limit - head):]
+    skill_stats = skill_stats or {}
+    baseline_stats = baseline_stats or {}
+    user_msg = (
+        f"=== SKILL ===\n{(skill_md or '')[:4000]}\n\n"
+        f"=== TASK ===\n{task}\n\n"
+        f"=== SKILL RUN STATS ===\n"
+        f"turns={skill_stats.get('turns', 'unknown')} "
+        f"tool_calls={skill_stats.get('tool_calls', 'unknown')}\n\n"
+        f"=== SKILL RUN TRANSCRIPT ===\n{_clip(transcript)}\n\n"
+        f"=== BASELINE RUN WITHOUT SKILL STATS ===\n"
+        f"turns={baseline_stats.get('turns', 'unknown')} "
+        f"tool_calls={baseline_stats.get('tool_calls', 'unknown')}\n\n"
+        f"=== BASELINE RUN WITHOUT SKILL TRANSCRIPT ===\n{_clip(baseline_transcript)}"
+    )
+
+    # Two attempts: the first lets the judge reason; if a heavy reasoning model
+    # burns its budget inside <think> and never emits the JSON, the second
+    # forbids thinking and demands the JSON immediately.
+    last_text = ""
+    last_err = None
+    for attempt in range(2):
+        msgs = [{"role": "system", "content": sys_prompt},
+                {"role": "user", "content": user_msg}]
+        if attempt == 1:
+            msgs[0]["content"] = (
+                sys_prompt + "\n\nDO NOT use <think> or any reasoning. Your reply "
+                "must START with '{' and be ONLY the JSON object, nothing else."
+            )
+        try:
+            raw = await _llm_call(
+                # Generous budget so a heavy reasoner can think AND still have
+                # room to emit the JSON afterwards (reasoning tokens come out of
+                # this same cap; the server clamps to its own max).
+                url, model, msgs,
+                temperature=0.1, max_tokens=32768, headers=headers, timeout=180,
+                workload=workload,
+                reasoning_effort=_effort_for_call(url, model, owner),
+            )
+        except Exception as e:
+            # Don't give up on a transient first-attempt error — let the second
+            # (no-think) attempt run before reporting failure.
+            last_err = e
+            continue
+        last_text = (raw or '')
+        parsed = parse_run_verdict(raw)
+        if parsed is not None:
+            return parsed
+
+    if last_err is not None and not last_text:
+        return {"verdict": "unknown", "confidence": 0, "summary": f"Review call failed: {last_err}", "issues": []}
+    return {"verdict": "unknown", "confidence": 0,
+            "summary": "Reviewer returned unparseable output.", "issues": [], "raw": last_text[:300]}
+
+
+async def evaluate_necessity(skill_md: str, others: list, url: str, model: str,
+                                headers: Optional[dict],
+                                workload: str = "foreground", owner: Optional[str] = None,
+                          *, _llm_call=None, _effort_for_call=None) -> Optional[dict]:
+    """Advisory judge: is this skill worth keeping, or is it redundant / trivially
+    unnecessary? Sees the OTHER skills' names+descriptions so it can spot
+    duplicates. Returns {necessary, redundant_with, reason} or None. Never acts —
+    purely a flag the UI surfaces."""
+    import json as _json
+    import re as _re
+    if _llm_call is None:
+        from src.llm_core import llm_call_async
+        _llm_call = llm_call_async
+    _effort_for_call = _effort_for_call or effort_for_call
+
+    catalog = "\n".join(f"- {o.get('name')}: {o.get('description', '')}" for o in others) or "(no other skills)"
+    sys_prompt = (
+        "You assess whether a reusable AI 'skill' (a saved procedure) is worth keeping. "
+        "A skill is UNNECESSARY if it essentially duplicates another skill in the library. "
+        "Do NOT call a skill unnecessary merely because it is broad or generic; broad "
+        "skills can be worth keeping when they make a capable assistant finish accurately "
+        "with fewer turns or fewer tool calls than it would without the skill. A skill IS "
+        "necessary if it captures a reusable trigger, procedure, tool sequence, or "
+        "hard-won detail that could improve future runs.\n\n"
+        "Be conservative: only call it unnecessary when you're confident. Reason in "
+        "<think></think> first if needed, then output ONLY this JSON:\n"
+        '{"necessary": true|false, "redundant_with": ["skill-name", ...], '
+        '"reason": "one short sentence"}'
+    )
+    user_msg = (
+        f"=== SKILL UNDER REVIEW ===\n{(skill_md or '')[:3000]}\n\n"
+        f"=== OTHER SKILLS IN THE LIBRARY ===\n{catalog[:4000]}"
+    )
+    try:
+        raw = await _llm_call(
+            url, model,
+            [{"role": "system", "content": sys_prompt}, {"role": "user", "content": user_msg}],
+            temperature=0.1, max_tokens=8192, headers=headers, timeout=120,
+            workload=workload,
+            reasoning_effort=_effort_for_call(url, model, owner),
+        )
+    except Exception as e:
+        logger.warning(f"Necessity check failed: {e}")
+        return None
+    text = strip_closed_think_blocks(raw or '')
+    text = _re.sub(r'<think(?:ing)?>[\s\S]*$', '', text, flags=_re.I).strip()
+    data = None
+    a, b = text.find('{'), text.rfind('}')
+    if a >= 0 and b > a:
+        frag = text[a:b + 1]
+        for cand in (frag, _re.sub(r',(\s*[}\]])', r'\1', frag)):
+            try:
+                data = _json.loads(cand)
+                break
+            except Exception:
+                continue
+    if not isinstance(data, dict) or "necessary" not in data:
+        return None
+    return {
+        "necessary": bool(data.get("necessary", True)),
+        "redundant_with": [str(x)[:80] for x in (data.get("redundant_with") or []) if str(x).strip()][:6],
+        "reason": str(data.get("reason", ""))[:200],
+    }
+
+
+def should_check_retrieval_precision(skill: dict) -> bool:
+    """Cheap prefilter for the expensive retrieval-precision judge.
+
+    Skills with broad tags like "network" or "document" are the ones most likely
+    to over-inject. Narrow command/vendor tags alone are fine.
+    """
+    broad = {
+        "arch", "arch linux", "linux", "network", "networking", "wifi",
+        "installation", "install", "system", "ssh", "document", "documents",
+        "search", "email", "calendar", "gpu", "server", "python",
+    }
+    if not isinstance(skill, dict):
+        return False
+    tags = {str(t or "").strip().lower() for t in (skill.get("tags") or [])}
+    if tags & broad:
+        return True
+    text = " ".join([
+        str(skill.get("name") or ""),
+        str(skill.get("description") or ""),
+        str(skill.get("when_to_use") or ""),
+    ]).lower()
+    return sum(1 for t in broad if t in text) >= 2
+
+
+async def evaluate_retrieval_precision(skill_md: str, others: list,
+                                          url: str, model: str,
+                                          headers: Optional[dict],
+                                          workload: str = "foreground", owner: Optional[str] = None,
+                          *, _llm_call=None, _effort_for_call=None) -> Optional[dict]:
+    """Advisory judge: would this skill's metadata make retrieval over-select it?
+
+    This is distinct from "does the procedure work?". It asks whether tags,
+    description, and when_to_use are specific enough that the skill won't be
+    injected into adjacent but wrong tasks.
+    """
+    import json as _json
+    import re as _re
+    if _llm_call is None:
+        from src.llm_core import llm_call_async
+        _llm_call = llm_call_async
+    _effort_for_call = _effort_for_call or effort_for_call
+
+    catalog = "\n".join(f"- {o.get('name')}: {o.get('description', '')}" for o in others[:80]) or "(no other skills)"
+    sys_prompt = (
+        "You are auditing retrieval metadata for a reusable AI skill. The app selects "
+        "skills by matching user requests against the skill name, description, tags, "
+        "when_to_use, and procedure text. Judge whether this skill is likely to be "
+        "over-selected for nearby but wrong requests.\n\n"
+        "Focus ONLY on metadata/retrieval precision, not whether the procedure works. "
+        "Flag broad tags such as network, installation, system, document, search, ssh, "
+        "python, gpu, or server when they would cause this narrow skill to match too "
+        "many adjacent tasks. Recommend narrower tags/when_to_use wording. Compare "
+        "against the other skills to spot boundaries.\n\n"
+        "Return ok=true only when the trigger metadata is narrow enough. If not ok, "
+        "issues MUST start with 'metadata: retrieval:' and be actionable. Output ONLY JSON:\n"
+        '{"ok": true|false, "summary": "one short sentence", "issues": ["metadata: retrieval: ..."]}'
+    )
+    user_msg = (
+        f"=== SKILL UNDER REVIEW ===\n{(skill_md or '')[:5000]}\n\n"
+        f"=== OTHER SKILLS IN LIBRARY ===\n{catalog[:5000]}\n\n"
+        "Decide if this skill's retrieval metadata should be narrowed so it only "
+        "fires for its intended scenario and not for adjacent skills above."
+    )
+    try:
+        raw = await _llm_call(
+            url, model,
+            [{"role": "system", "content": sys_prompt}, {"role": "user", "content": user_msg}],
+            temperature=0.1, max_tokens=4096, headers=headers, timeout=90,
+            workload=workload,
+            reasoning_effort=_effort_for_call(url, model, owner),
+        )
+    except Exception as e:
+        logger.warning(f"Retrieval precision check failed: {e}")
+        return None
+    text = strip_closed_think_blocks(raw or '')
+    text = _re.sub(r'<think(?:ing)?>[\s\S]*$', '', text, flags=_re.I).strip()
+    data = None
+    a, b = text.find('{'), text.rfind('}')
+    if a >= 0 and b > a:
+        frag = text[a:b + 1]
+        for cand in (frag, _re.sub(r',(\s*[}\]])', r'\1', frag)):
+            try:
+                data = _json.loads(cand)
+                break
+            except Exception:
+                continue
+    if not isinstance(data, dict) or "ok" not in data:
+        return None
+    return {
+        "ok": bool(data.get("ok")),
+        "summary": str(data.get("summary", ""))[:300],
+        "issues": [str(x)[:220] for x in (data.get("issues") or []) if str(x).strip()][:6],
+    }
+
+
+async def improve_markdown(skill_md: str, verdict: dict, transcript: str, url, model, headers,
+                            workload: str = "foreground", owner: Optional[str] = None,
+                          *, _llm_call=None, _effort_for_call=None):
+    """Have a model rewrite SKILL.md to fix the reviewer's issues. Returns the
+    corrected markdown, or None if it couldn't produce a usable change."""
+    import re as _re
+    if _llm_call is None:
+        from src.llm_core import llm_call_async
+        _llm_call = llm_call_async
+    _effort_for_call = _effort_for_call or effort_for_call
+    issues = "\n".join("- " + str(i) for i in (verdict.get("issues") or []))
+    sys_prompt = (
+        "You are improving a reusable AI SKILL written in Markdown (frontmatter + body). "
+        "A QA reviewer found problems after a test run. Rewrite the SKILL.md to fix them: "
+        "make vague steps concrete, correct or remove references to tools that don't exist, "
+        "ensure the procedure is reproducible. "
+        "Keep the `name` field EXACTLY as-is (it is the skill's identity / filename). You MAY "
+        "correct the OTHER frontmatter — tags, category, when_to_use, description — when the "
+        "reviewer flagged them (issues prefixed 'metadata:') or they don't match the body; keep "
+        "retrieval metadata narrow: remove broad tags that would over-select the skill, and make "
+        "`when_to_use` say when NOT to use the skill if adjacent tasks are easy to confuse. Keep "
+        "valid frontmatter structure. Do NOT invent capabilities the agent lacks. Reason in "
+        "<think></think> first if needed, then output ONLY the full corrected SKILL.md (no "
+        "fences, no commentary)."
+    )
+    user_msg = (
+        f"=== CURRENT SKILL.md ===\n{skill_md}\n\n"
+        f"=== REVIEWER VERDICT ===\n{verdict.get('summary', '')}\nIssues:\n{issues}\n\n"
+        f"=== TEST TRANSCRIPT ===\n{(transcript or '')[:6000]}"
+    )
+    try:
+        raw = await _llm_call(url, model,
+                                   [{"role": "system", "content": sys_prompt},
+                                    {"role": "user", "content": user_msg}],
+                                   temperature=0.2, max_tokens=16384, headers=headers, timeout=180,
+                                   workload=workload,
+                                   reasoning_effort=_effort_for_call(url, model, owner))
+    except Exception as e:
+        logger.warning(f"Audit: improve call failed: {e}")
+        return None
+    text = strip_closed_think_blocks(raw or '')
+    text = _re.sub(r'<think(?:ing)?>[\s\S]*$', '', text, flags=_re.I)
+    text = _re.sub(r'</think(?:ing)?>', '', text, flags=_re.I).strip()
+    if text.startswith("```"):
+        text = text.split("\n", 1)[-1].rsplit("```", 1)[0].strip()
+    # Some reasoning models still prepend analysis or echo the old skill before
+    # the final corrected document. Keep only the last complete-looking
+    # frontmatter document so reviewer prose never gets persisted into SKILL.md.
+    starts = list(_re.finditer(r'(?m)^---\s*\n(?=[\s\S]*?^name\s*:)', text))
+    if starts:
+        text = text[starts[-1].start():].strip()
+    return text or None
diff --git a/services/skills/job_coordinator.py b/services/skills/job_coordinator.py
new file mode 100644
index 000000000..1f737a519
--- /dev/null
+++ b/services/skills/job_coordinator.py
@@ -0,0 +1,216 @@
+"""Transient job transitions and public polling projections.
+
+HTTP ownership and approval validation happen before these operations. These
+functions use the supplied registries and preserve the existing task ownership.
+"""
+import asyncio as _asyncio
+import logging
+import time as _time
+
+from src.prompt_security import untrusted_context_message
+from .dependencies import AuditDependencies
+
+logger = logging.getLogger(__name__)
+
+
+def start_test_job(name, md, task, url, model, headers, user, skills_manager,
+                   request_authority, *, deps: AuditDependencies):
+    key = (user or "", name)
+    previous_job = deps.test_jobs.get(key) or {}
+    previous_approval = previous_job.get("approval") or {}
+    if previous_approval.get("approval_id"):
+        try:
+            from src.tool_approvals import tool_approval_store
+            tool_approval_store.consume(
+                previous_approval["approval_id"],
+                decision="deny",
+                owner=user,
+                session_id=None,
+            )
+        except Exception:
+            logger.debug("Could not retire replaced skill approval", exc_info=True)
+    deps.test_jobs[key] = {
+        "status": "running",
+        "task": task,
+        "model": model,
+        "skill": name,
+        "started": _time.time(),
+        "log": [{"type": "skill_test_start", "task": task, "skill": name, "model": model}],
+        "verdict": None,
+        "_run": {
+            "md": md,
+            "url": url,
+            "model": model,
+            "headers": headers,
+            "owner": user,
+            "request_authority": request_authority,
+        },
+    }
+    _asyncio.create_task(deps.run_test_job(
+        key, name, md, task, url, model, headers, user, skills_manager,
+        request_authority=request_authority))
+    return {"ok": True, "status": "running", "skill": name, "model": model}
+
+
+def continue_test_job(job, key, name, decision, expected, exact_approval,
+                      skills_manager, *, deps: AuditDependencies):
+    job.pop("approval", None)
+    if decision == "deny":
+        job.pop("_transcript", None)
+        job.pop("_run", None)
+        job["log"].append({
+            "type": "approval_denied",
+            "text": "Exact action denied; the skill test stopped without executing it.",
+        })
+        job["verdict"] = {
+            "verdict": "inconclusive",
+            "confidence": 1.0,
+            "summary": "The test stopped because its exact action was denied.",
+            "issues": [],
+        }
+        job["status"] = "done"
+        return {"ok": True, "status": "done", "decision": "deny"}
+
+    run = job.get("_run") or {}
+    transcript = job.pop("_transcript", [])
+    # stream_agent_loop owns its per-round message list internally. Rebuild
+    # continuation context from the original untrusted skill plus the
+    # accumulated transcript so repeated approvals do not lose earlier
+    # approved results, while keeping every transcript byte tainted.
+    messages = deps.test_messages(
+        run.get("md", ""),
+        job.get("task", ""),
+    )
+    if transcript:
+        messages.append(untrusted_context_message(
+            "skill test transcript",
+            "".join(str(item) for item in transcript),
+        ))
+    messages.extend([
+        {
+            "role": "assistant",
+            "content": str(expected.get("question") or "Allow this exact action once?"),
+        },
+        {
+            "role": "user",
+            "content": (
+                f"Approved the exact {exact_approval.pending.tool_name} "
+                "action shown above once."
+            ),
+        },
+    ])
+    job["status"] = "running"
+    job["log"].append({
+        "type": "approval_granted",
+        "text": (
+            f"Approved exact {exact_approval.pending.tool_name} action once; "
+            "resuming test."
+        ),
+    })
+    _asyncio.create_task(deps.run_test_job(
+        key,
+        name,
+        run.get("md", ""),
+        job.get("task", ""),
+        run.get("url"),
+        run.get("model"),
+        run.get("headers"),
+        run.get("owner"),
+        skills_manager,
+        messages=messages,
+        transcript=transcript,
+        exact_approval=exact_approval,
+    ))
+    return {"ok": True, "status": "running", "decision": "approve"}
+
+
+def test_status(user, name, *, deps: AuditDependencies):
+    job = deps.test_jobs.get((user or "", name))
+    if not job:
+        return {"status": "none"}
+    return {
+        "status": job["status"],
+        "task": job.get("task"),
+        "model": job.get("model"),
+        "log": job.get("log", []),
+        "verdict": job.get("verdict"),
+        "approval": job.get("approval"),
+    }
+
+
+def select_audit_names(skills_manager, user, scope, requested_names, skip_audited):
+    skills = skills_manager.load(owner=user)
+    # Built-ins are tracked, pre-approved application procedures. They do
+    # not consume audit turns and cannot be demoted by an audit result.
+    auditable_skills = [s for s in skills if s.get("source") != "builtin"]
+    by_name = {s.get("name"): s for s in auditable_skills if s.get("name")}
+    if isinstance(requested_names, list):
+        names = []
+        seen = set()
+        for raw in requested_names:
+            nm = str(raw or "").strip()
+            if not nm or nm in seen or nm not in by_name:
+                continue
+            if scope not in ("all", "selected") and (by_name[nm].get("status") or "draft") == "published":
+                continue
+            if skip_audited and by_name[nm].get("audit_verdict"):
+                continue
+            names.append(nm)
+            seen.add(nm)
+        scope = "selected" if requested_names else scope
+    elif scope == "all":
+        names = [
+            s.get("name") for s in auditable_skills
+            if s.get("name") and (not skip_audited or not s.get("audit_verdict"))
+        ]
+    else:
+        scope = "unchecked" if scope == "drafts" else scope
+        names = [
+            s.get("name") for s in auditable_skills
+            if s.get("name")
+            and (s.get("status") or "draft") != "published"
+            and not s.get("audit_verdict")
+        ]
+    return names, scope
+
+
+def start_audit_job(key, skills_manager, names, url, model, headers, teacher, user,
+                    scope, *, deps: AuditDependencies):
+    if not names:
+        return {"ok": True, "status": "done", "total": 0, "results": [], "log": ["No skills to audit."]}
+
+    deps.audit_jobs[key] = {
+        "status": "running", "scope": scope, "model": model,
+        "teacher": teacher[1] if teacher else None,
+        "total": len(names), "done": 0, "current": None,
+        "results": [], "log": [f"Auditing {len(names)} skill(s) with {model}" + (f"; teacher {teacher[1]}" if teacher else "")],
+        "started": _time.time(), "cancel": False,
+    }
+    task = _asyncio.create_task(deps.run_batch(key, skills_manager, names, url, model, headers, teacher, user))
+    deps.audit_jobs[key]["task"] = task
+    return {"ok": True, "status": "running", "total": len(names), "model": model}
+
+
+def audit_status(user, *, deps: AuditDependencies):
+    job = deps.audit_jobs.get((user or "",))
+    if not job:
+        return {"status": "none"}
+    return {
+        "status": job["status"], "scope": job.get("scope"),
+        "total": job.get("total", 0), "done": job.get("done", 0),
+        "current": job.get("current"), "model": job.get("model"), "teacher": job.get("teacher"),
+        "results": job.get("results", []), "log": job.get("log", []),
+        "started": job.get("started"), "finished": job.get("finished"),
+    }
+
+
+def cancel_audit(user, *, deps: AuditDependencies):
+    job = deps.audit_jobs.get((user or "",))
+    if job:
+        job["cancel"] = True
+        job["status"] = "cancelled"
+        job["current"] = None
+        task = job.get("task")
+        if task and not task.done():
+            task.cancel()
+    return {"ok": True, "status": "cancelled" if job else "none"}
diff --git a/services/skills/model_selection.py b/services/skills/model_selection.py
new file mode 100644
index 000000000..cd446632c
--- /dev/null
+++ b/services/skills/model_selection.py
@@ -0,0 +1,75 @@
+"""Owner-scoped audit worker and teacher endpoint resolution."""
+
+import logging
+
+
+logger = logging.getLogger(__name__)
+
+def resolve_audit_models(owner=None, model_spec=None, endpoint_url=None):
+    """Resolve (url, model, headers, teacher) for an audit run from Settings.
+
+    Worker = Utility model (falling back to Default, normalized to a served
+    model id); teacher = the optional Settings → Teacher Model config. Shared
+    by the manual /audit-all route and scheduled/event audits. Raises
+    ValueError if no worker model.
+    """
+    from src.endpoint_resolver import resolve_endpoint, resolve_utility_fallback_candidates
+    if model_spec and endpoint_url:
+        # Scheduled tasks store the endpoint URL and model separately. Resolve
+        # the endpoint directly so an explicit task choice cannot be replaced
+        # by the global Utility setting.
+        from src.endpoint_resolver import build_headers, resolve_endpoint_runtime
+        from src.database import ModelEndpoint, SessionLocal
+        from src.endpoint_resolver import normalize_base, same_endpoint_base
+        from src.auth_helpers import owner_filter
+        url = endpoint_url
+        model = model_spec
+        headers = {}
+        db = SessionLocal()
+        try:
+            query = db.query(ModelEndpoint).filter(ModelEndpoint.is_enabled == True)
+            for ep in owner_filter(query, ModelEndpoint, owner).all():
+                base = normalize_base(getattr(ep, "base_url", "") or "")
+                if same_endpoint_base(url, base):
+                    runtime_base, api_key = resolve_endpoint_runtime(ep, owner=owner)
+                    headers = build_headers(api_key, runtime_base or base)
+                    break
+        finally:
+            db.close()
+    elif model_spec:
+        from src.ai_interaction import _resolve_model
+        url, model, headers = _resolve_model(str(model_spec), owner=owner)
+    else:
+        url, model, headers = resolve_endpoint("utility", owner=owner)
+    if not url or not model:
+        # Utility fallbacks are an explicit part of the user's model
+        # configuration. Audits must use the same chain as other background
+        # work instead of treating an empty primary Utility slot as fatal.
+        for fallback_url, fallback_model, fallback_headers in resolve_utility_fallback_candidates(owner=owner):
+            url, model, headers = fallback_url, fallback_model, fallback_headers
+            break
+    if not url or not model:
+        raise ValueError("No model configured — set a Default or Utility model in Settings.")
+    try:
+        from src.llm_core import list_model_ids
+        import os as _os
+        _avail = list_model_ids(url, headers=headers)
+        if _avail and model not in _avail:
+            _base = _os.path.basename((model or "").rstrip("/"))
+            model = next((a for a in _avail if _os.path.basename(a.rstrip("/")) == _base), None) or _avail[0]
+    except Exception:
+        pass
+
+    teacher = None
+    try:
+        from src.settings import get_setting
+        if get_setting("teacher_enabled", False):
+            spec = (get_setting("teacher_model", "") or "").strip()
+            if spec:
+                from src.ai_interaction import _resolve_model
+                t_url, t_model, t_headers = _resolve_model(spec, owner=owner)
+                if t_url and t_model:
+                    teacher = (t_url, t_model, t_headers)
+    except Exception as e:
+        logger.warning(f"Audit teacher resolve failed: {e}")
+    return url, model, headers, teacher
diff --git a/services/skills/prompts.py b/services/skills/prompts.py
new file mode 100644
index 000000000..42e32e000
--- /dev/null
+++ b/services/skills/prompts.py
@@ -0,0 +1,52 @@
+"""Identical audit tasks and explicitly untrusted skill context."""
+
+from src.prompt_security import untrusted_context_message
+
+def _skill_test_task(skill: dict) -> str:
+    """Build the one shared task used by both sides of an audit comparison."""
+    if not isinstance(skill, dict):
+        skill = {}
+    ctx = (skill.get("when_to_use") or skill.get("description") or skill.get("name") or "").strip()
+    return (
+        "Complete this task end-to-end. Use this exact task context and do not ask "
+        "the user for more input. If a harmless fixture is needed, create the "
+        "smallest realistic one that satisfies the context, state it explicitly, "
+        "then complete and verify the result. Do not perform destructive or "
+        "externally visible actions. Task context: " + (ctx or "(general)")
+    )
+
+
+def _skill_baseline_task(skill: dict) -> str:
+    """Backward-compatible alias; both audit arms must receive identical text."""
+    return _skill_test_task(skill)
+
+
+def _skill_test_messages(md: str, task: str) -> list[dict]:
+    """Keep user-editable skill text out of the trusted system role."""
+    return [
+        {
+            "role": "system",
+            "content": (
+                "You are TESTING a skill. Follow the supplied reusable procedure "
+                "to complete the user's task for real, using available tools step "
+                "by step. If the skill is wrong, unclear, or references tools that "
+                "do not exist, do your best; the problems will be reviewed afterward."
+            ),
+        },
+        untrusted_context_message("skill under test", md),
+        {"role": "user", "content": task},
+    ]
+
+
+def _skill_baseline_messages(task: str) -> list[dict]:
+    return [
+        {
+            "role": "system",
+            "content": (
+                "You are completing a baseline audit run. Do not use any saved "
+                "skill text. Solve the user's task using only your normal tools "
+                "and reasoning."
+            ),
+        },
+        {"role": "user", "content": task},
+    ]
diff --git a/services/skills/publication.py b/services/skills/publication.py
new file mode 100644
index 000000000..d5267d7e6
--- /dev/null
+++ b/services/skills/publication.py
@@ -0,0 +1,349 @@
+"""Audit publication and duplicate coordination through the canonical SkillsManager."""
+
+import logging
+import re
+from typing import Optional
+
+from .dependencies import AuditDependencies
+
+logger = logging.getLogger(__name__)
+
+def auto_publish_policy(owner) -> tuple[bool, float]:
+    """Return (auto_publish_enabled, minimum_confidence) for audit finalization."""
+    try:
+        from routes.prefs_routes import _load_for_user
+        prefs = _load_for_user(owner) or {}
+    except Exception:
+        prefs = {}
+    try:
+        from src.settings import get_setting
+        default_min = get_setting("skill_autosave_min_confidence", 0.85)
+    except Exception:
+        default_min = 0.85
+    enabled = bool(prefs.get("auto_approve_skills", True))
+    try:
+        min_conf = float(prefs.get("skill_min_confidence", default_min))
+    except (TypeError, ValueError):
+        min_conf = 0.85
+    return enabled, max(0.0, min(1.0, min_conf))
+
+
+def duplicate_blocker(skills_manager, name: str, owner) -> Optional[str]:
+    """Cheap duplicate guard matching the UI's duplicate grouping.
+
+    The LLM necessity check catches semantic redundancy, but the UI also has a
+    cheap similarity pass. Use the same broad signal before auto-publishing so
+    a high-scoring lower-priority duplicate stays draft.
+    """
+    import re as _re
+
+    def _tokens(sk: dict) -> set[str]:
+        text = " ".join([
+            str(sk.get("name") or ""),
+            str(sk.get("description") or ""),
+            str(sk.get("when_to_use") or ""),
+            " ".join(sk.get("procedure") or []),
+            " ".join(sk.get("tags") or []),
+        ]).lower()
+        text = _re.sub(r"-\d+\b", "", text)
+        return {
+            t for t in _re.split(r"[^a-z0-9]+", text)
+            if len(t) > 2 and t not in {"the", "and", "with", "for", "from", "using"}
+        }
+
+    def _sim(a: dict, b: dict) -> float:
+        A, B = _tokens(a), _tokens(b)
+        if not A or not B:
+            return 0.0
+        return len(A & B) / max(1, len(A | B))
+
+    def _base(n: str) -> str:
+        return _re.sub(r"-\d+$", "", str(n or ""))
+
+    def _score(sk: dict) -> float:
+        return (
+            (100000 if (sk.get("status") == "published") else 0)
+            + int(sk.get("uses") or 0) * 100
+            + round(float(sk.get("confidence") or 0) * 100)
+            + (-5 if sk.get("audit_by_teacher") else 0)
+            - (len(str(sk.get("name") or "")) / 1000)
+        )
+
+    skills = [s for s in skills_manager.load(owner=owner) if s.get("status") != "binned"]
+    current = next((s for s in skills if (s.get("name") or s.get("id")) == name), None)
+    if not current:
+        return None
+    duplicates = []
+    cur_name = current.get("name") or current.get("id") or name
+    for other in skills:
+        other_name = other.get("name") or other.get("id")
+        if not other_name or other_name == cur_name:
+            continue
+        if _base(cur_name) == _base(other_name) or _sim(current, other) >= 0.38:
+            duplicates.append(other)
+    if not duplicates:
+        return None
+    keeper = sorted([current, *duplicates], key=_score, reverse=True)[0]
+    keeper_name = keeper.get("name") or keeper.get("id") or ""
+    if keeper_name and keeper_name != cur_name:
+        try:
+            skills_manager.set_necessity(
+                cur_name,
+                False,
+                [keeper_name],
+                f"Lower-priority duplicate of {keeper_name}",
+                owner=owner,
+            )
+        except Exception:
+            pass
+        return keeper_name
+    return None
+
+
+def finalize_batch(skills_manager, results: list[dict], owner, log, *, deps: AuditDependencies) -> None:
+    """Draft audited failures, bin duplicate losers, and publish the best copy.
+
+    Binned skills remain on disk for recovery and inspection, but the Skills
+    manager excludes them from retrieval. Only skills actually processed by
+    this audit job are changed here; an unrelated existing skill is never
+    moved just because it resembles an audited one.
+    """
+    import re as _re
+
+    auto_publish, min_conf = deps.auto_publish_policy(owner)
+    current = [
+        s for s in skills_manager.load(owner=owner)
+        if s.get("source") != "builtin" and s.get("status") != "binned"
+    ]
+    by_name = {s.get("name"): s for s in current if s.get("name")}
+    processed = {str(r.get("skill")) for r in results if r.get("skill")}
+    protected = {
+        str(r.get("skill")) for r in results
+        if r.get("skill") and r.get("result") == "approval_required"
+    }
+
+    def tokens(sk: dict) -> set[str]:
+        text = " ".join([
+            str(sk.get("name") or ""), str(sk.get("description") or ""),
+            str(sk.get("when_to_use") or ""), " ".join(sk.get("procedure") or []),
+            " ".join(sk.get("tags") or []),
+        ]).lower()
+        text = _re.sub(r"-\d+\b", "", text)
+        return {
+            t for t in _re.split(r"[^a-z0-9]+", text)
+            if len(t) > 2 and t not in {"the", "and", "with", "for", "from", "using"}
+        }
+
+    def similar(a: dict, b: dict) -> float:
+        left, right = tokens(a), tokens(b)
+        return len(left & right) / max(1, len(left | right)) if left and right else 0.0
+
+    def base(name: str) -> str:
+        return _re.sub(r"-\d+$", "", str(name or ""))
+
+    def score(sk: dict) -> float:
+        try:
+            confidence = float(sk.get("confidence") or 0)
+        except (TypeError, ValueError):
+            confidence = 0.0
+        return (
+            (100000 if sk.get("status") == "published" else 0)
+            + int(sk.get("uses") or 0) * 100
+            + round(confidence * 100)
+            + (-5 if sk.get("audit_by_teacher") else 0)
+            - len(str(sk.get("name") or "")) / 1000
+        )
+
+    # Anything that does not clear the configured policy stays a draft. Drafts
+    # are excluded from retrieval/injection by SkillsManager.index_for().
+    for name in processed - protected:
+        skill = by_name.get(name)
+        if not skill:
+            continue
+        verdict = str(skill.get("audit_verdict") or "").lower()
+        try:
+            confidence = float(skill.get("confidence") or 0)
+        except (TypeError, ValueError):
+            confidence = 0.0
+        if verdict in {"needs_work", "fail"} or (
+            verdict == "pass" and confidence < min_conf
+        ):
+            try:
+                skills_manager.update_skill(name, {"status": "draft"}, owner=owner)
+                log(f"{name}: kept as draft after audit")
+            except Exception:
+                logger.warning("Could not bin audited skill %s", name, exc_info=True)
+
+    # Build the same connected duplicate groups shown by the UI.
+    parent = {s["name"]: s["name"] for s in current}
+
+    def find(name: str) -> str:
+        while parent[name] != name:
+            parent[name] = parent[parent[name]]
+            name = parent[name]
+        return name
+
+    def unite(left: str, right: str) -> None:
+        left, right = find(left), find(right)
+        if left != right:
+            parent[right] = left
+
+    for index, left in enumerate(current):
+        for right in current[index + 1:]:
+            if base(left["name"]) == base(right["name"]) or similar(left, right) >= 0.38:
+                unite(left["name"], right["name"])
+    groups: dict[str, list[dict]] = {}
+    for skill in current:
+        groups.setdefault(find(skill["name"]), []).append(skill)
+
+    for group in groups.values():
+        if len(group) < 2:
+            continue
+        passing = []
+        for skill in group:
+            if skill["name"] not in processed or skill["name"] in protected:
+                continue
+            if str(skill.get("audit_verdict") or "").lower() != "pass":
+                continue
+            try:
+                confidence = float(skill.get("confidence") or 0)
+            except (TypeError, ValueError):
+                confidence = 0.0
+            if confidence >= min_conf:
+                passing.append(skill)
+        if not passing:
+            continue
+        keeper = max(passing, key=score)
+        if auto_publish:
+            try:
+                skills_manager.update_skill(keeper["name"], {"status": "published"}, owner=owner)
+                log(f"{keeper['name']}: auto-approved as best passing duplicate")
+            except Exception:
+                logger.warning("Could not auto-approve skill %s", keeper["name"], exc_info=True)
+        for skill in group:
+            name = skill["name"]
+            if name == keeper["name"] or name not in processed or name in protected:
+                continue
+            try:
+                skills_manager.update_skill(name, {"status": "binned"}, owner=owner)
+                log(f"{name}: moved to bin as duplicate of {keeper['name']}")
+            except Exception:
+                logger.warning("Could not bin duplicate skill %s", name, exc_info=True)
+
+
+def audit_flag_text(*parts) -> str:
+    text_parts = []
+    for part in parts:
+        if isinstance(part, dict):
+            text_parts.extend(str(v or "") for v in part.values())
+        elif isinstance(part, (list, tuple, set)):
+            text_parts.extend(str(v or "") for v in part)
+        else:
+            text_parts.append(str(part or ""))
+    return " ".join(text_parts).lower()
+
+
+def utility_blocker(skill: Optional[dict], necessity: Optional[dict],
+                           verdict_data: Optional[dict]) -> Optional[str]:
+    """Return a short reason when a passing skill still should stay draft.
+
+    Broad/generic wording is not a blocker by itself. The blocker is whether
+    the skill failed to improve the agent versus a no-skill baseline, or whether
+    it duplicates another skill.
+    """
+    generic_re = re.compile(
+        r"\b(duplicat\w*|redundan\w*|overlap\w*|same skill|same procedure)\b",
+        re.I,
+    )
+    if isinstance(necessity, dict):
+        reason = str(necessity.get("reason") or "")
+        if necessity.get("necessary") is False and generic_re.search(reason):
+            return reason or "Duplicate or redundant skill"
+
+    if isinstance(verdict_data, dict):
+        baseline_verdict = str(verdict_data.get("baseline_verdict") or "unknown").lower()
+        try:
+            usefulness = float(verdict_data.get("usefulness", 0.0) or 0.0)
+        except (TypeError, ValueError):
+            usefulness = 0.0
+        try:
+            saved_turns = int(verdict_data.get("saved_turns", 0) or 0)
+        except (TypeError, ValueError):
+            saved_turns = 0
+        try:
+            saved_tool_calls = int(verdict_data.get("saved_tool_calls", 0) or 0)
+        except (TypeError, ValueError):
+            saved_tool_calls = 0
+        if baseline_verdict == "worse":
+            return "Skill performed worse than the no-skill baseline"
+        verdict_text = audit_flag_text(
+            verdict_data.get("summary"),
+            verdict_data.get("issues") or [],
+        )
+        if generic_re.search(verdict_text):
+            return "Audit flagged the skill as duplicate or redundant"
+    return None
+
+
+def finalize_status(skills_manager, name: str, owner, verdict: str,
+                           confidence: Optional[float], necessity: Optional[dict] = None,
+                           verdict_data: Optional[dict] = None, *, deps: AuditDependencies) -> str:
+    """Apply the user's audit publishing policy.
+
+    Audit is the final pass: skills that pass at/above the threshold are
+    published; failing or unnecessary/redundant skills are returned to draft.
+    Inconclusive runs preserve the existing state because they provide no
+    evidence either way. The completed batch moves duplicate losers to the bin.
+    """
+    auto_publish, min_conf = deps.auto_publish_policy(owner)
+    necessary = True
+    current = next((s for s in skills_manager.load(owner=owner) if s.get("name") == name), None)
+    if verdict in {"inconclusive", "unknown"}:
+        return (current or {}).get("status") or "draft"
+    utility_reason = deps.utility_blocker(current, necessity, verdict_data)
+    if (
+        isinstance(necessity, dict)
+        and necessity.get("necessary") is False
+        and necessity.get("redundant_with")
+    ):
+        necessary = False
+    if utility_reason:
+        necessary = False
+        try:
+            skills_manager.set_necessity(name, False, [], utility_reason, owner=owner)
+        except Exception:
+            pass
+    duplicate_of = deps.duplicate_blocker(skills_manager, name, owner) if verdict == "pass" else None
+    if duplicate_of:
+        necessary = False
+    c = float(confidence or 0.0)
+    status = "published" if (auto_publish and necessary and verdict == "pass" and c >= min_conf) else "draft"
+    try:
+        skills_manager.update_skill(name, {"status": status}, owner=owner)
+    except Exception:
+        pass
+    return status
+
+
+def apply_markdown(skills_manager, name: str, md: str, owner) -> bool:
+    """Parse + persist an edited SKILL.md. Returns True on success."""
+    try:
+        from services.memory.skill_format import Skill, slugify
+        sk = Skill.from_markdown(md)
+        # Pin the identity: the audit's fixer is now allowed to edit frontmatter
+        # (tags/category/when_to_use/description), but it must NEVER rename the
+        # skill — a changed `name` would move the dir and orphan the usage/audit
+        # sidecar entries that the caller keeps writing under the original name.
+        sk.name = name
+        return bool(skills_manager.update_skill(name, {
+            "name": sk.name, "description": sk.description, "version": sk.version,
+            "category": sk.category, "tags": sk.tags, "platforms": sk.platforms,
+            "requires_toolsets": sk.requires_toolsets, "fallback_for_toolsets": sk.fallback_for_toolsets,
+            "status": sk.status, "confidence": sk.confidence, "source": sk.source,
+            "teacher_model": sk.teacher_model, "owner": sk.owner or owner,
+            "when_to_use": sk.when_to_use, "procedure": sk.procedure,
+            "pitfalls": sk.pitfalls, "verification": sk.verification, "body_extra": sk.body_extra,
+        }, owner=owner))
+    except Exception as e:
+        logger.warning(f"Audit: could not save edited skill {name}: {e}")
+        return False
diff --git a/tests/fixtures/skills_api_baseline.json b/tests/fixtures/skills_api_baseline.json
new file mode 100644
index 000000000..deed1b2d9
--- /dev/null
+++ b/tests/fixtures/skills_api_baseline.json
@@ -0,0 +1,4429 @@
+{
+  "baseline": "86b886c611338282af6d4a717246ea4e256f58df",
+  "routes": [
+    [
+      [
+        "GET"
+      ],
+      "/api/skills",
+      "list_skills"
+    ],
+    [
+      [
+        "GET"
+      ],
+      "/api/skills/index",
+      "get_index"
+    ],
+    [
+      [
+        "GET"
+      ],
+      "/api/skills/slash-catalog",
+      "get_slash_catalog"
+    ],
+    [
+      [
+        "GET"
+      ],
+      "/api/skills/builtin",
+      "list_builtin_skills"
+    ],
+    [
+      [
+        "GET"
+      ],
+      "/api/skills/builtin/{name}",
+      "get_builtin_skill"
+    ],
+    [
+      [
+        "PUT"
+      ],
+      "/api/skills/builtin/{name}",
+      "set_builtin_override"
+    ],
+    [
+      [
+        "DELETE"
+      ],
+      "/api/skills/builtin/{name}",
+      "reset_builtin_override"
+    ],
+    [
+      [
+        "POST"
+      ],
+      "/api/skills/import-from-url",
+      "import_skill_from_url"
+    ],
+    [
+      [
+        "POST"
+      ],
+      "/api/skills/add",
+      "add_skill"
+    ],
+    [
+      [
+        "POST"
+      ],
+      "/api/skills/{skill_id}/invoke",
+      "invoke_skill"
+    ],
+    [
+      [
+        "GET"
+      ],
+      "/api/skills/{skill_id}",
+      "get_skill"
+    ],
+    [
+      [
+        "GET"
+      ],
+      "/api/skills/{skill_id}/markdown",
+      "get_skill_markdown"
+    ],
+    [
+      [
+        "POST"
+      ],
+      "/api/skills/{skill_id}/test",
+      "test_skill"
+    ],
+    [
+      [
+        "POST"
+      ],
+      "/api/skills/{skill_id}/test-approval",
+      "approve_skill_test_action"
+    ],
+    [
+      [
+        "GET"
+      ],
+      "/api/skills/{skill_id}/test-status",
+      "test_skill_status"
+    ],
+    [
+      [
+        "POST"
+      ],
+      "/api/skills/audit-all",
+      "audit_all_skills"
+    ],
+    [
+      [
+        "GET"
+      ],
+      "/api/skills/audit-all/status",
+      "audit_status"
+    ],
+    [
+      [
+        "POST"
+      ],
+      "/api/skills/audit-all/cancel",
+      "audit_cancel"
+    ],
+    [
+      [
+        "POST"
+      ],
+      "/api/skills/{skill_id}/markdown",
+      "save_skill_markdown"
+    ],
+    [
+      [
+        "PUT"
+      ],
+      "/api/skills/{skill_id}",
+      "update_skill"
+    ],
+    [
+      [
+        "DELETE"
+      ],
+      "/api/skills/{skill_id}",
+      "delete_skill"
+    ],
+    [
+      [
+        "POST"
+      ],
+      "/api/skills/search",
+      "search_skills"
+    ]
+  ],
+  "signatures": {
+    "_verdict_efficiency": {
+      "parameters": [
+        {
+          "name": "verdict",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "origin": "typing.Union",
+            "module": "typing",
+            "arguments": [
+              {
+                "type": "builtins.dict"
+              },
+              {
+                "type": "builtins.NoneType"
+              }
+            ]
+          },
+          "default": {
+            "empty": true
+          }
+        }
+      ],
+      "return": {
+        "type": "builtins.dict"
+      }
+    },
+    "SkillAddRequest": {
+      "parameters": [
+        {
+          "name": "name",
+          "kind": "KEYWORD_ONLY",
+          "annotation": {
+            "origin": "typing.Annotated",
+            "annotation": {
+              "origin": "typing.Union",
+              "module": "typing",
+              "arguments": [
+                {
+                  "type": "builtins.str"
+                },
+                {
+                  "type": "builtins.NoneType"
+                }
+              ]
+            },
+            "metadata": [
+              {
+                "type": "annotated_types.MaxLen",
+                "fields": {
+                  "max_length": {
+                    "type": "builtins.int",
+                    "value": 80
+                  }
+                }
+              }
+            ]
+          },
+          "default": {
+            "type": "builtins.NoneType",
+            "value": null
+          }
+        },
+        {
+          "name": "description",
+          "kind": "KEYWORD_ONLY",
+          "annotation": {
+            "origin": "typing.Annotated",
+            "annotation": {
+              "origin": "typing.Union",
+              "module": "typing",
+              "arguments": [
+                {
+                  "type": "builtins.str"
+                },
+                {
+                  "type": "builtins.NoneType"
+                }
+              ]
+            },
+            "metadata": [
+              {
+                "type": "annotated_types.MaxLen",
+                "fields": {
+                  "max_length": {
+                    "type": "builtins.int",
+                    "value": 200
+                  }
+                }
+              }
+            ]
+          },
+          "default": {
+            "type": "builtins.NoneType",
+            "value": null
+          }
+        },
+        {
+          "name": "category",
+          "kind": "KEYWORD_ONLY",
+          "annotation": {
+            "origin": "typing.Annotated",
+            "annotation": {
+              "type": "builtins.str"
+            },
+            "metadata": [
+              {
+                "type": "annotated_types.MaxLen",
+                "fields": {
+                  "max_length": {
+                    "type": "builtins.int",
+                    "value": 40
+                  }
+                }
+              }
+            ]
+          },
+          "default": {
+            "type": "builtins.str",
+            "value": "general"
+          }
+        },
+        {
+          "name": "tags",
+          "kind": "KEYWORD_ONLY",
+          "annotation": {
+            "origin": "builtins.list",
+            "module": "typing",
+            "arguments": [
+              {
+                "type": "builtins.str"
+              }
+            ]
+          },
+          "default": {
+            "factory": "builtins.list",
+            "marker": "pydantic._internal._signature._HAS_DEFAULT_FACTORY_CLASS"
+          }
+        },
+        {
+          "name": "platforms",
+          "kind": "KEYWORD_ONLY",
+          "annotation": {
+            "origin": "builtins.list",
+            "module": "typing",
+            "arguments": [
+              {
+                "type": "builtins.str"
+              }
+            ]
+          },
+          "default": {
+            "factory": "builtins.list",
+            "marker": "pydantic._internal._signature._HAS_DEFAULT_FACTORY_CLASS"
+          }
+        },
+        {
+          "name": "requires_toolsets",
+          "kind": "KEYWORD_ONLY",
+          "annotation": {
+            "origin": "builtins.list",
+            "module": "typing",
+            "arguments": [
+              {
+                "type": "builtins.str"
+              }
+            ]
+          },
+          "default": {
+            "factory": "builtins.list",
+            "marker": "pydantic._internal._signature._HAS_DEFAULT_FACTORY_CLASS"
+          }
+        },
+        {
+          "name": "fallback_for_toolsets",
+          "kind": "KEYWORD_ONLY",
+          "annotation": {
+            "origin": "builtins.list",
+            "module": "typing",
+            "arguments": [
+              {
+                "type": "builtins.str"
+              }
+            ]
+          },
+          "default": {
+            "factory": "builtins.list",
+            "marker": "pydantic._internal._signature._HAS_DEFAULT_FACTORY_CLASS"
+          }
+        },
+        {
+          "name": "when_to_use",
+          "kind": "KEYWORD_ONLY",
+          "annotation": {
+            "origin": "typing.Annotated",
+            "annotation": {
+              "origin": "typing.Union",
+              "module": "typing",
+              "arguments": [
+                {
+                  "type": "builtins.str"
+                },
+                {
+                  "type": "builtins.NoneType"
+                }
+              ]
+            },
+            "metadata": [
+              {
+                "type": "annotated_types.MaxLen",
+                "fields": {
+                  "max_length": {
+                    "type": "builtins.int",
+                    "value": 2000
+                  }
+                }
+              }
+            ]
+          },
+          "default": {
+            "type": "builtins.NoneType",
+            "value": null
+          }
+        },
+        {
+          "name": "procedure",
+          "kind": "KEYWORD_ONLY",
+          "annotation": {
+            "origin": "builtins.list",
+            "module": "typing",
+            "arguments": [
+              {
+                "type": "builtins.str"
+              }
+            ]
+          },
+          "default": {
+            "factory": "builtins.list",
+            "marker": "pydantic._internal._signature._HAS_DEFAULT_FACTORY_CLASS"
+          }
+        },
+        {
+          "name": "pitfalls",
+          "kind": "KEYWORD_ONLY",
+          "annotation": {
+            "origin": "builtins.list",
+            "module": "typing",
+            "arguments": [
+              {
+                "type": "builtins.str"
+              }
+            ]
+          },
+          "default": {
+            "factory": "builtins.list",
+            "marker": "pydantic._internal._signature._HAS_DEFAULT_FACTORY_CLASS"
+          }
+        },
+        {
+          "name": "verification",
+          "kind": "KEYWORD_ONLY",
+          "annotation": {
+            "origin": "builtins.list",
+            "module": "typing",
+            "arguments": [
+              {
+                "type": "builtins.str"
+              }
+            ]
+          },
+          "default": {
+            "factory": "builtins.list",
+            "marker": "pydantic._internal._signature._HAS_DEFAULT_FACTORY_CLASS"
+          }
+        },
+        {
+          "name": "status",
+          "kind": "KEYWORD_ONLY",
+          "annotation": {
+            "type": "builtins.str"
+          },
+          "default": {
+            "type": "builtins.str",
+            "value": "draft"
+          }
+        },
+        {
+          "name": "version",
+          "kind": "KEYWORD_ONLY",
+          "annotation": {
+            "type": "builtins.str"
+          },
+          "default": {
+            "type": "builtins.str",
+            "value": "1.0.0"
+          }
+        },
+        {
+          "name": "confidence",
+          "kind": "KEYWORD_ONLY",
+          "annotation": {
+            "type": "builtins.float"
+          },
+          "default": {
+            "type": "builtins.float",
+            "value": 0.8
+          }
+        },
+        {
+          "name": "source",
+          "kind": "KEYWORD_ONLY",
+          "annotation": {
+            "type": "builtins.str"
+          },
+          "default": {
+            "type": "builtins.str",
+            "value": "user"
+          }
+        },
+        {
+          "name": "teacher_model",
+          "kind": "KEYWORD_ONLY",
+          "annotation": {
+            "origin": "typing.Union",
+            "module": "typing",
+            "arguments": [
+              {
+                "type": "builtins.str"
+              },
+              {
+                "type": "builtins.NoneType"
+              }
+            ]
+          },
+          "default": {
+            "type": "builtins.NoneType",
+            "value": null
+          }
+        },
+        {
+          "name": "session_id",
+          "kind": "KEYWORD_ONLY",
+          "annotation": {
+            "origin": "typing.Union",
+            "module": "typing",
+            "arguments": [
+              {
+                "type": "builtins.str"
+              },
+              {
+                "type": "builtins.NoneType"
+              }
+            ]
+          },
+          "default": {
+            "type": "builtins.NoneType",
+            "value": null
+          }
+        },
+        {
+          "name": "title",
+          "kind": "KEYWORD_ONLY",
+          "annotation": {
+            "origin": "typing.Annotated",
+            "annotation": {
+              "origin": "typing.Union",
+              "module": "typing",
+              "arguments": [
+                {
+                  "type": "builtins.str"
+                },
+                {
+                  "type": "builtins.NoneType"
+                }
+              ]
+            },
+            "metadata": [
+              {
+                "type": "annotated_types.MaxLen",
+                "fields": {
+                  "max_length": {
+                    "type": "builtins.int",
+                    "value": 200
+                  }
+                }
+              }
+            ]
+          },
+          "default": {
+            "type": "builtins.NoneType",
+            "value": null
+          }
+        },
+        {
+          "name": "problem",
+          "kind": "KEYWORD_ONLY",
+          "annotation": {
+            "origin": "typing.Annotated",
+            "annotation": {
+              "origin": "typing.Union",
+              "module": "typing",
+              "arguments": [
+                {
+                  "type": "builtins.str"
+                },
+                {
+                  "type": "builtins.NoneType"
+                }
+              ]
+            },
+            "metadata": [
+              {
+                "type": "annotated_types.MaxLen",
+                "fields": {
+                  "max_length": {
+                    "type": "builtins.int",
+                    "value": 2000
+                  }
+                }
+              }
+            ]
+          },
+          "default": {
+            "type": "builtins.NoneType",
+            "value": null
+          }
+        },
+        {
+          "name": "solution",
+          "kind": "KEYWORD_ONLY",
+          "annotation": {
+            "origin": "typing.Annotated",
+            "annotation": {
+              "origin": "typing.Union",
+              "module": "typing",
+              "arguments": [
+                {
+                  "type": "builtins.str"
+                },
+                {
+                  "type": "builtins.NoneType"
+                }
+              ]
+            },
+            "metadata": [
+              {
+                "type": "annotated_types.MaxLen",
+                "fields": {
+                  "max_length": {
+                    "type": "builtins.int",
+                    "value": 5000
+                  }
+                }
+              }
+            ]
+          },
+          "default": {
+            "type": "builtins.NoneType",
+            "value": null
+          }
+        },
+        {
+          "name": "steps",
+          "kind": "KEYWORD_ONLY",
+          "annotation": {
+            "origin": "builtins.list",
+            "module": "typing",
+            "arguments": [
+              {
+                "type": "builtins.str"
+              }
+            ]
+          },
+          "default": {
+            "factory": "builtins.list",
+            "marker": "pydantic._internal._signature._HAS_DEFAULT_FACTORY_CLASS"
+          }
+        }
+      ],
+      "return": {
+        "type": "builtins.NoneType",
+        "value": null
+      },
+      "model_fields": {
+        "name": {
+          "annotation": {
+            "origin": "typing.Annotated",
+            "annotation": {
+              "origin": "typing.Union",
+              "module": "typing",
+              "arguments": [
+                {
+                  "type": "builtins.str"
+                },
+                {
+                  "type": "builtins.NoneType"
+                }
+              ]
+            },
+            "metadata": [
+              {
+                "type": "annotated_types.MaxLen",
+                "fields": {
+                  "max_length": {
+                    "type": "builtins.int",
+                    "value": 80
+                  }
+                }
+              }
+            ]
+          },
+          "default": {
+            "type": "builtins.NoneType",
+            "value": null
+          },
+          "validation": {
+            "alias": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "alias_priority": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "validation_alias": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "discriminator": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "validate_default": {
+              "type": "builtins.NoneType",
+              "value": null
+            }
+          }
+        },
+        "description": {
+          "annotation": {
+            "origin": "typing.Annotated",
+            "annotation": {
+              "origin": "typing.Union",
+              "module": "typing",
+              "arguments": [
+                {
+                  "type": "builtins.str"
+                },
+                {
+                  "type": "builtins.NoneType"
+                }
+              ]
+            },
+            "metadata": [
+              {
+                "type": "annotated_types.MaxLen",
+                "fields": {
+                  "max_length": {
+                    "type": "builtins.int",
+                    "value": 200
+                  }
+                }
+              }
+            ]
+          },
+          "default": {
+            "type": "builtins.NoneType",
+            "value": null
+          },
+          "validation": {
+            "alias": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "alias_priority": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "validation_alias": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "discriminator": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "validate_default": {
+              "type": "builtins.NoneType",
+              "value": null
+            }
+          }
+        },
+        "category": {
+          "annotation": {
+            "origin": "typing.Annotated",
+            "annotation": {
+              "type": "builtins.str"
+            },
+            "metadata": [
+              {
+                "type": "annotated_types.MaxLen",
+                "fields": {
+                  "max_length": {
+                    "type": "builtins.int",
+                    "value": 40
+                  }
+                }
+              }
+            ]
+          },
+          "default": {
+            "type": "builtins.str",
+            "value": "general"
+          },
+          "validation": {
+            "alias": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "alias_priority": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "validation_alias": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "discriminator": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "validate_default": {
+              "type": "builtins.NoneType",
+              "value": null
+            }
+          }
+        },
+        "tags": {
+          "annotation": {
+            "origin": "builtins.list",
+            "module": "typing",
+            "arguments": [
+              {
+                "type": "builtins.str"
+              }
+            ]
+          },
+          "default": {
+            "factory": "builtins.list",
+            "takes_validated_data": false
+          },
+          "validation": {
+            "alias": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "alias_priority": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "validation_alias": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "discriminator": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "validate_default": {
+              "type": "builtins.NoneType",
+              "value": null
+            }
+          }
+        },
+        "platforms": {
+          "annotation": {
+            "origin": "builtins.list",
+            "module": "typing",
+            "arguments": [
+              {
+                "type": "builtins.str"
+              }
+            ]
+          },
+          "default": {
+            "factory": "builtins.list",
+            "takes_validated_data": false
+          },
+          "validation": {
+            "alias": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "alias_priority": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "validation_alias": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "discriminator": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "validate_default": {
+              "type": "builtins.NoneType",
+              "value": null
+            }
+          }
+        },
+        "requires_toolsets": {
+          "annotation": {
+            "origin": "builtins.list",
+            "module": "typing",
+            "arguments": [
+              {
+                "type": "builtins.str"
+              }
+            ]
+          },
+          "default": {
+            "factory": "builtins.list",
+            "takes_validated_data": false
+          },
+          "validation": {
+            "alias": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "alias_priority": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "validation_alias": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "discriminator": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "validate_default": {
+              "type": "builtins.NoneType",
+              "value": null
+            }
+          }
+        },
+        "fallback_for_toolsets": {
+          "annotation": {
+            "origin": "builtins.list",
+            "module": "typing",
+            "arguments": [
+              {
+                "type": "builtins.str"
+              }
+            ]
+          },
+          "default": {
+            "factory": "builtins.list",
+            "takes_validated_data": false
+          },
+          "validation": {
+            "alias": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "alias_priority": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "validation_alias": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "discriminator": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "validate_default": {
+              "type": "builtins.NoneType",
+              "value": null
+            }
+          }
+        },
+        "when_to_use": {
+          "annotation": {
+            "origin": "typing.Annotated",
+            "annotation": {
+              "origin": "typing.Union",
+              "module": "typing",
+              "arguments": [
+                {
+                  "type": "builtins.str"
+                },
+                {
+                  "type": "builtins.NoneType"
+                }
+              ]
+            },
+            "metadata": [
+              {
+                "type": "annotated_types.MaxLen",
+                "fields": {
+                  "max_length": {
+                    "type": "builtins.int",
+                    "value": 2000
+                  }
+                }
+              }
+            ]
+          },
+          "default": {
+            "type": "builtins.NoneType",
+            "value": null
+          },
+          "validation": {
+            "alias": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "alias_priority": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "validation_alias": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "discriminator": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "validate_default": {
+              "type": "builtins.NoneType",
+              "value": null
+            }
+          }
+        },
+        "procedure": {
+          "annotation": {
+            "origin": "builtins.list",
+            "module": "typing",
+            "arguments": [
+              {
+                "type": "builtins.str"
+              }
+            ]
+          },
+          "default": {
+            "factory": "builtins.list",
+            "takes_validated_data": false
+          },
+          "validation": {
+            "alias": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "alias_priority": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "validation_alias": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "discriminator": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "validate_default": {
+              "type": "builtins.NoneType",
+              "value": null
+            }
+          }
+        },
+        "pitfalls": {
+          "annotation": {
+            "origin": "builtins.list",
+            "module": "typing",
+            "arguments": [
+              {
+                "type": "builtins.str"
+              }
+            ]
+          },
+          "default": {
+            "factory": "builtins.list",
+            "takes_validated_data": false
+          },
+          "validation": {
+            "alias": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "alias_priority": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "validation_alias": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "discriminator": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "validate_default": {
+              "type": "builtins.NoneType",
+              "value": null
+            }
+          }
+        },
+        "verification": {
+          "annotation": {
+            "origin": "builtins.list",
+            "module": "typing",
+            "arguments": [
+              {
+                "type": "builtins.str"
+              }
+            ]
+          },
+          "default": {
+            "factory": "builtins.list",
+            "takes_validated_data": false
+          },
+          "validation": {
+            "alias": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "alias_priority": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "validation_alias": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "discriminator": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "validate_default": {
+              "type": "builtins.NoneType",
+              "value": null
+            }
+          }
+        },
+        "status": {
+          "annotation": {
+            "type": "builtins.str"
+          },
+          "default": {
+            "type": "builtins.str",
+            "value": "draft"
+          },
+          "validation": {
+            "alias": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "alias_priority": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "validation_alias": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "discriminator": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "validate_default": {
+              "type": "builtins.NoneType",
+              "value": null
+            }
+          }
+        },
+        "version": {
+          "annotation": {
+            "type": "builtins.str"
+          },
+          "default": {
+            "type": "builtins.str",
+            "value": "1.0.0"
+          },
+          "validation": {
+            "alias": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "alias_priority": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "validation_alias": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "discriminator": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "validate_default": {
+              "type": "builtins.NoneType",
+              "value": null
+            }
+          }
+        },
+        "confidence": {
+          "annotation": {
+            "type": "builtins.float"
+          },
+          "default": {
+            "type": "builtins.float",
+            "value": 0.8
+          },
+          "validation": {
+            "alias": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "alias_priority": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "validation_alias": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "discriminator": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "validate_default": {
+              "type": "builtins.NoneType",
+              "value": null
+            }
+          }
+        },
+        "source": {
+          "annotation": {
+            "type": "builtins.str"
+          },
+          "default": {
+            "type": "builtins.str",
+            "value": "user"
+          },
+          "validation": {
+            "alias": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "alias_priority": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "validation_alias": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "discriminator": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "validate_default": {
+              "type": "builtins.NoneType",
+              "value": null
+            }
+          }
+        },
+        "teacher_model": {
+          "annotation": {
+            "origin": "typing.Union",
+            "module": "typing",
+            "arguments": [
+              {
+                "type": "builtins.str"
+              },
+              {
+                "type": "builtins.NoneType"
+              }
+            ]
+          },
+          "default": {
+            "type": "builtins.NoneType",
+            "value": null
+          },
+          "validation": {
+            "alias": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "alias_priority": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "validation_alias": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "discriminator": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "validate_default": {
+              "type": "builtins.NoneType",
+              "value": null
+            }
+          }
+        },
+        "session_id": {
+          "annotation": {
+            "origin": "typing.Union",
+            "module": "typing",
+            "arguments": [
+              {
+                "type": "builtins.str"
+              },
+              {
+                "type": "builtins.NoneType"
+              }
+            ]
+          },
+          "default": {
+            "type": "builtins.NoneType",
+            "value": null
+          },
+          "validation": {
+            "alias": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "alias_priority": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "validation_alias": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "discriminator": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "validate_default": {
+              "type": "builtins.NoneType",
+              "value": null
+            }
+          }
+        },
+        "title": {
+          "annotation": {
+            "origin": "typing.Annotated",
+            "annotation": {
+              "origin": "typing.Union",
+              "module": "typing",
+              "arguments": [
+                {
+                  "type": "builtins.str"
+                },
+                {
+                  "type": "builtins.NoneType"
+                }
+              ]
+            },
+            "metadata": [
+              {
+                "type": "annotated_types.MaxLen",
+                "fields": {
+                  "max_length": {
+                    "type": "builtins.int",
+                    "value": 200
+                  }
+                }
+              }
+            ]
+          },
+          "default": {
+            "type": "builtins.NoneType",
+            "value": null
+          },
+          "validation": {
+            "alias": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "alias_priority": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "validation_alias": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "discriminator": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "validate_default": {
+              "type": "builtins.NoneType",
+              "value": null
+            }
+          }
+        },
+        "problem": {
+          "annotation": {
+            "origin": "typing.Annotated",
+            "annotation": {
+              "origin": "typing.Union",
+              "module": "typing",
+              "arguments": [
+                {
+                  "type": "builtins.str"
+                },
+                {
+                  "type": "builtins.NoneType"
+                }
+              ]
+            },
+            "metadata": [
+              {
+                "type": "annotated_types.MaxLen",
+                "fields": {
+                  "max_length": {
+                    "type": "builtins.int",
+                    "value": 2000
+                  }
+                }
+              }
+            ]
+          },
+          "default": {
+            "type": "builtins.NoneType",
+            "value": null
+          },
+          "validation": {
+            "alias": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "alias_priority": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "validation_alias": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "discriminator": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "validate_default": {
+              "type": "builtins.NoneType",
+              "value": null
+            }
+          }
+        },
+        "solution": {
+          "annotation": {
+            "origin": "typing.Annotated",
+            "annotation": {
+              "origin": "typing.Union",
+              "module": "typing",
+              "arguments": [
+                {
+                  "type": "builtins.str"
+                },
+                {
+                  "type": "builtins.NoneType"
+                }
+              ]
+            },
+            "metadata": [
+              {
+                "type": "annotated_types.MaxLen",
+                "fields": {
+                  "max_length": {
+                    "type": "builtins.int",
+                    "value": 5000
+                  }
+                }
+              }
+            ]
+          },
+          "default": {
+            "type": "builtins.NoneType",
+            "value": null
+          },
+          "validation": {
+            "alias": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "alias_priority": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "validation_alias": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "discriminator": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "validate_default": {
+              "type": "builtins.NoneType",
+              "value": null
+            }
+          }
+        },
+        "steps": {
+          "annotation": {
+            "origin": "builtins.list",
+            "module": "typing",
+            "arguments": [
+              {
+                "type": "builtins.str"
+              }
+            ]
+          },
+          "default": {
+            "factory": "builtins.list",
+            "takes_validated_data": false
+          },
+          "validation": {
+            "alias": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "alias_priority": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "validation_alias": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "discriminator": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "validate_default": {
+              "type": "builtins.NoneType",
+              "value": null
+            }
+          }
+        }
+      },
+      "model_config": {
+        "type": "builtins.dict",
+        "items": {}
+      }
+    },
+    "SkillImportUrlRequest": {
+      "parameters": [
+        {
+          "name": "url",
+          "kind": "KEYWORD_ONLY",
+          "annotation": {
+            "origin": "typing.Annotated",
+            "annotation": {
+              "type": "builtins.str"
+            },
+            "metadata": [
+              {
+                "type": "annotated_types.MinLen",
+                "fields": {
+                  "min_length": {
+                    "type": "builtins.int",
+                    "value": 8
+                  }
+                }
+              },
+              {
+                "type": "annotated_types.MaxLen",
+                "fields": {
+                  "max_length": {
+                    "type": "builtins.int",
+                    "value": 2000
+                  }
+                }
+              }
+            ]
+          },
+          "default": {
+            "empty": true
+          }
+        }
+      ],
+      "return": {
+        "type": "builtins.NoneType",
+        "value": null
+      },
+      "model_fields": {
+        "url": {
+          "annotation": {
+            "origin": "typing.Annotated",
+            "annotation": {
+              "type": "builtins.str"
+            },
+            "metadata": [
+              {
+                "type": "annotated_types.MinLen",
+                "fields": {
+                  "min_length": {
+                    "type": "builtins.int",
+                    "value": 8
+                  }
+                }
+              },
+              {
+                "type": "annotated_types.MaxLen",
+                "fields": {
+                  "max_length": {
+                    "type": "builtins.int",
+                    "value": 2000
+                  }
+                }
+              }
+            ]
+          },
+          "default": {
+            "empty": true
+          },
+          "validation": {
+            "alias": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "alias_priority": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "validation_alias": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "discriminator": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "validate_default": {
+              "type": "builtins.NoneType",
+              "value": null
+            }
+          }
+        }
+      },
+      "model_config": {
+        "type": "builtins.dict",
+        "items": {}
+      }
+    },
+    "SkillUpdateRequest": {
+      "parameters": [
+        {
+          "name": "name",
+          "kind": "KEYWORD_ONLY",
+          "annotation": {
+            "origin": "typing.Union",
+            "module": "typing",
+            "arguments": [
+              {
+                "type": "builtins.str"
+              },
+              {
+                "type": "builtins.NoneType"
+              }
+            ]
+          },
+          "default": {
+            "type": "builtins.NoneType",
+            "value": null
+          }
+        },
+        {
+          "name": "description",
+          "kind": "KEYWORD_ONLY",
+          "annotation": {
+            "origin": "typing.Union",
+            "module": "typing",
+            "arguments": [
+              {
+                "type": "builtins.str"
+              },
+              {
+                "type": "builtins.NoneType"
+              }
+            ]
+          },
+          "default": {
+            "type": "builtins.NoneType",
+            "value": null
+          }
+        },
+        {
+          "name": "category",
+          "kind": "KEYWORD_ONLY",
+          "annotation": {
+            "origin": "typing.Union",
+            "module": "typing",
+            "arguments": [
+              {
+                "type": "builtins.str"
+              },
+              {
+                "type": "builtins.NoneType"
+              }
+            ]
+          },
+          "default": {
+            "type": "builtins.NoneType",
+            "value": null
+          }
+        },
+        {
+          "name": "tags",
+          "kind": "KEYWORD_ONLY",
+          "annotation": {
+            "origin": "typing.Union",
+            "module": "typing",
+            "arguments": [
+              {
+                "origin": "builtins.list",
+                "module": "typing",
+                "arguments": [
+                  {
+                    "type": "builtins.str"
+                  }
+                ]
+              },
+              {
+                "type": "builtins.NoneType"
+              }
+            ]
+          },
+          "default": {
+            "type": "builtins.NoneType",
+            "value": null
+          }
+        },
+        {
+          "name": "platforms",
+          "kind": "KEYWORD_ONLY",
+          "annotation": {
+            "origin": "typing.Union",
+            "module": "typing",
+            "arguments": [
+              {
+                "origin": "builtins.list",
+                "module": "typing",
+                "arguments": [
+                  {
+                    "type": "builtins.str"
+                  }
+                ]
+              },
+              {
+                "type": "builtins.NoneType"
+              }
+            ]
+          },
+          "default": {
+            "type": "builtins.NoneType",
+            "value": null
+          }
+        },
+        {
+          "name": "requires_toolsets",
+          "kind": "KEYWORD_ONLY",
+          "annotation": {
+            "origin": "typing.Union",
+            "module": "typing",
+            "arguments": [
+              {
+                "origin": "builtins.list",
+                "module": "typing",
+                "arguments": [
+                  {
+                    "type": "builtins.str"
+                  }
+                ]
+              },
+              {
+                "type": "builtins.NoneType"
+              }
+            ]
+          },
+          "default": {
+            "type": "builtins.NoneType",
+            "value": null
+          }
+        },
+        {
+          "name": "fallback_for_toolsets",
+          "kind": "KEYWORD_ONLY",
+          "annotation": {
+            "origin": "typing.Union",
+            "module": "typing",
+            "arguments": [
+              {
+                "origin": "builtins.list",
+                "module": "typing",
+                "arguments": [
+                  {
+                    "type": "builtins.str"
+                  }
+                ]
+              },
+              {
+                "type": "builtins.NoneType"
+              }
+            ]
+          },
+          "default": {
+            "type": "builtins.NoneType",
+            "value": null
+          }
+        },
+        {
+          "name": "when_to_use",
+          "kind": "KEYWORD_ONLY",
+          "annotation": {
+            "origin": "typing.Union",
+            "module": "typing",
+            "arguments": [
+              {
+                "type": "builtins.str"
+              },
+              {
+                "type": "builtins.NoneType"
+              }
+            ]
+          },
+          "default": {
+            "type": "builtins.NoneType",
+            "value": null
+          }
+        },
+        {
+          "name": "procedure",
+          "kind": "KEYWORD_ONLY",
+          "annotation": {
+            "origin": "typing.Union",
+            "module": "typing",
+            "arguments": [
+              {
+                "origin": "builtins.list",
+                "module": "typing",
+                "arguments": [
+                  {
+                    "type": "builtins.str"
+                  }
+                ]
+              },
+              {
+                "type": "builtins.NoneType"
+              }
+            ]
+          },
+          "default": {
+            "type": "builtins.NoneType",
+            "value": null
+          }
+        },
+        {
+          "name": "pitfalls",
+          "kind": "KEYWORD_ONLY",
+          "annotation": {
+            "origin": "typing.Union",
+            "module": "typing",
+            "arguments": [
+              {
+                "origin": "builtins.list",
+                "module": "typing",
+                "arguments": [
+                  {
+                    "type": "builtins.str"
+                  }
+                ]
+              },
+              {
+                "type": "builtins.NoneType"
+              }
+            ]
+          },
+          "default": {
+            "type": "builtins.NoneType",
+            "value": null
+          }
+        },
+        {
+          "name": "verification",
+          "kind": "KEYWORD_ONLY",
+          "annotation": {
+            "origin": "typing.Union",
+            "module": "typing",
+            "arguments": [
+              {
+                "origin": "builtins.list",
+                "module": "typing",
+                "arguments": [
+                  {
+                    "type": "builtins.str"
+                  }
+                ]
+              },
+              {
+                "type": "builtins.NoneType"
+              }
+            ]
+          },
+          "default": {
+            "type": "builtins.NoneType",
+            "value": null
+          }
+        },
+        {
+          "name": "status",
+          "kind": "KEYWORD_ONLY",
+          "annotation": {
+            "origin": "typing.Union",
+            "module": "typing",
+            "arguments": [
+              {
+                "type": "builtins.str"
+              },
+              {
+                "type": "builtins.NoneType"
+              }
+            ]
+          },
+          "default": {
+            "type": "builtins.NoneType",
+            "value": null
+          }
+        },
+        {
+          "name": "version",
+          "kind": "KEYWORD_ONLY",
+          "annotation": {
+            "origin": "typing.Union",
+            "module": "typing",
+            "arguments": [
+              {
+                "type": "builtins.str"
+              },
+              {
+                "type": "builtins.NoneType"
+              }
+            ]
+          },
+          "default": {
+            "type": "builtins.NoneType",
+            "value": null
+          }
+        },
+        {
+          "name": "confidence",
+          "kind": "KEYWORD_ONLY",
+          "annotation": {
+            "origin": "typing.Union",
+            "module": "typing",
+            "arguments": [
+              {
+                "type": "builtins.float"
+              },
+              {
+                "type": "builtins.NoneType"
+              }
+            ]
+          },
+          "default": {
+            "type": "builtins.NoneType",
+            "value": null
+          }
+        },
+        {
+          "name": "body_extra",
+          "kind": "KEYWORD_ONLY",
+          "annotation": {
+            "origin": "typing.Union",
+            "module": "typing",
+            "arguments": [
+              {
+                "type": "builtins.str"
+              },
+              {
+                "type": "builtins.NoneType"
+              }
+            ]
+          },
+          "default": {
+            "type": "builtins.NoneType",
+            "value": null
+          }
+        },
+        {
+          "name": "title",
+          "kind": "KEYWORD_ONLY",
+          "annotation": {
+            "origin": "typing.Union",
+            "module": "typing",
+            "arguments": [
+              {
+                "type": "builtins.str"
+              },
+              {
+                "type": "builtins.NoneType"
+              }
+            ]
+          },
+          "default": {
+            "type": "builtins.NoneType",
+            "value": null
+          }
+        },
+        {
+          "name": "problem",
+          "kind": "KEYWORD_ONLY",
+          "annotation": {
+            "origin": "typing.Union",
+            "module": "typing",
+            "arguments": [
+              {
+                "type": "builtins.str"
+              },
+              {
+                "type": "builtins.NoneType"
+              }
+            ]
+          },
+          "default": {
+            "type": "builtins.NoneType",
+            "value": null
+          }
+        },
+        {
+          "name": "solution",
+          "kind": "KEYWORD_ONLY",
+          "annotation": {
+            "origin": "typing.Union",
+            "module": "typing",
+            "arguments": [
+              {
+                "type": "builtins.str"
+              },
+              {
+                "type": "builtins.NoneType"
+              }
+            ]
+          },
+          "default": {
+            "type": "builtins.NoneType",
+            "value": null
+          }
+        },
+        {
+          "name": "steps",
+          "kind": "KEYWORD_ONLY",
+          "annotation": {
+            "origin": "typing.Union",
+            "module": "typing",
+            "arguments": [
+              {
+                "origin": "builtins.list",
+                "module": "typing",
+                "arguments": [
+                  {
+                    "type": "builtins.str"
+                  }
+                ]
+              },
+              {
+                "type": "builtins.NoneType"
+              }
+            ]
+          },
+          "default": {
+            "type": "builtins.NoneType",
+            "value": null
+          }
+        }
+      ],
+      "return": {
+        "type": "builtins.NoneType",
+        "value": null
+      },
+      "model_fields": {
+        "name": {
+          "annotation": {
+            "origin": "typing.Union",
+            "module": "typing",
+            "arguments": [
+              {
+                "type": "builtins.str"
+              },
+              {
+                "type": "builtins.NoneType"
+              }
+            ]
+          },
+          "default": {
+            "type": "builtins.NoneType",
+            "value": null
+          },
+          "validation": {
+            "alias": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "alias_priority": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "validation_alias": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "discriminator": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "validate_default": {
+              "type": "builtins.NoneType",
+              "value": null
+            }
+          }
+        },
+        "description": {
+          "annotation": {
+            "origin": "typing.Union",
+            "module": "typing",
+            "arguments": [
+              {
+                "type": "builtins.str"
+              },
+              {
+                "type": "builtins.NoneType"
+              }
+            ]
+          },
+          "default": {
+            "type": "builtins.NoneType",
+            "value": null
+          },
+          "validation": {
+            "alias": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "alias_priority": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "validation_alias": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "discriminator": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "validate_default": {
+              "type": "builtins.NoneType",
+              "value": null
+            }
+          }
+        },
+        "category": {
+          "annotation": {
+            "origin": "typing.Union",
+            "module": "typing",
+            "arguments": [
+              {
+                "type": "builtins.str"
+              },
+              {
+                "type": "builtins.NoneType"
+              }
+            ]
+          },
+          "default": {
+            "type": "builtins.NoneType",
+            "value": null
+          },
+          "validation": {
+            "alias": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "alias_priority": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "validation_alias": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "discriminator": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "validate_default": {
+              "type": "builtins.NoneType",
+              "value": null
+            }
+          }
+        },
+        "tags": {
+          "annotation": {
+            "origin": "typing.Union",
+            "module": "typing",
+            "arguments": [
+              {
+                "origin": "builtins.list",
+                "module": "typing",
+                "arguments": [
+                  {
+                    "type": "builtins.str"
+                  }
+                ]
+              },
+              {
+                "type": "builtins.NoneType"
+              }
+            ]
+          },
+          "default": {
+            "type": "builtins.NoneType",
+            "value": null
+          },
+          "validation": {
+            "alias": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "alias_priority": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "validation_alias": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "discriminator": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "validate_default": {
+              "type": "builtins.NoneType",
+              "value": null
+            }
+          }
+        },
+        "platforms": {
+          "annotation": {
+            "origin": "typing.Union",
+            "module": "typing",
+            "arguments": [
+              {
+                "origin": "builtins.list",
+                "module": "typing",
+                "arguments": [
+                  {
+                    "type": "builtins.str"
+                  }
+                ]
+              },
+              {
+                "type": "builtins.NoneType"
+              }
+            ]
+          },
+          "default": {
+            "type": "builtins.NoneType",
+            "value": null
+          },
+          "validation": {
+            "alias": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "alias_priority": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "validation_alias": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "discriminator": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "validate_default": {
+              "type": "builtins.NoneType",
+              "value": null
+            }
+          }
+        },
+        "requires_toolsets": {
+          "annotation": {
+            "origin": "typing.Union",
+            "module": "typing",
+            "arguments": [
+              {
+                "origin": "builtins.list",
+                "module": "typing",
+                "arguments": [
+                  {
+                    "type": "builtins.str"
+                  }
+                ]
+              },
+              {
+                "type": "builtins.NoneType"
+              }
+            ]
+          },
+          "default": {
+            "type": "builtins.NoneType",
+            "value": null
+          },
+          "validation": {
+            "alias": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "alias_priority": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "validation_alias": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "discriminator": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "validate_default": {
+              "type": "builtins.NoneType",
+              "value": null
+            }
+          }
+        },
+        "fallback_for_toolsets": {
+          "annotation": {
+            "origin": "typing.Union",
+            "module": "typing",
+            "arguments": [
+              {
+                "origin": "builtins.list",
+                "module": "typing",
+                "arguments": [
+                  {
+                    "type": "builtins.str"
+                  }
+                ]
+              },
+              {
+                "type": "builtins.NoneType"
+              }
+            ]
+          },
+          "default": {
+            "type": "builtins.NoneType",
+            "value": null
+          },
+          "validation": {
+            "alias": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "alias_priority": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "validation_alias": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "discriminator": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "validate_default": {
+              "type": "builtins.NoneType",
+              "value": null
+            }
+          }
+        },
+        "when_to_use": {
+          "annotation": {
+            "origin": "typing.Union",
+            "module": "typing",
+            "arguments": [
+              {
+                "type": "builtins.str"
+              },
+              {
+                "type": "builtins.NoneType"
+              }
+            ]
+          },
+          "default": {
+            "type": "builtins.NoneType",
+            "value": null
+          },
+          "validation": {
+            "alias": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "alias_priority": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "validation_alias": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "discriminator": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "validate_default": {
+              "type": "builtins.NoneType",
+              "value": null
+            }
+          }
+        },
+        "procedure": {
+          "annotation": {
+            "origin": "typing.Union",
+            "module": "typing",
+            "arguments": [
+              {
+                "origin": "builtins.list",
+                "module": "typing",
+                "arguments": [
+                  {
+                    "type": "builtins.str"
+                  }
+                ]
+              },
+              {
+                "type": "builtins.NoneType"
+              }
+            ]
+          },
+          "default": {
+            "type": "builtins.NoneType",
+            "value": null
+          },
+          "validation": {
+            "alias": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "alias_priority": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "validation_alias": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "discriminator": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "validate_default": {
+              "type": "builtins.NoneType",
+              "value": null
+            }
+          }
+        },
+        "pitfalls": {
+          "annotation": {
+            "origin": "typing.Union",
+            "module": "typing",
+            "arguments": [
+              {
+                "origin": "builtins.list",
+                "module": "typing",
+                "arguments": [
+                  {
+                    "type": "builtins.str"
+                  }
+                ]
+              },
+              {
+                "type": "builtins.NoneType"
+              }
+            ]
+          },
+          "default": {
+            "type": "builtins.NoneType",
+            "value": null
+          },
+          "validation": {
+            "alias": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "alias_priority": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "validation_alias": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "discriminator": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "validate_default": {
+              "type": "builtins.NoneType",
+              "value": null
+            }
+          }
+        },
+        "verification": {
+          "annotation": {
+            "origin": "typing.Union",
+            "module": "typing",
+            "arguments": [
+              {
+                "origin": "builtins.list",
+                "module": "typing",
+                "arguments": [
+                  {
+                    "type": "builtins.str"
+                  }
+                ]
+              },
+              {
+                "type": "builtins.NoneType"
+              }
+            ]
+          },
+          "default": {
+            "type": "builtins.NoneType",
+            "value": null
+          },
+          "validation": {
+            "alias": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "alias_priority": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "validation_alias": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "discriminator": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "validate_default": {
+              "type": "builtins.NoneType",
+              "value": null
+            }
+          }
+        },
+        "status": {
+          "annotation": {
+            "origin": "typing.Union",
+            "module": "typing",
+            "arguments": [
+              {
+                "type": "builtins.str"
+              },
+              {
+                "type": "builtins.NoneType"
+              }
+            ]
+          },
+          "default": {
+            "type": "builtins.NoneType",
+            "value": null
+          },
+          "validation": {
+            "alias": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "alias_priority": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "validation_alias": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "discriminator": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "validate_default": {
+              "type": "builtins.NoneType",
+              "value": null
+            }
+          }
+        },
+        "version": {
+          "annotation": {
+            "origin": "typing.Union",
+            "module": "typing",
+            "arguments": [
+              {
+                "type": "builtins.str"
+              },
+              {
+                "type": "builtins.NoneType"
+              }
+            ]
+          },
+          "default": {
+            "type": "builtins.NoneType",
+            "value": null
+          },
+          "validation": {
+            "alias": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "alias_priority": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "validation_alias": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "discriminator": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "validate_default": {
+              "type": "builtins.NoneType",
+              "value": null
+            }
+          }
+        },
+        "confidence": {
+          "annotation": {
+            "origin": "typing.Union",
+            "module": "typing",
+            "arguments": [
+              {
+                "type": "builtins.float"
+              },
+              {
+                "type": "builtins.NoneType"
+              }
+            ]
+          },
+          "default": {
+            "type": "builtins.NoneType",
+            "value": null
+          },
+          "validation": {
+            "alias": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "alias_priority": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "validation_alias": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "discriminator": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "validate_default": {
+              "type": "builtins.NoneType",
+              "value": null
+            }
+          }
+        },
+        "body_extra": {
+          "annotation": {
+            "origin": "typing.Union",
+            "module": "typing",
+            "arguments": [
+              {
+                "type": "builtins.str"
+              },
+              {
+                "type": "builtins.NoneType"
+              }
+            ]
+          },
+          "default": {
+            "type": "builtins.NoneType",
+            "value": null
+          },
+          "validation": {
+            "alias": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "alias_priority": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "validation_alias": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "discriminator": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "validate_default": {
+              "type": "builtins.NoneType",
+              "value": null
+            }
+          }
+        },
+        "title": {
+          "annotation": {
+            "origin": "typing.Union",
+            "module": "typing",
+            "arguments": [
+              {
+                "type": "builtins.str"
+              },
+              {
+                "type": "builtins.NoneType"
+              }
+            ]
+          },
+          "default": {
+            "type": "builtins.NoneType",
+            "value": null
+          },
+          "validation": {
+            "alias": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "alias_priority": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "validation_alias": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "discriminator": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "validate_default": {
+              "type": "builtins.NoneType",
+              "value": null
+            }
+          }
+        },
+        "problem": {
+          "annotation": {
+            "origin": "typing.Union",
+            "module": "typing",
+            "arguments": [
+              {
+                "type": "builtins.str"
+              },
+              {
+                "type": "builtins.NoneType"
+              }
+            ]
+          },
+          "default": {
+            "type": "builtins.NoneType",
+            "value": null
+          },
+          "validation": {
+            "alias": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "alias_priority": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "validation_alias": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "discriminator": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "validate_default": {
+              "type": "builtins.NoneType",
+              "value": null
+            }
+          }
+        },
+        "solution": {
+          "annotation": {
+            "origin": "typing.Union",
+            "module": "typing",
+            "arguments": [
+              {
+                "type": "builtins.str"
+              },
+              {
+                "type": "builtins.NoneType"
+              }
+            ]
+          },
+          "default": {
+            "type": "builtins.NoneType",
+            "value": null
+          },
+          "validation": {
+            "alias": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "alias_priority": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "validation_alias": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "discriminator": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "validate_default": {
+              "type": "builtins.NoneType",
+              "value": null
+            }
+          }
+        },
+        "steps": {
+          "annotation": {
+            "origin": "typing.Union",
+            "module": "typing",
+            "arguments": [
+              {
+                "origin": "builtins.list",
+                "module": "typing",
+                "arguments": [
+                  {
+                    "type": "builtins.str"
+                  }
+                ]
+              },
+              {
+                "type": "builtins.NoneType"
+              }
+            ]
+          },
+          "default": {
+            "type": "builtins.NoneType",
+            "value": null
+          },
+          "validation": {
+            "alias": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "alias_priority": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "validation_alias": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "discriminator": {
+              "type": "builtins.NoneType",
+              "value": null
+            },
+            "validate_default": {
+              "type": "builtins.NoneType",
+              "value": null
+            }
+          }
+        }
+      },
+      "model_config": {
+        "type": "builtins.dict",
+        "items": {}
+      }
+    },
+    "_skill_test_task": {
+      "parameters": [
+        {
+          "name": "skill",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "type": "builtins.dict"
+          },
+          "default": {
+            "empty": true
+          }
+        }
+      ],
+      "return": {
+        "type": "builtins.str"
+      }
+    },
+    "_skill_baseline_task": {
+      "parameters": [
+        {
+          "name": "skill",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "type": "builtins.dict"
+          },
+          "default": {
+            "empty": true
+          }
+        }
+      ],
+      "return": {
+        "type": "builtins.str"
+      }
+    },
+    "_skill_test_messages": {
+      "parameters": [
+        {
+          "name": "md",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "type": "builtins.str"
+          },
+          "default": {
+            "empty": true
+          }
+        },
+        {
+          "name": "task",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "type": "builtins.str"
+          },
+          "default": {
+            "empty": true
+          }
+        }
+      ],
+      "return": {
+        "origin": "builtins.list",
+        "module": "builtins",
+        "arguments": [
+          {
+            "type": "builtins.dict"
+          }
+        ]
+      }
+    },
+    "_skill_baseline_messages": {
+      "parameters": [
+        {
+          "name": "task",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "type": "builtins.str"
+          },
+          "default": {
+            "empty": true
+          }
+        }
+      ],
+      "return": {
+        "origin": "builtins.list",
+        "module": "builtins",
+        "arguments": [
+          {
+            "type": "builtins.dict"
+          }
+        ]
+      }
+    },
+    "_eval_skill_run": {
+      "parameters": [
+        {
+          "name": "skill_md",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "type": "builtins.str"
+          },
+          "default": {
+            "empty": true
+          }
+        },
+        {
+          "name": "task",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "type": "builtins.str"
+          },
+          "default": {
+            "empty": true
+          }
+        },
+        {
+          "name": "transcript",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "type": "builtins.str"
+          },
+          "default": {
+            "empty": true
+          }
+        },
+        {
+          "name": "url",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "type": "builtins.str"
+          },
+          "default": {
+            "empty": true
+          }
+        },
+        {
+          "name": "model",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "type": "builtins.str"
+          },
+          "default": {
+            "empty": true
+          }
+        },
+        {
+          "name": "headers",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "origin": "typing.Union",
+            "module": "typing",
+            "arguments": [
+              {
+                "type": "builtins.dict"
+              },
+              {
+                "type": "builtins.NoneType"
+              }
+            ]
+          },
+          "default": {
+            "empty": true
+          }
+        },
+        {
+          "name": "baseline_transcript",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "type": "builtins.str"
+          },
+          "default": {
+            "type": "builtins.str",
+            "value": ""
+          }
+        },
+        {
+          "name": "skill_stats",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "origin": "typing.Union",
+            "module": "typing",
+            "arguments": [
+              {
+                "type": "builtins.dict"
+              },
+              {
+                "type": "builtins.NoneType"
+              }
+            ]
+          },
+          "default": {
+            "type": "builtins.NoneType",
+            "value": null
+          }
+        },
+        {
+          "name": "baseline_stats",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "origin": "typing.Union",
+            "module": "typing",
+            "arguments": [
+              {
+                "type": "builtins.dict"
+              },
+              {
+                "type": "builtins.NoneType"
+              }
+            ]
+          },
+          "default": {
+            "type": "builtins.NoneType",
+            "value": null
+          }
+        },
+        {
+          "name": "workload",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "type": "builtins.str"
+          },
+          "default": {
+            "type": "builtins.str",
+            "value": "foreground"
+          }
+        },
+        {
+          "name": "owner",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "origin": "typing.Union",
+            "module": "typing",
+            "arguments": [
+              {
+                "type": "builtins.str"
+              },
+              {
+                "type": "builtins.NoneType"
+              }
+            ]
+          },
+          "default": {
+            "type": "builtins.NoneType",
+            "value": null
+          }
+        }
+      ],
+      "return": {
+        "type": "builtins.dict"
+      }
+    },
+    "_eval_skill_necessity": {
+      "parameters": [
+        {
+          "name": "skill_md",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "type": "builtins.str"
+          },
+          "default": {
+            "empty": true
+          }
+        },
+        {
+          "name": "others",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "type": "builtins.list"
+          },
+          "default": {
+            "empty": true
+          }
+        },
+        {
+          "name": "url",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "type": "builtins.str"
+          },
+          "default": {
+            "empty": true
+          }
+        },
+        {
+          "name": "model",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "type": "builtins.str"
+          },
+          "default": {
+            "empty": true
+          }
+        },
+        {
+          "name": "headers",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "origin": "typing.Union",
+            "module": "typing",
+            "arguments": [
+              {
+                "type": "builtins.dict"
+              },
+              {
+                "type": "builtins.NoneType"
+              }
+            ]
+          },
+          "default": {
+            "empty": true
+          }
+        },
+        {
+          "name": "workload",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "type": "builtins.str"
+          },
+          "default": {
+            "type": "builtins.str",
+            "value": "foreground"
+          }
+        },
+        {
+          "name": "owner",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "origin": "typing.Union",
+            "module": "typing",
+            "arguments": [
+              {
+                "type": "builtins.str"
+              },
+              {
+                "type": "builtins.NoneType"
+              }
+            ]
+          },
+          "default": {
+            "type": "builtins.NoneType",
+            "value": null
+          }
+        }
+      ],
+      "return": {
+        "origin": "typing.Union",
+        "module": "typing",
+        "arguments": [
+          {
+            "type": "builtins.dict"
+          },
+          {
+            "type": "builtins.NoneType"
+          }
+        ]
+      }
+    },
+    "_should_check_retrieval_precision": {
+      "parameters": [
+        {
+          "name": "skill",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "type": "builtins.dict"
+          },
+          "default": {
+            "empty": true
+          }
+        }
+      ],
+      "return": {
+        "type": "builtins.bool"
+      }
+    },
+    "_eval_skill_retrieval_precision": {
+      "parameters": [
+        {
+          "name": "skill_md",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "type": "builtins.str"
+          },
+          "default": {
+            "empty": true
+          }
+        },
+        {
+          "name": "others",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "type": "builtins.list"
+          },
+          "default": {
+            "empty": true
+          }
+        },
+        {
+          "name": "url",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "type": "builtins.str"
+          },
+          "default": {
+            "empty": true
+          }
+        },
+        {
+          "name": "model",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "type": "builtins.str"
+          },
+          "default": {
+            "empty": true
+          }
+        },
+        {
+          "name": "headers",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "origin": "typing.Union",
+            "module": "typing",
+            "arguments": [
+              {
+                "type": "builtins.dict"
+              },
+              {
+                "type": "builtins.NoneType"
+              }
+            ]
+          },
+          "default": {
+            "empty": true
+          }
+        },
+        {
+          "name": "workload",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "type": "builtins.str"
+          },
+          "default": {
+            "type": "builtins.str",
+            "value": "foreground"
+          }
+        },
+        {
+          "name": "owner",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "origin": "typing.Union",
+            "module": "typing",
+            "arguments": [
+              {
+                "type": "builtins.str"
+              },
+              {
+                "type": "builtins.NoneType"
+              }
+            ]
+          },
+          "default": {
+            "type": "builtins.NoneType",
+            "value": null
+          }
+        }
+      ],
+      "return": {
+        "origin": "typing.Union",
+        "module": "typing",
+        "arguments": [
+          {
+            "type": "builtins.dict"
+          },
+          {
+            "type": "builtins.NoneType"
+          }
+        ]
+      }
+    },
+    "_run_skill_test_job": {
+      "parameters": [
+        {
+          "name": "key",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "empty": true
+          },
+          "default": {
+            "empty": true
+          }
+        },
+        {
+          "name": "name",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "empty": true
+          },
+          "default": {
+            "empty": true
+          }
+        },
+        {
+          "name": "md",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "empty": true
+          },
+          "default": {
+            "empty": true
+          }
+        },
+        {
+          "name": "task",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "empty": true
+          },
+          "default": {
+            "empty": true
+          }
+        },
+        {
+          "name": "url",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "empty": true
+          },
+          "default": {
+            "empty": true
+          }
+        },
+        {
+          "name": "model",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "empty": true
+          },
+          "default": {
+            "empty": true
+          }
+        },
+        {
+          "name": "headers",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "empty": true
+          },
+          "default": {
+            "empty": true
+          }
+        },
+        {
+          "name": "owner",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "empty": true
+          },
+          "default": {
+            "empty": true
+          }
+        },
+        {
+          "name": "skills_manager",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "empty": true
+          },
+          "default": {
+            "type": "builtins.NoneType",
+            "value": null
+          }
+        },
+        {
+          "name": "messages",
+          "kind": "KEYWORD_ONLY",
+          "annotation": {
+            "empty": true
+          },
+          "default": {
+            "type": "builtins.NoneType",
+            "value": null
+          }
+        },
+        {
+          "name": "transcript",
+          "kind": "KEYWORD_ONLY",
+          "annotation": {
+            "empty": true
+          },
+          "default": {
+            "type": "builtins.NoneType",
+            "value": null
+          }
+        },
+        {
+          "name": "exact_approval",
+          "kind": "KEYWORD_ONLY",
+          "annotation": {
+            "empty": true
+          },
+          "default": {
+            "type": "builtins.NoneType",
+            "value": null
+          }
+        },
+        {
+          "name": "request_authority",
+          "kind": "KEYWORD_ONLY",
+          "annotation": {
+            "empty": true
+          },
+          "default": {
+            "type": "builtins.NoneType",
+            "value": null
+          }
+        }
+      ],
+      "return": {
+        "empty": true
+      }
+    },
+    "_audit_auto_publish_policy": {
+      "parameters": [
+        {
+          "name": "owner",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "empty": true
+          },
+          "default": {
+            "empty": true
+          }
+        }
+      ],
+      "return": {
+        "origin": "builtins.tuple",
+        "module": "builtins",
+        "arguments": [
+          {
+            "type": "builtins.bool"
+          },
+          {
+            "type": "builtins.float"
+          }
+        ]
+      }
+    },
+    "_skill_duplicate_blocker": {
+      "parameters": [
+        {
+          "name": "skills_manager",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "empty": true
+          },
+          "default": {
+            "empty": true
+          }
+        },
+        {
+          "name": "name",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "type": "builtins.str"
+          },
+          "default": {
+            "empty": true
+          }
+        },
+        {
+          "name": "owner",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "empty": true
+          },
+          "default": {
+            "empty": true
+          }
+        }
+      ],
+      "return": {
+        "origin": "typing.Union",
+        "module": "typing",
+        "arguments": [
+          {
+            "type": "builtins.str"
+          },
+          {
+            "type": "builtins.NoneType"
+          }
+        ]
+      }
+    },
+    "_finalize_audit_batch": {
+      "parameters": [
+        {
+          "name": "skills_manager",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "empty": true
+          },
+          "default": {
+            "empty": true
+          }
+        },
+        {
+          "name": "results",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "origin": "builtins.list",
+            "module": "builtins",
+            "arguments": [
+              {
+                "type": "builtins.dict"
+              }
+            ]
+          },
+          "default": {
+            "empty": true
+          }
+        },
+        {
+          "name": "owner",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "empty": true
+          },
+          "default": {
+            "empty": true
+          }
+        },
+        {
+          "name": "log",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "empty": true
+          },
+          "default": {
+            "empty": true
+          }
+        }
+      ],
+      "return": {
+        "type": "builtins.NoneType",
+        "value": null
+      }
+    },
+    "_audit_flag_text": {
+      "parameters": [
+        {
+          "name": "parts",
+          "kind": "VAR_POSITIONAL",
+          "annotation": {
+            "empty": true
+          },
+          "default": {
+            "empty": true
+          }
+        }
+      ],
+      "return": {
+        "type": "builtins.str"
+      }
+    },
+    "_audit_utility_blocker": {
+      "parameters": [
+        {
+          "name": "skill",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "origin": "typing.Union",
+            "module": "typing",
+            "arguments": [
+              {
+                "type": "builtins.dict"
+              },
+              {
+                "type": "builtins.NoneType"
+              }
+            ]
+          },
+          "default": {
+            "empty": true
+          }
+        },
+        {
+          "name": "necessity",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "origin": "typing.Union",
+            "module": "typing",
+            "arguments": [
+              {
+                "type": "builtins.dict"
+              },
+              {
+                "type": "builtins.NoneType"
+              }
+            ]
+          },
+          "default": {
+            "empty": true
+          }
+        },
+        {
+          "name": "verdict_data",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "origin": "typing.Union",
+            "module": "typing",
+            "arguments": [
+              {
+                "type": "builtins.dict"
+              },
+              {
+                "type": "builtins.NoneType"
+              }
+            ]
+          },
+          "default": {
+            "empty": true
+          }
+        }
+      ],
+      "return": {
+        "origin": "typing.Union",
+        "module": "typing",
+        "arguments": [
+          {
+            "type": "builtins.str"
+          },
+          {
+            "type": "builtins.NoneType"
+          }
+        ]
+      }
+    },
+    "_audit_finalize_status": {
+      "parameters": [
+        {
+          "name": "skills_manager",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "empty": true
+          },
+          "default": {
+            "empty": true
+          }
+        },
+        {
+          "name": "name",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "type": "builtins.str"
+          },
+          "default": {
+            "empty": true
+          }
+        },
+        {
+          "name": "owner",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "empty": true
+          },
+          "default": {
+            "empty": true
+          }
+        },
+        {
+          "name": "verdict",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "type": "builtins.str"
+          },
+          "default": {
+            "empty": true
+          }
+        },
+        {
+          "name": "confidence",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "origin": "typing.Union",
+            "module": "typing",
+            "arguments": [
+              {
+                "type": "builtins.float"
+              },
+              {
+                "type": "builtins.NoneType"
+              }
+            ]
+          },
+          "default": {
+            "empty": true
+          }
+        },
+        {
+          "name": "necessity",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "origin": "typing.Union",
+            "module": "typing",
+            "arguments": [
+              {
+                "type": "builtins.dict"
+              },
+              {
+                "type": "builtins.NoneType"
+              }
+            ]
+          },
+          "default": {
+            "type": "builtins.NoneType",
+            "value": null
+          }
+        },
+        {
+          "name": "verdict_data",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "origin": "typing.Union",
+            "module": "typing",
+            "arguments": [
+              {
+                "type": "builtins.dict"
+              },
+              {
+                "type": "builtins.NoneType"
+              }
+            ]
+          },
+          "default": {
+            "type": "builtins.NoneType",
+            "value": null
+          }
+        }
+      ],
+      "return": {
+        "type": "builtins.str"
+      }
+    },
+    "_apply_skill_md": {
+      "parameters": [
+        {
+          "name": "skills_manager",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "empty": true
+          },
+          "default": {
+            "empty": true
+          }
+        },
+        {
+          "name": "name",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "type": "builtins.str"
+          },
+          "default": {
+            "empty": true
+          }
+        },
+        {
+          "name": "md",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "type": "builtins.str"
+          },
+          "default": {
+            "empty": true
+          }
+        },
+        {
+          "name": "owner",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "empty": true
+          },
+          "default": {
+            "empty": true
+          }
+        }
+      ],
+      "return": {
+        "type": "builtins.bool"
+      }
+    },
+    "_run_skill_audit_arm": {
+      "parameters": [
+        {
+          "name": "messages",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "origin": "builtins.list",
+            "module": "builtins",
+            "arguments": [
+              {
+                "type": "builtins.dict"
+              }
+            ]
+          },
+          "default": {
+            "empty": true
+          }
+        },
+        {
+          "name": "url",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "empty": true
+          },
+          "default": {
+            "empty": true
+          }
+        },
+        {
+          "name": "model",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "empty": true
+          },
+          "default": {
+            "empty": true
+          }
+        },
+        {
+          "name": "headers",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "empty": true
+          },
+          "default": {
+            "empty": true
+          }
+        },
+        {
+          "name": "owner",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "empty": true
+          },
+          "default": {
+            "empty": true
+          }
+        },
+        {
+          "name": "workload",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "type": "builtins.str"
+          },
+          "default": {
+            "type": "builtins.str",
+            "value": "foreground"
+          }
+        }
+      ],
+      "return": {
+        "origin": "builtins.tuple",
+        "module": "builtins",
+        "arguments": [
+          {
+            "type": "builtins.str"
+          },
+          {
+            "type": "builtins.dict"
+          },
+          {
+            "origin": "typing.Union",
+            "module": "typing",
+            "arguments": [
+              {
+                "type": "builtins.dict"
+              },
+              {
+                "type": "builtins.NoneType"
+              }
+            ]
+          }
+        ]
+      }
+    },
+    "_run_skill_test_once": {
+      "parameters": [
+        {
+          "name": "md",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "type": "builtins.str"
+          },
+          "default": {
+            "empty": true
+          }
+        },
+        {
+          "name": "task",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "type": "builtins.str"
+          },
+          "default": {
+            "empty": true
+          }
+        },
+        {
+          "name": "url",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "empty": true
+          },
+          "default": {
+            "empty": true
+          }
+        },
+        {
+          "name": "model",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "empty": true
+          },
+          "default": {
+            "empty": true
+          }
+        },
+        {
+          "name": "headers",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "empty": true
+          },
+          "default": {
+            "empty": true
+          }
+        },
+        {
+          "name": "owner",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "empty": true
+          },
+          "default": {
+            "empty": true
+          }
+        },
+        {
+          "name": "workload",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "type": "builtins.str"
+          },
+          "default": {
+            "type": "builtins.str",
+            "value": "foreground"
+          }
+        }
+      ],
+      "return": {
+        "type": "builtins.tuple"
+      }
+    },
+    "_improve_skill_md": {
+      "parameters": [
+        {
+          "name": "skill_md",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "type": "builtins.str"
+          },
+          "default": {
+            "empty": true
+          }
+        },
+        {
+          "name": "verdict",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "type": "builtins.dict"
+          },
+          "default": {
+            "empty": true
+          }
+        },
+        {
+          "name": "transcript",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "type": "builtins.str"
+          },
+          "default": {
+            "empty": true
+          }
+        },
+        {
+          "name": "url",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "empty": true
+          },
+          "default": {
+            "empty": true
+          }
+        },
+        {
+          "name": "model",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "empty": true
+          },
+          "default": {
+            "empty": true
+          }
+        },
+        {
+          "name": "headers",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "empty": true
+          },
+          "default": {
+            "empty": true
+          }
+        },
+        {
+          "name": "workload",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "type": "builtins.str"
+          },
+          "default": {
+            "type": "builtins.str",
+            "value": "foreground"
+          }
+        },
+        {
+          "name": "owner",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "origin": "typing.Union",
+            "module": "typing",
+            "arguments": [
+              {
+                "type": "builtins.str"
+              },
+              {
+                "type": "builtins.NoneType"
+              }
+            ]
+          },
+          "default": {
+            "type": "builtins.NoneType",
+            "value": null
+          }
+        }
+      ],
+      "return": {
+        "empty": true
+      }
+    },
+    "_audit_one_skill": {
+      "parameters": [
+        {
+          "name": "skills_manager",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "empty": true
+          },
+          "default": {
+            "empty": true
+          }
+        },
+        {
+          "name": "skill",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "empty": true
+          },
+          "default": {
+            "empty": true
+          }
+        },
+        {
+          "name": "url",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "empty": true
+          },
+          "default": {
+            "empty": true
+          }
+        },
+        {
+          "name": "model",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "empty": true
+          },
+          "default": {
+            "empty": true
+          }
+        },
+        {
+          "name": "headers",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "empty": true
+          },
+          "default": {
+            "empty": true
+          }
+        },
+        {
+          "name": "teacher",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "empty": true
+          },
+          "default": {
+            "empty": true
+          }
+        },
+        {
+          "name": "owner",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "empty": true
+          },
+          "default": {
+            "empty": true
+          }
+        },
+        {
+          "name": "log",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "empty": true
+          },
+          "default": {
+            "empty": true
+          }
+        },
+        {
+          "name": "workload",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "type": "builtins.str"
+          },
+          "default": {
+            "type": "builtins.str",
+            "value": "foreground"
+          }
+        }
+      ],
+      "return": {
+        "type": "builtins.dict"
+      }
+    },
+    "_run_audit_all_job": {
+      "parameters": [
+        {
+          "name": "key",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "empty": true
+          },
+          "default": {
+            "empty": true
+          }
+        },
+        {
+          "name": "skills_manager",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "empty": true
+          },
+          "default": {
+            "empty": true
+          }
+        },
+        {
+          "name": "names",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "empty": true
+          },
+          "default": {
+            "empty": true
+          }
+        },
+        {
+          "name": "url",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "empty": true
+          },
+          "default": {
+            "empty": true
+          }
+        },
+        {
+          "name": "model",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "empty": true
+          },
+          "default": {
+            "empty": true
+          }
+        },
+        {
+          "name": "headers",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "empty": true
+          },
+          "default": {
+            "empty": true
+          }
+        },
+        {
+          "name": "teacher",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "empty": true
+          },
+          "default": {
+            "empty": true
+          }
+        },
+        {
+          "name": "owner",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "empty": true
+          },
+          "default": {
+            "empty": true
+          }
+        },
+        {
+          "name": "workload",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "type": "builtins.str"
+          },
+          "default": {
+            "type": "builtins.str",
+            "value": "foreground"
+          }
+        }
+      ],
+      "return": {
+        "empty": true
+      }
+    },
+    "_resolve_audit_models": {
+      "parameters": [
+        {
+          "name": "owner",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "empty": true
+          },
+          "default": {
+            "type": "builtins.NoneType",
+            "value": null
+          }
+        },
+        {
+          "name": "model_spec",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "empty": true
+          },
+          "default": {
+            "type": "builtins.NoneType",
+            "value": null
+          }
+        },
+        {
+          "name": "endpoint_url",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "empty": true
+          },
+          "default": {
+            "type": "builtins.NoneType",
+            "value": null
+          }
+        }
+      ],
+      "return": {
+        "empty": true
+      }
+    },
+    "run_scheduled_skill_audit": {
+      "parameters": [
+        {
+          "name": "skills_manager",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "type": "services.memory.skills.SkillsManager"
+          },
+          "default": {
+            "empty": true
+          }
+        },
+        {
+          "name": "owner",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "origin": "typing.Union",
+            "module": "typing",
+            "arguments": [
+              {
+                "type": "builtins.str"
+              },
+              {
+                "type": "builtins.NoneType"
+              }
+            ]
+          },
+          "default": {
+            "type": "builtins.NoneType",
+            "value": null
+          }
+        },
+        {
+          "name": "max_skills",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "type": "builtins.int"
+          },
+          "default": {
+            "type": "builtins.int",
+            "value": 8
+          }
+        }
+      ],
+      "return": {
+        "type": "builtins.dict"
+      }
+    },
+    "setup_skills_routes": {
+      "parameters": [
+        {
+          "name": "skills_manager",
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "annotation": {
+            "type": "services.memory.skills.SkillsManager"
+          },
+          "default": {
+            "empty": true
+          }
+        }
+      ],
+      "return": {
+        "type": "fastapi.routing.APIRouter"
+      }
+    }
+  }
+}
diff --git a/tests/fixtures/skills_openapi_baseline.json b/tests/fixtures/skills_openapi_baseline.json
new file mode 100644
index 000000000..e34aa171f
--- /dev/null
+++ b/tests/fixtures/skills_openapi_baseline.json
@@ -0,0 +1,1226 @@
+{
+  "components": {
+    "schemas": {
+      "HTTPValidationError": {
+        "properties": {
+          "detail": {
+            "items": {
+              "$ref": "#/components/schemas/ValidationError"
+            },
+            "title": "Detail",
+            "type": "array"
+          }
+        },
+        "title": "HTTPValidationError",
+        "type": "object"
+      },
+      "SkillAddRequest": {
+        "properties": {
+          "category": {
+            "default": "general",
+            "maxLength": 40,
+            "title": "Category",
+            "type": "string"
+          },
+          "confidence": {
+            "default": 0.8,
+            "title": "Confidence",
+            "type": "number"
+          },
+          "description": {
+            "anyOf": [
+              {
+                "maxLength": 200,
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Description"
+          },
+          "fallback_for_toolsets": {
+            "items": {
+              "type": "string"
+            },
+            "title": "Fallback For Toolsets",
+            "type": "array"
+          },
+          "name": {
+            "anyOf": [
+              {
+                "maxLength": 80,
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Name"
+          },
+          "pitfalls": {
+            "items": {
+              "type": "string"
+            },
+            "title": "Pitfalls",
+            "type": "array"
+          },
+          "platforms": {
+            "items": {
+              "type": "string"
+            },
+            "title": "Platforms",
+            "type": "array"
+          },
+          "problem": {
+            "anyOf": [
+              {
+                "maxLength": 2000,
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Problem"
+          },
+          "procedure": {
+            "items": {
+              "type": "string"
+            },
+            "title": "Procedure",
+            "type": "array"
+          },
+          "requires_toolsets": {
+            "items": {
+              "type": "string"
+            },
+            "title": "Requires Toolsets",
+            "type": "array"
+          },
+          "session_id": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Session Id"
+          },
+          "solution": {
+            "anyOf": [
+              {
+                "maxLength": 5000,
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Solution"
+          },
+          "source": {
+            "default": "user",
+            "title": "Source",
+            "type": "string"
+          },
+          "status": {
+            "default": "draft",
+            "title": "Status",
+            "type": "string"
+          },
+          "steps": {
+            "items": {
+              "type": "string"
+            },
+            "title": "Steps",
+            "type": "array"
+          },
+          "tags": {
+            "items": {
+              "type": "string"
+            },
+            "title": "Tags",
+            "type": "array"
+          },
+          "teacher_model": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Teacher Model"
+          },
+          "title": {
+            "anyOf": [
+              {
+                "maxLength": 200,
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Title"
+          },
+          "verification": {
+            "items": {
+              "type": "string"
+            },
+            "title": "Verification",
+            "type": "array"
+          },
+          "version": {
+            "default": "1.0.0",
+            "title": "Version",
+            "type": "string"
+          },
+          "when_to_use": {
+            "anyOf": [
+              {
+                "maxLength": 2000,
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "When To Use"
+          }
+        },
+        "title": "SkillAddRequest",
+        "type": "object"
+      },
+      "SkillImportUrlRequest": {
+        "properties": {
+          "url": {
+            "maxLength": 2000,
+            "minLength": 8,
+            "title": "Url",
+            "type": "string"
+          }
+        },
+        "required": [
+          "url"
+        ],
+        "title": "SkillImportUrlRequest",
+        "type": "object"
+      },
+      "SkillUpdateRequest": {
+        "properties": {
+          "body_extra": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Body Extra"
+          },
+          "category": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Category"
+          },
+          "confidence": {
+            "anyOf": [
+              {
+                "type": "number"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Confidence"
+          },
+          "description": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Description"
+          },
+          "fallback_for_toolsets": {
+            "anyOf": [
+              {
+                "items": {
+                  "type": "string"
+                },
+                "type": "array"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Fallback For Toolsets"
+          },
+          "name": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Name"
+          },
+          "pitfalls": {
+            "anyOf": [
+              {
+                "items": {
+                  "type": "string"
+                },
+                "type": "array"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Pitfalls"
+          },
+          "platforms": {
+            "anyOf": [
+              {
+                "items": {
+                  "type": "string"
+                },
+                "type": "array"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Platforms"
+          },
+          "problem": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Problem"
+          },
+          "procedure": {
+            "anyOf": [
+              {
+                "items": {
+                  "type": "string"
+                },
+                "type": "array"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Procedure"
+          },
+          "requires_toolsets": {
+            "anyOf": [
+              {
+                "items": {
+                  "type": "string"
+                },
+                "type": "array"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Requires Toolsets"
+          },
+          "solution": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Solution"
+          },
+          "status": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Status"
+          },
+          "steps": {
+            "anyOf": [
+              {
+                "items": {
+                  "type": "string"
+                },
+                "type": "array"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Steps"
+          },
+          "tags": {
+            "anyOf": [
+              {
+                "items": {
+                  "type": "string"
+                },
+                "type": "array"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Tags"
+          },
+          "title": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Title"
+          },
+          "verification": {
+            "anyOf": [
+              {
+                "items": {
+                  "type": "string"
+                },
+                "type": "array"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Verification"
+          },
+          "version": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Version"
+          },
+          "when_to_use": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "When To Use"
+          }
+        },
+        "title": "SkillUpdateRequest",
+        "type": "object"
+      },
+      "ValidationError": {
+        "properties": {
+          "ctx": {
+            "title": "Context",
+            "type": "object"
+          },
+          "input": {
+            "title": "Input"
+          },
+          "loc": {
+            "items": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "integer"
+                }
+              ]
+            },
+            "title": "Location",
+            "type": "array"
+          },
+          "msg": {
+            "title": "Message",
+            "type": "string"
+          },
+          "type": {
+            "title": "Error Type",
+            "type": "string"
+          }
+        },
+        "required": [
+          "loc",
+          "msg",
+          "type"
+        ],
+        "title": "ValidationError",
+        "type": "object"
+      }
+    }
+  },
+  "info": {
+    "title": "FastAPI",
+    "version": "0.1.0"
+  },
+  "openapi": "3.1.0",
+  "paths": {
+    "/api/skills": {
+      "get": {
+        "operationId": "list_skills_api_skills_get",
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {}
+              }
+            },
+            "description": "Successful Response"
+          }
+        },
+        "summary": "List Skills",
+        "tags": [
+          "skills"
+        ]
+      }
+    },
+    "/api/skills/add": {
+      "post": {
+        "operationId": "add_skill_api_skills_add_post",
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/SkillAddRequest"
+              }
+            }
+          },
+          "required": true
+        },
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {}
+              }
+            },
+            "description": "Successful Response"
+          },
+          "422": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HTTPValidationError"
+                }
+              }
+            },
+            "description": "Validation Error"
+          }
+        },
+        "summary": "Add Skill",
+        "tags": [
+          "skills"
+        ]
+      }
+    },
+    "/api/skills/audit-all": {
+      "post": {
+        "description": "Kick off a background audit of skills: each is tested + judged; if it\nneeds work the model self-edits and retries; if a teacher model is\nconfigured it escalates; a skill that still fails is demoted to draft\n(never deleted). Poll GET /audit-status. Body:\n{scope: 'drafts'|'unchecked'|'all', names?: [...], skip_audited?: bool}. Default 'all'\nmeans every visible skill, including already-published skills, so audit\ncan publish or demote according to the confidence threshold.",
+        "operationId": "audit_all_skills_api_skills_audit_all_post",
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {}
+              }
+            },
+            "description": "Successful Response"
+          }
+        },
+        "summary": "Audit All Skills",
+        "tags": [
+          "skills"
+        ]
+      }
+    },
+    "/api/skills/audit-all/cancel": {
+      "post": {
+        "operationId": "audit_cancel_api_skills_audit_all_cancel_post",
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {}
+              }
+            },
+            "description": "Successful Response"
+          }
+        },
+        "summary": "Audit Cancel",
+        "tags": [
+          "skills"
+        ]
+      }
+    },
+    "/api/skills/audit-all/status": {
+      "get": {
+        "operationId": "audit_status_api_skills_audit_all_status_get",
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {}
+              }
+            },
+            "description": "Successful Response"
+          }
+        },
+        "summary": "Audit Status",
+        "tags": [
+          "skills"
+        ]
+      }
+    },
+    "/api/skills/builtin": {
+      "get": {
+        "description": "Read-only list of the agent's built-in tool capabilities (research,\nsessions, tasks, email, etc.) \u2014 the things it natively knows how to do.\nSurfaced so the Skills tab can show them in a separate \"Built-in\"\nsection alongside the user's learned SKILL.md skills. Sourced from\nagent_loop.TOOL_SECTIONS (the same descriptions the model is given).",
+        "operationId": "list_builtin_skills_api_skills_builtin_get",
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {}
+              }
+            },
+            "description": "Successful Response"
+          }
+        },
+        "summary": "List Builtin Skills",
+        "tags": [
+          "skills"
+        ]
+      }
+    },
+    "/api/skills/builtin/{name}": {
+      "delete": {
+        "description": "Revert a built-in tool to its shipped instruction block.",
+        "operationId": "reset_builtin_override_api_skills_builtin__name__delete",
+        "parameters": [
+          {
+            "in": "path",
+            "name": "name",
+            "required": true,
+            "schema": {
+              "title": "Name",
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {}
+              }
+            },
+            "description": "Successful Response"
+          },
+          "422": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HTTPValidationError"
+                }
+              }
+            },
+            "description": "Validation Error"
+          }
+        },
+        "summary": "Reset Builtin Override",
+        "tags": [
+          "skills"
+        ]
+      },
+      "get": {
+        "description": "Full text of a built-in tool's instruction block \u2014 the override\nif one is set, plus the shipped default (for the revert button).",
+        "operationId": "get_builtin_skill_api_skills_builtin__name__get",
+        "parameters": [
+          {
+            "in": "path",
+            "name": "name",
+            "required": true,
+            "schema": {
+              "title": "Name",
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {}
+              }
+            },
+            "description": "Successful Response"
+          },
+          "422": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HTTPValidationError"
+                }
+              }
+            },
+            "description": "Validation Error"
+          }
+        },
+        "summary": "Get Builtin Skill",
+        "tags": [
+          "skills"
+        ]
+      },
+      "put": {
+        "description": "Save a user override for a built-in tool's instruction block.\nWARNING surfaced in the UI \u2014 this changes how the assistant is\ntold to use a native tool.",
+        "operationId": "set_builtin_override_api_skills_builtin__name__put",
+        "parameters": [
+          {
+            "in": "path",
+            "name": "name",
+            "required": true,
+            "schema": {
+              "title": "Name",
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {}
+              }
+            },
+            "description": "Successful Response"
+          },
+          "422": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HTTPValidationError"
+                }
+              }
+            },
+            "description": "Validation Error"
+          }
+        },
+        "summary": "Set Builtin Override",
+        "tags": [
+          "skills"
+        ]
+      }
+    },
+    "/api/skills/import-from-url": {
+      "post": {
+        "description": "Install a SKILL.md bundle from a public GitHub URL (skills.sh links supported).",
+        "operationId": "import_skill_from_url_api_skills_import_from_url_post",
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/SkillImportUrlRequest"
+              }
+            }
+          },
+          "required": true
+        },
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {}
+              }
+            },
+            "description": "Successful Response"
+          },
+          "422": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HTTPValidationError"
+                }
+              }
+            },
+            "description": "Validation Error"
+          }
+        },
+        "summary": "Import Skill From Url",
+        "tags": [
+          "skills"
+        ]
+      }
+    },
+    "/api/skills/index": {
+      "get": {
+        "description": "The lightweight `[{name, description, category}]` list that the\nagent's system prompt sees. Useful for the UI's \"what does the model\nactually have access to?\" view.",
+        "operationId": "get_index_api_skills_index_get",
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {}
+              }
+            },
+            "description": "Successful Response"
+          }
+        },
+        "summary": "Get Index",
+        "tags": [
+          "skills"
+        ]
+      }
+    },
+    "/api/skills/search": {
+      "post": {
+        "operationId": "search_skills_api_skills_search_post",
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {}
+              }
+            },
+            "description": "Successful Response"
+          }
+        },
+        "summary": "Search Skills",
+        "tags": [
+          "skills"
+        ]
+      }
+    },
+    "/api/skills/slash-catalog": {
+      "get": {
+        "description": "Return skills that are available as slash commands.\n\nMirrors the agent prompt's published-skill index so the UI never offers\na slash command the model would not normally be allowed to discover.",
+        "operationId": "get_slash_catalog_api_skills_slash_catalog_get",
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {}
+              }
+            },
+            "description": "Successful Response"
+          }
+        },
+        "summary": "Get Slash Catalog",
+        "tags": [
+          "skills"
+        ]
+      }
+    },
+    "/api/skills/{skill_id}": {
+      "delete": {
+        "operationId": "delete_skill_api_skills__skill_id__delete",
+        "parameters": [
+          {
+            "in": "path",
+            "name": "skill_id",
+            "required": true,
+            "schema": {
+              "title": "Skill Id",
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {}
+              }
+            },
+            "description": "Successful Response"
+          },
+          "422": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HTTPValidationError"
+                }
+              }
+            },
+            "description": "Validation Error"
+          }
+        },
+        "summary": "Delete Skill",
+        "tags": [
+          "skills"
+        ]
+      },
+      "get": {
+        "operationId": "get_skill_api_skills__skill_id__get",
+        "parameters": [
+          {
+            "in": "path",
+            "name": "skill_id",
+            "required": true,
+            "schema": {
+              "title": "Skill Id",
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {}
+              }
+            },
+            "description": "Successful Response"
+          },
+          "422": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HTTPValidationError"
+                }
+              }
+            },
+            "description": "Validation Error"
+          }
+        },
+        "summary": "Get Skill",
+        "tags": [
+          "skills"
+        ]
+      },
+      "put": {
+        "operationId": "update_skill_api_skills__skill_id__put",
+        "parameters": [
+          {
+            "in": "path",
+            "name": "skill_id",
+            "required": true,
+            "schema": {
+              "title": "Skill Id",
+              "type": "string"
+            }
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/SkillUpdateRequest"
+              }
+            }
+          },
+          "required": true
+        },
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {}
+              }
+            },
+            "description": "Successful Response"
+          },
+          "422": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HTTPValidationError"
+                }
+              }
+            },
+            "description": "Validation Error"
+          }
+        },
+        "summary": "Update Skill",
+        "tags": [
+          "skills"
+        ]
+      }
+    },
+    "/api/skills/{skill_id}/invoke": {
+      "post": {
+        "description": "Build a skill-pinned prompt for slash-command invocation.\n\nThis is intentionally server-side so availability, ownership, and usage\naccounting use the same rules as the SkillsManager.",
+        "operationId": "invoke_skill_api_skills__skill_id__invoke_post",
+        "parameters": [
+          {
+            "in": "path",
+            "name": "skill_id",
+            "required": true,
+            "schema": {
+              "title": "Skill Id",
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {}
+              }
+            },
+            "description": "Successful Response"
+          },
+          "422": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HTTPValidationError"
+                }
+              }
+            },
+            "description": "Validation Error"
+          }
+        },
+        "summary": "Invoke Skill",
+        "tags": [
+          "skills"
+        ]
+      }
+    },
+    "/api/skills/{skill_id}/markdown": {
+      "get": {
+        "description": "Return the raw SKILL.md text \u2014 used by the slash-invocation flow\nand the editor's 'view source' affordance.",
+        "operationId": "get_skill_markdown_api_skills__skill_id__markdown_get",
+        "parameters": [
+          {
+            "in": "path",
+            "name": "skill_id",
+            "required": true,
+            "schema": {
+              "title": "Skill Id",
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {}
+              }
+            },
+            "description": "Successful Response"
+          },
+          "422": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HTTPValidationError"
+                }
+              }
+            },
+            "description": "Validation Error"
+          }
+        },
+        "summary": "Get Skill Markdown",
+        "tags": [
+          "skills"
+        ]
+      },
+      "post": {
+        "description": "Replace SKILL.md with new raw content. Parses + validates first.",
+        "operationId": "save_skill_markdown_api_skills__skill_id__markdown_post",
+        "parameters": [
+          {
+            "in": "path",
+            "name": "skill_id",
+            "required": true,
+            "schema": {
+              "title": "Skill Id",
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {}
+              }
+            },
+            "description": "Successful Response"
+          },
+          "422": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HTTPValidationError"
+                }
+              }
+            },
+            "description": "Validation Error"
+          }
+        },
+        "summary": "Save Skill Markdown",
+        "tags": [
+          "skills"
+        ]
+      }
+    },
+    "/api/skills/{skill_id}/test": {
+      "post": {
+        "description": "Kick off a background skill test (agent run + LLM judge). Returns\nimmediately; the run executes server-side so it survives the modal being\nclosed. Poll GET /{skill_id}/test-status for progress + verdict.\nOn completion it records the verdict and nudges the skill's confidence\nto match (pass\u21920.95, needs_work\u21920.6, fail\u21920.4; inconclusive/unknown leave\nit untouched). It never changes the skill's published/draft STATUS.",
+        "operationId": "test_skill_api_skills__skill_id__test_post",
+        "parameters": [
+          {
+            "in": "path",
+            "name": "skill_id",
+            "required": true,
+            "schema": {
+              "title": "Skill Id",
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {}
+              }
+            },
+            "description": "Successful Response"
+          },
+          "422": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HTTPValidationError"
+                }
+              }
+            },
+            "description": "Validation Error"
+          }
+        },
+        "summary": "Test Skill",
+        "tags": [
+          "skills"
+        ]
+      }
+    },
+    "/api/skills/{skill_id}/test-approval": {
+      "post": {
+        "description": "Resume a manual skill test with one exact server-sealed action.",
+        "operationId": "approve_skill_test_action_api_skills__skill_id__test_approval_post",
+        "parameters": [
+          {
+            "in": "path",
+            "name": "skill_id",
+            "required": true,
+            "schema": {
+              "title": "Skill Id",
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {}
+              }
+            },
+            "description": "Successful Response"
+          },
+          "422": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HTTPValidationError"
+                }
+              }
+            },
+            "description": "Validation Error"
+          }
+        },
+        "summary": "Approve Skill Test Action",
+        "tags": [
+          "skills"
+        ]
+      }
+    },
+    "/api/skills/{skill_id}/test-status": {
+      "get": {
+        "description": "Current background-test state for a skill (status / log / verdict).",
+        "operationId": "test_skill_status_api_skills__skill_id__test_status_get",
+        "parameters": [
+          {
+            "in": "path",
+            "name": "skill_id",
+            "required": true,
+            "schema": {
+              "title": "Skill Id",
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {}
+              }
+            },
+            "description": "Successful Response"
+          },
+          "422": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HTTPValidationError"
+                }
+              }
+            },
+            "description": "Validation Error"
+          }
+        },
+        "summary": "Test Skill Status",
+        "tags": [
+          "skills"
+        ]
+      }
+    }
+  }
+}
diff --git a/tests/test_redos_residual_python.py b/tests/test_redos_residual_python.py
index 276c71059..8ee889ab5 100644
--- a/tests/test_redos_residual_python.py
+++ b/tests/test_redos_residual_python.py
@@ -26,7 +26,7 @@ def _fast(fn, *args):
     return result
 
 
-# -- closed <think> blocks (skills_routes x4, memory_extractor.audit_memories) --
+# -- closed <think> blocks (skills.evaluation x4, memory_extractor.audit_memories) --
 
 _THINK_REF = re.compile(r"<think(?:ing)?>[\s\S]*?</think(?:ing)?>", re.I)
 
@@ -51,7 +51,11 @@ def test_strip_closed_think_blocks_unclosed_opener_flood_is_linear():
 
 
 def test_lazy_think_regex_is_gone_from_llm_review_parsers():
-    for rel in ("routes/skills_routes.py", "services/memory/memory_extractor.py"):
+    for rel in (
+        "routes/skills_routes.py",
+        "services/skills/evaluation.py",
+        "services/memory/memory_extractor.py",
+    ):
         source = (_ROOT / rel).read_text(encoding="utf-8")
         assert r"<think(?:ing)?>[\s\S]*?</think(?:ing)?>" not in source, rel
 
diff --git a/tests/test_redos_verdict_continuation.py b/tests/test_redos_verdict_continuation.py
index 1304f0200..685a4dfa6 100644
--- a/tests/test_redos_verdict_continuation.py
+++ b/tests/test_redos_verdict_continuation.py
@@ -3,7 +3,7 @@
 Both had two adjacent `\\s`-matching quantifiers that backtrack O(n^2) when the
 rest of the pattern fails on a whitespace flood:
 
-  * `routes/skills_routes.py` `_VERDICT_PROSE_RE` — `["\\'\\s:]*\\s*` (the class
+  * `services/skills/evaluation.py` `_VERDICT_PROSE_RE`: `["\\'\\s:]*\\s*` (the class
     already matches `\\s`) over a teacher/verifier model's prose verdict.
   * `src/agent_loop.py` `_EXPLICIT_CONTINUATION_RE` — `\\s*[.!?]*\\s*$` over a
     user's terse reply.
@@ -18,7 +18,7 @@ import time
 import pytest
 
 import src.agent_tools  # noqa: F401  (break agent_tools<->agent_loop import cycle)
-from routes.skills_routes import _VERDICT_PROSE_RE
+from services.skills.evaluation import _VERDICT_PROSE_RE
 from src.agent_loop import _EXPLICIT_CONTINUATION_RE, _is_explicit_continuation
 
 _BUDGET_S = 4.0
diff --git a/tests/test_skills_audit_characterization.py b/tests/test_skills_audit_characterization.py
new file mode 100644
index 000000000..14d942ff1
--- /dev/null
+++ b/tests/test_skills_audit_characterization.py
@@ -0,0 +1,485 @@
+"""Offline contracts captured against the merged skills baseline before extraction."""
+import asyncio
+from dataclasses import fields, is_dataclass
+from difflib import unified_diff
+import inspect
+import json
+from contextvars import ContextVar
+from pathlib import Path
+from typing import Annotated, get_args, get_origin
+
+import pytest
+from fastapi import FastAPI
+from starlette.requests import Request
+
+from routes import skills_routes as routes
+
+
+FIXTURES = Path(__file__).parent / 'fixtures'
+
+
+def _qualified_name(value):
+    return f'{value.__module__}.{value.__qualname__}'
+
+
+def _value_contract(value):
+    if value is inspect.Signature.empty:
+        return {'empty': True}
+    if value is None or type(value) in (bool, int, float, str):
+        return {'type': _qualified_name(type(value)), 'value': value}
+    if type(value) in (list, tuple):
+        return {'type': _qualified_name(type(value)),
+                'items': [_value_contract(item) for item in value]}
+    if type(value) is dict and all(type(key) is str for key in value):
+        return {'type': 'builtins.dict',
+                'items': {key: _value_contract(item) for key, item in value.items()}}
+    if is_dataclass(value) and not isinstance(value, type):
+        return {'type': _qualified_name(type(value)), 'fields': {
+            field.name: _value_contract(getattr(value, field.name))
+            for field in fields(value)
+        }}
+    raise TypeError(f'Unsupported contract value: {type(value)}')
+
+
+def _annotation_contract(annotation):
+    if annotation is inspect.Signature.empty or annotation is None:
+        return _value_contract(annotation)
+    origin = get_origin(annotation)
+    if origin is Annotated:
+        base, *metadata = get_args(annotation)
+        return {'origin': _qualified_name(origin),
+                'annotation': _annotation_contract(base),
+                'metadata': [_value_contract(item) for item in metadata]}
+    if origin is not None:
+        return {'origin': _qualified_name(origin), 'module': annotation.__module__,
+                'arguments': [_annotation_contract(arg) for arg in get_args(annotation)]}
+    return {'type': _qualified_name(annotation)}
+
+
+def _factory_contract(factory):
+    # Names do not identify closure state, partial arguments or arbitrary code.
+    # Only these known builtin constructors have a supported default contract.
+    if not any(factory is builtin for builtin in (list, tuple, dict, set, frozenset)):
+        raise TypeError('Unsupported default factory; requires an explicit compatibility contract')
+    return _qualified_name(factory)
+
+
+def _signature_contract(target):
+    """Freeze supported constructor structure without executing default factories."""
+    signature = inspect.signature(target)
+    model_fields = getattr(target, 'model_fields', {})
+    parameters = []
+    for parameter in signature.parameters.values():
+        field = model_fields.get(parameter.name)
+        if field is not None and field.default_factory is not None:
+            default = {'factory': _factory_contract(field.default_factory),
+                       'marker': _qualified_name(type(parameter.default))}
+        else:
+            default = _value_contract(parameter.default)
+        parameters.append({'name': parameter.name, 'kind': parameter.kind.name,
+                           'annotation': _annotation_contract(parameter.annotation),
+                           'default': default})
+    contract = {'parameters': parameters,
+                'return': _annotation_contract(signature.return_annotation)}
+    if model_fields:
+        # Field names can be absent from the Python signature (validation aliases).
+        # These public FieldInfo attributes affect input validation independently
+        # of the generated signature and JSON schema. Rebuilt annotations retain
+        # field metadata, including constraints and strict/union validation modes.
+        contract['model_fields'] = {
+            name: {
+                'annotation': _annotation_contract(field.rebuild_annotation()),
+                'default': ({'factory': _factory_contract(field.default_factory),
+                             'takes_validated_data': field.default_factory_takes_validated_data}
+                            if field.default_factory is not None else
+                            _value_contract(inspect.Signature.empty if field.is_required() else field.default)),
+                'validation': {attribute: _value_contract(getattr(field, attribute))
+                               for attribute in ('alias', 'alias_priority', 'validation_alias',
+                                                 'discriminator', 'validate_default')},
+            }
+            for name, field in model_fields.items()
+        }
+        # Includes inherited model settings such as validate_default and strict.
+        # Unsupported callables or values fail closed through _value_contract.
+        contract['model_config'] = _value_contract(target.model_config)
+    return contract
+
+
+def _canonical_openapi(schema):
+    return json.dumps(schema, sort_keys=True, indent=2, ensure_ascii=True) + '\n'
+
+
+def _assert_openapi_matches_baseline(schema):
+    expected = (FIXTURES / 'skills_openapi_baseline.json').read_text(encoding='utf-8')
+    actual = _canonical_openapi(schema)
+    if actual != expected:
+        baseline = json.loads(expected)
+        affected = []
+        for label, before, after in [
+            ('paths', baseline.get('paths', {}), schema.get('paths', {})),
+            ('schemas', baseline.get('components', {}).get('schemas', {}),
+             schema.get('components', {}).get('schemas', {})),
+        ]:
+            changed = [key for key in sorted(before.keys() | after.keys())
+                       if _canonical_openapi(before.get(key)) != _canonical_openapi(after.get(key))]
+            if changed:
+                affected.append(f'Changed {label}: {", ".join(changed)}\n')
+        pytest.fail('OpenAPI contract changed:\n' + ''.join(affected) + ''.join(unified_diff(
+            expected.splitlines(keepends=True), actual.splitlines(keepends=True),
+            fromfile='skills_openapi_baseline.json', tofile='generated OpenAPI',
+        )))
+
+
+def endpoint(method, path, manager=None):
+    return next(r.endpoint for r in routes.setup_skills_routes(manager).routes
+                if method in r.methods and r.path == '/api/skills' + path)
+
+
+def request(owner='alice', body=None):
+    async def receive():
+        return {'type': 'http.request', 'body': json.dumps(body or {}).encode()}
+    return Request({'type': 'http', 'method': 'POST', 'path': '/',
+                    'headers': [(b'content-type', b'application/json')],
+                    'state': {'user': owner}}, receive)
+
+
+def test_api_and_python_signatures_match_baseline():
+    baseline = json.loads((FIXTURES / 'skills_api_baseline.json').read_text(encoding='utf-8'))
+    app = FastAPI()
+    router = routes.setup_skills_routes(object())
+    app.include_router(router)
+    schema = app.openapi()
+    _assert_openapi_matches_baseline(schema)
+    declarations = [[sorted(r.methods), r.path, r.name] for r in router.routes]
+    assert declarations == baseline['routes']
+    for name, signature in baseline['signatures'].items():
+        assert _signature_contract(getattr(routes, name)) == signature, name
+
+
+def test_signature_contract_ignores_annotated_repr(monkeypatch):
+    target = routes.SkillImportUrlRequest
+    before = _signature_contract(target)
+    annotation = inspect.signature(target).parameters['url'].annotation
+    monkeypatch.setattr(type(annotation), '__repr__', lambda self: 'different Python rendering')
+    assert _signature_contract(target) == before
+
+
+@pytest.mark.parametrize('change', ['name', 'order', 'kind', 'default', 'annotation', 'return'])
+def test_signature_contract_detects_interface_changes(change):
+    def original(first: str, second: int = 1) -> bool:
+        pass
+    signature = inspect.signature(original)
+    first, second = signature.parameters.values()
+    parameters = [first, second]
+    if change == 'order':
+        parameters = [second.replace(default=inspect.Parameter.empty),
+                      first.replace(default='')]
+    elif change == 'return':
+        signature = signature.replace(return_annotation=str)
+    else:
+        changes = {
+            'name': {'name': 'renamed'},
+            'kind': {'kind': inspect.Parameter.KEYWORD_ONLY},
+            'default': {'default': 2},
+            'annotation': {'annotation': float},
+        }
+        parameters[1] = second.replace(**changes[change])
+    def changed():
+        pass
+    changed.__signature__ = signature.replace(parameters=parameters)
+    assert _signature_contract(changed) != _signature_contract(original)
+
+
+@pytest.mark.parametrize('change', ['constraint', 'factory'])
+def test_signature_contract_detects_model_changes(change):
+    from pydantic import BaseModel, Field
+
+    class Original(BaseModel):
+        text: str = Field(max_length=8)
+        tags: list[str] = Field(default_factory=list)
+
+    class Changed(BaseModel):
+        text: str = Field(max_length=9 if change == 'constraint' else 8)
+        tags: list[str] = Field(default_factory=tuple if change == 'factory' else list)
+
+    assert _signature_contract(Changed) != _signature_contract(Original)
+
+
+@pytest.mark.parametrize('validated_data', [False, True])
+def test_signature_contract_rejects_custom_factories_without_calling_them(validated_data):
+    from pydantic import BaseModel, Field
+
+    calls = []
+    def make_factory(value):
+        def plain():
+            calls.append(value)
+            return [value]
+        def with_data(data):
+            calls.append(value)
+            return [data['prefix'], value]
+        return with_data if validated_data else plain
+
+    class Before(BaseModel):
+        prefix: str = 'validated'
+        tags: list[str] = Field(default_factory=make_factory('before'))
+
+    class After(BaseModel):
+        prefix: str = 'validated'
+        tags: list[str] = Field(default_factory=make_factory('after'))
+
+    assert Before().tags != After().tags
+    assert Before.model_fields['tags'].default_factory_takes_validated_data is validated_data
+    calls.clear()
+    for model in (Before, After):
+        with pytest.raises(TypeError, match='Unsupported default factory'):
+            _signature_contract(model)
+    assert calls == []
+
+
+def test_signature_contract_detects_default_validation_outside_signature_and_openapi():
+    from pydantic import BaseModel, Field, ValidationError
+
+    class Before(BaseModel):
+        count: int = Field(default='invalid', validate_default=False)
+
+    class After(BaseModel):
+        count: int = Field(default='invalid', validate_default=True)
+
+    assert Before().count == 'invalid'
+    with pytest.raises(ValidationError):
+        After()
+    assert inspect.signature(Before) == inspect.signature(After)
+    before_schema, after_schema = Before.model_json_schema(), After.model_json_schema()
+    before_schema.pop('title')
+    after_schema.pop('title')
+    assert before_schema == after_schema
+    assert _signature_contract(Before) != _signature_contract(After)
+
+
+def test_signature_contract_detects_validation_alias_paths():
+    from pydantic import AliasPath, BaseModel, Field, ValidationError
+
+    class Before(BaseModel):
+        count: int = Field(validation_alias=AliasPath('before', 0))
+
+    class After(BaseModel):
+        count: int = Field(validation_alias=AliasPath('after', 0))
+
+    assert Before(before=[1]).count == 1
+    with pytest.raises(ValidationError):
+        After(before=[1])
+    assert inspect.signature(Before) == inspect.signature(After)
+    before_schema, after_schema = Before.model_json_schema(), After.model_json_schema()
+    before_schema.pop('title')
+    after_schema.pop('title')
+    assert before_schema == after_schema
+    assert _signature_contract(Before) != _signature_contract(After)
+
+
+@pytest.mark.parametrize('setting', ['validate_default', 'strict'])
+def test_signature_contract_detects_model_validation_configuration(setting):
+    from pydantic import BaseModel, ConfigDict, ValidationError
+
+    class Before(BaseModel):
+        model_config = ConfigDict({setting: False})
+        count: int = 'invalid' if setting == 'validate_default' else 1
+
+    class After(BaseModel):
+        model_config = ConfigDict({setting: True})
+        count: int = 'invalid' if setting == 'validate_default' else 1
+
+    data = {} if setting == 'validate_default' else {'count': '1'}
+    Before(**data)
+    with pytest.raises(ValidationError):
+        After(**data)
+    assert inspect.signature(Before) == inspect.signature(After)
+    assert _signature_contract(Before) != _signature_contract(After)
+
+
+def test_openapi_golden_is_canonical():
+    golden = (FIXTURES / 'skills_openapi_baseline.json').read_text(encoding='utf-8')
+    schema = json.loads(golden)
+    assert golden == _canonical_openapi(schema)
+
+
+@pytest.mark.parametrize('section, key', [
+    ('paths', '/api/skills/add'), ('schemas', 'SkillAddRequest'),
+])
+def test_openapi_failure_identifies_changed_endpoint_or_schema(section, key):
+    schema = json.loads((FIXTURES / 'skills_openapi_baseline.json').read_text(encoding='utf-8'))
+    target = schema['paths'] if section == 'paths' else schema['components']['schemas']
+    if section == 'paths':
+        target[key]['post']['responses']['200']['description'] = 'changed contract'
+    else:
+        target[key]['properties']['solution']['anyOf'][0]['maxLength'] = 4999
+    with pytest.raises(pytest.fail.Exception) as failure:
+        _assert_openapi_matches_baseline(schema)
+    diagnostic = str(failure.value)
+    assert '--- skills_openapi_baseline.json' in diagnostic
+    assert '+++ generated OpenAPI' in diagnostic
+    assert f'Changed {section}: {key}' in diagnostic
+    expected_change = '"description": "changed contract"' if section == 'paths' else '"maxLength": 4999'
+    assert any(line.startswith('+') and expected_change in line
+               for line in diagnostic.splitlines())
+
+
+@pytest.mark.parametrize('raw, expected', [
+    ('<think>{"verdict":"fail"}</think>{"verdict":"PASS","confidence":2,}', 'pass'),
+    ('{"verdict":"fail"} text {"verdict":"needs_work"}', 'needs_work'),
+    ('Verdict: INCONCLUSIVE', 'inconclusive'),
+    ('<think>{"verdict":"pass"}', 'unknown'),
+    ('{"verdict":"invalid"}', 'unknown'),
+])
+async def test_run_verdict_parsing_and_retry(monkeypatch, raw, expected):
+    calls = []
+    async def call(url, model, messages, **kwargs):
+        calls.append((messages, kwargs))
+        return raw
+    monkeypatch.setattr('src.llm_core.llm_call_async', call)
+    monkeypatch.setattr(routes, 'effort_for_call', lambda url, model, owner: 'high' if owner == 'alice' else None)
+    result = await routes._eval_skill_run('md', 'task', 'transcript', 'url', 'm', {},
+                                          workload='background', owner='alice')
+    assert result['verdict'] == expected
+    assert len(calls) == (2 if expected == 'unknown' else 1)
+    for _, kwargs in calls:
+        assert kwargs['reasoning_effort'] == 'high'
+        assert kwargs['workload'] == 'background'
+        assert kwargs['timeout'] == 180
+        assert kwargs['max_tokens'] == 32768
+    if len(calls) == 2:
+        assert "must START with '{'" in calls[1][0][0]['content']
+
+
+async def test_review_transient_failure_and_result_coercion(monkeypatch):
+    calls = []
+    async def call(*args, **kwargs):
+        calls.append(kwargs)
+        if len(calls) == 1:
+            raise TimeoutError('offline')
+        return json.dumps({'verdict': 'pass', 'confidence': '-1', 'summary': 'x' * 500,
+                           'issues': ['y' * 250] * 10, 'baseline_verdict': 'invalid',
+                           'usefulness': '2', 'saved_turns': '-2', 'saved_tool_calls': 'bad'})
+    monkeypatch.setattr('src.llm_core.llm_call_async', call)
+    result = await routes._eval_skill_run('', '', '', 'url', 'm', None)
+    assert result == {'verdict': 'pass', 'confidence': 0.0, 'summary': 'x' * 400,
+                      'issues': ['y' * 200] * 8, 'baseline_verdict': 'unknown',
+                      'usefulness': 1.0, 'saved_turns': -2, 'saved_tool_calls': 0}
+
+
+async def test_review_failure_schema_and_transcript_tail(monkeypatch):
+    seen = []
+    async def call(url, model, messages, **kwargs):
+        seen.append(messages)
+        raise RuntimeError('offline')
+    monkeypatch.setattr('src.llm_core.llm_call_async', call)
+    result = await routes._eval_skill_run('m' * 5000, 'TASK', 'HEAD' + 'x' * 30000 + 'TAIL', 'url', 'm', None)
+    assert result == {'verdict': 'unknown', 'confidence': 0,
+                      'summary': 'Review call failed: offline', 'issues': []}
+    assert len(seen) == 2
+    assert 'HEAD' in seen[0][1]['content'] and 'TAIL' in seen[0][1]['content']
+    assert 'm' * 4001 not in seen[0][1]['content']
+
+
+@pytest.mark.parametrize('name, raw, expected, tokens, timeout', [
+    ('_eval_skill_necessity', '<think>x</think>{"necessary":false,"redundant_with":["demo"],"reason":"duplicate",}',
+     {'necessary': False, 'redundant_with': ['demo'], 'reason': 'duplicate'}, 8192, 120),
+    ('_eval_skill_retrieval_precision', '{"ok":false,"summary":"broad","issues":["metadata: retrieval: narrow"]}',
+     {'ok': False, 'summary': 'broad', 'issues': ['metadata: retrieval: narrow']}, 4096, 90),
+    ('_eval_skill_necessity', '<think>unfinished', None, 8192, 120),
+    ('_eval_skill_retrieval_precision', '[]', None, 4096, 90),
+])
+async def test_advisory_schema_budget_and_owner(monkeypatch, name, raw, expected, tokens, timeout):
+    async def call(*args, **kwargs):
+        assert kwargs['max_tokens'] == tokens
+        assert kwargs['timeout'] == timeout
+        assert kwargs['reasoning_effort'] == 'medium'
+        return raw
+    monkeypatch.setattr('src.llm_core.llm_call_async', call)
+    monkeypatch.setattr(routes, 'effort_for_call', lambda url, model, owner: 'medium' if owner == 'alice' else None)
+    assert await getattr(routes, name)('md', [], 'url', 'm', None, owner='alice') == expected
+
+
+@pytest.mark.parametrize('name', ['_eval_skill_necessity', '_eval_skill_retrieval_precision', '_improve_skill_md'])
+async def test_advisory_exceptions_return_none(monkeypatch, name):
+    async def call(*args, **kwargs):
+        raise TimeoutError('offline')
+    monkeypatch.setattr('src.llm_core.llm_call_async', call)
+    args = ('md', {}, '', 'url', 'm', None) if name == '_improve_skill_md' else ('md', [], 'url', 'm', None)
+    assert await getattr(routes, name)(*args) is None
+
+
+async def test_cancelled_audit_closes_stream_in_originating_context(monkeypatch):
+    bound = ContextVar('audit_characterization', default=None)
+    opened = asyncio.Event()
+    closed = []
+    async def stream(*args, **kwargs):
+        token = bound.set('bound')
+        try:
+            yield 'data: {"delta":"started"}\n\n'
+            opened.set()
+            await asyncio.Event().wait()
+        finally:
+            bound.reset(token)
+            closed.append(asyncio.current_task())
+    monkeypatch.setattr('src.agent_loop.stream_agent_loop', stream)
+    task = asyncio.create_task(routes._run_skill_audit_arm([], 'url', 'm', {}, 'alice'))
+    await opened.wait()
+    task.cancel()
+    with pytest.raises(asyncio.CancelledError):
+        await task
+    assert closed == [task]
+    assert bound.get() is None
+
+
+async def test_cancelled_batch_skips_finalization_and_cleans_task(monkeypatch):
+    opened = asyncio.Event()
+    async def audit(*args, **kwargs):
+        opened.set()
+        await asyncio.Event().wait()
+    class Manager:
+        def load(self, owner=None):
+            assert owner == 'alice'
+            return [{'name': 'demo'}]
+    job = {'status': 'running', 'log': [], 'results': [], 'done': 0}
+    monkeypatch.setattr(routes, '_skill_audit_jobs', {('alice',): job})
+    monkeypatch.setattr(routes, '_audit_one_skill', audit)
+    monkeypatch.setattr(routes, '_finalize_audit_batch', lambda *args: pytest.fail('cancelled batch finalized'))
+    task = asyncio.create_task(routes._run_audit_all_job(('alice',), Manager(), ['demo'], 'url', 'm', {}, None, 'alice'))
+    job['task'] = task
+    await opened.wait()
+    task.cancel()
+    await task
+    assert job['status'] == 'cancelled'
+    assert job['current'] is None and 'task' not in job and 'finished' in job
+    assert job['results'] == [] and job['done'] == 0
+
+
+async def test_test_polling_is_owner_scoped_and_hides_continuation(monkeypatch):
+    class Manager:
+        def load(self, owner=None):
+            return [{'name': 'demo'}]
+    monkeypatch.setattr(routes, 'get_current_user', lambda req: req.state.user)
+    job = {'status': 'awaiting_approval', 'task': 'task', 'model': 'm', 'log': [],
+           'verdict': None, 'approval': {'approval_id': 'id'},
+           '_run': {'headers': {'Authorization': 'secret'}}, '_transcript': ['private']}
+    monkeypatch.setattr(routes, '_skill_test_jobs', {('alice', 'demo'): job})
+    poll = endpoint('GET', '/{skill_id}/test-status', Manager())
+    assert await poll(request('bob'), 'demo') == {'status': 'none'}
+    assert await poll(request(), 'demo') == {k: job[k] for k in ('status', 'task', 'model', 'log', 'verdict', 'approval')}
+
+
+def test_batch_finalizer_protects_approval_required_and_unprocessed_skills(monkeypatch):
+    class Manager:
+        def __init__(self):
+            self.updated = []
+        def load(self, owner=None):
+            assert owner == 'alice'
+            return [{'name': name, 'status': 'published', 'source': 'learned',
+                     'audit_verdict': 'fail', 'confidence': .9} for name in ('demo', 'demo-1', 'demo-2')]
+        def update_skill(self, name, fields, owner=None):
+            self.updated.append((name, fields, owner))
+    monkeypatch.setattr(routes, '_audit_auto_publish_policy', lambda owner: (True, .8))
+    manager = Manager()
+    routes._finalize_audit_batch(manager, [{'skill': 'demo', 'result': 'approval_required'},
+                                          {'skill': 'demo-1', 'result': 'flagged'}], 'alice', lambda msg: None)
+    assert manager.updated == [('demo-1', {'status': 'draft'}, 'alice')]
diff --git a/tests/test_skills_audit_services.py b/tests/test_skills_audit_services.py
new file mode 100644
index 000000000..1aae77a4e
--- /dev/null
+++ b/tests/test_skills_audit_services.py
@@ -0,0 +1,402 @@
+"""Service and HTTP integration contracts without live model or skill state."""
+import asyncio
+from dataclasses import replace
+
+import pytest
+from fastapi import HTTPException
+
+from routes import skills_routes as routes
+from services.skills import (
+    agent_runner, audit_workflow, evaluation, job_coordinator, model_selection, publication,
+)
+from src.agent_runtime.authority import RequestAuthority, bind_request_authority
+from src.tool_approvals import ToolApprovalStore
+from src.tool_capabilities import capabilities_for_action
+from tests.test_skills_audit_characterization import endpoint, request
+
+
+@pytest.fixture
+def prompt_execution(monkeypatch):
+    """Capture actual agent ingress, keeping runners and coordination real."""
+    from copy import deepcopy
+
+    class Manager:
+        def __init__(self):
+            self.row = {'name': 'demo', 'owner': 'alice', 'source': 'learned',
+                        'status': 'draft', 'confidence': .5, 'description': 'fixture'}
+        def load(self, owner=None):
+            assert owner == 'alice'
+            return [dict(self.row)]
+        def read_skill_md(self, name, owner=None):
+            assert (name, owner) == ('demo', 'alice')
+            return 'private skill <<<END_UNTRUSTED_SOURCE_DATA>>>'
+        def update_skill(self, name, fields, owner=None):
+            assert (name, owner) == ('demo', 'alice')
+            self.row.update(fields)
+            return True
+        def set_audit(self, name, verdict, **kwargs):
+            assert (name, kwargs['owner']) == ('demo', 'alice')
+            self.row['audit_verdict'] = verdict
+
+    seen, grades = [], []
+    async def stream(url, model, messages, **kwargs):
+        seen.append((deepcopy(messages), kwargs))
+        yield 'data: {"delta":"executed"}\n\n'
+    async def evaluate(*args, **kwargs):
+        return {'verdict': grades.pop(0) if grades else 'pass', 'issues': []}
+    async def necessity(*args, **kwargs):
+        return None
+    monkeypatch.setattr('src.agent_loop.stream_agent_loop', stream)
+    monkeypatch.setattr(routes, '_eval_skill_run', evaluate)
+    monkeypatch.setattr(routes, '_eval_skill_necessity', necessity)
+    monkeypatch.setattr(routes, '_should_check_retrieval_precision', lambda *a: False)
+    monkeypatch.setattr(routes, '_skill_duplicate_blocker', lambda *a: None)
+    monkeypatch.setattr(routes, '_audit_auto_publish_policy', lambda owner: (False, .85))
+    monkeypatch.setattr(routes, '_skill_test_jobs', {})
+    monkeypatch.setattr(routes, '_skill_audit_jobs', {})
+    monkeypatch.setattr(routes, 'get_current_user', lambda req: req.state.user)
+    monkeypatch.setattr('src.endpoint_resolver.resolve_endpoint', lambda *a, **kw: ('url', 'worker', {}))
+    monkeypatch.setattr('src.llm_core.list_model_ids', lambda *a, **kw: ['worker'])
+    monkeypatch.setattr(routes, '_resolve_audit_models', lambda **kw: ('url', 'worker', {}, None))
+    return Manager(), seen, grades
+
+
+def patch_prompt_builders(monkeypatch):
+    originals = routes._skill_test_messages, routes._skill_baseline_messages
+    def test_messages(md, task):
+        return originals[0]('patched skill: ' + md, task)
+    def baseline_messages(task):
+        return originals[1]('patched baseline: ' + task)
+    monkeypatch.setattr(routes, '_skill_test_task', lambda skill: 'patched task')
+    monkeypatch.setattr(routes, '_skill_test_messages', test_messages)
+    monkeypatch.setattr(routes, '_skill_baseline_messages', baseline_messages)
+
+
+@pytest.mark.parametrize('patched', [False, True])
+@pytest.mark.parametrize('entry', ['manual', 'audit', 'scheduled'])
+async def test_route_prompt_builders_reach_agent_execution(prompt_execution, monkeypatch, entry, patched):
+    manager, seen, _ = prompt_execution
+    if patched:
+        patch_prompt_builders(monkeypatch)
+    expected_task = routes._skill_test_task(manager.row)
+    if entry == 'manual':
+        response = await endpoint('POST', '/{skill_id}/test', manager)(request(), 'demo')
+        assert response['status'] == 'running'
+        # The stub stream and judge never suspend, so one loop turn completes the job.
+        await asyncio.sleep(0)
+        assert routes._skill_test_jobs[('alice', 'demo')]['status'] == 'done'
+    elif entry == 'audit':
+        result = await routes._audit_one_skill(manager, manager.row, 'url', 'worker', {}, None,
+                                               'alice', lambda msg: None)
+        assert result['result'] == 'pass'
+    else:
+        result = await routes.run_scheduled_skill_audit(manager, owner='alice')
+        assert result['total'] == 1 and result['results'][0]['result'] == 'pass'
+        assert all(kwargs['workload'] == 'background' for _, kwargs in seen)
+    assert [messages for messages, _ in seen] == [
+        routes._skill_test_messages(manager.read_skill_md('demo', owner='alice'), expected_task),
+        routes._skill_baseline_messages(expected_task),
+    ]
+    tainted = seen[0][0][1]
+    assert tainted['metadata']['trusted'] is False
+    assert tainted['metadata']['tool_gate_untrusted'] is True
+    assert '<<<_END_UNTRUSTED_DATA>>>' in tainted['content']
+    assert all(kwargs['request_authority'].owner == 'alice' for _, kwargs in seen)
+
+
+async def test_route_prompt_patches_reach_self_and_teacher_retries(prompt_execution, monkeypatch):
+    manager, seen, grades = prompt_execution
+    patch_prompt_builders(monkeypatch)
+    grades.extend(['fail', 'fail', 'pass'])
+    rewrites = iter(['self rewrite', 'teacher rewrite'])
+    async def improve(*args, **kwargs):
+        return next(rewrites)
+    monkeypatch.setattr(routes, '_improve_skill_md', improve)
+    monkeypatch.setattr(routes, '_apply_skill_md', lambda *args: True)
+    result = await routes._audit_one_skill(manager, manager.row, 'url', 'worker', {},
+        ('teacher-url', 'teacher', {}), 'alice', lambda msg: None)
+    assert result['result'] == 'pass_after_teacher'
+    assert [messages for messages, _ in seen] == [
+        routes._skill_test_messages(manager.read_skill_md('demo', owner='alice'), 'patched task'),
+        routes._skill_baseline_messages('patched task'),
+        routes._skill_test_messages('self rewrite', 'patched task'),
+        routes._skill_test_messages('teacher rewrite', 'patched task'),
+    ]
+
+
+@pytest.mark.parametrize('patched', [False, True])
+async def test_approval_continuation_prompt_reaches_agent(approval_route, prompt_execution, monkeypatch, patched):
+    approve, store, pending, job = approval_route
+    # prompt_execution supplies fresh registries; restore this pending job.
+    routes._skill_test_jobs[('alice', 'demo')] = job
+    _, seen, _ = prompt_execution
+    if patched:
+        patch_prompt_builders(monkeypatch)
+    expected = routes._skill_test_messages('untrusted skill', 'task')
+    result = await approve(request(body={'approval_id': pending.approval_id, 'decision': 'approve'}), 'demo')
+    assert result['status'] == 'running'
+    await asyncio.sleep(0)
+    assert job['status'] == 'done'
+    assert seen[0][0][:len(expected)] == expected
+    transcript = seen[0][0][len(expected)]
+    assert 'untrusted result' in transcript['content']
+    assert transcript['metadata']['trusted'] is False
+    assert transcript['metadata']['tool_gate_untrusted'] is True
+    grant = seen[0][1]['exact_approval']
+    assert grant.pending is pending and grant.allow_remaining_actions is False
+    assert store.peek(pending.approval_id) is None
+    assert seen[1][0] == routes._skill_baseline_messages('task')
+
+
+def test_baseline_task_alias_uses_route_test_task_patch(monkeypatch):
+    monkeypatch.setattr(routes, '_skill_test_task', lambda skill: 'patched shared task')
+    assert routes._skill_baseline_task({'name': 'demo'}) == 'patched shared task'
+
+
+async def test_evaluation_can_inject_model_call_and_owner_effort_without_network():
+    seen = []
+    async def call(url, model, messages, **kwargs):
+        seen.append(kwargs)
+        return '{"verdict":"pass"}'
+    def effort(url, model, owner):
+        assert (url, model, owner) == ('offline', 'worker', 'alice')
+        return 'high'
+    result = await evaluation.evaluate_run('md', 'task', 'done', 'offline', 'worker', None,
+                                           owner='alice', _llm_call=call, _effort_for_call=effort)
+    assert result['verdict'] == 'pass'
+    assert seen[0]['reasoning_effort'] == 'high'
+
+
+async def test_rewrite_keeps_last_document_and_owner_effort():
+    async def call(*args, **kwargs):
+        assert kwargs['reasoning_effort'] == 'medium'
+        return '<think>reasoning</think>old\n---\nname: old\n---\nbody\n---\nname: demo\n---\nfixed'
+    assert await evaluation.improve_markdown('md', {}, 'transcript', 'url', 'm', {},
+        owner='alice', _llm_call=call, _effort_for_call=lambda u, m, o: 'medium') == '---\nname: demo\n---\nfixed'
+
+
+def test_audit_model_resolution_uses_first_owner_scoped_utility_fallback(monkeypatch):
+    seen = []
+    def primary(role, owner=None):
+        seen.append(('primary', role, owner))
+        return None, None, {}
+    def fallback(owner=None):
+        seen.append(('fallback', owner))
+        return [('first', '/models/worker', {'Authorization': 'owner-key'}), ('second', 'other', {})]
+    def served(url, headers=None):
+        assert (url, headers) == ('first', {'Authorization': 'owner-key'})
+        return ['worker']
+    monkeypatch.setattr('src.endpoint_resolver.resolve_endpoint', primary)
+    monkeypatch.setattr('src.endpoint_resolver.resolve_utility_fallback_candidates', fallback)
+    monkeypatch.setattr('src.llm_core.list_model_ids', served)
+    monkeypatch.setattr('src.settings.get_setting', lambda key, default=None: default)
+    assert model_selection.resolve_audit_models(owner='alice') == ('first', 'worker', {'Authorization': 'owner-key'}, None)
+    assert seen == [('primary', 'utility', 'alice'), ('fallback', 'alice')]
+
+
+async def test_audit_stream_failure_closes_and_restores_inherited_authority(monkeypatch):
+    authority = RequestAuthority.empty(owner='alice')
+    closed = []
+    async def stream(*args, **kwargs):
+        assert kwargs['owner'] == 'alice'
+        assert kwargs['request_authority'] is authority
+        assert kwargs['suppress_skills'] is True
+        try:
+            yield 'event: error\ndata: {"error":"offline"}\n\n'
+        finally:
+            closed.append(asyncio.current_task())
+    monkeypatch.setattr('src.agent_loop.stream_agent_loop', stream)
+    with bind_request_authority(authority):
+        with pytest.raises(agent_runner.SkillAuditUnavailable, match='offline'):
+            await agent_runner.run_audit_arm([], 'url', 'm', {}, 'alice')
+    assert closed == [asyncio.current_task()]
+
+
+async def test_manual_exception_closes_stream_and_finishes_without_publishing(monkeypatch):
+    closed = []
+    async def stream(*args, **kwargs):
+        try:
+            yield 'data: {"delta":"partial"}\n\n'
+            raise RuntimeError('stream failed')
+        finally:
+            closed.append(asyncio.current_task())
+    async def arm(*args, **kwargs):
+        return 'baseline', {}, None
+    async def evaluate(*args, **kwargs):
+        return {'verdict': 'fail', 'summary': 'failed', 'issues': []}
+    class Manager:
+        def __init__(self):
+            self.updates = []
+        def set_audit(self, name, verdict, **kwargs):
+            assert name == 'demo' and verdict == 'fail' and kwargs['owner'] == 'alice'
+        def update_skill(self, name, fields, owner=None):
+            self.updates.append((fields, owner))
+    job = {'status': 'running', 'log': [], '_run': {}, '_transcript': []}
+    deps = replace(routes._audit_dependencies(), test_jobs={('alice', 'demo'): job},
+                   run_arm=arm, evaluate_run=evaluate)
+    monkeypatch.setattr('src.agent_loop.stream_agent_loop', stream)
+    manager = Manager()
+    await agent_runner.run_test_job(('alice', 'demo'), 'demo', 'md', 'task', 'url', 'm', {},
+                                 'alice', manager, deps=deps)
+    assert closed == [asyncio.current_task()]
+    assert job['status'] == 'done' and '_run' not in job and '_transcript' not in job
+    assert {'type': 'error', 'error': 'stream failed'} in job['log']
+    assert manager.updates == [({'confidence': .4}, 'alice')]
+
+
+async def test_batch_exception_records_progress_and_finalizes_once():
+    class Manager:
+        def __init__(self):
+            self.audit = []
+        def load(self, owner=None):
+            assert owner == 'alice'
+            return [{'name': name, 'status': 'draft'} for name in ('first', 'second')]
+        def set_audit(self, *args, **kwargs):
+            self.audit.append((args, kwargs))
+    async def audit(manager, skill, *args, **kwargs):
+        if skill['name'] == 'first':
+            raise RuntimeError('failed')
+        return {'skill': 'second', 'result': 'pass'}
+    finalized = []
+    job = {'status': 'running', 'log': [], 'results': [], 'done': 0, 'task': object()}
+    deps = replace(routes._audit_dependencies(), audit_jobs={('alice',): job}, audit_one=audit,
+                   finalize_batch=lambda manager, results, owner, log: finalized.append((list(results), owner)))
+    manager = Manager()
+    await audit_workflow.run_audit_batch(('alice',), manager, ['first', 'second'], 'url', 'm', {}, None, 'alice', deps=deps)
+    assert job['status'] == 'done' and job['done'] == 2 and job['current'] is None
+    assert 'task' not in job and 'finished' in job
+    assert [r['result'] for r in job['results']] == ['error', 'pass']
+    assert manager.audit == [(('first', 'inconclusive'), {'worker_model': 'm', 'owner': 'alice'})]
+    assert finalized == [(job['results'], 'alice')]
+
+
+@pytest.mark.parametrize('enabled,confidence,verdict,expected', [
+    (True, .85, 'pass', 'published'), (True, .84, 'pass', 'draft'),
+    (False, .95, 'pass', 'draft'), (True, .95, 'fail', 'draft'),
+    (False, .2, 'unknown', 'published'),
+])
+def test_policy_preserves_threshold_and_auto_approval(enabled, confidence, verdict, expected):
+    class Manager:
+        def __init__(self):
+            self.updates = []
+        def load(self, owner=None):
+            return [{'name': 'demo', 'status': 'published'}]
+        def update_skill(self, name, fields, owner=None):
+            assert owner == 'alice'
+            self.updates.append(fields)
+    deps = replace(routes._audit_dependencies(), auto_publish_policy=lambda owner: (enabled, .85),
+                   duplicate_blocker=lambda *args: None)
+    manager = Manager()
+    assert publication.finalize_status(manager, 'demo', 'alice', verdict, confidence, deps=deps) == expected
+    assert manager.updates == ([] if verdict == 'unknown' else [{'status': expected}])
+
+
+@pytest.mark.parametrize('enabled', [True, False])
+def test_batch_duplicate_finalization_changes_only_processed_unprotected_skills(enabled):
+    class Manager:
+        def __init__(self):
+            self.updates = []
+        def load(self, owner=None):
+            assert owner == 'alice'
+            return [{'name': name, 'source': 'learned', 'status': 'draft',
+                     'audit_verdict': 'pass', 'confidence': .95, 'uses': uses}
+                    for name, uses in [('demo', 10), ('demo-1', 0), ('demo-2', 20), ('demo-3', 30)]]
+        def update_skill(self, name, fields, owner=None):
+            self.updates.append((name, fields, owner))
+    deps = replace(routes._audit_dependencies(), auto_publish_policy=lambda owner: (enabled, .85))
+    manager = Manager()
+    publication.finalize_batch(manager, [{'skill': 'demo', 'result': 'pass'},
+                                    {'skill': 'demo-1', 'result': 'pass'},
+                                    {'skill': 'demo-3', 'result': 'approval_required'}],
+                          'alice', lambda message: None, deps=deps)
+    expected = [('demo', {'status': 'published'}, 'alice')] if enabled else []
+    assert manager.updates == expected + [('demo-1', {'status': 'binned'}, 'alice')]
+
+
+@pytest.fixture
+def approval_route(monkeypatch):
+    store = ToolApprovalStore()
+    monkeypatch.setattr('src.tool_approvals.tool_approval_store', store)
+    monkeypatch.setattr(routes, 'get_current_user', lambda req: req.state.user)
+    monkeypatch.setattr(routes, '_skill_test_jobs', {})
+    class Manager:
+        def load(self, owner=None):
+            return [{'name': 'demo', 'owner': owner}]
+    pending = store.create(owner='alice', session_id=None, origin_run_id='run', tool_name='bash',
+        content='printf approved', workspace=None, external_untrusted_context_seen=True,
+        capabilities=capabilities_for_action('bash', 'printf approved'))
+    job = {'status': 'awaiting_approval', 'log': [], 'task': 'task',
+           'approval': pending.public_payload(), '_transcript': ['untrusted result'],
+           '_run': {'owner': 'alice', 'md': 'untrusted skill', 'url': 'url', 'model': 'm'}}
+    routes._skill_test_jobs[('alice', 'demo')] = job
+    return endpoint('POST', '/{skill_id}/test-approval', Manager()), store, pending, job
+
+
+async def test_denied_skill_approval_retires_state_without_spawning(approval_route, monkeypatch):
+    approve, store, pending, job = approval_route
+    async def run(*args, **kwargs):
+        pytest.fail('denial spawned a test')
+    monkeypatch.setattr(routes, '_run_skill_test_job', run)
+    result = await approve(request(body={'approval_id': pending.approval_id, 'decision': 'deny'}), 'demo')
+    assert result == {'ok': True, 'status': 'done', 'decision': 'deny'}
+    assert store.peek(pending.approval_id) is None
+    assert job['verdict']['verdict'] == 'inconclusive'
+    assert not {'approval', '_run', '_transcript'} & job.keys()
+
+
+@pytest.mark.parametrize('case,status', [('other_owner', 409), ('mismatch', 409), ('consumed', 409), ('invalid_decision', 400)])
+async def test_invalid_skill_approval_cannot_resume(approval_route, monkeypatch, case, status):
+    approve, store, pending, job = approval_route
+    async def run(*args, **kwargs):
+        pytest.fail('invalid approval resumed a test')
+    monkeypatch.setattr(routes, '_run_skill_test_job', run)
+    owner = 'bob' if case == 'other_owner' else 'alice'
+    if case == 'other_owner':
+        routes._skill_test_jobs[('bob', 'demo')] = job
+    if case == 'consumed':
+        store.consume(pending.approval_id, decision='deny', owner='alice', session_id=None)
+    body = {'approval_id': 'wrong' if case == 'mismatch' else pending.approval_id,
+            'decision': 'approve_task' if case == 'invalid_decision' else 'approve'}
+    with pytest.raises(HTTPException) as error:
+        await approve(request(owner, body), 'demo')
+    assert error.value.status_code == status
+    assert job['status'] == 'awaiting_approval'
+
+
+async def test_allowed_skill_approval_is_single_action_and_cannot_be_reused(approval_route, monkeypatch):
+    approve, store, pending, job = approval_route
+    resumed = []
+    async def run(*args, **kwargs):
+        resumed.append((args, kwargs))
+    monkeypatch.setattr(routes, '_run_skill_test_job', run)
+    body = {'approval_id': pending.approval_id, 'decision': 'approve'}
+    assert await approve(request(body=body), 'demo') == {'ok': True, 'status': 'running', 'decision': 'approve'}
+    await asyncio.sleep(0)
+    assert len(resumed) == 1 and resumed[0][0][7] == 'alice'
+    grant = resumed[0][1]['exact_approval']
+    assert grant.pending is pending and grant.allow_remaining_actions is False
+    assert grant.grants_chat_session is False
+    assert store.peek(pending.approval_id) is None
+    messages = resumed[0][1]['messages']
+    tainted = [m for m in messages if m.get('metadata', {}).get('tool_gate_untrusted')]
+    assert len(tainted) == 2
+    assert any('untrusted result' in m['content'] for m in tainted)
+    with pytest.raises(HTTPException) as error:
+        await approve(request(body=body), 'demo')
+    assert error.value.status_code == 409
+    assert len(resumed) == 1
+
+
+@pytest.mark.parametrize('scope,selected,skip,names,expected_scope', [
+    ('all', None, False, ['draft', 'published', 'checked'], 'all'),
+    ('drafts', None, False, ['draft'], 'unchecked'),
+    ('all', ['published', 'draft', 'draft', 'builtin', 'missing'], False, ['published', 'draft'], 'selected'),
+    ('all', None, True, ['draft', 'published'], 'all'),
+])
+def test_manual_audit_selection_preserves_published_and_builtin_rules(scope, selected, skip, names, expected_scope):
+    class Manager:
+        def load(self, owner=None):
+            assert owner == 'alice'
+            return [{'name': 'draft', 'status': 'draft'}, {'name': 'published', 'status': 'published'},
+                    {'name': 'checked', 'audit_verdict': 'pass'}, {'name': 'builtin', 'source': 'builtin'}]
+    assert job_coordinator.select_audit_names(Manager(), 'alice', scope, selected, skip) == (names, expected_scope)

From c74f4756796a48780f02b2ca913528c013d9c60a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Robert=20Vind-Gardo=C8=99?=
 <41092915+robyroro@users.noreply.github.com>
Date: Thu, 15 Oct 2026 13:08:58 +0300
Subject: [PATCH 19/53] fix(upload): honor no-login mode after account setup
 (#6528)

* fix(upload): honor no-login mode after account setup

* ci: refresh checks against the current dev base

* test(upload): add regression tests for unconfigured auth and no-login POST

* fix(upload): fail closed on missing auth_manager and preserve cross-user isolation

Enforce strict cross-user isolation so that authenticated users cannot access
files owned by other accounts when app.state.auth_manager is absent or None.
Fail closed with HTTP 503 for non-loopback requests when AUTH_ENABLED=true and
authentication infrastructure is unexpectedly unavailable, while preserving
intended single-user mode (AUTH_ENABLED=false) and intentional first-run setup
mode (auth_manager.is_configured=False).

* fix(upload): eliminate fail-open paths for unconfigured manager and loopback transport

- Eliminate early return on unconfigured auth_manager (Finding A): fail closed with HTTP 401 Setup required
- Eliminate loopback transport bypass when auth_manager is missing (Finding B): fail closed with HTTP 503
- Enforce strict ownership isolation: non-owners and legacy ownerless uploads require verified administrator access
- Add regression suites in tests/test_upload_no_login.py covering Finding A, Finding B, bearer tokens, and ownerless files
- Explicitly set AUTH_ENABLED=false for unauthenticated tests in tests/test_upload_routes_owner_scope.py

* fix(upload): prevent delegated API tokens from inheriting admin privileges and enforce upload scopes

- Prevent delegated bearer API credentials from inheriting interactive administrator privileges over other users' files or legacy ownerless files.
- Enforce granular upload scopes for delegated credentials: chat and documents:write for upload creation and vision OCR editing; chat, documents:read, and documents:write for downloads, thumbnails, and vision OCR reads.
- Reject requests with missing token owners or reserved sentinel identities (api, demo, system, internal-tool) with 403 Forbidden.
- Add comprehensive regression tests in tests/test_upload_no_login.py verifying delegated token scope isolation, sentinel rejection, owner isolation, and untouched OCR state on rejected edits.

---------

Co-authored-by: PR #6029 Reviewer <reviewer@odysseus-review.local>
---
 routes/upload_routes.py                 | 101 ++-
 tests/test_upload_no_login.py           | 888 ++++++++++++++++++++++++
 tests/test_upload_routes_owner_scope.py |   2 +
 3 files changed, 966 insertions(+), 25 deletions(-)
 create mode 100644 tests/test_upload_no_login.py

diff --git a/routes/upload_routes.py b/routes/upload_routes.py
index 0978f2217..347da487e 100644
--- a/routes/upload_routes.py
+++ b/routes/upload_routes.py
@@ -21,7 +21,8 @@ from core.database import (
     Note,
     Session as DbSession,
 )
-from src.auth_helpers import effective_user
+from src.auth_helpers import effective_user, is_delegated_credential
+from src.owner_identity import auth_disabled, is_request_sentinel_owner
 from src.attachment_refs import attachment_refs_from_metadata
 from src.constants import GENERATED_IMAGES_DIR
 from src.path_confinement import is_inside
@@ -34,6 +35,8 @@ from src.upload_handler import (
 logger = logging.getLogger(__name__)
 
 router = APIRouter(prefix="/api/upload", tags=["upload"])
+UPLOAD_READ_SCOPES = frozenset({"chat", "documents:read", "documents:write"})
+UPLOAD_WRITE_SCOPES = frozenset({"chat", "documents:write"})
 UPLOAD_RESPONSE_HEADERS = {"X-Content-Type-Options": "nosniff"}
 
 def _upload_ids_from_persisted_text(value: object) -> set[str]:
@@ -178,6 +181,52 @@ def setup_upload_routes(upload_handler):
 
         raise HTTPException(404, "File not found")
 
+    def _verify_upload_access(
+        request: Request,
+        file_owner: str | None,
+        *,
+        write: bool = False,
+    ) -> None:
+        if auth_disabled():
+            return
+
+        auth_mgr = getattr(request.app.state, "auth_manager", None)
+        if auth_mgr is None:
+            raise HTTPException(503, "Authentication service unavailable")
+
+        if not getattr(auth_mgr, "is_configured", False):
+            raise HTTPException(401, "Setup required")
+
+        current_user = effective_user(request)
+        if not current_user or is_request_sentinel_owner(current_user):
+            raise HTTPException(403, "Access denied")
+
+        # Delegated credentials (bearer API tokens):
+        # Establish token owner identity but NEVER inherit interactive administrator privileges.
+        if is_delegated_credential(request):
+            token_owner = getattr(request.state, "api_token_owner", None)
+            if not token_owner or is_request_sentinel_owner(token_owner):
+                raise HTTPException(403, "API token has no valid owner")
+
+            token_scopes = set(getattr(request.state, "api_token_scopes", []) or [])
+            required_scopes = UPLOAD_WRITE_SCOPES if write else UPLOAD_READ_SCOPES
+            if not token_scopes.intersection(required_scopes):
+                raise HTTPException(403, f"API token missing required scope: {' or '.join(sorted(required_scopes))}")
+
+            # Non-owners and legacy ownerless uploads are strictly forbidden for delegated tokens.
+            if file_owner is None or current_user != file_owner:
+                raise HTTPException(404, "File not found")
+            return
+
+        # Interactive session (cookie-authenticated human):
+        # Owner access
+        if file_owner is not None and current_user == file_owner:
+            return
+
+        # Non-owner or legacy ownerless upload: administrator only
+        if not (hasattr(auth_mgr, "is_admin") and auth_mgr.is_admin(current_user)):
+            raise HTTPException(404, "File not found")
+
     def _valid_session_id_for_owner(db, session_id: str | None, owner: str | None) -> str | None:
         if not session_id:
             return None
@@ -280,6 +329,25 @@ def setup_upload_routes(upload_handler):
             session_id = None
         if not files:
             raise HTTPException(400, "No files uploaded")
+
+        if not auth_disabled():
+            app = getattr(request, "app", None)
+            if app is not None:
+                auth_mgr = getattr(getattr(app, "state", None), "auth_manager", None)
+                if auth_mgr is None:
+                    raise HTTPException(503, "Authentication service unavailable")
+                if not getattr(auth_mgr, "is_configured", False):
+                    raise HTTPException(401, "Setup required")
+            current_user = effective_user(request)
+            if not current_user or is_request_sentinel_owner(current_user):
+                raise HTTPException(403, "Access denied")
+            if is_delegated_credential(request):
+                token_owner = getattr(request.state, "api_token_owner", None)
+                if not token_owner or is_request_sentinel_owner(token_owner):
+                    raise HTTPException(403, "API token has no valid owner")
+                token_scopes = set(getattr(request.state, "api_token_scopes", []) or [])
+                if not token_scopes.intersection(UPLOAD_WRITE_SCOPES):
+                    raise HTTPException(403, f"API token missing required scope: {' or '.join(sorted(UPLOAD_WRITE_SCOPES))}")
             
         client_ip = request.client.host if request.client else "unknown"
         out = []
@@ -303,6 +371,8 @@ def setup_upload_routes(upload_handler):
         for u in files:
             try:
                 owner = effective_user(request)
+                if is_request_sentinel_owner(owner):
+                    owner = None
                 meta = upload_handler.save_upload(u, client_ip, owner=owner)
                 promoted_gallery_id = _promote_chat_image_to_gallery(meta, owner, session_id, gallery_id)
                 item = {
@@ -382,15 +452,8 @@ def setup_upload_routes(upload_handler):
         info = next((fi for fi in db.values() if fi.get("id") == file_id), None)
         if info:
             original_name = info.get("name", file_id)
-        auth_mgr = getattr(request.app.state, "auth_manager", None)
-        auth_configured = bool(auth_mgr and auth_mgr.is_configured)
-        current_user = effective_user(request)
         file_owner = info.get("owner") if info else None
-        if auth_configured:
-            if not current_user:
-                raise HTTPException(403, "Access denied")
-            if file_owner != current_user and not auth_mgr.is_admin(current_user):
-                raise HTTPException(404, "File not found")
+        _verify_upload_access(request, file_owner)
         path = _resolve_upload_path(file_id)
         mime = (info or {}).get("mime") or _mt.guess_type(path)[0] or "application/octet-stream"
         from fastapi.responses import FileResponse
@@ -471,15 +534,9 @@ def setup_upload_routes(upload_handler):
         if not upload_handler.validate_upload_id(file_id):
             raise HTTPException(400, "Invalid file ID")
         info = _load_upload_info(file_id)
-        auth_mgr = getattr(request.app.state, "auth_manager", None)
-        auth_configured = bool(auth_mgr and auth_mgr.is_configured)
-        current_user = effective_user(request)
         file_owner = info.get("owner") if info else None
-        if auth_configured:
-            if not current_user:
-                raise HTTPException(403, "Access denied")
-            if file_owner != current_user and not auth_mgr.is_admin(current_user):
-                raise HTTPException(404, "File not found")
+        _verify_upload_access(request, file_owner)
+        current_user = effective_user(request)
         path = _resolve_upload_path(file_id)
         import mimetypes as _mt
         mime = (info or {}).get("mime") or _mt.guess_type(path)[0] or ""
@@ -517,15 +574,9 @@ def setup_upload_routes(upload_handler):
         info = _load_upload_info(file_id)
         if not info:
             raise HTTPException(404, "File not found")
-        auth_mgr = getattr(request.app.state, "auth_manager", None)
-        auth_configured = bool(auth_mgr and auth_mgr.is_configured)
-        current_user = effective_user(request)
         file_owner = info.get("owner")
-        if auth_configured:
-            if not current_user:
-                raise HTTPException(403, "Access denied")
-            if file_owner != current_user and not auth_mgr.is_admin(current_user):
-                raise HTTPException(404, "File not found")
+        _verify_upload_access(request, file_owner, write=True)
+        current_user = effective_user(request)
         _resolve_upload_path(file_id)
         try:
             body = await request.json()
diff --git a/tests/test_upload_no_login.py b/tests/test_upload_no_login.py
new file mode 100644
index 000000000..cbc4e046a
--- /dev/null
+++ b/tests/test_upload_no_login.py
@@ -0,0 +1,888 @@
+import io
+import json
+from types import SimpleNamespace
+
+import pytest
+from fastapi import APIRouter, FastAPI, Request
+from fastapi.testclient import TestClient
+from PIL import Image
+
+
+@pytest.fixture
+def upload_client(tmp_path, monkeypatch):
+    from routes import upload_routes
+    from src.upload_handler import UploadHandler
+
+    upload_dir = tmp_path / "uploads"
+    upload_dir.mkdir()
+    file_id = "a" * 32 + ".png"
+    image_path = upload_dir / file_id
+    Image.new("RGB", (640, 360), "red").save(image_path)
+    (upload_dir / "uploads.json").write_text(
+        json.dumps({"alice:image": {
+            "id": file_id,
+            "path": str(image_path),
+            "name": "image.png",
+            "mime": "image/png",
+            "owner": "alice",
+        }}),
+        encoding="utf-8",
+    )
+    cache_dir = upload_dir / ".vision"
+    cache_dir.mkdir()
+    cache_path = cache_dir / f"{file_id}.txt"
+    cache_path.write_text("A red image", encoding="utf-8")
+    monkeypatch.setattr(upload_routes, "router", APIRouter(prefix="/api/upload"))
+    handler = UploadHandler(str(tmp_path), str(upload_dir))
+    router, _cleanup = upload_routes.setup_upload_routes(handler)
+    app = FastAPI()
+    app.state.auth_manager = SimpleNamespace(
+        is_configured=True,
+        is_admin=lambda user: user == "admin",
+    )
+
+    @app.middleware("http")
+    async def set_user(request: Request, call_next):
+        user = request.headers.get("x-test-user")
+        if user:
+            request.state.current_user = user
+        if request.headers.get("x-test-api-token"):
+            request.state.current_user = "api"
+            request.state.api_token = True
+            request.state.api_token_owner = request.headers.get("x-test-api-token-owner")
+            scopes_header = request.headers.get("x-test-api-token-scopes")
+            if scopes_header is not None:
+                request.state.api_token_scopes = [s.strip() for s in scopes_header.split(",") if s.strip()]
+            else:
+                request.state.api_token_scopes = ["chat"]
+        return await call_next(request)
+
+    app.include_router(router)
+    with TestClient(app) as client:
+        yield client, file_id, image_path, cache_path
+
+
+@pytest.mark.parametrize("auth_enabled", ["false", " false ", "true"])
+@pytest.mark.parametrize("operation", ["download", "thumbnail", "read_vision", "edit_vision"])
+def test_upload_access_after_disabling_login(upload_client, monkeypatch, auth_enabled, operation):
+    monkeypatch.setenv("AUTH_ENABLED", auth_enabled)
+    client, file_id, image_path, cache_path = upload_client
+    url = f"/api/upload/{file_id}"
+    if operation == "edit_vision":
+        response = client.put(f"{url}/vision", json={"text": "Edited description"})
+    elif operation == "read_vision":
+        response = client.get(f"{url}/vision")
+    else:
+        response = client.get(url, params={"thumb": int(operation == "thumbnail")})
+
+    if auth_enabled.strip() == "true":
+        assert response.status_code == 403
+        assert cache_path.read_text(encoding="utf-8") == "A red image"
+        return
+
+    assert response.status_code == 200, response.text
+    if operation == "download":
+        assert response.content == image_path.read_bytes()
+    elif operation == "thumbnail":
+        assert response.headers["content-type"] == "image/jpeg"
+        assert (image_path.parent / ".thumbs" / f"{file_id}.jpg").is_file()
+    elif operation == "read_vision":
+        assert response.json() == {"text": "A red image", "cached": True}
+    else:
+        assert response.json() == {"ok": True}
+        assert cache_path.read_text(encoding="utf-8") == "Edited description"
+
+
+# ===========================================================================
+# 1. AUTH_ENABLED=true with auth_manager.is_configured=False
+# ===========================================================================
+
+
+@pytest.mark.parametrize("operation", ["download", "thumbnail", "read_vision", "edit_vision"])
+def test_unconfigured_auth_manager_fails_closed(upload_client, monkeypatch, operation):
+    """When AUTH_ENABLED=true and auth_manager is not configured (e.g. first-run
+    before initial setup is complete), existing uploads must NOT be exposed
+    and modification attempts must be rejected with 401 Setup required."""
+    monkeypatch.setenv("AUTH_ENABLED", "true")
+    client, file_id, image_path, cache_path = upload_client
+    client.app.state.auth_manager = SimpleNamespace(
+        is_configured=False,
+        is_admin=lambda user: False,
+    )
+    url = f"/api/upload/{file_id}"
+
+    if operation == "edit_vision":
+        response = client.put(f"{url}/vision", json={"text": "Defaced OCR"})
+    elif operation == "read_vision":
+        response = client.get(f"{url}/vision")
+    else:
+        response = client.get(url, params={"thumb": int(operation == "thumbnail")})
+
+    assert response.status_code == 401, response.text
+    if operation == "edit_vision":
+        assert cache_path.read_text(encoding="utf-8") == "A red image"
+
+
+@pytest.mark.parametrize("caller,expected_status", [
+    (None, 403),        # Anonymous caller is rejected with 403 Access denied
+    ("bob", 404),       # Non-owner non-admin caller is rejected with 404 File not found
+    ("alice", 200),     # Legitimate owner is allowed
+    ("admin", 200),     # Admin user is allowed
+])
+def test_auth_configured_enforces_owner_isolation(upload_client, monkeypatch, caller, expected_status):
+    """When AUTH_ENABLED=true and auth_manager IS configured, owner isolation
+    must be strictly enforced: anonymous callers get 403, cross-user callers
+    get 404, while the owner and admin are permitted."""
+    monkeypatch.setenv("AUTH_ENABLED", "true")
+    client, file_id, image_path, _ = upload_client
+    client.app.state.auth_manager = SimpleNamespace(
+        is_configured=True,
+        is_admin=lambda user: user == "admin",
+    )
+    headers = {"x-test-user": caller} if caller else {}
+
+    response = client.get(f"/api/upload/{file_id}", headers=headers)
+    assert response.status_code == expected_status
+    if expected_status == 200:
+        assert response.content == image_path.read_bytes()
+
+
+# ===========================================================================
+# 2. Finding A: Unconfigured manager in route state must NOT grant access
+# ===========================================================================
+
+
+@pytest.mark.parametrize("auth_method", ["cookie", "bearer"])
+@pytest.mark.parametrize("operation", ["download", "thumbnail", "read_vision", "edit_vision"])
+def test_finding_a_unconfigured_route_manager_denies_cross_user(upload_client, monkeypatch, auth_method, operation):
+    """Finding A Regression Test:
+    When AUTH_ENABLED=true and middleware authenticates Bob, but app.state.auth_manager
+    is an unconfigured manager instance (is_configured=False), Bob MUST NOT be granted
+    access to Alice's upload. Access must fail closed with 401 Setup required."""
+    monkeypatch.setenv("AUTH_ENABLED", "true")
+    client, file_id, image_path, cache_path = upload_client
+
+    # Route observes an unconfigured manager
+    client.app.state.auth_manager = SimpleNamespace(
+        is_configured=False,
+        is_admin=lambda user: False,
+    )
+
+    url = f"/api/upload/{file_id}"
+    headers = {}
+    if auth_method == "cookie":
+        headers["x-test-user"] = "bob"
+    else:
+        # Bearer token owned by Bob
+        headers["x-test-api-token"] = "1"
+        headers["x-test-api-token-owner"] = "bob"
+
+    if operation == "edit_vision":
+        response = client.put(f"{url}/vision", headers=headers, json={"text": "Defaced by Bob"})
+    elif operation == "read_vision":
+        response = client.get(f"{url}/vision", headers=headers)
+    else:
+        response = client.get(url, headers=headers, params={"thumb": int(operation == "thumbnail")})
+
+    # Must fail closed: 401 Setup required (never 200)
+    assert response.status_code == 401, f"Expected 401, got {response.status_code}: {response.text}"
+    if operation == "edit_vision":
+        # OCR cache must remain untouched
+        assert cache_path.read_text(encoding="utf-8") == "A red image"
+
+
+# ===========================================================================
+# 3. Finding B: Loopback requests under infrastructure failure must fail closed
+# ===========================================================================
+
+
+@pytest.mark.parametrize("loopback_host", ["127.0.0.1", "::1", "localhost"])
+@pytest.mark.parametrize("proxy_header", [None, "X-Forwarded-For", "CF-Connecting-IP"])
+@pytest.mark.parametrize("caller", [None, "bob", "admin"])
+def test_finding_b_loopback_infrastructure_failure_fails_closed(
+    upload_client, monkeypatch, loopback_host, proxy_header, caller
+):
+    """Finding B Regression Test:
+    When AUTH_ENABLED=true and app.state.auth_manager is None (infrastructure failure),
+    loopback requests (127.0.0.1, ::1, localhost) MUST NOT bypass authentication or
+    gain access to uploads. All requests must fail closed with 503 Service Unavailable."""
+    monkeypatch.setenv("AUTH_ENABLED", "true")
+    client, file_id, _, cache_path = upload_client
+    if hasattr(client.app.state, "auth_manager"):
+        delattr(client.app.state, "auth_manager")
+
+    headers = {}
+    if caller:
+        headers["x-test-user"] = caller
+    if proxy_header:
+        headers[proxy_header] = "203.0.113.195"
+
+    url = f"/api/upload/{file_id}"
+
+    # Test download
+    resp_dl = client.get(url, headers=headers)
+    assert resp_dl.status_code == 503, f"Loopback host {loopback_host} leaked file: {resp_dl.status_code}"
+
+    # Test thumbnail
+    resp_th = client.get(url, headers=headers, params={"thumb": 1})
+    assert resp_th.status_code == 503
+
+    # Test vision read
+    resp_vr = client.get(f"{url}/vision", headers=headers)
+    assert resp_vr.status_code == 503
+
+    # Test vision edit
+    resp_ve = client.put(f"{url}/vision", headers=headers, json={"text": "Defaced"})
+    assert resp_ve.status_code == 503
+    assert cache_path.read_text(encoding="utf-8") == "A red image"
+
+
+# ===========================================================================
+# 4. Absent auth_manager (infrastructure failure) fail-closed behavior
+# ===========================================================================
+
+
+@pytest.mark.parametrize("operation", ["download", "thumbnail", "read_vision", "edit_vision"])
+def test_absent_auth_manager_fails_closed(upload_client, monkeypatch, operation):
+    """When AUTH_ENABLED=true and auth_manager is absent from app.state (unexpected
+    infrastructure failure), upload routes must fail closed (503 Service Unavailable)
+    rather than failing open."""
+    monkeypatch.setenv("AUTH_ENABLED", "true")
+    client, file_id, image_path, cache_path = upload_client
+    if hasattr(client.app.state, "auth_manager"):
+        delattr(client.app.state, "auth_manager")
+
+    url = f"/api/upload/{file_id}"
+    if operation == "edit_vision":
+        response = client.put(f"{url}/vision", json={"text": "No auth_manager edit"})
+    elif operation == "read_vision":
+        response = client.get(f"{url}/vision")
+    else:
+        response = client.get(url, params={"thumb": int(operation == "thumbnail")})
+
+    assert response.status_code == 503, response.text
+    if operation == "edit_vision":
+        assert cache_path.read_text(encoding="utf-8") == "A red image"
+
+
+def test_absent_auth_manager_restoring_auth_enforces_access(upload_client, monkeypatch):
+    """Verify that when auth_manager is absent, routes fail closed (503),
+    and attaching a configured auth_manager enforces full owner isolation."""
+    monkeypatch.setenv("AUTH_ENABLED", "true")
+    client, file_id, _, _ = upload_client
+
+    # First, verify access fails closed when auth_manager is absent
+    if hasattr(client.app.state, "auth_manager"):
+        delattr(client.app.state, "auth_manager")
+    assert client.get(f"/api/upload/{file_id}").status_code == 503
+
+    # Now attach configured auth_manager: anonymous access must fail closed (403),
+    # wrong owner gets 404, owner and admin get 200.
+    client.app.state.auth_manager = SimpleNamespace(
+        is_configured=True,
+        is_admin=lambda user: user == "admin",
+    )
+    assert client.get(f"/api/upload/{file_id}").status_code == 403
+    assert client.get(f"/api/upload/{file_id}", headers={"x-test-user": "bob"}).status_code == 404
+    assert client.get(f"/api/upload/{file_id}", headers={"x-test-user": "alice"}).status_code == 200
+    assert client.get(f"/api/upload/{file_id}", headers={"x-test-user": "admin"}).status_code == 200
+
+
+def test_authenticated_cross_user_with_absent_auth_manager_fails_closed(upload_client, monkeypatch):
+    """When AUTH_ENABLED=true, an authenticated non-owner (e.g. Bob) must NOT be able
+    to access Alice's upload when app.state.auth_manager is absent/None.
+    The route must fail closed (503 Service Unavailable)."""
+    monkeypatch.setenv("AUTH_ENABLED", "true")
+    client, file_id, _, cache_path = upload_client
+    if hasattr(client.app.state, "auth_manager"):
+        delattr(client.app.state, "auth_manager")
+
+    # Bob is authenticated but auth_manager is absent on app.state -> 503
+    resp_download = client.get(f"/api/upload/{file_id}", headers={"x-test-user": "bob"})
+    assert resp_download.status_code == 503
+
+    resp_thumb = client.get(f"/api/upload/{file_id}?thumb=1", headers={"x-test-user": "bob"})
+    assert resp_thumb.status_code == 503
+
+    resp_read_vision = client.get(f"/api/upload/{file_id}/vision", headers={"x-test-user": "bob"})
+    assert resp_read_vision.status_code == 503
+
+    resp_edit_vision = client.put(f"/api/upload/{file_id}/vision", headers={"x-test-user": "bob"}, json={"text": "Defaced"})
+    assert resp_edit_vision.status_code == 503
+    assert cache_path.read_text(encoding="utf-8") == "A red image"
+
+
+def test_absent_auth_manager_allows_access_when_auth_disabled(upload_client, monkeypatch):
+    """When AUTH_ENABLED=false, absent auth_manager must NOT block single-user access."""
+    monkeypatch.setenv("AUTH_ENABLED", "false")
+    client, file_id, image_path, cache_path = upload_client
+    if hasattr(client.app.state, "auth_manager"):
+        delattr(client.app.state, "auth_manager")
+
+    assert client.get(f"/api/upload/{file_id}").status_code == 200
+    assert client.get(f"/api/upload/{file_id}?thumb=1").status_code == 200
+    assert client.get(f"/api/upload/{file_id}/vision").status_code == 200
+    assert client.put(f"/api/upload/{file_id}/vision", json={"text": "Single user edit"}).status_code == 200
+    assert cache_path.read_text(encoding="utf-8") == "Single user edit"
+
+
+# ===========================================================================
+# 5. Bearer token identity & Legacy ownerless upload isolation
+# ===========================================================================
+
+
+def test_bearer_token_owner_isolation(upload_client, monkeypatch):
+    """Bearer tokens must resolve to their actual token owner (effective_user).
+    Alice's token gets 200 for Alice's upload, Bob's token gets 404, Admin's token
+    gets 404 (delegated tokens never inherit admin privileges on other users' files)."""
+    monkeypatch.setenv("AUTH_ENABLED", "true")
+    client, file_id, image_path, cache_path = upload_client
+    client.app.state.auth_manager = SimpleNamespace(
+        is_configured=True,
+        is_admin=lambda user: user == "admin",
+    )
+
+    # Bob's bearer token -> 404 (non-owner)
+    bob_headers = {"x-test-api-token": "1", "x-test-api-token-owner": "bob"}
+    assert client.get(f"/api/upload/{file_id}", headers=bob_headers).status_code == 404
+    assert client.get(f"/api/upload/{file_id}?thumb=1", headers=bob_headers).status_code == 404
+    assert client.get(f"/api/upload/{file_id}/vision", headers=bob_headers).status_code == 404
+    resp_edit = client.put(f"/api/upload/{file_id}/vision", headers=bob_headers, json={"text": "Defaced by Bob token"})
+    assert resp_edit.status_code == 404
+    assert cache_path.read_text(encoding="utf-8") == "A red image"
+
+    # Alice's bearer token -> 200 (legitimate owner)
+    alice_headers = {"x-test-api-token": "1", "x-test-api-token-owner": "alice"}
+    assert client.get(f"/api/upload/{file_id}", headers=alice_headers).status_code == 200
+    assert client.get(f"/api/upload/{file_id}?thumb=1", headers=alice_headers).status_code == 200
+    assert client.get(f"/api/upload/{file_id}/vision", headers=alice_headers).status_code == 200
+    resp_edit_alice = client.put(f"/api/upload/{file_id}/vision", headers=alice_headers, json={"text": "Updated by Alice token"})
+    assert resp_edit_alice.status_code == 200
+    assert cache_path.read_text(encoding="utf-8") == "Updated by Alice token"
+
+    # Admin's bearer token accessing Alice's file -> 404 (delegated token does NOT inherit admin access)
+    admin_headers = {"x-test-api-token": "1", "x-test-api-token-owner": "admin"}
+    assert client.get(f"/api/upload/{file_id}", headers=admin_headers).status_code == 404
+    assert client.get(f"/api/upload/{file_id}?thumb=1", headers=admin_headers).status_code == 404
+    assert client.get(f"/api/upload/{file_id}/vision", headers=admin_headers).status_code == 404
+    resp_edit_admin = client.put(f"/api/upload/{file_id}/vision", headers=admin_headers, json={"text": "Defaced by Admin token"})
+    assert resp_edit_admin.status_code == 404
+    assert cache_path.read_text(encoding="utf-8") == "Updated by Alice token"
+
+    # Interactive Admin session (cookie) accessing Alice's file -> 200
+    admin_cookie_headers = {"x-test-user": "admin"}
+    assert client.get(f"/api/upload/{file_id}", headers=admin_cookie_headers).status_code == 200
+    assert client.get(f"/api/upload/{file_id}?thumb=1", headers=admin_cookie_headers).status_code == 200
+    assert client.get(f"/api/upload/{file_id}/vision", headers=admin_cookie_headers).status_code == 200
+    resp_edit_admin_cookie = client.put(f"/api/upload/{file_id}/vision", headers=admin_cookie_headers, json={"text": "Admin override"})
+    assert resp_edit_admin_cookie.status_code == 200
+    assert cache_path.read_text(encoding="utf-8") == "Admin override"
+
+
+def test_legacy_ownerless_upload_isolation(tmp_path, monkeypatch):
+    """Legacy ownerless uploads (owner=None in uploads.json) must remain
+    administrator-only for interactive sessions when AUTH_ENABLED=true:
+    - Anonymous callers get 403 Access denied
+    - Regular authenticated users get 404 File not found
+    - Delegated bearer tokens (even admin-owned) get 404 File not found
+    - Verified interactive administrators get 200 OK"""
+    from routes import upload_routes
+    from src.upload_handler import UploadHandler
+
+    monkeypatch.setenv("AUTH_ENABLED", "true")
+    upload_dir = tmp_path / "uploads_legacy"
+    upload_dir.mkdir()
+    file_id = "f" * 32 + ".png"
+    img_path = upload_dir / file_id
+    Image.new("RGB", (100, 100), "blue").save(img_path)
+    (upload_dir / "uploads.json").write_text(
+        json.dumps({"legacy_key": {
+            "id": file_id,
+            "path": str(img_path),
+            "name": "legacy.png",
+            "mime": "image/png",
+            "owner": None,
+        }}),
+        encoding="utf-8",
+    )
+    monkeypatch.setattr(upload_routes, "router", APIRouter(prefix="/api/upload"))
+    handler = UploadHandler(str(tmp_path), str(upload_dir))
+    router, _cleanup = upload_routes.setup_upload_routes(handler)
+    app = FastAPI()
+    app.state.auth_manager = SimpleNamespace(
+        is_configured=True,
+        is_admin=lambda user: user == "admin",
+    )
+
+    @app.middleware("http")
+    async def set_user(request: Request, call_next):
+        user = request.headers.get("x-test-user")
+        if user:
+            request.state.current_user = user
+        if request.headers.get("x-test-api-token"):
+            request.state.current_user = "api"
+            request.state.api_token = True
+            request.state.api_token_owner = request.headers.get("x-test-api-token-owner")
+            scopes_header = request.headers.get("x-test-api-token-scopes")
+            if scopes_header is not None:
+                request.state.api_token_scopes = [s.strip() for s in scopes_header.split(",") if s.strip()]
+            else:
+                request.state.api_token_scopes = ["chat"]
+        return await call_next(request)
+
+    app.include_router(router)
+    with TestClient(app) as client:
+        # Anonymous -> 403
+        assert client.get(f"/api/upload/{file_id}").status_code == 403
+        assert client.get(f"/api/upload/{file_id}?thumb=1").status_code == 403
+        assert client.get(f"/api/upload/{file_id}/vision").status_code == 403
+
+        # Non-admin user "bob" (interactive cookie) -> 404
+        assert client.get(f"/api/upload/{file_id}", headers={"x-test-user": "bob"}).status_code == 404
+        assert client.get(f"/api/upload/{file_id}?thumb=1", headers={"x-test-user": "bob"}).status_code == 404
+        assert client.get(f"/api/upload/{file_id}/vision", headers={"x-test-user": "bob"}).status_code == 404
+
+        # Non-admin bearer token "bob" -> 404
+        bob_bearer = {"x-test-api-token": "1", "x-test-api-token-owner": "bob"}
+        assert client.get(f"/api/upload/{file_id}", headers=bob_bearer).status_code == 404
+
+        # Admin bearer token -> 404 (delegated token never inherits admin privileges on ownerless files)
+        admin_bearer = {"x-test-api-token": "1", "x-test-api-token-owner": "admin", "x-test-api-token-scopes": "chat"}
+        assert client.get(f"/api/upload/{file_id}", headers=admin_bearer).status_code == 404
+        assert client.get(f"/api/upload/{file_id}?thumb=1", headers=admin_bearer).status_code == 404
+        assert client.get(f"/api/upload/{file_id}/vision", headers=admin_bearer).status_code == 404
+        assert client.put(f"/api/upload/{file_id}/vision", headers=admin_bearer, json={"text": "Defaced"}).status_code == 404
+
+        # Admin user "admin" (interactive cookie) -> 200
+        assert client.get(f"/api/upload/{file_id}", headers={"x-test-user": "admin"}).status_code == 200
+        assert client.get(f"/api/upload/{file_id}?thumb=1", headers={"x-test-user": "admin"}).status_code == 200
+        assert client.get(f"/api/upload/{file_id}/vision", headers={"x-test-user": "admin"}).status_code == 200
+
+
+def test_delegated_token_can_access_own_file_when_owner_is_admin(tmp_path, monkeypatch):
+    """When a file is owned by 'admin', an admin-owned bearer token with valid scope
+    can access and edit it, but a non-admin token or user cannot."""
+    from routes import upload_routes
+    from src.upload_handler import UploadHandler
+
+    monkeypatch.setenv("AUTH_ENABLED", "true")
+    upload_dir = tmp_path / "uploads_admin_owned"
+    upload_dir.mkdir()
+    file_id = "e" * 32 + ".png"
+    img_path = upload_dir / file_id
+    Image.new("RGB", (100, 100), "green").save(img_path)
+    (upload_dir / "uploads.json").write_text(
+        json.dumps({"admin_key": {
+            "id": file_id,
+            "path": str(img_path),
+            "name": "admin_file.png",
+            "mime": "image/png",
+            "owner": "admin",
+        }}),
+        encoding="utf-8",
+    )
+    cache_dir = upload_dir / ".vision"
+    cache_dir.mkdir()
+    cache_path = cache_dir / f"{file_id}.txt"
+    cache_path.write_text("Admin green image", encoding="utf-8")
+
+    monkeypatch.setattr(upload_routes, "router", APIRouter(prefix="/api/upload"))
+    handler = UploadHandler(str(tmp_path), str(upload_dir))
+    router, _cleanup = upload_routes.setup_upload_routes(handler)
+    app = FastAPI()
+    app.state.auth_manager = SimpleNamespace(
+        is_configured=True,
+        is_admin=lambda user: user == "admin",
+    )
+
+    @app.middleware("http")
+    async def set_user(request: Request, call_next):
+        user = request.headers.get("x-test-user")
+        if user:
+            request.state.current_user = user
+        if request.headers.get("x-test-api-token"):
+            request.state.current_user = "api"
+            request.state.api_token = True
+            request.state.api_token_owner = request.headers.get("x-test-api-token-owner")
+            scopes_header = request.headers.get("x-test-api-token-scopes")
+            if scopes_header is not None:
+                request.state.api_token_scopes = [s.strip() for s in scopes_header.split(",") if s.strip()]
+            else:
+                request.state.api_token_scopes = ["chat"]
+        return await call_next(request)
+
+    app.include_router(router)
+    with TestClient(app) as client:
+        # Admin's bearer token accessing its own file -> 200
+        admin_bearer = {"x-test-api-token": "1", "x-test-api-token-owner": "admin", "x-test-api-token-scopes": "chat"}
+        assert client.get(f"/api/upload/{file_id}", headers=admin_bearer).status_code == 200
+        assert client.get(f"/api/upload/{file_id}/vision", headers=admin_bearer).status_code == 200
+        resp_put = client.put(f"/api/upload/{file_id}/vision", headers=admin_bearer, json={"text": "Admin updated own"})
+        assert resp_put.status_code == 200
+        assert cache_path.read_text(encoding="utf-8") == "Admin updated own"
+
+        # Bob's bearer token accessing admin's file -> 404
+        bob_bearer = {"x-test-api-token": "1", "x-test-api-token-owner": "bob", "x-test-api-token-scopes": "chat"}
+        assert client.get(f"/api/upload/{file_id}", headers=bob_bearer).status_code == 404
+        assert client.put(f"/api/upload/{file_id}/vision", headers=bob_bearer, json={"text": "Bob deface"}).status_code == 404
+        assert cache_path.read_text(encoding="utf-8") == "Admin updated own"
+
+        # Bob's interactive session accessing admin's file -> 404
+        assert client.get(f"/api/upload/{file_id}", headers={"x-test-user": "bob"}).status_code == 404
+
+
+@pytest.mark.parametrize("scope,can_read,can_write", [
+    ("chat", True, True),
+    ("documents:write", True, True),
+    ("documents:read", True, False),
+    ("todos:read", False, False),
+    ("todos:write", False, False),
+    ("", False, False),
+])
+def test_delegated_token_scope_matrix(upload_client, monkeypatch, scope, can_read, can_write):
+    """Test token scope enforcement on legitimate owner's upload (Alice's file):
+    - chat and documents:write allow both read and write
+    - documents:read allows read but rejects write with 403
+    - unrelated scopes (todos:read, todos:write) or empty scopes reject with 403
+    - on rejected write, persisted OCR content remains untouched."""
+    monkeypatch.setenv("AUTH_ENABLED", "true")
+    client, file_id, image_path, cache_path = upload_client
+    initial_text = cache_path.read_text(encoding="utf-8")
+
+    headers = {
+        "x-test-api-token": "1",
+        "x-test-api-token-owner": "alice",
+        "x-test-api-token-scopes": scope,
+    }
+
+    # Test read operations
+    resp_dl = client.get(f"/api/upload/{file_id}", headers=headers)
+    resp_th = client.get(f"/api/upload/{file_id}?thumb=1", headers=headers)
+    resp_vr = client.get(f"/api/upload/{file_id}/vision", headers=headers)
+
+    if can_read:
+        assert resp_dl.status_code == 200
+        assert resp_th.status_code == 200
+        assert resp_vr.status_code == 200
+    else:
+        assert resp_dl.status_code == 403
+        assert resp_th.status_code == 403
+        assert resp_vr.status_code == 403
+
+    # Test write operation (OCR edit)
+    resp_ve = client.put(f"/api/upload/{file_id}/vision", headers=headers, json={"text": f"Edit by {scope}"})
+    if can_write:
+        assert resp_ve.status_code == 200
+        assert cache_path.read_text(encoding="utf-8") == f"Edit by {scope}"
+    else:
+        assert resp_ve.status_code == 403
+        # Persisted content must remain completely unchanged
+        assert cache_path.read_text(encoding="utf-8") == initial_text
+
+
+@pytest.mark.parametrize("sentinel_owner", ["api", "internal-tool", "demo", "system", ""])
+def test_delegated_token_sentinel_or_missing_owner_denied(upload_client, monkeypatch, sentinel_owner):
+    """Delegated tokens with sentinel owner names or missing owner must be rejected with 403."""
+    monkeypatch.setenv("AUTH_ENABLED", "true")
+    client, file_id, _, cache_path = upload_client
+    initial_text = cache_path.read_text(encoding="utf-8")
+
+    headers = {"x-test-api-token": "1", "x-test-api-token-scopes": "chat"}
+    if sentinel_owner:
+        headers["x-test-api-token-owner"] = sentinel_owner
+
+    resp_dl = client.get(f"/api/upload/{file_id}", headers=headers)
+    assert resp_dl.status_code == 403
+
+    resp_ve = client.put(f"/api/upload/{file_id}/vision", headers=headers, json={"text": "Defaced by sentinel"})
+    assert resp_ve.status_code == 403
+    assert cache_path.read_text(encoding="utf-8") == initial_text
+
+
+@pytest.mark.parametrize("sentinel_user", ["api", "internal-tool", "demo", "system"])
+def test_interactive_sentinel_user_denied(upload_client, monkeypatch, sentinel_user):
+    """Interactive requests claiming sentinel user identities must be rejected with 403."""
+    monkeypatch.setenv("AUTH_ENABLED", "true")
+    client, file_id, _, cache_path = upload_client
+
+    headers = {"x-test-user": sentinel_user}
+    assert client.get(f"/api/upload/{file_id}", headers=headers).status_code == 403
+    assert client.put(f"/api/upload/{file_id}/vision", headers=headers, json={"text": "Defaced"}).status_code == 403
+    assert cache_path.read_text(encoding="utf-8") == "A red image"
+
+
+def test_upload_post_delegated_token_authorization(tmp_path, monkeypatch):
+    """POST /api/upload with AUTH_ENABLED=true and delegated bearer tokens:
+    - Token with 'chat' or 'documents:write' succeeds and sets file owner to token owner
+    - Token with 'documents:read' is rejected with 403
+    - Token with 'todos:read' is rejected with 403
+    - Token with missing owner is rejected with 403
+    - Token with sentinel owner ('api') is rejected with 403"""
+    from routes import upload_routes
+    from src.upload_handler import UploadHandler
+
+    monkeypatch.setenv("AUTH_ENABLED", "true")
+    upload_dir = tmp_path / "uploads_post_token"
+    upload_dir.mkdir()
+    monkeypatch.setattr(upload_routes, "router", APIRouter(prefix="/api/upload"))
+    handler = UploadHandler(str(tmp_path), str(upload_dir))
+    router, _cleanup = upload_routes.setup_upload_routes(handler)
+    app = FastAPI()
+    app.state.auth_manager = SimpleNamespace(
+        is_configured=True,
+        is_admin=lambda user: user == "admin",
+    )
+
+    @app.middleware("http")
+    async def set_user(request: Request, call_next):
+        user = request.headers.get("x-test-user")
+        if user:
+            request.state.current_user = user
+        if request.headers.get("x-test-api-token"):
+            request.state.current_user = "api"
+            request.state.api_token = True
+            request.state.api_token_owner = request.headers.get("x-test-api-token-owner")
+            scopes_header = request.headers.get("x-test-api-token-scopes")
+            if scopes_header is not None:
+                request.state.api_token_scopes = [s.strip() for s in scopes_header.split(",") if s.strip()]
+            else:
+                request.state.api_token_scopes = ["chat"]
+        return await call_next(request)
+
+    app.include_router(router)
+
+    with TestClient(app) as client:
+        # 1. Valid token with 'chat' scope
+        resp_chat = client.post(
+            "/api/upload",
+            files=[("files", ("chat.txt", io.BytesIO(b"chat content"), "text/plain"))],
+            headers={"x-test-api-token": "1", "x-test-api-token-owner": "alice", "x-test-api-token-scopes": "chat"},
+        )
+        assert resp_chat.status_code == 200
+        chat_id = resp_chat.json()["files"][0]["id"]
+        index = handler._load_upload_index()
+        rec_chat = next(v for v in index.values() if v.get("id") == chat_id)
+        assert rec_chat["owner"] == "alice"
+
+        # 2. Valid token with 'documents:write' scope
+        resp_doc = client.post(
+            "/api/upload",
+            files=[("files", ("doc.txt", io.BytesIO(b"doc content"), "text/plain"))],
+            headers={"x-test-api-token": "1", "x-test-api-token-owner": "bob", "x-test-api-token-scopes": "documents:write"},
+        )
+        assert resp_doc.status_code == 200
+        doc_id = resp_doc.json()["files"][0]["id"]
+        index = handler._load_upload_index()
+        rec_doc = next(v for v in index.values() if v.get("id") == doc_id)
+        assert rec_doc["owner"] == "bob"
+
+        # 3. Token with read-only 'documents:read' scope -> 403
+        resp_ro = client.post(
+            "/api/upload",
+            files=[("files", ("ro.txt", io.BytesIO(b"ro content"), "text/plain"))],
+            headers={"x-test-api-token": "1", "x-test-api-token-owner": "alice", "x-test-api-token-scopes": "documents:read"},
+        )
+        assert resp_ro.status_code == 403
+
+        # 4. Token with unrelated 'todos:read' scope -> 403
+        resp_unrelated = client.post(
+            "/api/upload",
+            files=[("files", ("unrelated.txt", io.BytesIO(b"content"), "text/plain"))],
+            headers={"x-test-api-token": "1", "x-test-api-token-owner": "alice", "x-test-api-token-scopes": "todos:read"},
+        )
+        assert resp_unrelated.status_code == 403
+
+        # 5. Token with missing owner -> 403
+        resp_no_owner = client.post(
+            "/api/upload",
+            files=[("files", ("no_owner.txt", io.BytesIO(b"content"), "text/plain"))],
+            headers={"x-test-api-token": "1", "x-test-api-token-scopes": "chat"},
+        )
+        assert resp_no_owner.status_code == 403
+
+        # 6. Token with sentinel owner 'api' -> 403
+        resp_sentinel = client.post(
+            "/api/upload",
+            files=[("files", ("sentinel.txt", io.BytesIO(b"content"), "text/plain"))],
+            headers={"x-test-api-token": "1", "x-test-api-token-owner": "api", "x-test-api-token-scopes": "chat"},
+        )
+        assert resp_sentinel.status_code == 403
+
+
+# ===========================================================================
+# 3. POST /api/upload with AUTH_ENABLED=false
+# ===========================================================================
+
+
+def test_upload_post_succeeds_without_login(tmp_path, monkeypatch):
+    """POST /api/upload with AUTH_ENABLED=false succeeds without authentication,
+    persists the file, stores owner=None, and can be retrieved via GET."""
+    from routes import upload_routes
+    from src.upload_handler import UploadHandler
+
+    monkeypatch.setenv("AUTH_ENABLED", "false")
+    upload_dir = tmp_path / "uploads_post"
+    upload_dir.mkdir()
+    monkeypatch.setattr(upload_routes, "router", APIRouter(prefix="/api/upload"))
+    handler = UploadHandler(str(tmp_path), str(upload_dir))
+    router, _cleanup = upload_routes.setup_upload_routes(handler)
+    app = FastAPI()
+    app.state.auth_manager = SimpleNamespace(is_configured=True)
+    app.include_router(router)
+
+    file_bytes = b"Hello, no-login upload test content!"
+    with TestClient(app) as client:
+        response = client.post(
+            "/api/upload",
+            files=[("files", ("test_file.txt", io.BytesIO(file_bytes), "text/plain"))],
+        )
+
+        assert response.status_code == 200, response.text
+        data = response.json()
+        assert "files" in data
+        assert len(data["files"]) == 1
+        item = data["files"][0]
+        assert item["name"] == "test_file.txt"
+        assert item["size"] == len(file_bytes)
+        new_id = item["id"]
+
+        # Check upload index: owner must be None (no authenticated user)
+        index = handler._load_upload_index()
+        record = next((v for v in index.values() if v.get("id") == new_id), None)
+        assert record is not None
+        assert record.get("owner") is None
+
+        # Verify storage isolation: file path is confined inside upload_dir
+        saved_path = record.get("path")
+        assert saved_path and handler.inside_base_dir(saved_path)
+
+        # Verify download of the newly uploaded file succeeds
+        download_resp = client.get(f"/api/upload/{new_id}")
+        assert download_resp.status_code == 200
+        assert download_resp.content == file_bytes
+
+
+def test_upload_post_preserves_validations_and_constraints(tmp_path, monkeypatch):
+    """POST /api/upload with AUTH_ENABLED=false continues enforcing validation:
+    empty files, oversized files, and dangerous file types are rejected."""
+    from routes import upload_routes
+    from src.upload_handler import UploadHandler
+
+    monkeypatch.setenv("AUTH_ENABLED", "false")
+    upload_dir = tmp_path / "uploads_val"
+    upload_dir.mkdir()
+    monkeypatch.setattr(upload_routes, "router", APIRouter(prefix="/api/upload"))
+    handler = UploadHandler(str(tmp_path), str(upload_dir))
+    router, _cleanup = upload_routes.setup_upload_routes(handler)
+    app = FastAPI()
+    app.state.auth_manager = SimpleNamespace(is_configured=True)
+    app.include_router(router)
+
+    with TestClient(app) as client:
+        # 1. Empty file rejection
+        resp_empty = client.post(
+            "/api/upload",
+            files=[("files", ("empty.txt", io.BytesIO(b""), "text/plain"))],
+        )
+        assert resp_empty.status_code == 400
+
+        # 2. Oversized file rejection
+        handler.max_upload_size = 10  # 10 bytes limit
+        resp_oversized = client.post(
+            "/api/upload",
+            files=[("files", ("large.txt", io.BytesIO(b"x" * 50), "text/plain"))],
+        )
+        assert resp_oversized.status_code == 400
+
+        # 3. Dangerous file type rejection (executable)
+        resp_dangerous = client.post(
+            "/api/upload",
+            files=[("files", ("malware.exe", io.BytesIO(b"MZ123"), "application/x-msdownload"))],
+        )
+        assert resp_dangerous.status_code == 400
+
+
+def test_upload_post_sanitizes_filename_and_confines_storage(tmp_path, monkeypatch):
+    """POST /api/upload with AUTH_ENABLED=false sanitizes path traversal attempts
+    in filenames and confines saved files inside the upload directory."""
+    from routes import upload_routes
+    from src.upload_handler import UploadHandler
+
+    monkeypatch.setenv("AUTH_ENABLED", "false")
+    upload_dir = tmp_path / "uploads_trav"
+    upload_dir.mkdir()
+    monkeypatch.setattr(upload_routes, "router", APIRouter(prefix="/api/upload"))
+    handler = UploadHandler(str(tmp_path), str(upload_dir))
+    router, _cleanup = upload_routes.setup_upload_routes(handler)
+    app = FastAPI()
+    app.state.auth_manager = SimpleNamespace(is_configured=True)
+    app.include_router(router)
+
+    with TestClient(app) as client:
+        resp_traversal = client.post(
+            "/api/upload",
+            files=[("files", ("../../traversal.txt", io.BytesIO(b"safe content"), "text/plain"))],
+        )
+        assert resp_traversal.status_code == 200
+        traversal_id = resp_traversal.json()["files"][0]["id"]
+        index = handler._load_upload_index()
+        rec = next((v for v in index.values() if v.get("id") == traversal_id), None)
+        assert rec is not None
+        assert handler.inside_base_dir(rec["path"])
+        assert "/" not in rec["name"] and "\\" not in rec["name"]
+
+
+def test_upload_post_no_login_then_auth_enabled_prevents_unauthorized_download(tmp_path, monkeypatch):
+    """When a file is uploaded in AUTH_ENABLED=false mode (stored with owner=None),
+    and the server subsequently runs with AUTH_ENABLED=true and auth configured,
+    unauthorized downloads are prevented: anonymous callers get 403, non-admin
+    users get 404, and only admins can access."""
+    from routes import upload_routes
+    from src.upload_handler import UploadHandler
+
+    # Step 1: Upload in no-login mode
+    monkeypatch.setenv("AUTH_ENABLED", "false")
+    upload_dir = tmp_path / "uploads_transition"
+    upload_dir.mkdir()
+    monkeypatch.setattr(upload_routes, "router", APIRouter(prefix="/api/upload"))
+    handler = UploadHandler(str(tmp_path), str(upload_dir))
+    router, _cleanup = upload_routes.setup_upload_routes(handler)
+    app = FastAPI()
+    app.state.auth_manager = SimpleNamespace(
+        is_configured=True,
+        is_admin=lambda user: user == "admin",
+    )
+
+    @app.middleware("http")
+    async def set_user(request: Request, call_next):
+        user = request.headers.get("x-test-user")
+        if user:
+            request.state.current_user = user
+        return await call_next(request)
+
+    app.include_router(router)
+
+    file_bytes = b"Sensitive document uploaded in no-login mode"
+    with TestClient(app) as client:
+        upload_resp = client.post(
+            "/api/upload",
+            files=[("files", ("document.txt", io.BytesIO(file_bytes), "text/plain"))],
+        )
+        assert upload_resp.status_code == 200
+        file_id = upload_resp.json()["files"][0]["id"]
+
+        # Step 2: Transition to AUTH_ENABLED=true
+        monkeypatch.setenv("AUTH_ENABLED", "true")
+
+        # Anonymous caller -> 403 Access denied
+        resp_anon = client.get(f"/api/upload/{file_id}")
+        assert resp_anon.status_code == 403
+
+        # Non-admin user "bob" -> 404 File not found (owner isolation)
+        resp_bob = client.get(f"/api/upload/{file_id}", headers={"x-test-user": "bob"})
+        assert resp_bob.status_code == 404
+
+        # Admin user "admin" -> 200 OK
+        resp_admin = client.get(f"/api/upload/{file_id}", headers={"x-test-user": "admin"})
+        assert resp_admin.status_code == 200
+        assert resp_admin.content == file_bytes
diff --git a/tests/test_upload_routes_owner_scope.py b/tests/test_upload_routes_owner_scope.py
index a29b7c795..1ece12a31 100644
--- a/tests/test_upload_routes_owner_scope.py
+++ b/tests/test_upload_routes_owner_scope.py
@@ -318,6 +318,7 @@ def test_put_vision_text_allows_same_owner_to_write_cache(tmp_path, monkeypatch)
 def test_download_file_survives_corrupted_uploads_json(tmp_path, monkeypatch):
     # A truncated/corrupt uploads.json must not 500 the download endpoint —
     # metadata simply becomes unavailable and the file is still served.
+    monkeypatch.setenv("AUTH_ENABLED", "false")
     handler, alice_id, _bob_id, upload_dir = _make_upload_store(tmp_path, monkeypatch)
     download_file = _upload_endpoints(handler, monkeypatch)["download_file"]
     (upload_dir / "uploads.json").write_text('{"alice:h1": {', encoding="utf-8")
@@ -332,6 +333,7 @@ def test_download_file_survives_corrupted_uploads_json(tmp_path, monkeypatch):
 
 def test_put_vision_text_returns_400_on_malformed_json(tmp_path, monkeypatch):
     # A non-JSON request body must yield 400, not an unhandled JSONDecodeError -> 500.
+    monkeypatch.setenv("AUTH_ENABLED", "false")
     handler, alice_id, _bob_id, _upload_dir = _make_upload_store(tmp_path, monkeypatch)
     put_vision_text = _upload_endpoints(handler, monkeypatch)["put_vision_text"]
 

From a0137b47d16ffa4288860903ddbb160346f8c7d9 Mon Sep 17 00:00:00 2001
From: Alexandre Teixeira <111787685+alteixeira20@users.noreply.github.com>
Date: Thu, 15 Oct 2026 11:16:52 +0100
Subject: [PATCH 20/53] docs(maintainers): publish governance handbook draft
 and review playbook

Adapt the agreed maintainer responsibilities and risk-based review policy for the public repository. Add evidence-driven security review, CodeQL triage, release guidance and a discoverable contributing link.
---
 CODE_OF_CONDUCT.md                       |  33 ++++++
 CONTRIBUTING.md                          |   4 +
 docs/maintainers/README.md               |  40 ++++++++
 docs/maintainers/changes-and-review.md   |  62 ++++++++++++
 docs/maintainers/documentation.md        |  31 ++++++
 docs/maintainers/product-and-features.md |  42 ++++++++
 docs/maintainers/review-playbook.md      | 124 +++++++++++++++++++++++
 docs/maintainers/roles-and-access.md     |  40 ++++++++
 docs/maintainers/testing-and-releases.md |  46 +++++++++
 docs/maintainers/triage.md               |  48 +++++++++
 10 files changed, 470 insertions(+)
 create mode 100644 CODE_OF_CONDUCT.md
 create mode 100644 docs/maintainers/README.md
 create mode 100644 docs/maintainers/changes-and-review.md
 create mode 100644 docs/maintainers/documentation.md
 create mode 100644 docs/maintainers/product-and-features.md
 create mode 100644 docs/maintainers/review-playbook.md
 create mode 100644 docs/maintainers/roles-and-access.md
 create mode 100644 docs/maintainers/testing-and-releases.md
 create mode 100644 docs/maintainers/triage.md

diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
new file mode 100644
index 000000000..f79c0be5b
--- /dev/null
+++ b/CODE_OF_CONDUCT.md
@@ -0,0 +1,33 @@
+# Code of Conduct
+
+Odysseus project spaces should remain respectful, useful, and focused on the project. Technical disagreement is welcome; personal hostility is not.
+
+## Expected conduct
+
+- Be professional and constructive. Critique ideas, evidence, and implementations, not people.
+- Treat people fairly regardless of experience, background, identity, or role.
+- Explain disagreement with reproducible evidence when possible, and acknowledge uncertainty.
+- Keep project spaces relevant to Odysseus, software engineering, AI, and project work.
+- Help de-escalate discussions that stop being productive, and respect moderation decisions while they are reviewed.
+
+## Unacceptable conduct
+
+- Harassment, discrimination, threats, intimidation, or personal attacks.
+- Trolling, baiting, sustained disruption, or targeted hostility.
+- Doxxing, publishing private correspondence or personal information without permission.
+- Political campaigning, ideological or culture-war disputes, and repeated highly polarizing arguments unrelated to project work.
+- Retaliation against someone who reports a concern in good faith.
+
+These expectations apply to everyone, including administrators and maintainers. Disagreeing about project decisions or criticizing code in good faith is not a violation.
+
+## Scope
+
+This applies across official Odysseus spaces, including GitHub, Matrix, Plane, maintainer channels, and other project-managed community spaces, and to representatives acting on the project's behalf.
+
+## Reporting and enforcement
+
+Report conduct concerns to a Repository Admin or Organization Owner using an appropriate project communication channel. For sensitive concerns, ask for a private channel rather than posting personal details publicly. Security vulnerabilities follow [SECURITY.md](SECURITY.md), not the public conduct-reporting process.
+
+Maintainers may redirect or pause unproductive conversations. Repository Admins handle serious moderation or access decisions, consulting others when appropriate and avoiding conflicts of interest.
+
+Actions may include a reminder, warning, temporary restriction, removal from project spaces, or removal of elevated access. Responses should be proportionate to the behavior and circumstances, with privacy respected and an opportunity to provide context where practical. Retaliation is prohibited.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 38586845f..2934094d2 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -62,6 +62,10 @@ docker compose logs --tail=120 odysseus
 
 Mention what you ran in the pull request description. If you could not run a check, say so.
 
+## Maintainer governance and review guidance
+
+For repository roles, product decisions, risk-based approvals, issue triage, independent security reviews, CodeQL findings, and release handoffs, see the [Odysseus maintainer handbook](docs/maintainers/README.md). This complements the contributor requirements below and does not change the branch model or current PR template.
+
 ## Pull Requests
 
 Good pull requests usually include:
diff --git a/docs/maintainers/README.md b/docs/maintainers/README.md
new file mode 100644
index 000000000..aae60d4df
--- /dev/null
+++ b/docs/maintainers/README.md
@@ -0,0 +1,40 @@
+# Odysseus maintainer handbook
+
+Odysseus maintainers are trusted to act, not to wait for permission. The default is individual responsibility; additional review is required when the **risk** warrants it.
+
+This handbook records the project's maintainer governance and gives reviewers a reusable process. It complements [CONTRIBUTING.md](../../CONTRIBUTING.md) and [SECURITY.md](../../SECURITY.md); it does not replace the PR template, repository protections, or product decisions.
+
+## At a glance
+
+| Area | Working rule |
+|---|---|
+| Product direction | Pewds is the Product Owner |
+| Ordinary, reversible maintainer PR | Self-merge allowed after appropriate validation and applicable repository checks |
+| External contribution | Maintainer review required |
+| High-risk change | At least one **independent, qualified** maintainer review |
+| Access | Need-to-have, least privilege, separately granted per system |
+| Release | A designated Release Maintainer owns preparation and publish |
+| Inactivity | Access review after 2 months without activity, notice, or response |
+| Documentation | Repository Markdown is canonical |
+
+These are governance rules, not guarantees that a GitHub permission or branch-protection setting permits a particular action. Respect the stronger applicable automated gate.
+
+## Start here
+
+- [Roles and access](roles-and-access.md): responsibility, permissions, and continuity.
+- [Product and feature proposals](product-and-features.md): product approval versus technical ownership.
+- [Changes and review](changes-and-review.md): review thresholds, self-merge, contributor corrections.
+- [Practical review playbook](review-playbook.md): risk, provenance, CI, CodeQL, independent audit, and handoff evidence.
+- [Triage](triage.md): turning incoming reports into actionable work.
+- [Testing and releases](testing-and-releases.md): evidence, platform validation, promotion to main.
+- [Documentation](documentation.md): canonical sources, updates, and traceability.
+
+## Accountability
+
+Maintainers own the changes they take on, including validation, regression prevention, follow-up, and rollback when needed. Roles describe responsibilities, not a hierarchy of technical approval.
+
+Important product-direction decisions go through the Product Owner. Maintainers retain responsibility for feasibility, implementation, maintainability, and security.
+
+AI coding or review agents can help collect evidence, test hypotheses, and prepare changes, but they are not the qualified human reviewer required for high-risk changes. A maintainer must inspect and accept the evidence.
+
+Project spaces follow the [Code of Conduct](../../CODE_OF_CONDUCT.md).
diff --git a/docs/maintainers/changes-and-review.md b/docs/maintainers/changes-and-review.md
new file mode 100644
index 000000000..fdad31d23
--- /dev/null
+++ b/docs/maintainers/changes-and-review.md
@@ -0,0 +1,62 @@
+# Changes and review
+
+Review is **risk-based**. Trusted maintainers should be able to ship ordinary work without creating a queue of ceremonial approvals.
+
+## Required review
+
+| Change | Minimum review rule |
+|---|---|
+| Ordinary, reversible maintainer change | Independent approval optional; self-merge permitted after appropriate validation |
+| External contribution | Maintainer review required |
+| High-risk change | At least one independent, qualified maintainer review required |
+
+Repository branch protection and required checks also apply. Never treat this document as permission to bypass a live protection rule.
+
+## Ordinary maintainer changes
+
+1. Open a PR against `dev`, scoped to one coherent change.
+2. Explain intent, expected behavior, validation, and rollback if relevant.
+3. Run suitable tests and inspect the actual result.
+4. Ensure applicable required checks pass, address feedback, and merge when ready.
+
+Self-merge is allowed for ordinary reversible work. The author remains responsible for follow-up, correction, and rollback.
+
+## External contributions and small corrections
+
+External contributions receive maintainer review.
+
+A maintainer may directly fix a **small, obvious** problem in a contributor PR when the intended behavior is clear and the repair is faster than a separate round trip. Document what changed, preserve contributor attribution and history, avoid force-pushing, and re-run affected checks.
+
+Substantive or ambiguous corrections require discussion with the contributor or a separately scoped correction. A maintainer must not silently turn a contributor's PR into unrelated work. Any corrective commit changes the SHA being reviewed; update validation and audit evidence accordingly.
+
+## High-risk changes
+
+High-risk work requires **at least one independent qualified review**. The author cannot be the only approver. Examples:
+
+- Authentication, authorization, tenancy, sandboxing, agent tool permissions, or secrets.
+- Outbound network and SSRF defenses, sensitive integrations, and deployment access.
+- Destructive operations, deletion, filesystem ownership, and data migrations.
+- Persistence and concurrency invariants with possible data loss.
+- Major architectural contracts, release infrastructure, or changes hard to roll back.
+
+A high-risk review should verify the threat or failure model, exact final commit, reproducer or regression evidence, failure and rollback behavior, and the relevant CI/security findings. Use the [review playbook](review-playbook.md).
+
+## Cross-area changes and CODEOWNERS
+
+Touching multiple areas does **not** automatically require multiple approvals. Consult domain expertise when needed. CODEOWNERS helps identify reviewers and accountable contacts; it is not a blanket approval requirement by itself. See [issue #593](https://github.com/odysseus-dev/odysseus/issues/593) for the ongoing ownership map discussion.
+
+## Validation and UI evidence
+
+Automated tests count as runtime evidence when they truly exercise the changed behavior. Use manual validation when coverage is insufficient.
+
+For any change to visible UI behavior, follow the current [contributor UI checklist](../../CONTRIBUTING.md#style-and-visual-changes) and the repository PR template. Screenshots or clips are expected when they materially demonstrate the rendered result; screenshots alone do not replace behavioral tests.
+
+## Disagreement and escalation
+
+The maintainer doing the work owns ordinary implementation decisions within approved product direction and existing technical contracts. For substantive disagreements:
+
+1. Involve a qualified maintainer with relevant expertise.
+2. Escalate unresolved cross-cutting technical issues to trusted project-wide maintainers.
+3. Refer product-direction disagreements to the Product Owner.
+
+Security findings should be handled via [SECURITY.md](../../SECURITY.md), without disclosing exploit details in public issues. Repository protection rules should support these risk-based policies and should not accidentally force independent approval for every ordinary maintainer PR.
diff --git a/docs/maintainers/documentation.md b/docs/maintainers/documentation.md
new file mode 100644
index 000000000..0057305f0
--- /dev/null
+++ b/docs/maintainers/documentation.md
@@ -0,0 +1,31 @@
+# Documentation
+
+Repository Markdown is the canonical source for project documentation. A public docs site may be generated from it; avoid maintaining an independent wiki copy unless there is a deliberate future decision to do so.
+
+## Where information belongs
+
+| Location | Purpose |
+|---|---|
+| `/design` | Product intent, proposals, and accepted decisions (when those paths are used) |
+| `/specs` | Technical contracts and invariants (when those paths are used) |
+| `/docs` | User, developer, architecture, security, deployment, and maintainer guidance |
+| Root Markdown | Discoverable entry points and policies |
+
+Keep root documents easy to find:
+
+- `README.md`
+- `CONTRIBUTING.md`
+- `SECURITY.md`
+- `CODE_OF_CONDUCT.md`
+
+Not every named directory exists today; do not invent a parallel documentation store just to match this map.
+
+## Updating documentation
+
+When behavior, architecture, a workflow, or its verification requirements change, update the canonical documentation in the same PR when appropriate.
+
+Separate **policy** from **examples**: examples may evolve with tooling; changes to role authority, review requirements, or product ownership require an explicit governance decision. Do not introduce a new mandatory approval rule through a checklist alone.
+
+Documentation PRs should link the relevant issue, record what was reviewed (links, commands, or affected features), and avoid publishing private channels, account names, local paths, secrets, or confidential incident details.
+
+For practical examples of review evidence, see the [review playbook](review-playbook.md). For contributor setup and PR requirements, use [CONTRIBUTING.md](../../CONTRIBUTING.md).
diff --git a/docs/maintainers/product-and-features.md b/docs/maintainers/product-and-features.md
new file mode 100644
index 000000000..71b6cf686
--- /dev/null
+++ b/docs/maintainers/product-and-features.md
@@ -0,0 +1,42 @@
+# Product and feature proposals
+
+Pewds is the Product Owner for Odysseus and has final authority over product direction. Maintainers own technical feasibility, implementation, and safety.
+
+## Which changes require product approval?
+
+**Product Owner approval before implementation:** new features and material changes to product direction or behavior.
+
+**No separate product approval by default:** bug fixes, security fixes, maintenance, tests, CI, documentation, and internal refactors, unless they materially change product behavior or direction.
+
+A security or reliability fix that changes behavior should state the user-visible impact and seek product input when its direction is genuinely ambiguous. Urgent containment need not wait if it preserves existing product intent.
+
+## Product Owner initiated
+
+```text
+Product Owner proposal or implementation
+    -> technical feasibility
+    -> plan and implementation
+    -> risk-based review and validation
+```
+
+A Product Owner proposal is already product-approved; it is not automatically technically approved or exempt from high-risk review.
+
+## Community or maintainer initiated
+
+```text
+Feature proposal
+    -> Product Owner accepts / rejects
+    -> technical feasibility
+    -> plan and implementation
+    -> risk-based review and validation
+```
+
+Record the decision in an issue, proposal, work item, or PR so future maintainers can discover it. Do not rely on a chat-only decision.
+
+## Decision boundaries
+
+The Product Owner decides **what belongs in Odysseus**. Maintainers decide **how approved work is built safely and maintainably**.
+
+A rejected or out-of-scope feature can be maintained independently in a contributor's fork.
+
+If the Product Owner is unavailable, new product-direction decisions wait unless that authority was explicitly delegated. Urgent security and reliability corrections that do not redefine product direction may continue under normal review rules.
diff --git a/docs/maintainers/review-playbook.md b/docs/maintainers/review-playbook.md
new file mode 100644
index 000000000..77c4357e7
--- /dev/null
+++ b/docs/maintainers/review-playbook.md
@@ -0,0 +1,124 @@
+# Practical PR review playbook
+
+Use this as a **repeatable review method**, not as an extra organizational approval ladder. The binding minimums remain in [changes and review](changes-and-review.md): ordinary maintainer changes may be self-merged, external PRs require maintainer review, and high-risk work requires at least one independent qualified maintainer review.
+
+No single checklist replaces engineering judgment. Increase depth with risk.
+
+## 1. Establish provenance and scope
+
+- Confirm repository, source fork, target branch (`dev`), exact **HEAD SHA**, and current base.
+- Review the full effective diff, commit history, issue, prior feedback, and related upstream changes.
+- Confirm the branch is mergeable against the **current** `dev`, not an older local snapshot.
+- Identify the user-facing contract, affected data and users, security boundaries, and rollback plan.
+- Separate pre-existing upstream problems from regressions introduced or made reachable by the PR.
+
+Example read-only commands:
+
+```bash
+REPO="odysseus-dev/odysseus"
+PR=1234
+gh pr view "$PR" --repo "$REPO" --json title,state,isDraft,headRefOid,baseRefName,mergeable
+gh pr diff "$PR" --repo "$REPO"
+gh pr checks "$PR" --repo "$REPO"
+```
+
+A green check on an old commit does not verify the revised branch.
+
+## 2. Review the failure and threat model
+
+For the relevant change, ask what happens with malformed input, missing auth state, wrong owner, concurrent requests, stale caches, partial failure, retries, cancelled jobs, unavailable dependencies, and restart/recovery.
+
+Prioritize boundaries that can lose data or authority: identity, delegated API tokens, filesystem confinement, email deletion, persistence versioning, network/SSRF destinations, secrets, and agent tool execution.
+
+For security claims, demonstrate the source-to-sink path and the *actual* guard. Tests must represent production middleware or transport where a unit mock could conceal a bypass.
+
+## 3. Correct without obscuring contributor work
+
+For small, unambiguous issues, maintainers may add focused corrections directly to a contributor PR under [the contribution review policy](changes-and-review.md#external-contributions-and-small-corrections). Preserve provenance, explain the change, prefer normal commits and fast-forward pushes, and avoid unrelated rewrites.
+
+For substantive or ambiguous work, ask the contributor or prepare a clearly separated patch. Any code change means validating **the new SHA**, not approving based solely on the previous audit.
+
+## 4. Build an evidence record
+
+Useful evidence includes:
+
+- Pre-fix reproduction, expected outcome, and actual outcome.
+- Focused regression tests for the fix and broad suites relevant to cross-cutting effects.
+- Actual runtime checks (browser/UI, backend, Docker, supported OS) where necessary.
+- Exact executed commands, result counts, skipped cases, and environmental limitations.
+- GitHub required checks and conflict-free state on the exact final SHA.
+- Relevant operational consequences (data migration, rollback, compatibility).
+
+Keep audits reproducible. A screenshot alone is not a functional test, and a passing mocked test is not proof that a production integration path is safe.
+
+## 5. Independent review for high-risk changes
+
+A separate **qualified maintainer** must inspect high-risk changes; the implementing author cannot be the sole reviewer. Independent coding agents may be useful for adversarial tests and cross-checks, but **an AI agent is not itself a GitHub approver** and does not replace human accountability.
+
+To avoid confirmation bias, give the independent reviewer the current SHA, changed files, acceptance criteria, known reproduction, and explicit permission to challenge the proposed solution. Preserve unresolved findings and require a new audit when meaningful fixes change the diff.
+
+## CodeQL and security scanning
+
+A successful CodeQL workflow means analysis ran, not that the security dashboard is empty. Likewise, resolving a PR discussion does not necessarily resolve its code-scanning alert.
+
+For each relevant alert:
+
+1. Record the alert number, rule, severity, file/line, state, and source-to-sink trace if applicable.
+2. Compare with the current `dev` baseline; decide whether the PR introduced, exposed, or did not affect it.
+3. Reproduce or reason through the actual production behavior, including validation and authorization.
+4. **Fix** credible vulnerabilities, preferably with a regression test. Do not hide them by broad suppressions.
+5. **Recommend dismissal** only for a demonstrable false positive or a stale/invalid finding, with a precise technical explanation; only authorized maintainers should dismiss alerts.
+6. Document genuine but intentionally accepted risk separately. A true positive is not a false positive merely because it is deliberate.
+7. Rerun or inspect updated analysis on the final commit and confirm no blocking issues remain.
+
+Never publish exploit payloads, secrets, or credentials in public review comments. See [SECURITY.md](../../SECURITY.md).
+
+## 6. Decide and integrate
+
+Before approval or self-merge, verify:
+
+- Current branch and reviewed SHA are still the ones to be merged.
+- All applicable required checks are complete and successful.
+- High-risk independent review is present, where required.
+- No unresolved, credible P0/P1/P2 security or data-integrity defects remain in the change. Resolve or explicitly document P3 observations with a tracked owner and priority.
+- Review discussions, compatibility risks, and operational handoffs have been addressed.
+- The correct target is `dev`; `main` is curated for releases.
+
+This P0-P3 classification is [triage guidance](triage.md#practical-priority-language), not a replacement for branch protection or an excuse to self-approve high-risk work. Maintainers may apply a stricter bar where warranted.
+
+For a final manual merge, GitHub CLI supports an exact-head guard:
+
+```bash
+gh pr merge 1234 --repo odysseus-dev/odysseus --squash \
+  --match-head-commit <reviewed-full-head-sha>
+```
+
+Use `--delete-branch` only when removing the source branch is appropriate and does not disrupt another workstream. Do not force a merge past review or security requirements.
+
+## 7. Post-merge follow-up
+
+Verify the PR actually merged and reference its integration commit. Record remaining operational work, such as schema migrations, backup/restore verification, service restarts, or compatibility documentation. A code change to a container mount does **not** by itself migrate existing runtime data.
+
+Do not silently mark a deferred data migration complete; track its owner, evidence, rollback, and execution separately.
+
+## Reusable reviewer handoff
+
+```text
+PR / target:
+Reviewed source HEAD SHA:
+Current target branch SHA:
+Scope and changed files:
+Impact and risk classification:
+Security / correctness invariants challenged:
+Pre-fix reproducer and post-fix evidence:
+Tests run, skipped, and environment:
+CodeQL / scanning alert dispositions:
+Required GitHub checks (exact SHA):
+Mergeability and remaining conflicts:
+Unresolved P0 / P1 / P2 / P3 findings:
+Rollback / operational follow-ups:
+Independent qualified review required? Completed?
+Verdict: APPROVED / CHANGES REQUIRED / BLOCKED
+```
+
+State what was actually verified. Do not write "all checks green" if only a subset of workflows was inspected.
diff --git a/docs/maintainers/roles-and-access.md b/docs/maintainers/roles-and-access.md
new file mode 100644
index 000000000..a98fd3258
--- /dev/null
+++ b/docs/maintainers/roles-and-access.md
@@ -0,0 +1,40 @@
+# Roles and access
+
+Roles clarify who is accountable. They do not create a management chain or automatically grant privileges.
+
+## Responsibility and typical access
+
+| Responsibility | Typical GitHub access | Purpose |
+|---|---|---|
+| Product Owner | No automatic repository access implied | Product direction |
+| Organization Owner | Organization Owner | Organization administration and continuity |
+| Repository Admin | Admin | Repository settings, permissions, and protection rules |
+| Maintainer | Write by default | Implement, review, merge, and maintain |
+| Triage | Triage | Organize intake, de-duplicate, and prepare work |
+| Contributor / Platform Tester | Public / Read as appropriate | Contribute code or provide validation |
+
+Maintain access may be granted when repository-management duties require it.
+
+## Maintainer focus
+
+- **Core Maintainer:** project-wide judgment, difficult technical decisions, governance support.
+- **Technical Maintainer:** implementation, architecture, validation, technical health.
+- **Project Maintainer:** review, contributor coordination, documentation, releases, organization.
+
+These are responsibility labels. No label automatically changes GitHub permissions or overrides the [review rules](changes-and-review.md).
+
+## Functional responsibilities
+
+Maintainers may coordinate Release, Security, Infrastructure and CI, Community, or Test and Validation. These are duties, not ranks. For each release, designate one Release Maintainer and record the handoff if ownership changes.
+
+## Least privilege and continuity
+
+Grant access because it is necessary for current work, not because of a title. GitHub, Matrix, Plane, infrastructure, SSH, deployment systems, secrets, and external services are separate access surfaces.
+
+For elevated or sensitive access, document a responsible owner and recovery route in an appropriate **private** administrative system. Do not publish tokens, SSH details, personal addresses, or credential locations in this handbook. Remove access promptly when it is no longer needed.
+
+## Inactivity
+
+Tell an admin when you expect to be unavailable; a communicated absence is fine.
+
+If there is no meaningful maintainer or triage activity for **two months**, no prior notice, and no response to reasonable follow-up, elevated access may be reviewed and removed. This is access hygiene, not punishment. Returning members may regain access appropriate to their active responsibilities.
diff --git a/docs/maintainers/testing-and-releases.md b/docs/maintainers/testing-and-releases.md
new file mode 100644
index 000000000..ce7c1b59b
--- /dev/null
+++ b/docs/maintainers/testing-and-releases.md
@@ -0,0 +1,46 @@
+# Testing and releases
+
+Validation must match the actual change, and evidence must state what was **run**, **observed**, and **not tested**.
+
+`dev` is the integration and stabilization branch. `main` is the curated release destination. Changes land in `dev`; a release promotes a verified `dev` revision to `main`.
+
+## Change validation
+
+- Run focused tests that cover the modified behavior and failure cases.
+- Run broader regressions where risk crosses module boundaries.
+- For authentication, data loss, or similar high-risk work, include adversarial and rollback tests.
+- Reproduce the issue on the pre-fix version when safe and practical, then prove the correction.
+- For visual changes, run the application and attach the screenshots or clips required by [CONTRIBUTING.md](../../CONTRIBUTING.md).
+- Record exact commands, environment, result, skipped tests, and blockers. Never claim execution from a command you did not run.
+
+GitHub Actions success means a workflow finished successfully; it does **not** mean CodeQL found no alerts. Use [review playbook](review-playbook.md#codeql-and-security-scanning) to assess findings separately. A review must tie required CI and the final diff to the **same commit SHA**.
+
+## Supported-environment evidence
+
+Platform Testers may validate without maintainer permissions. Useful coverage includes:
+
+- Windows native and WSL.
+- macOS Apple Silicon.
+- macOS Intel while supported.
+- Linux native on the reference distribution.
+- Docker on supported hosts.
+
+Record the environment and configuration for each result. Do not imply that a platform was tested when it was not.
+
+## Release ownership
+
+A designated **Release Maintainer** owns preparation and the publish decision once the release criteria are met. Other maintainers and testers supply the evidence needed for the change set. If the Release Maintainer becomes unavailable, another maintainer explicitly takes over.
+
+## Release checklist
+
+Before promoting `dev` to `main`:
+
+1. Identify and freeze the release candidate SHA; check the actual content that will ship.
+2. Verify required checks and relevant supported-environment validation.
+3. Confirm high-risk and data-migration findings are resolved or addressed through an explicit approved plan.
+4. Document skipped coverage, known issues, compatibility and upgrade implications.
+5. Prepare the version, tag, artifacts, and release notes.
+6. Confirm rollback/recovery, including any manual persistence or data migration steps.
+7. Publish and record what was promoted, the verification evidence, and operational follow-ups.
+
+Publishing does not require ceremonial Core or domain sign-off when the criteria are met. Exceptional or disputed releases follow the normal high-risk escalation path.
diff --git a/docs/maintainers/triage.md b/docs/maintainers/triage.md
new file mode 100644
index 000000000..d2f47f8ab
--- /dev/null
+++ b/docs/maintainers/triage.md
@@ -0,0 +1,48 @@
+# Triage
+
+Triage turns reports into evidence-backed work that a maintainer can pick up without guessing.
+
+## Intake flow
+
+```text
+Report
+  -> reproduce / clarify
+  -> identify duplicates and affected versions
+  -> classify impact, urgency, and risk
+  -> prepare actionable work item
+  -> maintainer takes ownership
+  -> PR, verification, and follow-up
+```
+
+## A useful work item
+
+Record what is known and distinguish it from what remains unverified:
+
+- Original report and reproducible steps; installation method, OS, version/commit, and relevant environment.
+- Expected versus actual behavior, including user-visible impact.
+- Evidence: sanitized logs, screenshots, failing tests, or controlled reproduction.
+- Related issues, PRs, duplicates, or a known prior regression.
+- Scope, acceptance criteria, and non-goals.
+- Priority, ownership, and relevant domain expertise.
+- Remaining unknowns, risks, and safe recovery or workaround when available.
+
+Small and obvious fixes may go straight to a focused PR, consistent with [CONTRIBUTING.md](../../CONTRIBUTING.md) and [changes and review](changes-and-review.md).
+
+## Practical priority language
+
+Use P0-P3 as **triage shorthand**, not as a substitute for verified exploitability or the project's actual GitHub labels:
+
+| Priority | Typical impact | Expected response |
+|---|---|---|
+| P0 | Active exploitation, broad irreversible loss, catastrophic outage | Immediate containment and escalation |
+| P1 | Credible severe security or data-integrity vulnerability | Urgent owner assignment and validated fix |
+| P2 | Significant correctness, security, or operational regression | Prioritize and resolve before approving affected high-risk changes |
+| P3 | Limited impact, maintainability, or low-risk polish | Fix or explicitly track with rationale |
+
+Do not call a concern harmless merely because an automated check is green. Escalate privately when reproduction would disclose a vulnerability.
+
+## Where decisions live
+
+Matrix is for coordination; durable decisions belong in GitHub, Plane, a specification, or the relevant PR. Keep confidential security and access details in appropriate private channels. Do not leave important project decisions only in chat history.
+
+See the [review playbook](review-playbook.md) for converting triage into review evidence and handling contested or uncertain findings.

From eb940f24a3f867220804a644d128ea023ddf25d1 Mon Sep 17 00:00:00 2001
From: pewdiepie-archdaemon <pewdiepie-archdaemon@users.noreply.github.com>
Date: Tue, 13 Oct 2026 13:37:51 +0000
Subject: [PATCH 21/53] feat(photo-editor): NL editor planner, image ops,
 email/gallery server

Server-side photo editor: natural-language editor agent route
(/api/editor/agent), photo_editor tool family + style guide, image-op
provider proxy with progress, email server hardening, gallery/hwfit
routes, and graceful shutdown.

Source: vendor/photocraft (ad1cff44) editor-server files, merged onto
upstream/dev (a8c147b2). Conflict resolution documented in
pr_work/B_conflicts.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 app.py                                        |   83 +-
 docs/EDITOR_AGENT_API.md                      |  201 ++
 routes/editor_agent_routes.py                 | 1811 +++++++++++++++++
 routes/email/email_helpers.py                 |  169 +-
 routes/email/email_routes.py                  |  449 ++--
 routes/gallery/gallery_routes.py              |  821 +++++++-
 routes/hwfit_routes.py                        |   14 +-
 routes/model_routes.py                        |   29 +-
 src/activity.py                               |   61 +
 src/agent_tools/editor_tools.py               |  646 ++++++
 src/editor_agent_model.py                     |  498 +++++
 src/editor_style_guide.py                     | 1105 ++++++++++
 src/fixture_email.py                          |   65 +-
 src/shutdown.py                               |   34 +
 src/tools/image.py                            |   16 +-
 src/upload_handler.py                         |   79 +-
 tests/test_activity.py                        |   36 +
 tests/test_agent_editor_routes.py             | 1492 ++++++++++++++
 tests/test_docs_no_orphan_images.py           |   14 +-
 tests/test_edit_image_tool.py                 |   30 +-
 tests/test_editor_agent_model_resolution.py   |   71 +
 tests/test_editor_planner_routing.py          |  171 ++
 tests/test_editor_writing_action_routing.py   |   11 +
 tests/test_email_imap_timeout.py              |   12 +-
 .../test_email_list_stale_while_revalidate.py |   79 +
 tests/test_email_send_only_no_inbox.py        |    2 +-
 tests/test_email_smtp_security.py             |   18 +-
 tests/test_email_test_connection_oauth.py     |   24 +-
 tests/test_gallery_cloud_inpaint.py           |  155 ++
 tests/test_gallery_edit_progress.py           |  120 ++
 tests/test_gallery_heavy_image_ops.py         |  201 ++
 tests/test_gallery_image_endpoint_fallback.py |  124 ++
 tests/test_gallery_image_model_picker.py      |   27 +
 tests/test_gallery_landing_import_button.py   |   25 +
 tests/test_gallery_seneca_image_ops.py        |  187 ++
 tests/test_hwfit_gemma4_12b.py                |   77 +-
 tests/test_hwfit_gpu_count_nonnumeric.py      |   99 +-
 tests/test_hwfit_macos.py                     |   27 +-
 tests/test_hwfit_quant_formats.py             |   14 +-
 tests/test_image_creation_routing.py          |    6 +-
 tests/test_image_op_offload.py                |   54 +
 tests/test_image_provider_transport.py        |   32 +
 tests/test_imap_leak_fixes.py                 |    2 +-
 tests/test_photo_editor_family.py             |  503 +++++
 tests/test_photo_editor_style_guide.py        |  642 ++++++
 tests/test_shutdown_signal.py                 |   51 +
 46 files changed, 9662 insertions(+), 725 deletions(-)
 create mode 100644 docs/EDITOR_AGENT_API.md
 create mode 100644 routes/editor_agent_routes.py
 create mode 100644 src/activity.py
 create mode 100644 src/agent_tools/editor_tools.py
 create mode 100644 src/editor_agent_model.py
 create mode 100644 src/editor_style_guide.py
 create mode 100644 src/shutdown.py
 create mode 100644 tests/test_activity.py
 create mode 100644 tests/test_agent_editor_routes.py
 create mode 100644 tests/test_editor_agent_model_resolution.py
 create mode 100644 tests/test_editor_planner_routing.py
 create mode 100644 tests/test_email_list_stale_while_revalidate.py
 create mode 100644 tests/test_gallery_edit_progress.py
 create mode 100644 tests/test_gallery_heavy_image_ops.py
 create mode 100644 tests/test_gallery_image_endpoint_fallback.py
 create mode 100644 tests/test_gallery_image_model_picker.py
 create mode 100644 tests/test_gallery_landing_import_button.py
 create mode 100644 tests/test_gallery_seneca_image_ops.py
 create mode 100644 tests/test_image_op_offload.py
 create mode 100644 tests/test_photo_editor_family.py
 create mode 100644 tests/test_photo_editor_style_guide.py
 create mode 100644 tests/test_shutdown_signal.py

diff --git a/app.py b/app.py
index 60441baf1..6c3974c65 100644
--- a/app.py
+++ b/app.py
@@ -178,6 +178,14 @@ app.add_middleware(SecurityHeadersMiddleware)
 import asyncio as _asyncio
 from starlette.middleware.base import BaseHTTPMiddleware as _BaseHTTPMiddleware
 from starlette.responses import JSONResponse as _JSONResponse
+import anyio as _anyio
+from starlette.requests import ClientDisconnect as _ClientDisconnect
+
+# SSE endpoints (e.g. /api/editor/bridge/events) end/abort mid-stream when the
+# browser disconnects; Starlette's BaseHTTPMiddleware surfaces that as
+# anyio.EndOfStream (and sometimes ClientDisconnect). Those are client-side
+# events, not server errors, so we map them to a 499 instead of a 500 traceback.
+_STREAM_CLIENT_EXC = (_anyio.EndOfStream, _ClientDisconnect)
 
 REQUEST_HARD_TIMEOUT = float(os.getenv("REQUEST_HARD_TIMEOUT", "45"))
 _TIMEOUT_EXEMPT_PREFIXES = (
@@ -190,6 +198,7 @@ _TIMEOUT_EXEMPT_PREFIXES = (
     "/api/cookbook/setup",  # remote pacman/apt installs
     "/api/upload",          # large files
     "/api/image",           # diffusion proxies (inpaint/harmonize/upscale/etc.) — own 120s httpx timeout
+    "/api/editor",          # editor agent/bridge: generative steps can take 30-110s (SAM + local diffusion)
     "/api/memory/audit",    # retains own 120s LLM inactivity timeout
 )
 
@@ -225,15 +234,43 @@ class _InteractiveActivityMiddleware(_BaseHTTPMiddleware):
             return await call_next(request)
 
 
+# Heavy image ops that can run 30-150 s; a deploy restart must not cut these off.
+_HEAVY_IMAGE_OP_PREFIXES = (
+    "/api/image/inpaint",
+    "/api/image/replace-background",
+    "/api/image/outpaint",
+    "/api/image/extend",
+    "/api/image/remove-bg",
+    "/api/image/mask",
+    "/api/image/upscale-local",
+    "/api/image/denoise",
+    "/api/image/enhance-face",
+    "/api/gallery/ai-upscale",
+    "/api/gallery/style-transfer",
+    "/api/editor/agent",
+)
+
+
 class _SlowRequestLogMiddleware(_BaseHTTPMiddleware):
     async def dispatch(self, request, call_next):
+        from src import activity
+        path = request.url.path or ""
+        heavy = any(path.startswith(p) for p in _HEAVY_IMAGE_OP_PREFIXES)
+        if heavy:
+            activity.begin_image_op(path)
         start = time.perf_counter()
         status = 500
         try:
             response = await call_next(request)
             status = getattr(response, "status_code", 0) or 0
             return response
+        except _STREAM_CLIENT_EXC:
+            # Client disconnected / SSE stream ended — not a server error.
+            status = 499
+            return _JSONResponse({"detail": "client disconnected"}, status_code=499)
         finally:
+            if heavy:
+                activity.end_image_op(path)
             elapsed = time.perf_counter() - start
             try:
                 threshold = float(os.getenv("ODYSSEUS_SLOW_REQUEST_LOG_SECONDS", "0.75") or "0.75")
@@ -821,6 +858,10 @@ app.include_router(setup_gallery_routes())
 from routes.editor_draft_routes import setup_editor_draft_routes
 app.include_router(setup_editor_draft_routes())
 
+# Natural-language editor planning (planner wired to the configured chat model)
+from routes.editor_agent_routes import setup_editor_agent_routes
+app.include_router(setup_editor_agent_routes())
+
 # Scheduled tasks + event bus
 from src.task_scheduler import TaskScheduler
 task_scheduler = TaskScheduler(session_manager)
@@ -992,12 +1033,21 @@ async def serve_login(request: Request):
 @app.get("/api/version")
 async def get_version():
     from core.constants import APP_BUILD_VERSION, APP_SOURCE_COMMIT, APP_VERSION
+    from src import activity
     return {
         "version": APP_VERSION,
         "build": APP_BUILD_VERSION,
         "source_commit": APP_SOURCE_COMMIT,
+        "busy_image_ops": activity.heavy_image_ops_active(),
     }
 
+
+@app.get("/api/busy")
+async def get_busy():
+    """Report in-flight heavy work so a deploy can wait instead of dropping it."""
+    from src import activity
+    return activity.activity()
+
 @app.get("/api/health")
 async def health_check() -> Dict[str, str]:
     return {"status": "healthy", "timestamp": datetime.now(timezone.utc).isoformat()}
@@ -1436,4 +1486,35 @@ if __name__ == "__main__":
     bind_host = os.getenv("APP_BIND", "127.0.0.1")
     bind_port = int(os.getenv("APP_PORT", "7011"))
 
-    uvicorn.run(app, host=bind_host, port=bind_port, log_level="info")
+    # Give in-flight requests time to finish on SIGTERM instead of being cut
+    # off mid-flight. Diffusion edits run 60-120 s; outpaint/extend can run up
+    # to ~330 s (provider cap 900 s), so default the graceful window to 900 s.
+    # systemd's TimeoutStopSec must exceed this (see the graceful-stop drop-in).
+    #
+    # We hook uvicorn's signal handler so a SIGTERM also flips src.shutdown:
+    # SSE / streaming generators check it and end promptly, so an open browser
+    # stream cannot stall a restart for the whole window. The long window stays
+    # a safety net for genuine in-flight image ops.
+    from src import shutdown as _shutdown
+
+    config = uvicorn.Config(
+        app,
+        host=bind_host,
+        port=bind_port,
+        log_level="info",
+        timeout_graceful_shutdown=int(os.getenv("ODYSSEUS_GRACEFUL_SHUTDOWN_TIMEOUT", "900") or 900),
+    )
+    server = uvicorn.Server(config)
+
+    # uvicorn's capture_signals() wires SIGINT/SIGTERM to self.handle_exit, so
+    # wrapping that method lets us set the shutdown flag before the normal exit
+    # path runs (this uvicorn version has no install_signal_handlers kwarg).
+    _uvicorn_handle_exit = server.handle_exit
+
+    def _handle_shutdown_signal(signum, frame):
+        _shutdown.request_shutdown()
+        _uvicorn_handle_exit(signum, frame)
+
+    server.handle_exit = _handle_shutdown_signal
+
+    server.run()
diff --git a/docs/EDITOR_AGENT_API.md b/docs/EDITOR_AGENT_API.md
new file mode 100644
index 000000000..c873d28d9
--- /dev/null
+++ b/docs/EDITOR_AGENT_API.md
@@ -0,0 +1,201 @@
+# Editor Agent API
+
+How an agent (LLM or script) drives the PhotoCraft editor. There are three layers:
+
+1. **Control API** — `window.geEditorControl`, a stable in-page command surface.
+2. **NL planner** — `window.geEditorAI`, turns a prompt into control-API steps (LLM or basic mode).
+3. **Bridge** — server-mediated SSE channel so a *server-side* agent can drive an **open** editor.
+
+All three are owner-scoped by the app session; nothing is exposed to unauthenticated users.
+
+---
+
+## 1. Control API (`window.geEditorControl`)
+
+Installed when the editor opens. Version `EDITOR_CONTROL_VERSION`.
+
+```js
+await window.geEditorControl.invoke(op, params)   // { ok, op, result } | { ok:false, op, error }
+await window.geEditorControl.run([{op, params}])  // sequential, stops on first failure
+window.geEditorControl.list()                     // [{op, description}]
+```
+
+`invoke` is async. Every op that mutates the document pushes **one** undo entry via
+`_saveState`, so a single op is one undo step.
+
+### Op catalog
+
+| Op | Params | Notes |
+| --- | --- | --- |
+| `document.info` | – | size, layers, mode |
+| `document.importImage` | `{dataUrl,name,raster}` | load a raster image as a new layer |
+| `layers.list` | – | top-most first |
+| `layers.select` | `{id\|index\|name}` | index is top-most-first |
+| `layers.addRaster` | – | new empty pixel layer |
+| `layers.addAdjustment` | `{type,params}` | adjustment layer |
+| `layers.duplicate` / `layers.delete` | – | on the active/selected layer(s) |
+| `layers.setOpacity` | `{id?,opacity 0-1}` | |
+| `layers.setBlend` | `{id?,blendMode\|mode}` | |
+| `layers.group` / `layers.ungroup` | – | |
+| `selection.selectAll` / `deselect` / `invert` | – | |
+| `selection.rectangle` / `selection.ellipse` | `{x,y,w,h}` | document space |
+| `selection.subject` | `{label}` | SAM text grounding (falls back to a centred rect) |
+| `selection.face` | – | SAM "face" (falls back to an upper-centre ellipse) |
+| `selection.sky` | – | SAM "sky" (falls back to a top-band colour range) |
+| `selection.background` | `{fuzziness}` | border colour union |
+| `selection.samText` | `{text}` | SAM text grounding only (throws without SAM) |
+| `selection.colorRange` | `{color,fuzziness}` | |
+| `selection.hasMask` | – | `{active, space}` |
+| `adjustments.apply` | `{type,params}` | adjustment layer; camelCase types accepted |
+| `adjustments.applyMasked` | `{brightness,contrast,saturation,warmth,invert}` | pixel pass, masked if a selection exists else whole layer |
+| `filters.apply` | `{id}` | opens the slider dialog and applies |
+| `filters.applyMasked` | `{id,radius,amount,invert}` | `id`: blur-gaussian, sharpen, unsharp-mask |
+| `transform.start` / `transform.apply` / `transform.cancel` | – | |
+| `text.add` | `{text,x,y,color,size,font,align}` | |
+| `history.undo` / `history.redo` | – | |
+| `history.mark` | – | returns current undo depth (for grouping) |
+| `history.collapse` | `{mark,label}` | collapses entries above `mark` into one |
+| `export.png` | – | `{dataUrl}` of the flattened document |
+| `export.gallery` | – | saves a copy back to the gallery |
+| `screenshot` | – | `{dataUrl,width,height}` of the composited canvas |
+
+Param conventions the planner must respect:
+
+- `adjustments.applyMasked`: `brightness`/`contrast`/`warmth` are **-100..100** (0 neutral);
+  `saturation` is a **multiplier** (1 neutral; values >3 are treated as percentages).
+- `adjustments.apply` `type` aliases are normalised (`blackAndWhite` -> `black-white`).
+- `color-balance` params are `{shadows:{r,g,b}, midtones:{r,g,b}, highlights:{r,g,b}}`;
+  a bare number is coerced to `{r:n,g:n,b:n}`.
+- A masked op with **no** active selection degrades to a whole-layer edit (does not throw).
+
+---
+
+## 2. NL planner (`window.geEditorAI`)
+
+```js
+const res = await window.geEditorAI.execute('blur the background behind the person', { onStep });
+// exec: window.geEditorAI.execute('blur the background behind the person', { onStep });
+// res = { ok, prompt, reply, planner, basicMode, steps, trace, failed }
+```
+
+Flow (`static/js/editor/nl-edit.js`):
+
+1. Read document state + a **before** screenshot.
+2. Ask the **server planner** (`POST /api/editor/plan`) with the prompt, state and
+   screenshot. The client passes its strong guidance via `state.planner_guidance`.
+   If the route is unavailable it falls back to `localPlan` (regex — labelled
+   **"basic mode"** in the UI).
+3. `sanitizeSteps()`: drop no-op/export steps and, if a masked op has no preceding
+   `selection.*`, insert the region implied by the prompt (face/sky/background/subject).
+4. `history.mark`, then run each step, screenshotting after each one.
+5. **Self-check** (server plans only, max 3 rounds): send the after screenshot back in
+   `mode:"check"` with the original intent. If not satisfied, **revert** the previous
+   attempt (undo its history entries) and apply the model's **full corrected** plan.
+6. `history.collapse` — the whole request becomes a single undoable step.
+
+UI: the Quick Edit box routes multi-clause / "and ..." prompts to this executor and
+streams `Step i/n: <op>` into its status line; a `(basic mode)` suffix marks the offline planner.
+
+### Server route
+
+`POST /api/editor/plan` (HARNESS, `routes/editor_agent_routes.py`)
+
+```
+{ prompt, state, mode?: "plan"|"check", screenshot?: "data:image/..." }
+-> { reply, planner, steps: [{op, params}], done? }
+```
+
+Owner-scoped, authenticated. Uses the configured default/utility model with vision.
+If the model call is unavailable it returns a deterministic `planner:"fallback"` plan.
+
+---
+
+## 3. Bridge (server agent drives an open editor)
+
+`static/js/editor/editor-bridge.js` subscribes the open editor to the server queue.
+Enabled automatically when the editor opens (`window.__geEditorBridge`).
+
+- Subscribe: `GET /api/editor/bridge/events?session=<id>` — SSE, `data: {id,op,params}` (keepalive every 15s).
+- The page runs the op via the control API and replies:
+  `POST /api/editor/bridge/result {id,ok,result,error,screenshot,ms}`.
+- Enqueue a command (server side): `POST /api/editor/bridge/command {session, op|steps, wait, timeout}`.
+  With `wait:true` the call blocks and returns the editor's result.
+
+Round-trip example (authenticated; `<session>` = `window.__geEditorBridge.session`):
+
+```bash
+curl -s -X POST http://127.0.0.1:7011/api/editor/bridge/command \
+  -H 'Content-Type: application/json' -b "odysseus_session=$TOKEN" \
+  -d '{"session":"default","op":"layers.addRaster","wait":true,"timeout":8000}'
+# -> {"id":"...","ok":true,"result":{...},"screenshot":"data:image/png;base64,..."}
+```
+
+Session scoping is `owner:session`, so an agent can only drive editors owned by the
+same user. The bridge is a **browser-only** flow: it requires an editor page to be open.
+
+---
+
+## 4. SAM dependency
+
+`selection.subject` / `selection.face` / `selection.sky` / `selection.samText` use the
+server SAM mask tool (`POST /api/image/mask`). When the SAM tools are **not installed**
+the editor raises *"Object mask tools are not installed"* and the control op falls back
+to a **coarse approximation** (centred rect / upper-centre ellipse / top-band colour range).
+On a plain background the approximation is acceptable; on real photos it leaks, producing
+visible rectangular/elliptical artifacts. Install the Cookbook SAM mask dependencies for
+true subject/face/sky segmentation.
+
+`selection.colorRange` and `selection.background` never need SAM (pure colour matching),
+but they are also coarse on busy scenes.
+
+---
+
+## 5. Two ways for an agent to use this — pick one
+
+### Option A — built-in tool (in-process)
+
+Register an editor-control tool inside the app (same process as the model) that calls the
+bridge/control API directly. Uses the app's normal login; nothing new is exposed. This is
+the rejected stdio-MCP design's replacement: a server-side tool that talks to the bridge
+needs either an internal token (auth-bypass) or to run in-process. **Decision pending (user).**
+
+### Option B — browser-only flow (works today)
+
+No new server tool. An external agent drives an open editor purely through the bridge
+endpoints using the logged-in owner's session. Restricted to the editor the user has open.
+This is the flow demonstrated above and requires **no** auth-bypass.
+
+A stdio `photo_editor` MCP server was prototyped and **rejected** because the built-in MCP
+subprocess has no internal token; wiring it would require expanding an auth bypass.
+The two viable options above are left for the user to choose.
+
+---
+
+## 6. Known limitations / honest grading
+
+Live run against real 7011 with the server LLM planner (7 prompts): all 7 executed
+(`planner:"llm"`). Graded by eye:
+
+- PASS: black & white portrait; warm cinematic; sharper + more vivid; text title.
+- FAIL (region-masked, SAM-bound): "dramatic sky" (global over-saturation instead of a
+  dramatic, masked sky), "blur the background" (coarse mask leaks; visible rectangle),
+  "brighten the face" (coarse ellipse/rect artifact).
+
+Whole-image edits are reliable; subject/face/sky region edits need SAM. The self-check
+loop works (revert-and-replan) but the region cases spend all 3 iterations.
+
+## 7. Theming (control kit)
+
+The editor's interactive controls (ranges, number fields, selects, checkboxes) share a
+single themed kit: `static/js/editor/control-kit.js` adds `.ge-ctl-*` classes scoped to
+the editor roots (`#gallery-editor-container`, `.ge-adj-popup`, `.ge-filter-overlay`,
+`.ge-canvas-size-overlay`, `.ge-float-window`, `.ge-transform-popup`), and
+`static/css/13-image-editor.css` (section "Editor control kit") styles them from the app
+design tokens (`static/css/00-tokens.css`) to match the app sliders/selects. It keeps
+range fills in sync and attaches a **scrub-on-label** affordance to numeric fields
+(drag the field's label to change the value; arrow keys work, Shift = x10).
+
+**The PhotoCraft editor is dark-only.** `:root.light` flips the global tokens, but
+`13-image-editor.css` has no `.light` handling and the editor relies on dark surfaces,
+so light mode renders a garbled mix. Unlike the rest of Odysseus, the editor follows
+Photoshop and is not offered in a light theme.
diff --git a/routes/editor_agent_routes.py b/routes/editor_agent_routes.py
new file mode 100644
index 000000000..3fe3b7901
--- /dev/null
+++ b/routes/editor_agent_routes.py
@@ -0,0 +1,1811 @@
+"""Editor agent routes: natural-language planning for the image editor.
+
+Provides:
+  POST /api/editor/plan             -> {reply, planner, steps:[{op,params}], done?}
+  POST /api/editor/bridge/command   -> enqueue validated ops for the open editor
+  GET  /api/editor/bridge/events    -> SSE stream of queued commands (browser subscriber)
+  POST /api/editor/bridge/result    -> browser posts results/screenshots back
+  POST /api/editor/bridge/await     -> wait for a queued command's result
+
+The browser editor (static/js/editor/nl-edit.js) posts {prompt, state, mode, screenshot}
+and consumes {reply, planner, steps} or {done:true}. When mode == "check" and the model
+reports completion, the route returns {"done": true} to stop the client's self-check loop.
+
+The planner is wired to the app's configured chat model (vision-capable when a screenshot
+is supplied) via set_editor_planner(); a deterministic keyword planner is the fallback so
+the editor always gets a usable plan.
+"""
+from __future__ import annotations
+
+import asyncio
+import inspect
+import json
+import logging
+import re
+import uuid
+from typing import Any, Awaitable, Callable, Dict, List, Optional, Tuple
+
+from fastapi import APIRouter, Request
+from fastapi.responses import JSONResponse, StreamingResponse
+
+from src import editor_style_guide as style_guide
+from src import editor_agent_model as editor_agent_model
+from src import shutdown as _shutdown
+
+logger = logging.getLogger(__name__)
+
+# ── Op catalog (kept in sync with static/js/editor/editor-control.js) ──
+OP_CATALOG = [
+    "document.info", "document.importImage",
+    "document.crop", "document.resizeCanvas", "document.savePsd",
+    "layers.list", "layers.select", "layers.addRaster", "layers.placeImage", "layers.addAdjustment",
+    "layers.duplicate", "layers.delete", "layers.setOpacity", "layers.setBlend",
+    "layers.group", "layers.ungroup", "layers.addStyle",
+    "ai.generativeExpand",
+    "selection.selectAll", "selection.deselect", "selection.invert",
+    "selection.rectangle", "selection.ellipse",
+    "selection.subject", "selection.sky", "selection.background", "selection.samText",
+    "selection.colorRange", "selection.maskBounds", "selection.exportMask",
+    "adjustments.apply", "adjustments.applyMasked",
+    "filters.apply", "filters.applyMasked",
+    "transform.start", "transform.apply", "transform.cancel",
+    "text.add",
+    "history.mark", "history.collapse", "history.undo", "history.redo",
+    "export.png", "export.gallery", "screenshot",
+]
+# Retouch/selection ops are defined once in the shared style guide so the
+# server planner and the browser fallback cannot drift; a plan naming one of
+# these would otherwise be filtered out of the catalog.
+for _extra_op in style_guide.NEW_OP_NAMES:
+    if _extra_op not in OP_CATALOG:
+        OP_CATALOG.append(_extra_op)
+del _extra_op
+_OP_SET = frozenset(OP_CATALOG)
+
+# Canonical argument shapes advertised to the model so it stops guessing. The
+# browser client tolerates loose forms as a safety net, but the model should
+# emit exactly these.
+_ADJUSTMENT_TYPES = (
+    "brightness-contrast {brightness,contrast} (multipliers, 1=neutral), "
+    "exposure {exposure,offset,gamma}, white-balance {temperature,tint}, "
+    "hue-saturation {hue,saturation,lightness}, vibrance {vibrance}, black-white, "
+    "shadows-highlights {shadows,highlights}, levels, curves, color-balance, "
+    "photo-filter {color,density,preserve_luminosity}, selective-color, gradient-map, "
+    "invert, posterize, threshold, channel-mixer, color-lookup"
+)
+_FILTER_IDS = (
+    "blur-gaussian, blur-motion, blur-zoom, sharpen, sharpen-edges, unsharp-mask, "
+    "noise-add, noise-despeckle, pixelate-mosaic, pixelate-crystallize, stylize-emboss, "
+    "stylize-find-edges, stylize-solarize, distort-twirl, distort-pinch, distort-spherize, "
+    "distort-ripple, render-clouds, clarity {amount,radius}, vignette {amount,feather}"
+)
+_CANONICAL_GUIDANCE = (
+    "Canonical op shapes (use exactly these, never invent keys or names): "
+    "adjustments.apply / adjustments.applyMasked params = "
+    "{\"type\": <one of: " + _ADJUSTMENT_TYPES + ">, \"params\": {...}}; "
+    "filters.apply / filters.applyMasked params = {\"id\": <one of: " + _FILTER_IDS + ">}. "
+    "Never nest a numeric bag under {\"adjustments\": {...}} with no type, and never invent "
+    "adjustment types or filter ids. \"clarity\" (params amount,radius) and \"vignette\" "
+    "(params amount,feather) are real filters — use them for local-contrast and framing. "
+    "Canvas: document.crop {x,y,width,height}, document.resizeCanvas {width,height,anchor}, "
+    "ai.generativeExpand {width,height,anchor,prompt,mode:'instruction',feather}. Text/styles: "
+    "text.add {text,x,y,color,size}, layers.addStyle {type,params}. Export: document.savePsd. "
+    "ai_edit_image takes a mode: 'instruction' (default; whole image, no mask, prompt names "
+    "what stays unchanged) for background/scene/season/style changes, adding an object to an "
+    "existing photo, and removing diffuse distractions; 'masked' (tight selection first) ONLY "
+    "for explicit regional removal of a clearly identified object. generate_image is ONLY for "
+    "creating a brand-new image."
+)
+# The shared style guide is the single source of truth for intent routing,
+# calibrated strengths and the low-key/temperature/portrait rules. Both the
+# server planner and the browser fallback read it (the client fetches
+# GET /api/editor/style-guide).
+_STYLE_GUIDANCE = style_guide.guidance()
+
+# EDITOR_PLANNER: async (messages: list[dict], owner: Optional[str]) -> str | dict. Set by app.py.
+_EDITOR_PLANNER: Optional[Callable[[List[dict], Optional[str]], Any]] = None
+_MAX_STEPS = 32
+_QUEUE_MAX = 64
+# Generative editor steps (SAM mask + local diffusion) take 30-110s each, so
+# bridge waits and the agent's per-step wait must outlast the provider.
+_BRIDGE_DEFAULT_TIMEOUT = 330.0
+
+# ── Strict JSON ops schema (structured outputs / grammar) ──
+# The planner (the local Qwen3.5-9B at :8097 and every fallback) is constrained
+# to this schema so it can only emit valid editor ops. Allowed ops:
+#   * the deterministic editor ops (OP_CATALOG),
+#   * generate_edit  -> image model (instruction, optional mask) [=ai_edit_image]
+#   * select_object  -> SAM mask by description (seneca /v1/images/mask)
+#                       [=selection.samText]
+#   * ask_user       -> ask 2-3 concrete choices (never a silent tone default).
+# The model-facing aliases are translated to the internal execution ops below,
+# so the browser client and the executor keep their existing op vocabulary.
+_MODEL_PLAN_OPS = tuple(dict.fromkeys(
+    list(OP_CATALOG) + ["generate_edit", "select_object", "ai_edit_image",
+                        "generate_image", "ask_user"]
+))
+_ALLOWED_PLAN_OPS = frozenset(OP_CATALOG) | {"ai_edit_image", "generate_image"}
+_PLAN_OP_ALIASES = {
+    "generate_edit": "ai_edit_image",      # image model: instruction + optional mask
+    "select_object": "selection.samText",  # SAM mask by description
+}
+# Inner op values the ai_edit_image tool accepts (src/agent_tools/editor_tools.py
+# `_AI_OPS`). A model-authored ai_edit_image step frequently omits the inner op or
+# invents one (e.g. "restyle"), which the tool then rejects. Normalise it so
+# instruction/restyle edits become op "generative" and masked region edits become
+# "inpaint".
+_AI_IMAGE_INNER_OPS = frozenset(
+    {"remove-bg", "upscale", "denoise", "enhance-face", "inpaint", "generative"}
+)
+
+
+def _normalize_ai_step(params: Any) -> Dict[str, Any]:
+    """Repair an ai_edit_image step's inner op so it always runs (restyle ->
+    generative, masked -> inpaint)."""
+    params = dict(params) if isinstance(params, dict) else {}
+    mode = str(params.get("mode") or "").strip().lower()
+    inner = str(params.get("op") or "").strip().lower()
+    if inner not in _AI_IMAGE_INNER_OPS:
+        inner = "inpaint" if mode == "masked" else "generative"
+        params["op"] = inner
+    if inner in ("inpaint", "generative") and not mode:
+        params["mode"] = "masked" if inner == "inpaint" else "instruction"
+    return params
+PLAN_SCHEMA: Dict[str, Any] = {
+    "type": "object",
+    "properties": {
+        "reply": {"type": "string"},
+        "steps": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "properties": {
+                    "op": {
+                        "type": "string",
+                        "enum": list(_MODEL_PLAN_OPS),
+                        "description": (
+                            "generate_edit = AI image model edit (params {prompt, "
+                            "mode:'instruction'|'masked'}; do NOT add an inner 'op' — "
+                            "instruction/restyle edits run as the image model's "
+                            "'generative' op, masked region edits as 'inpaint'). "
+                            "select_object = SAM mask by text (params {text}). "
+                            "ask_user = ask with 2-3 choices (params {question, options})."
+                        ),
+                    },
+                    "params": {"type": "object"},
+                },
+                "required": ["op"],
+            },
+        },
+        "ask_user": {
+            "type": "object",
+            "properties": {
+                "question": {"type": "string"},
+                "options": {"type": "array", "items": {"type": "string"}},
+            },
+            "required": ["question", "options"],
+        },
+        "done": {"type": "boolean"},
+    },
+    "required": ["reply", "steps"],
+}
+PLAN_RESPONSE_FORMAT: Dict[str, Any] = {
+    "type": "json_schema",
+    "json_schema": {"name": "editor_plan", "schema": PLAN_SCHEMA},
+}
+
+
+def _normalize_ask_user(payload: Any) -> Optional[Dict[str, Any]]:
+    """Validate an ask_user payload: one question and 2-3 concrete choices."""
+    if not isinstance(payload, dict):
+        return None
+    question = str(payload.get("question") or "").strip()
+    raw = payload.get("options")
+    labels: List[str] = []
+    for opt in (raw or []):
+        if isinstance(opt, str):
+            lbl = opt.strip()
+        elif isinstance(opt, dict):
+            lbl = str(opt.get("label") or "").strip()
+        else:
+            lbl = ""
+        if lbl:
+            labels.append(lbl)
+    labels = labels[:3]
+    if not question or len(labels) < 2:
+        return None
+    # Match the shape the ask_user tool + the editor client expect: option
+    # objects with a label (and an optional description).
+    return {
+        "question": question,
+        "options": [{"label": lbl, "description": ""} for lbl in labels],
+        "multi": False,
+    }
+
+
+def _validate_plan(data: Any) -> Optional[Dict[str, Any]]:
+    """Validate a raw planner plan against the strict ops schema.
+
+    Returns a normalized plan (aliases translated, ops checked against the
+    allowed set, ask_user normalized to 2-3 choices) or None when the plan is
+    invalid or empty. Callers turn None into an ask_user plan — never a silent
+    tone default.
+    """
+    if not isinstance(data, dict):
+        return None
+    reply = str(data.get("reply") or "")
+    ask_user = _normalize_ask_user(data.get("ask_user"))
+    raw_steps = data.get("steps")
+    if raw_steps is None:
+        raw_steps = []
+    if not isinstance(raw_steps, list):
+        return None
+    steps: List[Dict[str, Any]] = []
+    for s in raw_steps[:_MAX_STEPS]:
+        if not isinstance(s, dict):
+            continue  # drop a malformed step rather than rejecting the whole plan
+        op = str(s.get("op") or "")
+        if op == "ask_user":
+            au = _normalize_ask_user(s.get("params"))
+            if au is not None and ask_user is None:
+                ask_user = au
+            continue
+        op = _PLAN_OP_ALIASES.get(op, op)
+        if op not in _ALLOWED_PLAN_OPS:
+            continue  # drop a single unknown/hallucinated op; keep the valid steps
+        params = s.get("params") if isinstance(s.get("params"), dict) else {}
+        if op == "ai_edit_image":
+            params = _normalize_ai_step(params)
+        steps.append({"op": op, "params": params})
+    # Guardrails apply to model plans too (no stacked lifts, no brighten after
+    # retouch.skin, no global adjustment after a masked recolour).
+    steps = style_guide.enforce_guards(steps)
+    done = bool(data.get("done"))
+    if not steps and not done and ask_user is None:
+        return None
+    out: Dict[str, Any] = {"reply": reply, "planner": "llm", "steps": steps}
+    if ask_user is not None:
+        out["ask_user"] = ask_user
+    if done:
+        out["done"] = True
+    return out
+
+# Generative edits (remove/add/replace content) require an image provider. When
+# none is available the agent must stop and say so plainly rather than apply a
+# deterministic approximation that silently does the wrong thing.
+try:
+    from src.ai_interaction import IMAGE_PROVIDER_REQUIRED_MESSAGE as _PROVIDER_REQUIRED_MESSAGE
+except Exception:  # pragma: no cover - defensive
+    _PROVIDER_REQUIRED_MESSAGE = (
+        "Removing/adding objects needs an image generation provider; enable one in "
+        "Settings > Models."
+    )
+
+_AI_CONTENT_OPS = frozenset({"ai_edit_image", "generate_image"})
+
+# Model ids that are editing/inpainting models rather than text-to-image ones.
+_EDIT_MODEL_RE = re.compile(r"edit|inpaint|fill|kontext|controlnet|removal|qwen-image-edit", re.I)
+
+# Content nouns that signal a generative object edit rather than a tone/filter
+# tweak. Kept narrow so "make it black and white" / "add a vignette" stay
+# deterministic.
+_GEN_OBJECTS = (
+    r"(?:persons?|people|men|man|women|woman|guys?|girls?|boys?|someone|somebody|"
+    r"objects?|car|cars|sign|signs|logos?|watermarks?|trees?|buildings?|"
+    r"reflections?|animals?|dogs?|cats?|birds?|hands?|fingers?|moons?|suns?|clouds?|"
+    r"stars?|fire|smoke|snow|rain|flowers?|mountains?|planets?|balloons?|rockets?|hats?|"
+    r"glasses|sunglasses|shades|beard|beards|stickers?|frames?|borders?|"
+    r"rainbows?|wildflowers?|sunflowers?|tulips?|daisies?|leaves|pumpkins?|lanterns?|"
+    r"butterflies?|bees?|boats?|sailboats?|kites?|umbrellas?)"
+)
+_REMOVE_RE = re.compile(
+    r"\b(?:remove|delete|erase|eliminate|get\s+rid\s+of|take\s+out|photoshop\s+out|paint\s+out)\b"
+    r"[^.!?\n]{0,60}?\b" + _GEN_OBJECTS + r"\b",
+    re.I,
+)
+_ADD_RE = re.compile(
+    r"\b(?:add|insert|put|place|draw|paint|create|generate)\b"
+    r"[^.!?\n]{0,40}?\b" + _GEN_OBJECTS + r"\b",
+    re.I,
+)
+_REPLACE_RE = re.compile(
+    r"\b(?:replace|swap|substitute)\b|\b(?:change|turn)\b[^.!?\n]{0,40}?\b(?:to|into)\b",
+    re.I,
+)
+# Removing diffuse clutter ("remove the distractions") is generative too, but
+# the specific-noun _REMOVE_RE above does not catch it.
+_REMOVE_CLEANUP_RE = re.compile(
+    r"\b(?:remove|delete|erase|eliminate|get\s+rid\s+of|take\s+out|clean\s+up|declutter|clear)\b"
+    r"[^.!?\n]{0,40}?\b(?:distractions?|clutter|junk|mess|noise|"
+    r"unwanted\s+(?:objects?|items?|things?)|stuff|things|blemishes?|spots?)\b",
+    re.I,
+)
+
+# Changing the whole background/scene (or placing the subject somewhere new)
+# is a generative replacement, not the local remove-bg op. "make the
+# background nicer/better" is included; plain "blur the background" is not.
+_BG_RE = re.compile(
+    r"\b(?:replace|change|swap|put|place|set|make|improve|enhance|beautify|upgrade)\b"
+    r"[^.!?\n]{0,40}?\b(?:background|backdrop|scene)\b"
+    r"|\b(?:put|place)\b[^.!?\n]{0,30}?\b(?:on|in|at)\s+(?:a|an|the)\s+"
+    r"(?:beach|street|mountains?|forest|city|park|ocean|sea|desert|room|stage|field|snow|"
+    r"night|moon|mars|space|island|jungle)\b",
+    re.I,
+)
+# Season/weather changes and an explicit "generative fill" change scene
+# content (not just tone), so they must be a generative edit, never a
+# colour adjustment/filter step.
+_SEASON_WEATHER_RE = re.compile(
+    r"\b(?:snow(?:y|ing|fall)?|winter|autumn(?:al)?|fall\s+(?:leaves|foliage)|spring|"
+    r"rain(?:y|ing)?|fog(?:gy)?|mist(?:y)?|storm(?:y)?|overcast)\b",
+    re.I,
+)
+_GENERATIVE_FILL_RE = re.compile(r"\bgenerative(?:\s+fill)?\b", re.I)
+# Whole-image artistic RESTYLE requests (turn the photo into a painting, anime,
+# pixel art, ...). These are a model instruction edit over the whole frame, not a
+# local adjustment. The client has a short fast-path regex; the server must
+# generalise so unknown restyle phrasings still reach the model.
+_RESTYLE_RE = re.compile(
+    r"\b(?:re[\s-]?style|painting|painterly|water[\s-]?colou?r|oil\s+paint(?:ing)?|"
+    r"acrylic|gouache|pastel|sketch|pencil|charcoal|ink\s+drawing|line\s+art|comic|"
+    r"cartoon|anime|manga|illustration|3d\s+render|cgi|claymation|clay|pixel\s+art|"
+    r"voxel|low[\s-]?poly|mosaic|stained\s+glass|pop\s+art|art\s+nouveau|ukiyo[\s-]?e|"
+    r"surreal|fantasy\s+art|steampunk|cyberpunk|vaporwave|synthwave|graffiti|woodcut|"
+    r"linocut|etching|lithograph|impressionist|cubist|abstract|doodle|vector\s+art|"
+    r"neon\s+sign|psychedelic|gothic|comic[\s-]?book|storybook)\b",
+    re.I,
+)
+
+# Text/title/PSD/format requests are deterministic edits, never generative.
+_TEXT_RE = re.compile(
+    r"\b(?:title|caption|subtitle|label|heading|watermark|text|word(?:ing)?)\b", re.I,
+)
+_TEXT_ADD_RE = re.compile(r"\b(?:add|insert|put|place|write|overlay|create|set)\b", re.I)
+_STYLE_RE = re.compile(
+    r"\b(drop[\s-]?shadow|outer[\s-]?glow|glow|stroke|outline|emboss|bevel)\b", re.I,
+)
+_PSD_RE = re.compile(r"\b(?:psd|photoshop file|layered file)\b", re.I)
+
+# Aspect -> exact output size. Instagram/format intents crop to the aspect and
+# then resize to this size (then optionally add a title).
+_ASPECT_TARGETS = (
+    (re.compile(r"\b(?:1080\s*[x×]\s*1350|4\s*:\s*5|four[\s-]?fifths?|instagram)\b", re.I), (1080, 1350)),
+    (re.compile(r"\b(?:1080\s*[x×]\s*1080|1\s*:\s*1|square)\b", re.I), (1080, 1080)),
+    (re.compile(r"\b(?:1080\s*[x×]\s*1920|9\s*:\s*16|story|reel|tiktok|vertical)\b", re.I), (1080, 1920)),
+    (re.compile(r"\b(?:1920\s*[x×]\s*1080|16\s*:\s*9|widescreen|landscape video)\b", re.I), (1920, 1080)),
+)
+_DIM_RE = re.compile(r"\b(\d{3,5})\s*[x×]\s*(\d{3,5})\b")
+
+
+def _is_text_request(text: str) -> bool:
+    return bool(_TEXT_RE.search(text) and _TEXT_ADD_RE.search(text))
+
+
+def _format_target(text: str) -> Optional[Tuple[int, int]]:
+    for pattern, dims in _ASPECT_TARGETS:
+        if pattern.search(text):
+            return dims
+    m = _DIM_RE.search(text)
+    if m:
+        try:
+            return (int(m.group(1)), int(m.group(2)))
+        except Exception:
+            return None
+    return None
+
+
+def _extend_requested(text: str) -> bool:
+    if re.search(r"\b(?:extend|expand|wider|taller|letterbox)\b", text, re.I):
+        return True
+    return bool(re.search(
+        r"\badd\b[^.!?\n]{0,25}?\b(?:canvas|border|space|margin)\b", text, re.I,
+    ))
+
+
+def _generative_kind(prompt: str) -> Optional[str]:
+    """Classify a prompt as a generative content edit: 'remove'/'add'/'replace'.
+
+    Returns None for tone/colour/filter/text/selection edits that deterministic
+    editor ops handle correctly. 'remove the background' is deliberately not
+    matched (that is the local remove-bg op).
+    """
+    text = str(prompt or "")
+    if not text.strip():
+        return None
+    # Text/title, PSD and format requests are deterministic — never generative.
+    if _is_text_request(text) or _PSD_RE.search(text) or _format_target(text):
+        return None
+    # An explicit brand-new image ("create/generate/make a new image/picture/logo
+    # ...") is a text-to-image generation, never an edit of the current photo.
+    if _is_new_image_request(text):
+        return "add"
+    # Replacing the background/scene (or putting the subject somewhere new) is
+    # a generative replacement even though it is phrased like a background op.
+    if _BG_RE.search(text):
+        return "replace"
+    if re.search(
+        r"\b(?:remove|delete|erase|eliminate|get\s+rid\s+of)\s+(?:the\s+)?background\b",
+        text,
+        re.I,
+    ):
+        return None
+    # Season/weather changes and explicit "generative fill" change content, not
+    # tone. Only treat them as generative when the user is not asking to REMOVE
+    # that element ("remove the rain" stays a removal).
+    if _GENERATIVE_FILL_RE.search(text) or _SEASON_WEATHER_RE.search(text):
+        if not re.search(
+            r"\b(?:remove|delete|erase|eliminate|get\s+rid\s+of|take\s+out)\b", text, re.I
+        ):
+            return "replace"
+    if _RESTYLE_RE.search(text) and not _is_new_image_request(text):
+        # A whole-image artistic restyle is a model instruction edit (keep the
+        # subject/composition), never a local tone/colour adjustment.
+        return "restyle"
+    if _REPLACE_RE.search(text):
+        return "replace"
+    if _ADD_RE.search(text):
+        return "add"
+    if _REMOVE_RE.search(text) or _REMOVE_CLEANUP_RE.search(text):
+        return "remove"
+    return None
+
+
+_NEW_IMAGE_RE = re.compile(
+    r"\b(?:create|generate|make|produce|draw|design)\b[^.!?\n]{0,30}?\b"
+    r"(?:new\s+)?(?:image|picture|photo|illustration|artwork|graphic|logo|icon|wallpaper|poster)\b",
+    re.I,
+)
+_EDIT_CONTEXT_RE = re.compile(
+    r"\b(?:this|that|these|it|the\s+(?:photo|image|picture)|attached|from\s+this|"
+    r"of\s+(?:this|the\s+photo)|edit|in\s+(?:this|the)\s+photo)\b",
+    re.I,
+)
+_KEEP_CLAUSE_RE = re.compile(r"\bkeep\b|\bunchanged\b|\bpreserve\b|\bsame\b|\bidentical\b", re.I)
+
+
+def _is_new_image_request(text: str) -> bool:
+    """True only for a from-scratch image generation (not an edit of an existing photo)."""
+    if not _NEW_IMAGE_RE.search(text):
+        return False
+    return not _EDIT_CONTEXT_RE.search(text)
+
+
+def _instruction_prompt(text: str) -> str:
+    """Append a keep-unchanged clause so instruction edits preserve the subject."""
+    t = str(text or "").strip()
+    if not t:
+        return t
+    if _KEEP_CLAUSE_RE.search(t):
+        return t
+    return (
+        t.rstrip(".")
+        + ". Keep the main subject and everything else in the image exactly the same."
+    )
+
+
+def _restyle_prompt(text: str) -> str:
+    """Whole-image artistic restyle instruction (subject/composition preserved)."""
+    t = str(text or "").strip()
+    if t:
+        base = (
+            "Restyle the entire image as requested, applying the artistic style "
+            "across the whole frame: " + t
+        )
+    else:
+        base = "Restyle the entire image in a new artistic style."
+    return _instruction_prompt(base)
+
+
+def _generative_mode(kind: str, prompt: str) -> str:
+    """'masked' only for an explicit regional removal of a clearly identified object.
+
+    Everything else generative (background/season/style replacement, adding an
+    object to the scene, removing diffuse distractions) uses 'instruction'.
+    """
+    if kind == "remove":
+        text = str(prompt or "")
+        if _REMOVE_RE.search(text) and not _REMOVE_CLEANUP_RE.search(text):
+            return "masked"
+    return "instruction"
+
+
+def _removal_prompt(text: str) -> str:
+    """A more explicit diffuse-removal instruction that names common clutter."""
+    t = str(text or "").strip() or "Remove the distracting clutter from the photo"
+    return (
+        t.rstrip(". ")
+        + ". Remove any distracting clutter such as roads, guardrails, utility poles, "
+        "signs, wires and debris, and fill the cleared area with the surrounding "
+        "landscape so it looks natural."
+    )
+
+
+# Rich, scene-specific descriptions so a background replacement produces a
+# convincing scene (Qwen-Image-Edit is an instruction model and a bare "a beach"
+# tends to yield a flat blue backdrop). Keyed by keywords in the request.
+_SCENE_HINTS = (
+    (r"beach|shore|seaside|coast|tropical",
+     "a sunny tropical beach",
+     "golden sand, turquoise sea with gentle waves, a clear blue sky with soft "
+     "clouds, and natural daylight"),
+    (r"mountain|alps|peak|valley",
+     "a scenic mountain landscape",
+     "distant peaks, natural daylight and soft haze"),
+    (r"forest|woods|jungle",
+     "a lush green forest",
+     "dappled natural daylight and depth"),
+    (r"city|street|urban|downtown",
+     "a realistic city street",
+     "recognisable city buildings and depth of field with natural perspective"),
+    (r"field|meadow|grass",
+     "an open grassy field",
+     "natural daylight and a distant horizon"),
+    (r"snow|winter",
+     "a snow-covered landscape",
+     "cold, soft daylight and a pale sky"),
+    (r"desert|dunes",
+     "a warm desert",
+     "sand dunes and a clear sky"),
+    (r"studio|plain|neutral|solid",
+     "a clean neutral studio backdrop",
+     "soft, even lighting"),
+)
+_SCENE_DEFAULT = (
+    "a realistic natural background",
+    "matching the subject's lighting, perspective and shadows",
+)
+# Season/weather scene descriptions ("make it snowy/autumn").
+_SEASON_HINTS = (
+    (r"snow|winter|snowy", "a snowy winter scene",
+     "fresh snow covering the ground and surfaces, soft cold daylight, a pale overcast sky"),
+    (r"autumn|autumnal|fall", "an autumn scene",
+     "vivid orange and golden foliage, warm low sunlight and fallen leaves"),
+    (r"spring", "a bright spring scene",
+     "fresh green foliage and blossoms under bright natural daylight"),
+    (r"rain|storm|overcast", "a rainy overcast scene",
+     "wet reflective surfaces, raindrops and a dramatic overcast sky"),
+    (r"fog|mist", "a foggy scene",
+     "soft drifting mist and diffuse light"),
+    (r"sky|clouds", "a new sky",
+     "realistic clouds and natural lighting matching the scene"),
+)
+
+
+def _scene_prompt(text: str) -> str:
+    """Deterministic, templated instruction for a background/scene change.
+
+    Qwen-Image-Edit is an instruction model and a bare scene noun tends to yield
+    a flat backdrop, so the scene is expanded into concrete detail. The result is
+    passed to the provider unmodified.
+    """
+    t = str(text or "").strip()
+    if not t:
+        return t
+    if _BG_RE.search(t):
+        scene, details = _SCENE_DEFAULT
+        for pattern, scene_name, description in _SCENE_HINTS:
+            if re.search(pattern, t, re.I):
+                scene, details = scene_name, description
+                break
+        return (
+            f"Replace the entire background behind the person with {scene}: {details}. "
+            "Keep the person exactly the same."
+        )
+    if _SEASON_WEATHER_RE.search(t) or _GENERATIVE_FILL_RE.search(t):
+        scene, details = _SCENE_DEFAULT
+        for pattern, scene_name, description in _SEASON_HINTS:
+            if re.search(pattern, t, re.I):
+                scene, details = scene_name, description
+                break
+        return (
+            f"Change the scene to {scene}: {details}. "
+            "Keep the main subject and everything else in the image exactly the same."
+        )
+    return t
+
+
+def _generative_step(kind: str, prompt: str) -> Dict[str, Any]:
+    """The AI step a generative intent must use instead of deterministic ops."""
+    instruction = str(prompt or "").strip()
+    if kind == "restyle":
+        return {
+            "op": "ai_edit_image",
+            "params": {"op": "generative", "mode": "instruction",
+                       "prompt": _restyle_prompt(instruction), "steps": 8},
+        }
+    if kind == "add":
+        # A brand-new image is the only case for generate_image; adding an object
+        # to an existing photo is an instruction edit of the whole image.
+        if _is_new_image_request(prompt):
+            return {"op": "generate_image", "params": {"prompt": instruction}}
+        return {
+            "op": "ai_edit_image",
+            "params": {
+                "op": "generative",
+                "mode": "instruction",
+                "prompt": _instruction_prompt(instruction),
+                "steps": 8,
+            },
+        }
+    mode = _generative_mode(kind, prompt)
+    op = "inpaint" if kind == "remove" else "generative"
+    if mode == "instruction":
+        if kind == "remove":
+            base = _removal_prompt(instruction)
+        else:
+            base = _scene_prompt(instruction)
+        params: Dict[str, Any] = {"op": op, "mode": "instruction", "prompt": _instruction_prompt(base)}
+    else:
+        params = {"op": op, "mode": "masked", "prompt": instruction}
+    if kind in ("remove", "replace"):
+        # Removal and background-replacement edits need more sampler steps than
+        # the server's default of 4.
+        params["steps"] = 8
+    return {"op": "ai_edit_image", "params": params}
+
+
+_SKY_ADD_RE = re.compile(
+    r"\b(?:sky|moons?|suns?|sunset|sunrise|clouds?|stars?|night|aurora|stars?)\b",
+    re.I,
+)
+_REMOVE_NOUN_RE = re.compile(
+    r"\b(?:remove|delete|erase|eliminate|get\s+rid\s+of|take\s+out|clean\s+up|declutter|clear)\b"
+    r"[^.!?\n]{0,60}?\b("
+    + _GEN_OBJECTS
+    + r"|distractions?|clutter|junk|mess|noise|stuff|things)\b",
+    re.I,
+)
+
+
+def _selection_step_for(kind: str, prompt: str) -> Optional[Dict[str, Any]]:
+    """A deterministic selection step that yields the mask a MASKED ai_edit_image needs.
+
+    Instruction-mode edits operate on the whole image and need no mask, so this
+    returns None for them. Masked mode is only used for an explicit regional
+    object removal; the selection targets that object so ``selection.exportMask``
+    has a tight region to export.
+    """
+    text = str(prompt or "")
+    if kind == "remove" and _generative_mode(kind, text) == "masked":
+        m = _REMOVE_NOUN_RE.search(text)
+        label = (m.group(1).lower() if m else "person")
+        if label.endswith("s"):
+            label = label[:-1]
+        if label in ("people",):
+            label = "person"
+        return {"op": "selection.subject", "params": {"label": label}}
+    return None
+
+
+def _generative_steps(kind: str, prompt: str) -> List[Dict[str, Any]]:
+    """The selection step (when needed) followed by the AI content step."""
+    steps: List[Dict[str, Any]] = []
+    selection = _selection_step_for(kind, prompt)
+    if selection:
+        steps.append(selection)
+    steps.append(_generative_step(kind, prompt))
+    return steps
+
+
+def _plan_uses_ai_content(steps: Any) -> bool:
+    return any(isinstance(s, dict) and s.get("op") in _AI_CONTENT_OPS for s in (steps or []))
+
+
+def _ensure_generative(prompt: str, steps: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+    """Force a generative intent onto an AI content op, never a substitute.
+
+    If the prompt is a generative content edit (remove/add/replace) but the
+    plan has no ai_edit_image/generate_image step, replace the plan with the
+    correct AI step so the agent cannot silently do an unrelated deterministic
+    edit. Non-generative prompts are returned unchanged.
+    """
+    kind = _generative_kind(prompt)
+    if not kind:
+        return steps
+    # Background/scene replacement is deterministic: always use the templated
+    # scene prompt so a model rewrite cannot drop the scene details (a model
+    # ai_edit_image step would otherwise pass with its own vague prompt).
+    if kind == "replace" and (
+        _BG_RE.search(str(prompt or ""))
+        or _SEASON_WEATHER_RE.search(str(prompt or ""))
+        or _GENERATIVE_FILL_RE.search(str(prompt or ""))
+    ):
+        return _generative_steps(kind, prompt)
+    # For a restyle (and any other generative intent) the planner is expected to
+    # choose generate_edit itself; the _RESTYLE_RE keyword list is only a fast
+    # path used when the model did not already pick an AI content op.
+    if not _plan_uses_ai_content(steps):
+        return _generative_steps(kind, prompt)
+    return steps
+
+
+def _image_provider_available(owner: Optional[str]) -> bool:
+    try:
+        from src.ai_interaction import image_editing_provider_available
+
+        return bool(image_editing_provider_available(owner))
+    except Exception:
+        return True  # unknown: let the tool attempt and report its own error
+
+
+def _state_dims(state: Any) -> Optional[Tuple[int, int]]:
+    """Current canvas size from the client-sent state (flat or nested)."""
+    if not isinstance(state, dict):
+        return None
+    candidates = [state]
+    for key in ("document", "document_info", "info"):
+        if isinstance(state.get(key), dict):
+            candidates.append(state[key])
+    for src in candidates:
+        w = src.get("width") or src.get("imgWidth")
+        h = src.get("height") or src.get("imgHeight")
+        try:
+            if w and h:
+                return (int(round(float(w))), int(round(float(h))))
+        except Exception:
+            continue
+    return None
+
+
+def _title_text(prompt: str) -> Optional[str]:
+    quoted = re.search(r"[\"'\u201c\u201d\u2018\u2019]([^\"'\u201c\u201d\u2018\u2019]{1,40})[\"'\u201c\u201d\u2018\u2019]", prompt)
+    if quoted and quoted.group(1).strip():
+        return quoted.group(1).strip()
+    caps = re.search(r"\b([A-Z][A-Z0-9]{1,20})\b", prompt)
+    if caps and caps.group(1).lower() not in {"add", "title", "text", "psd"}:
+        return caps.group(1)
+    return None
+
+
+def _crop_rect_for_aspect(cur: Tuple[int, int], target: Tuple[int, int]) -> Optional[Dict[str, int]]:
+    cw, ch = cur
+    tw, th = target
+    if cw <= 0 or ch <= 0 or tw <= 0 or th <= 0:
+        return None
+    target_ratio = tw / th
+    cur_ratio = cw / ch
+    if abs(cur_ratio - target_ratio) < 0.02:
+        return None  # already the right aspect
+    if cur_ratio > target_ratio:
+        # too wide -> trim the sides
+        new_w = int(round(ch * target_ratio))
+        new_w = min(cw, max(1, new_w))
+        return {"x": (cw - new_w) // 2, "y": 0, "width": new_w, "height": ch}
+    # too tall -> trim top/bottom
+    new_h = int(round(cw / target_ratio))
+    new_h = min(ch, max(1, new_h))
+    return {"x": 0, "y": (ch - new_h) // 2, "width": cw, "height": new_h}
+
+
+def _extend_dims(cur: Tuple[int, int], target: Tuple[int, int]) -> Tuple[int, int]:
+    """Target canvas that grows (never crops) toward the target aspect."""
+    cw, ch = cur
+    target_ratio = target[0] / target[1]
+    cur_ratio = cw / ch
+    if abs(cur_ratio - target_ratio) < 0.02:
+        return (cw, ch)
+    if cur_ratio < target_ratio:
+        return (int(round(ch * target_ratio)), ch)  # add width
+    return (cw, int(round(cw / target_ratio)))  # add height
+
+
+def _plan_text_steps(prompt: str) -> List[Dict[str, Any]]:
+    title = _title_text(prompt) or "Title"
+    steps: List[Dict[str, Any]] = [{
+        "op": "text.add",
+        "params": {"text": title, "x": 40, "y": 40, "color": "#ffffff", "size": 64},
+    }]
+    if _STYLE_RE.search(prompt):
+        steps.append({"op": "layers.addStyle", "params": {"type": "drop-shadow", "params": {}}})
+    return steps
+
+
+def _plan_format_steps(prompt: str, state: Any, provider_available: bool) -> Optional[List[Dict[str, Any]]]:
+    target = _format_target(prompt)
+    if not target:
+        return None
+    cur = _state_dims(state)
+    if not cur:
+        # No canvas size known: ask the client to crop to the aspect itself.
+        return None
+    steps: List[Dict[str, Any]] = []
+    if _extend_requested(prompt):
+        new_w, new_h = _extend_dims(cur, target)
+        if (new_w, new_h) == cur:
+            return None
+        if provider_available:
+            steps.append({"op": "ai.generativeExpand", "params": {
+                "width": new_w, "height": new_h,
+                "anchor": "center", "mode": "instruction", "feather": True,
+                "steps": 8,
+                "prompt": "extend the surrounding scene and sky naturally into the new border, "
+                          "keep the original photo unchanged"}})
+        else:
+            steps.append({"op": "document.resizeCanvas", "params": {
+                "width": new_w, "height": new_h, "anchor": "center"}})
+    else:
+        rect = _crop_rect_for_aspect(cur, target)
+        if rect:
+            steps.append({"op": "document.crop", "params": rect})
+        # Only resize when an exact output size was requested.
+        if abs(target[0] / target[1] - cur[0] / cur[1]) >= 0.02 or target in ((1080, 1350), (1080, 1080), (1080, 1920), (1920, 1080)):
+            steps.append({"op": "document.resizeCanvas", "params": {
+                "width": target[0], "height": target[1], "anchor": "center"}})
+    if not steps:
+        return None
+    # Optional caption/title that came with the format request.
+    if _is_text_request(prompt):
+        steps.extend(_plan_text_steps(prompt))
+    return steps
+
+
+def _plan_psd_steps(prompt: str) -> Optional[List[Dict[str, Any]]]:
+    if _PSD_RE.search(prompt):
+        return [{"op": "document.savePsd", "params": {}}]
+    return None
+
+
+def _plan_special(
+    prompt: str, state: Any, provider_available: bool,
+) -> Optional[Tuple[List[Dict[str, Any]], str, str]]:
+    """Deterministic overrides for intents the model reliably botches.
+
+    Canvas format/crop/extend, text + layer styles and PSD export must not be
+    left to the model.     Returns (steps, reply, note) or None. These never need an
+    image provider except generative border fill, used only when one exists.
+    """
+    # Targeted recolour is fully deterministic (object mask + masked hue shift)
+    # and must never be left to the model, which sometimes substitutes a
+    # generative placeImage. Highest priority so it can never vary.
+    recolor = style_guide.recolor_plan(prompt)
+    if recolor:
+        return list(recolor["steps"]), str(recolor["reply"]), ""
+    if _format_target(prompt):
+        steps = _plan_format_steps(prompt, state, provider_available)
+        if not steps:
+            return None
+        target = _format_target(prompt)
+        reply = f"Setting the canvas to {target[0]}\u00d7{target[1]}."
+        note = ""
+        if _extend_requested(prompt) and not provider_available:
+            note = ("No image generation provider is configured, so the new border "
+                    "was extended with edge/transparent pixels.")
+        return steps, reply, note
+    if _PSD_RE.search(prompt):
+        steps = _plan_psd_steps(prompt)
+        return (steps, "Saving a layered PSD.", "") if steps else None
+    if _is_text_request(prompt):
+        steps = _plan_text_steps(prompt)
+        if steps:
+            reply = ("Adding the title with a drop shadow."
+                     if _STYLE_RE.search(prompt) else "Adding the title text.")
+            return steps, reply, ""
+    # Structural ops (fill, text edit, align, rotate/flip, copy/paste, flatten,
+    # merge-down, colour overlay) — the guide's deterministic routing so the
+    # model never substitutes a generic adjustment/transform for them.
+    structural = style_guide.structural_plan(prompt)
+    if structural:
+        return list(structural["steps"]), str(structural["reply"]), ""
+    return None
+
+
+_DIMS_CLAIM_RE = re.compile(r"(\d{2,5})\s*[x\u00d7]\s*(\d{2,5})")
+_CANVAS_CHANGE_OPS = frozenset({
+    "document.crop", "document.resizeCanvas", "ai.generativeExpand", "document.importImage",
+})
+_TEXT_OPS = frozenset({"text.add", "layers.addStyle", "document.savePsd"})
+
+
+def _step_op_signature(step: Any) -> str:
+    """Identify an executed step by op plus its adjustment type / filter id."""
+    if not isinstance(step, dict):
+        return ""
+    op = str(step.get("op") or "")
+    params = step.get("params") or {}
+    if op in ("adjustments.apply", "adjustments.applyMasked"):
+        return f"{op}:{params.get('type') or ''}"
+    if op in ("filters.apply", "filters.applyMasked"):
+        return f"{op}:{params.get('id') or ''}"
+    return op
+
+
+# Phrases that name a specific edit. If the reply claims one of these but the
+# executed steps do not contain it, the reply is rewritten from the real steps.
+_OP_CLAIM_KEYWORDS: List[Tuple[str, Tuple[str, ...]]] = [
+    ("photo.autoTone", ("auto tone", "auto-tone", "autotone", "auto-tune")),
+    ("adjustments.apply:shadows-highlights", ("shadow", "highlight")),
+    ("adjustments.apply:white-balance", ("white balance", "white-balance",
+                                         "temperature", "colour cast", "color cast")),
+    ("adjustments.apply:vibrance", ("vibrance",)),
+    ("adjustments.apply:brightness-contrast", ("brightness", "contrast")),
+    ("adjustments.apply:black-white", ("black and white", "black & white",
+                                       "grayscale", "greyscale", "monochrome")),
+    ("filters.apply:clarity", ("clarity", "local contrast")),
+    ("filters.apply:vignette", ("vignette",)),
+    ("filters.apply:sharpen", ("sharpen", "crisper")),
+    ("retouch.skin", ("skin", "complexion")),
+    ("retouch.teeth", ("teeth", "smile")),
+]
+
+_OP_LABELS: Dict[str, str] = {
+    "photo.autoTone": "auto tone",
+    "adjustments.apply:shadows-highlights": "a shadow lift (highlights protected)",
+    "adjustments.apply:white-balance": "white balance",
+    "adjustments.apply:vibrance": "vibrance",
+    "adjustments.apply:brightness-contrast": "brightness/contrast",
+    "adjustments.apply:black-white": "black and white",
+    "filters.apply:clarity": "local contrast (clarity)",
+    "filters.apply:vignette": "a light vignette",
+    "filters.apply:sharpen": "sharpening",
+    "selection.face": "a face selection",
+    "selection.background": "a background selection",
+    "retouch.skin": "gentle skin retouching",
+    "retouch.teeth": "teeth whitening",
+}
+
+
+def _reply_from_ops(steps: List[Dict[str, Any]]) -> str:
+    """Describe what was actually executed, never what was planned."""
+    labels: List[str] = []
+    for step in steps or []:
+        sig = _step_op_signature(step)
+        label = _OP_LABELS.get(sig)
+        if label is None:
+            label = sig.split(":")[0] or "an edit"
+        if label not in labels:
+            labels.append(label)
+    if not labels:
+        return "Done."
+    return "Done \u2014 I applied " + ", ".join(labels) + "."
+
+
+def _reply_matches_ops(planned_reply: str, steps: List[Dict[str, Any]]) -> bool:
+    """True when the reply does not claim an edit that was not executed."""
+    text = (planned_reply or "").lower()
+    if not text:
+        return True
+    # "drop shadow" is a layer style, not a shadows/highlights adjustment.
+    text = text.replace("drop shadow", "drop-shadow-style")
+    executed = {_step_op_signature(step) for step in (steps or [])}
+    for sig, keywords in _OP_CLAIM_KEYWORDS:
+        if sig in executed:
+            continue
+        if any(keyword in text for keyword in keywords):
+            return False
+    return True
+
+
+
+def _verified_reply(
+    prompt: str,
+    steps: List[Dict[str, Any]],
+    results: List[Dict[str, Any]],
+    final_state: Any,
+    planned_reply: str,
+) -> str:
+    """Build the final reply from ACTUAL executed results + final document state.
+
+    Never let a plan's optimistic prose claim an edit that did not happen.
+    """
+    failed = [
+        r for r in (results or [])
+        if isinstance(r, dict) and r.get("ok") is False
+    ]
+    if failed:
+        op = str(failed[0].get("op") or "step")
+        err = failed[0].get("error") or "it did not complete"
+        return (f"I couldn't finish the {op} step ({err}). "
+                f"Nothing else was left changed — the image is back as it was.")
+    dims = _state_dims(final_state)
+    step_ops = [str(s.get("op") or "") for s in (steps or []) if isinstance(s, dict)]
+    claim = _DIMS_CLAIM_RE.search(planned_reply or "")
+    if claim and dims:
+        try:
+            claimed = (int(claim.group(1)), int(claim.group(2)))
+        except Exception:
+            claimed = None
+        if claimed and (abs(dims[0] - claimed[0]) > 2 or abs(dims[1] - claimed[1]) > 2):
+            if not any(op in _CANVAS_CHANGE_OPS for op in step_ops):
+                return (f"I planned to make it {claimed[0]}\u00d7{claimed[1]}, but the canvas is "
+                        f"still {dims[0]}\u00d7{dims[1]} — the resize didn't apply. "
+                        f"Please try again in the editor.")
+    if not steps and not results:
+        return planned_reply or "I didn't have a concrete edit to apply."
+    if not _is_text_request(prompt) and not _reply_matches_ops(planned_reply, steps):
+        return _reply_from_ops(steps)
+    if _is_text_request(prompt) and any(op in _TEXT_OPS for op in step_ops) and not failed:
+        return planned_reply or "Added the text."
+    if dims and any(op in _CANVAS_CHANGE_OPS for op in step_ops):
+        return (planned_reply or f"Done — the canvas is now {dims[0]}\u00d7{dims[1]}.")
+    return planned_reply
+
+
+def set_editor_planner(
+    fn: Optional[Callable[[List[dict], Optional[str]], Any]],
+) -> None:
+    global _EDITOR_PLANNER
+    _EDITOR_PLANNER = fn
+
+
+_ROUTING_GUIDANCE = (
+    "Routing rules (follow strictly): removing objects/people, adding new content "
+    "(e.g. a moon, an animal, a sign), or replacing/changing what is in the picture "
+    "are GENERATIVE edits -> use op \"ai_edit_image\" (op \"inpaint\" to remove, "
+    "\"generative\" to replace, with a descriptive prompt) or op \"generate_image\" "
+    "({prompt}) for added content. NEVER approximate these with selection.rectangle, "
+    "adjustments.apply, filters.apply, transform.* or any other deterministic op. "
+    "Use deterministic ops only for tone/colour/filter/crop/resize/text/selection "
+    "edits that do not invent or delete picture content. \"remove the background\" "
+    "is op \"ai_edit_image\" op \"remove-bg\". If a generative edit is requested and "
+    "no image provider is configured, do NOT substitute a deterministic edit: return "
+    "{\"reply\": \"" + _PROVIDER_REQUIRED_MESSAGE + "\", \"steps\": []}."
+)
+
+# Strict ops vocabulary for the model (the schema is also sent as a structured
+# output constraint, so the model can only emit these ops).
+_SCHEMA_NOTE = (
+    "Reply with ONLY a JSON object matching the ops schema. Valid step ops are the "
+    "deterministic editor ops above plus: \"generate_edit\" (a model image edit; "
+    "params {\"prompt\": str, \"mode\": \"instruction\"|\"masked\", \"mask\": optional "
+    "object description}) for any edit that invents, removes, replaces, recolours or "
+    "restyles image content; \"select_object\" (params {\"text\": object description}) "
+    "to select an object by description; and \"ask_user\" (params {\"question\": str, "
+    "\"options\": [2-3 short choices]}) when the request is ambiguous. For "
+    "\"generate_edit\" set params {\"prompt\": str, \"mode\": \"instruction\"|\"masked\"} "
+    "and do NOT set an inner \"op\" field: the server maps instruction/restyle edits to "
+    "the image model's \"generative\" op and masked region edits to \"inpaint\". Prefer "
+    "generate_edit over deterministic approximations for content changes, and ask_user "
+    "with 2-3 concrete choices rather than guessing a tone tweak."
+)
+
+_SYSTEM_PROMPT = (
+    "You are a photo-editor planning agent. Convert the user's request into a JSON plan of "
+    "editor operations. Return ONLY JSON: {\"reply\": str, \"steps\": [{\"op\": str, \"params\": {}}]}. "
+    "Available ops: " + ", ".join(OP_CATALOG) + ", plus ai_edit_image and generate_image. "
+    + _ROUTING_GUIDANCE + " "
+    + _CANONICAL_GUIDANCE + " " + _STYLE_GUIDANCE + " "
+    "Use selection.* before targeted edits when possible. Keep to <=6 steps. "
+    "If a screenshot is attached, use it to judge the current result. "
+    + _SCHEMA_NOTE
+)
+
+_CHECK_SYSTEM_PROMPT = (
+    "You are a photo-editor quality checker. A screenshot of the editor's CURRENT result is "
+    "attached along with the user's request and the iteration number. Decide whether the edit "
+    "satisfies the request. Return ONLY JSON: if it is complete, {\"done\": true, \"reply\": str}; "
+    "if more work is needed, {\"done\": false, \"reply\": str, \"steps\": [{\"op\": str, \"params\": {}}]}. "
+    "Available ops: " + ", ".join(OP_CATALOG) + ", plus ai_edit_image and generate_image. "
+    + _ROUTING_GUIDANCE + " "
+    + _CANONICAL_GUIDANCE + " " + _STYLE_GUIDANCE + " "
+    "Never repeat steps that already ran; <=4 steps. "
+    + _SCHEMA_NOTE
+)
+
+
+_GENERIC_TONE_OPS = frozenset({"photo.autoTone", "adjustments.apply", "filters.apply"})
+
+
+def _plan_is_generic_tone_only(steps: Any) -> bool:
+    """True when a plan is nothing but whole-image tone/colour/filter steps."""
+    items = [s for s in (steps or []) if isinstance(s, dict)]
+    return bool(items) and all(s.get("op") in _GENERIC_TONE_OPS for s in items)
+
+
+def _unsure_plan(prompt: str, plan: Optional[Dict[str, Any]]) -> Optional[Dict[str, Any]]:
+    """Demote a bare whole-image tone plan to an ask when the prompt is unsure.
+
+    When the planner produced ONLY generic tone ops (photo.autoTone /
+    adjustments.apply / filters.apply) for a prompt that matches no concrete
+    intent and names no concrete defect, the editor is guessing ("it just adds
+    vibrance and brightness"). Ask the user with 2-3 concrete choices instead.
+    """
+    if not isinstance(plan, dict):
+        return plan
+    steps = plan.get("steps") or []
+    if not _plan_is_generic_tone_only(steps):
+        return plan
+    if _generative_kind(prompt):
+        return plan
+    if style_guide.has_concrete_intent(prompt):
+        return plan
+    return style_guide.ask_user_plan()
+
+
+def _fallback_plan(prompt: str) -> Dict[str, Any]:
+    kind = _generative_kind(prompt)
+    if kind:
+        label = {"remove": "object removal", "add": "content addition",
+                 "replace": "content replacement", "restyle": "artistic restyle"}[kind]
+        return {
+            "reply": f"Planned an AI {label}.",
+            "planner": "fallback",
+            "steps": _generative_steps(kind, prompt),
+        }
+    guided = style_guide.fallback_plan(prompt)
+    if guided is not None:
+        guided["steps"] = style_guide.enforce_guards(guided.get("steps") or [])
+        return guided
+    # Nothing mapped to a concrete intent: ASK instead of silently applying a
+    # default tone tweak. The old fallback emitted a generic
+    # photo.autoTone/adjustments/filters stack here, which is the "it just adds
+    # vibrance and brightness" bug for unrecognized prompts.
+    return style_guide.ask_user_plan()
+
+
+def _parse_plan(raw: Any) -> Optional[Dict[str, Any]]:
+    if isinstance(raw, dict):
+        data = raw
+    else:
+        text = raw if isinstance(raw, str) else ""
+        if not text:
+            return None
+        try:
+            data = json.loads(text)
+        except Exception:
+            start, end = text.find("{"), text.rfind("}")
+            if start < 0 or end <= start:
+                return None
+            try:
+                data = json.loads(text[start:end + 1])
+            except Exception:
+                return None
+    # Every plan is validated against the strict ops schema; an invalid or empty
+    # plan returns None so the caller falls back to ask_user (never a tone
+    # default). See _validate_plan.
+    return _validate_plan(data)
+
+
+def _normalize_steps(body: Dict[str, Any]) -> List[Dict[str, Any]]:
+    if isinstance(body.get("steps"), list):
+        raw = body["steps"]
+    elif body.get("op"):
+        raw = [{"op": body["op"], "params": body.get("params") or {}}]
+    else:
+        raw = []
+    out: List[Dict[str, Any]] = []
+    for step in raw[:_MAX_STEPS]:
+        if not isinstance(step, dict):
+            continue
+        op = str(step.get("op") or "")
+        if op not in _OP_SET:
+            continue
+        out.append({"op": op, "params": step.get("params") or {}})
+    return out
+
+
+def _user(request: Request) -> Optional[str]:
+    try:
+        from src.auth_helpers import get_current_user
+        return get_current_user(request)
+    except Exception:
+        return None
+
+
+async def _default_editor_planner(messages: List[dict], owner: Optional[str]) -> Optional[str]:
+    """Plan with the local editor-agent model, falling back through the chain.
+
+    Order: per-request ``agent_model`` override -> local Qwen3.5-9B (vision,
+    screenshot attached) -> the same model text-only with a VL caption of the
+    screenshot -> the hosted default/utility chat model. The model actually
+    used is recorded so the route can report it.
+    """
+    result = await editor_agent_model.plan_with_editor_agent(
+        messages, owner, override=editor_agent_model.get_override(),
+        response_format=PLAN_RESPONSE_FORMAT,
+    )
+    if result is None:
+        return None
+    raw, model_used, source = result
+    editor_agent_model.set_last_model(model_used, source)
+    return raw
+
+
+def setup_editor_agent_routes() -> APIRouter:
+    router = APIRouter(tags=["editor-agent"])
+
+    if _EDITOR_PLANNER is None:
+        set_editor_planner(_default_editor_planner)
+
+    # Probe the local editor-agent model server (non-blocking) so the planner
+    # can use it for vision planning when reachable.
+    editor_agent_model.startup_probe()
+
+    # scoped session -> list of that session's live subscriber queues; id -> result future.
+    # A command is BROADCAST to every live subscriber (per-connection queue), never to a
+    # single shared queue: EventSource reconnects overlap, and with one shared queue a
+    # command could be consumed by a stale subscriber while the active page got nothing.
+    subscribers: Dict[str, List["asyncio.Queue[dict]"]] = {}
+    backlog: Dict[str, List[dict]] = {}
+    pending: Dict[str, asyncio.Future] = {}
+
+    def _subscribe(session: str) -> "asyncio.Queue[dict]":
+        q: "asyncio.Queue[dict]" = asyncio.Queue(maxsize=_QUEUE_MAX)
+        subscribers.setdefault(session, []).append(q)
+        # Replay anything enqueued while this session had no live subscriber.
+        for cmd in backlog.pop(session, []) or []:
+            try:
+                q.put_nowait(cmd)
+            except asyncio.QueueFull:
+                break
+        return q
+
+    def _unsubscribe(session: str, q: "asyncio.Queue[dict]") -> None:
+        subs = subscribers.get(session)
+        if subs and q in subs:
+            subs.remove(q)
+        if not subs:
+            subscribers.pop(session, None)
+
+    def _broadcast(session: str, cmd: dict) -> int:
+        subs = subscribers.get(session) or []
+        if subs:
+            for q in list(subs):
+                try:
+                    q.put_nowait(cmd)
+                except asyncio.QueueFull:
+                    pass
+            return len(subs)
+        # No live subscriber yet: hold it so a subscriber that connects shortly
+        # after still receives the command (bounded ring buffer).
+        bl = backlog.setdefault(session, [])
+        bl.append(cmd)
+        if len(bl) > _QUEUE_MAX:
+            del bl[0: len(bl) - _QUEUE_MAX]
+        return 0
+
+    def _scoped(session: Optional[str], owner: Optional[str]) -> str:
+        return f"{owner or 'anon'}:{session or 'default'}"
+
+    @router.post("/api/editor/plan")
+    async def plan(request: Request) -> JSONResponse:
+        owner = _user(request)
+        try:
+            body = await request.json()
+        except Exception:
+            body = {}
+        prompt = str(body.get("prompt") or "").strip()
+        state = body.get("state") or {}
+        mode = str(body.get("mode") or "plan").strip().lower()
+        screenshot = body.get("screenshot")
+        agent_model = str(body.get("agent_model") or "").strip()
+        if not prompt and mode != "check":
+            return JSONResponse({"reply": "No prompt provided.", "planner": "none", "steps": [],
+                                 "agent_model": agent_model or editor_agent_model.local_model()})
+
+        system = _CHECK_SYSTEM_PROMPT if mode == "check" else _SYSTEM_PROMPT
+        text = json.dumps({"prompt": prompt, "state": state}, ensure_ascii=False)
+        content: Any = text
+        if isinstance(screenshot, str) and screenshot.startswith("data:image/"):
+            content = [
+                {"type": "text", "text": text},
+                {"type": "image_url", "image_url": {"url": screenshot}},
+            ]
+        messages = [
+            {"role": "system", "content": system},
+            {"role": "user", "content": content},
+        ]
+
+        raw: Any = None
+        planner = _EDITOR_PLANNER
+        editor_agent_model.set_override(agent_model)
+        editor_agent_model.set_last_model("", "")
+        if planner is not None:
+            try:
+                raw = planner(messages, owner)
+                if inspect.isawaitable(raw):
+                    raw = await raw
+            except Exception:
+                raw = None
+        _used = editor_agent_model.get_last_model()
+        model_used = (_used[0] if _used and _used[0]
+                      else (agent_model or editor_agent_model.local_model()))
+        parsed = _parse_plan(raw)
+        if isinstance(parsed, dict):
+            parsed["agent_model"] = model_used
+        if mode != "check":
+            _special = _plan_special(prompt, state, _image_provider_available(owner))
+            if _special:
+                _special_steps, _special_reply, _ = _special
+                return JSONResponse({
+                    "reply": _special_reply,
+                    "planner": "deterministic",
+                    "steps": style_guide.enforce_guards(_special_steps) or _special_steps,
+                    "agent_model": model_used,
+                })
+        if parsed and mode != "check":
+            _strengthened = style_guide.strengthen(prompt, list(parsed.get("steps") or []))
+            if _strengthened != parsed.get("steps"):
+                parsed["steps"] = _strengthened
+                parsed["planner"] = str(parsed.get("planner") or "llm") + "+guide"
+            # Keep /plan and /agent consistent: a generative intent must never be
+            # left on a deterministic substitute (e.g. a model returning only
+            # selection/adjustment steps for 'remove the person on the left').
+            _generative = _ensure_generative(prompt, list(parsed.get("steps") or []))
+            if _generative != parsed.get("steps"):
+                parsed["steps"] = _generative
+                parsed["planner"] = str(parsed.get("planner") or "llm") + "+generative"
+            # Same safety guards the /agent path applies, so /plan never returns
+            # a stacked-lift or a global adjustment after a masked recolour.
+            parsed["steps"] = style_guide.enforce_guards(list(parsed.get("steps") or []))
+            # A bare whole-image tone plan for an unspecified prompt is a guess:
+            # ask the user instead of silently tweaking.
+            _maybe = _unsure_plan(prompt, parsed)
+            if _maybe is not parsed and isinstance(_maybe, dict):
+                _maybe["agent_model"] = model_used
+                parsed = _maybe
+
+        if mode == "check":
+            # Never let a self-check re-plan substitute a generative placeImage
+            # for a deterministic recolour; re-issue the masked-hue plan instead.
+            _recolor = style_guide.recolor_plan(prompt)
+            if _recolor and _plan_uses_ai_content(list((parsed or {}).get("steps") or [])):
+                return JSONResponse({
+                    "reply": str(_recolor["reply"]),
+                    "planner": "deterministic",
+                    "steps": style_guide.enforce_guards(list(_recolor["steps"])),
+                    "agent_model": model_used,
+                })
+            if parsed and (parsed.get("done") or parsed.get("steps")):
+                return JSONResponse(parsed)
+            return JSONResponse({
+                "done": True,
+                "reply": (parsed or {}).get("reply") or "The edit looks complete.",
+                "planner": (parsed or {}).get("planner") or "check",
+                "steps": [],
+                "agent_model": model_used,
+            })
+        if parsed:
+            return JSONResponse(parsed)
+        _fallback = _fallback_plan(prompt)
+        _fallback["agent_model"] = model_used
+        return JSONResponse(_fallback)
+
+    @router.post("/api/editor/bridge/command")
+    async def bridge_command(request: Request) -> JSONResponse:
+        owner = _user(request)
+        try:
+            body = await request.json()
+        except Exception:
+            body = {}
+        session = _scoped(body.get("session"), owner)
+        steps = _normalize_steps(body)
+        wait = bool(body.get("wait"))
+        timeout = float(body.get("timeout") or _BRIDGE_DEFAULT_TIMEOUT)
+        ids: List[str] = []
+        wait_ids: List[str] = []
+        for step in steps:
+            cid = uuid.uuid4().hex
+            ids.append(cid)
+            if wait:
+                pending[cid] = asyncio.get_event_loop().create_future()
+                wait_ids.append(cid)
+            _broadcast(session, {"id": cid, "op": step["op"], "params": step["params"]})
+        if wait and len(wait_ids) == 1:
+            try:
+                result = await asyncio.wait_for(pending[wait_ids[0]], timeout=timeout)
+                return JSONResponse(result)
+            except asyncio.TimeoutError:
+                pending.pop(wait_ids[0], None)
+                return JSONResponse({"ok": False, "error": "timeout", "id": wait_ids[0]})
+        return JSONResponse({"queued": ids, "session": session})
+
+    @router.get("/api/editor/bridge/events")
+    async def bridge_events(request: Request, session: str = "default") -> StreamingResponse:
+        owner = _user(request)
+        scoped = _scoped(session, owner)
+
+        async def gen():
+            q = _subscribe(scoped)
+            try:
+                yield ": connected\n\n"
+                while not _shutdown.is_shutting_down():
+                    try:
+                        cmd = await asyncio.wait_for(q.get(), timeout=15)
+                        yield f"data: {json.dumps(cmd)}\n\n"
+                    except asyncio.TimeoutError:
+                        yield ": keepalive\n\n"
+            finally:
+                _unsubscribe(scoped, q)
+
+        return StreamingResponse(gen(), media_type="text/event-stream",
+                                 headers={"Cache-Control": "no-cache", "X-Accel-Buffering": "no"})
+
+    @router.post("/api/editor/bridge/result")
+    async def bridge_result(request: Request) -> JSONResponse:
+        try:
+            body = await request.json()
+        except Exception:
+            body = {}
+        cid = str(body.get("id") or "")
+        fut = pending.pop(cid, None)
+        if fut is not None and not fut.done():
+            fut.set_result({
+                "id": cid, "ok": bool(body.get("ok")),
+                "result": body.get("result"), "error": body.get("error"),
+                "screenshot": body.get("screenshot"),
+            })
+        return JSONResponse({"ok": True})
+
+    @router.post("/api/editor/bridge/await")
+    async def bridge_await(request: Request) -> JSONResponse:
+        try:
+            body = await request.json()
+        except Exception:
+            body = {}
+        cid = str(body.get("id") or "")
+        timeout = float(body.get("timeout") or _BRIDGE_DEFAULT_TIMEOUT)
+        fut = pending.get(cid)
+        if fut is None:
+            fut = asyncio.get_event_loop().create_future()
+            pending[cid] = fut
+        try:
+            result = await asyncio.wait_for(fut, timeout=timeout)
+            return JSONResponse(result)
+        except asyncio.TimeoutError:
+            pending.pop(cid, None)
+            return JSONResponse({"ok": False, "error": "timeout", "id": cid})
+
+    _AGENT_SYSTEM_PROMPT = (
+        "You are the photo editor agent. You drive the open image editor and "
+        "may also run AI image operations. Available editor ops: "
+        + ", ".join(OP_CATALOG)
+        + ", plus ai_edit_image and generate_image. "
+        "Respond with ONLY a JSON object: {\"reply\": <short text>, "
+        "\"steps\": [{\"op\": <string>, \"params\": {...}}]}. "
+        + _ROUTING_GUIDANCE + " "
+        + _CANONICAL_GUIDANCE + " " + _STYLE_GUIDANCE + " "
+        "Prefer AI content ops for generative requests: \"remove the person on the left\" "
+        "-> op \"ai_edit_image\" op \"inpaint\" with a prompt; \"add a full moon in the sky\" "
+        "-> op \"generate_image\" with a prompt. "
+        "Use deterministic editor ops (adjustments.apply, filters.apply, selection.*, "
+        "layers.placeImage, text.add, ...) only for non-generative, precise edits. "
+        "Keep steps minimal and ordered. "
+        + _SCHEMA_NOTE
+    )
+
+    def _scoped_editor_tools() -> List[str]:
+        """The exact tool list offered to the model for a photo_editor turn."""
+        fallback = [
+            "plan_edit", "run_editor_command", "get_editor_screenshot",
+            "ai_edit_image", "generate_image", "ask_user",
+        ]
+        try:
+            from src.tool_policy import ToolPolicy
+            from src.tool_schemas import FUNCTION_TOOL_SCHEMAS
+            from src.turn_contract import resolve_turn_contract
+
+            contract = resolve_turn_contract(
+                capabilities={"photo_editor"},
+                schemas=FUNCTION_TOOL_SCHEMAS,
+                policy=ToolPolicy(),
+                required_capabilities={"photo_editor"},
+            )
+            return sorted(contract.offered) or fallback
+        except Exception:
+            return fallback
+
+    @router.post("/api/editor/agent")
+    async def editor_agent(request: Request) -> JSONResponse:
+        """Scoped photo_editor agent turn (Quick Edit).
+
+        Offers ONLY the editor tool family plus ask_user, plans edits, and
+        drives the open editor through the owner-scoped bridge. AI edit and
+        generation actions land as new layers; the original is never
+        overwritten.
+        """
+        owner = _user(request)
+        try:
+            body = await request.json()
+        except Exception:
+            body = {}
+        prompt = str(body.get("prompt") or "").strip()
+        session = str(body.get("editor_session") or body.get("session") or "default")
+        state = body.get("state") if isinstance(body.get("state"), dict) else {}
+        screenshot = body.get("screenshot")
+        # Optional user-picked image model (from the editor model selector).
+        model_choice = str(body.get("model") or body.get("image_model") or "").strip()
+        # Optional user-picked PLANNER model (the editor agent/planner model).
+        agent_model = str(body.get("agent_model") or "").strip()
+        tools_offered = _scoped_editor_tools()
+        scoped = _scoped(session, owner)
+        trace: List[Dict[str, Any]] = [
+            {"type": "session", "session": scoped, "tools_offered": tools_offered},
+        ]
+        if not prompt:
+            return JSONResponse({
+                "ok": False, "reply": "No prompt provided.",
+                "tools_offered": tools_offered, "steps": [], "trace": trace,
+                "agent_model": agent_model or editor_agent_model.local_model(),
+            })
+        text = json.dumps({"prompt": prompt, "state": state}, ensure_ascii=False)
+        content: Any = text
+        if isinstance(screenshot, str) and screenshot.startswith("data:image/"):
+            content = [
+                {"type": "text", "text": text},
+                {"type": "image_url", "image_url": {"url": screenshot}},
+            ]
+        messages = [
+            {"role": "system", "content": _AGENT_SYSTEM_PROMPT},
+            {"role": "user", "content": content},
+        ]
+        raw = None
+        planner = _EDITOR_PLANNER
+        editor_agent_model.set_override(agent_model)
+        editor_agent_model.set_last_model("", "")
+        if planner is not None:
+            try:
+                raw = planner(messages, owner)
+                if hasattr(raw, "__await__"):
+                    raw = await raw
+            except Exception:
+                raw = None
+        _used = editor_agent_model.get_last_model()
+        model_used = (_used[0] if _used and _used[0]
+                      else (agent_model or editor_agent_model.local_model()))
+        plan = _parse_plan(raw) or _fallback_plan(prompt)
+        _strengthened = style_guide.strengthen(prompt, list(plan.get("steps") or []))
+        if _strengthened != plan.get("steps"):
+            plan = {**plan, "steps": _strengthened,
+                    "planner": f"{plan.get('planner') or 'llm'}+guide"}
+        kind = _generative_kind(prompt)
+        provider_available = _image_provider_available(owner)
+        # Deterministic overrides for intents the model reliably botches: canvas
+        # format/crop/extend, text + layer styles, and PSD export.
+        _special = _plan_special(prompt, state, provider_available)
+        special_note = ""
+        if _special:
+            special_steps, special_reply, special_note = _special
+            steps = style_guide.enforce_guards(special_steps) or list(special_steps)
+            reply = special_reply
+            kind = None
+            plan = {**plan, "steps": steps,
+                    "planner": f"{plan.get('planner') or 'llm'}+deterministic"}
+        else:
+            steps = _ensure_generative(prompt, list(plan.get("steps") or []))
+            steps = style_guide.enforce_guards(steps)
+            if steps != (plan.get("steps") or []):
+                plan = {**plan, "steps": steps,
+                        "planner": f"{plan.get('planner') or 'llm'}+generative"}
+            reply = str(plan.get("reply") or "")
+            # A bare whole-image tone plan for an unspecified prompt is a guess:
+            # ask the user instead of silently tweaking.
+            # A bare whole-image tone plan for an unspecified prompt is a guess:
+            # ask the user instead of silently tweaking. Only replace when the
+            # guard actually changed the plan (identity), so a model-supplied
+            # ask_user never wipes out a concrete generative edit.
+            _base_plan = {**plan, "steps": steps}
+            _maybe = _unsure_plan(prompt, _base_plan)
+            if _maybe is not _base_plan and isinstance(_maybe, dict) and _maybe.get("ask_user"):
+                plan = _maybe
+                steps = []
+                reply = str(_maybe.get("reply") or "")
+        trace.append({
+            "type": "plan", "tool": "plan_edit",
+            "planner": plan.get("planner"), "steps": steps,
+            "image_provider": provider_available, "agent_model": model_used,
+        })
+        # A vague prompt with no concrete defect asks the user instead of
+        # guessing a token edit (2-3 concrete options).
+        ask_user_payload = plan.get("ask_user")
+        if isinstance(ask_user_payload, dict) and not steps and not _special:
+            trace.append({"type": "ask_user",
+                          "question": ask_user_payload.get("question")})
+            return JSONResponse({
+                "ok": True,
+                "ask_user": ask_user_payload,
+                "ask_user_pending": True,
+                "reply": reply or str(ask_user_payload.get("question") or ""),
+                "tools_offered": tools_offered,
+                "steps": [],
+                "trace": trace,
+                "results": [],
+                "agent_model": model_used,
+            })
+        # No image provider: stop before any edit runs and tell the user plainly
+        # (zero canvas changes; nothing to roll back).
+        if (kind or _plan_uses_ai_content(steps)) and not provider_available:
+            trace.append({"type": "blocked", "reason": "image_provider_unavailable"})
+            return JSONResponse({
+                "ok": False,
+                "blocked": True,
+                "needs_provider": True,
+                "reply": _PROVIDER_REQUIRED_MESSAGE,
+                "message": _PROVIDER_REQUIRED_MESSAGE,
+                "image_provider": False,
+                "tools_offered": tools_offered,
+                "steps": steps,
+                "trace": trace,
+                "results": [],
+                "agent_model": model_used,
+            })
+        results: List[Dict[str, Any]] = []
+        for step in steps:
+            op = step.get("op")
+            params = step.get("params") or {}
+            if op in ("ai_edit_image", "generate_image"):
+                try:
+                    from src.agent_tools.editor_tools import AiEditImageTool, GenerateImageLayerTool
+                except Exception:
+                    results.append({"op": op, "ok": False, "error": "editor tools unavailable"})
+                    break
+                tool_payload = dict(params)
+                tool_payload.setdefault("session", session)
+                # Route to the user-picked model when one is selected.
+                if model_choice:
+                    tool_payload.setdefault("model", model_choice)
+                # Hand the AI step the canvas image the client already captured
+                # for this request. Without it the tool falls back to a separate
+                # bridge screenshot, which is not reliably answered right after a
+                # selection step (the masked path was losing the canvas image).
+                if isinstance(screenshot, str) and screenshot.startswith("data:image/"):
+                    tool_payload.setdefault("image", screenshot)
+                tool_cls = AiEditImageTool if op == "ai_edit_image" else GenerateImageLayerTool
+                try:
+                    _desc, res = await tool_cls().execute(
+                        json.dumps(tool_payload),
+                        {"owner": owner, "session_id": scoped},
+                    )
+                except Exception as exc:
+                    res = {"error": str(exc), "exit_code": 1}
+                res = res if isinstance(res, dict) else {}
+                ok = res.get("exit_code", 0) == 0
+                step_result = {
+                    k: res.get(k) for k in ("image_id", "image_url", "placed", "output", "model")
+                    if k in res
+                }
+                results.append({
+                    "op": op, "ok": ok, "result": step_result,
+                    # Surface the real provider/tool failure so the reply can
+                    # say what went wrong instead of a bare ok:true/ok:false.
+                    "error": None if ok else (res.get("error") or res.get("output") or "it did not complete"),
+                })
+                trace.append({"type": "step", "op": op, "ok": ok, "result": step_result})
+                if not ok:
+                    break
+                continue
+            cid = uuid.uuid4().hex
+            pending[cid] = asyncio.get_event_loop().create_future()
+            _broadcast(scoped, {"id": cid, "op": op, "params": params})
+            try:
+                res = await asyncio.wait_for(pending[cid], timeout=_BRIDGE_DEFAULT_TIMEOUT)
+            except asyncio.TimeoutError:
+                pending.pop(cid, None)
+                results.append({"op": op, "ok": False, "error": "timeout"})
+                trace.append({"type": "step", "op": op, "ok": False, "error": "timeout"})
+                break
+            results.append(res)
+            trace.append({"type": "step", "op": op, "ok": res.get("ok"), "result": res.get("result")})
+            if res.get("ok") is False:
+                break
+        # Post-run verification: read the ACTUAL canvas back and base the reply
+        # on executed results + final document.info, never the plan.
+        final_state: Dict[str, Any] = {}
+        if steps and not any(r.get("ok") is False for r in results):
+            try:
+                _info_id = uuid.uuid4().hex
+                pending[_info_id] = asyncio.get_event_loop().create_future()
+                _broadcast(scoped, {"id": _info_id, "op": "document.info", "params": {}})
+                _info = await asyncio.wait_for(pending[_info_id], timeout=60)
+                if isinstance(_info, dict) and isinstance(_info.get("result"), dict):
+                    final_state = _info["result"]
+            except Exception:
+                final_state = {}
+        planned_reply = reply
+        reply = _verified_reply(prompt, steps, results, final_state, planned_reply)
+        if special_note and special_note.strip() not in reply:
+            reply = (reply + " " + special_note.strip()).strip()
+        return JSONResponse({
+            "ok": not any(r.get("ok") is False for r in results),
+            "reply": reply or "Done.",
+            "planned_reply": planned_reply,
+            "image_provider": provider_available,
+            "final_state": final_state,
+            "tools_offered": tools_offered,
+            "tools": ["plan_edit"],
+            "steps": steps,
+            "trace": trace,
+            "results": results,
+            "agent_model": model_used,
+        })
+
+    @router.get("/api/editor/style-guide")
+    async def style_guide_route() -> JSONResponse:
+        """The shared intent -> ops guide (single source of truth).
+
+        The browser fallback planner fetches this so the client and server
+        routing rules cannot drift.
+        """
+        return JSONResponse(style_guide.as_json())
+
+    @router.get("/api/editor/image-models")
+    async def editor_image_models(request: Request) -> JSONResponse:
+        """List the image models available from configured, owner-visible providers.
+
+        Each entry is ``{id, label, kind, provider}`` where ``id`` is the model id
+        to pass as ``model`` to ai_edit_image / generate_image, and ``kind`` is
+        ``edit`` (editing/inpainting models) or ``generate`` (text-to-image).
+        """
+        owner = _user(request)
+        models: List[Dict[str, Any]] = []
+        seen: set = set()
+        try:
+            from core.database import SessionLocal, ModelEndpoint
+            from src.auth_helpers import owner_filter
+            from src.endpoint_resolver import _endpoint_enabled_models
+
+            db = SessionLocal()
+            try:
+                query = owner_filter(
+                    db.query(ModelEndpoint).filter(ModelEndpoint.is_enabled == True),  # noqa: E712
+                    ModelEndpoint,
+                    owner,
+                )
+                for ep in query.all():
+                    if getattr(ep, "model_type", None) != "image":
+                        continue
+                    provider = getattr(ep, "name", None) or getattr(ep, "base_url", "") or "image"
+                    for name in _endpoint_enabled_models(ep):
+                        key = (provider, name)
+                        if key in seen:
+                            continue
+                        seen.add(key)
+                        models.append({
+                            "id": name,
+                            "label": name,
+                            "kind": "edit" if _EDIT_MODEL_RE.search(name) else "generate",
+                            "provider": provider,
+                            "endpoint_id": getattr(ep, "id", None),
+                            "base_url": getattr(ep, "base_url", "") or "",
+                        })
+            finally:
+                db.close()
+        except Exception:
+            logger.warning("editor image-models lookup failed", exc_info=True)
+        return JSONResponse({"models": models})
+
+    @router.get("/api/editor/agent-models")
+    async def editor_agent_models(request: Request) -> JSONResponse:
+        """List the models the editor agent/planner can run on.
+
+        Each entry is ``{id, label, source, vision, base_url}`` where ``id`` is
+        passed as ``agent_model`` to /api/editor/plan or /api/editor/agent, and
+        ``source`` is ``local`` (the local Qwen3.5-9B vision server) or
+        ``hosted`` (the configured default/utility chat model that the planner
+        falls back to).
+        """
+        owner = _user(request)
+        try:
+            models = await editor_agent_model.list_editor_agent_models(owner)
+        except Exception:
+            logger.warning("editor agent-models lookup failed", exc_info=True)
+            models = []
+        return JSONResponse({
+            "models": models,
+            "probe": editor_agent_model.probe_status(),
+        })
+
+    @router.post("/api/editor/self-check")
+    async def editor_self_check(request: Request) -> JSONResponse:
+        """Same-origin VL self-check: compare BEFORE/AFTER against the intent.
+
+        The local VL server (seneca :8097) sends no CORS headers, so the browser
+        cannot call it directly and the self-check silently "passed". This route
+        proxies the two images + intent to the agent VLM and returns
+        ``{done, issues, retry_hint, text}`` (``done=True`` with
+        ``reason="unavailable"`` on any failure so the client never loops).
+        """
+        owner = _user(request)
+        try:
+            body = await request.json()
+        except Exception:
+            body = {}
+        result = await editor_agent_model.self_check(
+            body.get("before"),
+            body.get("after"),
+            str(body.get("prompt") or body.get("intent") or ""),
+            model=str(body.get("model") or "").strip() or None,
+            owner=owner,
+        )
+        return JSONResponse(result)
+
+    return router
diff --git a/routes/email/email_helpers.py b/routes/email/email_helpers.py
index d697b2fe7..1808af13b 100644
--- a/routes/email/email_helpers.py
+++ b/routes/email/email_helpers.py
@@ -17,8 +17,6 @@ import base64
 import time
 import imaplib
 import smtplib
-import socket
-import ssl
 import email as email_mod
 import email.header
 import email.utils
@@ -38,7 +36,6 @@ from typing import Optional, List
 
 from src.auth_helpers import _auth_disabled, get_current_user
 from src.secret_storage import decrypt as _decrypt
-from src.url_safety import OutboundAddressBlocked, connect_outbound_tcp
 
 logger = logging.getLogger(__name__)
 
@@ -163,94 +160,6 @@ def _smtp_security_mode(cfg: dict) -> str:
     return "ssl"
 
 
-# Raised when a mail host resolves into a denied range (see _mail_private_blocked).
-MailServerAddressBlocked = OutboundAddressBlocked
-
-
-def _mail_private_blocked(owner: str | None) -> bool:
-    """Whether private/loopback/shared mail destinations are denied for *owner*.
-
-    Link-local (cloud metadata), multicast, reserved and unspecified addresses
-    are always denied (src/url_safety.py). Private ranges are where a mail
-    tester or saved account becomes an internal-network probe, so they are
-    only allowed for an admin or in single-user mode (AUTH_ENABLED=false), the
-    same principals trusted with host-level tools. Operators of multi-user
-    deployments with a LAN mail server opt in with EMAIL_ALLOW_PRIVATE_IPS=true;
-    EMAIL_BLOCK_PRIVATE_IPS=true denies private ranges for everyone.
-    """
-    if os.getenv("EMAIL_BLOCK_PRIVATE_IPS", "").strip().lower() == "true":
-        return True
-    if os.getenv("EMAIL_ALLOW_PRIVATE_IPS", "").strip().lower() == "true":
-        return False
-    from src.tool_security import owner_is_admin_or_single_user
-
-    return not owner_is_admin_or_single_user((owner or "").strip() or None)
-
-
-def _mail_socket_timeout(timeout):
-    return socket._GLOBAL_DEFAULT_TIMEOUT if timeout is None else timeout
-
-
-class _PolicyIMAP4(imaplib.IMAP4):
-    """IMAP4 whose socket comes from connect_outbound_tcp.
-
-    The mail host is resolved once and connected to only at the addresses the
-    address policy approved, so DNS rebinding between check and connect is
-    impossible. STARTTLS still verifies against ``self.host``.
-    """
-
-    def __init__(self, host, port, *, block_private: bool, timeout=None):
-        self._block_private = block_private
-        super().__init__(host, port, timeout=timeout)
-
-    def _create_socket(self, timeout):
-        if timeout is not None and not timeout:
-            raise ValueError("Non-blocking socket (timeout=0) is not supported")
-        return connect_outbound_tcp(
-            self.host, self.port, timeout=_mail_socket_timeout(timeout), block_private=self._block_private,
-        )
-
-
-class _PolicyIMAP4_SSL(imaplib.IMAP4_SSL):
-    """IMAP4_SSL over a policy-checked socket; TLS SNI/verification use the hostname."""
-
-    def __init__(self, host, port, *, block_private: bool, timeout=None, ssl_context=None):
-        self._block_private = block_private
-        super().__init__(host, port, ssl_context=ssl_context, timeout=timeout)
-
-    def _create_socket(self, timeout):
-        sock = _PolicyIMAP4._create_socket(self, timeout)
-        return self.ssl_context.wrap_socket(sock, server_hostname=self.host)
-
-
-class _PolicySMTP(smtplib.SMTP):
-    """SMTP whose socket comes from connect_outbound_tcp (see _PolicyIMAP4)."""
-
-    def __init__(self, host="", port=0, *, block_private: bool, **kwargs):
-        self._block_private = block_private
-        super().__init__(host, port, **kwargs)
-
-    def _get_socket(self, host, port, timeout):
-        if timeout is not None and not timeout:
-            raise ValueError("Non-blocking socket (timeout=0) is not supported")
-        return connect_outbound_tcp(
-            host, port, timeout=timeout, block_private=self._block_private,
-            source_address=self.source_address,
-        )
-
-
-class _PolicySMTP_SSL(smtplib.SMTP_SSL):
-    """SMTP_SSL over a policy-checked socket; TLS SNI/verification use the hostname."""
-
-    def __init__(self, host="", port=0, *, block_private: bool, **kwargs):
-        self._block_private = block_private
-        super().__init__(host, port, **kwargs)
-
-    def _get_socket(self, host, port, timeout):
-        sock = _PolicySMTP._get_socket(self, host, port, timeout)
-        return self.context.wrap_socket(sock, server_hostname=self._host)
-
-
 def _send_smtp_message(cfg: dict, from_addr: str, recipients: list[str], message: str | bytes, timeout: int = 30) -> None:
     """Send through SMTP using the configured transport security mode."""
     host = cfg["smtp_host"]
@@ -269,15 +178,14 @@ def _send_smtp_message(cfg: dict, from_addr: str, recipients: list[str], message
             smtp.login(user, password)
 
     security = _smtp_security_mode(cfg)
-    block_private = _mail_private_blocked(cfg.get("owner"))
 
     if security == "ssl":
-        with _PolicySMTP_SSL(host, port, timeout=timeout, block_private=block_private) as smtp:
+        with smtplib.SMTP_SSL(host, port, timeout=timeout) as smtp:
             _auth_smtp(smtp)
             smtp.sendmail(from_addr, recipients, message)
         return
 
-    with _PolicySMTP(host, port, timeout=timeout, block_private=block_private) as smtp:
+    with smtplib.SMTP(host, port, timeout=timeout) as smtp:
         if security == "starttls":
             smtp.starttls()
         _auth_smtp(smtp)
@@ -316,39 +224,6 @@ def _friendly_email_auth_error(protocol: str, host: str, error: object) -> str:
     return raw[:200]
 
 
-# Bound at import: callers (and tests) may swap out imaplib.IMAP4 itself.
-_IMAP_ABORT = imaplib.IMAP4.abort
-
-
-def _mail_connection_test_error(protocol: str, host: str, error: BaseException) -> str:
-    """User-facing result for a failed IMAP/SMTP connection test.
-
-    Transport failures are reported by category, never with the peer's own
-    bytes: a non-mail service answering on the chosen host/port would
-    otherwise have its banner echoed back (an internal-service fingerprinting
-    oracle). Errors from a server that does speak the protocol (login/auth
-    rejections) keep their text via _friendly_email_auth_error, since that is
-    what the user needs to fix their settings.
-    """
-    if isinstance(error, MailServerAddressBlocked):
-        return f"{protocol} server address is not allowed by this server's network policy"
-    if isinstance(error, (_IMAP_ABORT, smtplib.SMTPConnectError, smtplib.SMTPServerDisconnected)):
-        return f"{protocol} server did not respond like an {protocol} server"
-    if isinstance(error, ssl.SSLCertVerificationError):
-        return f"{protocol} TLS certificate verification failed"
-    if isinstance(error, ssl.SSLError):
-        return f"{protocol} TLS handshake failed; check the port and security setting"
-    if isinstance(error, (socket.timeout, TimeoutError)):
-        return f"{protocol} connection timed out"
-    if isinstance(error, ConnectionRefusedError):
-        return f"{protocol} connection refused"
-    if isinstance(error, socket.gaierror):
-        return f"{protocol} server name could not be resolved"
-    if isinstance(error, OSError) and not isinstance(error, smtplib.SMTPException):
-        return f"{protocol} connection failed"
-    return _friendly_email_auth_error(protocol, host, error)
-
-
 def _strip_think(text: str) -> str:
     """Email-flavored think strip — thin wrapper over the central helper.
 
@@ -810,21 +685,18 @@ def _ensure_sender_signatures_table(conn):
         _lg.getLogger(__name__).warning(f"sender_signatures owner-migration skipped: {_mig_e}")
 
 
-def attachment_extract_dir(folder: str, uid: str, *, owner: str, account_id: str | None) -> Path:
-    """Containment-safe extraction directory for one message's attachments.
+def attachment_extract_dir(folder: str, uid: str) -> Path:
+    """Containment-safe extraction directory for an attachment.
 
-    IMAP UIDs are small per-mailbox counters, so `folder_uid` alone put every
-    user's and every account's "INBOX 42" in one directory, where extractions
-    overwrote each other by filename (a path handed to one user's agent could
-    then hold another user's attachment). See src.mail_attachment_paths: the
-    directory is keyed by (owner, account, folder, uid) and contained in
-    ATTACHMENTS_DIR whatever `folder`/`uid` hold."""
-    from src.mail_attachment_paths import attachment_scope_dir
-
-    try:
-        return attachment_scope_dir(ATTACHMENTS_DIR, folder, uid, owner=owner, account_id=account_id)
-    except ValueError:
+    `folder` and `uid` are user-controlled (query/path params). Flatten them to
+    a single safe path segment so a value like folder='../../tmp' can't escape
+    ATTACHMENTS_DIR, then assert containment as belt-and-suspenders."""
+    key = re.sub(r"[^A-Za-z0-9._-]", "_", f"{folder}_{uid}") or "_"
+    target = (ATTACHMENTS_DIR / key).resolve()
+    base = ATTACHMENTS_DIR.resolve()
+    if target != base and base not in target.parents:
         raise HTTPException(400, "Invalid attachment location")
+    return target
 
 
 def _init_scheduled_db():
@@ -1205,8 +1077,6 @@ def _get_email_config(account_id: str | None = None, owner: str = "") -> dict:
                 cfg = {
                     "account_id": row.id,
                     "account_name": row.name,
-                    # Principal for the outbound mail address policy.
-                    "owner": row.owner or owner or "",
                     "smtp_host": row.smtp_host or "",
                     "smtp_port": int(row.smtp_port or 465),
                     "smtp_security": _smtp_security_mode({"smtp_security": getattr(row, "smtp_security", ""), "smtp_port": row.smtp_port}),
@@ -1240,7 +1110,6 @@ def _get_email_config(account_id: str | None = None, owner: str = "") -> dict:
     cfg = {
         "account_id": resolved_id,
         "account_name": "legacy",
-        "owner": owner or "",
         "smtp_host": settings.get("smtp_host", os.environ.get("SMTP_HOST", "")),
         "smtp_port": int(settings.get("smtp_port", os.environ.get("SMTP_PORT", "465")) or 465),
         "smtp_security": _smtp_security_mode({
@@ -1304,16 +1173,11 @@ def _open_imap_connection(
     starttls: bool,
     timeout: int = _IMAP_TIMEOUT_SECONDS,
     ssl_context=None,
-    owner: str | None = None,
 ):
-    """Open an IMAP connection using the configured security mode.
-
-    `owner` is the principal the destination is judged for
-    (see _mail_private_blocked)."""
+    """Open an IMAP connection using the configured security mode."""
     port = int(port or 993)
-    block_private = _mail_private_blocked(owner)
     if starttls:
-        conn = _PolicyIMAP4(host, port, timeout=timeout, block_private=block_private)
+        conn = imaplib.IMAP4(host, port, timeout=timeout)
         try:
             if ssl_context:
                 conn.starttls(ssl_context=ssl_context)
@@ -1329,9 +1193,9 @@ def _open_imap_connection(
             raise
     elif port == 993:
         kwargs = {"ssl_context": ssl_context} if ssl_context else {}
-        conn = _PolicyIMAP4_SSL(host, port, timeout=timeout, block_private=block_private, **kwargs)
+        conn = imaplib.IMAP4_SSL(host, port, timeout=timeout, **kwargs)
     else:
-        conn = _PolicyIMAP4(host, port, timeout=timeout, block_private=block_private)
+        conn = imaplib.IMAP4(host, port, timeout=timeout)
     try:
         conn.sock.settimeout(timeout)
     except Exception:
@@ -1371,7 +1235,6 @@ def _imap_connect(account_id: str | None = None, owner: str = "",
         cfg["imap_port"],
         starttls=bool(cfg.get("imap_starttls")),
         timeout=timeout,
-        owner=cfg.get("owner"),
     )
     try:
         if cfg.get("oauth_provider") == "google":
diff --git a/routes/email/email_routes.py b/routes/email/email_routes.py
index 172790a6c..12d2dd82a 100644
--- a/routes/email/email_routes.py
+++ b/routes/email/email_routes.py
@@ -36,10 +36,10 @@ from pathlib import Path
 from email.mime.text import MIMEText
 from email.mime.multipart import MIMEMultipart
 
-from starlette.concurrency import run_in_threadpool
 from fastapi import APIRouter, Query, UploadFile, File, BackgroundTasks, HTTPException, Depends, Request
 from fastapi.responses import FileResponse, StreamingResponse
 from src.constants import DATA_DIR
+from src import shutdown as _shutdown
 from src.path_confinement import confine
 
 from src.llm_core import llm_call_async
@@ -61,7 +61,6 @@ from .email_helpers import (
     _fetch_sender_thread_context, _pre_retrieve_context,
     _EMAIL_REPLY_SYS_PROMPT_BASE, _POOL_HOOKS,
     _friendly_email_auth_error, _email_summary_failure_log_detail,
-    _mail_connection_test_error, _mail_private_blocked, _PolicySMTP, _PolicySMTP_SSL,
     _generate_email_summary, EMAIL_SUMMARY_ERROR_CODE, EMAIL_SUMMARY_ERROR_MESSAGE,
     SendEmailRequest, ExtractStyleRequest,
     ATTACHMENTS_DIR, COMPOSE_UPLOADS_DIR, SCHEDULED_DB,
@@ -1543,44 +1542,6 @@ def _envelope_recipients(*fields: str) -> list:
     return out
 
 
-_MD_LINK_URL_RE = re.compile(r"\((https?://)[^)\s]*")
-
-
-def _md_links_to_html(s: str) -> str:
-    """Linear ``re.sub(r"\\[([^\\]]+)\\]\\((https?://[^)\\s]+)\\)", '<a href="\\2">\\1</a>', s)``.
-
-    Every `[` before the next `]` shares that `]`, so only the first can match;
-    and when a URL runs into whitespace/end without `)`, every later `[` whose
-    `]` also lies before that stop fails the same way. Skipping those spans
-    keeps a `[[[` or `[a](http://x[a](http://x` flood O(n) instead of the
-    regex's O(n^2).
-    """
-    out: list[str] = []
-    emitted = scan = 0
-    while True:
-        open_at = s.find("[", scan)
-        if open_at < 0:
-            break
-        close_at = s.find("]", open_at + 1)
-        if close_at < 0:
-            break
-        scan = close_at + 1
-        if close_at == open_at + 1:
-            continue
-        url = _MD_LINK_URL_RE.match(s, close_at + 1)
-        if url is None:
-            continue
-        end = url.end()
-        if end < len(s) and s[end] == ")" and end > url.end(1):
-            out.append(s[emitted:open_at])
-            out.append(f'<a href="{s[url.start(1):end]}">{s[open_at + 1:close_at]}</a>')
-            emitted = scan = end + 1
-        elif end > url.end(1):
-            scan = max(scan, s.rfind("]", scan, end) + 1)
-    out.append(s[emitted:])
-    return "".join(out)
-
-
 def _md_to_email_html(text: str) -> str:
     """Render the compose markdown body to a SAFE HTML fragment for the email's
     text/html part. Everything is HTML-escaped FIRST (so a pasted <script> /
@@ -1596,7 +1557,7 @@ def _md_to_email_html(text: str) -> str:
         s = re.sub(r"~~([^~]+)~~", r"<del>\1</del>", s)
         s = re.sub(r"`([^`]+)`", r"<code>\1</code>", s)
         # links: text + http(s) url only (escape() already neutralised quotes)
-        s = _md_links_to_html(s)
+        s = re.sub(r"\[([^\]]+)\]\((https?://[^)\s]+)\)", r'<a href="\2">\1</a>', s)
         return s
 
     parts: list[str] = []
@@ -1815,13 +1776,60 @@ def setup_email_routes():
             return None
         return v[1]
 
+    # Stale-while-revalidate snapshot store: a last-good list response per key
+    # with NO TTL, so a list view can render instantly from a snapshot (or the
+    # durable index) and refresh in the background instead of blocking ~2-5 s on
+    # IMAP. Kept small and separate from the TTL cache so invalidation of the
+    # fresh cache never removes the fallback snapshot.
+    _LIST_STALE = {}
+
+    def _list_stale_get(key):
+        return _LIST_STALE.get(key)
+
+    def _list_stale_put(key, value):
+        _LIST_STALE[key] = value
+        if len(_LIST_STALE) > 96:
+            for k in list(_LIST_STALE.keys())[:-48]:
+                _LIST_STALE.pop(k, None)
+
+    _LIST_REFRESHING = set()
+
     def _list_cache_put(key, value):
         _LIST_CACHE[key] = (_time.monotonic() + _LIST_TTL, value)
+        # Also snapshot the last-good response for stale-while-revalidate.
+        _list_stale_put(key, value)
         # Cap size
         if len(_LIST_CACHE) > 64:
             for k in list(_LIST_CACHE.keys())[:-32]:
                 _LIST_CACHE.pop(k, None)
 
+    def _schedule_list_refresh(sync_args, cache_key, folder, account_id, owner):
+        """Refresh a list snapshot off the event loop, at most once per key.
+
+        Runs the blocking IMAP fetch in a daemon thread, then repopulates both
+        the TTL cache and the stale snapshot so the next list view is warm.
+        """
+        if cache_key in _LIST_REFRESHING:
+            return
+        _LIST_REFRESHING.add(cache_key)
+
+        def _run():
+            try:
+                refreshed = _list_emails_sync(*sync_args)
+                if refreshed and not refreshed.get("error"):
+                    _list_cache_put(cache_key, refreshed)
+                    try:
+                        _schedule_recent_email_warm(
+                            refreshed.get("emails") or [], folder, account_id, owner)
+                    except Exception:
+                        pass
+            except Exception as exc:  # pragma: no cover - background best effort
+                logger.debug("email list background refresh failed: %s", exc)
+            finally:
+                _LIST_REFRESHING.discard(cache_key)
+
+        _threading.Thread(target=_run, daemon=True, name="email-list-refresh").start()
+
     def _folder_cache_get(account_id, owner):
         key = (account_id or "", owner or "")
         v = _FOLDER_CACHE.get(key)
@@ -2848,6 +2856,46 @@ def setup_email_routes():
                         owner, account_id or "", folder, filter, limit, offset, elapsed_ms,
                     )
                 return cached
+        # Stale-while-revalidate: never block a plain list view on IMAP while
+        # we already hold a recent snapshot or a durable index. Serve it now
+        # with a `stale` marker and refresh in the background so the next view
+        # is warm. Blocking IMAP only remains for a genuine cold start with no
+        # snapshot and no indexed rows (e.g. a brand-new account/folder).
+        if not from_addr and not has_attachments and not (date_from or date_to):
+            snapshot = _list_stale_get(ck)
+            if snapshot is None:
+                try:
+                    indexed_emails, indexed_total, indexed_at = _email_index_list(
+                        owner, account_id, folder, filter, limit, offset, False,
+                    )
+                except Exception:
+                    indexed_emails, indexed_total, indexed_at = [], 0, None
+                if indexed_total:
+                    snapshot = {
+                        "emails": indexed_emails,
+                        "total": indexed_total,
+                        "folder": folder,
+                        "offset": offset,
+                        "sync": {
+                            "source": "index",
+                            "indexed": indexed_total,
+                            "updated_at": indexed_at,
+                        },
+                    }
+            if snapshot is not None:
+                payload = dict(snapshot)
+                payload["emails"] = list(payload.get("emails") or [])
+                _hide_unlinked_calendar_tags(payload["emails"])
+                sync_meta = dict(payload.get("sync") or {})
+                sync_meta["source"] = "cache_stale" if _list_stale_get(ck) is not None else "index"
+                sync_meta["stale"] = True
+                payload["sync"] = sync_meta
+                _schedule_list_refresh(
+                    (folder, limit, offset, filter, account_id, from_addr,
+                     bool(has_attachments), owner, True, date_from or "", date_to or ""),
+                    ck, folder, account_id, owner,
+                )
+                return payload
         result = await _asyncio.to_thread(
             _list_emails_sync, folder, limit, offset, filter, account_id, from_addr,
             bool(has_attachments), owner, manual_refresh, date_from or "", date_to or "",
@@ -3964,7 +4012,7 @@ def setup_email_routes():
             _row, att = fixture_att
             filename = str(att.get("filename") or f"attachment-{index}.txt")
             safe_name = re.sub(r"[^\w\s\-.]", "_", filename).strip() or f"attachment-{index}.txt"
-            target_dir = attachment_extract_dir(folder, uid, owner=owner, account_id=account_id)
+            target_dir = attachment_extract_dir(folder, uid)
             target_dir.mkdir(parents=True, exist_ok=True)
             filepath = target_dir / safe_name
             filepath.write_bytes(str(att.get("content") or "").encode("utf-8"))
@@ -3983,7 +4031,7 @@ def setup_email_routes():
             msg = email_mod.message_from_bytes(raw)
 
             # Extract to a per-email folder
-            target_dir = attachment_extract_dir(folder, uid, owner=owner, account_id=account_id)
+            target_dir = attachment_extract_dir(folder, uid)
             filepath = _extract_attachment_to_disk(msg, index, target_dir)
             if not filepath:
                 return {"error": f"Attachment index {index} not found"}
@@ -4015,7 +4063,7 @@ def setup_email_routes():
             if not attachments:
                 raise HTTPException(status_code=404, detail="No downloadable attachments")
 
-            target_dir = attachment_extract_dir(folder, uid, owner=owner, account_id=account_id)
+            target_dir = attachment_extract_dir(folder, uid)
             zip_buf = io.BytesIO()
             used_names: dict[str, int] = {}
             with zipfile.ZipFile(zip_buf, "w", compression=zipfile.ZIP_DEFLATED) as zf:
@@ -4155,7 +4203,7 @@ def setup_email_routes():
                                     att for att in _list_attachments_from_msg(msg)
                                     if not _is_likely_signature_image_attachment(att)
                                 ]
-                                target_dir = attachment_extract_dir(folder, uid, owner=owner, account_id=acct)
+                                target_dir = attachment_extract_dir(folder, uid)
                                 for att in attachments:
                                     idx = att.get("index")
                                     if idx is None:
@@ -4220,7 +4268,7 @@ def setup_email_routes():
                     continue
                 if not ct.lower().startswith("image/"):
                     raise HTTPException(status_code=415, detail="Content-ID is not an image")
-                target_dir = attachment_extract_dir(folder, uid, owner=owner, account_id=account_id)
+                target_dir = attachment_extract_dir(folder, uid)
                 filepath = _extract_attachment_to_disk(msg, idx, target_dir)
                 if not filepath:
                     raise HTTPException(status_code=404, detail="Inline image not found")
@@ -4258,7 +4306,7 @@ def setup_email_routes():
             raw = msg_data[0][1]
             msg = email_mod.message_from_bytes(raw)
 
-            target_dir = attachment_extract_dir(folder, uid, owner=owner, account_id=account_id)
+            target_dir = attachment_extract_dir(folder, uid)
             filepath = _extract_attachment_to_disk(msg, index, target_dir)
             if not filepath:
                 return {"error": f"Attachment index {index} not found"}
@@ -4586,9 +4634,7 @@ def setup_email_routes():
                 try:
                     content = filepath.read_text(encoding="utf-8", errors="replace")
                 except Exception as e:
-                    # OSError text includes the server-side extraction path.
-                    logger.warning("Failed to read text attachment %s: %s", base, e)
-                    return {"error": "Failed to read text file", "filename": base}
+                    return {"error": f"Failed to read text file: {e}", "filename": base}
                 doc_id = _create_markdown_doc(content, "Imported from email attachment")
                 return {"doc_id": doc_id, "filename": filepath.name}
 
@@ -4605,7 +4651,7 @@ def setup_email_routes():
             _row, att = fixture_att
             filename = str(att.get("filename") or f"attachment-{index}.txt")
             safe_name = re.sub(r"[^\w\s\-.]", "_", filename).strip() or f"attachment-{index}.txt"
-            target_dir = attachment_extract_dir(folder, uid, owner=owner, account_id=account_id)
+            target_dir = attachment_extract_dir(folder, uid)
             target_dir.mkdir(parents=True, exist_ok=True)
             filepath = target_dir / safe_name
             filepath.write_bytes(str(att.get("content") or "").encode("utf-8"))
@@ -4619,7 +4665,7 @@ def setup_email_routes():
             raw = msg_data[0][1]
             msg = email_mod.message_from_bytes(raw)
 
-            target_dir = attachment_extract_dir(folder, uid, owner=owner, account_id=account_id)
+            target_dir = attachment_extract_dir(folder, uid)
             filepath = _extract_attachment_to_disk(msg, index, target_dir)
             if not filepath:
                 return {"error": f"Attachment index {index} not found"}
@@ -5273,7 +5319,7 @@ def setup_email_routes():
                 return {"success": False, "error": "Email not found"}
             raw = msg_data[0][1]
             msg = email_mod.message_from_bytes(raw)
-            target_dir = attachment_extract_dir(folder, uid, owner=owner, account_id=account_id)
+            target_dir = attachment_extract_dir(folder, uid)
             filepath = _extract_attachment_to_disk(msg, index, target_dir)
             if not filepath:
                 return {"success": False, "error": f"Attachment index {index} not found"}
@@ -6290,7 +6336,7 @@ def setup_email_routes():
                     await queue.put({'type': 'result', **result})
                 task = asyncio.create_task(run())
                 try:
-                    while True:
+                    while not _shutdown.is_shutting_down():
                         item = await queue.get()
                         yield 'data: ' + json.dumps(item) + '\n\n'
                         if item.get('type') == 'result':
@@ -6980,158 +7026,6 @@ def setup_email_routes():
         finally:
             db.close()
 
-    def _test_mail_connections(body: dict, owner: str) -> dict:
-        """Blocking IMAP/SMTP connection test for /accounts/test.
-
-        Runs in the threadpool: each probe can block for its full socket
-        timeout, which on the event loop stalled every other request. The
-        connections go through the outbound mail address policy for `owner`
-        (the user who chose the hosts)."""
-        imap_result = {"ok": False}
-        smtp_result = None
-
-        imap_host = (body.get("imap_host") or "").strip()
-        imap_port, imap_port_err = _coerce_port(body.get("imap_port"), 993)
-        imap_user = (body.get("imap_user") or "").strip()
-        imap_pass = body.get("imap_password") or ""
-        imap_starttls = bool(body.get("imap_starttls"))
-        oauth_provider = body.get("oauth_provider") or ""
-
-        google_token = None
-        google_token_loaded = False
-        google_ssl_context = (
-            ssl.create_default_context()
-            if oauth_provider == "google"
-            else None
-        )
-
-        def _google_token():
-            nonlocal google_token, google_token_loaded
-            if not google_token_loaded:
-                google_token = _get_valid_google_token(body.get("account_id"), body)
-                google_token_loaded = True
-            if not google_token:
-                raise RuntimeError("Google OAuth token unavailable — reconnect the account")
-            return google_token
-
-        if imap_port_err:
-            imap_result = {"ok": False, "error": imap_port_err}
-        elif not (imap_host and imap_user and (imap_pass or oauth_provider == "google")):
-            imap_result = {"ok": False, "error": "Need IMAP host, username, and password"}
-        elif oauth_provider == "google" and _normalized_mail_host(imap_host) != _GOOGLE_OAUTH_IMAP_HOST:
-            imap_result = {"ok": False, "error": "Google OAuth IMAP requires imap.gmail.com"}
-        elif oauth_provider == "google" and not _google_oauth_imap_transport_allowed(imap_port, imap_starttls):
-            imap_result = {"ok": False, "error": "Google OAuth IMAP requires TLS on port 993 or STARTTLS on port 143"}
-        else:
-            # Connection mode resolution:
-            #   STARTTLS on  → plain IMAP4 + .starttls() (upgrade)
-            #   STARTTLS off + port 993 → IMAP4_SSL (implicit SSL, "IMAPS")
-            #   STARTTLS off + any other port → plain IMAP4 (no encryption)
-            # Without the last branch, local servers exposed on a non-993
-            # port (Dovecot on 31143, etc.) would always fail the SSL
-            # handshake because they're not actually wrapped in TLS.
-            try:
-                imap_kwargs = {
-                    "starttls": imap_starttls,
-                    "timeout": _IMAP_TIMEOUT_SECONDS,
-                    "owner": owner,
-                }
-                if google_ssl_context:
-                    imap_kwargs["ssl_context"] = google_ssl_context
-                conn = _open_imap_connection(
-                    imap_host,
-                    imap_port,
-                    **imap_kwargs,
-                )
-                try:
-                    if oauth_provider == "google":
-                        token = _google_token()
-                        conn.authenticate("XOAUTH2", lambda x: _xoauth2_bytes(imap_user, token))
-                    else:
-                        conn.login(imap_user, imap_pass)
-                    imap_result = {"ok": True}
-                finally:
-                    try: conn.logout()
-                    except Exception: pass
-            except Exception as e:
-                imap_result = {"ok": False, "error": _mail_connection_test_error("IMAP", imap_host, e)}
-
-        smtp_host = (body.get("smtp_host") or "").strip()
-        smtp_port, smtp_port_err = _coerce_port(body.get("smtp_port"), 465)
-        if smtp_host and smtp_port_err:
-            smtp_result = {"ok": False, "error": smtp_port_err}
-        elif oauth_provider == "google" and smtp_host and _normalized_mail_host(smtp_host) != _GOOGLE_OAUTH_SMTP_HOST:
-            smtp_result = {"ok": False, "error": "Google OAuth SMTP requires smtp.gmail.com"}
-        elif (
-            oauth_provider == "google"
-            and smtp_host
-            and not _google_oauth_smtp_transport_allowed(
-                smtp_port,
-                _smtp_security_mode({"smtp_security": body.get("smtp_security"), "smtp_port": smtp_port}),
-            )
-        ):
-            smtp_result = {"ok": False, "error": "Google OAuth SMTP requires TLS on port 465 or STARTTLS on port 587"}
-        elif smtp_host:
-            smtp_security = _smtp_security_mode({"smtp_security": body.get("smtp_security"), "smtp_port": smtp_port})
-            smtp_user = (body.get("smtp_user") or imap_user).strip()
-            smtp_pass = body.get("smtp_password") or imap_pass
-            smtp = None
-            try:
-                if smtp_security == "ssl":
-                    smtp_kwargs = (
-                        {"context": google_ssl_context}
-                        if google_ssl_context
-                        else {}
-                    )
-                    smtp = _PolicySMTP_SSL(
-                        smtp_host,
-                        smtp_port,
-                        timeout=10,
-                        block_private=_mail_private_blocked(owner),
-                        **smtp_kwargs,
-                    )
-                else:
-                    smtp = _PolicySMTP(smtp_host, smtp_port, timeout=10, block_private=_mail_private_blocked(owner))
-                    if smtp_security == "starttls":
-                        try:
-                            if google_ssl_context:
-                                smtp.starttls(context=google_ssl_context)
-                            else:
-                                smtp.starttls()
-                        except Exception:
-                            # STARTTLS failed before the auth cleanup block.
-                            # Close the still-open plaintext socket explicitly.
-                            try:
-                                smtp.close()
-                            except Exception:
-                                pass
-                            smtp = None
-                            raise
-                if oauth_provider == "google":
-                    token = _google_token()
-                    smtp.ehlo()
-                    smtp.auth("XOAUTH2", lambda challenge=None: _xoauth2_raw(smtp_user, token), initial_response_ok=True)
-                else:
-                    smtp.login(smtp_user, smtp_pass)
-                smtp_result = {"ok": True}
-            except Exception as e:
-                smtp_result = {"ok": False, "error": _mail_connection_test_error("SMTP", smtp_host, e)}
-            finally:
-                if smtp is not None:
-                    try:
-                        smtp.quit()
-                    except Exception:
-                        try:
-                            smtp.close()
-                        except Exception:
-                            pass
-
-        return {
-            "ok": imap_result["ok"] and (smtp_result is None or smtp_result["ok"]),
-            "imap": imap_result,
-            "smtp": smtp_result,
-        }
-
     @router.post("/accounts/test")
     async def test_account_config(req: Request, owner: str = Depends(require_user)):
         """Try to actually connect to the provided IMAP (and optionally SMTP)
@@ -7195,7 +7089,148 @@ def setup_email_routes():
             # inline test payloads select the OAuth branch or supply token data.
             body = {key: value for key, value in body.items() if key not in _SERVER_OWNED_OAUTH_FIELDS}
 
-        return await run_in_threadpool(_test_mail_connections, body, owner)
+        imap_result = {"ok": False}
+        smtp_result = None
+
+        imap_host = (body.get("imap_host") or "").strip()
+        imap_port, imap_port_err = _coerce_port(body.get("imap_port"), 993)
+        imap_user = (body.get("imap_user") or "").strip()
+        imap_pass = body.get("imap_password") or ""
+        imap_starttls = bool(body.get("imap_starttls"))
+        oauth_provider = body.get("oauth_provider") or ""
+
+        google_token = None
+        google_token_loaded = False
+        google_ssl_context = (
+            ssl.create_default_context()
+            if oauth_provider == "google"
+            else None
+        )
+
+        def _google_token():
+            nonlocal google_token, google_token_loaded
+            if not google_token_loaded:
+                google_token = _get_valid_google_token(body.get("account_id"), body)
+                google_token_loaded = True
+            if not google_token:
+                raise RuntimeError("Google OAuth token unavailable — reconnect the account")
+            return google_token
+
+        if imap_port_err:
+            imap_result = {"ok": False, "error": imap_port_err}
+        elif not (imap_host and imap_user and (imap_pass or oauth_provider == "google")):
+            imap_result = {"ok": False, "error": "Need IMAP host, username, and password"}
+        elif oauth_provider == "google" and _normalized_mail_host(imap_host) != _GOOGLE_OAUTH_IMAP_HOST:
+            imap_result = {"ok": False, "error": "Google OAuth IMAP requires imap.gmail.com"}
+        elif oauth_provider == "google" and not _google_oauth_imap_transport_allowed(imap_port, imap_starttls):
+            imap_result = {"ok": False, "error": "Google OAuth IMAP requires TLS on port 993 or STARTTLS on port 143"}
+        else:
+            # Connection mode resolution:
+            #   STARTTLS on  → plain IMAP4 + .starttls() (upgrade)
+            #   STARTTLS off + port 993 → IMAP4_SSL (implicit SSL, "IMAPS")
+            #   STARTTLS off + any other port → plain IMAP4 (no encryption)
+            # Without the last branch, local servers exposed on a non-993
+            # port (Dovecot on 31143, etc.) would always fail the SSL
+            # handshake because they're not actually wrapped in TLS.
+            try:
+                imap_kwargs = {
+                    "starttls": imap_starttls,
+                    "timeout": _IMAP_TIMEOUT_SECONDS,
+                }
+                if google_ssl_context:
+                    imap_kwargs["ssl_context"] = google_ssl_context
+                conn = _open_imap_connection(
+                    imap_host,
+                    imap_port,
+                    **imap_kwargs,
+                )
+                try:
+                    if oauth_provider == "google":
+                        token = _google_token()
+                        conn.authenticate("XOAUTH2", lambda x: _xoauth2_bytes(imap_user, token))
+                    else:
+                        conn.login(imap_user, imap_pass)
+                    imap_result = {"ok": True}
+                finally:
+                    try: conn.logout()
+                    except Exception: pass
+            except Exception as e:
+                imap_result = {"ok": False, "error": _friendly_email_auth_error("IMAP", imap_host, e)}
+
+        smtp_host = (body.get("smtp_host") or "").strip()
+        smtp_port, smtp_port_err = _coerce_port(body.get("smtp_port"), 465)
+        if smtp_host and smtp_port_err:
+            smtp_result = {"ok": False, "error": smtp_port_err}
+        elif oauth_provider == "google" and smtp_host and _normalized_mail_host(smtp_host) != _GOOGLE_OAUTH_SMTP_HOST:
+            smtp_result = {"ok": False, "error": "Google OAuth SMTP requires smtp.gmail.com"}
+        elif (
+            oauth_provider == "google"
+            and smtp_host
+            and not _google_oauth_smtp_transport_allowed(
+                smtp_port,
+                _smtp_security_mode({"smtp_security": body.get("smtp_security"), "smtp_port": smtp_port}),
+            )
+        ):
+            smtp_result = {"ok": False, "error": "Google OAuth SMTP requires TLS on port 465 or STARTTLS on port 587"}
+        elif smtp_host:
+            smtp_security = _smtp_security_mode({"smtp_security": body.get("smtp_security"), "smtp_port": smtp_port})
+            smtp_user = (body.get("smtp_user") or imap_user).strip()
+            smtp_pass = body.get("smtp_password") or imap_pass
+            smtp = None
+            try:
+                if smtp_security == "ssl":
+                    smtp_kwargs = (
+                        {"context": google_ssl_context}
+                        if google_ssl_context
+                        else {}
+                    )
+                    smtp = smtplib.SMTP_SSL(
+                        smtp_host,
+                        smtp_port,
+                        timeout=10,
+                        **smtp_kwargs,
+                    )
+                else:
+                    smtp = smtplib.SMTP(smtp_host, smtp_port, timeout=10)
+                    if smtp_security == "starttls":
+                        try:
+                            if google_ssl_context:
+                                smtp.starttls(context=google_ssl_context)
+                            else:
+                                smtp.starttls()
+                        except Exception:
+                            # STARTTLS failed before the auth cleanup block.
+                            # Close the still-open plaintext socket explicitly.
+                            try:
+                                smtp.close()
+                            except Exception:
+                                pass
+                            smtp = None
+                            raise
+                if oauth_provider == "google":
+                    token = _google_token()
+                    smtp.ehlo()
+                    smtp.auth("XOAUTH2", lambda challenge=None: _xoauth2_raw(smtp_user, token), initial_response_ok=True)
+                else:
+                    smtp.login(smtp_user, smtp_pass)
+                smtp_result = {"ok": True}
+            except Exception as e:
+                smtp_result = {"ok": False, "error": _friendly_email_auth_error("SMTP", smtp_host, e)}
+            finally:
+                if smtp is not None:
+                    try:
+                        smtp.quit()
+                    except Exception:
+                        try:
+                            smtp.close()
+                        except Exception:
+                            pass
+
+        return {
+            "ok": imap_result["ok"] and (smtp_result is None or smtp_result["ok"]),
+            "imap": imap_result,
+            "smtp": smtp_result,
+        }
 
     @router.post("/accounts/{account_id}/set-default")
     async def set_default_account(account_id: str, owner: str = Depends(require_user)):
diff --git a/routes/gallery/gallery_routes.py b/routes/gallery/gallery_routes.py
index 276ac90a5..3465fd8bb 100644
--- a/routes/gallery/gallery_routes.py
+++ b/routes/gallery/gallery_routes.py
@@ -1,14 +1,17 @@
 """Gallery routes — browsable library for photos and AI-generated images."""
 
 import os
+import asyncio
 import base64
+import gc
 import hashlib
 import io
 import logging
 import re
+import time
 import uuid
 from pathlib import Path
-from typing import Dict, Any, Optional
+from typing import Dict, Any, Optional, Tuple
 
 from fastapi import APIRouter, HTTPException, Query, Request
 
@@ -34,6 +37,241 @@ _SAM_STATE: Dict[str, Any] = {}
 _GROUNDING_STATE: Dict[str, Any] = {}
 
 
+def _rss_mb() -> float:
+    """Current process RSS in MB (from /proc; -1.0 when unavailable)."""
+    try:
+        with open("/proc/self/status", "r") as fh:
+            for line in fh:
+                if line.startswith("VmRSS:"):
+                    return round(int(line.split()[1]) / 1024.0, 1)
+    except Exception:
+        pass
+    return -1.0
+
+
+def _image_op_log_rss(op: str, phase: str) -> None:
+    logger.info("image-op %s %s rss_mb=%.1f", op, phase, _rss_mb())
+
+
+def _local_image_models_enabled() -> bool:
+    """Whether GB-scale local image models may be loaded IN-PROCESS.
+
+    Default OFF: loading rembg/SAM/OWL-ViT/Real-ESRGAN in the web process
+    routinely OOM-kills memory-constrained hosts. Enable with
+    ``ODYSSEUS_ALLOW_LOCAL_IMAGE_MODELS=1`` or point ``ODYSSEUS_IMAGE_OPS_BASE``
+    at a remote service that implements the same ``/api/image/*`` endpoints.
+    """
+    return os.getenv("ODYSSEUS_ALLOW_LOCAL_IMAGE_MODELS", "").strip().lower() in (
+        "1", "true", "yes", "on",
+    )
+
+
+def _remote_image_ops_base() -> str:
+    return (os.getenv("ODYSSEUS_IMAGE_OPS_BASE", "") or "").strip().rstrip("/")
+
+
+def _outpaint_timeout() -> float:
+    """Provider timeout for the outpaint/extend proxy.
+
+    Tall extensions can take up to ~330 s (the provider's own timeout is
+    900 s), so the proxy waits 900 s by default — otherwise a long extend is
+    cut off at the proxy. Override with ``ODYSSEUS_IMAGE_OUTPAINT_TIMEOUT``.
+    """
+    try:
+        return float(os.getenv("ODYSSEUS_IMAGE_OUTPAINT_TIMEOUT", "900") or 900)
+    except (TypeError, ValueError):
+        return 900.0
+
+
+def _unload_image_models() -> None:
+    """Drop lazily-loaded torch models so their RAM returns to the OS."""
+    if not _SAM_STATE and not _GROUNDING_STATE:
+        return
+    _SAM_STATE.clear()
+    _GROUNDING_STATE.clear()
+    try:
+        import torch  # type: ignore
+
+        if torch.cuda.is_available():
+            torch.cuda.empty_cache()
+    except Exception:
+        pass
+    gc.collect()
+    _image_op_log_rss("models", "unloaded")
+
+
+async def _route_heavy_image_op(path: str, body: dict, *, label: str):
+    """Proxy a heavy image op to the remote ops service when configured, else
+    run it in-process only when explicitly enabled.
+
+    Returns the remote JSON on success, or ``None`` to signal the caller should
+    run it in-process; raises HTTPException(503) with a clear message otherwise
+    so the app never loads a GB-scale model on a memory-constrained host.
+    """
+    base = _remote_image_ops_base()
+    if base:
+        _image_op_log_rss(label, f"proxy->{base}")
+        try:
+            import httpx
+
+            async with httpx.AsyncClient(timeout=300) as client:
+                resp = await client.post(base + path, json=body)
+            if resp.status_code == 200:
+                return resp.json()
+            logger.warning("image-op %s remote %s -> %s", label, path, resp.status_code)
+            raise HTTPException(
+                503,
+                f"{label} is temporarily unavailable (remote service returned {resp.status_code}).",
+            )
+        except HTTPException:
+            raise
+        except Exception as exc:
+            logger.warning("image-op %s remote %s failed: %s", label, path, exc)
+            raise HTTPException(
+                503,
+                f"{label} is temporarily unavailable (remote service unreachable).",
+            ) from exc
+    if _local_image_models_enabled():
+        return None
+    raise HTTPException(503, f"{label} is temporarily unavailable on this server.")
+
+
+def _xywh_to_xyxy(bbox):
+    """Convert a remote image-ops [x, y, w, h] bbox to this app's [x1,y1,x2,y2]."""
+    try:
+        x, y, w, h = (float(v) for v in bbox)
+        return [int(x), int(y), int(x + w), int(y + h)]
+    except Exception:
+        return bbox
+
+
+async def _remote_remove_background(body: dict):
+    """Proxy background removal to the remote ops service (seneca contract).
+
+    Endpoint: POST {base}/v1/images/remove-background (multipart: image,
+    optional hint_mask, model, return_mask). Returns {"image": <b64 RGBA PNG>}
+    to match this route's local response shape, or None when the caller should
+    run in-process (local models explicitly enabled); raises 503 otherwise.
+    """
+    base = _remote_image_ops_base()
+    if not base:
+        if _local_image_models_enabled():
+            return None
+        raise HTTPException(503, "Background removal is temporarily unavailable on this server.")
+    img_bytes = _b64_bytes(body.get("image"))
+    hint_bytes = None
+    if body.get("hint_mask"):
+        hint_bytes = _b64_bytes(body.get("hint_mask"), label="hint_mask")
+    _image_op_log_rss("remove-bg", f"proxy->{base}")
+    try:
+        import httpx
+
+        files = {"image": ("image.png", img_bytes, "image/png")}
+        if hint_bytes:
+            files["hint_mask"] = ("hint.png", hint_bytes, "image/png")
+        data = {"model": str(body.get("model") or ""), "return_mask": "true"}
+        async with httpx.AsyncClient(timeout=300) as client:
+            resp = await client.post(base + "/v1/images/remove-background", files=files, data=data)
+        if resp.status_code == 200:
+            payload = resp.json()
+            items = payload.get("data") or []
+            if not items or not items[0].get("b64_json"):
+                raise HTTPException(503, "Background removal is temporarily unavailable (remote returned no image).")
+            out = {"image": items[0]["b64_json"]}
+            if items[0].get("mask_b64"):
+                out["mask"] = items[0]["mask_b64"]
+            if items[0].get("bbox"):
+                out["bbox"] = items[0]["bbox"]
+            return out
+        raise HTTPException(
+            503, f"Background removal is temporarily unavailable (remote service returned {resp.status_code})."
+        )
+    except HTTPException:
+        raise
+    except Exception as exc:
+        logger.warning("image-op remove-bg remote failed: %s", exc)
+        raise HTTPException(503, "Background removal is temporarily unavailable (remote service unreachable).") from exc
+
+
+async def _remote_smart_mask(body: dict):
+    """Proxy SAM/grounding masking to the remote ops service (seneca contract).
+
+    Endpoint: POST {base}/v1/images/mask (multipart: image + one of prompt/box/
+    points). Returns {"mask": <b64 L PNG>, "bbox": [...], "model", "device"} to
+    match this route's local response shape, or None when the caller should run
+    in-process; raises 503 otherwise.
+    """
+    base = _remote_image_ops_base()
+    if not base:
+        if _local_image_models_enabled():
+            return None
+        raise HTTPException(503, "Smart mask is temporarily unavailable on this server.")
+    img_bytes = _b64_bytes(body.get("image"))
+    points = body.get("points") or []
+    box = body.get("box")
+    text = (body.get("text") or body.get("query") or "").strip()
+    if not points and not box and not text:
+        raise HTTPException(400, "Provide at least one point, box, or object text")
+    _image_op_log_rss("mask", f"proxy->{base}")
+    try:
+        import httpx
+
+        data: Dict[str, Any] = {}
+        if text:
+            data["prompt"] = text
+        if box:
+            try:
+                x1, y1, x2, y2 = (float(v) for v in box)
+                data["box"] = ",".join(str(int(v)) for v in (x1, y1, x2 - x1, y2 - y1))
+            except Exception as exc:
+                raise HTTPException(400, "Box must be [x1, y1, x2, y2]") from exc
+        if points:
+            import json as _json
+
+            data["points"] = _json.dumps(
+                [[float(p["x"]), float(p["y"]), int(p.get("label", 1))] for p in points]
+            )
+        if body.get("multimask") is not None:
+            data["multimask"] = str(bool(body.get("multimask"))).lower()
+        if body.get("dilate_px") is not None:
+            data["dilate_px"] = str(int(body.get("dilate_px")))
+        files = {"image": ("image.png", img_bytes, "image/png")}
+        async with httpx.AsyncClient(timeout=300) as client:
+            resp = await client.post(base + "/v1/images/mask", files=files, data=data)
+        if resp.status_code == 200:
+            payload = resp.json()
+            masks = payload.get("masks") or []
+            candidates = [m for m in masks if m.get("b64_json")]
+            if not candidates:
+                # Empty selection is a normal 200 outcome (never a 400): the
+                # editor shows a "nothing selected" message and changes nothing.
+                return {
+                    "mask": None,
+                    "bbox": None,
+                    "masks": [],
+                    "model": payload.get("model") or "sam+grounding",
+                    "device": payload.get("device", ""),
+                    "error": "Nothing selected for that selection.",
+                }
+            best = max(candidates, key=lambda m: float(m.get("score") or 0.0))
+            return {
+                "mask": best["b64_json"],
+                "bbox": _xywh_to_xyxy(best.get("bbox")),
+                "label": best.get("label"),
+                "masks": masks,
+                "model": payload.get("model") or "sam+grounding",
+                "device": payload.get("device", ""),
+            }
+        raise HTTPException(
+            503, f"Smart mask is temporarily unavailable (remote service returned {resp.status_code})."
+        )
+    except HTTPException:
+        raise
+    except Exception as exc:
+        logger.warning("image-op mask remote failed: %s", exc)
+        raise HTTPException(503, "Smart mask is temporarily unavailable (remote service unreachable).") from exc
+
+
 def _b64_to_pil_image(image_b64: str, *, mode: str = "RGBA"):
     if not image_b64:
         raise HTTPException(400, "Missing image")
@@ -50,12 +288,79 @@ def _b64_to_pil_image(image_b64: str, *, mode: str = "RGBA"):
         raise HTTPException(400, "Invalid image") from exc
 
 
+def _b64_bytes(value: str, *, label: str = "image") -> bytes:
+    """Decode raw base64 OR a ``data:image/...;base64,`` URL to bytes.
+
+    The image-edit tools post data URLs, while the browser posts raw base64,
+    so every decode site must accept both.
+    """
+    if not value:
+        raise HTTPException(400, f"Missing {label}")
+    text = str(value)
+    if "," in text and text.split(",", 1)[0].startswith("data:"):
+        text = text.split(",", 1)[1]
+    try:
+        return base64.b64decode(text)
+    except Exception as exc:
+        raise HTTPException(400, f"Invalid {label}") from exc
+
+
 def _pil_image_to_b64(img, *, fmt: str = "PNG") -> str:
     buf = io.BytesIO()
     img.save(buf, format=fmt)
     return base64.b64encode(buf.getvalue()).decode("ascii")
 
 
+def _prepare_local_edit(src_b64, mask_b64, max_side):
+    """Decode/normalize/cap an edit's inputs to PNG bytes at a model-friendly size.
+
+    CPU-bound (a 4000x3000 decode+resize is ~0.2 s); run it via a thread off the
+    event loop. Returns (source_png_bytes, mask_png_bytes, model_w, model_h, orig_size).
+    """
+    from PIL import Image
+
+    img_bytes = _b64_bytes(src_b64)
+    source_png = Image.open(io.BytesIO(img_bytes)).convert("RGBA")
+    if mask_b64:
+        mask_bytes = _b64_bytes(mask_b64, label="mask")
+        mask_png = Image.open(io.BytesIO(mask_bytes)).convert("L")
+    else:
+        mask_png = Image.new("L", source_png.size, 255)
+    orig_size = source_png.size
+    if max(orig_size) > max_side:
+        scale = float(max_side) / max(orig_size)
+        model_w = max(16, int(round(orig_size[0] * scale / 16.0)) * 16)
+        model_h = max(16, int(round(orig_size[1] * scale / 16.0)) * 16)
+    else:
+        model_w, model_h = orig_size
+    if (model_w, model_h) != orig_size:
+        source_work = source_png.resize((model_w, model_h), Image.LANCZOS)
+        mask_work = mask_png.resize((model_w, model_h), Image.LANCZOS)
+    else:
+        source_work, mask_work = source_png, mask_png
+    src_buf = io.BytesIO()
+    source_work.save(src_buf, format="PNG")
+    mask_buf = io.BytesIO()
+    mask_work.save(mask_buf, format="PNG")
+    return src_buf.getvalue(), mask_buf.getvalue(), model_w, model_h, orig_size
+
+
+def _restore_local_b64(raw_b64, orig_size, model_size):
+    """Resize a provider result b64 back to the original dimensions (CPU-bound)."""
+    if tuple(model_size) == tuple(orig_size):
+        return raw_b64
+    from PIL import Image
+
+    try:
+        im = Image.open(io.BytesIO(base64.b64decode(raw_b64))).convert("RGBA")
+        im = im.resize(tuple(orig_size), Image.LANCZOS)
+        ob = io.BytesIO()
+        im.save(ob, format="PNG")
+        return base64.b64encode(ob.getvalue()).decode("ascii")
+    except Exception:
+        return raw_b64
+
+
 def _load_sam_backend():
     model_id = os.getenv("ODYSSEUS_SAM_MODEL", "facebook/sam-vit-base")
     cached = _SAM_STATE.get(model_id)
@@ -301,7 +606,61 @@ def _first_visible_image_endpoint(db, owner: str | None):
         for ep in endpoints:
             if getattr(ep, "owner", None) == owner:
                 return ep
-    return endpoints[0] if endpoints else None
+    if endpoints:
+        return endpoints[0]
+    # Fallback: the image model may live on a *mixed* endpoint (model_type !=
+    # "image"), e.g. qwen-image-edit / gpt-image-1 on a shared OpenAI-compatible
+    # gateway or a diffusion server registered as "chat". Chat image generation
+    # already resolves its model by name across every enabled endpoint, so the
+    # editor must find the same model here instead of reporting "no endpoint".
+    return _first_mixed_image_endpoint(db, owner)
+
+
+def _first_mixed_image_endpoint(db, owner: str | None):
+    """Best-effort image endpoint when no image-only endpoint is registered.
+
+    Returns an enabled, owner-visible endpoint whose configured model list
+    includes an image-generation model, preferring the admin's configured
+    ``image_model`` when it is one of them.
+    """
+    import json
+    from src.auth_helpers import owner_filter
+    from src.image_model_ids import looks_like_image_generation_model
+
+    preferred = ""
+    try:
+        from src.settings import load_settings
+        preferred = str((load_settings() or {}).get("image_model") or "").strip()
+    except Exception:
+        preferred = ""
+
+    query = owner_filter(
+        db.query(ModelEndpoint).filter(ModelEndpoint.is_enabled == True),  # noqa: E712
+        ModelEndpoint,
+        owner,
+    )
+    fallback = None
+    for ep in query.all():
+        if getattr(ep, "model_type", None) == "image":
+            continue
+        models = set()
+        for field in ("cached_models", "pinned_models"):
+            try:
+                values = getattr(ep, field, None) or []
+                values = json.loads(values) if isinstance(values, str) else values
+                models.update(v for v in values if isinstance(v, str))
+            except (TypeError, ValueError):
+                pass
+        matches = {m for m in models if looks_like_image_generation_model(m)}
+        if not matches:
+            continue
+        if preferred and preferred in matches:
+            return ep
+        if owner and getattr(ep, "owner", None) == owner:
+            return ep
+        if fallback is None:
+            fallback = ep
+    return fallback
 
 
 def _visible_image_endpoint_for_base(db, base: str, owner: str | None, model: str = ""):
@@ -360,6 +719,92 @@ async def _fetch_result_image_b64(url: str) -> Optional[str]:
     return None
 
 
+def _resolve_image_op_endpoint(db, owner, requested_base: str, chosen_model: str = "") -> Tuple[str, Optional[str]]:
+    """Resolve the provider base (with /v1) + api_key for a self-hosted image op.
+
+    Mirrors inpaint_proxy: a client-supplied base must map to a registered,
+    owner-visible image endpoint (no direct use of request-body URLs).
+    """
+    if requested_base:
+        ep = _visible_image_endpoint_for_base(db, requested_base, owner, chosen_model)
+        if not ep:
+            raise HTTPException(403, "Choose a registered image endpoint")
+    else:
+        ep = _first_visible_image_endpoint(db, owner)
+        if not ep:
+            raise HTTPException(400, "No image generation endpoint configured. Serve a diffusion model via Cookbook first.")
+    base = ep.base_url.rstrip("/")
+    if not base.endswith("/v1"):
+        base += "/v1"
+    return base, ep.api_key
+
+
+async def _forward_seneca_image_op(
+    base: str,
+    api_key: Optional[str],
+    provider_path: str,
+    image_bytes: bytes,
+    fields: Dict[str, str],
+    *,
+    label: str,
+    timeout: float = 300.0,
+) -> Dict[str, Any]:
+    """POST a single-image multipart op to the provider and return ``{image}``.
+
+    The provider returns OpenAI-style ``{data:[{b64_json|url}]}`` or a raw
+    ``{image}``. ``request_id`` in ``fields`` keys the provider's progress route.
+    """
+    import httpx
+
+    url = base.rstrip("/") + provider_path
+    headers = {"Authorization": f"Bearer {api_key}"} if api_key else {}
+    files = {"image": ("source.png", image_bytes, "image/png")}
+    _t0 = time.perf_counter()
+    try:
+        async with httpx.AsyncClient(timeout=timeout) as client:
+            r = await client.post(url, data=fields, files=files, headers=headers)
+        _provider_ms = (time.perf_counter() - _t0) * 1000.0
+    except httpx.TimeoutException:
+        raise HTTPException(504, f"{label} timed out ({int(timeout)}s)")
+    except Exception as exc:
+        logger.warning("%s provider call failed: %s", label, exc)
+        raise HTTPException(503, f"{label} is temporarily unavailable (remote service unreachable).")
+    if r.status_code != 200:
+        logger.warning("%s provider status %s", label, r.status_code)
+        detail = f"{label} failed"
+        try:
+            j = r.json()
+            if isinstance(j, dict) and (j.get("error") or j.get("detail")):
+                detail = str(j.get("error") or j.get("detail"))[:200]
+        except Exception:
+            pass
+        raise HTTPException(r.status_code if r.status_code in (400, 404, 422) else 502, detail)
+    result = r.json()
+    raw_b64: Optional[str] = None
+    used_model = ""
+    if isinstance(result, dict):
+        used_model = str(result.get("model") or "")
+        data = result.get("data")
+        if isinstance(data, list) and data:
+            item = data[0] or {}
+            raw_b64 = item.get("b64_json") or None
+            if not raw_b64 and item.get("url"):
+                raw_b64 = await _fetch_result_image_b64(item["url"])
+        if not raw_b64 and result.get("image"):
+            raw_b64 = result["image"]
+    if not raw_b64:
+        raise HTTPException(502, "Image endpoint returned no image")
+    logger.info(
+        "%s timing model_ms=%.1f total_ms=%.1f request_id=%s",
+        label, _provider_ms,
+        (time.perf_counter() - _t0) * 1000.0, fields.get("request_id") or "-",
+    )
+    payload: Dict[str, Any] = {"image": raw_b64}
+    if used_model:
+        payload["model"] = used_model
+    return payload
+
+
 def setup_gallery_routes() -> APIRouter:
     router = APIRouter(tags=["gallery"])
 
@@ -602,7 +1047,7 @@ def setup_gallery_routes() -> APIRouter:
 
         # Use img2img endpoint if available, otherwise upscale via canvas on client
         try:
-            async with httpx.AsyncClient(timeout=120) as client:
+            async with httpx.AsyncClient(timeout=300) as client:
                 resp = await client.post(f"{base_url}/images/upscale", json={
                     "image": b64, "scale": scale,
                 })
@@ -645,7 +1090,7 @@ def setup_gallery_routes() -> APIRouter:
             base_url += "/v1"
 
         try:
-            async with httpx.AsyncClient(timeout=180) as client:
+            async with httpx.AsyncClient(timeout=300) as client:
                 resp = await client.post(f"{base_url}/images/generations", json={
                     "prompt": prompt,
                     "image": b64,
@@ -1291,6 +1736,10 @@ def setup_gallery_routes() -> APIRouter:
             if not ok:
                 raise HTTPException(400, f"Rejected endpoint URL: {reason}")
         chosen_model = (body.pop("_model", "") or "").strip()
+        # Optional client-supplied id so GET /api/image/edit-progress can poll the
+        # provider's step progress for this op. Ignored by providers that do not
+        # implement the progress contract.
+        progress_request_id = (body.get("request_id") or "").strip()
         api_key = None
         if not requested_base:
             db = SessionLocal()
@@ -1338,8 +1787,10 @@ def setup_gallery_routes() -> APIRouter:
                 raise HTTPException(500, "Pillow not installed on server")
 
             try:
-                img_bytes = base64.b64decode(body["image"])
-                mask_bytes = base64.b64decode(body["mask"])
+                img_bytes = _b64_bytes(body.get("image"))
+                if not body.get("mask"):
+                    raise HTTPException(400, "A mask is required for OpenAI-compatible image edits")
+                mask_bytes = _b64_bytes(body.get("mask"), label="mask")
                 source_png = Image.open(io.BytesIO(img_bytes)).convert("RGBA")
                 mask_png = Image.open(io.BytesIO(mask_bytes)).convert("L")  # luminance
                 # Build OpenAI mask: RGBA where alpha=255 means keep, 0 means regenerate.
@@ -1390,7 +1841,11 @@ def setup_gallery_routes() -> APIRouter:
             }
             headers = {"Authorization": f"Bearer {api_key}"}
             try:
-                async with httpx.AsyncClient(timeout=120) as client:
+                logger.debug(
+                    "inpaint_proxy provider edit -> prompt=%r model=%r size=%r base=%s",
+                    body.get("prompt", ""), oa_model, size, base,
+                )
+                async with httpx.AsyncClient(timeout=300) as client:
                     if is_openrouter:
                         # Reference-based editing, then composite locally so
                         # pixels outside the user's mask remain unchanged.
@@ -1410,7 +1865,16 @@ def setup_gallery_routes() -> APIRouter:
                         r = await client.post(_join_checked_gallery_endpoint(base, "/images/edits"), headers=headers, data=data, files=files)
                     if r.status_code != 200:
                         logger.error("inpaint_proxy OpenAI edit: status %s", r.status_code)
-                        raise HTTPException(r.status_code, "OpenAI edit failed")
+                        _detail = "OpenAI edit failed"
+                        try:
+                            _j = r.json()
+                            if isinstance(_j, dict):
+                                _detail = _j.get("error") or _j.get("detail") or _detail
+                                if isinstance(_detail, dict):
+                                    _detail = _detail.get("message") or _detail
+                        except Exception:
+                            pass
+                        raise HTTPException(r.status_code, f"{_detail} (provider HTTP {r.status_code})")
                     result = r.json()
                     raw_b64 = None
                     if result.get("data"):
@@ -1441,13 +1905,16 @@ def setup_gallery_routes() -> APIRouter:
                         blended = Image.composite(generated, source_png, mask_png)
                         out_buf = io.BytesIO()
                         blended.save(out_buf, format="PNG")
-                        return {"image": base64.b64encode(out_buf.getvalue()).decode()}
+                        return {"image": base64.b64encode(out_buf.getvalue()).decode(), "model": oa_model}
                     except Exception as comp_err:
                         # Never return a full-image edit when masking fails.
                         logger.warning(f"Inpaint compose failed: {comp_err}")
                         raise HTTPException(502, "Could not apply the edit within the selected region")
             except httpx.TimeoutException:
-                raise HTTPException(504, "OpenAI inpaint timed out (120s)")
+                raise HTTPException(504, "OpenAI inpaint timed out (300s)")
+            except httpx.TransportError as exc:
+                logger.warning("inpaint_proxy: OpenAI endpoint unreachable: %s", exc)
+                raise HTTPException(502, f"Image server unreachable ({base}): {type(exc).__name__}")
 
         # Self-hosted diffusion server path. Newer Odysseus image
         # wrappers expose the OpenAI-compatible /v1/images/edits
@@ -1459,45 +1926,96 @@ def setup_gallery_routes() -> APIRouter:
             # supports multiple models per process. Harmless if ignored.
             if chosen_model:
                 body["model"] = chosen_model
-            async with httpx.AsyncClient(timeout=240) as client:
+            async with httpx.AsyncClient(timeout=300) as client:
+                _t0 = time.perf_counter()
+                _restore_ms = [0.0]
                 try:
                     import base64, io
                     from PIL import Image
 
-                    img_bytes = base64.b64decode(body["image"])
-                    mask_bytes = base64.b64decode(body["mask"])
-                    # Normalize both inputs to PNG bytes. Local MLX and
-                    # Diffusers wrappers expect white mask pixels to mean
-                    # "edit this region", which matches the editor's mask.
-                    source_png = Image.open(io.BytesIO(img_bytes)).convert("RGBA")
-                    mask_png = Image.open(io.BytesIO(mask_bytes)).convert("L")
-                    src_buf = io.BytesIO()
-                    source_png.save(src_buf, format="PNG")
-                    mask_buf = io.BytesIO()
-                    mask_png.save(mask_buf, format="PNG")
+                    # Decode/resize/encode off the event loop: a 4000x3000 input
+                    # costs ~0.2 s of CPU that would otherwise block every other
+                    # request (and stack under concurrent edits).
+                    _max_side = int(os.getenv("ODYSSEUS_IMAGE_EDIT_MAX_SIDE", "768") or 768)
+                    _src_png, _mask_png, _model_w, _model_h, _orig_size = await asyncio.to_thread(
+                        _prepare_local_edit, body.get("image"), body.get("mask"), _max_side
+                    )
                     files = {
-                        "image": ("source.png", src_buf.getvalue(), "image/png"),
-                        "mask": ("mask.png", mask_buf.getvalue(), "image/png"),
+                        "image": ("source.png", _src_png, "image/png"),
+                        "mask": ("mask.png", _mask_png, "image/png"),
                     }
                     data = {
                         "model": chosen_model or body.get("model") or "",
                         "prompt": body.get("prompt", ""),
-                        "size": f"{int(body.get('width') or source_png.width)}x{int(body.get('height') or source_png.height)}",
+                        "size": f"{_model_w}x{_model_h}",
                         "n": "1",
                     }
+                    if progress_request_id:
+                        data["request_id"] = progress_request_id
+                    # Let the caller's step budget through up to a cap (quality
+                    # edits such as removal/background-replacement/expand pass 8
+                    # on purpose); only fall back to a moderate default when no
+                    # count is requested. The size cap above is what keeps the
+                    # op responsive.
+                    _max_steps = int(os.getenv("ODYSSEUS_IMAGE_EDIT_MAX_STEPS", "8") or 8)
+                    if body.get("steps"):
+                        try:
+                            data["steps"] = str(min(max(1, int(body["steps"])), _max_steps))
+                        except (TypeError, ValueError):
+                            data["steps"] = "4"
+                    else:
+                        data["steps"] = "4"
+
+                    async def _restore_b64(_raw: str) -> str:
+                        """Resize a provider PNG b64 back to the original size (off-loop)."""
+                        if (_model_w, _model_h) == _orig_size:
+                            return _raw
+                        _rs = time.perf_counter()
+                        try:
+                            return await asyncio.to_thread(
+                                _restore_local_b64, _raw, _orig_size, (_model_w, _model_h)
+                            )
+                        finally:
+                            _restore_ms[0] += (time.perf_counter() - _rs) * 1000.0
+                    logger.debug(
+                        "inpaint_proxy self-hosted /images/edits -> prompt=%r model=%r "
+                        "size=%r steps=%r endpoint=%s",
+                        data.get("prompt"), data.get("model"), data.get("size"),
+                        data.get("steps"), base,
+                    )
+                    _prep_ms = (time.perf_counter() - _t0) * 1000.0
+
+                    def _finish(_payload: Dict[str, Any]) -> Dict[str, Any]:
+                        # model_ms is the provider round-trip (its own queue +
+                        # diffusion time); prep_ms is our decode/resize; restore_ms
+                        # is resizing the result back. total_ms is the whole op.
+                        logger.info(
+                            "inpaint-proxy timing prep_ms=%.1f model_ms=%.1f restore_ms=%.1f "
+                            "total_ms=%.1f size=%s steps=%s model=%s request_id=%s",
+                            _prep_ms, _provider_ms[0], _restore_ms[0],
+                            (time.perf_counter() - _t0) * 1000.0,
+                            data.get("size"), data.get("steps"), data.get("model"),
+                            progress_request_id or "-",
+                        )
+                        return _payload
+
+                    _t_post = time.perf_counter()
                     r = await client.post(_join_checked_gallery_endpoint(base, "/images/edits"), data=data, files=files)
+                    _provider_ms = [(time.perf_counter() - _t_post) * 1000.0]
                     if r.status_code == 200:
                         result = r.json()
+                        _used_model = result.get("model") if isinstance(result, dict) else None
+                        _used_model = _used_model or data.get("model") or ""
                         if isinstance(result, dict) and result.get("data"):
                             item = result["data"][0]
                             if item.get("b64_json"):
-                                return {"image": item["b64_json"]}
+                                return _finish({"image": await _restore_b64(item["b64_json"]), "model": _used_model})
                             if item.get("url"):
                                 raw_b64 = await _fetch_result_image_b64(item["url"])
                                 if raw_b64:
-                                    return {"image": raw_b64}
+                                    return _finish({"image": await _restore_b64(raw_b64), "model": _used_model})
                         if isinstance(result, dict) and result.get("image"):
-                            return {"image": result["image"]}
+                            return _finish({"image": await _restore_b64(result["image"]), "model": _used_model})
                         raise HTTPException(502, "Image edit endpoint returned no image")
                     if r.status_code not in (404, 405):
                         logger.warning("inpaint_proxy self-hosted edits: status %s", r.status_code)
@@ -1528,16 +2046,158 @@ def setup_gallery_routes() -> APIRouter:
                 r = await client.post(_join_checked_gallery_endpoint(base, "/images/inpaint"), json=body)
                 if r.status_code != 200:
                     logger.error("inpaint_proxy diffusion: status %s", r.status_code)
-                    raise HTTPException(r.status_code, "Inpaint request failed")
+                    detail = "Inpaint request failed"
+                    try:
+                        j = r.json()
+                        if isinstance(j, dict):
+                            detail = j.get("detail") or j.get("error") or detail
+                    except Exception:
+                        pass
+                    raise HTTPException(r.status_code, f"{detail} (provider HTTP {r.status_code})")
                 return r.json()
         except httpx.TimeoutException:
             raise HTTPException(504, "Inpaint request timed out (240s)")
+        except httpx.TransportError as exc:
+            logger.warning("inpaint_proxy: image endpoint unreachable: %s", exc)
+            raise HTTPException(502, f"Image server unreachable ({base}): {type(exc).__name__}")
         except HTTPException:
             raise
         except Exception:
             logger.exception("inpaint_proxy: request failed")
             raise HTTPException(502, "Inpaint request failed")
 
+    async def _resolve_and_decode(body: Dict[str, Any], user):
+        """Shared prep for the seneca single-image ops: validate endpoint + decode.
+
+        Returns (base, api_key, image_bytes, chosen_model). The base64 decode
+        runs off the event loop (large images).
+        """
+        requested_base = (body.pop("_endpoint", "") or "").rstrip("/")
+        if requested_base:
+            from src.url_safety import check_outbound_url
+            ok, reason = check_outbound_url(
+                requested_base,
+                block_private=os.getenv("IMAGE_BLOCK_PRIVATE_IPS", "false").lower() == "true",
+            )
+            if not ok:
+                raise HTTPException(400, f"Rejected endpoint URL: {reason}")
+        chosen_model = (body.pop("_model", "") or "").strip()
+        db = SessionLocal()
+        try:
+            base, api_key = _resolve_image_op_endpoint(db, user, requested_base, chosen_model)
+        finally:
+            db.close()
+        image_bytes = await asyncio.to_thread(_b64_bytes, body.get("image"))
+        return base, api_key, image_bytes, chosen_model
+
+    @router.post("/api/image/replace-background")
+    async def replace_background(request: Request):
+        """Proxy seneca's subject-mask background replacement (~/v1/images/replace-background)."""
+        user = require_privilege(request, "can_generate_images")
+        body = await request.json()
+        base, api_key, image_bytes, chosen_model = await _resolve_and_decode(body, user)
+        fields: Dict[str, str] = {
+            "prompt": str(body.get("prompt") or ""),
+            "steps": str(body.get("steps") or 4),
+        }
+        if body.get("request_id"):
+            fields["request_id"] = str(body["request_id"]).strip()
+        if body.get("harmonise") is not None:
+            fields["harmonise"] = "true" if body.get("harmonise") else "false"
+        if body.get("shadow") is not None:
+            fields["shadow"] = "true" if body.get("shadow") else "false"
+        if chosen_model:
+            fields["model"] = chosen_model
+        return await _forward_seneca_image_op(
+            base, api_key, "/images/replace-background", image_bytes, fields,
+            label="replace-background",
+        )
+
+    @router.post("/api/image/outpaint")
+    async def outpaint(request: Request):
+        """Proxy seneca's canvas outpaint/extend (~/v1/images/outpaint, alias /extend)."""
+        user = require_privilege(request, "can_generate_images")
+        body = await request.json()
+        base, api_key, image_bytes, chosen_model = await _resolve_and_decode(body, user)
+        fields: Dict[str, str] = {
+            "prompt": str(body.get("prompt") or ""),
+            "steps": str(body.get("steps") or 4),
+        }
+        for key in ("ratio", "size", "context"):
+            if body.get(key) is not None and str(body.get(key)) != "":
+                fields[key] = str(body[key])
+        if body.get("request_id"):
+            fields["request_id"] = str(body["request_id"]).strip()
+        if chosen_model:
+            fields["model"] = chosen_model
+        return await _forward_seneca_image_op(
+            base, api_key, "/images/outpaint", image_bytes, fields,
+            label="outpaint", timeout=_outpaint_timeout(),
+        )
+
+    @router.post("/api/image/extend")
+    async def outpaint_extend(request: Request):
+        """Alias of /api/image/outpaint (the provider exposes /outpaint as /extend too)."""
+        return await outpaint(request)
+
+    @router.get("/api/image/edit-progress")
+    async def edit_progress(request: Request):
+        """Poll a running image edit's provider-side step progress.
+
+        Contract v1 (image-op progress): the provider exposes
+        ``GET /v1/images/progress/{request_id}`` -> ``{stage, step, steps,
+        eta_s, progress}``. This proxy resolves the configured image endpoint
+        (owner-scoped) and returns that JSON, or ``{"available": false}`` when
+        the provider has no progress route yet, so the client can keep an
+        indeterminate bar without breaking.
+        """
+        import httpx
+        user = require_privilege(request, "can_generate_images")
+        request_id = (request.query_params.get("request_id") or "").strip()
+        if not request_id:
+            raise HTTPException(400, "Missing request_id")
+        # request_id is spliced into the outbound URL, so it must be a safe token
+        # (no path separators/host chars). The base itself is a DB-validated row.
+        if not re.fullmatch(r"[A-Za-z0-9_.-]{1,80}", request_id):
+            raise HTTPException(400, "Invalid request_id")
+        requested_base = (request.query_params.get("base") or "").strip().rstrip("/")
+        endpoint_id = (request.query_params.get("endpoint_id") or "").strip()
+        db = SessionLocal()
+        try:
+            ep = None
+            if endpoint_id:
+                ep = owner_filter(
+                    db.query(ModelEndpoint).filter(ModelEndpoint.id == endpoint_id),
+                    ModelEndpoint, user,
+                ).first()
+            if ep is None and requested_base:
+                ep = _visible_image_endpoint_for_base(db, requested_base, user)
+            if ep is None:
+                ep = _first_visible_image_endpoint(db, user)
+            if ep is None:
+                return {"available": False, "reason": "no image endpoint configured"}
+            base = ep.base_url.rstrip("/")
+        finally:
+            db.close()
+        if not base.endswith("/v1"):
+            base += "/v1"
+        # Dynamic path segment (validated token above), so not routed through
+        # _join_checked_gallery_endpoint's exact-match whitelist.
+        url = f"{base}/images/progress/{request_id}"
+        try:
+            async with httpx.AsyncClient(timeout=10) as client:
+                r = await client.get(url)
+            if r.status_code == 200:
+                data = r.json()
+                if isinstance(data, dict):
+                    data.setdefault("available", True)
+                    return data
+                return {"available": True, "progress": data}
+            return {"available": False, "status": r.status_code}
+        except Exception as exc:
+            logger.debug("edit-progress poll failed: %s", exc)
+            return {"available": False, "reason": "provider unreachable"}
+
     # ---- POST /api/image/harmonize — proper img2img call ----
     # Earlier version routed through inpaint with a full-white mask, but
     # most backends interpret "100% mask coverage" as "regenerate from
@@ -1689,10 +2349,10 @@ def setup_gallery_routes() -> APIRouter:
             headers["Authorization"] = f"Bearer {api_key}"
 
         last_err = None
-        # Cold-start SDXL inpaint can take 60-90s on first request (loading
-        # weights to GPU). 240s gives headroom for both that and a full
-        # 1024×1024 inference pass on slower setups.
-        async with httpx.AsyncClient(timeout=240) as client:
+        # Cold-start image servers can take 90-110s for a full pass (and
+        # 60-90s more on first request while weights load to GPU). 300s gives
+        # headroom for both on slower setups.
+        async with httpx.AsyncClient(timeout=300) as client:
             for path, kind, payload in candidates:
                 _effective_base = base_root if path.startswith("/sdapi") else base
                 target = _join_checked_gallery_endpoint(_effective_base, path)
@@ -1755,7 +2415,7 @@ def setup_gallery_routes() -> APIRouter:
         from PIL import Image, ImageFilter
         import base64, io
 
-        img_bytes = base64.b64decode(image_b64)
+        img_bytes = _b64_bytes(image_b64)
         img = Image.open(io.BytesIO(img_bytes)).convert("RGB")
 
         # Unsharp mask: radius=2, percent=amount*200, threshold=3
@@ -1776,6 +2436,9 @@ def setup_gallery_routes() -> APIRouter:
         image_b64 = body.get("image")
         if not image_b64:
             raise HTTPException(400, "No image provided")
+        _proxied = await _route_heavy_image_op("/api/image/denoise", body, label="AI denoise")
+        if _proxied is not None:
+            return _proxied
         try:
             strength = float(body.get("strength", 0.5))
         except Exception:
@@ -1788,7 +2451,7 @@ def setup_gallery_routes() -> APIRouter:
         except ImportError:
             raise HTTPException(500, "Server missing a required dependency")
         # Decode source image (RGB; Real-ESRGAN doesn't preserve alpha).
-        img_bytes = base64.b64decode(image_b64)
+        img_bytes = _b64_bytes(image_b64)
         src = Image.open(io.BytesIO(img_bytes)).convert("RGB")
         try:
             patch_realesrgan_torchvision_compat()
@@ -1827,6 +2490,9 @@ def setup_gallery_routes() -> APIRouter:
         image_b64 = body.get("image")
         if not image_b64:
             raise HTTPException(400, "No image provided")
+        _proxied = await _route_heavy_image_op("/api/image/upscale-local", body, label="AI upscale")
+        if _proxied is not None:
+            return _proxied
         try:
             scale = int(body.get("scale", 2))
         except Exception:
@@ -1838,7 +2504,7 @@ def setup_gallery_routes() -> APIRouter:
             import numpy as np
         except ImportError:
             raise HTTPException(500, "Server missing a required dependency")
-        img_bytes = base64.b64decode(image_b64)
+        img_bytes = _b64_bytes(image_b64)
         src = Image.open(io.BytesIO(img_bytes)).convert("RGB")
         try:
             patch_realesrgan_torchvision_compat()
@@ -1865,6 +2531,68 @@ def setup_gallery_routes() -> APIRouter:
             logger.warning("AI upscale failed", exc_info=True)
             return {"error": "AI upscale failed"}
 
+    # ---- POST /api/image/generate ----
+    @router.post("/api/image/generate")
+    async def generate_image(request: Request):
+        """Text-to-image generation for the editor's Quick Edit 'Image' mode.
+
+        Generates a brand-new image from a prompt using the admin-configured
+        image model, returned as base64 so the client can drop it in as a layer.
+        """
+        import json as _json
+        user = require_privilege(request, "can_generate_images")
+        try:
+            body = await request.json()
+        except Exception:
+            body = {}
+        prompt = str((body or {}).get("prompt") or "").strip()
+        if not prompt:
+            raise HTTPException(400, "A prompt is required")
+        try:
+            width = int((body or {}).get("width") or 0)
+            height = int((body or {}).get("height") or 0)
+        except (TypeError, ValueError):
+            width = height = 0
+        if height > width:
+            size = "1024x1536"
+        elif width > height:
+            size = "1536x1024"
+        else:
+            size = "1024x1024"
+        try:
+            from src.ai_interaction import do_generate_image
+        except Exception:
+            raise HTTPException(502, "Image generation is unavailable")
+        content = _json.dumps({"prompt": prompt, "size": size})
+        result = await do_generate_image(content, owner=user, incognito=True)
+        if not isinstance(result, dict) or result.get("error"):
+            msg = (result.get("error") if isinstance(result, dict) else None) or "Image generation failed"
+            low = str(msg).lower()
+            # Plain-language status codes the editor maps to fixed messages:
+            #   503 -> generation is switched off on the server
+            #   502 -> the image server could not be reached (or failed)
+            if "disabled" in low or "switched off" in low or "not enabled" in low:
+                raise HTTPException(503, "Image generation is switched off on the server at the moment.")
+            if "timed out" in low or "timeout" in low:
+                raise HTTPException(504, f"Image server timed out: {msg}")
+            if "connection" in low or "connect" in low or "unreachable" in low:
+                raise HTTPException(502, f"Image server unreachable: {msg}")
+            # A configured image model that cannot be resolved means its endpoint
+            # did not answer, i.e. the image server is down, not a bad prompt.
+            if "no endpoint found with image model" in low:
+                raise HTTPException(502, f"Image server unreachable: {msg}")
+            raise HTTPException(502, msg)
+        image_url = result.get("image_url") or ""
+        b64 = image_url.split(",", 1)[1] if image_url.startswith("data:") else image_url
+        if not b64:
+            raise HTTPException(502, "Image generation returned no image")
+        return {
+            "image": b64,
+            "prompt": prompt,
+            "model": result.get("image_model"),
+            "size": result.get("image_size") or size,
+        }
+
     # ---- POST /api/image/remove-bg ----
     @router.post("/api/image/mask")
     async def smart_mask(request: Request):
@@ -1876,6 +2604,9 @@ def setup_gallery_routes() -> APIRouter:
         """
         require_privilege(request, "can_generate_images")
         body = await request.json()
+        _proxied = await _remote_smart_mask(body)
+        if _proxied is not None:
+            return _proxied
         image = _b64_to_pil_image(body.get("image") or "", mode="RGB")
         points = body.get("points") or []
         box = body.get("box")
@@ -1889,6 +2620,7 @@ def setup_gallery_routes() -> APIRouter:
         if not points and not box:
             raise HTTPException(400, "Provide at least one point, box, or object text")
 
+        _image_op_log_rss("mask", "start")
         backend = _load_sam_backend()
         torch = backend["torch"]
         processor = backend["processor"]
@@ -1985,6 +2717,8 @@ def setup_gallery_routes() -> APIRouter:
             }
             if grounded:
                 result["grounding"] = grounded
+            _image_op_log_rss("mask", "end")
+            _unload_image_models()
             return result
         except HTTPException:
             raise
@@ -2010,11 +2744,14 @@ def setup_gallery_routes() -> APIRouter:
         body = await request.json()
         image_b64 = body.get("image")
         hint_b64 = body.get("hint_mask")
+        _proxied = await _remote_remove_background(body)
+        if _proxied is not None:
+            return _proxied
 
         from PIL import Image
         import base64, io
 
-        img_bytes = base64.b64decode(image_b64)
+        img_bytes = _b64_bytes(image_b64)
         img = Image.open(io.BytesIO(img_bytes)).convert("RGBA")
         W, H = img.size
 
@@ -2022,7 +2759,7 @@ def setup_gallery_routes() -> APIRouter:
         bbox = None
         if hint_b64:
             try:
-                hint_bytes = base64.b64decode(hint_b64)
+                hint_bytes = _b64_bytes(hint_b64, label="hint_mask")
                 hint = Image.open(io.BytesIO(hint_bytes)).convert("L")
                 # Resize the hint to match if dimensions disagree
                 if hint.size != img.size:
@@ -2046,6 +2783,7 @@ def setup_gallery_routes() -> APIRouter:
         else:
             crop = img
 
+        _image_op_log_rss("remove-bg", "start")
         try:
             from rembg import remove
             from starlette.concurrency import run_in_threadpool
@@ -2061,6 +2799,9 @@ def setup_gallery_routes() -> APIRouter:
                 cut = tmp
             except Exception:
                 return {"error": "No background removal model available. Install rembg: pip install rembg"}
+        finally:
+            _image_op_log_rss("remove-bg", "end")
+            _unload_image_models()
 
         # Compose the cropped result back into a full-size transparent canvas.
         if bbox:
@@ -2100,11 +2841,13 @@ def setup_gallery_routes() -> APIRouter:
         from PIL import Image, ImageFilter, ImageEnhance
         import numpy as np
 
-        img_bytes = base64.b64decode(image_b64)
+        img_bytes = _b64_bytes(image_b64)
         img = Image.open(io.BytesIO(img_bytes)).convert("RGB")
 
         # Try GFPGAN first (AI face restoration)
         try:
+            if not _local_image_models_enabled():
+                raise ImportError("local image models disabled")
             from gfpgan import GFPGANer
             import cv2
 
diff --git a/routes/hwfit_routes.py b/routes/hwfit_routes.py
index c101ae78c..799b937d2 100644
--- a/routes/hwfit_routes.py
+++ b/routes/hwfit_routes.py
@@ -5,9 +5,8 @@ import shlex
 import subprocess
 from copy import deepcopy
 
-from fastapi import APIRouter, Depends, HTTPException
+from fastapi import APIRouter, HTTPException
 
-from core.middleware import require_admin
 from core.platform_compat import run_ssh_command
 from routes._validators import validate_remote_host, validate_ssh_port
 
@@ -199,11 +198,7 @@ def _inspect_model_path(model_path: str, host: str = "", ssh_port: str = "") ->
 
 
 def setup_hwfit_routes():
-    # Admin-gated like the Cookbook routes this backs (/api/cookbook/gpus does
-    # the same SSH host probing): `host`/`ssh_port` make the server SSH out with
-    # its own key to any syntactically valid host, and `model_path` probes the
-    # host filesystem. Single-user mode and internal tool calls still pass.
-    router = APIRouter(prefix="/api/hwfit", tags=["hwfit"], dependencies=[Depends(require_admin)])
+    router = APIRouter(prefix="/api/hwfit", tags=["hwfit"])
 
     @router.get("/system")
     def get_system(host: str = "", ssh_port: str = "", platform: str = "", fresh: bool = False):
@@ -223,7 +218,7 @@ def setup_hwfit_routes():
         fresh=true bypasses the hardware-detection cache."""
         from services.hwfit.hardware import detect_system
         from services.hwfit.fit import rank_models
-        from services.hwfit.models import get_models, refresh_dynamic_catalogs
+        from services.hwfit.models import get_models, model_catalog_path, refresh_dynamic_catalogs
         host, ssh_port = _validate_detection_target(host, ssh_port)
         system = deepcopy(detect_system(host=host, ssh_port=ssh_port, platform=platform, fresh=fresh))
         if system.get("error"):
@@ -238,8 +233,7 @@ def setup_hwfit_routes():
             return {
                 "system": system,
                 "models": [],
-                "error": "Model catalog is empty. Use Rescan in Cookbook while online to populate runtime model data; offline recommendations require a previously populated cache.",
-                **({"catalog_refresh": catalog_refresh} if catalog_refresh is not None else {}),
+                "error": f"Model catalog missing or empty: {model_catalog_path()}",
             }
 
         if ignore_detected_gpu:
diff --git a/routes/model_routes.py b/routes/model_routes.py
index 3466d4b9b..9d490de69 100644
--- a/routes/model_routes.py
+++ b/routes/model_routes.py
@@ -472,7 +472,7 @@ def _truthy(value: str | None) -> bool:
 
 _ENDPOINT_KINDS = {"auto", "local", "api", "proxy"}
 _REFRESH_MODES = {"auto", "manual", "disabled"}
-_MODEL_TOOL_MODES = {"none", "compact", "full"}
+_MODEL_TOOL_MODES = {"none", "compact", "full", "spec"}
 _MODEL_TOOL_MODE_ALIASES = {
     "regular": "full",
     "odysseus_compact": "compact",
@@ -552,10 +552,10 @@ def _endpoint_refresh_timeout(ep: Any, category: str) -> float:
         val = 0
     if val > 0:
         return float(max(1, min(60, val)))
-    # llama.cpp and other local OpenAI-compatible servers can block briefly
-    # while warming/loading. A 2s local timeout makes working endpoints flicker
-    # offline before /v1/models is ready.
-    return 10.0 if category == "local" else 2.0
+    # Keep the background refresh short so a single dead endpoint cannot stall
+    # the model picker. A timed-out refresh never clears a non-empty model
+    # cache, so a briefly-warming local server is simply retried next round.
+    return 2.0
 
 
 def _manual_refresh_timeout(ep: Any, category: str, requested: Any = None) -> float:
@@ -1510,6 +1510,9 @@ def setup_model_routes(model_discovery):
     _refresh_inflight = {"v": False, "done": None}  # coarse single-flight guard
     _REFRESH_FAILURE_BASE = 300.0
     _REFRESH_FAILURE_MAX = 3600.0
+    # Even a user-triggered refresh must not re-probe an endpoint that just
+    # failed/timed out on every click; keep a short cooldown.
+    _REFRESH_FAILURE_MIN = 60.0
 
     def _refresh_key(base: str, api_key: Optional[str], provider_auth_id: Optional[str] = None) -> str:
         # Session-backed endpoints carry no static key; include their auth id
@@ -1557,14 +1560,20 @@ def setup_model_routes(model_discovery):
         if mode in ("manual", "disabled") and not force:
             return False, info
         fails = int(state.get("fail_count") or 0)
-        if fails and not force:
+        if fails:
             last_failure = float(state.get("last_failure") or 0.0)
             empty_local = (
                 not cached
                 and category == "local"
                 and str(getattr(ep, "id", "") or "").startswith("local-")
             )
-            if now - last_failure < _failure_delay(fails, empty_local=empty_local):
+            delay = _failure_delay(fails, empty_local=empty_local)
+            if force:
+                # A user-triggered refresh gets a short cooldown instead of the
+                # long background backoff, but still skips a just-failed
+                # endpoint so repeated clicks cannot stall the picker.
+                delay = min(delay, _REFRESH_FAILURE_MIN)
+            if now - last_failure < delay:
                 return False, info
         if cached and not force:
             interval = _endpoint_refresh_interval(ep, category)
@@ -3055,4 +3064,10 @@ def setup_model_routes(model_discovery):
 
     router._should_refresh_endpoint = _should_refresh_endpoint
     router._search_endpoint_catalog = search_endpoint_catalog
+    # Exposed for tests: the in-memory backoff state, its key function, and the
+    # background refresh driver (probes endpoints in parallel with the short
+    # per-endpoint timeout).
+    router._refresh_state = _refresh_state
+    router._refresh_key = _refresh_key
+    router._refresh_caches_bg = _refresh_caches_bg
     return router
diff --git a/src/activity.py b/src/activity.py
new file mode 100644
index 000000000..92c4098e5
--- /dev/null
+++ b/src/activity.py
@@ -0,0 +1,61 @@
+"""In-flight activity counters (heavy image ops) for safe restarts/observability.
+
+A deploy restart kills any in-flight long image op (a diffusion edit is 60-120 s),
+so the operator needs to know whether the process is busy before issuing
+``systemctl --user restart``. These counters are process-local and cheap.
+"""
+from __future__ import annotations
+
+import threading
+import time
+from contextlib import contextmanager
+from typing import Dict
+
+_lock = threading.Lock()
+_image_ops = 0
+_image_ops_by_name: Dict[str, int] = {}
+_started_at = time.time()
+
+
+def begin_image_op(name: str = "image") -> None:
+    global _image_ops
+    with _lock:
+        _image_ops += 1
+        _image_ops_by_name[name] = _image_ops_by_name.get(name, 0) + 1
+
+
+def end_image_op(name: str = "image") -> None:
+    global _image_ops
+    with _lock:
+        _image_ops = max(0, _image_ops - 1)
+        if name in _image_ops_by_name:
+            _image_ops_by_name[name] -= 1
+            if _image_ops_by_name[name] <= 0:
+                _image_ops_by_name.pop(name, None)
+
+
+@contextmanager
+def image_op(name: str = "image"):
+    begin_image_op(name)
+    try:
+        yield
+    finally:
+        end_image_op(name)
+
+
+def activity() -> Dict[str, object]:
+    with _lock:
+        return {
+            "image_ops": _image_ops,
+            "image_ops_by_name": dict(_image_ops_by_name),
+            "uptime_s": round(time.time() - _started_at, 1),
+        }
+
+
+def heavy_image_ops_active() -> int:
+    with _lock:
+        return _image_ops
+
+
+def busy() -> bool:
+    return heavy_image_ops_active() > 0
diff --git a/src/agent_tools/editor_tools.py b/src/agent_tools/editor_tools.py
new file mode 100644
index 000000000..d1fa4176e
--- /dev/null
+++ b/src/agent_tools/editor_tools.py
@@ -0,0 +1,646 @@
+"""In-process agent tools for the scoped ``photo_editor`` capability family.
+
+These handlers run as the logged-in owner and drive the image editor over the
+owner-scoped in-process bridge (``/api/editor/bridge/*``) plus the app's
+existing image transforms (``/api/image/*``). They are only offered to the
+model when the ``photo_editor`` family is active (the Quick Edit popup or an
+explicit photo-edit chat turn), never in the general tool list.
+
+Loopback calls carry the internal token and impersonate ``owner`` (middleware
+app.py), so the editor bridge resolves the same ``owner:session`` scope the
+browser subscriber uses.
+"""
+from __future__ import annotations
+
+import base64
+import hashlib
+import io
+import json
+import logging
+import re
+import time
+import uuid
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+import httpx
+
+from src.tools._common import _INTERNAL_BASE, _internal_headers
+
+logger = logging.getLogger(__name__)
+
+
+def _provider_message() -> str:
+    try:
+        from src.ai_interaction import IMAGE_PROVIDER_REQUIRED_MESSAGE
+
+        return IMAGE_PROVIDER_REQUIRED_MESSAGE
+    except Exception:
+        return (
+            "Removing/adding objects needs an image generation provider; enable one "
+            "in Settings > Models."
+        )
+
+
+def _provider_available(owner: Optional[str]) -> bool:
+    try:
+        from src.ai_interaction import image_editing_provider_available
+
+        return bool(image_editing_provider_available(owner))
+    except Exception:
+        return True
+
+# Local diffusion/image servers can take 90-110s per image (8 steps) and
+# longer on a cold start; the previous 120s default timed out mid-generation.
+_EDITOR_TIMEOUT = 300.0
+# A mask covering less than this fraction of the image cannot drive a useful
+# regional inpaint (tiny figures, empty SAM output): fall back to grounding or
+# whole-image instruction mode instead.
+_MIN_MASK_FRACTION = 0.002
+_AI_OPS = {
+    "remove-bg": "/api/image/remove-bg",
+    "upscale": "/api/image/upscale-local",
+    "denoise": "/api/image/denoise",
+    "enhance-face": "/api/image/enhance-face",
+    "inpaint": "/api/image/inpaint",
+    "generative": "/api/image/inpaint",
+}
+_PLACE_OP = "layers.placeImage"
+
+
+def _parse(content: Any) -> Dict[str, Any]:
+    raw = content if isinstance(content, str) else json.dumps(content or {})
+    try:
+        parsed = json.loads(raw) if raw.strip() else {}
+    except (ValueError, TypeError):
+        parsed = {}
+    return parsed if isinstance(parsed, dict) else {}
+
+
+def _session(args: Dict[str, Any], ctx: Dict[str, Any]) -> str:
+    return str(args.get("session") or args.get("editor_session") or ctx.get("session_id") or "default")
+
+
+async def _post(path: str, payload: Dict[str, Any], owner: Optional[str], timeout: float = _EDITOR_TIMEOUT) -> Dict[str, Any]:
+    headers = {**_internal_headers(owner), "Content-Type": "application/json"}
+    async with httpx.AsyncClient(timeout=timeout) as client:
+        resp = await client.post(f"{_INTERNAL_BASE}{path}", json=payload, headers=headers)
+        resp.raise_for_status()
+        try:
+            return resp.json()
+        except ValueError:
+            return {"raw": resp.text}
+
+
+def _as_data_url(value: Any) -> Optional[str]:
+    if not isinstance(value, str) or not value:
+        return None
+    if value.startswith("data:"):
+        return value
+    if value.startswith("/"):
+        return None
+    return f"data:image/png;base64,{value}"
+
+
+def _data_url_bytes(data_url: str) -> bytes:
+    _, _, b64 = data_url.partition(",")
+    return base64.b64decode(b64)
+
+
+def _persist_png(image_bytes: bytes, owner: Optional[str], session_id: Optional[str], prompt: str, model: str) -> Dict[str, Any]:
+    """Save an edited/generated PNG and return {image_id, image_url, image_size}."""
+    from core.database import GalleryImage, SessionLocal
+    from src.constants import GENERATED_IMAGES_DIR
+
+    db = SessionLocal()
+    try:
+        root = Path(GENERATED_IMAGES_DIR).resolve()
+        root.mkdir(parents=True, exist_ok=True)
+        filename = f"{uuid.uuid4().hex[:12]}.png"
+        (root / filename).write_bytes(image_bytes)
+        new_id = str(uuid.uuid4())
+        width = height = 0
+        try:
+            from PIL import Image
+
+            with Image.open(io.BytesIO(image_bytes)) as img:
+                width, height = img.size
+        except Exception:
+            pass
+        size = f"{width}x{height}" if width and height else ""
+        # The editor bridge uses an owner-scoped session id (e.g. "pewds:3")
+        # that is not a chat-sessions row. GalleryImage.session_id is a FK to
+        # sessions.id, so drop an unknown id instead of raising IntegrityError.
+        if session_id:
+            from core.database import Session as _ChatSession
+
+            try:
+                known = db.query(_ChatSession.id).filter(_ChatSession.id == session_id).first()
+            except Exception:
+                known = None
+            if known is None:
+                session_id = None
+        derived = GalleryImage(
+            id=new_id,
+            filename=filename,
+            prompt=prompt or None,
+            caption=None,
+            model=model,
+            size=size or None,
+            quality=None,
+            tags=None,
+            ai_tags=None,
+            session_id=session_id,
+            album_id=None,
+            owner=owner,
+            file_hash=hashlib.sha256(image_bytes).hexdigest(),
+            file_size=len(image_bytes),
+            width=width or None,
+            height=height or None,
+        )
+        db.add(derived)
+        db.commit()
+        return {"image_id": new_id, "image_url": f"/api/generated-image/{filename}", "image_size": size or None}
+    except Exception:
+        db.rollback()
+        raise
+    finally:
+        db.close()
+
+
+async def _place_layer(data_url: str, name: str, owner: Optional[str], session: str, *, masked: bool = False, blend: str = "normal", opacity: float = 100.0, mode: Optional[str] = None) -> bool:
+    params: Dict[str, Any] = {
+        "dataUrl": data_url,
+        "name": name,
+        "masked": bool(masked),
+        "blend": blend or "normal",
+        "opacity": opacity,
+    }
+    # Forward the edit mode so the client can build a difference mask for
+    # instruction-mode results: the whole image was regenerated under an
+    # instruction prompt, so untouched pixels must stay pixel-identical (the
+    # client keeps only the changed region) instead of the new layer overwriting
+    # the entire canvas. Omit the keys entirely when no mode is given so the
+    # client keeps its current behavior (e.g. generate_image must not diff-mask).
+    if mode:
+        params["mode"] = mode
+        params["differenceMask"] = mode == "instruction"
+        if mode == "instruction":
+            # Exclude a thin edge band from the client difference mask: full-frame
+            # regenerations can shift pixels along the border.
+            params["edgeExcludePx"] = 3
+    payload = {
+        "session": session,
+        "op": _PLACE_OP,
+        "params": params,
+        "wait": True,
+        "timeout": 60,
+    }
+    try:
+        data = await _post("/api/editor/bridge/command", payload, owner, timeout=90)
+        return data.get("ok") is not False
+    except Exception as exc:  # pragma: no cover - defensive
+        logger.warning("editor layer placement failed: %s", exc)
+        return False
+
+
+async def _fetch_selection_mask(owner: Optional[str], session: str) -> Optional[str]:
+    """Return the editor's current selection as a data-URL mask, or None.
+
+    Generative ops (inpaint/generative) need a mask; the planner/judge may not
+    have supplied one, so fall back to whatever is selected in the editor.
+    """
+    payload = {
+        "session": session,
+        "op": "selection.exportMask",
+        "params": {},
+        "wait": True,
+        "timeout": 30,
+    }
+    try:
+        data = await _post("/api/editor/bridge/command", payload, owner, timeout=45)
+    except Exception as exc:  # pragma: no cover - defensive
+        logger.warning("editor selection mask fetch failed: %s", exc)
+        return None
+    result = data.get("result") if isinstance(data, dict) else None
+    if isinstance(result, dict):
+        return _as_data_url(result.get("mask"))
+    return None
+
+
+def _mask_white_fraction(data_url: Optional[str]) -> float:
+    """Fraction of a grayscale mask that is selected (white, >=128)."""
+    if not data_url:
+        return 0.0
+    try:
+        from PIL import Image as _PILImage
+
+        with _PILImage.open(io.BytesIO(_data_url_bytes(data_url))).convert("L") as im:
+            total = im.width * im.height
+            if not total:
+                return 0.0
+            hist = im.histogram()
+            return sum(hist[128:]) / total
+    except Exception:
+        return 0.0
+
+
+def _image_is_blank(data_url: str) -> bool:
+    """True when a result has an alpha channel that is essentially transparent."""
+    try:
+        from PIL import Image as _PILImage
+
+        with _PILImage.open(io.BytesIO(_data_url_bytes(data_url))) as im:
+            if im.mode not in ("RGBA", "LA") and "transparency" not in im.info:
+                return False
+            alpha = im.convert("RGBA").getchannel("A")
+            hist = alpha.histogram()
+            total = sum(hist)
+            return total > 0 and (sum(hist[1:]) / total) < 0.001
+    except Exception:
+        return False
+
+
+def _rect_mask_data_url(image_data_url: str, box: List[float], *, pad_frac: float = 0.15) -> Optional[str]:
+    """Build a rectangular mask data URL from a [x1,y1,x2,y2] box, dilated.
+
+    Used when the grounding detector finds an object but SAM returns an empty
+    mask (tiny figures): a dilated box guarantees a usable region.
+    """
+    try:
+        from PIL import Image as _PILImage, ImageDraw
+
+        with _PILImage.open(io.BytesIO(_data_url_bytes(image_data_url))) as im:
+            w, h = im.size
+        x1, y1, x2, y2 = (float(v) for v in box)
+        bw, bh = x2 - x1, y2 - y1
+        x1, y1 = max(0.0, x1 - bw * pad_frac), max(0.0, y1 - bh * pad_frac)
+        x2, y2 = min(float(w), x2 + bw * pad_frac), min(float(h), y2 + bh * pad_frac)
+        mask = _PILImage.new("L", (w, h), 0)
+        ImageDraw.Draw(mask).rectangle([x1, y1, x2, y2], fill=255)
+        buf = io.BytesIO()
+        mask.save(buf, "PNG")
+        return "data:image/png;base64," + base64.b64encode(buf.getvalue()).decode()
+    except Exception:
+        return None
+
+
+async def _ground_box(owner: Optional[str], image_data_url: str, label: str) -> Optional[List[float]]:
+    """Use the in-app grounding detector (OWL-ViT via /api/image/mask) for a box."""
+    try:
+        data = await _post("/api/image/mask", {"image": image_data_url, "text": label}, owner, timeout=90)
+    except Exception as exc:  # pragma: no cover - defensive
+        logger.warning("editor grounding box failed: %s", exc)
+        return None
+    box = data.get("bbox") if isinstance(data, dict) else None
+    if isinstance(box, (list, tuple)) and len(box) == 4:
+        try:
+            return [float(v) for v in box]
+        except Exception:
+            return None
+    return None
+
+
+def _ensure_keep_clause(text: str) -> str:
+    """Append a keep-the-subject clause when the prompt lacks one."""
+    body = str(text or "").strip()
+    if not body:
+        return body
+    if re.search(r"\b(keep|preserve|leave|unchanged|identical|same)\b", body, re.I):
+        return body
+    return body.rstrip(". ") + ". Keep the main subject and everything else in the image exactly the same."
+
+
+def _mask_label(args: Dict[str, Any], prompt: str) -> str:
+    """Best-effort object noun for grounding a regional removal."""
+    label = str(args.get("label") or args.get("object") or "").strip()
+    if label:
+        return label
+    m = re.search(
+        r"\b(?:remove|delete|erase|eliminate|get\s+rid\s+of|take\s+out)\s+(?:the\s+|a\s+|an\s+)?"
+        r"([a-z][a-z \-]{1,30}?)(?:\s+(?:on|in|at|from|to|near|behind|beside|by)\b|[.,;!?]|$)",
+        prompt or "",
+        re.I,
+    )
+    if m:
+        noun = m.group(1).strip().lower()
+        if noun and noun not in {"background", "bg"}:
+            return noun
+    for noun in ("person", "people", "man", "woman", "car", "dog", "sign", "logo"):
+        if re.search(rf"\b{re.escape(noun)}\b", prompt or "", re.I):
+            return "person" if noun in {"person", "people", "man", "woman"} else noun
+    return "object"
+
+
+class PlanEditTool:
+    """Plan an image edit as ordered editor operations (no side effects)."""
+
+    async def execute(self, content: Any, ctx: Dict[str, Any]):
+        args = _parse(content)
+        prompt = str(args.get("prompt") or "").strip()
+        if not prompt:
+            return "plan_edit: invalid", {"error": "plan_edit needs a non-empty `prompt`.", "exit_code": 1}
+        state = args.get("state") if isinstance(args.get("state"), dict) else {}
+        try:
+            data = await _post(
+                "/api/editor/plan",
+                {"prompt": prompt, "state": state, "mode": "plan", "session": _session(args, ctx)},
+                ctx.get("owner"),
+            )
+        except Exception as exc:
+            return "plan_edit: error", {"error": f"plan_edit failed: {exc}", "exit_code": 1}
+        steps = data.get("steps") or []
+        reply = str(data.get("reply") or "")
+        return f"plan_edit: {len(steps)} step(s)", {
+            "output": reply or f"Planned {len(steps)} editor step(s).",
+            "reply": reply,
+            "planner": data.get("planner"),
+            "steps": steps,
+            "exit_code": 0,
+        }
+
+
+class RunEditorCommandTool:
+    """Run a single validated editor op in the browser via the owner bridge."""
+
+    async def execute(self, content: Any, ctx: Dict[str, Any]):
+        args = _parse(content)
+        op = str(args.get("op") or "").strip()
+        if not op:
+            return "run_editor_command: invalid", {"error": "run_editor_command needs `op`.", "exit_code": 1}
+        params = args.get("params") if isinstance(args.get("params"), dict) else {}
+        payload = {
+            "session": _session(args, ctx),
+            "op": op,
+            "params": params,
+            "wait": bool(args.get("wait", True)),
+            "timeout": float(args.get("timeout") or 60),
+        }
+        try:
+            data = await _post("/api/editor/bridge/command", payload, ctx.get("owner"))
+        except Exception as exc:
+            return f"run_editor_command: {op}", {"error": f"run_editor_command failed: {exc}", "exit_code": 1}
+        ok = data.get("ok")
+        result = data.get("result")
+        summary = json.dumps({"ok": ok, "error": data.get("error"), "result": result}, ensure_ascii=False)
+        return f"run_editor_command: {op}", {
+            "output": summary[:4000],
+            "result": result,
+            "screenshot": data.get("screenshot"),
+            "ok": ok,
+            "exit_code": 0 if ok is not False else 1,
+        }
+
+
+class GetEditorScreenshotTool:
+    """Capture the current editor canvas as a data URL."""
+
+    async def execute(self, content: Any, ctx: Dict[str, Any]):
+        args = _parse(content)
+        payload = {
+            "session": _session(args, ctx),
+            "op": "screenshot",
+            "params": {},
+            "wait": True,
+            "timeout": float(args.get("timeout") or 30),
+        }
+        try:
+            data = await _post("/api/editor/bridge/command", payload, ctx.get("owner"), timeout=45)
+        except Exception as exc:
+            return "get_editor_screenshot: error", {"error": f"get_editor_screenshot failed: {exc}", "exit_code": 1}
+        result = data.get("result") if isinstance(data.get("result"), dict) else {}
+        shot = data.get("screenshot") or result.get("dataUrl")
+        if not shot:
+            return "get_editor_screenshot: unavailable", {
+                "error": "No editor screenshot was returned (is the editor open?).",
+                "exit_code": 1,
+            }
+        return "get_editor_screenshot", {"output": "Captured the editor canvas.", "screenshot": shot, "exit_code": 0}
+
+
+class AiEditImageTool:
+    """Apply an AI image transform (remove-bg/upscale/denoise/enhance/inpaint)."""
+
+    async def execute(self, content: Any, ctx: Dict[str, Any]):
+        args = _parse(content)
+        _t = {"start": time.perf_counter()}
+        op = str(args.get("op") or "").strip().lower()
+        if op not in _AI_OPS:
+            return "ai_edit_image: invalid", {
+                "error": f"ai_edit_image `op` must be one of {sorted(_AI_OPS)}.",
+                "exit_code": 1,
+            }
+        owner = ctx.get("owner")
+        if op in ("inpaint", "generative") and not _provider_available(owner):
+            return "ai_edit_image: provider required", {
+                "error": _provider_message(),
+                "failure_kind": "image_provider_unavailable",
+                "needs_provider": True,
+                "exit_code": 1,
+            }
+        session = _session(args, ctx)
+        image = _as_data_url(args.get("image"))
+        if image is None and isinstance(args.get("image"), str) and args["image"].startswith("/"):
+            # A same-origin gallery/attachment URL: fetch it (owner-scoped) as bytes.
+            try:
+                async with httpx.AsyncClient(timeout=60) as client:
+                    resp = await client.get(f"{_INTERNAL_BASE}{args['image']}", headers=_internal_headers(owner))
+                    resp.raise_for_status()
+                    image = _as_data_url("data:image/png;base64," + base64.b64encode(resp.content).decode())
+            except Exception:
+                image = None
+        used_canvas = False
+        if not image:
+            shot = await GetEditorScreenshotTool().execute(json.dumps({"session": session}), ctx)
+            image = (shot[1] or {}).get("screenshot") if isinstance(shot, tuple) else None
+            used_canvas = bool(image)
+        if not image:
+            return "ai_edit_image: no image", {
+                "error": "ai_edit_image needs an `image` (data URL or same-origin URL) or an open editor.",
+                "exit_code": 1,
+            }
+        _t["image"] = time.perf_counter()
+        payload: Dict[str, Any] = {"image": image}
+        model_choice = str(args.get("model") or "").strip()
+        mask_used = False
+        place_mode: Optional[str] = None
+        if op == "upscale":
+            payload["scale"] = int(args.get("scale") or 2)
+        elif op == "denoise":
+            payload["strength"] = float(args.get("strength") or 0.5)
+        elif op in ("inpaint", "generative"):
+            payload["prompt"] = str(args.get("prompt") or "").strip()
+            if model_choice:
+                # inpaint_proxy reads `_model` to route to a specific model.
+                payload["_model"] = model_choice
+            mode = str(args.get("mode") or "instruction").strip().lower()
+            _steps = int(args.get("steps") or 0)
+            if _steps > 0:
+                payload["steps"] = _steps
+            mask_used = False
+            mask = None
+            if mode == "masked":
+                mask = _as_data_url(args.get("mask"))
+                if not mask:
+                    mask = await _fetch_selection_mask(owner, session)
+                # An empty/tiny SAM mask on small figures is useless: drop it.
+                if mask and _mask_white_fraction(mask) < _MIN_MASK_FRACTION:
+                    mask = None
+                if not mask:
+                    # Fall back to the grounding detector (OWL-ViT): a dilated
+                    # box mask around the matching object.
+                    box = await _ground_box(owner, image, _mask_label(args, payload["prompt"]))
+                    if box:
+                        candidate = _rect_mask_data_url(image, box, pad_frac=0.15)
+                        if candidate and _mask_white_fraction(candidate) >= _MIN_MASK_FRACTION:
+                            mask = candidate
+                if mask:
+                    payload["mask"] = mask
+                    payload["mode"] = "masked"
+                    mask_used = True
+                else:
+                    # Nothing usable to mask -> whole-image instruction fallback
+                    # rather than placing a transparent/empty layer.
+                    mode = "instruction"
+            if mode != "masked":
+                # Instruction mode: whole-image edit with no tight mask. Send a
+                # full-white mask so the edit endpoint accepts the request and
+                # regenerates the whole frame under the instruction prompt, which
+                # names what must stay unchanged. This avoids the mask-compositing
+                # halos that loose selections caused.
+                payload["mode"] = "instruction"
+                payload.pop("mask", None)
+                payload["prompt"] = _ensure_keep_clause(payload["prompt"])
+                try:
+                    from PIL import Image as _PILImage
+
+                    _raw = _data_url_bytes(image)
+                    _w, _h = _PILImage.open(io.BytesIO(_raw)).size
+                    _mbuf = io.BytesIO()
+                    _PILImage.new("L", (_w, _h), 255).save(_mbuf, "PNG")
+                    payload["mask"] = "data:image/png;base64," + base64.b64encode(_mbuf.getvalue()).decode()
+                except Exception:
+                    pass
+            place_mode = "masked" if mask_used else "instruction"
+        _t["prep"] = time.perf_counter()
+        try:
+            data = await _post(_AI_OPS[op], payload, owner)
+        except Exception as exc:
+            logger.info(
+                "image-op ai_edit_image op=%s stage=provider FAILED image_ms=%.1f prep_ms=%.1f total_ms=%.1f err=%s",
+                op, (_t["image"] - _t["start"]) * 1000.0, (_t["prep"] - _t["image"]) * 1000.0,
+                (time.perf_counter() - _t["start"]) * 1000.0, exc,
+            )
+            return f"ai_edit_image: {op}", {"error": f"ai_edit_image ({op}) failed: {exc}", "exit_code": 1}
+        _t["provider"] = time.perf_counter()
+        result = data.get("image") or data.get("data")
+        data_url = _as_data_url(result)
+        if not data_url:
+            return f"ai_edit_image: {op}", {"error": f"ai_edit_image ({op}) returned no image.", "exit_code": 1}
+        if _image_is_blank(data_url):
+            return f"ai_edit_image: {op}", {
+                "error": f"ai_edit_image ({op}) produced an empty layer.",
+                "failure_kind": "empty_result",
+                "exit_code": 1,
+            }
+
+        info: Dict[str, Any] = {
+            "output": f"Applied AI edit '{op}'" + (" to the current canvas." if used_canvas else "."),
+            "op": op,
+            "model": data.get("model") or model_choice or "",
+            "exit_code": 0,
+        }
+        try:
+            info.update(_persist_png(_data_url_bytes(data_url), owner, ctx.get("session_id"), f"ai_edit_image:{op}", f"ai_edit_image:{op}"))
+        except Exception as exc:
+            logger.warning("ai_edit_image persist failed: %s", exc)
+        _t["persist"] = time.perf_counter()
+        if bool(args.get("place", True)):
+            placed = await _place_layer(
+                data_url,
+                f"AI {op}",
+                owner,
+                session,
+                masked=mask_used,
+                blend=str(args.get("blend") or "normal"),
+                opacity=float(args.get("opacity") or 100),
+                mode=place_mode,
+            )
+            info["placed"] = placed
+            if placed:
+                info["output"] += " Placed the result as a new layer."
+        _t["place"] = time.perf_counter()
+        logger.info(
+            "image-op ai_edit_image op=%s mode=%s canvas=%s image_ms=%.1f mask_ms=%.1f "
+            "model_ms=%.1f persist_ms=%.1f place_ms=%.1f total_ms=%.1f",
+            op, place_mode or "instruction", used_canvas,
+            (_t["image"] - _t["start"]) * 1000.0,
+            (_t["prep"] - _t["image"]) * 1000.0,
+            (_t["provider"] - _t["prep"]) * 1000.0,
+            (_t["persist"] - _t["provider"]) * 1000.0,
+            (_t["place"] - _t["persist"]) * 1000.0,
+            (_t["place"] - _t["start"]) * 1000.0,
+        )
+        return f"ai_edit_image: {op}", info
+
+
+class GenerateImageLayerTool:
+    """Generate an image with the configured image model and place it as a layer."""
+
+    async def execute(self, content: str, ctx: dict):
+        args = _parse(content)
+        prompt = str(args.get("prompt") or "").strip()
+        if not prompt:
+            return "generate_image: invalid", {"error": "generate_image needs a non-empty `prompt`.", "exit_code": 1}
+        owner = ctx.get("owner")
+        if not _provider_available(owner):
+            return "generate_image: provider required", {
+                "error": _provider_message(),
+                "failure_kind": "image_provider_unavailable",
+                "needs_provider": True,
+                "exit_code": 1,
+            }
+        session = _session(args, ctx)
+        payload: Dict[str, Any] = {"prompt": prompt}
+        for key in ("model", "size", "quality"):
+            if args.get(key):
+                payload[key] = args[key]
+        try:
+            from src.ai_interaction import do_generate_image
+
+            data = await do_generate_image(
+                json.dumps(payload, ensure_ascii=False),
+                session_id=session,
+                owner=owner,
+                incognito=True,
+            )
+        except Exception as exc:
+            return "generate_image: error", {"error": f"generate_image failed: {exc}", "exit_code": 1}
+        result = data.get("image_url") or data.get("image") or data.get("data")
+        data_url = _as_data_url(result)
+        if not data_url:
+            return "generate_image", {"error": "generate_image returned no image.", "exit_code": 1}
+        info: Dict[str, Any] = {
+            "output": f"Generated an image for: {prompt[:120]}",
+            "image_size": data.get("image_size"),
+            "model": data.get("image_model") or str(args.get("model") or ""),
+            "exit_code": 0,
+        }
+        try:
+            info.update(_persist_png(_data_url_bytes(data_url), owner, ctx.get("session_id"), prompt, "generate_image"))
+        except Exception as exc:
+            logger.warning("generate_image persist failed: %s", exc)
+        if bool(args.get("place", True)):
+            placed = await _place_layer(
+                data_url,
+                str(args.get("name") or "Generated image"),
+                owner,
+                session,
+                masked=bool(args.get("mask")),
+                blend=str(args.get("blend") or "normal"),
+                opacity=float(args.get("opacity") or 100),
+            )
+            info["placed"] = placed
+            if placed:
+                info["output"] += " Placed it as a new layer."
+        return "generate_image", info
diff --git a/src/editor_agent_model.py b/src/editor_agent_model.py
new file mode 100644
index 000000000..82e82a5aa
--- /dev/null
+++ b/src/editor_agent_model.py
@@ -0,0 +1,498 @@
+"""Editor agent/planner model resolution.
+
+The image-editor Quick Edit planner (`/api/editor/plan`, `/api/editor/agent`)
+runs on a LOCAL Qwen3.5-9B vision model served on seneca when one is
+reachable, instead of the hosted chat model. This module owns:
+
+  * the local model base URLs / model id (settings-overridable),
+  * an ordered candidate list (per-request ``agent_model`` override, then the
+    local Qwen3.5-9B, then the hosted default/utility chat model),
+  * a vision fallback chain: local model WITH the canvas screenshot, else a
+    text-only call whose image is described by a separate VL caption model,
+  * a lightweight reachability probe for the configured local bases.
+
+Everything is best-effort: when no local server is reachable the planner
+transparently falls back to the previously-used hosted chat model, so the
+editor agent never regresses to "no plan".
+"""
+
+from __future__ import annotations
+
+import contextvars
+import json
+import logging
+import os
+import re
+import threading
+from typing import Any, Dict, List, Optional, Tuple
+
+import httpx
+
+logger = logging.getLogger(__name__)
+
+# The local Qwen3.5-9B vision server (seneca). :8097 (tmux AGENT_VLM) is the
+# canonical editor-agent endpoint. Override with the ``editor_agent_base_url``
+# setting (single URL wins) or the ``ODYSSEUS_EDITOR_AGENT_BASES`` env
+# (comma-separated). NOTE: :8095 is a DIFFERENT server (Qwen3-VL-30B) used ONLY
+# for the caption fallback below — never list it here as an agent model.
+DEFAULT_LOCAL_BASES = [
+    "http://100.69.120.65:8097/v1",
+]
+DEFAULT_LOCAL_MODEL = "Qwen/Qwen3.5-9B"
+
+# Vision caption model used when the editor-agent model cannot accept images.
+DEFAULT_CAPTION_BASE = "http://100.69.120.65:8095/v1"
+DEFAULT_CAPTION_MODEL = "Qwen/Qwen3.5-9B"
+
+# Served-model-id cache per base (populated on first use). The local servers 400
+# with "Failed to load model" when asked for an id they do not serve (e.g. the
+# client's default "Qwen3.5-9B-MLX-8bit", or a stale caption model), so we
+# resolve the requested id against GET {base}/models and fall back to one that
+# is actually served.
+_MODELS_CACHE: Dict[str, set] = {}
+
+_CAPTION_INSTRUCTION = (
+    "Describe this image in one or two sentences for a photo editor: the main "
+    "subject, the background/scene, lighting, dominant colours, and any obvious "
+    "flaws (blown highlights, colour cast, clutter, blur)."
+)
+
+
+def _setting(key: str, default: Any = "") -> Any:
+    try:
+        from src.settings import load_settings
+
+        value = load_settings().get(key)
+        return value if value not in (None, "") else default
+    except Exception:
+        return default
+
+
+def local_bases() -> List[str]:
+    override = _setting("editor_agent_base_url")
+    if override:
+        return [str(override)]
+    env = os.getenv("ODYSSEUS_EDITOR_AGENT_BASES")
+    if env:
+        bases = [b.strip() for b in env.split(",") if b.strip()]
+        if bases:
+            return bases
+    return list(DEFAULT_LOCAL_BASES)
+
+
+def local_model() -> str:
+    return str(_setting("editor_agent_model", DEFAULT_LOCAL_MODEL))
+
+
+def caption_base() -> str:
+    return str(_setting("editor_caption_base_url", DEFAULT_CAPTION_BASE))
+
+
+def caption_model() -> str:
+    return str(_setting("editor_caption_model", DEFAULT_CAPTION_MODEL))
+
+
+# Per-request / per-plan context (contextvars keep this correct under the
+# async event loop without sharing state between concurrent editor turns).
+_override: contextvars.ContextVar[Optional[str]] = contextvars.ContextVar(
+    "editor_agent_model_override", default=None
+)
+_last_model: contextvars.ContextVar[Optional[Tuple[str, str]]] = contextvars.ContextVar(
+    "editor_agent_last_model", default=None
+)
+
+
+def set_override(value: Optional[str]) -> None:
+    _override.set(value or None)
+
+
+def get_override() -> Optional[str]:
+    return _override.get()
+
+
+def set_last_model(model: str, source: str) -> None:
+    _last_model.set((model, source))
+
+
+def get_last_model() -> Optional[Tuple[str, str]]:
+    return _last_model.get()
+
+
+def _chat_url(base: str) -> str:
+    b = str(base or "").rstrip("/")
+    if b.endswith("/chat/completions"):
+        return b
+    return b + "/chat/completions"
+
+
+def _split_override(override: str) -> Tuple[str, str]:
+    """Parse ``base::model`` (or a bare model id)."""
+    raw = str(override or "").strip()
+    if "::" in raw:
+        base, model = raw.split("::", 1)
+        return base.strip(), model.strip()
+    return "", raw
+
+
+def _has_image(messages: List[dict]) -> bool:
+    for msg in messages:
+        content = msg.get("content")
+        if isinstance(content, list):
+            for part in content:
+                if isinstance(part, dict) and part.get("type") == "image_url":
+                    return True
+    return False
+
+
+def _first_image(messages: List[dict]) -> Optional[str]:
+    for msg in messages:
+        content = msg.get("content")
+        if isinstance(content, list):
+            for part in content:
+                if isinstance(part, dict) and part.get("type") == "image_url":
+                    url = (part.get("image_url") or {}).get("url")
+                    if isinstance(url, str):
+                        return url
+    return None
+
+
+def _strip_images(messages: List[dict]) -> List[dict]:
+    out: List[dict] = []
+    for msg in messages:
+        content = msg.get("content")
+        if isinstance(content, list):
+            text = "\n".join(
+                str(part.get("text") or "")
+                for part in content
+                if isinstance(part, dict) and part.get("type") == "text"
+            )
+            out.append({"role": msg.get("role", "user"), "content": text})
+        else:
+            out.append({"role": msg.get("role", "user"), "content": content})
+    return out
+
+
+def _with_caption(messages: List[dict], caption: str) -> List[dict]:
+    note = f"\n\n[Canvas screenshot caption: {caption}]"
+    out = [dict(m) for m in messages]
+    for msg in reversed(out):
+        if msg.get("role") == "user":
+            msg["content"] = str(msg.get("content") or "") + note
+            break
+    return out
+
+
+async def _post_chat(
+    base: str,
+    model: str,
+    messages: List[dict],
+    headers: Optional[dict],
+    timeout: float,
+    max_tokens: int = 1024,
+    response_format: Optional[dict] = None,
+) -> Optional[str]:
+    if not base or not model:
+        return None
+    payload: Dict[str, Any] = {
+        "model": model,
+        "messages": messages,
+        "temperature": 0.2,
+        "max_tokens": max_tokens,
+        "stream": False,
+    }
+    # Constrain the planner to a strict JSON ops schema (structured outputs /
+    # grammar) so the model can only emit valid editor ops. Unknown servers
+    # ignore the field; the server-side schema validation is the real enforcer.
+    if isinstance(response_format, dict):
+        payload["response_format"] = response_format
+    try:
+        async with httpx.AsyncClient(timeout=timeout) as client:
+            resp = await client.post(_chat_url(base), json=payload, headers=headers or {})
+            if resp.status_code != 200:
+                logger.debug(
+                    "editor agent chat %s -> %s (%s)", base, resp.status_code, resp.text[:200]
+                )
+                return None
+            data = resp.json()
+    except Exception as exc:
+        logger.debug("editor agent chat %s failed: %s", base, exc)
+        return None
+    try:
+        return data["choices"][0]["message"]["content"]
+    except Exception:
+        return None
+
+
+async def _served_models(base: str, timeout: float = 3.0) -> set:
+    """Return the set of model ids a base serves (cached; empty on failure)."""
+    if not base:
+        return set()
+    cached = _MODELS_CACHE.get(base)
+    if cached is not None:
+        return cached
+    ids: set = set()
+    try:
+        async with httpx.AsyncClient(timeout=timeout) as client:
+            resp = await client.get(base.rstrip("/") + "/models")
+            if resp.status_code == 200:
+                ids = {
+                    str(m.get("id"))
+                    for m in (resp.json().get("data") or [])
+                    if isinstance(m, dict) and m.get("id")
+                }
+    except Exception:
+        ids = set()
+    _MODELS_CACHE[base] = ids
+    return ids
+
+
+async def _resolve_model(base: str, requested: str, fallback: str) -> str:
+    """Return a model id ``base`` actually serves.
+
+    If the requested id is served, keep it; otherwise use ``fallback`` (when
+    served) or any served id. When the served list is unknown (server down),
+    keep the requested id (or ``fallback``).
+    """
+    requested = str(requested or "").strip()
+    fallback = str(fallback or "").strip()
+    ids = await _served_models(base)
+    if ids:
+        if requested and requested in ids:
+            return requested
+        if fallback in ids:
+            return fallback
+        return sorted(ids)[0]
+    return requested or fallback
+
+
+async def caption_image(data_url: str, owner: Optional[str] = None, timeout: float = 90.0) -> Optional[str]:
+    if not isinstance(data_url, str) or not data_url.startswith("data:image/"):
+        return None
+    messages = [
+        {
+            "role": "user",
+            "content": [
+                {"type": "text", "text": _CAPTION_INSTRUCTION},
+                {"type": "image_url", "image_url": {"url": data_url}},
+            ],
+        }
+    ]
+    base = caption_base()
+    model = await _resolve_model(base, caption_model(), local_model())
+    return await _post_chat(base, model, messages, None, timeout, max_tokens=200)
+
+
+_DONE_RE = re.compile(r"^\s*DONE\b", re.I)
+_RETRY_RE = re.compile(r"RETRY:?\s*(.+)", re.I | re.S)
+
+
+def _parse_self_check(text: str) -> Dict[str, Any]:
+    s = str(text or "").strip()
+    if _DONE_RE.match(s):
+        return {"done": True, "issues": [], "retry_hint": "", "text": s}
+    m = _RETRY_RE.search(s)
+    if m or re.search(r"\bretry\b", s, re.I):
+        hint = (m.group(1).strip() if m else s) or s
+        return {"done": False, "issues": [hint], "retry_hint": hint, "text": s}
+    return {"done": True, "issues": [], "retry_hint": "", "text": s}
+
+
+async def self_check(
+    before: Any,
+    after: Any,
+    prompt: str,
+    model: Optional[str] = None,
+    owner: Optional[str] = None,
+    timeout: float = 30.0,
+) -> Dict[str, Any]:
+    """Same-origin VL self-check: compare BEFORE vs AFTER against the intent.
+
+    The browser cannot call the local VL server directly (it sends no CORS
+    headers), so ``/api/editor/self-check`` proxies here. Returns
+    ``{done, issues, retry_hint, text}``; on any failure (bad input, the model
+    is unreachable, or a timeout) it degrades to ``done=True`` with
+    ``reason="unavailable"`` so the client never gets stuck retrying.
+    """
+    if not (
+        isinstance(before, str) and before.startswith("data:image/")
+        and isinstance(after, str) and after.startswith("data:image/")
+    ):
+        return {"done": True, "issues": [], "retry_hint": "",
+                "reason": "unavailable", "text": "DONE"}
+    bases = local_bases() or list(DEFAULT_LOCAL_BASES)
+    base = bases[0]
+    mdl = await _resolve_model(base, str(model or local_model()), local_model())
+    messages = [{
+        "role": "user",
+        "content": [
+            {"type": "text", "text": str(prompt or "")},
+            {"type": "image_url", "image_url": {"url": before}},
+            {"type": "image_url", "image_url": {"url": after}},
+        ],
+    }]
+    text = await _post_chat(base, mdl, messages, None, timeout, max_tokens=140)
+    if not text:
+        return {"done": True, "issues": [], "retry_hint": "",
+                "reason": "unavailable", "text": "DONE"}
+    out = _parse_self_check(text)
+    out["model"] = mdl
+    out["source"] = "local"
+    return out
+
+
+def _candidates(owner: Optional[str], override: Optional[str]) -> List[Dict[str, Any]]:
+    cands: List[Dict[str, Any]] = []
+    if override:
+        base, model = _split_override(override)
+        if model:
+            cands.append(
+                {"base": base or local_bases()[0], "model": model, "headers": None, "source": "override"}
+            )
+    for base in local_bases():
+        cands.append({"base": base, "model": local_model(), "headers": None, "source": "local"})
+    try:
+        from src.endpoint_resolver import resolve_endpoint
+
+        for prefix in ("utility", "default"):
+            try:
+                url, model, headers = resolve_endpoint(prefix, owner=owner)
+            except Exception:
+                continue
+            if url and model:
+                cands.append({"base": url, "model": model, "headers": headers, "source": "hosted"})
+                break
+    except Exception:
+        pass
+    return cands
+
+
+async def plan_with_editor_agent(
+    messages: List[dict],
+    owner: Optional[str] = None,
+    override: Optional[str] = None,
+    timeout: float = 90.0,
+    response_format: Optional[dict] = None,
+) -> Optional[Tuple[str, str, str]]:
+    """Return (raw_plan_text, model_used, source) or None.
+
+    Tries the local model WITH the screenshot, then the same model text-only
+    with a VL caption of the screenshot, then the hosted chat model.
+
+    ``response_format`` (a JSON-schema structured-output constraint) is sent
+    ONLY to the local editor-agent bases, so a hosted fallback model that does
+    not support the field never rejects the request.
+    """
+    has_img = _has_image(messages)
+    text_messages = _strip_images(messages) if has_img else messages
+    image = _first_image(messages) if has_img else None
+    caption: Optional[str] = None
+    _local = {str(b).rstrip("/") for b in local_bases()}
+    for cand in _candidates(owner, override):
+        base, model = cand["base"], cand["model"]
+        headers = cand.get("headers")
+        is_local = cand["source"] == "local" or str(base).rstrip("/") in _local
+        rf = response_format if (response_format and is_local) else None
+        extra = {"response_format": rf} if rf else {}
+        if has_img:
+            raw = await _post_chat(base, model, messages, headers, timeout, **extra)
+            if raw:
+                return raw, model, cand["source"]
+            if caption is None and image:
+                caption = await caption_image(image, owner)
+            if caption:
+                raw = await _post_chat(
+                    base, model, _with_caption(text_messages, caption), headers, timeout, **extra,
+                )
+                if raw:
+                    return raw, model, cand["source"] + "+caption"
+        else:
+            raw = await _post_chat(
+                base, model, text_messages, headers, timeout, **extra
+            )
+            if raw:
+                return raw, model, cand["source"]
+    return None
+
+
+async def list_editor_agent_models(owner: Optional[str] = None) -> List[Dict[str, Any]]:
+    """Models available to the editor agent, for the model picker.
+
+    Lists the local Qwen3.5-9B (one entry per reachable base) plus the hosted
+    default/utility chat model that the planner falls back to.
+    """
+    models: List[Dict[str, Any]] = []
+    seen: set = set()
+    for base in local_bases():
+        model = local_model()
+        key = ("local", base, model)
+        if key in seen:
+            continue
+        seen.add(key)
+        models.append({
+            "id": model,
+            "label": f"{model} · local",
+            "source": "local",
+            "vision": True,
+            "base_url": base,
+        })
+    try:
+        from src.endpoint_resolver import resolve_endpoint
+
+        for prefix in ("utility", "default"):
+            try:
+                url, model, _headers = resolve_endpoint(prefix, owner=owner)
+            except Exception:
+                continue
+            if url and model:
+                key = ("hosted", model)
+                if key not in seen:
+                    seen.add(key)
+                    models.append({
+                        "id": model,
+                        "label": model,
+                        "source": "hosted",
+                        "vision": None,
+                        "base_url": url,
+                    })
+                break
+    except Exception:
+        pass
+    return models
+
+
+# ---------------------------------------------------------------------------
+# Reachability probe (best effort, non-blocking).
+# ---------------------------------------------------------------------------
+
+_PROBE: Dict[str, bool] = {}
+
+
+def probe_models(base: str, timeout: float = 3.0) -> bool:
+    try:
+        with httpx.Client(timeout=timeout) as client:
+            resp = client.get(str(base).rstrip("/") + "/models")
+            return resp.status_code == 200
+    except Exception:
+        return False
+
+
+def _probe_worker() -> None:
+    for base in local_bases():
+        ok = probe_models(base)
+        _PROBE[base] = ok
+        logger.info("editor agent local base %s reachable=%s", base, ok)
+    cap = caption_base()
+    _PROBE[cap] = probe_models(cap)
+    logger.info("editor agent caption base %s reachable=%s", cap, _PROBE[cap])
+
+
+def startup_probe() -> None:
+    """Kick off a background reachability probe (never blocks startup)."""
+    try:
+        threading.Thread(target=_probe_worker, name="editor-agent-probe", daemon=True).start()
+    except Exception:
+        logger.debug("editor agent probe thread failed", exc_info=True)
+
+
+def probe_status() -> Dict[str, bool]:
+    return dict(_PROBE)
diff --git a/src/editor_style_guide.py b/src/editor_style_guide.py
new file mode 100644
index 000000000..0f03497ed
--- /dev/null
+++ b/src/editor_style_guide.py
@@ -0,0 +1,1105 @@
+"""Single source of truth for photo-editor intent routing.
+
+Both the server-side planner (``routes/editor_agent_routes.py``) and the
+browser fallback planner (``static/js/editor/nl-edit.js``) read this guide so
+their behaviour cannot drift. It is served verbatim to the client at
+``GET /api/editor/style-guide``.
+
+Calibrated strengths live here; this file is the only place to tune routing.
+It is intentionally dependency-free so the route module can import it cheaply.
+"""
+from __future__ import annotations
+
+import json
+import re
+from collections import Counter
+from typing import Any, Dict, List, Optional
+
+STYLE_GUIDE_VERSION = 8
+
+# New editor ops (implemented client-side, static) with canonical params. The
+# server op catalog must include these or a valid plan would be filtered out.
+NEW_OPS: List[Dict[str, Any]] = [
+    {
+        "op": "photo.autoTone",
+        "params": {},
+        "help": "Camera-Raw-style auto tone/colour (per-channel levels, auto white "
+                "balance, exposure, contrast). The single preferred global lift.",
+    },
+    {
+        "op": "retouch.skin",
+        "params": {"smooth": 8, "opacity": 0.35, "blemish": True,
+                   "radius": 12, "threshold": 16},
+        "help": "Gentle frequency-separation skin smoothing that keeps texture, over "
+                "the selection intersected with skin tones. Keep it subtle: smooth "
+                "<=14, opacity <=0.45; it never brightens the face.",
+    },
+    {
+        "op": "retouch.blemish",
+        "params": {"radius": 4, "threshold": 16},
+        "help": "Remove small blemishes inside the selection or skin region.",
+    },
+    {
+        "op": "retouch.teeth",
+        "params": {"desat": 0.6, "bright": 16},
+        "help": "Whiten teeth within the current selection (desaturate yellow, "
+                "lift brightness with a small feather).",
+    },
+    {
+        "op": "selection.face",
+        "params": {"mode": "replace"},
+        "help": "Select a face (SAM text 'face', upper-centre ellipse fallback).",
+    },
+    {
+        "op": "selection.background",
+        "params": {"mode": "replace", "subject": "person", "fuzziness": 30},
+        "help": "Select the background (SAM subject inverted, corner-colour "
+                "fallback). Subject-aware; prefer over a plain global blur.",
+    },
+    {
+        "op": "fill.flood",
+        "params": {"color": "#ff0000", "x": 0, "y": 0, "tolerance": 32},
+        "help": "Paint-bucket flood-fill a pixel layer from a point "
+                "{x,y,color,tolerance}. Use for 'fill ... with <colour>' when there "
+                "is no active selection.",
+    },
+    {
+        "op": "selection.fill",
+        "params": {"color": "#ff0000"},
+        "help": "Fill the current selection with a colour on the active pixel layer "
+                "{color}. Use for 'fill the selection with <colour>'.",
+    },
+    {
+        "op": "text.edit",
+        "params": {"content": "New text", "size": 96, "color": "#ff0000"},
+        "help": "Edit an EXISTING text layer {id|index|name, content, font, size, "
+                "color, align, tracking, lineHeight}. Use for 'make the text "
+                "bigger/smaller' and 'make the title <colour>' — never text.add.",
+    },
+    {
+        "op": "layers.align",
+        "params": {"mode": "center"},
+        "help": "Align/distribute the selected layers to the canvas {mode:left|center|"
+                "right|top|middle|bottom|distribute-h|distribute-v}.",
+    },
+    {
+        "op": "layer.rotate",
+        "params": {"degrees": 90},
+        "help": "Rotate the ACTIVE LAYER by 90/180/270 {degrees, id|index|name}. Use "
+                "unless the prompt names the whole image/canvas/photo.",
+    },
+    {
+        "op": "layer.flip",
+        "params": {"axis": "h"},
+        "help": "Flip the ACTIVE LAYER in place {axis:h|v, id|index|name}.",
+    },
+    {
+        "op": "document.rotate",
+        "params": {"degrees": 90},
+        "help": "Rotate the WHOLE document (all layers + canvas) by 90/180/270 "
+                "{degrees} — for 'rotate the whole image/canvas/photo'.",
+    },
+    {
+        "op": "document.flip",
+        "params": {"axis": "h"},
+        "help": "Flip the WHOLE document {axis:h|v} — for 'flip the canvas/whole "
+                "image'.",
+    },
+    {
+        "op": "selection.copy",
+        "params": {},
+        "help": "Copy (or cut, {cut:true}) the selection pixels to the internal "
+                "clipboard.",
+    },
+    {
+        "op": "selection.paste",
+        "params": {},
+        "help": "Paste the internal clipboard as a new layer {name}.",
+    },
+    {
+        "op": "layers.flatten",
+        "params": {},
+        "help": "Flatten all layers into a single layer.",
+    },
+    {
+        "op": "layers.mergeDown",
+        "params": {},
+        "help": "Merge the active layer down into the layer below.",
+    },
+]
+
+NEW_OP_NAMES: List[str] = [op["op"] for op in NEW_OPS]
+
+
+def _adj(kind: str, params: Dict[str, Any]) -> Dict[str, Any]:
+    return {"op": "adjustments.apply", "params": {"type": kind, "params": params}}
+
+
+def _filter(fid: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+    return {"op": "filters.apply", "params": {"id": fid, **(params or {})}}
+
+
+# Ordered intent routes. The first route whose keyword appears wins.
+INTENT_ROUTES: List[Dict[str, Any]] = [
+    {
+        "id": "teeth",
+        "keywords": ["teeth", "whiten my smile", "whiter smile", "smile looks"],
+        "steps": [
+            {"op": "selection.face", "params": {"mode": "replace"}},
+            {"op": "retouch.teeth", "params": {"desat": 0.6, "bright": 16}},
+        ],
+        "reply": "Selecting the face and whitening teeth.",
+    },
+    {
+        "id": "portrait_retouch",
+        "keywords": ["skin", "complexion", "blemish", "acne", "pores", "retouch",
+                     "look better", "look my best", "make me look", "beautify",
+                     "flawless", "smooth my face", "clear up", "clean up my face",
+                     "portrait", "selfie"],
+        # Do NOT lead with a whole-image photo.autoTone: lightening the whole frame
+        # washes out the face (the client suppresses autoTone for portrait intents
+        # unless the histogram shows real under/over-exposure). Go straight to a
+        # gentle skin retouch; keep it subtle and never brighten the face.
+        "min_steps": 3,
+        "steps": [
+            {"op": "selection.face", "params": {"mode": "replace"}},
+            {"op": "retouch.skin", "params": {"smooth": 8, "opacity": 0.35,
+                                              "blemish": True, "radius": 12,
+                                              "threshold": 16}},
+            {"op": "selection.deselect", "params": {}},
+        ],
+        "reply": "Selecting the face and gently retouching the skin.",
+    },
+    {
+        "id": "restore",
+        "keywords": ["restore", "restoration", "old photo", "old photograph",
+                     "old picture", "faded photo", "faded picture", "faded",
+                     "recover this photo", "bring back this photo",
+                     "photo restoration"],
+        # Never a large exposure lift: recover contrast + colour from a faded
+        # baseline, then a slight sharpen.
+        "min_steps": 4,
+        "steps": [
+            {"op": "photo.autoTone", "params": {}},
+            _adj("brightness-contrast", {"brightness": 0, "contrast": 18}),
+            _adj("white-balance", {"temperature": 0, "tint": 5}),
+            _adj("vibrance", {"vibrance": 18}),
+            _filter("sharpen"),
+        ],
+        "reply": "Restoring contrast and colour, then a light sharpen.",
+    },
+    {
+        "id": "background",
+        "keywords": ["background"],
+        "steps": [
+            {"op": "selection.background",
+             "params": {"mode": "replace", "subject": "person", "fuzziness": 30}},
+            {"op": "filters.applyMasked", "params": {"id": "blur-gaussian"}},
+        ],
+        "reply": "Selecting the background and softening it.",
+    },
+    {
+        "id": "lighting",
+        # Low-key lighting: one auto-tone pass (the preferred global lift) plus
+        # at most one shadow-lifting, highlight-protecting adjustment. Both are
+        # sanctioned together; never a stack of brightness/exposure lifts.
+        "keywords": ["lighting", "exposure", "too dark", "underexposed",
+                     "underexpose", "backlit", "back-lit", "brighten", "brighter",
+                     "lift the shadows", "dark photo", "dark image"],
+        "min_steps": 2,
+        "steps": [
+            {"op": "photo.autoTone", "params": {}},
+            {"op": "adjustments.apply",
+             "params": {"type": "shadows-highlights",
+                        "params": {"shadows": 30, "highlights": -15}}},
+        ],
+        "reply": "Auto tone (levels and white balance), then one shadow lift "
+                 "that protects the highlights.",
+    },
+    {
+        "id": "cool",
+        "keywords": ["moodier", "moody", "cooler", "cool it", "cinematic", "teal",
+                     "blue tone", "cold", "night mood", "colder"],
+        "steps": [_adj("white-balance", {"temperature": -25})],
+        "reply": "Cooling the white balance (negative temperature).",
+    },
+    {
+        "id": "warm",
+        "keywords": ["warmer", "warm it", "golden", "summer", "sunset",
+                     "golden hour", "warmth"],
+        "steps": [_adj("white-balance", {"temperature": 25})],
+        "reply": "Warming the white balance (positive temperature).",
+    },
+    {
+        "id": "black_white",
+        "keywords": ["black and white", "black & white", "grayscale", "greyscale",
+                     "monochrome", "b&w"],
+        "steps": [_adj("black-white", {})],
+        "reply": "Converting to black and white.",
+    },
+    {
+        "id": "polish",
+        # Generic "make it look good" intents: a decisive multi-step grade with
+        # visible strength (a single timid adjustment scores as imperceptible).
+        "keywords": ["pretty", "beautiful", "make it look good", "look good",
+                     "professional", "professionally", "editorial", "magazine",
+                     "glam", "glamour", "pop", "punchy", "striking", "vibrant",
+                     "film", "film look", "cinematic look", "instagram",
+                     "social media", "elevate", "polish"],
+        "min_steps": 3,
+        "steps": [
+            {"op": "photo.autoTone", "params": {}},
+            _adj("vibrance", {"vibrance": 25}),
+            _filter("clarity", {"amount": 22, "radius": 30}),
+            _filter("vignette", {"amount": 22, "feather": 0.6}),
+        ],
+        "reply": "Balancing tone, adding vibrance and local contrast, with a light vignette.",
+    },
+    {
+        "id": "vivid",
+        "keywords": ["vivid", "dramatic", "saturate", "saturation",
+                     "colourful", "colorful"],
+        "steps": [_adj("vibrance", {"vibrance": 35})],
+        "reply": "Boosting vibrance.",
+    },
+    {
+        "id": "sharpen",
+        "keywords": ["sharpen", "crisper", "crisp", "more detail", "sharper"],
+        "steps": [_filter("sharpen")],
+        "reply": "Sharpening.",
+    },
+]
+
+# A prompt that only asks for a vague "improvement" with no concrete defect and
+# no matching intent cannot be planned deterministically -> ask the user.
+_AMBIGUOUS_PATTERNS = [
+    "clean this up", "clean it up", "fix it", "fix this", "make it better",
+    "make this better", "improve", "touch up", "touch it up", "do something",
+    "enhance", "make it nice", "polish",
+]
+_AMBIGUOUS_OPTIONS = [
+    {"label": "Auto tone & color",
+     "description": "photo.autoTone: balanced levels, white balance, contrast."},
+    {"label": "Brighten (lift shadows)",
+     "description": "shadows-highlights: brighten without blowing highlights."},
+    {"label": "Cooler / cinematic",
+     "description": "white-balance negative: cooler, moodier look."},
+]
+_DEFECT_HINTS = [
+    "skin", "teeth", "background", "light", "dark", "colour", "color", "warm",
+    "cool", "blur", "sharpen", "contrast", "bright", "shadow", "face",
+    "blemish", "noise", "grain", "crop", "vibrance", "saturat", "black and white",
+    "grayscale", "portrait", "moody", "exposure", "tone",
+]
+
+# Low-key safety: at most ONE global lift; prefer shadows/highlights and keep
+# highlights protected. Global-lift adjustment types are counted together.
+GLOBAL_LIFT_TYPES = ("autoTone", "brightness-contrast", "exposure", "levels",
+                     "shadows-highlights")
+_SAFE_LOWKEY_LIFT = {
+    "op": "adjustments.apply",
+    "params": {"type": "shadows-highlights",
+               "params": {"shadows": 30, "highlights": -15}},
+}
+
+
+def match(prompt: str) -> Optional[Dict[str, Any]]:
+    """Return the first matching intent route for a prompt, or None."""
+    text = str(prompt or "").lower()
+    for route in INTENT_ROUTES:
+        if any(keyword in text for keyword in route["keywords"]):
+            return route
+    return None
+
+
+def is_ambiguous(prompt: str) -> bool:
+    text = str(prompt or "").lower()
+    if match(text):
+        return False
+    if any(hint in text for hint in _DEFECT_HINTS):
+        return False
+    return any(pattern in text for pattern in _AMBIGUOUS_PATTERNS)
+
+
+def ask_user_plan() -> Dict[str, Any]:
+    question = "What would you like me to do with this photo?"
+    return {
+        "reply": question,
+        "planner": "fallback",
+        "steps": [],
+        "ask_user": {
+            "question": question,
+            "options": [dict(o) for o in _AMBIGUOUS_OPTIONS],
+            "multi": False,
+        },
+    }
+
+
+def has_concrete_intent(prompt: str) -> bool:
+    """True when a prompt maps to a concrete edit (a recipe, look, recolour,
+    structural op) or names a concrete defect. Used to decide whether a plan made
+    only of generic whole-image tone ops should be trusted or replaced by an
+    ask_user prompt.
+    """
+    text = str(prompt or "").lower()
+    if match(text) or look_plan(text) or recolor_plan(text) or structural_plan(text):
+        return True
+    return any(hint in text for hint in _DEFECT_HINTS)
+
+
+def fallback_plan(prompt: str) -> Optional[Dict[str, Any]]:
+    """Deterministic plan from the guide, or None when nothing matches."""
+    route = match(prompt)
+    if route:
+        return {
+            "reply": route["reply"],
+            "planner": "fallback",
+            "steps": enforce_guards([dict(step) for step in route["steps"]]),
+        }
+    if is_ambiguous(prompt):
+        return ask_user_plan()
+    return None
+
+
+# ── Structural op routing ──────────────────────────────────────────────
+# Deterministic plans for structural editor ops the sampling model reliably
+# substitutes with a generic adjustments/transform step. Mirrors the browser
+# fallback (static/js/editor/nl-edit.js localPlan) so the server and client
+# agree; the server path must emit these or a wrong model plan suppresses the
+# browser fallback.
+_NAMED_COLORS = {
+    "red": "#ff0000", "blue": "#0000ff", "green": "#00a000", "yellow": "#ffff00",
+    "orange": "#ff8000", "purple": "#8000ff", "pink": "#ff69b4", "black": "#000000",
+    "white": "#ffffff", "grey": "#808080", "gray": "#808080", "cyan": "#00ffff",
+    "magenta": "#ff00ff", "brown": "#8b4513", "teal": "#008080",
+}
+_COLOR_TOKEN = (r"(red|blue|green|yellow|orange|purple|pink|black|white|grey|"
+                r"gray|cyan|magenta|brown|teal|#[0-9a-fA-F]{3,6})")
+
+
+def color_for_name(name: str) -> Optional[str]:
+    n = str(name or "").strip().lower()
+    if re.match(r"^#[0-9a-f]{3,6}$", n):
+        return n
+    return _NAMED_COLORS.get(n)
+
+
+# ── Named reference looks + targeted recolour ──────────────────────────
+# Server-only deterministic plans (reached via routes._plan_special ->
+# structural_plan). Deliberately NOT added to INTENT_ROUTES: the browser
+# client consumes `intents` and cannot run an ai_edit_image step, so strong
+# looks must stay on the server path.
+_LOOK_KEEP_CLAUSE = " Keep the main subject and composition exactly the same."
+
+LOOKS = [
+    {
+        "id": "wes_anderson",
+        "keywords": ["wes anderson"],
+        "mode": "recipe",
+        "steps": [
+            {"op": "photo.autoTone", "params": {}},
+            _adj("white-balance", {"temperature": 10, "tint": 6}),
+            _adj("vibrance", {"vibrance": 18}),
+            _adj("brightness-contrast", {"brightness": 6, "contrast": -10}),
+        ],
+        "reply": "Gave it a Wes Anderson look: pastel palette, warm highlights and soft contrast.",
+    },
+    {
+        "id": "film_noir",
+        "keywords": ["film noir"],
+        "mode": "recipe",
+        "steps": [
+            _adj("black-white", {}),
+            _adj("brightness-contrast", {"contrast": 38}),
+            _adj("shadows-highlights", {"shadows": -22, "highlights": 18}),
+            _filter("vignette", {"amount": 45, "feather": 0.5}),
+        ],
+        "reply": "Gave it a film-noir look: high-contrast black and white with deep shadows.",
+    },
+    {
+        "id": "vintage_kodachrome",
+        "keywords": ["kodachrome", "vintage film"],
+        "mode": "recipe",
+        "steps": [
+            {"op": "photo.autoTone", "params": {}},
+            _adj("white-balance", {"temperature": 12, "tint": 8}),
+            _adj("vibrance", {"vibrance": 22}),
+            _adj("brightness-contrast", {"contrast": 14}),
+            _filter("vignette", {"amount": 12, "feather": 0.7}),
+        ],
+        "reply": "Gave it a vintage Kodachrome look: warm saturated colour and lifted contrast.",
+    },
+    {
+        "id": "cyberpunk",
+        "keywords": ["cyberpunk"],
+        "mode": "instruction",
+        "prompt": "Restyle the photo as a cyberpunk scene: vivid neon magenta and cyan "
+                  "lighting, wet reflective surfaces, deep shadows and a futuristic "
+                  "atmosphere." + _LOOK_KEEP_CLAUSE,
+        "reply": "Restyling it as a cyberpunk scene with the image model.",
+    },
+    {
+        "id": "studio_ghibli",
+        "keywords": ["ghibli", "studio ghibli"],
+        "mode": "instruction",
+        "prompt": "Restyle the photo as a soft hand-painted anime scene in a "
+                  "Studio-Ghibli-inspired pastel style: luminous pastel palette, "
+                  "gentle painterly shading, clean edges and warm sunlight."
+                  + _LOOK_KEEP_CLAUSE,
+        "reply": "Restyling it as a Studio-Ghibli-inspired pastel scene with the image model.",
+    },
+]
+
+
+def look_plan(prompt: str) -> Optional[Dict[str, Any]]:
+    """Deterministic plan for a named reference look, or None.
+
+    Recipe looks (Wes Anderson, film noir, vintage Kodachrome) are pure
+    adjustment/filter stacks; strong looks (cyberpunk, Studio Ghibli) use
+    ai_edit_image instruction mode.
+    """
+    p = str(prompt or "").lower()
+    for look in LOOKS:
+        if any(k in p for k in look["keywords"]):
+            if look["mode"] == "instruction":
+                steps = [{"op": "ai_edit_image",
+                          "params": {"op": "generative", "mode": "instruction",
+                                     "prompt": look["prompt"], "steps": 8}}]
+            else:
+                steps = [dict(s) for s in look["steps"]]
+            return {"reply": look["reply"], "planner": "deterministic", "steps": steps}
+    return None
+
+
+_RECOLOR_ACTION_RE = re.compile(
+    r"\brecolou?r\b"
+    r"|\bmake\s+only\b"
+    r"|\bmake\s+the\b[^.]{0,30}?\b" + _COLOR_TOKEN + r"\b"
+    r"|\b(?:change|turn|convert|paint|colou?r)\b[^.]{0,40}?\b" + _COLOR_TOKEN + r"\b",
+    re.I,
+)
+_RECOLOR_EXCLUDE_RE = re.compile(
+    r"\b(?:background|backdrop|blur|black\s+and\s+white|grayscale|greyscale|"
+    r"monochrome|b&w|text|title|font|caption|label|logo|watermark|drop\s+shadow|"
+    r"generative)\b",
+    re.I,
+)
+
+
+_RECOLOR_TRAILING_ADJ = re.compile(
+    r"\s+\b(?:bright|brighter|vivid|vibrant|dark|darker|light|lighter|deep|"
+    r"pale|more|less|very|really|slightly|totally|completely)\b\s*$",
+    re.I,
+)
+
+
+def _hex_rgb01(hex_color: str):
+    h = str(hex_color or "").lstrip("#")
+    if len(h) == 3:
+        h = "".join(ch * 2 for ch in h)
+    try:
+        return tuple(int(h[i:i + 2], 16) / 255.0 for i in (0, 2, 4))
+    except Exception:
+        return None
+
+
+def _hue_degrees(hex_color: str) -> Optional[float]:
+    rgb = _hex_rgb01(hex_color)
+    if rgb is None:
+        return None
+    r, g, b = rgb
+    mx, mn = max(rgb), min(rgb)
+    if mx == mn:
+        return 0.0
+    d = mx - mn
+    if mx == r:
+        h = ((g - b) / d) % 6
+    elif mx == g:
+        h = (b - r) / d + 2
+    else:
+        h = (r - g) / d + 4
+    return h * 60.0
+
+
+def _hue_delta(src_hex: str, tgt_hex: str) -> int:
+    sh = _hue_degrees(src_hex)
+    th = _hue_degrees(tgt_hex)
+    if sh is None or th is None:
+        return 0
+    return int(round((th - sh + 180.0) % 360.0 - 180.0))
+
+
+def _is_chromatic(hex_color: str) -> bool:
+    """True when a pure hue rotation can plausibly reach this colour.
+
+    White / black / grey targets have (near) zero saturation and cannot be
+    reached by rotating hue, so they go through the image model instead.
+    """
+    rgb = _hex_rgb01(hex_color)
+    if rgb is None:
+        return False
+    mx, mn = max(rgb), min(rgb)
+    return (mx - mn) >= 0.15 and mx >= 0.12
+
+
+def _recolor_object_phrase(prompt: str, target_word: str) -> str:
+    """Best-effort object description for the mask ("red car" in 'the red car')."""
+    m = re.search(
+        r"\b(?:make|recolou?r|change|turn|convert|paint|colou?r)\b\s+(?:only\s+)?(.+)",
+        prompt, re.I,
+    )
+    phrase = (m.group(1) if m else prompt).strip()
+    if target_word:
+        phrase = re.sub(r"\b" + re.escape(target_word) + r"\b", " ", phrase,
+                        count=1, flags=re.I)
+    phrase = re.sub(r"\s+", " ", phrase).strip(" .,!?")
+    phrase = re.sub(r"^(?:to|into|the|a|an)\s+", "", phrase, flags=re.I).strip()
+    phrase = re.sub(r"\s+(?:to|into)$", "", phrase, flags=re.I).strip()
+    while phrase and _RECOLOR_TRAILING_ADJ.search(phrase):
+        phrase = _RECOLOR_TRAILING_ADJ.sub("", phrase).strip()
+    return phrase or "the subject"
+
+
+def recolor_plan(prompt: str) -> Optional[Dict[str, Any]]:
+    """Deterministic plan for a targeted recolour, or None.
+
+    'make only the red car blue' -> select the OBJECT by description
+    (``selection.samText`` "red car"; falling back to a colour-range selection
+    via ``fallbackColor`` when the mask is empty) and then shift the MASKED
+    HUE toward the target with ``adjustments.applyMasked`` (preserving shading,
+    highlights and reflections). Never a flat ``selection.fill`` and never a
+    whole-image ``adjustments.apply`` tint. When the target cannot be reached by
+    a hue rotation (white/black/grey) or no source colour is known, the masked
+    region is recoloured with ``ai_edit_image`` instruction mode instead.
+    """
+    p = str(prompt or "")
+    if not _RECOLOR_ACTION_RE.search(p):
+        return None
+    if _RECOLOR_EXCLUDE_RE.search(p):
+        return None
+    colors = [m.group(1).lower() for m in
+              re.finditer(r"\b" + _COLOR_TOKEN + r"\b", p)]
+    colors = [c for c in colors if color_for_name(c)]
+    if not colors:
+        return None
+    target = colors[-1]
+    tgt_hex = color_for_name(target)
+    source = colors[0] if len(colors) >= 2 and colors[0] != target else None
+    src_hex = color_for_name(source) if source else None
+    phrase = _recolor_object_phrase(p, target)
+    select = {
+        "op": "selection.samText",
+        "params": {"text": phrase},
+    }
+    if src_hex:
+        select["params"]["fallbackColor"] = src_hex
+        select["params"]["fallbackFuzziness"] = 40
+    if source and src_hex and _is_chromatic(tgt_hex):
+        delta = _hue_delta(src_hex, tgt_hex)
+        src_hue = int(round(_hue_degrees(src_hex) or 0))
+        return {
+            "reply": "Selected the %s and shifted its hue toward %s "
+                     "(shading kept)." % (phrase, target),
+            "planner": "deterministic",
+            "steps": [
+                select,
+                {"op": "adjustments.applyMasked",
+                 "params": {"hue": delta, "saturation": 0,
+                            "mode": "hue-saturation",
+                            "sourceHue": src_hue,
+                            "source": src_hex, "target": tgt_hex}},
+            ],
+        }
+    instruction = ("Recolour the %s to %s, preserving its shading, highlights "
+                   "and reflections." % (phrase, target))
+    return {
+        "reply": "Recolouring the %s with the image model." % phrase,
+        "planner": "deterministic",
+        "steps": [
+            select,
+            {"op": "ai_edit_image",
+             "params": {"op": "inpaint", "mode": "masked",
+                        "prompt": instruction, "steps": 8}},
+        ],
+    }
+
+
+def structural_plan(prompt: str) -> Optional[Dict[str, Any]]:
+    """Deterministic plan for structural editor ops, or None.
+
+    Covers fill/flood, text.edit, colour-overlay layer style, layer align,
+    layer/document rotate+flip, selection copy/paste, flatten and merge-down.
+    Also dispatches named reference looks and targeted recolours.
+    Returns ``{"reply", "planner": "deterministic", "steps": [...]}``.
+    """
+    look = look_plan(prompt)
+    if look is not None:
+        return look
+    recolor = recolor_plan(prompt)
+    if recolor is not None:
+        return recolor
+    p = str(prompt or "").lower()
+    steps: List[Dict[str, Any]] = []
+    labels: List[str] = []
+
+    fm = (re.search(r"\bfill\b[^.]*?\bwith\s+" + _COLOR_TOKEN + r"\b", p)
+          or re.search(r"\bfill\b[^.]*?\b" + _COLOR_TOKEN + r"\b", p))
+    if fm:
+        color = color_for_name(fm.group(1))
+        if color:
+            if re.search(r"\bselection\b|\bselected\b", p):
+                steps.append({"op": "selection.fill", "params": {"color": color}})
+                labels.append("filled the selection")
+            else:
+                steps.append({"op": "fill.flood",
+                              "params": {"color": color, "x": 0, "y": 0}})
+                labels.append("flood-filled the layer")
+
+    if re.search(r"\b(text|title|caption|font|label)\b", p) and not re.search(
+            r"\b(add|insert|create|write|put|place)\b", p):
+        tparams: Dict[str, Any] = {}
+        if re.search(r"\b(bigger|larger|increase)\b", p):
+            tparams["size"] = 96
+        elif re.search(r"\b(smaller|reduce|decrease)\b", p):
+            tparams["size"] = 28
+        cm = re.search(r"\b" + _COLOR_TOKEN + r"\b", p)
+        if cm:
+            c = color_for_name(cm.group(1))
+            if c:
+                tparams["color"] = c
+        if tparams:
+            steps.append({"op": "text.edit", "params": tparams})
+            labels.append("updated the text layer")
+
+    if re.search(r"\bcolo?ur?\s*overlay\b", p):
+        steps.append({"op": "layers.addStyle",
+                      "params": {"type": "color-overlay", "params": {}}})
+        labels.append("added a colour-overlay layer style")
+
+    am = re.search(
+        r"\balign\b[^.]*?\b(centre|center|left|right|top|middle|bottom)\b", p)
+    if am:
+        mode = "center" if am.group(1) in ("centre", "center") else am.group(1)
+        steps.append({"op": "layers.align", "params": {"mode": mode}})
+        labels.append("aligned to the %s" % mode)
+
+    whole = bool(re.search(
+        r"\b(?:whole|entire|full)\s+(?:image|canvas|photo|picture|document)\b", p)) \
+        or bool(re.search(r"\b(?:canvas|document)\b", p)
+                  and re.search(r"\b(?:rotate|flip|mirror|turn)\b", p))
+    if re.search(r"\b(?:flip|mirror)\b", p):
+        axis = "v" if re.search(r"\b(?:vertical(?:ly)?|v)\b", p) else "h"
+        if whole:
+            steps.append({"op": "document.flip", "params": {"axis": axis}})
+            labels.append("flipped the whole image")
+        else:
+            steps.append({"op": "layer.flip", "params": {"axis": axis}})
+            labels.append("flipped the layer")
+    # Rotation needs an explicit angle/quarter-turn or the verb "rotate"; a bare
+    # "turn ... into <style>" (e.g. "turn this into an anime") is a restyle, not
+    # a rotation.
+    rotate_deg = None
+    rm = re.search(r"\b(?:rotate|turn)\b[^\d]*?\b(90|180|270)\b", p)
+    if rm:
+        rotate_deg = int(rm.group(1))
+    elif re.search(r"\brotate\b", p):
+        rotate_deg = 90
+    if rotate_deg is not None:
+        degrees = rotate_deg
+        if whole:
+            steps.append({"op": "document.rotate", "params": {"degrees": degrees}})
+            labels.append("rotated the whole image %d\u00b0" % degrees)
+        else:
+            steps.append({"op": "layer.rotate", "params": {"degrees": degrees}})
+            labels.append("rotated the layer %d\u00b0" % degrees)
+
+    if re.search(r"\bcopy\b", p) and re.search(r"\bselection\b|\bselected\b", p):
+        steps.append({"op": "selection.copy", "params": {}})
+        labels.append("copied the selection")
+    if re.search(r"\bpaste\b", p) and not re.search(r"\bflatten\b|\bmerge\b", p):
+        steps.append({"op": "selection.paste", "params": {}})
+        labels.append("pasted as a new layer")
+
+    if re.search(r"\bflatten\b", p):
+        steps.append({"op": "layers.flatten", "params": {}})
+        labels.append("flattened the image")
+    elif re.search(r"\bmerge\b", p) and re.search(r"\bdown\b|\blayer\b", p):
+        steps.append({"op": "layers.mergeDown", "params": {}})
+        labels.append("merged the layer down")
+
+    if not steps:
+        return None
+    return {
+        "reply": "Done \u2014 I " + ", ".join(labels) + ".",
+        "planner": "deterministic",
+        "steps": steps,
+    }
+
+
+def _is_global_lift(step: Any) -> bool:
+    if not isinstance(step, dict):
+        return False
+    op = step.get("op")
+    params = step.get("params") or {}
+    if op == "photo.autoTone":
+        return True
+    if op != "adjustments.apply":
+        return False
+    kind = params.get("type")
+    if kind not in GLOBAL_LIFT_TYPES:
+        return False
+    inner = params.get("params") or {}
+    if kind == "brightness-contrast":
+        return float(inner.get("brightness") or 0) > 0
+    if kind == "exposure":
+        return float(inner.get("exposure") or 0) > 0
+    return True
+
+
+def _is_shadows_highlights(step: Any) -> bool:
+    if not isinstance(step, dict) or step.get("op") != "adjustments.apply":
+        return False
+    params = step.get("params") or {}
+    return params.get("type") == "shadows-highlights"
+
+
+def _is_masked_recolor(step: Any) -> bool:
+    """True for a masked hue-saturation recolour step.
+
+    Such a step already targets the object's own colour, so no whole-image
+    global adjustment may follow it (it would double-process the photo and
+    undo the "only this object" intent).
+    """
+    if not isinstance(step, dict) or step.get("op") != "adjustments.applyMasked":
+        return False
+    params = step.get("params") or {}
+    if params.get("mode") == "hue-saturation":
+        return True
+    hue = params.get("hue")
+    return hue not in (None, 0, 0.0)
+
+
+def _is_whole_image_adjustment(step: Any) -> bool:
+    """True for a whole-image tone/colour adjustment (never selection-scoped).
+
+    ``adjustments.apply`` acts on the entire layer and ``photo.autoTone`` on the
+    whole photo, so after a masked recolour either one re-grades everything and
+    undoes the "only this object" intent — drop both regardless of type
+    (a non-lift grade such as vibrance/saturation would otherwise survive the
+    low-key guard).
+    """
+    if not isinstance(step, dict):
+        return False
+    return step.get("op") in ("photo.autoTone", "adjustments.apply")
+
+
+def collapse_global_lifts(steps: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+    """Enforce the low-key rule: at most one global lift, never a stack.
+
+    A single auto-tone pass (``photo.autoTone``) is the preferred global lift;
+    it may be paired with ONE shadow-lifting, highlight-protecting adjustment.
+    Any further global lift (a second auto tone, a brightness/exposure lift, or
+    an extra shadows-highlights) is dropped. When there is no auto tone, two or
+    more global lifts collapse to a single safe shadows-highlights step and a
+    lone brightness/exposure lift is clamped so it cannot blow out highlights.
+    """
+    if not steps:
+        return steps
+    lifts = [i for i, step in enumerate(steps) if _is_global_lift(step)]
+    auto = [i for i in lifts if steps[i].get("op") == "photo.autoTone"]
+    if auto:
+        other = [i for i in lifts if i not in auto]
+        keep_other = other[0] if len(other) == 1 and _is_shadows_highlights(steps[other[0]]) else None
+        drop = set(auto[1:]) | (set(other) - ({keep_other} if keep_other is not None else set()))
+        if drop:
+            return [step for i, step in enumerate(steps) if i not in drop]
+        return steps
+    if len(lifts) >= 2:
+        drop = set(lifts)
+        out = [step for i, step in enumerate(steps) if i not in drop]
+        insert_at = min(lifts[0], len(out))
+        out.insert(insert_at, json.loads(json.dumps(_SAFE_LOWKEY_LIFT)))
+        return out
+    if len(lifts) == 1:
+        step = steps[lifts[0]]
+        params = step.get("params") or {}
+        if step.get("op") == "adjustments.apply":
+            inner = params.get("params") or {}
+            if params.get("type") == "brightness-contrast":
+                inner["brightness"] = min(float(inner.get("brightness") or 0), 25.0)
+                params["params"] = inner
+                step["params"] = params
+            elif params.get("type") == "exposure":
+                inner["exposure"] = min(float(inner.get("exposure") or 0), 30.0)
+                params["params"] = inner
+                step["params"] = params
+    return steps
+
+
+def _clone(step: Any) -> Any:
+    return json.loads(json.dumps(step))
+
+
+def enforce_guards(steps: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+    """Apply every planner-side safety rule so the client rarely has to undo.
+
+    * at most one global lift, never a stack (``collapse_global_lifts``);
+    * never a global brightness lift AFTER ``retouch.skin`` (the client's
+      "never brighten skin" guard), which also removes a trailing autoTone.
+    """
+    steps = collapse_global_lifts(steps)
+    out: List[Dict[str, Any]] = []
+    skin_seen = False
+    for step in steps:
+        op = step.get("op") if isinstance(step, dict) else None
+        if op == "retouch.skin":
+            skin_seen = True
+            out.append(step)
+            continue
+        if skin_seen and _is_global_lift(step):
+            continue
+        out.append(step)
+    # Never append a global adjustment after a masked recolour: the recolour is
+    # already scoped to the object, so a following whole-image lift would undo
+    # the intent and double-process the image.
+    recolored = False
+    guarded: List[Dict[str, Any]] = []
+    for step in out:
+        if _is_masked_recolor(step):
+            recolored = True
+            guarded.append(step)
+            continue
+        if recolored and (_is_global_lift(step) or _is_whole_image_adjustment(step)):
+            continue
+        guarded.append(step)
+    return guarded
+
+
+def strengthen(prompt: str, steps: Optional[List[Dict[str, Any]]]) -> List[Dict[str, Any]]:
+    """Promote a timid model plan to the guide recipe for the matched intent.
+
+    The sampling LLM frequently returns a single mild ``adjustments.apply`` for
+    generic intents (make it pretty / pop / professional / film look) and for
+    skin/restore, which grade as imperceptible. When the plan is shorter than
+    the recipe's ``min_steps`` the deterministic recipe is used instead.
+    """
+    steps = list(steps or [])
+    route = match(prompt)
+    if not route:
+        return steps
+    recipe = route.get("steps") or []
+    try:
+        min_steps = int(route.get("min_steps") or len(recipe))
+    except (TypeError, ValueError):
+        min_steps = len(recipe)
+    # The guide is authoritative for a matched intent: keep the model plan only
+    # when it already contains every recipe op (with multiplicity) and is at
+    # least ``min_steps`` long. Otherwise the model substituted weaker/different
+    # ops (e.g. three global adjustments with no photo.autoTone/white-balance for
+    # "restore"), so the calibrated recipe is used. The signature distinguishes
+    # adjustments by type and filters by id, so a plain brightness-contrast does
+    # not masquerade as the recipe's white-balance.
+    recipe_ops = Counter(_step_signature(step) for step in recipe)
+    plan_ops = Counter(_step_signature(step) for step in steps)
+    if len(steps) < min_steps or (plan_ops & recipe_ops) != recipe_ops:
+        return [_clone(step) for step in recipe]
+    return steps
+
+
+def _step_signature(step: Any) -> str:
+    if not isinstance(step, dict):
+        return ""
+    op = str(step.get("op") or "")
+    params = step.get("params") or {}
+    if not isinstance(params, dict):
+        params = {}
+    if op in ("adjustments.apply", "adjustments.applyMasked"):
+        return op + ":" + str(params.get("type") or "")
+    if op in ("filters.apply", "filters.applyMasked"):
+        return op + ":" + str(params.get("id") or "")
+    return op
+
+
+def guidance() -> str:
+    """The routing/style block injected into every planner system prompt."""
+    ops = "; ".join(
+        "{op} {params}".format(op=o["op"], params=json.dumps(o["params"]))
+        for o in NEW_OPS
+    )
+    return (
+        "Style guide v" + str(STYLE_GUIDE_VERSION) + " (single source of truth; "
+        "the browser fallback reads the same rules). New ops with canonical params: "
+        + ops + ". Clarity and vignette are filters.apply ids "
+        "(filters.apply {id:'clarity',amount,radius} and {id:'vignette',amount,feather}). "
+        "Generic 'make it look good' ('make it pretty', 'make it pop', 'make it look "
+        "professional', 'film look', 'instagram ready'): a decisive 3-4 step grade, "
+        "never one mild adjustment: photo.autoTone -> adjustments.apply vibrance "
+        "{vibrance:20-30} -> filters.apply {id:'clarity'} -> optional filters.apply "
+        "{id:'vignette'}. "
+        "Portrait / look-better ('fix the skin', 'make me look better', 'fix my "
+        "teeth'): do NOT lead with photo.autoTone — a whole-image auto tone washes out "
+        "the face. Go straight to selection.face (or selection.subject "
+        "{label:'person'}) -> retouch.skin {smooth<=14, opacity<=0.45} -> "
+        "selection.deselect (teeth: selection.face -> retouch.teeth). Keep the retouch "
+        "gentle and never brighten the face; only add a global photo.autoTone when the "
+        "photo is genuinely under- or over-exposed, and NEVER a global brightness lift "
+        "AFTER retouch.skin. "
+        "'restore this old photo': photo.autoTone -> brightness-contrast "
+        "{brightness:0,contrast:~18} -> white-balance/tint -> vibrance {~18} -> "
+        "sharpen; recover contrast + colour from the faded baseline and NEVER apply a "
+        "large exposure lift. "
+        "Low-key / 'fix the lighting' on a dark image: photo.autoTone PLUS at most "
+        "ONE adjustments.apply shadows-highlights {shadows:30,highlights:-15} that "
+        "protects highlights; NEVER stack a second autoTone/brightness/exposure/"
+        "levels/shadows-highlights, and keep highlights <= 0. "
+        "Temperature sign: moody/cooler/cinematic/teal -> white-balance temperature "
+        "NEGATIVE; warmer/golden/summer/sunset -> POSITIVE. "
+        "Background softer / 'blur the background' -> selection.background then "
+        "filters.applyMasked {id:'blur-gaussian'}; never a plain global blur. "
+        "GENERATIVE CONTENT: Qwen-Image-Edit is an instruction model, so most "
+        "generative edits use ai_edit_image mode='instruction' on the WHOLE image "
+        "with NO mask and a prompt that NAMES what must stay unchanged (e.g. "
+        "'replace the background with a sunny beach, keep the woman exactly the "
+        "same'). Use instruction mode for: replacing/changing the background or "
+        "scene ('put her on a beach', 'change the background to night'), changing "
+        "the season or weather ('make it snowy', 'make it autumn', 'make it rainy', "
+        "'add fog'), adding an object or element to an existing photo ('add a full "
+        "moon in the sky', 'add wildflowers', 'add sunglasses to her', 'add a "
+        "rainbow', 'add clouds'), an explicit 'generative fill' ('generative fill "
+        "the sky'), and removing diffuse distractions ('remove the "
+        "distractions'). These are CONTENT changes, never adjustments.apply/filters. "
+        "Use 8 sampler steps for these generative content edits. Use ai_edit_image "
+        "mode='masked' ONLY for an explicit "
+        "regional removal of a clearly identified object ('remove the person on "
+        "the left') — select that object first so the mask is tight, then inpaint; "
+        "if the mask comes back tiny or empty, fall back to instruction mode. "
+        "generate_image is ONLY for creating a brand-new image ('create a new "
+        "image of ...', 'make a logo') — NEVER use it to add content to an "
+        "existing photo, and never place its output as an opaque full layer over "
+        "a photo. "
+        "Canvas format ('instagram post', '1080x1350', '4:5', 'square', '9:16', '16:9'): "
+        "document.crop {x,y,width,height} to the target aspect, then document.resizeCanvas "
+        "{width,height,anchor:'center'}; never just export/resize and claim success. To "
+        "EXTEND ('extend the canvas to 16:9', 'make it wider'): ai.generativeExpand "
+        "{width,height,anchor:'center',prompt,mode:'instruction',feather:true} when an "
+        "image provider is configured — pad the canvas, keep the ORIGINAL pixels opaque on "
+        "top, inpaint ONLY the new border with a prompt that continues the scene ('extend "
+        "the sky and clouds'), and feather the seam; else document.resizeCanvas "
+        "{width,height,anchor:'center'} and say honestly that the new border was extended "
+        "with edge/transparent pixels. "
+        "Text ('add a title TOKYO', 'add a caption', 'with a drop shadow'): text.add "
+        "{text,x,y,color,size} plus layers.addStyle {type:'drop-shadow'}; text and layer "
+        "styles are NOT generative and must never return the needs-provider message. "
+        "'save as PSD' / 'layered PSD': document.savePsd. "
+        "Structural ops (use the exact op, never a generic adjustment/transform): "
+        "'fill ... with <colour>' -> selection.fill {color} when a selection is named, "
+        "else fill.flood {color,x:0,y:0}; 'make the text bigger/smaller' or 'make the "
+        "title <colour>' -> text.edit {size,color}; a 'colour overlay' -> layers.addStyle "
+        "{type:'color-overlay'}; 'align ... left/centre/right/top/middle/bottom' -> "
+        "layers.align {mode}; 'rotate/flip this layer' -> layer.rotate {degrees} / "
+        "layer.flip {axis}, but 'rotate/flip the whole image/canvas/photo' -> "
+        "document.rotate {degrees} / document.flip {axis}; 'copy the selection' -> "
+        "selection.copy, 'paste' -> selection.paste; 'flatten the image' -> "
+        "layers.flatten; 'merge the layer down' -> layers.mergeDown. "
+        "Targeted recolour ('make only the red car blue', 'recolour the red rock to "
+        "teal', 'change the yellow car to red'): select the OBJECT by description with "
+        "selection.samText {text:'red car'} (carry fallbackColor {source hex} so the "
+        "client falls back to a colour-range selection only if the mask is empty), then "
+        "recolour the masked region with adjustments.applyMasked {hue:<source->target "
+        "hue delta in degrees>, saturation:0, mode:'hue-saturation'} so shading, "
+        "highlights and reflections are preserved. NEVER selection.fill (a flat fill "
+        "destroys shading) and NEVER a whole-image adjustments.apply tint. If the "
+        "target cannot be reached by a hue rotation (white/black/grey) or no source "
+        "colour is named ('make the flowers bright pink'), select the object the same "
+        "way and recolour the masked region with ai_edit_image mode='masked'. "
+        "Named reference look ('make it look like a Wes Anderson film', 'film noir', "
+        "'vintage Kodachrome'): apply the matching look recipe — Wes Anderson = pastel "
+        "+ warm highlights + soft contrast; film noir = high-contrast black and white "
+        "with deep shadows + a vignette; Kodachrome = warm saturated colour + contrast "
+        "+ a light vignette. Strong styles ('cyberpunk', 'Studio Ghibli') use "
+        "ai_edit_image mode='instruction' with a prompt that restyles the scene and "
+        "keeps the subject; never a generic single adjustment. "
+        "A vague prompt with no concrete defect ('clean this up') -> return "
+        "{\"reply\": <question>, \"steps\": [], \"ask_user\": {\"question\": <q>, "
+        "\"options\": [{\"label\":..,\"description\":..}, ...]}} with 2-3 concrete "
+        "options (auto tone / brighten / cool) instead of guessing."
+    )
+
+
+def as_json() -> Dict[str, Any]:
+    """The serialisable guide served to the browser client."""
+    return {
+        "version": STYLE_GUIDE_VERSION,
+        "new_ops": NEW_OPS,
+        "intents": [
+            {"id": r["id"], "keywords": r["keywords"], "steps": r["steps"],
+             "reply": r["reply"]}
+            for r in INTENT_ROUTES
+        ],
+        "looks": [
+            {"id": lk["id"], "keywords": lk["keywords"],
+             "mode": lk.get("mode"), "reply": lk["reply"],
+             **({"steps": lk["steps"]} if lk.get("steps") else {}),
+             **({"prompt": lk["prompt"]} if lk.get("prompt") else {})}
+            for lk in LOOKS
+        ],
+        "ambiguous_options": [dict(o) for o in _AMBIGUOUS_OPTIONS],
+        "rules": {
+            "low_key": "At most one global lift; prefer shadows-highlights; "
+                       "never stack; protect highlights.",
+            "temperature_sign": "cool/moody/cinematic -> negative; "
+                                "warm/golden/summer -> positive.",
+            "portrait": "No leading photo.autoTone (only if the photo is actually "
+                        "under/over-exposed): selection.face -> retouch.skin "
+                        "{smooth<=14, opacity<=0.45} -> selection.deselect; teeth: "
+                        "selection.face -> retouch.teeth; never brighten the face, "
+                        "never a global brightness lift AFTER retouch.skin.",
+            "generic_look": "make it pretty/pop/professional/film -> decisive 3-4 "
+                            "steps: photo.autoTone -> vibrance 20-30 -> clarity -> "
+                            "optional vignette.",
+            "restore": "old/faded photo -> photo.autoTone + contrast (brightness 0) "
+                       "+ white-balance/tint + vibrance + slight sharpen; never a "
+                       "large exposure lift.",
+            "format": "aspect request -> document.crop to the aspect then "
+                      "document.resizeCanvas; extend -> pad canvas, keep the "
+                      "original opaque on top, ai.generativeExpand (mode "
+                      "instruction, feather the seam) inpaints ONLY the new border "
+                      "when a provider exists else document.resizeCanvas (honest "
+                      "edge fill).",
+            "generative_content": "Most generative edits use ai_edit_image "
+                      "mode='instruction' on the WHOLE image (no mask, 8 steps) with a "
+                      "prompt naming what stays unchanged: background/scene replace, "
+                      "season/weather change (snowy/autumn/rain/fog), adding an "
+                      "object/element (wildflowers, sunglasses, rainbow, clouds), an "
+                      "explicit 'generative fill', removing diffuse distractions. "
+                      "mode='masked' ONLY for explicit regional "
+                      "removal of a clearly identified object ('remove the person on "
+                      "the left') — select it first, tight mask, fall back to "
+                      "instruction if the mask is tiny/empty. generate_image ONLY for "
+                      "creating a brand-new image; never use it to add content to a "
+                      "photo or place it as an opaque full layer.",
+            "text": "text.add (+ layers.addStyle drop-shadow); never generative, never "
+                    "the needs-provider message.",
+            "psd": "'save as PSD' -> document.savePsd.",
+            "structural": "Exact ops, never a generic adjustment: fill -> selection.fill "
+                    "(selection) or fill.flood {color,x,y}; existing text size/colour -> "
+                    "text.edit; colour overlay -> layers.addStyle {type:'color-overlay'}; "
+                    "align -> layers.align {mode}; rotate/flip the active layer -> "
+                    "layer.rotate/layer.flip, the whole image/canvas -> document.rotate/"
+                    "document.flip; copy/paste the selection -> selection.copy/paste; "
+                    "flatten -> layers.flatten; merge down -> layers.mergeDown.",
+            "recolor": "targeted recolour -> selection.samText {text:<object>, "
+                    "fallbackColor:<source hex>} then adjustments.applyMasked "
+                    "{hue:<source->target hue delta>, saturation:0, "
+                    "mode:'hue-saturation'} (preserves shading; colour-range fallback "
+                    "only if the mask is empty); white/black/grey or no source colour "
+                    "-> ai_edit_image mode:'masked'. Never selection.fill; never a "
+                    "whole-image adjustments.apply tint.",
+            "looks": "named look -> recipe (Wes Anderson pastel/warm/soft; film noir "
+                    "high-contrast B&W + vignette; Kodachrome warm saturated + vignette) "
+                    "or ai_edit_image instruction (cyberpunk, Studio Ghibli); never a "
+                    "generic single adjustment.",
+            "ambiguous": "ask_user with 2-3 concrete options.",
+        },
+        "guidance": guidance(),
+    }
diff --git a/src/fixture_email.py b/src/fixture_email.py
index 9ac248694..42098131c 100644
--- a/src/fixture_email.py
+++ b/src/fixture_email.py
@@ -68,6 +68,7 @@ def _row(index: int, message: dict[str, Any]) -> dict[str, Any]:
         })
     return {
         "uid": str(message.get("uid") or _uid(index)),
+        "message_id": str(message.get("message_id") or ""),
         "account": str(message.get("account") or "fixture"),
         "account_email": str(message.get("account_email") or message.get("to") or ""),
         "account_id": str(message.get("account_id") or "fixture"),
@@ -78,6 +79,16 @@ def _row(index: int, message: dict[str, Any]) -> dict[str, Any]:
         "folder": str(message.get("folder") or "INBOX"),
         "attachments": attachments,
         "has_attachments": bool(attachments),
+        "summary": str(message.get("summary") or message.get("body") or ""),
+    }
+
+
+def _account_matches(message: dict[str, Any], account: str | None) -> bool:
+    selector = str(account or "").strip().casefold()
+    return not selector or selector in {
+        str(message.get("account") or "fixture").strip().casefold(),
+        str(message.get("account_email") or message.get("to") or "").strip().casefold(),
+        str(message.get("account_id") or "fixture").strip().casefold(),
     }
 
 
@@ -108,9 +119,16 @@ def execute_fixture_email(tool: str, args: dict[str, Any], owner: str | None = N
 
     bare = tool.removeprefix("mcp__email__")
     if bare == "list_email_accounts":
+        accounts = {}
+        for index, message in enumerate(messages):
+            row = _row(index, message)
+            identity = (row["account_id"], row["account"], row["account_email"])
+            accounts.setdefault(identity, {"id": row["account_id"], "name": row["account"],
+                                            "email": row["account_email"], "default": not accounts})
         return {
-            "accounts": [{"id": "fixture", "name": "Fixture mailbox", "default": True}],
-            "output": "Fixture mailbox (default)",
+            "accounts": list(accounts.values()),
+            "output": "\n".join(f"{row['name']} <{row['email']}> ({row['id']})" for row in accounts.values())
+                      or "No fixture email accounts found.",
             "exit_code": 0,
         }
 
@@ -121,14 +139,7 @@ def execute_fixture_email(tool: str, args: dict[str, Any], owner: str | None = N
         rows = [
             _row(i, m) for i, m in enumerate(messages)
             if _matches(m, query) and _folder_matches(m.get("folder"), folder)
-            and (
-                not account
-                or account in {
-                    str(m.get("account") or "").strip().casefold(),
-                    str(m.get("account_email") or "").strip().casefold(),
-                    str(m.get("account_id") or "").strip().casefold(),
-                }
-            )
+            and _account_matches(m, account)
         ]
         limit = args.get("max_results", args.get("limit", 20))
         try:
@@ -139,11 +150,7 @@ def execute_fixture_email(tool: str, args: dict[str, Any], owner: str | None = N
             return {"output": "No emails found.", "emails": [], "exit_code": 0}
         output_lines = [f"Found {len(rows)} email(s):", ""]
         for index, r in enumerate(rows, start=1):
-            source = next(
-                (m for i, m in enumerate(messages) if _uid(i) == r["uid"]),
-                {},
-            )
-            summary = str(source.get("summary") or source.get("body") or "").strip()
+            summary = r["summary"].strip()
             output_lines.extend([
                 f"{index}. **{r['subject']}**",
                 f"   From: {r['from']}",
@@ -159,15 +166,19 @@ def execute_fixture_email(tool: str, args: dict[str, Any], owner: str | None = N
 
     if bare == "read_email":
         uid = str(args.get("uid") or "")
+        message_id = str(args.get("message_id") or "")
         folder = str(args.get("folder") or "INBOX")
-        try:
-            index = int(uid) - 1
-        except (TypeError, ValueError):
-            index = -1
-        if index < 0 or index >= len(messages) or not _folder_matches(messages[index].get("folder"), folder):
-            return {"error": f"Email UID {uid} not found.", "exit_code": 1}
-        message = messages[index]
-        row = _row(index, message)
+        if not uid and not message_id:
+            return {"error": "read_email requires a UID or Message-ID.", "exit_code": 1}
+        matches = [(m, _row(i, m)) for i, m in enumerate(messages)
+                   if _folder_matches(m.get("folder"), folder) and _account_matches(m, args.get("account"))
+                   and (not uid or str(m.get("uid") or _uid(i)) == uid)
+                   and (not message_id or str(m.get("message_id") or "") == message_id)]
+        if not matches:
+            return {"error": f"Email UID/Message-ID {uid or message_id} not found.", "exit_code": 1}
+        if len(matches) != 1:
+            return {"error": "Email identity is ambiguous; specify its account and folder.", "exit_code": 1}
+        message, row = matches[0]
         output = (
             f"UID: {row['uid']}\nSubject: {row['subject']}\nFrom: {row['from']}\n"
             f"Date: {row['date']}\n\n{message.get('body') or ''}"
@@ -185,6 +196,7 @@ def execute_fixture_email(tool: str, args: dict[str, Any], owner: str | None = N
         all_messages = _messages()
         owner_value = str(owner or "").strip()
         visible_index = -1
+        matches = []
         for original in all_messages:
             if owner_value and original.get("owner") and original.get("owner") != owner_value:
                 continue
@@ -193,6 +205,13 @@ def execute_fixture_email(tool: str, args: dict[str, Any], owner: str | None = N
                 continue
             if not _folder_matches(original.get("folder"), folder):
                 continue
+            if not _account_matches(original, args.get("account")):
+                continue
+            matches.append(original)
+        if len(matches) > 1:
+            return {"error": "Email identity is ambiguous; specify its account and folder.", "exit_code": 1}
+        if matches:
+            original = matches[0]
             if bare == "archive_email":
                 original["folder"] = "Archive"
                 action = "Archived"
diff --git a/src/shutdown.py b/src/shutdown.py
new file mode 100644
index 000000000..800b3baa5
--- /dev/null
+++ b/src/shutdown.py
@@ -0,0 +1,34 @@
+"""Process-wide shutdown signalling for graceful restarts.
+
+Server-Sent-Events / streaming responses never complete on their own, so
+uvicorn's graceful shutdown would wait for an open browser stream up to the
+full ``timeout_graceful_shutdown`` window before exiting. A SIGTERM/SIGINT
+handler flips this flag and tells uvicorn to exit; every streaming generator
+checks the flag on each loop and ends promptly, so a restart completes in
+seconds while ordinary in-flight requests still finish.
+"""
+from __future__ import annotations
+
+import logging
+import threading
+
+logger = logging.getLogger(__name__)
+
+_SHUTTING_DOWN = threading.Event()
+
+
+def is_shutting_down() -> bool:
+    """True once a shutdown (SIGTERM/SIGINT) has been requested."""
+    return _SHUTTING_DOWN.is_set()
+
+
+def request_shutdown() -> None:
+    """Mark the process as shutting down (idempotent)."""
+    if not _SHUTTING_DOWN.is_set():
+        _SHUTTING_DOWN.set()
+        logger.info("shutdown requested; streaming responses will end promptly")
+
+
+def reset() -> None:
+    """Clear the flag (for tests)."""
+    _SHUTTING_DOWN.clear()
diff --git a/src/tools/image.py b/src/tools/image.py
index 5150e377d..0a6c3698b 100644
--- a/src/tools/image.py
+++ b/src/tools/image.py
@@ -16,7 +16,7 @@ from typing import Dict, Optional
 from src.tools._common import _parse_tool_args
 
 
-async def do_edit_image(content: str, owner: Optional[str] = None) -> Dict:
+async def do_edit_image(content: str, owner: Optional[str] = None, *, incognito: bool = False) -> Dict:
     """Create an owner-scoped edited copy of a gallery image."""
     try:
         args = _parse_tool_args(content)
@@ -45,7 +45,7 @@ async def do_edit_image(content: str, owner: Optional[str] = None) -> Dict:
         if not load_settings().get('image_gen_enabled', True):
             return {'error': 'Image generation is disabled by the administrator.', 'exit_code': 1}
         from src.ai_interaction import do_edit_image as edit_with_model
-        return await edit_with_model(str(args.get('prompt') or '').strip(), info['path'], owner=owner, size='auto')
+        return await edit_with_model(str(args.get('prompt') or '').strip(), info['path'], owner=owner, size='auto', incognito=incognito)
 
     from core.database import GalleryImage, SessionLocal
     from src.constants import GENERATED_IMAGES_DIR
@@ -79,7 +79,7 @@ async def do_edit_image(content: str, owner: Optional[str] = None) -> Dict:
             session_id = source.session_id
             db.close()
             from src.ai_interaction import do_edit_image as edit_with_model
-            return await edit_with_model(prompt, str(source_path), session_id=session_id, owner=owner, size='auto')
+            return await edit_with_model(prompt, str(source_path), session_id=session_id, owner=owner, size='auto', incognito=incognito)
 
         from PIL import Image
 
@@ -111,6 +111,16 @@ async def do_edit_image(content: str, owner: Optional[str] = None) -> Dict:
             output_bytes = output.getvalue()
             width, height = image.size
 
+        if incognito:
+            import base64
+            return {
+                'output': f'Image edited ({action}). Private result, not saved to gallery.',
+                'exit_code': 0, 'image_id': None,
+                'image_url': 'data:image/png;base64,' + base64.b64encode(output_bytes).decode('ascii'),
+                'image_prompt': source.prompt or action, 'image_model': f'edit_image:{action}',
+                'image_size': f'{width}x{height}', 'image_quality': source.quality or '',
+            }
+
         root.mkdir(parents=True, exist_ok=True)
         filename = f"{uuid.uuid4().hex[:12]}.png"
         (root / filename).write_bytes(output_bytes)
diff --git a/src/upload_handler.py b/src/upload_handler.py
index 0d0a14065..ce87120d0 100644
--- a/src/upload_handler.py
+++ b/src/upload_handler.py
@@ -63,80 +63,19 @@ INTERNAL_UPLOAD_URL_RE = re.compile(
     r"([0-9a-fA-F]{32}(?:\.[A-Za-z0-9]+)?)"
     r"(?=$|[\s\"'<>\[\](){},;!?:&#]|\.(?![A-Za-z0-9]))"
 )
-# `<!--\s*pdf(?:_form)?_source\b[^>]*\bupload_id=["'](id)["'][^>]*-->` and
-# `\[Attachment:[^\]\r\n]*\|\s*id=(id)(?:\s*\||\s*\])` are matched by the
-# forward-only scanners below. As single regexes, every opener in a run with no
-# closing `>` / `]` rescanned to the end of that run: O(n^2) on chat content,
-# which is unbounded on persisted assistant output (CodeQL py/polynomial-redos).
-_PDF_SOURCE_OPEN_RE = re.compile(r"<!--\s*pdf(?:_form)?_source\b", re.IGNORECASE)
-_PDF_SOURCE_ID_RE = re.compile(
-    r"\bupload_id=[\"']([0-9a-fA-F]{32}(?:\.[A-Za-z0-9]+)?)[\"']",
+PDF_SOURCE_UPLOAD_RE = re.compile(
+    r"<!--\s*pdf(?:_form)?_source\b[^>]*\bupload_id="
+    r"[\"']([0-9a-fA-F]{32}(?:\.[A-Za-z0-9]+)?)[\"'][^>]*-->",
     re.IGNORECASE,
 )
-_ATTACHMENT_REFERENCE_OPEN_RE = re.compile(r"\[Attachment:", re.IGNORECASE)
-_ATTACHMENT_REFERENCE_STOP_RE = re.compile(r"[\]\r\n]")
-_ATTACHMENT_REFERENCE_TAIL_RE = re.compile(
-    r"\|\s*id=([0-9a-fA-F]{32}(?:\.[A-Za-z0-9]+)?)(?:\s*\||\s*\])",
+ATTACHMENT_REFERENCE_LINE_RE = re.compile(
+    r"\[Attachment:[^\]\r\n]*\|\s*id="
+    r"([0-9a-fA-F]{32}(?:\.[A-Za-z0-9]+)?)"
+    r"(?:\s*\||\s*\])",
     re.IGNORECASE,
 )
 
 
-def _pdf_source_upload_ids(value: str) -> list[str]:
-    """IDs from `<!-- pdf_source ... upload_id="<id>" ... -->` comments.
-
-    Every opener before the next `>` shares that `>`: the comment matches only
-    if `--` sits right before it, and then with the last `upload_id=` (the
-    greedy `[^>]*` backtracks from the right). Otherwise all of those openers
-    fail together, so the scan resumes after the `>`.
-    """
-    found: list[str] = []
-    pos = 0
-    while True:
-        opener = _PDF_SOURCE_OPEN_RE.search(value, pos)
-        if opener is None:
-            return found
-        close = value.find(">", opener.end())
-        if close < 0:
-            return found
-        if value[close - 2:close] == "--":
-            last = None
-            for last in _PDF_SOURCE_ID_RE.finditer(value, opener.end(), close):
-                pass
-            if last is not None:
-                found.append(last.group(1))
-        pos = close + 1
-
-
-def _attachment_reference_ids(value: str) -> list[str]:
-    """IDs from `[Attachment: name | id=<id> | ...]` reference lines.
-
-    The label scan stops at the first `]`/CR/LF, so every opener before that
-    stop shares it and can only use the last `|` (scanning right to left)
-    whose tail matches. If none does, all of those openers fail together and
-    the scan resumes at the stop.
-    """
-    found: list[str] = []
-    pos = 0
-    while True:
-        opener = _ATTACHMENT_REFERENCE_OPEN_RE.search(value, pos)
-        if opener is None:
-            return found
-        stop = _ATTACHMENT_REFERENCE_STOP_RE.search(value, opener.end())
-        end = stop.start() if stop else len(value)
-        tail = None
-        pipe = value.rfind("|", opener.end(), end)
-        while pipe >= 0:
-            tail = _ATTACHMENT_REFERENCE_TAIL_RE.match(value, pipe)
-            if tail is not None:
-                break
-            pipe = value.rfind("|", opener.end(), pipe)
-        if tail is None:
-            pos = end
-        else:
-            found.append(tail.group(1))
-            pos = tail.end()
-
-
 def is_valid_upload_id(upload_id: str) -> bool:
     """Return True when *upload_id* matches the canonical uploads.json id format."""
     return UPLOAD_ID_RE.fullmatch(upload_id or "") is not None
@@ -171,8 +110,8 @@ def extract_internal_upload_ids(value: Any) -> set[str]:
         return set()
     return (
         set(INTERNAL_UPLOAD_URL_RE.findall(value))
-        | set(_pdf_source_upload_ids(value))
-        | set(_attachment_reference_ids(value))
+        | set(PDF_SOURCE_UPLOAD_RE.findall(value))
+        | set(ATTACHMENT_REFERENCE_LINE_RE.findall(value))
     )
 
 
diff --git a/tests/test_activity.py b/tests/test_activity.py
new file mode 100644
index 000000000..9a44151b0
--- /dev/null
+++ b/tests/test_activity.py
@@ -0,0 +1,36 @@
+"""Tests for src/activity.py — in-flight heavy-image-op counters (safe restart)."""
+from src import activity
+
+
+def test_image_op_counter_increments_and_decrements():
+    assert activity.heavy_image_ops_active() == 0
+    activity.begin_image_op("a")
+    activity.begin_image_op("a")
+    assert activity.heavy_image_ops_active() == 2
+    activity.end_image_op("a")
+    assert activity.heavy_image_ops_active() == 1
+    activity.end_image_op("a")
+    assert activity.heavy_image_ops_active() == 0
+    # never goes negative
+    activity.end_image_op("a")
+    assert activity.heavy_image_ops_active() == 0
+
+
+def test_image_op_context_manager_and_busy():
+    assert activity.busy() is False
+    with activity.image_op("/api/image/inpaint"):
+        assert activity.busy() is True
+        snap = activity.activity()
+        assert snap["image_ops"] == 1
+        assert snap["image_ops_by_name"].get("/api/image/inpaint") == 1
+    assert activity.busy() is False
+    assert activity.activity()["image_ops"] == 0
+
+
+def test_image_op_released_on_exception():
+    try:
+        with activity.image_op("boom"):
+            raise RuntimeError("x")
+    except RuntimeError:
+        pass
+    assert activity.heavy_image_ops_active() == 0
diff --git a/tests/test_agent_editor_routes.py b/tests/test_agent_editor_routes.py
new file mode 100644
index 000000000..7c4cec2a0
--- /dev/null
+++ b/tests/test_agent_editor_routes.py
@@ -0,0 +1,1492 @@
+"""Tests for routes/editor_agent_routes.py (NL editor planning + bridge).
+
+The route wires an injected planner callable (messages, owner) -> raw plan and always
+falls back to a deterministic keyword planner, so the editor gets a usable plan even
+without a model. Tests use a minimal FastAPI app (no full app import) and inject fake
+planners to assert parse/vision/check-mode/bridge-validation behavior.
+"""
+import json
+
+import pytest
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+
+from routes import editor_agent_routes as eaar
+
+
+@pytest.fixture(autouse=True)
+def _reset_planner():
+    eaar.set_editor_planner(None)
+    yield
+    eaar.set_editor_planner(None)
+
+
+@pytest.fixture()
+def client():
+    app = FastAPI()
+    app.include_router(eaar.setup_editor_agent_routes())
+    return TestClient(app)
+
+
+def test_plan_uses_injected_planner_and_parses_steps(client):
+    eaar.set_editor_planner(
+        lambda messages, owner: json.dumps(
+            {"reply": "ok", "steps": [{"op": "adjustments.apply", "params": {"type": "vibrance"}}]}
+        )
+    )
+    r = client.post("/api/editor/plan", json={"prompt": "make it vivid", "state": {}})
+    assert r.status_code == 200
+    data = r.json()
+    assert data["planner"] == "llm"
+    assert data["steps"] == [{"op": "adjustments.apply", "params": {"type": "vibrance"}}]
+
+
+def test_plan_sends_screenshot_as_vision_part(client):
+    seen = {}
+
+    def fake(messages, owner):
+        seen["messages"] = messages
+        return json.dumps({"reply": "ok", "steps": [{"op": "filters.apply", "params": {"id": "sharpen"}}]})
+
+    eaar.set_editor_planner(fake)
+    r = client.post(
+        "/api/editor/plan",
+        json={"prompt": "sharpen it", "state": {}, "screenshot": "data:image/png;base64,AAAA"},
+    )
+    assert r.status_code == 200
+    content = seen["messages"][1]["content"]
+    assert any(p.get("type") == "image_url" for p in content if isinstance(p, dict))
+    assert any(
+        p.get("type") == "image_url" and p["image_url"]["url"].startswith("data:image/")
+        for p in content if isinstance(p, dict)
+    )
+
+
+def test_plan_without_screenshot_sends_plain_text(client):
+    seen = {}
+
+    def fake(messages, owner):
+        seen["messages"] = messages
+        return json.dumps({"reply": "ok", "steps": [{"op": "filters.apply", "params": {"id": "sharpen"}}]})
+
+    eaar.set_editor_planner(fake)
+    client.post("/api/editor/plan", json={"prompt": "sharpen it", "state": {}})
+    assert isinstance(seen["messages"][1]["content"], str)
+
+
+def test_plan_falls_back_when_planner_yields_nothing(client):
+    eaar.set_editor_planner(lambda messages, owner: None)
+    r = client.post("/api/editor/plan", json={"prompt": "make it black and white", "state": {}})
+    data = r.json()
+    assert data["planner"] == "fallback"
+    assert any(op["op"] == "adjustments.apply" for op in data["steps"])
+
+
+def test_plan_parses_dict_return_and_filters_unknown_ops(client):
+    eaar.set_editor_planner(
+        lambda messages, owner: {
+            "reply": "x",
+            "steps": [{"op": "evil.op"}, {"op": "text.add", "params": {"text": "hi"}}],
+        }
+    )
+    data = client.post("/api/editor/plan", json={"prompt": "add text", "state": {}}).json()
+    assert [s["op"] for s in data["steps"]] == ["text.add"]
+
+
+def test_plan_awaits_async_planner(client):
+    async def fake(messages, owner):
+        return json.dumps({"reply": "ok", "steps": [{"op": "history.mark", "params": {}}]})
+
+    eaar.set_editor_planner(fake)
+    data = client.post("/api/editor/plan", json={"prompt": "mark", "state": {}}).json()
+    assert data["steps"][0]["op"] == "history.mark"
+
+
+def test_check_mode_reports_done_when_model_completes(client):
+    eaar.set_editor_planner(lambda messages, owner: json.dumps({"done": True, "reply": "looks good"}))
+    data = client.post(
+        "/api/editor/plan",
+        json={"prompt": "make it warm", "state": {"iteration": 2}, "mode": "check",
+              "screenshot": "data:image/png;base64,AAAA"},
+    ).json()
+    assert data["done"] is True
+    assert data["steps"] == []
+
+
+def test_check_mode_returns_remaining_steps(client):
+    eaar.set_editor_planner(
+        lambda messages, owner: json.dumps(
+            {"done": False, "reply": "more contrast", "steps": [{"op": "adjustments.apply", "params": {}}]}
+        )
+    )
+    data = client.post(
+        "/api/editor/plan",
+        json={"prompt": "make it vivid", "state": {"iteration": 1}, "mode": "check"},
+    ).json()
+    assert data.get("done") is not True
+    assert data["steps"][0]["op"] == "adjustments.apply"
+
+
+def test_check_mode_with_unparseable_planner_stops_loop(client):
+    eaar.set_editor_planner(lambda messages, owner: "not json at all")
+    data = client.post(
+        "/api/editor/plan", json={"prompt": "x", "state": {}, "mode": "check"}
+    ).json()
+    assert data["done"] is True
+    assert data["steps"] == []
+
+
+def test_normalize_steps_drops_ops_outside_catalog():
+    assert eaar._normalize_steps({"op": "evil.op"}) == []
+    assert eaar._normalize_steps(
+        {"steps": [{"op": "text.add"}, {"op": "nope"}, {"not": "a step"}]}
+    ) == [{"op": "text.add", "params": {}}]
+
+
+def test_bridge_command_only_queues_known_ops(client):
+    good = client.post("/api/editor/bridge/command", json={"session": "s", "op": "screenshot"}).json()
+    assert good["queued"]
+    bad = client.post("/api/editor/bridge/command", json={"session": "s", "op": "evil.op"}).json()
+    assert bad["queued"] == []
+
+
+def test_bridge_command_accepts_selection_export_mask(client):
+    # The generative tools fetch the current selection via this op; if it is not
+    # in the catalog the bridge drops the command and the mask comes back empty.
+    assert "selection.exportMask" in eaar._OP_SET
+    ok = client.post(
+        "/api/editor/bridge/command",
+        json={"session": "s", "op": "selection.exportMask", "wait": False},
+    ).json()
+    assert ok["queued"], ok
+
+
+def test_set_editor_planner_is_used_by_setup_when_set():
+    sentinel = lambda messages, owner: None  # noqa: E731
+    eaar.set_editor_planner(sentinel)
+    app = FastAPI()
+    app.include_router(eaar.setup_editor_agent_routes())
+    assert eaar._EDITOR_PLANNER is sentinel
+
+
+def _recipe_ops(steps):
+    out = []
+    for step in steps:
+        params = step.get("params") or {}
+        if step.get("op") in ("adjustments.apply", "adjustments.applyMasked"):
+            out.append((step.get("op"), params.get("type")))
+        elif step.get("op") in ("filters.apply", "filters.applyMasked"):
+            out.append((step.get("op"), params.get("id")))
+        else:
+            out.append((step.get("op"), None))
+    return out
+
+
+def test_agent_path_enforces_v3_recipes_over_a_timid_model_plan(client, monkeypatch):
+    """The /api/editor/agent path (not just /plan) must follow the style guide.
+
+    The sampling model returns one mild brightness-contrast step for every
+    generic intent; the guide is authoritative, so the calibrated recipe ops
+    must appear in the agent response steps.
+    """
+    weak = [{"op": "adjustments.apply",
+             "params": {"type": "brightness-contrast",
+                        "params": {"brightness": 10, "contrast": 10}}}]
+    eaar.set_editor_planner(lambda messages, owner: json.dumps({"reply": "ok", "steps": weak}))
+
+    async def _fake_wait(fut, timeout=None, **kwargs):  # noqa: ANN001
+        return {"ok": True, "result": {"width": 100, "height": 100}}
+
+    monkeypatch.setattr(eaar.asyncio, "wait_for", _fake_wait)
+
+    cases = {
+        "restore this old photo": {("photo.autoTone", None),
+                                   ("adjustments.apply", "white-balance"),
+                                   ("adjustments.apply", "vibrance")},
+        "make it pretty": {("photo.autoTone", None),
+                           ("adjustments.apply", "vibrance"),
+                           ("filters.apply", "clarity")},
+        "make it pop": {("photo.autoTone", None),
+                        ("adjustments.apply", "vibrance"),
+                        ("filters.apply", "clarity")},
+        "make it look like summer": {("adjustments.apply", "white-balance")},
+    }
+    for prompt, required in cases.items():
+        resp = client.post("/api/editor/agent",
+                           json={"prompt": prompt, "state": {"width": 100, "height": 100}})
+        assert resp.status_code == 200, (prompt, resp.text)
+        data = resp.json()
+        ops = set(_recipe_ops(data["steps"]))
+        assert required <= ops, (prompt, ops)
+        if prompt != "make it look like summer":
+            assert len(data["steps"]) >= 3, (prompt, data["steps"])
+
+
+def test_agent_path_low_key_lighting_uses_auto_tone_plus_one_shadow_lift(client, monkeypatch):
+    """Round-6 case 5: 'fix the lighting' on a night photo.
+
+    The model returned a single adjustments.apply step while claiming an
+    auto-tone pass; the guide must supply photo.autoTone + one shadows lift,
+    and the executed steps must contain the auto tone.
+    """
+    weak = [{"op": "adjustments.apply",
+             "params": {"type": "shadows-highlights",
+                        "params": {"shadows": 20, "highlights": -10}}}]
+    eaar.set_editor_planner(lambda messages, owner: json.dumps(
+        {"reply": "A single auto-tone pass.", "steps": weak}))
+
+    async def _fake_wait(fut, timeout=None, **kwargs):  # noqa: ANN001
+        return {"ok": True, "result": {"width": 900, "height": 600}}
+
+    monkeypatch.setattr(eaar.asyncio, "wait_for", _fake_wait)
+
+    resp = client.post("/api/editor/agent",
+                       json={"prompt": "fix the lighting", "state": {"width": 900, "height": 600}})
+    assert resp.status_code == 200, resp.text
+    data = resp.json()
+    ops = _recipe_ops(data["steps"])
+    assert ("photo.autoTone", None) in ops, ops
+    shadow = [s for s in data["steps"] if s.get("params", {}).get("type") == "shadows-highlights"]
+    assert shadow and shadow[0]["params"]["params"]["highlights"] <= 0, data["steps"]
+    assert len(data["steps"]) == 2, data["steps"]
+
+
+def test_agent_path_reply_describes_executed_ops_not_the_plan(client, monkeypatch):
+    """A reply must not claim an edit (auto tone / white balance) that the
+    executed steps do not contain; it is rewritten from the real steps."""
+    eaar.set_editor_planner(lambda messages, owner: json.dumps({
+        "reply": "Applied a single auto-tone pass and white balance.",
+        "steps": [{"op": "adjustments.apply",
+                   "params": {"type": "vibrance", "params": {"vibrance": 20}}}],
+    }))
+
+    async def _fake_wait(fut, timeout=None, **kwargs):  # noqa: ANN001
+        return {"ok": True, "result": {"width": 100, "height": 100}}
+
+    monkeypatch.setattr(eaar.asyncio, "wait_for", _fake_wait)
+
+    resp = client.post("/api/editor/agent",
+                       json={"prompt": "boost the saturation", "state": {"width": 100, "height": 100}})
+    assert resp.status_code == 200, resp.text
+    data = resp.json()
+    reply = data["reply"].lower()
+    assert "auto" not in reply, data["reply"]
+    assert "white balance" not in reply, data["reply"]
+    assert "vibrance" in reply, data["reply"]
+
+
+def _install_provider_and_fake_tools(monkeypatch, *, failing=False):
+    """Provider is available and the AI content tools resolve instantly."""
+    monkeypatch.setattr(eaar, "_image_provider_available", lambda owner: True)
+
+    class _FakeTool:
+        async def execute(self, content, ctx):  # noqa: ANN001
+            if failing:
+                return ("ai_edit_image", {"exit_code": 1, "error": "provider exploded"})
+            return (
+                "ai_edit_image",
+                {
+                    "exit_code": 0,
+                    "image_id": "gen-1",
+                    "image_url": "/api/generated-image/gen-1.png",
+                    "placed": True,
+                    "output": "applied",
+                },
+            )
+
+    from src.agent_tools import editor_tools
+
+    monkeypatch.setattr(editor_tools, "AiEditImageTool", _FakeTool)
+    monkeypatch.setattr(editor_tools, "GenerateImageLayerTool", _FakeTool)
+
+    async def _fake_wait(fut, timeout=None, **kwargs):  # noqa: ANN001
+        return {"ok": True, "result": {"width": 100, "height": 100}}
+
+    monkeypatch.setattr(eaar.asyncio, "wait_for", _fake_wait)
+
+
+def test_agent_path_routes_generative_intents_when_provider_present(client, monkeypatch):
+    """Gen-6 bug 4: with an image provider, object-removal / background-change
+    prompts must use ai_edit_image, and plain 'blur the background' stays a blur."""
+    _install_provider_and_fake_tools(monkeypatch)
+
+    def _ai_ops(data):
+        return {s.get("op") for s in data["steps"]}
+
+    r = client.post("/api/editor/agent",
+                    json={"prompt": "remove the distractions", "state": {"width": 100, "height": 100}})
+    assert r.status_code == 200, r.text
+    assert "ai_edit_image" in _ai_ops(r.json()), r.json()["steps"]
+
+    r = client.post("/api/editor/agent",
+                    json={"prompt": "make the background nicer", "state": {"width": 100, "height": 100}})
+    assert r.status_code == 200, r.text
+    assert "ai_edit_image" in _ai_ops(r.json()), r.json()["steps"]
+
+    r = client.post("/api/editor/agent",
+                    json={"prompt": "add a full moon in the sky", "state": {"width": 100, "height": 100}})
+    assert r.status_code == 200, r.text
+    assert "ai_edit_image" in _ai_ops(r.json()), r.json()["steps"]
+
+    r = client.post("/api/editor/agent",
+                    json={"prompt": "remove the person on the left", "state": {"width": 100, "height": 100}})
+    assert r.status_code == 200, r.text
+    assert "ai_edit_image" in _ai_ops(r.json()), r.json()["steps"]
+
+    r = client.post("/api/editor/agent",
+                    json={"prompt": "create a new image of a full moon", "state": {"width": 100, "height": 100}})
+    assert r.status_code == 200, r.text
+    assert "generate_image" in _ai_ops(r.json()), r.json()["steps"]
+
+    r = client.post("/api/editor/agent",
+                    json={"prompt": "blur the background", "state": {"width": 100, "height": 100}})
+    assert r.status_code == 200, r.text
+    assert _ai_ops(r.json()) & {"ai_edit_image", "generate_image"} == set(), r.json()["steps"]
+
+
+def test_agent_path_recolor_is_exactly_object_mask_plus_masked_hue(client, monkeypatch):
+    """#125/#127: on the agent path a recolour must be EXACTLY
+    [selection.samText, adjustments.applyMasked] — the VLM planner used to
+    append whole-image adjustments.apply after the masked hue shift."""
+    _install_provider_and_fake_tools(monkeypatch)
+    eaar.set_editor_planner(
+        lambda messages, owner: json.dumps({
+            "reply": "recolor",
+            "steps": [
+                {"op": "selection.samText", "params": {"text": "red car"}},
+                {"op": "adjustments.applyMasked",
+                 "params": {"mode": "hue-saturation", "hue": -120, "sourceHue": 0}},
+                {"op": "adjustments.apply", "params": {"type": "vibrance", "params": {"vibrance": 20}}},
+                {"op": "adjustments.apply", "params": {"type": "brightness-contrast", "params": {"brightness": 15}}},
+            ],
+        })
+    )
+    r = client.post("/api/editor/agent",
+                    json={"prompt": "make only the red car blue",
+                          "session": "s1", "editor_session": "s1",
+                          "state": {"width": 100, "height": 100}})
+    assert r.status_code == 200, r.text
+    ops = [s["op"] for s in r.json()["steps"]]
+    assert ops == ["selection.samText", "adjustments.applyMasked"], ops
+    assert "selection.fill" not in ops
+
+
+def test_agent_path_strips_global_grades_after_a_masked_recolor(client, monkeypatch):
+    """Even when the deterministic recolour special does not fire, a planner's
+    masked-recolour plan must not keep trailing whole-image adjustments."""
+    _install_provider_and_fake_tools(monkeypatch)
+    eaar.set_editor_planner(
+        lambda messages, owner: json.dumps({
+            "reply": "tweak",
+            "steps": [
+                {"op": "selection.samText", "params": {"text": "the object"}},
+                {"op": "adjustments.applyMasked",
+                 "params": {"mode": "hue-saturation", "hue": 90, "sourceHue": 200}},
+                {"op": "adjustments.apply", "params": {"type": "vibrance", "params": {"vibrance": 20}}},
+                {"op": "photo.autoTone", "params": {}},
+            ],
+        })
+    )
+    r = client.post("/api/editor/agent",
+                    json={"prompt": "do a quick tweak",
+                          "session": "s2", "editor_session": "s2",
+                          "state": {"width": 100, "height": 100}})
+    assert r.status_code == 200, r.text
+    ops = [s["op"] for s in r.json()["steps"]]
+    assert ops == ["selection.samText", "adjustments.applyMasked"], ops
+
+
+def test_agent_path_reports_failure_when_a_generative_step_fails(client, monkeypatch):
+    """Gen-6 bug 5: a failed generative step must return ok:false with the real
+    error, never ok:true."""
+    _install_provider_and_fake_tools(monkeypatch, failing=True)
+    r = client.post("/api/editor/agent",
+                    json={"prompt": "remove the distractions", "state": {"width": 100, "height": 100}})
+    assert r.status_code == 200, r.text
+    data = r.json()
+    assert data["ok"] is False, data
+    assert "provider exploded" in data["reply"], data["reply"]
+    assert any(
+        r.get("op") in ("ai_edit_image", "generate_image") and r.get("ok") is False
+        for r in data["results"]
+    ), data["results"]
+
+
+def test_bridge_default_timeout_allows_slow_generative_steps():
+    """Gen-6 bug 2: the bridge/agent waits must exceed the provider latency."""
+    assert eaar._BRIDGE_DEFAULT_TIMEOUT >= 300
+
+
+def test_inpaint_proxy_decodes_data_url_base64():
+    """Gen-6 bug 1: the image endpoints must accept both raw base64 and a
+    'data:...;base64,' data URL (the editor tools send data URLs)."""
+    import base64
+
+    from routes.gallery import gallery_routes as gr
+
+    raw = b"\x89PNG\r\n\x1a\n payload"
+    data_url = "data:image/png;base64," + base64.b64encode(raw).decode("ascii")
+    assert gr._b64_bytes(data_url) == raw
+    assert gr._b64_bytes(base64.b64encode(raw).decode("ascii")) == raw
+    from fastapi import HTTPException
+
+    with pytest.raises(HTTPException):
+        gr._b64_bytes("")
+
+
+def test_generative_routing_uses_instruction_vs_masked():
+    """Qwen-Image-Edit instruction approach: most generative edits are whole-image
+    instruction edits (no mask); masked inpaint only for a clear regional object
+    removal; generate_image only for a brand-new image."""
+    from routes.editor_agent_routes import _generative_mode, _generative_steps
+
+    bg = _generative_steps("replace", "make the background nicer")
+    assert len(bg) == 1 and bg[0]["op"] == "ai_edit_image"
+    assert bg[0]["params"]["mode"] == "instruction"
+    assert "keep" in bg[0]["params"]["prompt"].lower()  # names what must stay
+
+    add = _generative_steps("add", "add a full moon in the sky")
+    assert add[-1]["op"] == "ai_edit_image" and add[-1]["params"]["mode"] == "instruction"
+
+    cleanup = _generative_steps("remove", "remove the distractions")
+    assert cleanup[-1]["op"] == "ai_edit_image" and cleanup[-1]["params"]["mode"] == "instruction"
+
+    masked = _generative_steps("remove", "remove the person on the left")
+    assert masked[0]["op"] == "selection.subject"  # tight mask first
+    assert masked[-1]["op"] == "ai_edit_image" and masked[-1]["params"]["mode"] == "masked"
+    assert _generative_mode("remove", "remove the person on the left") == "masked"
+
+    fresh = _generative_steps("add", "create a new image of a full moon")
+    assert fresh[-1]["op"] == "generate_image"
+
+
+@pytest.mark.parametrize(
+    "prompt",
+    [
+        "add wildflowers",
+        "make it snowy",
+        "make it autumn",
+        "add sunglasses to her",
+        "add a rainbow",
+        "generative fill the sky",
+    ],
+)
+def test_generative_content_intents_never_route_to_adjustments(prompt):
+    """Bench round 4: adding elements, season/weather changes and an explicit
+    "generative fill" must be a whole-image instruction edit (steps 8, keep
+    clause), never a colour adjustment/filter."""
+    deterministic = [
+        {"op": "adjustments.apply", "params": {"type": "brightness-contrast", "params": {"brightness": 10}}}
+    ]
+    kind = eaar._generative_kind(prompt)
+    assert kind in ("add", "replace"), (prompt, kind)
+    steps = eaar._ensure_generative(prompt, list(deterministic))
+    assert not any(s.get("op") == "adjustments.apply" for s in steps), steps
+    ai = [s for s in steps if s.get("op") == "ai_edit_image"]
+    assert ai, steps
+    assert ai[-1]["params"]["mode"] == "instruction"
+    assert ai[-1]["params"].get("steps") == 8
+    assert "keep" in ai[-1]["params"]["prompt"].lower()
+
+
+@pytest.mark.parametrize(
+    "prompt", ["make it black and white", "blur the background", "add a vignette", "make it look like summer"]
+)
+def test_tone_intents_still_do_not_route_to_generative(prompt):
+    assert eaar._generative_kind(prompt) is None
+
+
+def test_season_prompt_names_the_season_and_keeps_subject():
+    params = eaar._generative_step("replace", "make it snowy")["params"]
+    low = params["prompt"].lower()
+    assert "snow" in low and "keep" in low and params["mode"] == "instruction" and params["steps"] == 8
+
+
+def test_removal_and_expand_use_eight_steps():
+    """Gen-6 (C/D): removal and expand edits ask for 8 sampler steps (the server
+    default of 4 is too weak) and naming what to remove / where to fill."""
+    from routes.editor_agent_routes import _generative_step, _plan_format_steps
+
+    rm = _generative_step("remove", "remove the distractions")["params"]
+    assert rm["steps"] == 8, rm
+    assert "landscape" in rm["prompt"].lower(), rm["prompt"]
+
+    masked = _generative_step("remove", "remove the person on the left")["params"]
+    assert masked["steps"] == 8 and masked["mode"] == "masked", masked
+
+    ext = _plan_format_steps("extend the canvas to 16:9", {"width": 900, "height": 600}, True)[0]["params"]
+    assert ext["steps"] == 8 and ext["feather"] is True, ext
+
+
+def test_extend_plan_uses_instruction_expand_with_feather():
+    from routes.editor_agent_routes import _plan_format_steps
+
+    steps = _plan_format_steps("extend the canvas to 16:9", {"width": 900, "height": 600}, True)
+    assert steps and steps[0]["op"] == "ai.generativeExpand"
+    p = steps[0]["params"]
+    assert p.get("mode") == "instruction" and p.get("feather") is True
+    assert "border" in p.get("prompt", "").lower()
+
+
+def test_ai_edit_image_schema_exposes_mode():
+    from src.tool_schemas import FUNCTION_TOOL_SCHEMAS
+
+    schema = next(
+        s["function"] for s in FUNCTION_TOOL_SCHEMAS if s["function"]["name"] == "ai_edit_image"
+    )
+    mode = schema["parameters"]["properties"]["mode"]
+    assert set(mode["enum"]) == {"instruction", "masked"}
+
+
+def test_ai_edit_image_tool_instruction_needs_no_mask_masked_does(monkeypatch):
+    """Instruction mode sends a full-white mask (whole-image edit); masked mode
+    still requires a real selection and errors when none is available."""
+    import asyncio
+    import base64
+    import io
+
+    from PIL import Image
+
+    import src.agent_tools.editor_tools as et
+
+    buf = io.BytesIO()
+    Image.new("RGB", (32, 32), (10, 20, 30)).save(buf, "PNG")
+    img = "data:image/png;base64," + base64.b64encode(buf.getvalue()).decode()
+
+    captured = {}
+
+    async def _fake_post(path, payload, owner, timeout=120):
+        captured["path"] = path
+        captured["payload"] = payload
+        return {"image": "data:image/png;base64," + base64.b64encode(buf.getvalue()).decode()}
+
+    async def _no_mask(owner, session):
+        return None
+
+    async def _no_place(*a, **k):
+        return True
+
+    monkeypatch.setattr(et, "_post", _fake_post)
+    monkeypatch.setattr(et, "_fetch_selection_mask", _no_mask)
+    monkeypatch.setattr(et, "_place_layer", _no_place)
+    monkeypatch.setattr(et, "_persist_png", lambda *a, **k: {})
+    monkeypatch.setattr(et, "_provider_available", lambda owner: True)
+
+    tool = et.AiEditImageTool()
+    # Instruction mode: no mask supplied, still succeeds and sends a full mask.
+    desc, res = asyncio.run(tool.execute(
+        json.dumps({"op": "generative", "mode": "instruction", "prompt": "nice beach", "image": img}),
+        {"owner": "u"},
+    ))
+    assert res.get("exit_code") == 0, res
+    assert captured["payload"].get("mode") == "instruction"
+    assert str(captured["payload"].get("mask", "")).startswith("data:image/png;base64,")
+
+    # Masked mode without any selection and no grounding box: fall back to
+    # whole-image instruction mode instead of placing an empty/transparent layer.
+    captured.clear()
+    desc, res = asyncio.run(tool.execute(
+        json.dumps({"op": "inpaint", "mode": "masked", "prompt": "remove it", "image": img}),
+        {"owner": "u"},
+    ))
+    assert res.get("exit_code") == 0, res
+    assert captured["payload"].get("mode") == "instruction"
+
+    # Masked mode with a grounding box (OWL-ViT) builds a dilated box mask and
+    # stays in masked mode.
+    async def _ground(owner, image, label):
+        return [0.0, 0.0, 8.0, 8.0]
+
+    monkeypatch.setattr(et, "_ground_box", _ground)
+    captured.clear()
+    desc, res = asyncio.run(tool.execute(
+        json.dumps({"op": "inpaint", "mode": "masked", "prompt": "remove the person on the left", "image": img}),
+        {"owner": "u"},
+    ))
+    assert res.get("exit_code") == 0, res
+    assert captured["payload"].get("mode") == "masked"
+    assert str(captured["payload"].get("mask", "")).startswith("data:image/png;base64,")
+
+
+def test_place_layer_forwards_edit_mode(monkeypatch):
+    """Instruction-mode results must tell the client to build a difference mask."""
+    import asyncio
+
+    import src.agent_tools.editor_tools as et
+
+    seen = {}
+
+    async def _fake_post(path, payload, owner, timeout=120):
+        seen["payload"] = payload
+        return {"ok": True}
+
+    monkeypatch.setattr(et, "_post", _fake_post)
+
+    asyncio.run(et._place_layer("data:image/png;base64,AA", "AI inpaint", "u", "s1", mode="instruction"))
+    params = seen["payload"]["params"]
+    assert params["mode"] == "instruction"
+    assert params["differenceMask"] is True
+
+    asyncio.run(et._place_layer("data:image/png;base64,AA", "AI inpaint", "u", "s1", masked=True, mode="masked"))
+    params = seen["payload"]["params"]
+    assert params["mode"] == "masked"
+    assert params["differenceMask"] is False
+
+    # No mode (e.g. generate_image) => keys omitted so the client keeps its behavior.
+    asyncio.run(et._place_layer("data:image/png;base64,AA", "Generated image", "u", "s1"))
+    params = seen["payload"]["params"]
+    assert "mode" not in params and "differenceMask" not in params
+
+
+def test_plan_route_forces_generative_over_a_deterministic_model_plan(client):
+    """/plan must agree with /agent: a generative intent is never left on a
+    deterministic substitute even if the model proposes one."""
+    eaar.set_editor_planner(
+        lambda messages, owner: {"reply": "ok", "steps": [{"op": "history.mark", "params": {}}]}
+    )
+    try:
+        for prompt in ("remove the person on the left", "add a full moon in the sky",
+                       "make the background nicer"):
+            r = client.post("/api/editor/plan", json={"prompt": prompt, "state": {"width": 100, "height": 100}})
+            assert r.status_code == 200, r.text
+            ops = [s["op"] for s in r.json()["steps"]]
+            assert "ai_edit_image" in ops, (prompt, r.json()["steps"])
+        r = client.post("/api/editor/plan", json={"prompt": "create a new image of a full moon",
+                                                  "state": {"width": 100, "height": 100}})
+        assert "generate_image" in [s["op"] for s in r.json()["steps"]], r.json()["steps"]
+    finally:
+        eaar.set_editor_planner(None)
+
+
+def test_scene_replacement_prompt_names_the_scene_and_uses_eight_steps():
+    """Gen-6 case 2: a background/scene replacement must name concrete scene
+    details and ask for 8 sampler steps, not a bare 'a beach'."""
+    from routes.editor_agent_routes import _generative_steps
+
+    steps = _generative_steps("replace", "put her on a beach")
+    ai = steps[-1]
+    assert ai["op"] == "ai_edit_image", steps
+    params = ai["params"]
+    assert params["mode"] == "instruction", params
+    assert params.get("steps") == 8, params
+    low = params["prompt"].lower()
+    assert "beach" in low and ("sand" in low or "sea" in low), params["prompt"]
+    assert "keep" in low, params["prompt"]
+    # Deterministic template, passed to the provider unmodified.
+    assert params["prompt"].startswith(
+        "Replace the entire background behind the person with"), params["prompt"]
+    assert params["prompt"].endswith("Keep the person exactly the same."), params["prompt"]
+
+    generic = _generative_steps("replace", "make the background nicer")[-1]["params"]
+    assert generic.get("steps") == 8, generic
+    assert "background" in generic["prompt"].lower(), generic
+
+
+def test_scene_prompt_overrides_a_vague_model_ai_step():
+    """A model-written ai_edit_image prompt must not drop the scene details: the
+    background-replacement intent forces the templated scene prompt."""
+    from routes.editor_agent_routes import _ensure_generative
+
+    model_steps = [{"op": "ai_edit_image",
+                    "params": {"op": "generative", "mode": "instruction",
+                               "prompt": "put her outside somewhere"}}]
+    out = _ensure_generative("put her on a beach", model_steps)
+    ai = [s for s in out if s.get("op") == "ai_edit_image"][-1]
+    prompt = ai["params"]["prompt"]
+    assert prompt.startswith("Replace the entire background behind the person with")
+    assert prompt.endswith("Keep the person exactly the same.")
+    assert "beach" in prompt.lower() and "sand" in prompt.lower()
+    assert ai["params"]["mode"] == "instruction" and ai["params"].get("mask") is None
+
+
+def test_agent_path_masked_ai_step_receives_canvas_screenshot(client, monkeypatch):
+    """Gen-6 case 1: after a selection step, the masked ai_edit_image must still
+    receive the canvas image (from the request screenshot), not fail with
+    'needs an image'."""
+    import base64
+
+    from src.agent_tools import editor_tools
+
+    seen = {}
+
+    class _FakeAI:
+        async def execute(self, content, ctx):  # noqa: ANN001
+            seen["args"] = json.loads(content)
+            return ("ai_edit_image", {"exit_code": 0, "image_id": "g", "placed": True, "output": "ok"})
+
+    monkeypatch.setattr(editor_tools, "AiEditImageTool", _FakeAI)
+    monkeypatch.setattr(eaar, "_image_provider_available", lambda owner: True)
+
+    async def _fake_wait(fut, timeout=None, **kwargs):  # noqa: ANN001
+        return {"ok": True, "result": {"width": 100, "height": 100}}
+
+    monkeypatch.setattr(eaar.asyncio, "wait_for", _fake_wait)
+
+    eaar.set_editor_planner(
+        lambda messages, owner: json.dumps(
+            {
+                "reply": "ok",
+                "steps": [
+                    {"op": "selection.subject", "params": {"label": "person"}},
+                    {
+                        "op": "ai_edit_image",
+                        "params": {"op": "inpaint", "mode": "masked", "prompt": "remove the person on the left"},
+                    },
+                ],
+            }
+        )
+    )
+    shot = "data:image/png;base64," + base64.b64encode(b"canvas").decode("ascii")
+    r = client.post(
+        "/api/editor/agent",
+        json={
+            "prompt": "remove the person on the left",
+            "session": "s1",
+            "editor_session": "s1",
+            "state": {"width": 100, "height": 100},
+            "screenshot": shot,
+        },
+    )
+    assert r.status_code == 200, r.text
+    assert seen.get("args"), r.json()
+    assert seen["args"].get("image") == shot, seen["args"]
+    assert seen["args"].get("mode") == "masked", seen["args"]
+
+
+def _bridge_app():
+    app = FastAPI()
+    app.include_router(eaar.setup_editor_agent_routes())
+    return app
+
+
+async def _asgi_post(app, path, payload):
+    sent = []
+    scope = {"type": "http", "method": "POST", "path": path, "query_string": b"",
+             "headers": [(b"content-type", b"application/json")]}
+    data = json.dumps(payload).encode()
+    recv = [{"type": "http.request", "body": data, "more_body": False}]
+
+    async def receive():
+        return recv.pop(0) if recv else {"type": "http.disconnect"}
+
+    async def send(msg):
+        if msg["type"] == "http.response.body" and msg.get("body"):
+            sent.append(msg["body"])
+
+    await app(scope, receive, send)
+    return b"".join(sent)
+
+
+def test_bridge_roundtrip_subscribe_command_result():
+    """URGENT regression: a real subscribe -> command -> result round trip must
+    deliver the command to the SSE subscriber and resolve the waiting /command."""
+    import asyncio
+
+    app = _bridge_app()
+
+    async def scenario():
+        out, stop = [], asyncio.Event()
+
+        async def receive():
+            await stop.wait()
+            return {"type": "http.disconnect"}
+
+        async def send(msg):
+            if msg["type"] == "http.response.body" and msg.get("body"):
+                out.append(msg["body"])
+
+        sse = asyncio.create_task(app(
+            {"type": "http", "method": "GET", "path": "/api/editor/bridge/events",
+             "query_string": b"session=S", "headers": []}, receive, send))
+        for _ in range(200):
+            if any(b": connected" in b for b in out):
+                break
+            await asyncio.sleep(0.01)
+
+        cmd_result = {}
+
+        async def issue():
+            cmd_result["body"] = await _asgi_post(
+                app, "/api/editor/bridge/command",
+                {"session": "S", "steps": [{"op": "document.info"}], "wait": True, "timeout": 5})
+
+        cmd_task = asyncio.create_task(issue())
+        cmd_id = None
+        for _ in range(300):
+            for b in out:
+                for line in b.decode().splitlines():
+                    if line.startswith("data:"):
+                        cmd_id = json.loads(line[5:].strip())["id"]
+                        break
+                if cmd_id:
+                    break
+            if cmd_id:
+                break
+            await asyncio.sleep(0.01)
+        assert cmd_id, out
+        await _asgi_post(app, "/api/editor/bridge/result",
+                         {"id": cmd_id, "ok": True, "result": {"width": 10, "height": 20}})
+        await asyncio.wait_for(cmd_task, 5)
+        body = json.loads(cmd_result["body"].decode())
+        assert body.get("ok") is True and body.get("result") == {"width": 10, "height": 20}, body
+        stop.set()
+        try:
+            await asyncio.wait_for(sse, 2)
+        except (asyncio.TimeoutError, asyncio.CancelledError):
+            pass
+
+    asyncio.run(scenario())
+
+
+def test_bridge_broadcasts_to_every_subscriber():
+    """URGENT regression: with two live subscribers on the same session (EventSource
+    reconnects overlap), a command must reach BOTH, never be eaten by one."""
+    import asyncio
+
+    app = _bridge_app()
+
+    async def scenario():
+        outs = {"A": [], "B": []}
+        stops = {"A": asyncio.Event(), "B": asyncio.Event()}
+
+        def subscriber(name):
+            async def receive():
+                await stops[name].wait()
+                return {"type": "http.disconnect"}
+
+            async def send(msg):
+                if msg["type"] == "http.response.body" and msg.get("body"):
+                    outs[name].append(msg["body"])
+
+            return asyncio.create_task(app(
+                {"type": "http", "method": "GET", "path": "/api/editor/bridge/events",
+                 "query_string": b"session=D", "headers": []}, receive, send))
+
+        tasks = [subscriber("A"), subscriber("B")]
+        for _ in range(200):
+            if all(any(b": connected" in b for b in outs[n]) for n in ("A", "B")):
+                break
+            await asyncio.sleep(0.01)
+
+        await _asgi_post(app, "/api/editor/bridge/command",
+                         {"session": "D", "steps": [{"op": "screenshot"}], "wait": False})
+        for _ in range(300):
+            if all(any(b"data:" in b for b in outs[n]) for n in ("A", "B")):
+                break
+            await asyncio.sleep(0.01)
+
+        for name in ("A", "B"):
+            assert any(b'"op": "screenshot"' in b for b in outs[name]), (name, outs)
+        for e in stops.values():
+            e.set()
+        for t in tasks:
+            try:
+                await asyncio.wait_for(t, 2)
+            except (asyncio.TimeoutError, asyncio.CancelledError):
+                pass
+
+    asyncio.run(scenario())
+
+
+def test_editor_image_models_route_shape():
+    """The editor model selector reads the available image models from here."""
+    from fastapi import FastAPI
+    from starlette.testclient import TestClient
+
+    app = FastAPI()
+    app.include_router(eaar.setup_editor_agent_routes())
+    c = TestClient(app)
+    r = c.get("/api/editor/image-models")
+    assert r.status_code == 200, r.text
+    data = r.json()
+    assert isinstance(data.get("models"), list)
+    for m in data["models"]:
+        assert set(("id", "label", "kind", "provider")).issubset(m)
+        assert m["kind"] in ("edit", "generate")
+
+
+def test_ai_edit_image_tool_forwards_and_reports_model(monkeypatch):
+    """A picked model is forwarded to the provider (_model) and reported back."""
+    import asyncio
+    import base64
+    import io
+
+    from PIL import Image
+
+    import src.agent_tools.editor_tools as et
+
+    buf = io.BytesIO()
+    Image.new("RGB", (32, 32), (10, 20, 30)).save(buf, "PNG")
+    img = "data:image/png;base64," + base64.b64encode(buf.getvalue()).decode()
+
+    captured = {}
+
+    async def _fake_post(path, payload, owner, timeout=120):
+        captured["payload"] = payload
+        return {"image": img, "model": "qwen-image-edit-2511"}
+
+    async def _no_place(*a, **k):
+        return True
+
+    monkeypatch.setattr(et, "_post", _fake_post)
+    monkeypatch.setattr(et, "_place_layer", _no_place)
+    monkeypatch.setattr(et, "_persist_png", lambda *a, **k: {})
+    monkeypatch.setattr(et, "_provider_available", lambda owner: True)
+
+    _desc, res = asyncio.run(et.AiEditImageTool().execute(
+        json.dumps({"op": "generative", "mode": "instruction", "prompt": "beach",
+                    "image": img, "model": "qwen-image-edit-2511", "place": False}),
+        {"owner": "u"},
+    ))
+    assert res.get("exit_code") == 0, res
+    assert captured["payload"].get("_model") == "qwen-image-edit-2511", captured["payload"]
+    assert res.get("model") == "qwen-image-edit-2511", res
+
+
+def test_agent_path_injects_selected_model_into_ai_step(client, monkeypatch):
+    """The /api/editor/agent body `model` reaches the AI step tool payload."""
+    monkeypatch.setattr(eaar, "_image_provider_available", lambda owner: True)
+    captured = {}
+
+    class _CapturingTool:
+        async def execute(self, content, ctx):  # noqa: ANN001
+            captured["content"] = json.loads(content)
+            return ("ai_edit_image", {"exit_code": 0, "image_id": "g1", "placed": True,
+                                      "output": "ok", "model": "qwen-image-edit-2511"})
+
+    from src.agent_tools import editor_tools
+
+    monkeypatch.setattr(editor_tools, "AiEditImageTool", _CapturingTool)
+    monkeypatch.setattr(editor_tools, "GenerateImageLayerTool", _CapturingTool)
+
+    async def _fake_wait(fut, timeout=None, **kwargs):  # noqa: ANN001
+        return {"ok": True, "result": {"width": 100, "height": 100}}
+
+    monkeypatch.setattr(eaar.asyncio, "wait_for", _fake_wait)
+
+    r = client.post("/api/editor/agent",
+                    json={"prompt": "put her on a beach", "state": {"width": 100, "height": 100},
+                          "model": "qwen-image-edit-2511"})
+    assert r.status_code == 200, r.text
+    assert captured.get("content", {}).get("model") == "qwen-image-edit-2511", captured
+    data = r.json()
+    assert data["results"][-1]["result"].get("model") == "qwen-image-edit-2511", data
+
+
+# ---------------------------------------------------------------------------
+# Editor agent/planner model (local Qwen3.5-9B) resolution + reporting.
+# ---------------------------------------------------------------------------
+
+def test_editor_agent_models_route_shape(client):
+    """The agent-model picker reads the local planner model + hosted fallback."""
+    r = client.get("/api/editor/agent-models")
+    assert r.status_code == 200, r.text
+    data = r.json()
+    assert isinstance(data.get("models"), list)
+    assert isinstance(data.get("probe"), dict)
+    for m in data["models"]:
+        assert set(("id", "label", "source", "vision")).issubset(m)
+        assert m["source"] in ("local", "hosted")
+
+
+def test_list_editor_agent_models_includes_base_url():
+    import asyncio
+
+    import src.editor_agent_model as eam
+
+    models = asyncio.run(eam.list_editor_agent_models(None))
+    assert any(m["source"] == "local" for m in models), models
+    for m in models:
+        assert "base_url" in m
+
+
+def test_plan_reports_agent_model(client):
+    eaar.set_editor_planner(
+        lambda messages, owner: json.dumps(
+            {"reply": "ok", "steps": [{"op": "filters.apply", "params": {"id": "sharpen"}}]}
+        )
+    )
+    r = client.post("/api/editor/plan",
+                    json={"prompt": "sharpen it", "state": {}, "agent_model": "MYPLANNER"})
+    assert r.status_code == 200, r.text
+    assert r.json().get("agent_model") == "MYPLANNER", r.json()
+
+
+def test_agent_reports_agent_model(client, monkeypatch):
+    monkeypatch.setattr(eaar, "_image_provider_available", lambda owner: True)
+    eaar.set_editor_planner(
+        lambda messages, owner: json.dumps(
+            {"reply": "ok", "steps": [{"op": "adjustments.apply", "params": {"type": "vibrance"}}]}
+        )
+    )
+
+    async def _fake_wait(fut, timeout=None, **kwargs):  # noqa: ANN001
+        try:
+            fut.close()
+        except Exception:
+            pass
+        return {"ok": True, "result": {"width": 100, "height": 100}}
+
+    monkeypatch.setattr(eaar.asyncio, "wait_for", _fake_wait)
+    r = client.post("/api/editor/agent",
+                    json={"prompt": "make it vivid", "state": {"width": 100, "height": 100},
+                          "agent_model": "MYPLANNER"})
+    assert r.status_code == 200, r.text
+    data = r.json()
+    assert data.get("agent_model") == "MYPLANNER", data
+    assert data["trace"][-1].get("agent_model") == "MYPLANNER" or data["trace"][1].get("agent_model") == "MYPLANNER", data
+
+
+def test_editor_agent_model_override_is_first_candidate(monkeypatch):
+    import src.editor_agent_model as eam
+
+    monkeypatch.setattr(eam, "local_bases", lambda: ["http://local1"])
+    monkeypatch.setattr(eam, "local_model", lambda: "LMODEL")
+    cands = eam._candidates(None, "http://ovr::OVERRIDE")
+    assert cands[0] == {"base": "http://ovr", "model": "OVERRIDE", "headers": None,
+                        "source": "override"}
+    assert any(c["source"] == "local" and c["base"] == "http://local1" for c in cands)
+
+
+def test_editor_agent_model_uses_vision_first(monkeypatch):
+    import asyncio
+
+    import src.editor_agent_model as eam
+
+    calls = []
+
+    async def fake_post(base, model, messages, headers, timeout, max_tokens=1024):  # noqa: ANN001
+        calls.append((base, eam._has_image(messages)))
+        return "PLAN" if base == "http://local1" and eam._has_image(messages) else None
+
+    monkeypatch.setattr(eam, "_candidates", lambda owner, override: [
+        {"base": "http://local1", "model": "m1", "headers": None, "source": "local"}])
+    monkeypatch.setattr(eam, "_post_chat", fake_post)
+
+    msgs = [{"role": "user", "content": [
+        {"type": "text", "text": "x"},
+        {"type": "image_url", "image_url": {"url": "data:image/png;base64,AA"}}]}]
+    res = asyncio.run(eam.plan_with_editor_agent(msgs, None))
+    assert res == ("PLAN", "m1", "local"), res
+    assert calls == [("http://local1", True)]
+
+
+def test_editor_agent_model_caption_fallback(monkeypatch):
+    import asyncio
+
+    import src.editor_agent_model as eam
+
+    async def fake_post(base, model, messages, headers, timeout, max_tokens=1024):  # noqa: ANN001
+        return None if eam._has_image(messages) else "PLAN"
+
+    async def fake_caption(url, owner=None, timeout=90):  # noqa: ANN001
+        return "a beach at sunset"
+
+    monkeypatch.setattr(eam, "_candidates", lambda owner, override: [
+        {"base": "http://local1", "model": "m1", "headers": None, "source": "local"}])
+    monkeypatch.setattr(eam, "_post_chat", fake_post)
+    monkeypatch.setattr(eam, "caption_image", fake_caption)
+
+    msgs = [{"role": "user", "content": [
+        {"type": "image_url", "image_url": {"url": "data:image/png;base64,AA"}}]}]
+    res = asyncio.run(eam.plan_with_editor_agent(msgs, None))
+    assert res == ("PLAN", "m1", "local+caption"), res
+
+
+def test_editor_agent_model_returns_none_when_all_fail(monkeypatch):
+    import asyncio
+
+    import src.editor_agent_model as eam
+
+    async def fake_post(*a, **k):  # noqa: ANN001
+        return None
+
+    async def fake_caption(*a, **k):  # noqa: ANN001
+        return None
+
+    monkeypatch.setattr(eam, "_candidates", lambda owner, override: [
+        {"base": "b", "model": "m", "headers": None, "source": "local"}])
+    monkeypatch.setattr(eam, "_post_chat", fake_post)
+    monkeypatch.setattr(eam, "caption_image", fake_caption)
+
+    msgs = [{"role": "user", "content": [
+        {"type": "image_url", "image_url": {"url": "data:image/png;base64,AA"}}]}]
+    assert asyncio.run(eam.plan_with_editor_agent(msgs, None)) is None
+
+
+def test_plan_special_recolor_overrides_a_model_plan(client):
+    # A deterministic recolour must win over any model-written plan
+    # (no LLM variance / no samText+placeImage substitution).
+    eaar.set_editor_planner(lambda messages, owner: json.dumps({
+        "reply": "ok",
+        "steps": [{"op": "adjustments.apply", "params": {"type": "vibrance"}}]}))
+    r = client.post("/api/editor/plan", json={
+        "prompt": "make only the red car blue",
+        "state": {"width": 900, "height": 600}})
+    assert r.status_code == 200
+    data = r.json()
+    assert data["planner"] == "deterministic"
+    assert [s["op"] for s in data["steps"]] == [
+        "selection.samText", "adjustments.applyMasked"]
+    assert "selection.fill" not in [s["op"] for s in data["steps"]]
+
+
+def test_self_check_endpoint_parses_retry(client, monkeypatch):
+    import src.editor_agent_model as eam
+
+    async def _retry(*a, **k):  # noqa: ANN001
+        return "RETRY: brighten the subject"
+
+    monkeypatch.setattr(eam, "_post_chat", _retry)
+    r = client.post("/api/editor/self-check", json={
+        "before": "data:image/png;base64,AA",
+        "after": "data:image/png;base64,AA",
+        "prompt": "did it get brighter?"})
+    assert r.status_code == 200
+    data = r.json()
+    assert data["done"] is False
+    assert "brighten" in data["retry_hint"]
+    assert "RETRY" in data["text"]
+
+
+def test_self_check_endpoint_parses_done(client, monkeypatch):
+    import src.editor_agent_model as eam
+
+    async def _done(*a, **k):  # noqa: ANN001
+        return "DONE"
+
+    monkeypatch.setattr(eam, "_post_chat", _done)
+    r = client.post("/api/editor/self-check", json={
+        "before": "data:image/png;base64,AA",
+        "after": "data:image/png;base64,AA",
+        "prompt": "ok?"})
+    assert r.status_code == 200
+    assert r.json()["done"] is True
+
+
+def test_self_check_endpoint_unavailable_when_vlm_down(client, monkeypatch):
+    import src.editor_agent_model as eam
+
+    async def _none(*a, **k):  # noqa: ANN001
+        return None
+
+    monkeypatch.setattr(eam, "_post_chat", _none)
+    r = client.post("/api/editor/self-check", json={
+        "before": "data:image/png;base64,AA",
+        "after": "data:image/png;base64,AA",
+        "prompt": "ok?"})
+    assert r.status_code == 200
+    data = r.json()
+    assert data["done"] is True
+    assert data.get("reason") == "unavailable"
+
+
+def test_self_check_endpoint_unavailable_without_images(client):
+    r = client.post("/api/editor/self-check", json={"prompt": "ok?"})
+    assert r.status_code == 200
+    data = r.json()
+    assert data["done"] is True
+    assert data.get("reason") == "unavailable"
+
+
+# ── Round: planner-unsure asks; whole-image restyle is a model edit ──────────
+def test_plan_asks_when_no_intent_matches(client):
+    """A prompt mapped to no concrete intent must ASK (2-3 concrete choices),
+    never silently apply a default photo.autoTone/adjustments/filters stack."""
+    eaar.set_editor_planner(lambda messages, owner: None)
+    r = client.post("/api/editor/plan", json={"prompt": "give it some oomph", "state": {}})
+    assert r.status_code == 200, r.text
+    data = r.json()
+    assert data["steps"] == [], data
+    ask = data.get("ask_user")
+    assert isinstance(ask, dict), data
+    assert 2 <= len(ask["options"]) <= 3, ask
+    for s in data["steps"]:
+        assert s.get("op") not in {"adjustments.apply", "filters.apply", "photo.autoTone"}
+
+
+def test_agent_path_asks_when_no_intent_matches(client):
+    eaar.set_editor_planner(lambda messages, owner: None)
+    r = client.post("/api/editor/agent",
+                    json={"prompt": "give it some oomph", "session": "s1",
+                          "editor_session": "s1", "state": {"width": 100, "height": 100}})
+    assert r.status_code == 200, r.text
+    data = r.json()
+    assert data.get("ask_user_pending") is True, data
+    assert data["steps"] == [], data
+    assert data["results"] == [], data
+    ask = data.get("ask_user")
+    assert isinstance(ask, dict), data
+    assert 2 <= len(ask["options"]) <= 3, ask
+
+
+@pytest.mark.parametrize("prompt", [
+    "make it look like an oil painting",
+    "turn this into an anime",
+    "make it a watercolour",
+    "pixel art this",
+    "make it surreal",
+    "restyle as a comic",
+])
+def test_restyle_prompts_classified_as_model_edit(prompt):
+    assert eaar._generative_kind(prompt) == "restyle"
+
+
+@pytest.mark.parametrize("prompt", [
+    "make it look like an oil painting",
+    "turn this into an anime",
+    "make it a watercolour",
+])
+def test_plan_routes_restyle_to_ai_edit_image(client, prompt):
+    eaar.set_editor_planner(lambda messages, owner: None)
+    data = client.post("/api/editor/plan", json={"prompt": prompt, "state": {}}).json()
+    ops = [s["op"] for s in data["steps"]]
+    assert ops == ["ai_edit_image"], data
+    params = data["steps"][0]["params"]
+    assert params["mode"] == "instruction", params
+    assert "exactly the same" in params["prompt"], params
+
+
+def test_restyle_does_not_hijack_tone_or_new_image(client):
+    """Restyle must not grab tone prompts, nor a brand-new image request."""
+    for prompt in ("make it black and white", "blur the background", "add a vignette",
+                   "make it look snowy", "make it warmer"):
+        assert eaar._generative_kind(prompt) != "restyle", prompt
+    assert eaar._generative_kind("create an illustration of a cat") == "add"
+
+
+def test_agent_path_forces_restyle_over_a_local_adjustment_plan(client, monkeypatch):
+    _install_provider_and_fake_tools(monkeypatch)
+    eaar.set_editor_planner(
+        lambda messages, owner: json.dumps({
+            "reply": "vibrance",
+            "steps": [{"op": "adjustments.apply",
+                       "params": {"type": "vibrance", "params": {"vibrance": 20}}}],
+        })
+    )
+    r = client.post("/api/editor/agent",
+                    json={"prompt": "make it look like an oil painting", "session": "s1",
+                          "editor_session": "s1", "state": {"width": 100, "height": 100}})
+    assert r.status_code == 200, r.text
+    ops = [s["op"] for s in r.json()["steps"]]
+    assert "ai_edit_image" in ops, r.json()["steps"]
+    assert "adjustments.apply" not in ops, r.json()["steps"]
+
+
+def test_plan_asks_when_model_returns_only_a_generic_tone_plan(client):
+    """Even when the model returns a plan, a bare whole-image tone stack for an
+    unspecified prompt is a guess -> ask (2-3 concrete choices)."""
+    eaar.set_editor_planner(lambda messages, owner: json.dumps({
+        "reply": "punchy",
+        "steps": [
+            {"op": "photo.autoTone", "params": {}},
+            {"op": "adjustments.apply", "params": {"type": "vibrance", "params": {"vibrance": 25}}},
+            {"op": "filters.apply", "params": {"id": "clarity"}},
+        ],
+    }))
+    data = client.post("/api/editor/plan", json={"prompt": "give it some oomph", "state": {}}).json()
+    assert data["steps"] == [], data
+    ask = data.get("ask_user")
+    assert isinstance(ask, dict), data
+    assert 2 <= len(ask["options"]) <= 3, ask
+
+
+def test_plan_keeps_a_generic_tone_plan_when_a_concrete_intent_matched(client):
+    eaar.set_editor_planner(lambda messages, owner: json.dumps({
+        "reply": "punchy",
+        "steps": [
+            {"op": "photo.autoTone", "params": {}},
+            {"op": "adjustments.apply", "params": {"type": "vibrance", "params": {"vibrance": 25}}},
+        ],
+    }))
+    data = client.post("/api/editor/plan", json={"prompt": "make it pop", "state": {}}).json()
+    assert data["steps"], data
+    assert not data.get("ask_user"), data
+
+
+def test_agent_path_asks_when_model_returns_only_a_generic_tone_plan(client):
+    eaar.set_editor_planner(lambda messages, owner: json.dumps({
+        "reply": "punchy", "steps": [{"op": "photo.autoTone", "params": {}}]}))
+    r = client.post("/api/editor/agent",
+                    json={"prompt": "give it some oomph", "session": "s1",
+                          "editor_session": "s1", "state": {"width": 100, "height": 100}})
+    assert r.status_code == 200, r.text
+    data = r.json()
+    assert data.get("ask_user_pending") is True, data
+    assert data["steps"] == [], data
+
+
+# ── Strict ops schema (structured outputs) ──────────────────────────────────
+
+def test_plan_schema_is_a_strict_ops_enum():
+    props = eaar.PLAN_SCHEMA["properties"]
+    enum = props["steps"]["items"]["properties"]["op"]["enum"]
+    # New model-facing ops plus the deterministic catalog.
+    for op in ("generate_edit", "select_object", "ask_user", "adjustments.apply",
+               "filters.apply", "selection.samText"):
+        assert op in enum, op
+    assert props["steps"]["items"]["required"] == ["op"]
+    assert eaar.PLAN_RESPONSE_FORMAT["type"] == "json_schema"
+    assert eaar.PLAN_RESPONSE_FORMAT["json_schema"]["schema"] is eaar.PLAN_SCHEMA
+
+
+def test_validate_plan_translates_model_ops_to_execution_ops():
+    gen = eaar._validate_plan(
+        {"reply": "r", "steps": [{"op": "generate_edit",
+                                  "params": {"prompt": "make it snowy",
+                                             "mode": "instruction"}}]})
+    assert gen["steps"][0]["op"] == "ai_edit_image"
+    sel = eaar._validate_plan(
+        {"reply": "r", "steps": [{"op": "select_object", "params": {"text": "the red car"}}]})
+    assert sel["steps"][0]["op"] == "selection.samText"
+    assert sel["steps"][0]["params"]["text"] == "the red car"
+
+
+def test_validate_plan_normalizes_ai_edit_image_inner_op():
+    # Regression: the :8097 model authors a restyle as ai_edit_image with NO inner
+    # op; it must be repaired to op "generative" (instruction mode).
+    no_inner = eaar._validate_plan({"reply": "r", "steps": [
+        {"op": "ai_edit_image", "params": {"mode": "instruction", "prompt": "oil painting"}}]})
+    assert no_inner["steps"][0]["params"]["op"] == "generative"
+    assert no_inner["steps"][0]["params"]["mode"] == "instruction"
+    # An invented inner op ("restyle") is repaired too.
+    bad = eaar._validate_plan({"reply": "r", "steps": [
+        {"op": "ai_edit_image", "params": {"op": "restyle", "mode": "instruction", "prompt": "anime"}}]})
+    assert bad["steps"][0]["params"]["op"] == "generative"
+    # generate_edit is translated AND normalized.
+    ge = eaar._validate_plan({"reply": "r", "steps": [
+        {"op": "generate_edit", "params": {"prompt": "restyle"}}]})
+    assert ge["steps"][0]["op"] == "ai_edit_image"
+    assert ge["steps"][0]["params"]["op"] == "generative"
+    # A masked edit with no inner op becomes inpaint.
+    masked = eaar._validate_plan({"reply": "r", "steps": [
+        {"op": "ai_edit_image", "params": {"mode": "masked", "prompt": "remove the sign"}}]})
+    assert masked["steps"][0]["params"]["op"] == "inpaint"
+    assert masked["steps"][0]["params"]["mode"] == "masked"
+    # A valid inner op is left untouched.
+    keep = eaar._validate_plan({"reply": "r", "steps": [
+        {"op": "ai_edit_image", "params": {"op": "remove-bg"}}]})
+    assert keep["steps"][0]["params"]["op"] == "remove-bg"
+
+
+def test_validate_plan_drops_a_single_bad_step_and_empty_plans():
+    # A single unknown/hallucinated op is DROPPED; the valid steps survive.
+    mixed = eaar._validate_plan(
+        {"reply": "r", "steps": [{"op": "adjustments.apply", "params": {}}, {"op": "evil.op"}]})
+    assert [s["op"] for s in mixed["steps"]] == ["adjustments.apply"]
+    # A plan whose only step is invalid has nothing left -> None (ask_user upstream).
+    assert eaar._validate_plan({"reply": "r", "steps": [{"op": "convert_to_grayscale"}]}) is None
+    assert eaar._validate_plan({"reply": "r", "steps": []}) is None
+    assert eaar._validate_plan("not a dict") is None
+
+
+def test_validate_plan_ask_user_needs_two_to_three_choices():
+    ok = eaar._validate_plan({"reply": "q", "steps": [],
+                              "ask_user": {"question": "Which?", "options": ["A", "B"]}})
+    assert ok["ask_user"]["options"] == [{"label": "A", "description": ""},
+                                         {"label": "B", "description": ""}]
+    trimmed = eaar._validate_plan({"reply": "q", "steps": [],
+                                   "ask_user": {"question": "Which?", "options": ["A", "B", "C", "D"]}})
+    assert len(trimmed["ask_user"]["options"]) == 3
+    # Fewer than two choices is not a valid ask_user.
+    assert eaar._validate_plan({"reply": "q", "steps": [],
+                                "ask_user": {"question": "Which?", "options": ["only"]}}) is None
+
+
+def test_plan_route_invalid_model_plan_asks_not_a_tone_default(client):
+    # A hallucinated op invalidates the plan; the route must ask, never tweak.
+    eaar.set_editor_planner(lambda messages, owner: json.dumps(
+        {"reply": "made it gray", "steps": [{"op": "convert_to_grayscale", "params": {}}]}))
+    data = client.post("/api/editor/plan", json={"prompt": "do the thing", "state": {}}).json()
+    assert data.get("ask_user"), data
+    assert data["steps"] == [], data
+
+
+def test_plan_route_translates_generate_edit(client):
+    eaar.set_editor_planner(lambda messages, owner: json.dumps(
+        {"reply": "restyling", "steps": [{"op": "generate_edit",
+                                          "params": {"prompt": "make it a watercolour",
+                                                     "mode": "instruction"}}]}))
+    data = client.post("/api/editor/plan",
+                       json={"prompt": "do the thing", "state": {"width": 100, "height": 100}}).json()
+    assert [s["op"] for s in data["steps"]] == ["ai_edit_image"], data
+
+
+def test_restyle_keeps_a_model_chosen_generate_edit(client, monkeypatch):
+    # With the strict schema + generate_edit available, the planner itself picks
+    # the AI op for a restyle; the _RESTYLE_RE keyword list is only a fast path,
+    # so a valid model generate_edit is NOT overwritten by the templated step.
+    _install_provider_and_fake_tools(monkeypatch)
+    eaar.set_editor_planner(lambda messages, owner: json.dumps(
+        {"reply": "oil painting", "steps": [{"op": "generate_edit",
+                                             "params": {"prompt": "render as an impressionist oil painting",
+                                                        "mode": "instruction"}}]}))
+    r = client.post("/api/editor/agent",
+                    json={"prompt": "make it look like an oil painting", "session": "s1",
+                          "editor_session": "s1", "state": {"width": 100, "height": 100}})
+    assert r.status_code == 200, r.text
+    data = r.json()
+    assert [s["op"] for s in data["steps"]] == ["ai_edit_image"], data["steps"]
+
+
+def test_agent_restyle_with_model_shape_repairs_inner_op(client, monkeypatch):
+    """Regression (m2334): in AGENT mode the :8097 model authors a restyle as an
+    ai_edit_image step WITHOUT a valid inner op, which used to be blocked. It must
+    be repaired to op 'generative' and run (ok)."""
+    _install_provider_and_fake_tools(monkeypatch)
+    eaar.set_editor_planner(lambda messages, owner: json.dumps(
+        {"reply": "painting", "steps": [{"op": "ai_edit_image",
+                                         "params": {"mode": "instruction",
+                                                    "prompt": "restyle as an oil painting"}}]}))
+    r = client.post("/api/editor/agent",
+                    json={"prompt": "make it look like an oil painting", "session": "s1",
+                          "editor_session": "s1", "state": {"width": 100, "height": 100}})
+    assert r.status_code == 200, r.text
+    data = r.json()
+    assert data["ok"] is True, data
+    ai = [s for s in data["steps"] if s["op"] == "ai_edit_image"]
+    assert ai and ai[0]["params"].get("op") == "generative", data["steps"]
+
+
+def test_restyle_keyword_is_still_a_fast_path_when_model_returns_no_ai_op(client, monkeypatch):
+    # Control: a model adjustment plan for a restyle is still forced to the
+    # deterministic restyle step (the fast path), so the keyword list stays a
+    # safety net.
+    _install_provider_and_fake_tools(monkeypatch)
+    eaar.set_editor_planner(lambda messages, owner: json.dumps(
+        {"reply": "vivid", "steps": [{"op": "adjustments.apply",
+                                      "params": {"type": "vibrance"}}]}))
+    r = client.post("/api/editor/agent",
+                    json={"prompt": "make it look like an oil painting", "session": "s1",
+                          "editor_session": "s1", "state": {"width": 100, "height": 100}})
+    data = r.json()
+    assert [s["op"] for s in data["steps"]] == ["ai_edit_image"], data["steps"]
+
+
+def test_editor_agent_plan_response_format_only_sent_to_local(monkeypatch):
+    from src import editor_agent_model as eam
+
+    calls = []
+
+    async def _fake_post(base, model, messages, headers, timeout, **kwargs):
+        calls.append((base, kwargs.get("response_format")))
+        return json.dumps({"reply": "r", "steps": [{"op": "adjustments.apply",
+                                                     "params": {"type": "vibrance"}}]})
+
+    monkeypatch.setattr(eam, "_post_chat", _fake_post)
+    monkeypatch.setattr(eam, "_candidates", lambda owner, override: [
+        {"base": "http://100.69.120.65:8097/v1", "model": "Qwen/Qwen3.5-9B",
+         "headers": None, "source": "local"},
+        {"base": "https://api.deepseek.com/v1", "model": "deepseek-v4-flash",
+         "headers": None, "source": "hosted"},
+    ])
+    import asyncio
+    fmt = {"type": "json_schema", "json_schema": {"name": "x", "schema": {}}}
+    out = asyncio.run(eam.plan_with_editor_agent(
+        [{"role": "user", "content": "x"}], response_format=fmt))
+    assert out is not None
+    # The local (first) candidate got the structured-output constraint; the
+    # request short-circuits on the first success, so only the local call ran.
+    assert calls and calls[0][0] == "http://100.69.120.65:8097/v1"
+    assert calls[0][1] is fmt
+    assert all(base != "https://api.deepseek.com/v1" for base, _ in calls)
diff --git a/tests/test_docs_no_orphan_images.py b/tests/test_docs_no_orphan_images.py
index 2696f04f4..5c3d27c60 100644
--- a/tests/test_docs_no_orphan_images.py
+++ b/tests/test_docs_no_orphan_images.py
@@ -1,10 +1,9 @@
 """Repository asset ownership guards for issues #1335 and #6175.
 
 Public Markdown and landing-page media belong in website/, while shared
-optional README/packaging imagery belongs in assets/branding/. Retained images
-in either managed root must be referenced by tracked text, and every retained
-website video must be referenced by the site's entry point. Publication can
-operate with no imagery or videos.
+README/packaging imagery belongs in assets/branding/. Images in either managed
+root must be referenced by tracked text, and every tracked website video must
+be referenced by the site's entry point.
 """
 import re
 import subprocess
@@ -42,8 +41,7 @@ def _tracked(*paths_under):
         return None
     if out.returncode != 0:
         return None
-    return [REPO / line for line in out.stdout.splitlines()
-            if line.strip() and (REPO / line).is_file()]
+    return [REPO / line for line in out.stdout.splitlines() if line.strip()]
 
 
 def test_no_orphan_documentation_or_branding_images():
@@ -51,6 +49,9 @@ def test_no_orphan_documentation_or_branding_images():
     if managed_files is None:
         pytest.skip("not a git checkout")
     managed_images = [p for p in managed_files if p.suffix.lower() in IMAGE_EXTS]
+    assert any("assets/branding" in p.as_posix() for p in managed_images), (
+        "expected assets/branding/ to contain the shared project imagery"
+    )
 
     # All tracked text we might reference an image from.
     all_tracked = _tracked(".") or []
@@ -93,6 +94,7 @@ def test_pages_site_owns_its_entrypoint_and_media():
         assert text.startswith("---\nlayout: default\n---\n"), guide
 
     website_videos = [p for p in website_files if p.suffix.lower() in VIDEO_EXTS]
+    assert website_videos, "expected website/ to contain the landing-page videos"
 
     entrypoint = (REPO / "website/index.html").read_text(encoding="utf-8")
     unreferenced = [
diff --git a/tests/test_edit_image_tool.py b/tests/test_edit_image_tool.py
index a3bc35c8a..fe67edc6f 100644
--- a/tests/test_edit_image_tool.py
+++ b/tests/test_edit_image_tool.py
@@ -2,6 +2,7 @@ import asyncio
 import json
 from types import SimpleNamespace
 
+import pytest
 from PIL import Image
 
 from src.tools.image import do_edit_image
@@ -122,7 +123,8 @@ def test_edit_image_rejects_actions_without_complete_input_contract():
     assert "Use prompt, upscale or rembg" in result["error"]
 
 
-def test_prompt_edit_forwards_owned_pixels_and_preserves_original(monkeypatch, tmp_path):
+@pytest.mark.parametrize('incognito', [False, True])
+def test_prompt_edit_forwards_owned_pixels_and_preserves_original(monkeypatch, tmp_path, incognito):
     source_path = tmp_path / 'source.png'
     Image.new('RGB', (3, 2), 'red').save(source_path)
     original = source_path.read_bytes()
@@ -135,9 +137,9 @@ def test_prompt_edit_forwards_owned_pixels_and_preserves_original(monkeypatch, t
         return {'image_id': 'edited', 'image_url': '/api/generated-image/edited.png'}
     from pathlib import Path
     monkeypatch.setattr('src.ai_interaction.do_edit_image', edit)
-    result = asyncio.run(do_edit_image(json.dumps({'image_id': 'source-id', 'action': 'prompt', 'prompt': 'Add another cow'}), owner='alice'))
+    result = asyncio.run(do_edit_image(json.dumps({'image_id': 'source-id', 'action': 'prompt', 'prompt': 'Add another cow'}), owner='alice', incognito=incognito))
     assert result['image_id'] == 'edited'
-    assert calls == [('Add another cow', original, {'session_id': 'session-1', 'owner': 'alice', 'size': 'auto'})]
+    assert calls == [('Add another cow', original, {'session_id': 'session-1', 'owner': 'alice', 'size': 'auto', 'incognito': incognito})]
     assert source_path.read_bytes() == original
     denied = asyncio.run(do_edit_image('{"image_id":"source-id","action":"prompt","prompt":"edit"}', owner=None))
     assert denied['error'] == 'Image not found'
@@ -165,7 +167,7 @@ def test_uploaded_image_edit_uses_owner_scoped_reference(monkeypatch, tmp_path):
     monkeypatch.setattr('src.ai_interaction.do_edit_image', edit)
     args = '{"image_id":"odysseus://attachment/upload.jpg","action":"prompt","prompt":"Make more realistic"}'
     assert asyncio.run(do_edit_image(args, owner='alice')) == {'image_id': 'edited'}
-    assert calls == [('Make more realistic', str(path), {'owner': 'alice', 'size': 'auto'})]
+    assert calls == [('Make more realistic', str(path), {'owner': 'alice', 'size': 'auto', 'incognito': False})]
     assert resolutions == [('upload.jpg', {'owner': 'alice', 'allow_admin': False})]
     assert 'error' in asyncio.run(do_edit_image(args, owner='bob'))
     assert len(calls) == 1
@@ -173,3 +175,23 @@ def test_uploaded_image_edit_uses_owner_scoped_reference(monkeypatch, tmp_path):
     disabled = asyncio.run(do_edit_image(args, owner='alice'))
     assert 'disabled' in disabled['error']
     assert len(calls) == 1
+
+
+def test_private_upscale_does_not_save_image_or_gallery_record(monkeypatch, tmp_path):
+    source_path = tmp_path / 'source.png'
+    Image.new('RGB', (3, 2), 'red').save(source_path)
+    original = source_path.read_bytes()
+    db = _Db(_source(source_path.name))
+    monkeypatch.setattr('core.database.SessionLocal', lambda: db)
+    monkeypatch.setattr('src.constants.GENERATED_IMAGES_DIR', str(tmp_path))
+    result = asyncio.run(do_edit_image(
+        '{"image_id":"source-id","action":"upscale","scale":2}',
+        owner='alice', incognito=True,
+    ))
+    assert result['exit_code'] == 0
+    assert result['image_url'].startswith('data:image/png;base64,')
+    assert not result['image_id']
+    assert db.added == []
+    assert not db.committed
+    assert list(tmp_path.iterdir()) == [source_path]
+    assert source_path.read_bytes() == original
diff --git a/tests/test_editor_agent_model_resolution.py b/tests/test_editor_agent_model_resolution.py
new file mode 100644
index 000000000..3a30903d6
--- /dev/null
+++ b/tests/test_editor_agent_model_resolution.py
@@ -0,0 +1,71 @@
+"""Server health audit fix: the local editor VLM returned 400s when asked for a
+model id it does not serve (the client default 'Qwen3.5-9B-MLX-8bit', or the
+stale caption model 'Qwen/Qwen3-VL-30B'). ``_resolve_model`` maps the requested
+id to one the base actually serves."""
+import asyncio
+
+from src import editor_agent_model as eam
+
+
+def _cache(base, ids):
+    eam._MODELS_CACHE[base] = set(ids)
+
+
+def test_resolve_model_keeps_a_served_request():
+    base = "http://x:1/v1"
+    _cache(base, ["Qwen/Qwen3.5-9B", "other"])
+    assert asyncio.run(eam._resolve_model(base, "Qwen/Qwen3.5-9B", "Qwen/Qwen3.5-9B")) == "Qwen/Qwen3.5-9B"
+
+
+def test_resolve_model_falls_back_when_requested_is_not_served():
+    base = "http://x:2/v1"
+    _cache(base, ["Qwen/Qwen3.5-9B"])
+    # e.g. the client's MLX build name, or a stale caption model id.
+    assert asyncio.run(eam._resolve_model(base, "Qwen3.5-9B-MLX-8bit", "Qwen/Qwen3.5-9B")) == "Qwen/Qwen3.5-9B"
+    assert asyncio.run(eam._resolve_model(base, "Qwen/Qwen3-VL-30B", "Qwen/Qwen3.5-9B")) == "Qwen/Qwen3.5-9B"
+
+
+def test_resolve_model_picks_a_served_id_when_fallback_absent():
+    base = "http://x:3/v1"
+    _cache(base, ["B", "A"])
+    assert asyncio.run(eam._resolve_model(base, "nope", "also-nope")) == "A"
+
+
+def test_resolve_model_keeps_request_when_served_list_unknown():
+    base = "http://x:4/v1"
+    _cache(base, [])
+    # Server unreachable / no models listed -> don't rewrite the request.
+    assert asyncio.run(eam._resolve_model(base, "some/model", "fallback")) == "some/model"
+
+
+def test_self_check_resolves_the_model_before_calling(monkeypatch):
+    base = eam.local_bases()[0]
+    _cache(base, ["Qwen/Qwen3.5-9B"])
+    seen = {}
+
+    async def fake_post(b, model, messages, headers, timeout, **kwargs):
+        seen["model"] = model
+        return "DONE"
+
+    monkeypatch.setattr(eam, "_post_chat", fake_post)
+    out = asyncio.run(eam.self_check(
+        "data:image/png;base64,AAAA", "data:image/png;base64,BBBB",
+        "make it brighter", model="Qwen3.5-9B-MLX-8bit"))
+    assert seen["model"] == "Qwen/Qwen3.5-9B"
+    assert out["done"] is True
+
+
+def test_caption_resolves_the_caption_model(monkeypatch):
+    seen = {}
+
+    async def fake_post(b, model, messages, headers, timeout, **kwargs):
+        seen["base"] = b
+        seen["model"] = model
+        return "a photo"
+
+    monkeypatch.setattr(eam, "_post_chat", fake_post)
+    import src.editor_agent_model as m
+    _cache(m.caption_base(), ["Qwen/Qwen3.5-9B"])
+    txt = asyncio.run(m.caption_image("data:image/png;base64,AAAA"))
+    assert txt == "a photo"
+    assert seen["model"] == "Qwen/Qwen3.5-9B"
diff --git a/tests/test_editor_planner_routing.py b/tests/test_editor_planner_routing.py
new file mode 100644
index 000000000..d7936e69d
--- /dev/null
+++ b/tests/test_editor_planner_routing.py
@@ -0,0 +1,171 @@
+"""Planner routing regression suite (HARNESS-owned).
+
+Turns PHOTOSHOP's bench prompt families (vague, restyle, bg-remove/scene,
+tone/auto, generative, structural) into assertions on the ROUTE CLASS the
+server planner picks, so a future planner change cannot silently re-break
+routing. The classes are:
+
+  ask_user       -> the planner is unsure; it must ask with 2-3 choices and
+                    apply NO operations (never a silent tone default)
+  deterministic  -> a deterministic editor op / recipe (adjustments, filters,
+                    crop, text, rotate, fill, recolour ...)
+  ai_edit_image  -> a generative image-model edit (content add/remove/replace,
+                    restyle, look)
+  generate_image -> text-to-image for a brand-new image
+
+These use the pure routing helpers (``_plan_special`` / ``_generative_kind`` /
+``_fallback_plan``), so no model or network call is made.
+"""
+import json
+
+import pytest
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+
+from routes import editor_agent_routes as eaar
+
+_STATE = {"width": 900, "height": 600}
+_PROVIDER = True
+
+
+@pytest.fixture(autouse=True)
+def _reset_planner():
+    eaar.set_editor_planner(None)
+    yield
+    eaar.set_editor_planner(None)
+
+
+@pytest.fixture()
+def client():
+    app = FastAPI()
+    app.include_router(eaar.setup_editor_agent_routes())
+    return TestClient(app)
+
+
+def _classify(prompt, provider=_PROVIDER):
+    """Return (route_class, ops) for a prompt using the deterministic helpers."""
+    special = eaar._plan_special(prompt, _STATE, provider)
+    if special:
+        steps = list(special[0])
+    else:
+        fallback = eaar._fallback_plan(prompt)
+        if fallback.get("ask_user"):
+            return "ask_user", []
+        steps = list(fallback.get("steps") or [])
+    ops = [str(s.get("op") or "") for s in steps]
+    if "generate_image" in ops:
+        return "generate_image", ops
+    if "ai_edit_image" in ops:
+        return "ai_edit_image", ops
+    return "deterministic", ops
+
+
+# (prompt, expected route class)
+BENCH_ROUTING = [
+    # vague -> ask (never a silent tone tweak)
+    ("do the thing", "ask_user"),
+    ("give it some oomph", "ask_user"),
+    ("make it better", "ask_user"),
+    # whole-image restyle -> model edit
+    ("make it look like an oil painting", "ai_edit_image"),
+    ("turn it into an anime", "ai_edit_image"),
+    ("make it a comic book illustration", "ai_edit_image"),
+    ("make it look like cyberpunk", "ai_edit_image"),
+    # background / scene replacement -> model edit
+    ("put her on a beach", "ai_edit_image"),
+    ("make the background nicer", "ai_edit_image"),
+    ("make it snowy", "ai_edit_image"),
+    # generative content add / remove -> model edit
+    ("add a full moon in the sky", "ai_edit_image"),
+    ("remove the distractions", "ai_edit_image"),
+    ("remove the person on the left", "ai_edit_image"),
+    # brand-new image -> text-to-image
+    ("create a new image of a full moon", "generate_image"),
+    ("generate an image of a sunset", "generate_image"),
+    ("make a logo", "generate_image"),
+    # tone / auto / look / structural -> deterministic
+    ("make it black and white", "deterministic"),
+    ("make it pop", "deterministic"),
+    ("make it look professional", "deterministic"),
+    ("make only the red car blue", "deterministic"),
+    ("make a 1080x1350 Instagram post from this", "deterministic"),
+    ("add a title TOKYO with a drop shadow", "deterministic"),
+    ("extend the canvas to 16:9", "deterministic"),
+    ("save as PSD with layers", "deterministic"),
+    ("fill the white area with red", "deterministic"),
+    ("rotate the whole image 90 degrees", "deterministic"),
+]
+
+
+@pytest.mark.parametrize("prompt,expected", BENCH_ROUTING)
+def test_bench_prompts_route_to_expected_class(prompt, expected):
+    route_class, ops = _classify(prompt)
+    assert route_class == expected, f"{prompt!r} -> {route_class} {ops} (want {expected})"
+
+
+def test_ask_plans_offer_two_to_three_choices():
+    for prompt in ("do the thing", "give it some oomph", "make it better"):
+        plan = eaar._fallback_plan(prompt)
+        ask = plan.get("ask_user")
+        assert isinstance(ask, dict), prompt
+        opts = ask.get("options") or []
+        assert 2 <= len(opts) <= 3, (prompt, opts)
+        assert plan.get("steps") == []
+
+
+def test_object_removal_uses_selection_plus_model_edit():
+    _cls, ops = _classify("remove the person on the left")
+    assert "ai_edit_image" in ops
+    assert any(op.startswith("selection.") for op in ops), ops
+
+
+def test_recolour_never_uses_a_flat_fill_or_a_global_tint():
+    # Every recolour selects the object by description and either shifts the
+    # masked hue or asks the image model for the masked region — never a flat
+    # selection.fill and never a whole-image adjustments.apply.
+    for prompt in ("make only the red car blue", "make the red car white", "make the flowers bright pink"):
+        _cls, ops = _classify(prompt)
+        assert "selection.samText" in ops, (prompt, ops)
+        assert "selection.fill" not in ops, (prompt, ops)
+        assert "adjustments.apply" not in ops, (prompt, ops)
+
+
+def test_chromatic_recolour_is_a_deterministic_masked_hue_shift():
+    cls, ops = _classify("make only the red car blue")
+    assert cls == "deterministic", ops
+    assert ops == ["selection.samText", "adjustments.applyMasked"], ops
+
+
+def test_new_image_request_from_scratch_vs_edit_of_current_photo():
+    # A photo edit ("make it a <style>") must NOT be treated as a new image.
+    assert eaar._generative_kind("make it a comic book illustration") == "restyle"
+    assert eaar._is_new_image_request("make it a comic book illustration") is False
+    # A from-scratch generation still is.
+    assert eaar._is_new_image_request("create an illustration of a cat") is True
+    assert eaar._generative_kind("create an illustration of a cat") == "add"
+
+
+def test_plan_route_returns_deterministic_recolour(client):
+    eaar.set_editor_planner(lambda messages, owner: json.dumps({"reply": "ok", "steps": []}))
+    r = client.post("/api/editor/plan", json={"prompt": "make only the red car blue", "state": _STATE})
+    assert r.status_code == 200
+    data = r.json()
+    assert data["planner"] == "deterministic"
+    assert [s["op"] for s in data["steps"]] == ["selection.samText", "adjustments.applyMasked"]
+
+
+def test_plan_route_asks_for_a_vague_prompt(client):
+    eaar.set_editor_planner(lambda messages, owner: json.dumps({"reply": "ok", "steps": []}))
+    r = client.post("/api/editor/plan", json={"prompt": "do the thing", "state": _STATE})
+    assert r.status_code == 200
+    data = r.json()
+    assert data.get("ask_user"), data
+    assert data.get("steps") == []
+
+
+def test_plan_route_routes_restyle_to_model_edit(client):
+    eaar.set_editor_planner(lambda messages, owner: json.dumps({"reply": "ok", "steps": []}))
+    r = client.post("/api/editor/plan", json={"prompt": "turn it into an anime", "state": _STATE})
+    assert r.status_code == 200
+    ops = [s["op"] for s in r.json()["steps"]]
+    assert "ai_edit_image" in ops, ops
diff --git a/tests/test_editor_writing_action_routing.py b/tests/test_editor_writing_action_routing.py
index 26ee55aec..b436439cb 100644
--- a/tests/test_editor_writing_action_routing.py
+++ b/tests/test_editor_writing_action_routing.py
@@ -11,6 +11,7 @@ from src.clean_agent_preview import (
 from src.turn_contract import (
     editor_request_instructions, requested_capabilities, selected_tools_for_request,
     preserve_bound_editor_selected_tools, resolve_turn_contract,
+    targets_bound_editor_request,
 )
 from src.tool_schemas import FUNCTION_TOOL_SCHEMAS
 from src.tool_policy import ToolPolicy
@@ -72,6 +73,16 @@ def test_direct_edits_share_the_capability_router(prompt):
     assert not active_editor_suggestion_request(doc, prompt)
 
 
+@pytest.mark.parametrize('prompt', [
+    'ga mer ut pa att vi tanker pa framtid for bjorn och att vi faktist trivs sa bra har',
+    'Go more into how we are thinking about the future.',
+])
+def test_implicit_revision_followups_route_to_active_document_only(prompt):
+    assert requested_capabilities(prompt, active_document=True) == {'documents'}
+    assert requested_capabilities(prompt, active_document=False) == frozenset()
+    assert targets_bound_editor_request(prompt)
+
+
 def test_source_review_still_requires_tool_completion_after_research():
     schemas = [s for s in FUNCTION_TOOL_SCHEMAS if s['function']['name'] in {'web_search', 'suggest_document'}]
     assert required_active_editor_tool_choice(active_editor_target=True, suggestion_target=True,
diff --git a/tests/test_email_imap_timeout.py b/tests/test_email_imap_timeout.py
index 94e7133d2..c170106c1 100644
--- a/tests/test_email_imap_timeout.py
+++ b/tests/test_email_imap_timeout.py
@@ -26,7 +26,7 @@ class _FakeSock:
 class _FakeIMAP:
     calls = []
 
-    def __init__(self, host, port, timeout=None, **_policy):
+    def __init__(self, host, port, timeout=None):
         self.host = host
         self.port = port
         self.timeout = timeout
@@ -60,8 +60,8 @@ def test_open_imap_connection_uses_shared_timeout_for_implicit_ssl(monkeypatch):
     import routes.email_helpers as helpers
 
     _FakeIMAP.calls = []
-    monkeypatch.setattr(helpers, "_PolicyIMAP4", _FakeIMAP)
-    monkeypatch.setattr(helpers, "_PolicyIMAP4_SSL", _FakeIMAPSSL)
+    monkeypatch.setattr(helpers.imaplib, "IMAP4", _FakeIMAP)
+    monkeypatch.setattr(helpers.imaplib, "IMAP4_SSL", _FakeIMAPSSL)
 
     conn = _open_imap_connection("imap.one.com", 993, starttls=False)
 
@@ -75,8 +75,8 @@ def test_open_imap_connection_supports_starttls(monkeypatch):
     import routes.email_helpers as helpers
 
     _FakeIMAP.calls = []
-    monkeypatch.setattr(helpers, "_PolicyIMAP4", _FakeIMAP)
-    monkeypatch.setattr(helpers, "_PolicyIMAP4_SSL", _FakeIMAPSSL)
+    monkeypatch.setattr(helpers.imaplib, "IMAP4", _FakeIMAP)
+    monkeypatch.setattr(helpers.imaplib, "IMAP4_SSL", _FakeIMAPSSL)
 
     _open_imap_connection("imap.local", 143, starttls=True)
 
@@ -99,7 +99,7 @@ async def test_account_config_uses_shared_imap_timeout(monkeypatch):
         def logout(self):
             captured["logout"] = True
 
-    def fake_open(host, port, *, starttls, timeout, **_policy):
+    def fake_open(host, port, *, starttls, timeout):
         captured["open"] = (host, port, starttls, timeout)
         return _Conn()
 
diff --git a/tests/test_email_list_stale_while_revalidate.py b/tests/test_email_list_stale_while_revalidate.py
new file mode 100644
index 000000000..559994a10
--- /dev/null
+++ b/tests/test_email_list_stale_while_revalidate.py
@@ -0,0 +1,79 @@
+"""Email list stale-while-revalidate (SWR) regression tests.
+
+A plain list view must never block ~2-5 s on IMAP while we already hold a
+recent snapshot or a durable index: it should return the snapshot immediately
+(with ``sync.stale``) and refresh in the background. Blocking IMAP only remains
+for a genuine cold start (no snapshot AND no indexed rows).
+"""
+import asyncio
+import pathlib
+
+from routes.email import email_routes as er
+
+SRC = pathlib.Path(er.__file__).read_text(encoding="utf-8")
+
+
+def _list_endpoint():
+    router = er.setup_email_routes()
+    for route in router.routes:
+        if getattr(route, "name", "") == "list_emails":
+            return route.endpoint
+    raise AssertionError("list_emails route not found")
+
+
+def _call(endpoint, **over):
+    kwargs = dict(
+        folder="INBOX", limit=50, offset=0, filter="all", from_addr=None,
+        account_id=None, has_attachments=0, date_from=None, date_to=None,
+        cached_only=0, cache_bust=None, refresh=0, owner="pewds",
+    )
+    kwargs.update(over)
+    return asyncio.run(endpoint(**kwargs))
+
+
+def test_list_returns_index_snapshot_with_a_stale_marker_without_blocking_on_imap(monkeypatch):
+    endpoint = _list_endpoint()
+    monkeypatch.setattr(
+        er, "_email_index_list",
+        lambda owner, account_id, folder, filter_, limit, offset, has_att: (
+            [{"uid": "11", "subject": "Indexed", "is_read": False}], 1, "2026-10-11T00:00:00Z",
+        ),
+    )
+    # The synchronous path must never open IMAP; if it did the request would
+    # raise instead of returning the index snapshot immediately.
+    monkeypatch.setattr(er, "_imap_connect", lambda *a, **k: (_ for _ in ()).throw(
+        AssertionError("SWR must not open IMAP when an index snapshot exists")))
+
+    result = _call(endpoint, cache_bust="123")
+    assert result["total"] == 1
+    assert [e["uid"] for e in result["emails"]] == ["11"]
+    assert result["sync"]["stale"] is True
+    assert result["sync"]["source"] in ("index", "cache_stale")
+
+
+def test_cold_start_with_no_snapshot_and_no_index_is_not_marked_stale(monkeypatch):
+    # With neither a snapshot nor an index, SWR must NOT fire: the request
+    # falls through to the real (blocking) path, so the response is not a
+    # stale-marked snapshot.
+    endpoint = _list_endpoint()
+    monkeypatch.setattr(er, "_email_index_list", lambda *a, **k: ([], 0, None))
+    monkeypatch.setattr(er, "_imap_connect", lambda *a, **k: (_ for _ in ()).throw(
+        RuntimeError("offline test")))
+    try:
+        result = _call(endpoint)
+    except Exception:
+        return  # the cold path legitimately attempted real IMAP
+    assert isinstance(result, dict)
+    assert not (result.get("sync") or {}).get("stale")
+
+
+def test_swr_contract_is_wired_into_the_list_path():
+    assert "_LIST_STALE" in SRC
+    assert "def _list_stale_put" in SRC
+    assert "def _schedule_list_refresh" in SRC
+    assert 'sync_meta["source"] = "cache_stale"' in SRC
+    assert 'sync_meta["stale"] = True' in SRC
+    # The manual-refresh contract the UI relies on must stay intact.
+    assert "manual_refresh = bool(refresh)" in SRC
+    assert "_invalidate_list_cache(account_id, folder)" in SRC
+    assert "cached_rows = {} if refresh else _email_index_rows" in SRC
diff --git a/tests/test_email_send_only_no_inbox.py b/tests/test_email_send_only_no_inbox.py
index c7ed2eefb..1af014aae 100644
--- a/tests/test_email_send_only_no_inbox.py
+++ b/tests/test_email_send_only_no_inbox.py
@@ -64,7 +64,7 @@ def test_imap_connect_with_host_still_connects(monkeypatch):
         def login(self, user, password):
             opened["login"] = (user, password)
 
-    def _fake_open(host, port, *, starttls, timeout, **_policy):
+    def _fake_open(host, port, *, starttls, timeout):
         opened["host"] = host
         return _FakeConn()
 
diff --git a/tests/test_email_smtp_security.py b/tests/test_email_smtp_security.py
index d64fbdf1e..590a5e60c 100644
--- a/tests/test_email_smtp_security.py
+++ b/tests/test_email_smtp_security.py
@@ -12,7 +12,7 @@ from routes.email_helpers import _send_smtp_message
 class _FakeSMTP:
     calls = []
 
-    def __init__(self, host, port, timeout=None, **_policy):
+    def __init__(self, host, port, timeout=None):
         self.host = host
         self.port = port
         self.timeout = timeout
@@ -54,8 +54,8 @@ def test_send_smtp_message_supports_plain_smtp(monkeypatch):
     import routes.email_helpers as helpers
 
     _FakeSMTP.calls = []
-    monkeypatch.setattr(helpers, "_PolicySMTP", _FakeSMTP)
-    monkeypatch.setattr(helpers, "_PolicySMTP_SSL", _FakeSMTPSSL)
+    monkeypatch.setattr(helpers.smtplib, "SMTP", _FakeSMTP)
+    monkeypatch.setattr(helpers.smtplib, "SMTP_SSL", _FakeSMTPSSL)
 
     _send_smtp_message(_cfg("none"), "from@example.com", ["to@example.com"], "hello")
 
@@ -68,8 +68,8 @@ def test_send_smtp_message_supports_explicit_starttls(monkeypatch):
     import routes.email_helpers as helpers
 
     _FakeSMTP.calls = []
-    monkeypatch.setattr(helpers, "_PolicySMTP", _FakeSMTP)
-    monkeypatch.setattr(helpers, "_PolicySMTP_SSL", _FakeSMTPSSL)
+    monkeypatch.setattr(helpers.smtplib, "SMTP", _FakeSMTP)
+    monkeypatch.setattr(helpers.smtplib, "SMTP_SSL", _FakeSMTPSSL)
 
     _send_smtp_message(_cfg("starttls", port=2525), "from@example.com", ["to@example.com"], "hello")
 
@@ -82,8 +82,8 @@ def test_send_smtp_message_defaults_587_to_starttls(monkeypatch):
     import routes.email_helpers as helpers
 
     _FakeSMTP.calls = []
-    monkeypatch.setattr(helpers, "_PolicySMTP", _FakeSMTP)
-    monkeypatch.setattr(helpers, "_PolicySMTP_SSL", _FakeSMTPSSL)
+    monkeypatch.setattr(helpers.smtplib, "SMTP", _FakeSMTP)
+    monkeypatch.setattr(helpers.smtplib, "SMTP_SSL", _FakeSMTPSSL)
 
     cfg = _cfg("", port=587)
     _send_smtp_message(cfg, "from@example.com", ["to@example.com"], "hello")
@@ -96,8 +96,8 @@ def test_send_smtp_message_uses_ssl_when_configured(monkeypatch):
     import routes.email_helpers as helpers
 
     _FakeSMTP.calls = []
-    monkeypatch.setattr(helpers, "_PolicySMTP", _FakeSMTP)
-    monkeypatch.setattr(helpers, "_PolicySMTP_SSL", _FakeSMTPSSL)
+    monkeypatch.setattr(helpers.smtplib, "SMTP", _FakeSMTP)
+    monkeypatch.setattr(helpers.smtplib, "SMTP_SSL", _FakeSMTPSSL)
 
     _send_smtp_message(_cfg("ssl", port=465), "from@example.com", ["to@example.com"], "hello")
 
diff --git a/tests/test_email_test_connection_oauth.py b/tests/test_email_test_connection_oauth.py
index 107a79fbb..cc524d958 100644
--- a/tests/test_email_test_connection_oauth.py
+++ b/tests/test_email_test_connection_oauth.py
@@ -89,8 +89,8 @@ async def test_test_connection_oauth_account_uses_xoauth2_for_imap_and_smtp():
 
     with mock.patch("core.database.SessionLocal", Factory), \
          mock.patch("routes.email_routes._open_imap_connection", return_value=mock_imap_conn), \
-         mock.patch("routes.email_routes._PolicySMTP", return_value=mock_smtp_conn), \
-         mock.patch("routes.email_routes._PolicySMTP_SSL", return_value=mock_smtp_conn), \
+         mock.patch("routes.email_routes.smtplib.SMTP", return_value=mock_smtp_conn), \
+         mock.patch("routes.email_routes.smtplib.SMTP_SSL", return_value=mock_smtp_conn), \
          mock.patch("routes.email_routes._get_valid_google_token", return_value="ya29.live") as token_getter:
         result = await test_conn(req=_FakeReq(), owner="alice")
 
@@ -141,8 +141,8 @@ async def test_test_connection_password_account_still_uses_login():
 
     with mock.patch("core.database.SessionLocal", Factory), \
          mock.patch("routes.email_routes._open_imap_connection", return_value=mock_imap_conn), \
-         mock.patch("routes.email_routes._PolicySMTP", return_value=mock_smtp_conn), \
-         mock.patch("routes.email_routes._PolicySMTP_SSL", return_value=mock_smtp_conn):
+         mock.patch("routes.email_routes.smtplib.SMTP", return_value=mock_smtp_conn), \
+         mock.patch("routes.email_routes.smtplib.SMTP_SSL", return_value=mock_smtp_conn):
         result = await test_conn(req=_FakeReq(), owner="alice")
 
     assert result["ok"] is True
@@ -187,8 +187,8 @@ async def test_test_connection_rejects_non_google_hosts_before_oauth_auth():
 
     with mock.patch("core.database.SessionLocal", Factory), \
          mock.patch("routes.email_routes._open_imap_connection") as open_imap, \
-         mock.patch("routes.email_routes._PolicySMTP") as open_smtp, \
-         mock.patch("routes.email_routes._PolicySMTP_SSL") as open_smtp_ssl, \
+         mock.patch("routes.email_routes.smtplib.SMTP") as open_smtp, \
+         mock.patch("routes.email_routes.smtplib.SMTP_SSL") as open_smtp_ssl, \
          mock.patch("routes.email_routes._get_valid_google_token") as token_getter:
         result = await test_conn(req=_FakeReq(), owner="alice")
 
@@ -238,8 +238,8 @@ async def test_test_connection_rejects_insecure_oauth_transports_before_auth():
 
     with mock.patch("core.database.SessionLocal", Factory), \
          mock.patch("routes.email_routes._open_imap_connection") as open_imap, \
-         mock.patch("routes.email_routes._PolicySMTP") as open_smtp, \
-         mock.patch("routes.email_routes._PolicySMTP_SSL") as open_smtp_ssl, \
+         mock.patch("routes.email_routes.smtplib.SMTP") as open_smtp, \
+         mock.patch("routes.email_routes.smtplib.SMTP_SSL") as open_smtp_ssl, \
          mock.patch("routes.email_routes._get_valid_google_token") as token_getter:
         result = await test_conn(req=_FakeReq(), owner="alice")
 
@@ -336,10 +336,10 @@ async def test_test_connection_verifies_imap_tls_before_loading_oauth_token(
              "routes.email_routes.ssl.create_default_context",
              return_value=context,
          ), mock.patch(
-             "routes.email_helpers._PolicyIMAP4",
+             "routes.email_helpers.imaplib.IMAP4",
              return_value=starttls_conn,
          ) as imap_cls, mock.patch(
-             "routes.email_helpers._PolicyIMAP4_SSL",
+             "routes.email_helpers.imaplib.IMAP4_SSL",
              side_effect=ssl.SSLCertVerificationError("untrusted certificate"),
          ) as imap_ssl_cls, mock.patch(
              "routes.email_routes._get_valid_google_token"
@@ -412,10 +412,10 @@ async def test_test_connection_verifies_smtp_tls_before_loading_oauth_token(
              "routes.email_routes.ssl.create_default_context",
              return_value=context,
          ), mock.patch(
-             "routes.email_routes._PolicySMTP",
+             "routes.email_routes.smtplib.SMTP",
              return_value=starttls_smtp,
          ) as smtp_cls, mock.patch(
-             "routes.email_routes._PolicySMTP_SSL",
+             "routes.email_routes.smtplib.SMTP_SSL",
              side_effect=ssl.SSLCertVerificationError("untrusted certificate"),
          ) as smtp_ssl_cls, mock.patch(
              "routes.email_routes._get_valid_google_token"
diff --git a/tests/test_gallery_cloud_inpaint.py b/tests/test_gallery_cloud_inpaint.py
index ea8e912b6..0bfbd7ffe 100644
--- a/tests/test_gallery_cloud_inpaint.py
+++ b/tests/test_gallery_cloud_inpaint.py
@@ -76,3 +76,158 @@ def test_mixed_endpoint_requires_configured_image_model(monkeypatch):
     assert lookup(Query(), endpoint.base_url, 'alice', 'text-model') is None
     assert lookup(Query(), endpoint.base_url, 'alice', 'openai/gpt-image-1') is None
     assert lookup(Query(), 'https://unregistered.test/v1', 'alice', 'openai/gpt-5-image') is None
+
+
+def _form_fields(content, content_type):
+    """Parse simple multipart form fields (text parts only) from a request body."""
+    boundary = content_type.split('boundary=')[1].strip().strip('"')
+    fields = {}
+    for part in content.split(('--' + boundary).encode()):
+        if b'name="' not in part:
+            continue
+        head, _, body = part.partition(b'\r\n\r\n')
+        import re as _re
+        match = _re.search(rb'name="([^"]+)"', head)
+        if not match:
+            continue
+        fields[match.group(1).decode()] = body.rstrip(b'\r\n-').decode('latin1')
+    return fields
+
+
+def _self_hosted_inpaint(monkeypatch, image, mask, body_extra, respond, include_mask=True):
+    base_url = 'http://100.69.120.65:8188/v1'
+    endpoint = SimpleNamespace(base_url=base_url, api_key='local', owner='alice')
+    monkeypatch.setattr(gallery, 'SessionLocal', lambda: SimpleNamespace(close=lambda: None))
+    monkeypatch.setattr(gallery, 'require_privilege', lambda *a: 'alice')
+    monkeypatch.setattr(gallery, '_visible_image_endpoint_for_base', lambda *a: endpoint)
+    monkeypatch.setattr('src.url_safety.check_outbound_url', lambda *a, **k: (True, ''))
+    _real_client = httpx.AsyncClient
+    monkeypatch.setattr(httpx, 'AsyncClient',
+                        lambda **kw: _real_client(transport=httpx.MockTransport(respond), **kw))
+
+    class Request:
+        async def json(self):
+            payload = {'_endpoint': base_url, 'image': png(image), 'prompt': 'do a thing'}
+            if include_mask:
+                payload['mask'] = png(mask)
+            payload.update(body_extra)
+            return payload
+
+    route = next(r for r in gallery.setup_gallery_routes().routes if r.path == '/api/image/inpaint')
+    return asyncio.run(route.endpoint(Request()))
+
+
+def test_self_hosted_inpaint_caps_oversize_and_restores_dimensions(monkeypatch):
+    seen = {}
+
+    def respond(request):
+        assert str(request.url) == 'http://100.69.120.65:8188/v1/images/edits'
+        seen.update(_form_fields(request.content, request.headers['content-type']))
+        return httpx.Response(200, json={'data': [{'b64_json': png(Image.new('RGB', (768, 576), 'blue'))}]})
+
+    out = _self_hosted_inpaint(monkeypatch, Image.new('RGB', (1600, 1200), 'red'),
+                               Image.new('L', (1600, 1200), 255),
+                               {'steps': 8}, respond)
+    # Working size is capped to a model-friendly size (<=768 long side, /16).
+    assert seen['size'] == '768x576'
+    # A requested step budget passes through up to the cap (default 8).
+    assert seen['steps'] == '8'
+    # The returned image keeps the original dimensions.
+    assert Image.open(io.BytesIO(base64.b64decode(out['image']))).size == (1600, 1200)
+
+
+def test_self_hosted_inpaint_clamps_steps_to_the_cap(monkeypatch):
+    seen = {}
+
+    def respond(request):
+        seen.update(_form_fields(request.content, request.headers['content-type']))
+        return httpx.Response(200, json={'data': [{'b64_json': png(Image.new('RGB', (640, 480), 'blue'))}]})
+
+    _self_hosted_inpaint(monkeypatch, Image.new('RGB', (640, 480), 'red'),
+                         Image.new('L', (640, 480), 255), {'steps': 20}, respond)
+    # Over-cap requests are clamped to the configured maximum (default 8).
+    assert seen['steps'] == '8'
+
+
+def test_self_hosted_inpaint_leaves_small_images_unchanged(monkeypatch):
+    seen = {}
+
+    def respond(request):
+        seen.update(_form_fields(request.content, request.headers['content-type']))
+        return httpx.Response(200, json={'data': [{'b64_json': png(Image.new('RGB', (640, 480), 'green'))}]})
+
+    out = _self_hosted_inpaint(monkeypatch, Image.new('RGB', (640, 480), 'red'),
+                               Image.new('L', (640, 480), 255), {}, respond)
+    # Under the cap: dimensions pass through untouched; with no requested count
+    # sent the moderate default (4) is used.
+    assert seen['size'] == '640x480'
+    assert seen['steps'] == '4'
+    assert Image.open(io.BytesIO(base64.b64decode(out['image']))).size == (640, 480)
+
+
+def test_self_hosted_inpaint_without_mask_uses_a_full_white_mask(monkeypatch):
+    """A whole-image instruction edit may omit the mask; it must not raise
+    KeyError -> 400 (the health-audit regression)."""
+    seen = {}
+    mask_bytes = {}
+
+    def respond(request):
+        seen.update(_form_fields(request.content, request.headers['content-type']))
+        # The provider must receive a (full-white) mask, not a missing one.
+        import re as _re
+        parts = request.content.split(b'--')
+        for part in parts:
+            if b'name="mask"' in part:
+                head, _, body = part.partition(b'\r\n\r\n')
+                mask_bytes['png'] = body.rstrip(b'\r\n-')
+        return httpx.Response(200, json={'data': [{'b64_json': png(Image.new('RGB', (32, 32), 'blue'))}]})
+
+    out = _self_hosted_inpaint(monkeypatch, Image.new('RGB', (32, 32), 'red'),
+                               None, {}, respond, include_mask=False)
+    assert 'image' in out, out
+    assert seen.get('size') == '32x32'
+    # The synthesized mask is image-sized and all-white (whole image editable).
+    mask_img = Image.open(io.BytesIO(mask_bytes['png'])).convert('L')
+    assert mask_img.size == (32, 32)
+    assert mask_img.getextrema() == (255, 255)
+
+
+def test_openai_inpaint_without_mask_is_a_clean_400(monkeypatch):
+    """OpenAI edits need a mask; a missing one must be a clean 400, not a
+    KeyError traceback."""
+    from fastapi import HTTPException
+
+    endpoint = SimpleNamespace(base_url='https://api.openai.com/v1', api_key='sk-x', owner='alice')
+    monkeypatch.setattr(gallery, 'SessionLocal', lambda: SimpleNamespace(close=lambda: None))
+    monkeypatch.setattr(gallery, 'require_privilege', lambda *a: 'alice')
+    monkeypatch.setattr(gallery, '_visible_image_endpoint_for_base', lambda *a: endpoint)
+    monkeypatch.setattr('src.url_safety.check_outbound_url', lambda *a, **k: (True, ''))
+
+    class Request:
+        async def json(self):
+            return {'_endpoint': 'https://api.openai.com/v1',
+                    'image': png(Image.new('RGB', (32, 32), 'red')), 'prompt': 'x'}
+
+    route = next(r for r in gallery.setup_gallery_routes().routes if r.path == '/api/image/inpaint')
+    try:
+        asyncio.run(route.endpoint(Request()))
+        raise AssertionError('expected a 400 for a missing mask')
+    except HTTPException as exc:
+        assert exc.status_code == 400
+        assert 'mask' in str(exc.detail).lower()
+
+
+def test_self_hosted_inpaint_forwards_request_id(monkeypatch):
+    """A client-supplied request_id is forwarded to the provider so the client
+    can poll GET /api/image/edit-progress for step progress."""
+    seen = {}
+
+    def respond(request):
+        seen.update(_form_fields(request.content, request.headers.get('content-type', '')))
+        return httpx.Response(200, json={'model': 'qwen-image-edit-2511',
+                                         'data': [{'b64_json': png(Image.new('RGBA', (32, 32), 'red'))}]})
+
+    out = _self_hosted_inpaint(monkeypatch, Image.new('RGB', (32, 32), 'red'),
+                               Image.new('L', (32, 32), 255), {'request_id': 'job-777'}, respond)
+    assert 'image' in out, out
+    assert seen.get('request_id') == 'job-777'
diff --git a/tests/test_gallery_edit_progress.py b/tests/test_gallery_edit_progress.py
new file mode 100644
index 000000000..73987be7c
--- /dev/null
+++ b/tests/test_gallery_edit_progress.py
@@ -0,0 +1,120 @@
+"""Tests for the image-op progress contract (HARNESS-owned).
+
+The 7011 side accepts an optional client-supplied ``request_id`` on heavy image
+ops and exposes ``GET /api/image/edit-progress`` which proxies the provider's
+``/v1/images/progress/{request_id}`` route. When the provider has no such route
+the endpoint returns ``{"available": false}`` so the client keeps an
+indeterminate bar.
+"""
+import asyncio
+from types import SimpleNamespace
+
+import httpx
+
+import routes.gallery_routes as gallery
+
+
+def _route(path):
+    return next(r for r in gallery.setup_gallery_routes().routes if r.path == path)
+
+
+class _Req:
+    def __init__(self, query):
+        self.query_params = query
+
+
+def _fake_db():
+    class Db:
+        def close(self):
+            pass
+
+        def query(self, *args, **kwargs):
+            return self
+
+        def filter(self, *args, **kwargs):
+            return self
+
+        def first(self):
+            return None
+
+    return Db()
+
+
+def test_edit_progress_requires_request_id(monkeypatch):
+    monkeypatch.setattr(gallery, "require_privilege", lambda *a: "alice")
+    route = _route("/api/image/edit-progress")
+    try:
+        asyncio.run(route.endpoint(_Req({})))
+    except Exception as exc:  # FastAPI HTTPException
+        assert getattr(exc, "status_code", None) == 400
+    else:
+        raise AssertionError("expected a 400 for a missing request_id")
+
+
+def test_edit_progress_rejects_an_unsafe_request_id(monkeypatch):
+    monkeypatch.setattr(gallery, "require_privilege", lambda *a: "alice")
+    monkeypatch.setattr(gallery, "SessionLocal", lambda: _fake_db())
+    route = _route("/api/image/edit-progress")
+    try:
+        asyncio.run(route.endpoint(_Req({"request_id": "../secret"})))
+    except Exception as exc:
+        assert getattr(exc, "status_code", None) == 400
+    else:
+        raise AssertionError("expected a 400 for an unsafe request_id")
+
+
+def test_edit_progress_returns_provider_payload(monkeypatch):
+    endpoint = SimpleNamespace(base_url="http://100.69.120.65:8188/v1", api_key="k")
+    monkeypatch.setattr(gallery, "SessionLocal", lambda: _fake_db())
+    monkeypatch.setattr(gallery, "require_privilege", lambda *a: "alice")
+    monkeypatch.setattr(gallery, "_first_visible_image_endpoint", lambda *a: endpoint)
+    seen = {}
+
+    def respond(request):
+        seen["url"] = str(request.url)
+        # Live seneca contract stages: loading | editing | compositing | done | error.
+        return httpx.Response(
+            200,
+            json={"stage": "editing", "step": 3, "steps": 8, "eta_s": 42.0, "progress": 0.375},
+        )
+
+    client = httpx.AsyncClient
+    monkeypatch.setattr(httpx, "AsyncClient", lambda **k: client(transport=httpx.MockTransport(respond), **k))
+    out = asyncio.run(_route("/api/image/edit-progress").endpoint(_Req({"request_id": "abc-123"})))
+    assert out["available"] is True
+    assert out["stage"] == "editing"  # passed through unchanged
+    assert out["step"] == 3 and out["steps"] == 8
+    assert seen["url"].endswith("/images/progress/abc-123")
+
+
+def test_edit_progress_available_false_when_provider_has_no_route(monkeypatch):
+    endpoint = SimpleNamespace(base_url="http://100.69.120.65:8188/v1", api_key="k")
+    monkeypatch.setattr(gallery, "SessionLocal", lambda: _fake_db())
+    monkeypatch.setattr(gallery, "require_privilege", lambda *a: "alice")
+    monkeypatch.setattr(gallery, "_first_visible_image_endpoint", lambda *a: endpoint)
+
+    client = httpx.AsyncClient
+    monkeypatch.setattr(
+        httpx, "AsyncClient",
+        lambda **k: client(transport=httpx.MockTransport(lambda req: httpx.Response(404)), **k),
+    )
+    out = asyncio.run(_route("/api/image/edit-progress").endpoint(_Req({"request_id": "abc"})))
+    assert out["available"] is False
+
+
+def test_edit_progress_available_false_when_unreachable(monkeypatch):
+    endpoint = SimpleNamespace(base_url="http://100.69.120.65:8188/v1", api_key="k")
+    monkeypatch.setattr(gallery, "SessionLocal", lambda: _fake_db())
+    monkeypatch.setattr(gallery, "require_privilege", lambda *a: "alice")
+    monkeypatch.setattr(gallery, "_first_visible_image_endpoint", lambda *a: endpoint)
+
+    class Boom:
+        async def __aenter__(self):
+            raise httpx.ConnectError("nope")
+
+        async def __aexit__(self, *a):
+            return False
+
+    monkeypatch.setattr(httpx, "AsyncClient", lambda **k: Boom())
+    out = asyncio.run(_route("/api/image/edit-progress").endpoint(_Req({"request_id": "abc"})))
+    assert out["available"] is False
diff --git a/tests/test_gallery_heavy_image_ops.py b/tests/test_gallery_heavy_image_ops.py
new file mode 100644
index 000000000..31b988603
--- /dev/null
+++ b/tests/test_gallery_heavy_image_ops.py
@@ -0,0 +1,201 @@
+"""Heavy in-process image ops must not load GB-scale models by default.
+
+remove-bg / SAM mask / Real-ESRGAN upscale+denoise used to load rembg / torch
+models inside the web process and OOM-killed the host. They now default to a
+graceful 503, proxy to the seneca remote ops service when
+``ODYSSEUS_IMAGE_OPS_BASE`` is set (translate to the /v1/images/* contract), and
+only run in-process when explicitly enabled via ODYSSEUS_ALLOW_LOCAL_IMAGE_MODELS.
+"""
+
+import asyncio
+
+import httpx
+import pytest
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+
+from routes.gallery import gallery_routes as gr
+
+
+HEAVY_ROUTES = [
+    ("/api/image/remove-bg", {"image": "x"}, "Background removal"),
+    ("/api/image/mask", {"image": "x"}, "Smart mask"),
+    ("/api/image/upscale-local", {"image": "x"}, "AI upscale"),
+    ("/api/image/denoise", {"image": "x"}, "AI denoise"),
+]
+
+
+@pytest.fixture(autouse=True)
+def _clean_env(monkeypatch):
+    monkeypatch.setattr(gr, "require_privilege", lambda *a, **k: None)
+    monkeypatch.delenv("ODYSSEUS_IMAGE_OPS_BASE", raising=False)
+    monkeypatch.delenv("ODYSSEUS_ALLOW_LOCAL_IMAGE_MODELS", raising=False)
+
+
+@pytest.fixture()
+def client():
+    app = FastAPI()
+    app.include_router(gr.setup_gallery_routes())
+    return TestClient(app)
+
+
+def test_local_image_models_disabled_by_default():
+    assert gr._local_image_models_enabled() is False
+
+
+@pytest.mark.parametrize("value", ["1", "true", "Yes", "ON"])
+def test_local_image_models_enabled_env(monkeypatch, value):
+    monkeypatch.setenv("ODYSSEUS_ALLOW_LOCAL_IMAGE_MODELS", value)
+    assert gr._local_image_models_enabled() is True
+
+
+@pytest.mark.parametrize("value", ["", "0", "no", "off", "maybe"])
+def test_local_image_models_disabled_env(monkeypatch, value):
+    monkeypatch.setenv("ODYSSEUS_ALLOW_LOCAL_IMAGE_MODELS", value)
+    assert gr._local_image_models_enabled() is False
+
+
+def test_rss_mb_is_positive():
+    assert gr._rss_mb() > 0
+
+
+def test_route_heavy_image_op_returns_none_when_enabled(monkeypatch):
+    monkeypatch.setenv("ODYSSEUS_ALLOW_LOCAL_IMAGE_MODELS", "1")
+    assert asyncio.run(gr._route_heavy_image_op("/api/image/denoise", {}, label="x")) is None
+
+
+@pytest.mark.parametrize("path,body,label", HEAVY_ROUTES)
+def test_heavy_ops_503_when_disabled(client, path, body, label):
+    resp = client.post(path, json=body)
+    assert resp.status_code == 503
+    detail = resp.json().get("detail", "")
+    assert "temporarily unavailable" in detail
+    assert label in detail
+
+
+def test_remove_bg_disabled_does_not_import_rembg(monkeypatch):
+    import sys
+
+    monkeypatch.setitem(sys.modules, "rembg", None)
+
+    app = FastAPI()
+    app.include_router(gr.setup_gallery_routes())
+    client = TestClient(app)
+    resp = client.post("/api/image/remove-bg", json={"image": "x"})
+    assert resp.status_code == 503
+
+
+class _FakeResponse:
+    def __init__(self, payload, status_code=200):
+        self._payload = payload
+        self.status_code = status_code
+
+    def json(self):
+        return self._payload
+
+
+class _FakeAsyncClient:
+    calls = []
+    response = _FakeResponse({})
+
+    def __init__(self, *args, **kwargs):
+        pass
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, *args):
+        return False
+
+    async def post(self, url, json=None, files=None, data=None):
+        _FakeAsyncClient.calls.append((url, {"json": json, "files": files, "data": data}))
+        return _FakeAsyncClient.response
+
+
+def _client():
+    app = FastAPI()
+    app.include_router(gr.setup_gallery_routes())
+    return TestClient(app)
+
+
+def test_remove_bg_proxies_to_remote_contract(monkeypatch):
+    monkeypatch.setenv("ODYSSEUS_IMAGE_OPS_BASE", "http://seneca.test:8188")
+    monkeypatch.setattr(httpx, "AsyncClient", _FakeAsyncClient)
+    _FakeAsyncClient.calls = []
+    _FakeAsyncClient.response = _FakeResponse(
+        {"data": [{"b64_json": "RB", "mask_b64": "M", "bbox": [0, 0, 1, 1]}], "model": "birefnet"}
+    )
+
+    resp = _client().post("/api/image/remove-bg", json={"image": "AAAA"})
+    assert resp.status_code == 200
+    assert resp.json()["image"] == "RB"
+    url, kw = _FakeAsyncClient.calls[-1]
+    assert url == "http://seneca.test:8188/v1/images/remove-background"
+    assert "image" in kw["files"]
+
+
+def test_mask_proxies_to_remote_contract(monkeypatch):
+    monkeypatch.setenv("ODYSSEUS_IMAGE_OPS_BASE", "http://seneca.test:8188")
+    monkeypatch.setattr(httpx, "AsyncClient", _FakeAsyncClient)
+    _FakeAsyncClient.calls = []
+    _FakeAsyncClient.response = _FakeResponse(
+        {"masks": [{"b64_json": "MASK", "bbox": [10, 20, 30, 40], "score": 0.9, "label": "person"}],
+         "model": "sam+grounding"}
+    )
+
+    resp = _client().post("/api/image/mask", json={"image": "AAAA", "text": "person"})
+    assert resp.status_code == 200
+    body = resp.json()
+    assert body["mask"] == "MASK"
+    # remote [x,y,w,h] -> app [x1,y1,x2,y2]
+    assert body["bbox"] == [10, 20, 40, 60]
+    url, kw = _FakeAsyncClient.calls[-1]
+    assert url == "http://seneca.test:8188/v1/images/mask"
+    assert kw["data"]["prompt"] == "person"
+
+
+def test_mask_picks_top_score_not_first(monkeypatch):
+    monkeypatch.setenv("ODYSSEUS_IMAGE_OPS_BASE", "http://seneca.test:8188")
+    monkeypatch.setattr(httpx, "AsyncClient", _FakeAsyncClient)
+    _FakeAsyncClient.response = _FakeResponse(
+        {"masks": [
+            {"b64_json": "LOW", "bbox": [0, 0, 1, 1], "score": 0.2},
+            {"b64_json": "HIGH", "bbox": [0, 0, 2, 2], "score": 0.95},
+            {"b64_json": "MID", "bbox": [0, 0, 3, 3], "score": 0.5},
+        ], "model": "sam+grounding"}
+    )
+    resp = _client().post("/api/image/mask", json={"image": "AAAA", "text": "person"})
+    assert resp.status_code == 200
+    assert resp.json()["mask"] == "HIGH"
+
+
+def test_mask_box_is_sent_as_xywh(monkeypatch):
+    monkeypatch.setenv("ODYSSEUS_IMAGE_OPS_BASE", "http://seneca.test:8188")
+    monkeypatch.setattr(httpx, "AsyncClient", _FakeAsyncClient)
+    _FakeAsyncClient.calls = []
+    _FakeAsyncClient.response = _FakeResponse({"masks": [{"b64_json": "M", "bbox": [0, 0, 1, 1], "score": 1.0}]})
+    resp = _client().post("/api/image/mask", json={"image": "AAAA", "box": [10, 20, 40, 60]})
+    assert resp.status_code == 200
+    _, kw = _FakeAsyncClient.calls[-1]
+    assert kw["data"]["box"] == "10,20,30,40"
+
+
+def test_mask_remote_empty_masks_is_200_nothing_selected(monkeypatch):
+    monkeypatch.setenv("ODYSSEUS_IMAGE_OPS_BASE", "http://seneca.test:8188")
+    monkeypatch.setattr(httpx, "AsyncClient", _FakeAsyncClient)
+    _FakeAsyncClient.response = _FakeResponse({"masks": [], "model": "sam+grounding"})
+    resp = _client().post("/api/image/mask", json={"image": "AAAA", "text": "person"})
+    assert resp.status_code == 200
+    body = resp.json()
+    assert body["mask"] is None
+    assert body["masks"] == []
+    assert "Nothing selected" in body["error"]
+
+
+def test_remote_proxy_surfaces_error_status(monkeypatch):
+    monkeypatch.setenv("ODYSSEUS_IMAGE_OPS_BASE", "http://seneca.test:8188")
+    monkeypatch.setattr(httpx, "AsyncClient", _FakeAsyncClient)
+    _FakeAsyncClient.response = _FakeResponse({}, status_code=500)
+    resp = _client().post("/api/image/remove-bg", json={"image": "AAAA"})
+    assert resp.status_code == 503
+    assert "temporarily unavailable" in resp.json().get("detail", "")
diff --git a/tests/test_gallery_image_endpoint_fallback.py b/tests/test_gallery_image_endpoint_fallback.py
new file mode 100644
index 000000000..f2befa58b
--- /dev/null
+++ b/tests/test_gallery_image_endpoint_fallback.py
@@ -0,0 +1,124 @@
+"""Image endpoint fallback: image models on mixed (non image-only) endpoints.
+
+Chat image generation resolves its model by name across every enabled endpoint,
+so a ``qwen-image-edit`` / ``gpt-image-1`` model registered on a shared
+OpenAI-compatible gateway works there. The editor's generative ops used a
+stricter image-only lookup and reported "No image generation endpoint
+configured" on those same setups. These tests pin the fallback that makes the
+editor find the same endpoint.
+"""
+
+from types import SimpleNamespace
+
+import routes.gallery_routes as gallery_routes
+
+
+class _Predicate:
+    def __init__(self, check):
+        self._check = check
+
+    def __call__(self, row):
+        return self._check(row)
+
+    def __or__(self, other):
+        return _Predicate(lambda row: self(row) or other(row))
+
+
+class _Column:
+    def __init__(self, name):
+        self.name = name
+
+    def __eq__(self, value):
+        return _Predicate(lambda row: getattr(row, self.name) == value)
+
+
+class _ModelEndpoint:
+    base_url = _Column("base_url")
+    model_type = _Column("model_type")
+    is_enabled = _Column("is_enabled")
+    owner = _Column("owner")
+
+
+class _Query:
+    def __init__(self, rows):
+        self._rows = list(rows)
+
+    def filter(self, *predicates):
+        self._rows = [row for row in self._rows if all(pred(row) for pred in predicates)]
+        return self
+
+    def all(self):
+        return list(self._rows)
+
+
+class _DB:
+    def __init__(self, rows):
+        self._rows = rows
+
+    def query(self, model):
+        assert model is _ModelEndpoint
+        return _Query(self._rows)
+
+
+def _ep(base_url, owner=None, *, enabled=True, model_type="chat", models=None):
+    return SimpleNamespace(
+        base_url=base_url,
+        owner=owner,
+        is_enabled=enabled,
+        model_type=model_type,
+        api_key="sk-secret",
+        cached_models=models or [],
+        pinned_models=[],
+    )
+
+
+def _patch_model(monkeypatch):
+    monkeypatch.setattr(gallery_routes, "ModelEndpoint", _ModelEndpoint)
+
+
+def test_mixed_endpoint_with_image_model_is_found(monkeypatch):
+    _patch_model(monkeypatch)
+    rows = [_ep("https://gateway.example.com/v1", models=["qwen-image-edit", "llama-3"])]
+
+    ep = gallery_routes._first_visible_image_endpoint(_DB(rows), None)
+
+    assert ep is not None
+    assert ep.base_url == "https://gateway.example.com/v1"
+
+
+def test_mixed_endpoint_without_image_model_is_ignored(monkeypatch):
+    _patch_model(monkeypatch)
+    rows = [_ep("https://gateway.example.com/v1", models=["llama-3", "mistral"])]
+
+    assert gallery_routes._first_visible_image_endpoint(_DB(rows), None) is None
+
+
+def test_image_only_endpoint_wins_over_mixed(monkeypatch):
+    _patch_model(monkeypatch)
+    rows = [
+        _ep("https://gateway.example.com/v1", models=["gpt-image-1"]),
+        _ep("https://images.example.com/v1", model_type="image"),
+    ]
+
+    ep = gallery_routes._first_visible_image_endpoint(_DB(rows), None)
+
+    assert ep is not None
+    assert ep.model_type == "image"
+
+
+def test_unreachable_endpoint_reports_502():
+    """The inpaint proxy must distinguish an unreachable endpoint from a provider error.
+
+    502 (gateway) is reserved for "the image server could not be reached"; 503 is
+    reserved for "generation is switched off on the server", which the editor maps
+    to its own fixed message.
+    """
+    from pathlib import Path
+
+    src = (
+        Path(__file__).resolve().parents[1] / "routes" / "gallery" / "gallery_routes.py"
+    ).read_text()
+    assert "Image server unreachable" in src
+    assert "except httpx.TransportError as exc:" in src
+    assert "provider HTTP" in src
+    assert 'raise HTTPException(503, f"Image endpoint unreachable' not in src
diff --git a/tests/test_gallery_image_model_picker.py b/tests/test_gallery_image_model_picker.py
new file mode 100644
index 000000000..c0d038129
--- /dev/null
+++ b/tests/test_gallery_image_model_picker.py
@@ -0,0 +1,27 @@
+"""Source checks for the gallery Settings-tab image-model picker.
+
+The Quick Edit model picker lives in the editor; HARNESS mirrors it into the
+gallery Settings tab, fed by GET /api/editor/image-models and sharing the
+same localStorage key (`ge-ai-command-model`) so the two stay in sync.
+"""
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+GALLERY_JS = (ROOT / "static/js/gallery.js").read_text(encoding="utf-8")
+
+
+def test_settings_tab_has_image_model_picker():
+    assert 'id="gallery-image-model"' in GALLERY_JS
+    assert "/api/editor/image-models" in GALLERY_JS
+    assert "ge-ai-command-model" in GALLERY_JS
+
+
+def test_image_model_picker_lives_in_the_settings_container():
+    settings_idx = GALLERY_JS.index('id="gallery-settings-container"')
+    picker_idx = GALLERY_JS.index('id="gallery-image-model"')
+    assert picker_idx > settings_idx
+
+
+def test_picker_persists_with_the_shared_localstorage_key():
+    assert "localStorage.setItem(_GE_MODEL_KEY" in GALLERY_JS
+    assert "localStorage.getItem(_GE_MODEL_KEY)" in GALLERY_JS
diff --git a/tests/test_gallery_landing_import_button.py b/tests/test_gallery_landing_import_button.py
new file mode 100644
index 000000000..f9bfac9d6
--- /dev/null
+++ b/tests/test_gallery_landing_import_button.py
@@ -0,0 +1,25 @@
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[1]
+GALLERY = ROOT / "static/js/gallery.js"
+
+
+def test_editor_landing_has_an_import_button_next_to_new_canvas():
+    """The editor landing must offer a direct "Import" action.
+
+    It sits in the same action row as "New canvas..." / "Browse gallery" and,
+    on file pick, opens the editor on the chosen raster image (``openEditor``
+    takes an image data URL as its first argument).
+    """
+    src = GALLERY.read_text(encoding="utf-8")
+    assert 'id="gallery-editor-import"' in src, "landing Import button missing"
+    # Button order: New canvas → Import → Browse gallery.
+    new_at = src.index('id="gallery-editor-new"')
+    import_at = src.index('id="gallery-editor-import"')
+    pick_at = src.index('id="gallery-editor-pick"')
+    assert new_at < import_at < pick_at, "Import must sit next to New canvas"
+    # Wiring opens the editor on the selected file's data URL.
+    assert "getElementById('gallery-editor-import')?.addEventListener('click'" in src
+    assert "readAsDataURL(file)" in src
+    assert "await openEditor(reader.result, null, null, name)" in src
diff --git a/tests/test_gallery_seneca_image_ops.py b/tests/test_gallery_seneca_image_ops.py
new file mode 100644
index 000000000..ae1759a08
--- /dev/null
+++ b/tests/test_gallery_seneca_image_ops.py
@@ -0,0 +1,187 @@
+"""Tests for the seneca single-image op proxies (HARNESS-owned).
+
+POST /api/image/replace-background -> provider /v1/images/replace-background
+POST /api/image/outpaint           -> provider /v1/images/outpaint (alias /extend)
+
+Both forward a client-supplied JPEG/PNG as multipart with the prompt/params plus
+``request_id`` (so GET /api/image/edit-progress lights the progress bar) and
+return the provider image as ``{image}``.
+"""
+import asyncio
+import base64
+from types import SimpleNamespace
+
+import httpx
+
+import routes.gallery_routes as gallery
+
+_IMG_B64 = base64.b64encode(b"abc-not-a-real-png").decode()
+
+
+def _route(path):
+    return next(r for r in gallery.setup_gallery_routes().routes if r.path == path)
+
+
+class _Req:
+    def __init__(self, body):
+        self._body = body
+
+    async def json(self):
+        return self._body
+
+
+def _fake_db():
+    class Db:
+        def close(self):
+            pass
+
+        def query(self, *args, **kwargs):
+            return self
+
+        def filter(self, *args, **kwargs):
+            return self
+
+        def first(self):
+            return None
+
+    return Db()
+
+
+def _setup(monkeypatch, respond):
+    endpoint = SimpleNamespace(base_url="http://100.69.120.65:8188/v1", api_key="k")
+    monkeypatch.setattr(gallery, "SessionLocal", lambda: _fake_db())
+    monkeypatch.setattr(gallery, "require_privilege", lambda *a: "alice")
+    monkeypatch.setattr(gallery, "_first_visible_image_endpoint", lambda *a: endpoint)
+    seen = {}
+
+    def _respond(request):
+        seen["url"] = str(request.url)
+        seen["body"] = bytes(request.content)
+        return respond(request)
+
+    client = httpx.AsyncClient
+    monkeypatch.setattr(
+        httpx, "AsyncClient",
+        lambda **k: client(transport=httpx.MockTransport(_respond), **k),
+    )
+    return seen
+
+
+def _ok(_req):
+    return httpx.Response(200, json={"data": [{"b64_json": "AAAA"}]})
+
+
+def test_replace_background_forwards_multipart_and_returns_image(monkeypatch):
+    seen = _setup(monkeypatch, _ok)
+    out = asyncio.run(_route("/api/image/replace-background").endpoint(_Req({
+        "image": _IMG_B64, "prompt": "put her on a beach", "steps": 8,
+        "harmonise": True, "shadow": False, "request_id": "rb-123",
+    })))
+    assert out["image"] == "AAAA"
+    assert seen["url"].endswith("/images/replace-background")
+    body = seen["body"]
+    assert b"put her on a beach" in body
+    assert b"rb-123" in body            # request_id forwarded for progress
+    assert b"harmonise" in body and b"shadow" in body
+    assert b"8" in body                  # steps
+
+
+def test_outpaint_forwards_ratio_size_context_and_returns_image(monkeypatch):
+    seen = _setup(monkeypatch, _ok)
+    out = asyncio.run(_route("/api/image/outpaint").endpoint(_Req({
+        "image": _IMG_B64, "prompt": "extend the sky", "ratio": "16:9",
+        "size": "1920x1080", "steps": 4, "context": "calm blue sky",
+        "request_id": "op-9",
+    })))
+    assert out["image"] == "AAAA"
+    assert seen["url"].endswith("/images/outpaint")
+    body = seen["body"]
+    for token in (b"16:9", b"1920x1080", b"calm blue sky", b"op-9"):
+        assert token in body, token
+
+
+def test_outpaint_extend_alias_uses_the_same_provider_route(monkeypatch):
+    seen = _setup(monkeypatch, _ok)
+    out = asyncio.run(_route("/api/image/extend").endpoint(_Req({
+        "image": _IMG_B64, "prompt": "extend", "ratio": "9:16",
+    })))
+    assert out["image"] == "AAAA"
+    assert seen["url"].endswith("/images/outpaint")
+
+
+def test_outpaint_reads_openai_style_url_result(monkeypatch):
+    def _respond(_req):
+        return httpx.Response(200, json={"data": [{"url": "http://100.69.120.65:8188/v1/images/x.png"}]})
+
+    _setup(monkeypatch, _respond)
+    monkeypatch.setattr(gallery, "_fetch_result_image_b64", lambda url: _async_return("ZZZZ"))
+    out = asyncio.run(_route("/api/image/outpaint").endpoint(_Req({"image": _IMG_B64, "prompt": "x"})))
+    assert out["image"] == "ZZZZ"
+
+
+def test_replace_background_502_when_provider_returns_no_image(monkeypatch):
+    _setup(monkeypatch, lambda _req: httpx.Response(200, json={"data": []}))
+    try:
+        asyncio.run(_route("/api/image/replace-background").endpoint(_Req({"image": _IMG_B64})))
+    except Exception as exc:
+        assert getattr(exc, "status_code", None) == 502
+    else:
+        raise AssertionError("expected a 502 when the provider returns no image")
+
+
+async def _async_return(value):
+    return value
+
+
+def _capture_forward(monkeypatch):
+    """Replace _forward_seneca_image_op with a fake that records kwargs."""
+    captured = {}
+
+    async def _fake_forward(base, api_key, provider_path, image_bytes, fields, *, label, timeout=300.0):
+        captured["label"] = label
+        captured["provider_path"] = provider_path
+        captured["timeout"] = timeout
+        return {"image": "AAAA"}
+
+    monkeypatch.setattr(gallery, "_forward_seneca_image_op", _fake_forward)
+    monkeypatch.setattr(gallery, "SessionLocal", lambda: _fake_db())
+    monkeypatch.setattr(gallery, "require_privilege", lambda *a: "alice")
+    monkeypatch.setattr(
+        gallery, "_first_visible_image_endpoint",
+        lambda *a: SimpleNamespace(base_url="http://100.69.120.65:8188/v1", api_key="k"),
+    )
+    return captured
+
+
+def test_outpaint_proxy_uses_a_long_timeout(monkeypatch):
+    captured = _capture_forward(monkeypatch)
+    out = asyncio.run(_route("/api/image/outpaint").endpoint(_Req({"image": _IMG_B64, "prompt": "extend to 9:16"})))
+    assert out["image"] == "AAAA"
+    assert captured["provider_path"] == "/images/outpaint"
+    assert captured["timeout"] >= 900, captured
+
+
+def test_outpaint_extend_alias_also_uses_the_long_timeout(monkeypatch):
+    captured = _capture_forward(monkeypatch)
+    asyncio.run(_route("/api/image/extend").endpoint(_Req({"image": _IMG_B64, "prompt": "extend"})))
+    assert captured["timeout"] >= 900, captured
+
+
+def test_replace_background_keeps_the_short_default_timeout(monkeypatch):
+    captured = _capture_forward(monkeypatch)
+    asyncio.run(_route("/api/image/replace-background").endpoint(_Req({"image": _IMG_B64, "prompt": "beach"})))
+    assert captured["timeout"] == 300.0, captured
+
+
+def test_outpaint_timeout_env_override(monkeypatch):
+    monkeypatch.setenv("ODYSSEUS_IMAGE_OUTPAINT_TIMEOUT", "720")
+    assert gallery._outpaint_timeout() == 720.0
+    monkeypatch.delenv("ODYSSEUS_IMAGE_OUTPAINT_TIMEOUT", raising=False)
+    assert gallery._outpaint_timeout() == 900.0
+
+
+def test_graceful_shutdown_window_covers_a_long_outpaint():
+    from pathlib import Path
+
+    src = (Path(__file__).resolve().parent.parent / "app.py").read_text()
+    assert '"ODYSSEUS_GRACEFUL_SHUTDOWN_TIMEOUT", "900"' in src
diff --git a/tests/test_hwfit_gemma4_12b.py b/tests/test_hwfit_gemma4_12b.py
index a4a0ff894..33686e61f 100644
--- a/tests/test_hwfit_gemma4_12b.py
+++ b/tests/test_hwfit_gemma4_12b.py
@@ -1,11 +1,5 @@
-import pytest
-
 from services.hwfit.fit import rank_models
 from services.hwfit.models import get_models, is_prequantized
-from tests.hwfit_publication_fixtures import publication_catalog  # noqa: F401
-
-# Rank authored inputs rather than publication catalog snapshots.
-pytestmark = pytest.mark.usefixtures("publication_catalog")
 
 
 def _8gb_vram_system():
@@ -20,63 +14,38 @@ def _8gb_vram_system():
     }
 
 
-GEMMA = "google/gemma-4-12B-it"
+def test_gemma4_12b_in_catalog():
+    catalog = {m["name"]: m for m in get_models()}
+    assert "google/gemma-4-12B-it" in catalog, "gemma-4-12B-it missing from catalog"
 
 
-def _input_row(rows, name):
-    return next(r for r in rows if r["name"] == name)
-
-
-def _qat_rows(rows):
-    return [r for r in rows if r["name"].startswith(GEMMA + "-qat-")]
-
-
-def test_gemma4_12b_user_catalog_row_wins_the_merge(publication_catalog, monkeypatch):
-    """A dynamic cache listing the same repo must not replace or duplicate the
-    user-catalog row; rows only the cache knows are still merged in."""
-    from services.hwfit import hf_discovery
-
-    monkeypatch.setattr(hf_discovery, "load_cached_hf_collection_models", lambda: [
-        {"name": GEMMA, "quantization": "F16", "gguf_sources": [{"repo": "test/cache-GGUF", "file": "cache.gguf"}]},
-        {"name": "test/cache-only", "quantization": "F16", "gguf_sources": []},
-    ])
-    merged = get_models()
-    names = [m["name"] for m in merged]
-
-    assert names.count(GEMMA) == 1
-    assert "test/cache-only" in names
-    entry = next(m for m in merged if m["name"] == GEMMA)
-    assert entry["gguf_sources"] == _input_row(publication_catalog, GEMMA)["gguf_sources"]
-
-
-def test_gemma4_12b_ranked_row_carries_its_gguf_source(publication_catalog):
-    hit = next(r for r in rank_models(_8gb_vram_system(), search="gemma-4-12B-it", limit=20) if r["name"] == GEMMA)
-    assert hit["gguf_sources"] == _input_row(publication_catalog, GEMMA)["gguf_sources"]
-    # The F16 input does not fit 8 GB, so the fit falls back to a GGUF quant.
-    assert hit["quant"] == "Q4_K_M"
+def test_gemma4_12b_has_gguf_source():
+    catalog = {m["name"]: m for m in get_models()}
+    entry = catalog["google/gemma-4-12B-it"]
+    assert entry.get("gguf_sources"), "gemma-4-12B-it has no gguf_sources"
+    repos = [s["repo"] for s in entry["gguf_sources"]]
+    assert "unsloth/gemma-4-12B-it-GGUF" in repos
 
 
 def test_gemma4_12b_rank_models_returns_it_for_8gb_vram():
     results = rank_models(_8gb_vram_system(), search="gemma-4-12B-it", limit=20)
     names = [r["name"] for r in results]
-    assert GEMMA in names, "rank_models did not return gemma-4-12B-it for 8 GB VRAM"
+    assert "google/gemma-4-12B-it" in names, "rank_models did not return gemma-4-12B-it for 8 GB VRAM"
 
 
-def test_gemma4_12b_qat_entries_rank_with_their_native_quant(publication_catalog):
-    qat = _qat_rows(publication_catalog)
-    assert len(qat) == 2
-    ranked = {r["name"]: r for r in rank_models(_8gb_vram_system(), search="gemma-4-12B-it-qat", limit=20)}
-    for row in qat:
-        assert ranked[row["name"]]["quant"] == row["quantization"]
-
-
-def test_gemma4_12b_qat_entries_are_prequantized(publication_catalog):
+def test_gemma4_12b_qat_entries_in_catalog():
     catalog = {m["name"]: m for m in get_models()}
-    for row in _qat_rows(publication_catalog):
-        assert is_prequantized(catalog[row["name"]])
+    assert "google/gemma-4-12B-it-qat-int4" in catalog
+    assert "google/gemma-4-12B-it-qat-int8" in catalog
 
 
-def test_gemma4_12b_qat_entries_have_no_gguf(publication_catalog):
-    ranked = {r["name"]: r for r in rank_models(_8gb_vram_system(), search="gemma-4-12B-it-qat", limit=20)}
-    for row in _qat_rows(publication_catalog):
-        assert ranked[row["name"]]["gguf_sources"] == []
+def test_gemma4_12b_qat_entries_are_prequantized():
+    catalog = {m["name"]: m for m in get_models()}
+    assert is_prequantized(catalog["google/gemma-4-12B-it-qat-int4"])
+    assert is_prequantized(catalog["google/gemma-4-12B-it-qat-int8"])
+
+
+def test_gemma4_12b_qat_entries_have_no_gguf():
+    catalog = {m["name"]: m for m in get_models()}
+    assert catalog["google/gemma-4-12B-it-qat-int4"]["gguf_sources"] == []
+    assert catalog["google/gemma-4-12B-it-qat-int8"]["gguf_sources"] == []
diff --git a/tests/test_hwfit_gpu_count_nonnumeric.py b/tests/test_hwfit_gpu_count_nonnumeric.py
index f55cd4374..13e6b2f25 100644
--- a/tests/test_hwfit_gpu_count_nonnumeric.py
+++ b/tests/test_hwfit_gpu_count_nonnumeric.py
@@ -3,33 +3,8 @@
 The handler did `n = int(gpu_count)` with no guard, so `?gpu_count=abc` (or any
 non-integer) raised ValueError -> HTTP 500. A malformed count is now ignored,
 matching how the neighbouring gpu_group param is already parsed.
-
-The count parsing runs only after the empty-catalog early return, so these
-tests rank the authored publication catalog against a fixed two-GPU system and
-spy on rank_models to prove the parsing path actually ran.
 """
-import functools
-from copy import deepcopy
-
-import pytest
-
 from routes.hwfit_routes import setup_hwfit_routes
-from tests.hwfit_publication_fixtures import publication_catalog  # noqa: F401
-
-SYSTEM = {
-    "has_gpu": True,
-    "backend": "cuda",
-    "gpu_name": "Synthetic GPU",
-    "gpu_vram_gb": 24.0,
-    "gpu_count": 2,
-    "gpus": [
-        {"index": 0, "name": "Synthetic GPU", "vram_gb": 12.0},
-        {"index": 1, "name": "Synthetic GPU", "vram_gb": 12.0},
-    ],
-    "gpu_groups": [{"name": "Synthetic GPU", "vram_each": 12.0, "count": 2, "indices": [0, 1], "vram_total": 24.0}],
-    "available_ram_gb": 32.0,
-    "total_ram_gb": 32.0,
-}
 
 
 def _get_models():
@@ -40,80 +15,24 @@ def _get_models():
     raise AssertionError("hwfit /models route not found")
 
 
-@pytest.fixture
-def ranked_systems(publication_catalog, monkeypatch):
-    """Fix detection and record every system the handler hands to rank_models."""
-    from services.hwfit import fit, hardware
-
-    monkeypatch.setattr(hardware, "detect_system", lambda **_: deepcopy(SYSTEM))
-    calls = []
-    real_rank = fit.rank_models
-
-    @functools.wraps(real_rank)
-    def spy(system, **kwargs):
-        calls.append(deepcopy(system))
-        return real_rank(system, **kwargs)
-
-    monkeypatch.setattr(fit, "rank_models", spy)
-    return calls
-
-
-def _assert_ranked(result, ranked_systems):
-    assert isinstance(result, dict)
-    assert "error" not in result
-    assert isinstance(result["models"], list) and result["models"]
-    # Reaching rank_models means the empty-catalog return was not taken and the
-    # manual-hardware and gpu_count parsing ran first.
-    assert len(ranked_systems) == 1
-    assert ranked_systems[0] == result["system"]
-    return result["system"]
-
-
-def test_non_numeric_gpu_count_does_not_raise(ranked_systems):
+def test_non_numeric_gpu_count_does_not_raise():
     handler = _get_models()
     # Previously raised ValueError (HTTP 500); now degrades to a normal ranking.
-    system = _assert_ranked(handler(gpu_count="abc"), ranked_systems)
-    # Ignored like an omitted count: the auto pool keeps both GPUs and no
-    # explicit-count GPU-only pin is applied.
-    assert system["detected_gpu_count"] == 2
-    assert system["active_group"]["use_count"] == 2
-    assert system["gpu_count"] == 2
-    assert "gpu_only" not in system
+    result = handler(gpu_count="abc")
+    assert isinstance(result, dict)
 
 
-def test_numeric_gpu_count_still_accepted(ranked_systems):
+def test_numeric_gpu_count_still_accepted():
     handler = _get_models()
-    system = _assert_ranked(handler(gpu_count="0"), ranked_systems)
-    # 0 switches to RAM-only ranking.
-    assert system["detected_gpu_count"] == 2
-    assert system["has_gpu"] is False
-    assert system["gpu_count"] == 0
-    assert system["gpu_only"] is False
-    assert "active_group" not in system
+    result = handler(gpu_count="0")
+    assert isinstance(result, dict)
 
 
-def test_non_numeric_manual_gpu_count_does_not_raise(ranked_systems):
+def test_non_numeric_manual_gpu_count_does_not_raise():
     # manual_gpu_count is the other count param on this endpoint (the hardware
     # simulator in _apply_manual_hardware). A non-numeric value must also degrade
     # (default to 1) rather than 500, so the endpoint's count parsing is fully
     # covered.
     handler = _get_models()
-    system = _assert_ranked(handler(manual_mode="gpu", manual_gpu_count="abc"), ranked_systems)
-    assert system["manual_hardware"] is True
-    assert system["gpu_name"] == "Simulated CUDA GPU"
-    assert system["gpu_count"] == 1
-    assert system["gpu_groups"][0]["count"] == 1
-    assert system["detected_gpu_count"] == 1
-
-
-def test_empty_catalog_returns_before_count_parsing(ranked_systems, monkeypatch):
-    # Control: without catalog rows the handler stops before the parsing above,
-    # which is why the tests in this module must rank the authored catalog.
-    from services.hwfit import models
-
-    monkeypatch.setattr(models, "get_models", lambda: [])
-    result = _get_models()(gpu_count="abc", manual_mode="gpu", manual_gpu_count="abc")
-    assert result["models"] == []
-    assert "Model catalog is empty" in result["error"]
-    assert ranked_systems == []
-    assert "detected_gpu_count" not in result["system"]
+    result = handler(manual_mode="gpu", manual_gpu_count="abc")
+    assert isinstance(result, dict)
diff --git a/tests/test_hwfit_macos.py b/tests/test_hwfit_macos.py
index 2c9d89078..18487bf69 100644
--- a/tests/test_hwfit_macos.py
+++ b/tests/test_hwfit_macos.py
@@ -6,15 +6,9 @@ guarantee that non-macOS (Linux/Windows) detection is unchanged.
 
 import json
 
-import pytest
-
 from services.hwfit import hardware
 from services.hwfit.fit import rank_models
 from services.hwfit.models import get_models
-from tests.hwfit_publication_fixtures import publication_catalog  # noqa: F401
-
-# Rank authored inputs rather than publication catalog snapshots.
-pytestmark = pytest.mark.usefixtures("publication_catalog")
 
 
 def _metal_system(ram_gb=16.0, vram_gb=10.7):
@@ -84,20 +78,19 @@ def test_only_gguf_or_mlx_models_recommended_on_metal():
     assert unservable == [], f"{len(unservable)} non-servable models on Metal, e.g. {unservable[:3]}"
 
 
-def test_qwen_gguf_rows_rank_with_their_gguf_downloads_on_metal(publication_catalog):
-    """Qwen GGUF-looking Cookbook rows must download the GGUF repo/file their
-    catalog row names, not the base safetensors repository."""
+def test_qwen_catalog_entries_point_at_verified_gguf_repos():
+    """Qwen GGUF-looking Cookbook rows must download GGUF repos, not the base
+    safetensors repositories."""
+    catalog = {m["name"]: m for m in get_models()}
     expected = {
-        r["name"]: r["gguf_sources"]
-        for r in publication_catalog
-        if r["name"].startswith("Qwen/Qwen3.") and r["gguf_sources"]
+        "Qwen/Qwen3.5-9B": ("unsloth/Qwen3.5-9B-GGUF", "Qwen3.5-9B-Q4_K_M.gguf"),
+        "Qwen/Qwen3.6-27B": ("unsloth/Qwen3.6-27B-GGUF", "Qwen3.6-27B-Q4_K_M.gguf"),
+        "Qwen/Qwen3.6-35B-A3B": ("unsloth/Qwen3.6-35B-A3B-GGUF", "Qwen3.6-35B-A3B-UD-Q4_K_M.gguf"),
     }
-    assert len(expected) == 3
-    ranked = {r["name"]: r for r in rank_models(_metal_system(), search="Qwen/Qwen3.", limit=50)}
 
-    for model_name, sources in expected.items():
-        assert ranked[model_name]["gguf_sources"] == sources
-        assert all(src["repo"] != model_name and src["file"].endswith(".gguf") for src in ranked[model_name]["gguf_sources"])
+    for model_name, (repo, filename) in expected.items():
+        sources = catalog[model_name].get("gguf_sources") or []
+        assert any(src.get("repo") == repo and src.get("file") == filename for src in sources)
 
 
 def test_safetensors_models_still_recommended_on_cuda():
diff --git a/tests/test_hwfit_quant_formats.py b/tests/test_hwfit_quant_formats.py
index 411a15274..20e97434b 100644
--- a/tests/test_hwfit_quant_formats.py
+++ b/tests/test_hwfit_quant_formats.py
@@ -1,15 +1,9 @@
-import pytest
-
 from services.hwfit.fit import analyze_model, rank_models
 from services.hwfit.models import (
     get_models,
     infer_quantization_from_name,
     is_prequantized,
 )
-from tests.hwfit_publication_fixtures import publication_catalog  # noqa: F401
-
-# Rank authored inputs rather than publication catalog snapshots.
-pytestmark = pytest.mark.usefixtures("publication_catalog")
 
 
 def _dual_5060ti_system():
@@ -41,7 +35,7 @@ def test_infers_native_hf_quant_formats_from_repo_names():
 
 def test_nvfp4_catalog_quant_is_preserved():
     catalog = {m["name"]: m for m in get_models()}
-    model = catalog["test/native-NVFP4"]
+    model = catalog["txn545/Qwen3.5-122B-A10B-NVFP4"]
 
     assert model["quantization"] == "NVFP4"
     assert is_prequantized(model)
@@ -49,7 +43,7 @@ def test_nvfp4_catalog_quant_is_preserved():
 
 def test_nvfp4_search_result_is_not_gguf_or_cpu_offload():
     catalog = {m["name"]: m for m in get_models()}
-    model = catalog["test/native-NVFP4"]
+    model = catalog["txn545/Qwen3.5-122B-A10B-NVFP4"]
 
     fit = analyze_model(model, _dual_5060ti_system())
     assert fit["quant"] == "NVFP4"
@@ -57,10 +51,10 @@ def test_nvfp4_search_result_is_not_gguf_or_cpu_offload():
 
     results = rank_models(
         _dual_5060ti_system(),
-        search="native-NVFP4",
+        search="Qwen3.5-122B-A10B-NVFP4",
         limit=10,
     )
-    hit = next(r for r in results if r["name"] == "test/native-NVFP4")
+    hit = next(r for r in results if r["name"] == "txn545/Qwen3.5-122B-A10B-NVFP4")
     assert hit["quant"] == "NVFP4"
     assert hit["run_mode"] != "cpu_offload"
 
diff --git a/tests/test_image_creation_routing.py b/tests/test_image_creation_routing.py
index a571e960b..a0417a9de 100644
--- a/tests/test_image_creation_routing.py
+++ b/tests/test_image_creation_routing.py
@@ -120,8 +120,9 @@ def test_disabled_generation_is_not_restored():
 
 
 @pytest.mark.asyncio
+@pytest.mark.parametrize('incognito', [False, True])
 @pytest.mark.parametrize('exit_code', [None, 0])
-async def test_generation_dispatch_uses_owner_aware_backend(monkeypatch, exit_code):
+async def test_generation_dispatch_uses_owner_aware_backend(monkeypatch, exit_code, incognito):
     from types import SimpleNamespace
     from src import ai_interaction, tool_execution
     from src.agent_runtime.journal import ActionJournal, bind_journal
@@ -145,6 +146,7 @@ async def test_generation_dispatch_uses_owner_aware_backend(monkeypatch, exit_co
         _, denied = await execute(block, owner='pewds', session_id='fixture',
             disabled_tools={'generate_image'}, security_context=tool_execution.NO_TOOL_SECURITY_CONTEXT)
         _, result = await execute(block, owner='pewds', session_id='fixture',
+            client_runtime_context={'web_ui_state': {'incognito': incognito}},
             security_context=tool_execution.NO_TOOL_SECURITY_CONTEXT)
     assert denied['exit_code'] != 0
     assert journal.actions[0].execution_id is None
@@ -152,7 +154,7 @@ async def test_generation_dispatch_uses_owner_aware_backend(monkeypatch, exit_co
     assert journal.actions[1].execution_id is not None
     assert journal.actions[1].outcome['authoritative'] is (exit_code == 0)
     assert result['image_id'] == 'test'
-    assert calls == [(block.content, {'owner': 'pewds', 'session_id': 'fixture'})]
+    assert calls == [(block.content, {'owner': 'pewds', 'session_id': 'fixture', **({'incognito': True} if incognito else {})})]
 
 
 @pytest.mark.asyncio
diff --git a/tests/test_image_op_offload.py b/tests/test_image_op_offload.py
new file mode 100644
index 000000000..5e53ac038
--- /dev/null
+++ b/tests/test_image_op_offload.py
@@ -0,0 +1,54 @@
+"""The heavy image-edit CPU work must run off the event loop, and the app must
+expose in-flight heavy-op counts + a graceful shutdown so a deploy restart does
+not drop a 60-150 s edit."""
+import base64
+import io
+from pathlib import Path
+
+from PIL import Image
+
+from routes.gallery import gallery_routes as gr
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+def _png_b64(w, h, color=(120, 160, 210)):
+    buf = io.BytesIO()
+    Image.new("RGBA", (w, h), color).save(buf, format="PNG")
+    return base64.b64encode(buf.getvalue()).decode("ascii")
+
+
+def test_prepare_local_edit_caps_large_input():
+    src, mask, mw, mh, orig = gr._prepare_local_edit(_png_b64(4000, 3000), None, 768)
+    assert orig == (4000, 3000)
+    assert max(mw, mh) <= 768 and mw % 16 == 0 and mh % 16 == 0
+    assert mask  # a full-white mask is synthesised when none is supplied
+    assert Image.open(io.BytesIO(src)).size == (mw, mh)
+
+
+def test_prepare_local_edit_leaves_small_input_unchanged():
+    _src, _mask, mw, mh, orig = gr._prepare_local_edit(_png_b64(96, 96), _png_b64(96, 96, (255, 255, 255)), 768)
+    assert orig == (96, 96) and (mw, mh) == (96, 96)
+
+
+def test_restore_local_b64_resizes_back_to_original():
+    raw = _png_b64(768, 576)
+    out = gr._restore_local_b64(raw, (4000, 3000), (768, 576))
+    assert Image.open(io.BytesIO(base64.b64decode(out))).size == (4000, 3000)
+    # a same-size result is returned untouched
+    assert gr._restore_local_b64(raw, (768, 576), (768, 576)) == raw
+
+
+def test_inpaint_offloads_cpu_work_to_a_thread():
+    src = (ROOT / "routes/gallery/gallery_routes.py").read_text()
+    assert "await asyncio.to_thread(\n                        _prepare_local_edit" in src
+    assert "asyncio.to_thread(\n                                _restore_local_b64" in src
+
+
+def test_app_exposes_busy_count_and_graceful_shutdown():
+    src = (ROOT / "app.py").read_text()
+    assert "busy_image_ops" in src
+    assert '@app.get("/api/busy")' in src
+    assert "_HEAVY_IMAGE_OP_PREFIXES" in src
+    assert "timeout_graceful_shutdown" in src
+    assert "activity.begin_image_op" in src and "activity.end_image_op" in src
diff --git a/tests/test_image_provider_transport.py b/tests/test_image_provider_transport.py
index c161bc4a1..46d67598f 100644
--- a/tests/test_image_provider_transport.py
+++ b/tests/test_image_provider_transport.py
@@ -33,6 +33,38 @@ def test_native_generation_respects_admin_disable(monkeypatch):
     assert 'disabled' in result['error']
 
 
+@pytest.mark.parametrize('editing', [False, True])
+def test_incognito_images_never_write_gallery_or_files(image_transport, editing):
+    configure, source, requests, rows = image_transport
+    configure('https://openrouter.ai/api/v1')
+    if editing:
+        result = asyncio.run(ai_interaction.do_edit_image(
+            'Private edit', str(source), model_spec='openai/gpt-5-image',
+            owner='alice', session_id='private-chat', incognito=True))
+    else:
+        result = asyncio.run(ai_interaction.do_generate_image(
+            'Private image\nopenai/gpt-5-image', owner='alice',
+            session_id='private-chat', incognito=True))
+    assert 'error' not in result
+    assert result['image_url'].startswith('data:image/png;base64,')
+    assert base64.b64decode(result['image_url'].split(',', 1)[1]) == source.read_bytes()
+    assert not result['image_id']
+    assert not rows
+    assert not (source.parent / 'generated').exists()
+
+
+def test_incognito_url_image_is_not_persisted(image_transport, monkeypatch):
+    configure, source, requests, rows = image_transport
+    configure('https://api.openai.com/v1', body={'data': [{'url': 'https://example.com/output.png'}]})
+    monkeypatch.setattr(httpx, 'get', lambda *args, **kwargs: httpx.Response(200, content=source.read_bytes()))
+    monkeypatch.setattr('src.url_safety.check_outbound_url', lambda *args, **kwargs: (True, ''))
+    result = asyncio.run(ai_interaction.do_generate_image(
+        'Private image\nopenai/gpt-5-image', owner='alice', incognito=True))
+    assert result['image_url'].startswith('data:image/png;base64,')
+    assert not rows
+    assert not (source.parent / 'generated').exists()
+
+
 @pytest.fixture
 def image_transport(monkeypatch, tmp_path):
     rows = []
diff --git a/tests/test_imap_leak_fixes.py b/tests/test_imap_leak_fixes.py
index 83879d077..520a50e1e 100644
--- a/tests/test_imap_leak_fixes.py
+++ b/tests/test_imap_leak_fixes.py
@@ -281,7 +281,7 @@ def test_open_imap_connection_shuts_down_on_starttls_failure(monkeypatch):
     ))
     conn.starttls = MagicMock(side_effect=RuntimeError("STARTTLS rejected"))
 
-    monkeypatch.setattr(helpers, "_PolicyIMAP4", lambda *a, **kw: conn)
+    monkeypatch.setattr(helpers.imaplib, "IMAP4", lambda *a, **kw: conn)
 
     raised = False
     try:
diff --git a/tests/test_photo_editor_family.py b/tests/test_photo_editor_family.py
new file mode 100644
index 000000000..b29111360
--- /dev/null
+++ b/tests/test_photo_editor_family.py
@@ -0,0 +1,503 @@
+"""Scoped ``photo_editor`` capability family: routing, tools, and the
+Quick Edit agent endpoint.
+
+The family is context-only: it is offered to the model ONLY when an editor
+session / edit-this-photo request explicitly selects it, never inferred from
+message text and never part of the general tool list.
+"""
+import inspect
+
+import pytest
+
+from src.turn_contract import (
+    FAMILY_TOOLS,
+    requested_capabilities,
+    resolve_full_inventory_contract,
+    resolve_turn_contract,
+)
+from src.tool_schemas import FUNCTION_TOOL_SCHEMAS
+from src.tool_policy import ToolPolicy
+from src.tool_types import TOOL_TAGS
+from src.agent_tools import TOOL_HANDLERS
+from src.tool_index import BUILTIN_TOOL_DESCRIPTIONS
+from src.tool_capabilities import KNOWN_CAPABILITY_TOOLS
+from src.tool_security import PLAN_MODE_READONLY_TOOLS, _PLAN_MODE_KNOWN_MUTATORS
+
+PHOTO_TOOLS = frozenset(
+    {"plan_edit", "run_editor_command", "get_editor_screenshot", "ai_edit_image"}
+)
+FAMILY = FAMILY_TOOLS["photo_editor"]
+CORE_NAMES = frozenset({"bash", "python", "web_search", "web_fetch", "write_file"})
+
+
+def _schema_names():
+    return {s["function"]["name"] for s in FUNCTION_TOOL_SCHEMAS}
+
+
+def test_family_contains_scoped_tools_only():
+    assert FAMILY == PHOTO_TOOLS | {"generate_image"}
+
+
+def test_contract_offers_only_editor_tools_and_ask_user():
+    contract = resolve_turn_contract(
+        capabilities={"photo_editor"},
+        schemas=FUNCTION_TOOL_SCHEMAS,
+        policy=ToolPolicy(),
+        required_capabilities={"photo_editor"},
+    )
+    assert contract.offered == FAMILY | {"ask_user", "update_plan"}
+    assert not (CORE_NAMES & contract.offered)
+
+
+def test_photo_editor_is_never_inferred_from_message_text():
+    for message in (
+        "make it black and white",
+        "generate an image of a cat",
+        "remove the person on the left",
+        "add a full moon in the sky",
+        "blur the background behind the person",
+    ):
+        caps = requested_capabilities(message)
+        assert "photo_editor" not in caps, message
+
+
+def test_generate_image_keeps_its_own_family_without_leaking_photo_editor():
+    caps = requested_capabilities("Create a note and generate an image of a cat")
+    assert "image_generation" in caps
+    assert "photo_editor" not in caps
+
+
+def test_editor_tools_are_registered_everywhere():
+    schema_names = _schema_names()
+    for name in PHOTO_TOOLS:
+        assert name in TOOL_TAGS, name
+        assert name in TOOL_HANDLERS, name
+        assert name in BUILTIN_TOOL_DESCRIPTIONS, name
+        assert name in KNOWN_CAPABILITY_TOOLS, name
+        assert name in schema_names, name
+    assert "generate_image" in FAMILY
+
+
+def test_editor_tools_plan_mode_partition():
+    assert "get_editor_screenshot" in PLAN_MODE_READONLY_TOOLS
+    for name in ("plan_edit", "run_editor_command", "ai_edit_image"):
+        assert name in _PLAN_MODE_KNOWN_MUTATORS, name
+
+
+def test_full_inventory_contains_the_editor_tools():
+    preview = resolve_full_inventory_contract(
+        schemas=FUNCTION_TOOL_SCHEMAS, policy=ToolPolicy()
+    )
+    assert FAMILY <= set(preview.offered)
+
+
+def test_scope_preview_contract_keeps_only_the_editor_family():
+    from dataclasses import replace
+
+    from src.clean_agent_preview import scope_preview_contract
+
+    preview = resolve_full_inventory_contract(
+        schemas=FUNCTION_TOOL_SCHEMAS, policy=ToolPolicy()
+    )
+    routed = resolve_turn_contract(
+        capabilities={"photo_editor"},
+        schemas=FUNCTION_TOOL_SCHEMAS,
+        policy=ToolPolicy(),
+        required_capabilities={"photo_editor"},
+    )
+    scoped = scope_preview_contract(
+        replace(preview, selection_mode="full_compact_experiment"),
+        routed,
+        frozenset({"photo_editor"}),
+        extra_tools=frozenset({"ask_user"}),
+    )
+    assert FAMILY <= set(scoped.offered)
+    assert "ask_user" in scoped.offered
+    assert not (CORE_NAMES & set(scoped.offered))
+
+
+def test_editor_agent_endpoint_reports_scoped_tools():
+    from fastapi import FastAPI
+    from fastapi.testclient import TestClient
+
+    import routes.editor_agent_routes as eaar
+
+    eaar.set_editor_planner(lambda messages, owner: {"reply": "ok", "steps": [], "done": True})
+    try:
+        app = FastAPI()
+        app.include_router(eaar.setup_editor_agent_routes())
+        client = TestClient(app)
+        resp = client.post(
+            "/api/editor/agent",
+            json={"prompt": "hello there", "session": "s1"},
+        )
+        assert resp.status_code == 200
+        data = resp.json()
+        assert data["ok"] is True
+        assert PHOTO_TOOLS <= set(data["tools_offered"])
+        assert "generate_image" in data["tools_offered"]
+        assert not (CORE_NAMES & set(data["tools_offered"]))
+        assert data["trace"][0]["type"] == "session"
+    finally:
+        eaar.set_editor_planner(None)
+
+
+async def _route_contract(monkeypatch, message, *, attachment_meta=()):
+    from routes import chat_routes
+    from src import tool_security
+    from tests.test_foreground_model_routing import _RouteRequest, _chat_stream_endpoint
+
+    with monkeypatch.context() as route_patch:
+        endpoint = _chat_stream_endpoint(
+            route_patch, "agent", {},
+            session_model="odysseus-qwen3.5-tools-pre-heretic",
+            attachment_meta=attachment_meta,
+        )
+        route_patch.setattr(
+            chat_routes, "coerce_message_and_session",
+            lambda *args, **kwargs: (message, "session-1"),
+        )
+        route_patch.setattr(
+            tool_security, "owner_is_admin_or_single_user", lambda owner: True,
+        )
+        observed = []
+
+        async def capture_agent(*args, **kwargs):
+            observed.append(kwargs["turn_contract"])
+            yield 'data: {"delta":"ok"}\n\n'
+            yield "data: [DONE]\n\n"
+
+        route_patch.setattr(chat_routes, "stream_agent_loop", capture_agent)
+        request = _RouteRequest("agent")
+        request._form.update({
+            "message": message, "compare_mode": "false",
+            "allow_web_search": "false", "allow_bash": "false",
+        })
+        response = await endpoint(request)
+        async for _ in response.body_iterator:
+            pass
+        assert len(observed) == 1
+        return observed[0]
+
+
+@pytest.mark.asyncio
+async def test_normal_chat_turn_offers_no_editor_tools(monkeypatch):
+    for message in ("what is the capital of France", "write a haiku"):
+        contract = await _route_contract(monkeypatch, message)
+        assert "photo_editor" not in contract.capabilities, message
+        assert not (PHOTO_TOOLS & set(contract.offered)), message
+
+
+@pytest.mark.asyncio
+async def test_attached_photo_edit_selects_photo_editor_family(monkeypatch):
+    contract = await _route_contract(
+        monkeypatch,
+        "make this black and white",
+        attachment_meta=[{"id": "att1", "mime": "image/png", "name": "x.png"}],
+    )
+    assert contract.capabilities == {"photo_editor"}
+    assert set(contract.offered) == FAMILY | {"ask_user"}
+    assert not (CORE_NAMES & set(contract.offered))
+
+
+def test_chat_context_guides_open_or_absent_editor():
+    from pathlib import Path
+
+    src = (Path(__file__).resolve().parent.parent / "routes" / "chat_routes.py").read_text(
+        encoding="utf-8"
+    )
+    assert "The image editor is open (session " in src
+    assert "no image editor is open" in src
+    assert "the attached image in the editor (Quick Edit)" in src
+
+
+def test_generative_intent_classification():
+    from routes.editor_agent_routes import _generative_kind
+
+    assert _generative_kind("remove the person on the left") == "remove"
+    assert _generative_kind("erase the sign in the background") == "remove"
+    assert _generative_kind("add a full moon in the sky") == "add"
+    assert _generative_kind("put a bird on the fence") == "add"
+    assert _generative_kind("replace the sky with a sunset") == "replace"
+    assert _generative_kind("change the background to night") == "replace"
+    # Non-generative edits must stay deterministic.
+    assert _generative_kind("make it black and white") is None
+    assert _generative_kind("make it brighter") is None
+    assert _generative_kind("add a vignette") is None
+    assert _generative_kind("remove the background") is None
+    assert _generative_kind("sharpen the image") is None
+
+
+def test_generative_step_uses_ai_content_tools():
+    from routes.editor_agent_routes import _generative_step
+
+    assert _generative_step("remove", "remove the person")["op"] == "ai_edit_image"
+    assert _generative_step("replace", "replace the sky")["op"] == "ai_edit_image"
+    # Adding content to an existing photo is an instruction edit, not generate_image.
+    assert _generative_step("add", "add a moon")["op"] == "ai_edit_image"
+    assert _generative_step("add", "add a moon")["params"]["mode"] == "instruction"
+    # generate_image only for a brand-new image.
+    assert _generative_step("add", "create a new image of a moon")["op"] == "generate_image"
+
+
+def test_generative_mode_instruction_vs_masked():
+    from routes.editor_agent_routes import _generative_mode
+
+    # Masked only for an explicit regional removal of a clearly identified object.
+    assert _generative_mode("remove", "remove the person on the left") == "masked"
+    # Diffuse cleanup, replacement, season/style and additions use instruction mode.
+    assert _generative_mode("remove", "remove the distractions") == "instruction"
+    assert _generative_mode("replace", "make the background nicer") == "instruction"
+    assert _generative_mode("add", "add a full moon in the sky") == "instruction"
+
+
+def test_ensure_generative_replaces_deterministic_approximations():
+    from routes.editor_agent_routes import _ensure_generative
+
+    bad = [{"op": "selection.rectangle", "params": {}}, {"op": "adjustments.apply", "params": {}}]
+    removal = _ensure_generative("remove the person on the left", list(bad))
+    # A mask selection step now precedes the masked AI edit.
+    assert removal[-1]["op"] == "ai_edit_image"
+    assert removal[-1]["params"]["mode"] == "masked"
+    assert all(s["op"].startswith("selection.") for s in removal[:-1])
+    # Adding an object to an existing photo is an instruction edit (no selection).
+    addition = _ensure_generative("add a full moon in the sky", list(bad))
+    assert addition[-1]["op"] == "ai_edit_image"
+    assert addition[-1]["params"]["mode"] == "instruction"
+    # Non-generative plans are left untouched.
+    assert _ensure_generative("make it black and white", list(bad)) == bad
+
+
+def test_fallback_plan_routes_generative_intents():
+    import routes.editor_agent_routes as eaar
+
+    removal = eaar._fallback_plan("remove the person on the left")
+    assert removal["steps"][-1]["op"] == "ai_edit_image"
+    assert removal["steps"][-1]["params"]["mode"] == "masked"
+    addition = eaar._fallback_plan("add a full moon in the sky")
+    assert addition["steps"][-1]["op"] == "ai_edit_image"
+    assert addition["steps"][-1]["params"]["mode"] == "instruction"
+    plain = eaar._fallback_plan("make it black and white")
+    assert plain["steps"][0]["op"] == "adjustments.apply"
+
+
+def test_provider_message_is_actionable():
+    from src.ai_interaction import IMAGE_PROVIDER_REQUIRED_MESSAGE
+
+    assert "image generation provider" in IMAGE_PROVIDER_REQUIRED_MESSAGE
+    assert "Settings > Models" in IMAGE_PROVIDER_REQUIRED_MESSAGE
+
+
+def test_image_provider_respects_disabled_setting(monkeypatch):
+    import src.settings as settings
+
+    monkeypatch.setattr(settings, "load_settings", lambda: {"image_gen_enabled": False})
+    from src.ai_interaction import image_editing_provider_available
+
+    assert image_editing_provider_available(None) is False
+
+
+def _agent_client():
+    from fastapi import FastAPI
+    from fastapi.testclient import TestClient
+
+    import routes.editor_agent_routes as eaar
+
+    app = FastAPI()
+    app.include_router(eaar.setup_editor_agent_routes())
+    return eaar, TestClient(app)
+
+
+@pytest.mark.parametrize(
+    "prompt",
+    ["remove the person on the left", "add a full moon in the sky"],
+)
+def test_editor_agent_blocks_generative_without_provider(monkeypatch, prompt):
+    """No image provider -> zero canvas changes + a plain provider message."""
+    eaar, client = _agent_client()
+    # Planner proposes an unrelated deterministic edit, as the buggy run did.
+    eaar.set_editor_planner(
+        lambda messages, owner: {"reply": "done", "steps": [
+            {"op": "selection.rectangle", "params": {}},
+            {"op": "adjustments.apply", "params": {}},
+        ]}
+    )
+    monkeypatch.setattr(eaar, "_image_provider_available", lambda owner: False)
+    try:
+        resp = client.post(
+            "/api/editor/agent", json={"prompt": prompt, "session": "s1"}
+        )
+        assert resp.status_code == 200
+        data = resp.json()
+        assert data["needs_provider"] is True
+        assert data["blocked"] is True
+        assert "image generation provider" in data["message"]
+        assert data["image_provider"] is False
+        assert data["results"] == []
+        # Nothing was executed through the bridge (zero canvas changes).
+        assert not any(t.get("type") == "step" for t in data["trace"])
+        assert any(t.get("reason") == "image_provider_unavailable" for t in data["trace"])
+        # The proposed deterministic plan was replaced by the correct AI op.
+        ops = [s["op"] for s in data["steps"]]
+        assert ops[-1] in ("ai_edit_image", "generate_image")
+    finally:
+        eaar.set_editor_planner(None)
+
+
+def test_editor_agent_prefers_ai_op_over_deterministic_when_provider_present(monkeypatch):
+    eaar, client = _agent_client()
+    eaar.set_editor_planner(
+        lambda messages, owner: {"reply": "done", "steps": [
+            {"op": "selection.rectangle", "params": {}},
+            {"op": "adjustments.apply", "params": {}},
+        ]}
+    )
+    monkeypatch.setattr(eaar, "_image_provider_available", lambda owner: True)
+
+    async def _instant_wait_for(awaitable, *args, **kwargs):
+        # The plan now starts with a mask-selection bridge step; resolve it
+        # immediately instead of waiting for a (non-existent) editor subscriber.
+        try:
+            awaitable.close()
+        except Exception:
+            pass
+        return {"ok": True, "result": {"width": 100, "height": 100}}
+
+    monkeypatch.setattr(eaar.asyncio, "wait_for", _instant_wait_for)
+
+    calls = []
+
+    class _FakeAiEdit:
+        async def execute(self, content, ctx):
+            calls.append(content)
+            return "ai_edit_image: fake", {"output": "ok", "exit_code": 0}
+
+    class _FakeGen:
+        async def execute(self, content, ctx):
+            calls.append(content)
+            return "generate_image: fake", {"output": "ok", "exit_code": 0}
+
+    import src.agent_tools.editor_tools as et
+    monkeypatch.setattr(et, "AiEditImageTool", _FakeAiEdit)
+    monkeypatch.setattr(et, "GenerateImageLayerTool", _FakeGen)
+    try:
+        resp = client.post(
+            "/api/editor/agent",
+            json={"prompt": "remove the person on the left", "session": "s1"},
+        )
+        assert resp.status_code == 200
+        data = resp.json()
+        assert data["ok"] is True
+        ops = [s["op"] for s in data["steps"]]
+        assert ops[-1] == "ai_edit_image"
+        assert any(r.get("op") == "ai_edit_image" for r in data["results"])
+        assert calls, "the AI edit tool should have been invoked"
+        assert "adjustments.apply" not in ops
+    finally:
+        eaar.set_editor_planner(None)
+
+
+def test_editor_prompts_advertise_canonical_shapes():
+    import routes.editor_agent_routes as eaar
+
+    canonical = eaar._CANONICAL_GUIDANCE
+    assert "brightness-contrast" in canonical and "render-clouds" in canonical
+    assert canonical in eaar._SYSTEM_PROMPT
+    assert canonical in eaar._CHECK_SYSTEM_PROMPT
+    assert "_CANONICAL_GUIDANCE" in inspect.getsource(eaar.setup_editor_agent_routes)
+
+
+def test_run_editor_command_schema_advertises_canonical_shapes():
+    from src.tool_schemas import FUNCTION_TOOL_SCHEMAS
+
+    schema = next(s for s in FUNCTION_TOOL_SCHEMAS
+                  if s["function"]["name"] == "run_editor_command")
+    desc = schema["function"]["description"]
+    assert "brightness-contrast" in desc and "render-clouds" in desc
+    assert "vignette" in desc  # names the banned invented ids
+
+
+def test_photo_editor_chat_without_canvas_asks_to_open_editor():
+    from src import clean_agent_preview
+
+    source = inspect.getsource(clean_agent_preview.stream_preview)
+    assert "not open on the editor canvas" in source
+    assert "'photo_editor' in (getattr(turn_contract, 'active_capabilities'" in source
+
+
+def test_chat_photo_edit_without_open_editor_short_circuits(monkeypatch):
+    """A photo-edit chat turn with no open editor must not run the tool loop.
+
+    Regression: offering the editor tools with no canvas made the model loop
+    on plan_edit/run_editor_command until the round cap and end with an empty
+    answer. The runtime now answers deterministically and asks the user to
+    open the image in the editor.
+    """
+    import asyncio
+    import json as _json
+    from dataclasses import replace
+
+    import src.clean_agent_preview as module
+
+    contract = replace(
+        resolve_full_inventory_contract(schemas=FUNCTION_TOOL_SCHEMAS, policy=ToolPolicy()),
+        active_capabilities=frozenset({"photo_editor"}),
+    )
+    provider_calls = []
+
+    class _Client:
+        def __init__(self, **kwargs):
+            pass
+
+        async def __aenter__(self):
+            return self
+
+        async def __aexit__(self, *args):
+            pass
+
+        def stream(self, *args, **kwargs):
+            provider_calls.append(kwargs.get("json"))
+            raise AssertionError("provider must not be called when no editor is open")
+
+    monkeypatch.setattr(module.httpx, "AsyncClient", _Client)
+
+    async def _run():
+        return [
+            chunk
+            async for chunk in module.stream_preview(
+                endpoint_url="http://test",
+                model="test",
+                headers={},
+                messages=[{"role": "user", "content": "make this black and white"}],
+                turn_contract=contract,
+                session_id="test",
+                owner="test",
+                disabled_tools=set(),
+                tool_policy=ToolPolicy(),
+                client_runtime_context={"web_ui_state": {"photo_editor_open": False}},
+            )
+        ]
+
+    chunks = asyncio.run(_run())
+    events = [
+        _json.loads(chunk[6:])
+        for chunk in chunks
+        if chunk.startswith("data: ") and not chunk.startswith("data: [DONE]")
+    ]
+
+    assert provider_calls == []
+    contract_event = next(e for e in events if e.get("type") == "turn_contract")
+    assert "photo_editor" in contract_event["active_capabilities"]
+    final = next(e for e in events if e.get("type") == "final_response")
+    lowered = final["content"].lower()
+    assert "editor" in lowered and "open" in lowered
+    # One-click affordance contract for the chat UI.
+    assert final["photo_editor_action"] == {
+        "kind": "open_and_apply",
+        "prompt": "make this black and white",
+    }
+    assert not any(e.get("type") == "tool_start" for e in events)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(pytest.main([__file__, "-q"]))
diff --git a/tests/test_photo_editor_style_guide.py b/tests/test_photo_editor_style_guide.py
new file mode 100644
index 000000000..449aa3438
--- /dev/null
+++ b/tests/test_photo_editor_style_guide.py
@@ -0,0 +1,642 @@
+"""Unit tests for the shared photo-editor style guide and its server wiring.
+
+The guide (``src/editor_style_guide.py``) is the single source of truth for
+intent -> ops routing, calibrated strengths and the low-key / temperature /
+portrait / ambiguity rules. It feeds both the server planner and (via
+``GET /api/editor/style-guide``) the browser fallback.
+"""
+import pytest
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+
+import routes.editor_agent_routes as eaar
+from src import editor_style_guide as guide
+
+
+@pytest.fixture(autouse=True)
+def _reset_planner():
+    eaar.set_editor_planner(None)
+    yield
+    eaar.set_editor_planner(None)
+
+
+@pytest.fixture()
+def client():
+    app = FastAPI()
+    app.include_router(eaar.setup_editor_agent_routes())
+    return TestClient(app)
+
+
+def _ops(steps):
+    return [s["op"] for s in steps]
+
+
+def test_new_ops_are_in_the_server_op_catalog():
+    # If a new retouch/selection op is missing from OP_CATALOG, _parse_plan
+    # filters a valid plan step out and the edit silently disappears.
+    for name in guide.NEW_OP_NAMES:
+        assert name in eaar.OP_CATALOG
+    for name in ("photo.autoTone", "retouch.skin", "retouch.teeth",
+                 "selection.face", "selection.background"):
+        assert name in eaar._OP_SET
+
+
+def test_portrait_skin_intent_is_a_multi_step_plan():
+    plan = guide.fallback_plan("can you fix the skin a bit, look my best")
+    assert plan is not None
+    # No leading whole-image auto tone: it washes out the face. Go straight to a
+    # gentle face retouch, then clear the selection.
+    assert _ops(plan["steps"]) == [
+        "selection.face", "retouch.skin", "selection.deselect",
+    ]
+    skin = plan["steps"][1]["params"]
+    assert 0 < skin["smooth"] <= 14
+    assert 0 < skin["opacity"] <= 0.45
+    # No global lift anywhere in the portrait chain (client never brightens skin).
+    assert not any("autoTone" in op or "brightness" in op or "exposure" in op
+                   for op in _ops(plan["steps"]))
+
+
+def test_portrait_intent_does_not_lead_with_auto_tone():
+    for prompt in ("make me look better", "fix the skin", "fix my teeth",
+                   "smooth my complexion", "portrait touch up"):
+        plan = guide.fallback_plan(prompt)
+        assert plan is not None, prompt
+        assert "photo.autoTone" not in _ops(plan["steps"]), prompt
+
+
+def test_teeth_intent_selects_face_then_whitens():
+    plan = guide.fallback_plan("fix my teeth")
+    assert _ops(plan["steps"]) == ["selection.face", "retouch.teeth"]
+    assert plan["steps"][1]["params"]["desat"] > 0
+
+
+def test_background_intent_is_selection_then_masked_blur():
+    plan = guide.fallback_plan("blur the background / make the background nicer")
+    ops = _ops(plan["steps"])
+    assert ops == ["selection.background", "filters.applyMasked"]
+    assert plan["steps"][1]["params"]["id"] == "blur-gaussian"
+
+
+def test_temperature_sign_is_cool_negative_warm_positive():
+    cool = guide.fallback_plan("make it moodier")
+    assert cool["steps"][0]["params"] == {
+        "type": "white-balance", "params": {"temperature": -25}}
+    warm = guide.fallback_plan("make it warmer, golden summer feel")
+    assert warm["steps"][0]["params"]["params"]["temperature"] == 25
+
+
+def test_lighting_intent_uses_auto_tone_then_single_shadow_lift():
+    plan = guide.fallback_plan("fix the lighting, it's too dark")
+    assert _ops(plan["steps"]) == ["photo.autoTone", "adjustments.apply"]
+    inner = plan["steps"][1]["params"]
+    assert inner["type"] == "shadows-highlights"
+    assert inner["params"]["highlights"] <= 0
+    # The sanctioned low-key pair, never a stack of unspecified lifts.
+    assert len(plan["steps"]) == 2
+
+
+def test_ambiguous_prompt_asks_the_user_with_concrete_options():
+    plan = guide.fallback_plan("clean this up")
+    assert plan["steps"] == []
+    ask = plan["ask_user"]
+    assert ask["question"]
+    assert 2 <= len(ask["options"]) <= 3
+    assert all(o.get("label") for o in ask["options"])
+    assert guide.is_ambiguous("clean this up") is True
+    # A concrete defect is not ambiguous.
+    assert guide.is_ambiguous("fix the lighting") is False
+
+
+def test_collapse_global_lifts_replaces_a_stack():
+    # With an auto tone present, extra brightness/exposure lifts are dropped
+    # (the auto tone is the single sanctioned lift).
+    with_auto = [
+        {"op": "photo.autoTone", "params": {}},
+        {"op": "adjustments.apply",
+         "params": {"type": "brightness-contrast", "params": {"brightness": 30}}},
+        {"op": "adjustments.apply",
+         "params": {"type": "exposure", "params": {"exposure": 20}}},
+    ]
+    out = guide.collapse_global_lifts(with_auto)
+    assert len(out) == 1
+    assert out[0]["op"] == "photo.autoTone"
+    # Without an auto tone, a stack collapses to one safe shadows-highlights.
+    no_auto = [
+        {"op": "adjustments.apply",
+         "params": {"type": "brightness-contrast", "params": {"brightness": 30}}},
+        {"op": "adjustments.apply",
+         "params": {"type": "exposure", "params": {"exposure": 20}}},
+    ]
+    out2 = guide.collapse_global_lifts(no_auto)
+    assert len(out2) == 1
+    assert out2[0]["params"]["type"] == "shadows-highlights"
+    assert out2[0]["params"]["params"]["highlights"] <= 0
+    # The sanctioned low-key pair (auto tone + one shadows-highlights) is kept.
+    pair = [
+        {"op": "photo.autoTone", "params": {}},
+        {"op": "adjustments.apply",
+         "params": {"type": "shadows-highlights",
+                    "params": {"shadows": 30, "highlights": -15}}},
+    ]
+    assert guide.collapse_global_lifts(pair) == pair
+
+
+def test_collapse_global_lifts_clamps_a_single_brightness_lift():
+    steps = [{"op": "adjustments.apply",
+              "params": {"type": "brightness-contrast", "params": {"brightness": 80}}}]
+    out = guide.collapse_global_lifts(steps)
+    assert out[0]["params"]["params"]["brightness"] <= 25
+
+
+def test_llm_plan_parse_collapses_lifts_and_keeps_new_ops():
+    raw = (
+        '{"reply": "x", "steps": ['
+        '{"op": "retouch.skin", "params": {"smooth": 20}},'
+        '{"op": "photo.autoTone", "params": {}},'
+        '{"op": "adjustments.apply", "params": {"type": "exposure", "params": {"exposure": 25}}}'
+        ']}'
+    )
+    parsed = eaar._parse_plan(raw)
+    ops = _ops(parsed["steps"])
+    assert "retouch.skin" in ops
+    # Every global lift that trails retouch.skin is dropped (the client guard
+    # "never brighten skin"), so nothing but the retouch step remains.
+    assert ops == ["retouch.skin"]
+
+
+def test_editor_agent_returns_ask_user_for_ambiguous_prompt(client):
+    eaar.set_editor_planner(lambda messages, owner: '{"reply": "ok", "steps": []}')
+    resp = client.post("/api/editor/agent", json={"prompt": "clean this up"})
+    assert resp.status_code == 200
+    body = resp.json()
+    assert body.get("ask_user_pending") is True
+    assert body["steps"] == []
+    assert 2 <= len(body["ask_user"]["options"]) <= 3
+
+
+def test_editor_plan_returns_ask_user_for_ambiguous_prompt(client):
+    eaar.set_editor_planner(lambda messages, owner: None)
+    resp = client.post("/api/editor/plan", json={"prompt": "clean this up"})
+    assert resp.status_code == 200
+    body = resp.json()
+    assert body["steps"] == []
+    assert body.get("ask_user")
+
+
+def test_style_guide_endpoint_serves_the_shared_source(client):
+    resp = client.get("/api/editor/style-guide")
+    assert resp.status_code == 200
+    data = resp.json()
+    assert data["version"] == guide.STYLE_GUIDE_VERSION
+    assert {o["op"] for o in data["new_ops"]} == set(guide.NEW_OP_NAMES)
+    assert data["intents"]
+    assert "temperature" in data["rules"]["temperature_sign"].lower() or \
+        "negative" in data["rules"]["temperature_sign"]
+    # The prompt guidance states the sign rule explicitly.
+    assert "NEGATIVE" in data["guidance"] and "POSITIVE" in data["guidance"]
+
+
+def test_prompts_embed_the_style_guidance():
+    assert guide.guidance() in eaar._SYSTEM_PROMPT
+    assert guide.guidance() in eaar._CHECK_SYSTEM_PROMPT
+
+
+@pytest.mark.parametrize("prompt", [
+    "make it pretty", "make it pop", "professional", "film look",
+])
+def test_generic_look_intent_is_a_decisive_multi_step_plan(prompt):
+    plan = guide.fallback_plan(prompt)
+    assert plan is not None
+    ops = _ops(plan["steps"])
+    assert ops[0] == "photo.autoTone"
+    assert len(ops) >= 3
+    # A visible vibrance lift and a local-contrast filter are present.
+    assert any(s["op"] == "adjustments.apply" and s["params"].get("type") == "vibrance"
+               for s in plan["steps"])
+    assert any(s["op"] == "filters.apply" and s["params"].get("id") == "clarity"
+               for s in plan["steps"])
+
+
+def test_restore_intent_never_large_exposure_lift():
+    plan = guide.fallback_plan("restore this old photo")
+    assert plan is not None
+    ops = _ops(plan["steps"])
+    assert ops[0] == "photo.autoTone"
+    assert "filters.apply" in ops  # sharpen
+    # Colour recovery present.
+    assert any(s["op"] == "adjustments.apply" and s["params"].get("type") == "white-balance"
+               for s in plan["steps"])
+    # No exposure lift at all, and the contrast lift keeps brightness neutral.
+    assert not any(s["params"].get("type") == "exposure" for s in plan["steps"])
+    for s in plan["steps"]:
+        if s["params"].get("type") == "brightness-contrast":
+            assert s["params"]["params"].get("brightness", 0) == 0
+
+
+def test_strengthen_promotes_a_timid_plan_to_the_recipe():
+    timid = [{"op": "adjustments.apply",
+              "params": {"type": "brightness-contrast", "params": {"brightness": 8}}}]
+    promoted = guide.strengthen("make it pop", timid)
+    assert promoted != timid
+    assert _ops(promoted)[0] == "photo.autoTone"
+    assert len(promoted) >= 3
+    # A prompt with no recipe leaves the plan untouched.
+    assert guide.strengthen("nonsense prompt zzz", timid) == timid
+
+
+def test_enforce_guards_removes_trailing_lift_after_skin():
+    steps = [
+        {"op": "selection.face", "params": {}},
+        {"op": "retouch.skin", "params": {"smooth": 24}},
+        {"op": "photo.autoTone", "params": {}},
+    ]
+    guarded = guide.enforce_guards(steps)
+    assert _ops(guarded) == ["selection.face", "retouch.skin"]
+    stacked = [
+        {"op": "adjustments.apply",
+         "params": {"type": "brightness-contrast", "params": {"brightness": 20}}},
+        {"op": "adjustments.apply",
+         "params": {"type": "exposure", "params": {"exposure": 20}}},
+    ]
+    collapsed = guide.enforce_guards(stacked)
+    assert len(collapsed) == 1
+    assert collapsed[0]["params"]["type"] == "shadows-highlights"
+
+
+def test_plan_route_follows_the_recipe_for_generic_look(client):
+    import json as _json
+    eaar.set_editor_planner(lambda messages, owner: _json.dumps({
+        "reply": "ok",
+        "steps": [{"op": "adjustments.apply",
+                   "params": {"type": "brightness-contrast", "params": {"brightness": 8}}}],
+    }))
+    resp = client.post("/api/editor/plan", json={"prompt": "make it pop"})
+    assert resp.status_code == 200
+    data = resp.json()
+    assert data["steps"][0]["op"] == "photo.autoTone"
+    assert len(data["steps"]) >= 3
+    assert data["planner"].endswith("+guide")
+
+
+def test_guidance_documents_look_and_restore_recipes():
+    text = guide.guidance()
+    low = text.lower()
+    assert "clarity" in low and "vignette" in low
+    assert "vibrance" in low
+    assert "restore" in low and "exposure" in low
+    assert "autoTone" in text
+
+
+def test_plan_special_format_crops_and_resizes():
+    special = eaar._plan_special(
+        "make a 1080x1350 Instagram post from this", {"width": 900, "height": 600}, False)
+    assert special is not None
+    steps, reply, note = special
+    assert _ops(steps) == ["document.crop", "document.resizeCanvas"]
+    assert "1080" in reply and "1350" in reply
+    assert set(steps[0]["params"]) >= {"x", "y", "width", "height"}
+    assert steps[1]["params"]["width"] == 1080 and steps[1]["params"]["height"] == 1350
+
+
+def test_plan_special_text_add_with_shadow_is_not_generative():
+    assert eaar._generative_kind("add a title TOKYO with a drop shadow") is None
+    special = eaar._plan_special("add a title TOKYO with a drop shadow", {}, False)
+    assert special is not None
+    steps, reply, note = special
+    assert _ops(steps) == ["text.add", "layers.addStyle"]
+    assert steps[0]["params"]["text"] == "TOKYO"
+    assert steps[1]["params"]["type"] == "drop-shadow"
+    assert "drop shadow" in reply.lower()
+
+
+def test_plan_special_extend_resizes_without_provider_generative_with():
+    steps, reply, note = eaar._plan_special(
+        "extend the canvas to 16:9", {"width": 900, "height": 600}, False)
+    assert _ops(steps) == ["document.resizeCanvas"]
+    assert "provider" in note.lower()
+    steps2, _, note2 = eaar._plan_special(
+        "extend the canvas to 16:9", {"width": 900, "height": 600}, True)
+    assert _ops(steps2) == ["ai.generativeExpand"]
+    assert note2 == ""
+
+
+def test_plan_special_psd_export():
+    special = eaar._plan_special("save as PSD with layers", {}, False)
+    assert special is not None and _ops(special[0]) == ["document.savePsd"]
+
+
+def test_background_replacement_is_generative_not_blur():
+    assert eaar._generative_kind("put her on a beach") == "replace"
+    assert eaar._generative_kind("remove the background and put her on a beach") == "replace"
+
+
+def test_verified_reply_corrects_a_false_size_claim():
+    corrected = eaar._verified_reply(
+        "make a 1080x1350 Instagram post",
+        [{"op": "history.mark", "params": {}}],
+        [{"ok": True}],
+        {"width": 600, "height": 600},
+        "Exported your 900x600 as a 1080x1350 Instagram post.",
+    )
+    assert "600" in corrected
+    assert "still" in corrected.lower() or "didn't apply" in corrected.lower()
+    passed = eaar._verified_reply(
+        "make a 1080x1350 Instagram post",
+        [{"op": "document.crop", "params": {}}, {"op": "document.resizeCanvas", "params": {}}],
+        [{"ok": True}, {"ok": True}],
+        {"width": 1080, "height": 1350},
+        "Setting the canvas to 1080\u00d71350.",
+    )
+    assert "1080" in passed and "1350" in passed
+
+
+def test_plan_endpoint_returns_deterministic_format_steps(client, monkeypatch):
+    eaar.set_editor_planner(lambda messages, owner: {"reply": "Exporting.", "steps": []})
+    monkeypatch.setattr(eaar, "_image_provider_available", lambda owner: False)
+    resp = client.post("/api/editor/plan", json={
+        "prompt": "make a 1080x1350 Instagram post",
+        "state": {"width": 900, "height": 600},
+    })
+    data = resp.json()
+    assert data["planner"] == "deterministic"
+    assert _ops(data["steps"])[:2] == ["document.crop", "document.resizeCanvas"]
+
+
+def test_style_guide_serves_format_text_psd_rules():
+    rules = guide.as_json()["rules"]
+    assert "format" in rules and "text" in rules and "psd" in rules
+    assert guide.STYLE_GUIDE_VERSION >= 3
+
+
+# ── Quick Edit coverage: structural ops (server planner gaps) ──────────
+# Every prompt that failed the live Quick Edit coverage audit because the
+# server planner emitted a generic adjustments/transform step instead of the
+# exact structural op the browser supports.
+_STRUCTURAL_PROMPTS = [
+    ("fill the white area with red", "fill.flood"),          # 1
+    ("flood fill the sky with blue", "fill.flood"),          # 2
+    ("make the text bigger", "text.edit"),                   # 3
+    ("make the title red", "text.edit"),                     # 4
+    ("add a colour overlay", "layers.addStyle"),             # 8
+    ("align the logo to the centre", "layers.align"),        # 9
+    ("align the layer to the left", "layers.align"),         # 10
+    ("rotate only this layer 90 degrees", "layer.rotate"),   # 11
+    ("flip this layer horizontally", "layer.flip"),          # 12
+    ("rotate the whole image 90 degrees", "document.rotate"),  # 13
+    ("flip the canvas vertically", "document.flip"),         # 14
+    ("copy the selection", "selection.copy"),                # 19
+    ("paste", "selection.paste"),                            # 20
+    ("flatten the image", "layers.flatten"),                 # 40
+    ("merge the layer down", "layers.mergeDown"),            # 41
+]
+
+
+@pytest.mark.parametrize("prompt,expected_op", _STRUCTURAL_PROMPTS)
+def test_structural_plan_routes_to_the_exact_op(prompt, expected_op):
+    plan = guide.structural_plan(prompt)
+    assert plan is not None, prompt
+    assert plan["planner"] == "deterministic"
+    assert expected_op in _ops(plan["steps"]), (prompt, _ops(plan["steps"]))
+
+
+@pytest.mark.parametrize("prompt,expected_op", _STRUCTURAL_PROMPTS)
+def test_plan_special_emits_structural_ops(prompt, expected_op):
+    # The server override path (_plan_special) must return the structural step,
+    # otherwise a wrong model plan suppresses the browser fallback.
+    special = eaar._plan_special(prompt, {"width": 900, "height": 600}, True)
+    assert special is not None, prompt
+    steps, reply, _ = special
+    assert expected_op in _ops(steps), (prompt, _ops(steps))
+    assert reply
+
+
+def test_structural_ops_are_in_the_server_op_catalog():
+    for name in ("fill.flood", "selection.fill", "text.edit", "layers.align",
+                 "layer.rotate", "layer.flip", "document.rotate", "document.flip",
+                 "selection.copy", "selection.paste", "layers.flatten",
+                 "layers.mergeDown"):
+        assert name in eaar._OP_SET, name
+
+
+def test_structural_plan_ignores_non_structural_intents():
+    for prompt in ("make it brighter", "blur the background", "make it punchy",
+                   "restore this old photo", "smooth the skin", "sharpen it",
+                   "add the title \"Summer\"", "duplicate this layer"):
+        assert guide.structural_plan(prompt) is None, prompt
+
+
+def test_structural_params_match_the_client():
+    # Canonical params must match static/js/editor/galleryEditor.js control ops.
+    fill = guide.structural_plan("fill the white area with red")["steps"][0]
+    assert fill["op"] == "fill.flood" and fill["params"]["color"] == "#ff0000"
+    sel = guide.structural_plan("fill the selection with blue")["steps"][0]
+    assert sel["op"] == "selection.fill" and sel["params"]["color"] == "#0000ff"
+    align = guide.structural_plan("align the layer to the left")["steps"][0]
+    assert align["params"]["mode"] == "left"
+    rot = guide.structural_plan("rotate only this layer 90 degrees")["steps"][0]
+    assert rot["params"]["degrees"] == 90
+    flip = guide.structural_plan("flip the canvas vertically")["steps"][0]
+    assert flip["op"] == "document.flip" and flip["params"]["axis"] == "v"
+    overlay = guide.structural_plan("add a colour overlay")["steps"][0]
+    assert overlay["params"]["type"] == "color-overlay"
+    edit = guide.structural_plan("make the text bigger")["steps"][0]
+    assert edit["op"] == "text.edit" and edit["params"]["size"] > 0
+
+
+def test_plan_route_returns_structural_steps(client):
+    resp = client.post("/api/editor/plan", json={
+        "prompt": "flatten the image",
+        "state": {"width": 900, "height": 600},
+    })
+    data = resp.json()
+    assert data["planner"] == "deterministic"
+    assert "layers.flatten" in _ops(data["steps"])
+
+
+def test_style_guide_serves_structural_rule():
+    rules = guide.as_json()["rules"]
+    assert "structural" in rules
+    assert guide.STYLE_GUIDE_VERSION >= 5
+
+
+# ── Targeted recolour + named reference looks ──────────────────────────
+
+_RECOLOR_CASES = [
+    ("make only the red car blue", "red"),
+    ("recolour the red rock to teal", "red"),
+    ("change the yellow car to red", "yellow"),
+]
+
+
+@pytest.mark.parametrize("prompt,source", _RECOLOR_CASES)
+def test_targeted_recolor_selects_object_then_masked_hue(prompt, source):
+    plan = guide.recolor_plan(prompt)
+    assert plan is not None
+    assert _ops(plan["steps"]) == ["selection.samText", "adjustments.applyMasked"]
+    sel, adj = plan["steps"]
+    assert sel["params"]["text"]                    # object description for the mask
+    assert sel["params"]["fallbackColor"] == guide.color_for_name(source)
+    assert adj["params"]["mode"] == "hue-saturation"
+    assert "hue" in adj["params"] and isinstance(adj["params"]["hue"], int)
+
+
+def test_recolor_never_emits_selection_fill_or_a_global_tint():
+    for prompt, _ in _RECOLOR_CASES:
+        ops = _ops(guide.recolor_plan(prompt)["steps"])
+        # A flat fill destroys shading; a whole-image tint is not targeted.
+        assert "selection.fill" not in ops
+        assert "adjustments.apply" not in ops  # exact op, not applyMasked
+
+
+def test_targeted_recolor_hue_delta_is_source_to_target():
+    # red (hue 0) -> blue (hue 240): shortest rotation is -120 degrees.
+    plan = guide.recolor_plan("make only the red car blue")
+    assert plan["steps"][1]["params"]["hue"] == -120
+
+
+def test_recolor_masked_hue_carries_source_hue():
+    # red has hue 0; the client uses sourceHue as the rotation center so
+    # neighbouring colours (chrome, windows, highlights) keep their own hue.
+    plan = guide.recolor_plan("make only the red car blue")
+    assert plan["steps"][1]["params"]["sourceHue"] == 0
+
+
+def test_enforce_guards_drops_global_lift_after_masked_recolor():
+    # A recolour keeps shading; a later whole-image tone lift would tint the
+    # rest of the photo, so enforce_guards must drop global lifts after it.
+    steps = [
+        {"op": "selection.samText", "params": {"text": "red car"}},
+        {"op": "adjustments.applyMasked",
+         "params": {"mode": "hue-saturation", "hue": -120, "sourceHue": 0}},
+        {"op": "adjustments.apply",
+         "params": {"type": "brightness-contrast", "params": {"brightness": 20}}},
+        {"op": "photo.autoTone", "params": {}},
+    ]
+    assert _ops(guide.enforce_guards(steps)) == ["selection.samText", "adjustments.applyMasked"]
+
+
+def test_enforce_guards_drops_whole_image_grade_after_masked_recolor():
+    # Not just tone "lifts": ANY whole-image adjustment (vibrance/saturation/
+    # autoTone) after a masked recolour re-grades the photo and undoes the
+    # "only this object" intent, so enforce_guards must drop them all.
+    steps = [
+        {"op": "selection.samText", "params": {"text": "red car"}},
+        {"op": "adjustments.applyMasked",
+         "params": {"mode": "hue-saturation", "hue": -120, "sourceHue": 0}},
+        {"op": "adjustments.apply",
+         "params": {"type": "vibrance", "params": {"vibrance": 20}}},
+        {"op": "adjustments.apply",
+         "params": {"type": "hue-saturation", "params": {"saturation": 12}}},
+        {"op": "photo.autoTone", "params": {}},
+    ]
+    assert _ops(guide.enforce_guards(steps)) == ["selection.samText", "adjustments.applyMasked"]
+
+
+def test_enforce_guards_keeps_grades_when_there_is_no_recolor():
+    # A recipe/look (no masked recolour) still keeps its whole-image grades.
+    steps = [
+        {"op": "photo.autoTone", "params": {}},
+        {"op": "adjustments.apply", "params": {"type": "vibrance", "params": {"vibrance": 18}}},
+        {"op": "adjustments.apply",
+         "params": {"type": "brightness-contrast", "params": {"brightness": 6, "contrast": -10}}},
+    ]
+    assert _ops(guide.enforce_guards(steps)) == ["photo.autoTone", "adjustments.apply"]
+
+
+def test_recolor_to_white_uses_the_image_model_not_a_hue_shift():
+    # A white/black/grey target cannot be reached by a hue rotation.
+    plan = guide.recolor_plan("make the red car white")
+    assert plan is not None
+    assert _ops(plan["steps"]) == ["selection.samText", "ai_edit_image"]
+    assert plan["steps"][1]["params"]["mode"] == "masked"
+
+
+def test_recolor_with_single_colour_uses_masked_image_model():
+    plan = guide.recolor_plan("make the flowers bright pink")
+    assert plan is not None
+    assert _ops(plan["steps"]) == ["selection.samText", "ai_edit_image"]
+    assert plan["steps"][0]["params"]["text"] == "flowers"
+    params = plan["steps"][1]["params"]
+    assert params["mode"] == "masked"
+    assert params["steps"] == 8
+
+
+def test_recolor_does_not_hijack_unrelated_colour_prompts():
+    for prompt in ("make it blue", "fill the white area with red",
+                   "make the title red", "make this black and white",
+                   "blur the background"):
+        assert guide.recolor_plan(prompt) is None
+
+
+@pytest.mark.parametrize("prompt", [
+    "make it look like a Wes Anderson film",
+    "make it look like a film noir",
+    "make it look like vintage Kodachrome",
+])
+def test_named_recipe_looks_are_adjustment_stacks(prompt):
+    plan = guide.look_plan(prompt)
+    assert plan is not None
+    ops = _ops(plan["steps"])
+    assert ops and "ai_edit_image" not in ops
+
+
+@pytest.mark.parametrize("prompt", [
+    "make it look like cyberpunk",
+    "make it look like a Studio Ghibli film",
+])
+def test_strong_named_looks_use_instruction_mode(prompt):
+    plan = guide.look_plan(prompt)
+    assert plan is not None
+    assert _ops(plan["steps"]) == ["ai_edit_image"]
+    assert plan["steps"][0]["params"]["mode"] == "instruction"
+    assert plan["steps"][0]["params"]["steps"] == 8
+
+
+def test_structural_plan_dispatches_looks_and_recolor():
+    wes = guide.structural_plan("make it look like a Wes Anderson film")
+    assert "adjustments.apply" in _ops(wes["steps"])
+    recolor = guide.structural_plan("make only the red car blue")
+    assert _ops(recolor["steps"]) == ["selection.samText", "adjustments.applyMasked"]
+
+
+def test_named_looks_do_not_hijack_generative_lookalikes():
+    for prompt in ("make it look snowy", "make it look like summer"):
+        assert guide.look_plan(prompt) is None
+
+
+def test_plan_route_returns_targeted_recolor(client):
+    resp = client.post("/api/editor/plan", json={
+        "prompt": "make only the red car blue",
+        "state": {"width": 900, "height": 600},
+    })
+    assert resp.status_code == 200
+    data = resp.json()
+    assert data["planner"] == "deterministic"
+    assert _ops(data["steps"]) == ["selection.samText", "adjustments.applyMasked"]
+    assert "selection.fill" not in _ops(data["steps"])
+
+
+def test_plan_route_returns_named_look(client):
+    resp = client.post("/api/editor/plan", json={
+        "prompt": "make it look like a Wes Anderson film",
+        "state": {"width": 900, "height": 600},
+    })
+    assert resp.status_code == 200
+    data = resp.json()
+    assert data["planner"] == "deterministic"
+    assert "adjustments.apply" in _ops(data["steps"])
+
+
+def test_style_guide_serves_recolor_and_looks_rules():
+    body = guide.as_json()
+    assert "recolor" in body["rules"]
+    assert "looks" in body["rules"]
+    assert {lk["id"] for lk in body["looks"]} >= {
+        "wes_anderson", "film_noir", "cyberpunk", "vintage_kodachrome",
+        "studio_ghibli",
+    }
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(pytest.main([__file__, "-q"]))
diff --git a/tests/test_shutdown_signal.py b/tests/test_shutdown_signal.py
new file mode 100644
index 000000000..2858e9e01
--- /dev/null
+++ b/tests/test_shutdown_signal.py
@@ -0,0 +1,51 @@
+"""Graceful-shutdown signalling tests (HARNESS-owned).
+
+SSE / streaming responses never complete on their own, so uvicorn's graceful
+shutdown would wait for an open browser stream up to the whole
+``timeout_graceful_shutdown`` window. src.shutdown is a process-wide flag that
+the SIGTERM/SIGINT handler flips and every streaming generator checks, so a
+restart ends open streams promptly while ordinary in-flight requests still
+finish.
+"""
+from pathlib import Path
+
+from src import shutdown
+
+ROOT = Path(__file__).resolve().parent.parent
+
+
+def test_request_shutdown_is_sticky_and_resettable():
+    shutdown.reset()
+    try:
+        assert shutdown.is_shutting_down() is False
+        shutdown.request_shutdown()
+        assert shutdown.is_shutting_down() is True
+        # idempotent
+        shutdown.request_shutdown()
+        assert shutdown.is_shutting_down() is True
+    finally:
+        shutdown.reset()
+    assert shutdown.is_shutting_down() is False
+
+
+def test_app_installs_its_own_shutdown_handler():
+    src = (ROOT / "app.py").read_text(encoding="utf-8")
+    # This uvicorn version has no install_signal_handlers kwarg, so app.py wraps
+    # server.handle_exit (which capture_signals wires SIGINT/SIGTERM to).
+    assert "install_signal_handlers=False" not in src
+    assert "server.handle_exit = _handle_shutdown_signal" in src
+    assert "_shutdown.request_shutdown()" in src
+    assert "server.run()" in src
+
+
+def test_streaming_generators_check_the_shutdown_flag():
+    # editor bridge SSE + chat stream/resume + research + email events + shell.
+    for rel in (
+        "routes/editor_agent_routes.py",
+        "routes/chat_routes.py",
+        "routes/research/research_routes.py",
+        "routes/email/email_routes.py",
+        "routes/shell_routes.py",
+    ):
+        src = (ROOT / rel).read_text(encoding="utf-8")
+        assert "_shutdown.is_shutting_down()" in src, rel

From 6cf676dfe29fc6d43e3abd012f4f36d58edcbc3d Mon Sep 17 00:00:00 2001
From: pewdiepie-archdaemon <pewdiepie-archdaemon@users.noreply.github.com>
Date: Thu, 15 Oct 2026 12:02:06 +0000
Subject: [PATCH 22/53] feat(email): export selected messages as email or PDF

---
 routes/email/email_routes.py             | 190 ++++++++++++++++++++++-
 static/js/emailLibrary/index.js          | 165 +++++++++++++++++++-
 static/js/emailLibrary/menus.js          |  46 +++++-
 tests/test_email_library_bulk_actions.py |  31 +++-
 4 files changed, 415 insertions(+), 17 deletions(-)

diff --git a/routes/email/email_routes.py b/routes/email/email_routes.py
index 172790a6c..99b429f6e 100644
--- a/routes/email/email_routes.py
+++ b/routes/email/email_routes.py
@@ -26,12 +26,14 @@ import re
 import html
 import io
 import zipfile
-from urllib.parse import parse_qs, unquote, urlparse
+from urllib.parse import parse_qs, quote, unquote, urlparse
 from html.parser import HTMLParser as _HTMLParser
 import logging
 import uuid
-from datetime import datetime
+from datetime import datetime, timezone
 from pathlib import Path
+from email.message import EmailMessage
+from email import policy as email_policy
 
 from email.mime.text import MIMEText
 from email.mime.multipart import MIMEMultipart
@@ -4185,6 +4187,190 @@ def setup_email_routes():
             headers={"Content-Disposition": f'attachment; filename="{zip_name}"'},
         )
 
+    @router.post("/messages-download-bulk")
+    async def download_bulk_messages(request: Request, owner: str = Depends(require_owner)):
+        """Export selected original email messages as .eml files in a ZIP."""
+        try:
+            payload = await request.json()
+        except Exception:
+            raise HTTPException(status_code=400, detail="Invalid JSON body")
+        messages = payload.get("messages") if isinstance(payload, dict) else None
+        if not isinstance(messages, list) or not messages:
+            raise HTTPException(status_code=400, detail="No emails selected")
+        if len(messages) > 250:
+            raise HTTPException(status_code=400, detail="Too many emails selected")
+
+        category = str(payload.get("category") or "selected").strip().lower()
+        category = re.sub(r"[^a-z0-9_-]+", "-", category).strip("-") or "selected"
+        selected_dates = sorted({
+            str(row.get("date") or "").strip()
+            for row in messages if isinstance(row, dict)
+            and re.fullmatch(r"\d{4}-\d{2}-\d{2}", str(row.get("date") or "").strip())
+        })
+        date_span = ""
+        if selected_dates:
+            date_span = selected_dates[0] if len(selected_dates) == 1 else f"{selected_dates[0]} - {selected_dates[-1]}"
+        export_folder = f"emails-{category}" + (f" ({date_span})" if date_span else "")
+
+        zip_buf = io.BytesIO()
+        used_names: set[str] = set()
+        exported = 0
+        skipped = 0
+        single_export: tuple[str, bytes] | None = None
+
+        def _email_filename(row: dict, uid: str) -> str:
+            date = str(row.get("date") or "").strip()
+            date = date if re.fullmatch(r"\d{4}-\d{2}-\d{2}", date) else ""
+            subject = str(row.get("subject") or "email").strip()
+            subject = re.sub(r'[<>:"/\\|?*\x00-\x1f\x7f]+', "_", subject)
+            subject = re.sub(r"\s+", " ", subject).strip(" .")[:100] or "email"
+            safe_uid = re.sub(r"[^A-Za-z0-9_-]+", "_", uid).strip("_") or "message"
+            prefix = f"{date} - " if date else ""
+            return _safe_attachment_zip_name(f"{prefix}{subject} - {safe_uid}.eml", "email.eml")
+
+        def _fixture_message_bytes(fixture: dict, uid: str, folder: str) -> bytes:
+            msg = EmailMessage()
+            sender_name = str(fixture.get("from_name") or "").strip()
+            sender_address = str(fixture.get("from_address") or "").strip()
+            sender = email.utils.formataddr((sender_name, sender_address)) if sender_address else sender_name
+            for key, value in (
+                ("From", sender),
+                ("To", fixture.get("to") or owner),
+                ("Subject", fixture.get("subject") or "(no subject)"),
+                ("Message-ID", fixture.get("message_id") or f"<fixture-{uid}@mail.local>"),
+            ):
+                clean_value = re.sub(r"[\r\n]+", " ", str(value or "")).strip()
+                if clean_value:
+                    msg[key] = clean_value
+            raw_date = str(fixture.get("date") or "").strip()
+            if raw_date:
+                try:
+                    parsed_date = datetime.fromisoformat(raw_date.replace("Z", "+00:00"))
+                    if parsed_date.tzinfo is None:
+                        parsed_date = parsed_date.replace(tzinfo=timezone.utc)
+                except Exception:
+                    try:
+                        parsed_date = email.utils.parsedate_to_datetime(raw_date)
+                    except Exception:
+                        parsed_date = None
+                if parsed_date is not None:
+                    msg["Date"] = email.utils.format_datetime(parsed_date)
+            msg.set_content(str(fixture.get("body") or ""))
+            for attachment in fixture.get("attachments") or []:
+                try:
+                    index = int(attachment.get("index"))
+                    source = _fixture_attachment_source(uid, index, owner, folder)
+                    if not source:
+                        continue
+                    _row, raw_attachment = source
+                    content_type = str(raw_attachment.get("content_type") or "application/octet-stream")
+                    maintype, _, subtype = content_type.partition("/")
+                    if not subtype:
+                        maintype, subtype = "application", "octet-stream"
+                    msg.add_attachment(
+                        str(raw_attachment.get("content") or "").encode("utf-8"),
+                        maintype=maintype,
+                        subtype=subtype,
+                        filename=str(raw_attachment.get("filename") or attachment.get("filename") or f"attachment-{index}"),
+                    )
+                except Exception:
+                    logger.debug("Skipping malformed fixture email attachment uid=%s", uid, exc_info=True)
+            return msg.as_bytes(policy=email_policy.SMTP)
+
+        remote_groups: dict[tuple[str | None, str], dict[str, tuple[str, dict]]] = {}
+        with zipfile.ZipFile(zip_buf, "w", compression=zipfile.ZIP_DEFLATED) as zf:
+            for row in messages:
+                if not isinstance(row, dict):
+                    skipped += 1
+                    continue
+                uid = str(row.get("uid") or "").strip()
+                if not uid:
+                    skipped += 1
+                    continue
+                folder = str(row.get("folder") or "INBOX").strip() or "INBOX"
+                account_id = str(row.get("account_id") or row.get("account") or "").strip() or None
+                fixture = _fixture_email_read(uid, folder, owner)
+                if fixture is not None and not fixture.get("error"):
+                    filename = _email_filename(row, uid)
+                    unique_name = filename
+                    suffix = 2
+                    while unique_name.lower() in used_names:
+                        unique_name = f"{Path(filename).stem}-{suffix}.eml"
+                        suffix += 1
+                    used_names.add(unique_name.lower())
+                    message_bytes = _fixture_message_bytes(fixture, uid, folder)
+                    zf.writestr(f"{export_folder}/{unique_name}", message_bytes)
+                    single_export = (unique_name, message_bytes)
+                    exported += 1
+                    continue
+                if not re.fullmatch(r"\d+", uid):
+                    skipped += 1
+                    continue
+                group = remote_groups.setdefault((account_id, folder), {})
+                group.setdefault(uid, (_email_filename(row, uid), row))
+
+            # Fetch original RFC822 data in batches and store it byte-for-byte.
+            for (account_id, folder), rows_by_uid in remote_groups.items():
+                rows = list(rows_by_uid.items())
+                try:
+                    with _imap(account_id, owner=owner) as conn:
+                        conn.select(_q(folder), readonly=True)
+                        for batch_start in range(0, len(rows), 20):
+                            batch = rows[batch_start:batch_start + 20]
+                            wanted = {uid: filename for uid, (filename, _row) in batch}
+                            uid_set = ",".join(wanted).encode()
+                            status, msg_data = _imap_uid_fetch(conn, uid_set, "(UID RFC822)")
+                            if status != "OK" or not msg_data:
+                                skipped += len(batch)
+                                continue
+                            found: set[str] = set()
+                            for meta, raw_message in _group_uid_fetch_records(msg_data):
+                                uid = _uid_from_fetch_meta(meta)
+                                if uid not in wanted or not raw_message:
+                                    continue
+                                filename = wanted[uid]
+                                unique_name = filename
+                                suffix = 2
+                                while unique_name.lower() in used_names:
+                                    unique_name = f"{Path(filename).stem}-{suffix}.eml"
+                                    suffix += 1
+                                used_names.add(unique_name.lower())
+                                message_bytes = bytes(raw_message)
+                                zf.writestr(f"{export_folder}/{unique_name}", message_bytes)
+                                single_export = (unique_name, message_bytes)
+                                found.add(uid)
+                                exported += 1
+                            skipped += len(batch) - len(found)
+                except Exception as exc:
+                    skipped += len(rows)
+                    logger.warning("Bulk email export skipped mailbox folder=%s account=%s count=%s: %s", folder, account_id, len(rows), exc)
+
+        if exported <= 0:
+            raise HTTPException(status_code=404, detail="No selected emails could be exported")
+        if len(messages) == 1 and single_export:
+            filename, message_bytes = single_export
+            return StreamingResponse(
+                io.BytesIO(message_bytes),
+                media_type="message/rfc822",
+                headers={
+                    "Content-Disposition": f"attachment; filename=\"email.eml\"; filename*=UTF-8''{quote(filename, safe='')}",
+                    "X-Exported-Emails": "1",
+                    "X-Skipped-Emails": str(skipped),
+                },
+            )
+        zip_buf.seek(0)
+        zip_name = _safe_attachment_zip_name(f"{export_folder}.zip", "selected-emails.zip")
+        logger.info("Bulk email export complete owner=%s selected=%s exported=%s skipped=%s", owner, len(messages), exported, skipped)
+        return StreamingResponse(
+            zip_buf,
+            media_type="application/zip",
+            headers={
+                "Content-Disposition": f'attachment; filename="{zip_name}"',
+                "X-Exported-Emails": str(exported),
+                "X-Skipped-Emails": str(skipped),
+            },
+        )
+
     @router.get("/inline-image/{uid}")
     async def inline_image(
         uid: str,
diff --git a/static/js/emailLibrary/index.js b/static/js/emailLibrary/index.js
index 82f76b0c5..7de542fe8 100644
--- a/static/js/emailLibrary/index.js
+++ b/static/js/emailLibrary/index.js
@@ -1122,7 +1122,130 @@ function _filenameFromContentDisposition(header) {
   return bare ? bare[1].trim() : '';
 }
 
-export async function _exportSelectedAttachments() {
+let _emailHtml2PdfReady = null;
+async function _loadEmailHtml2Pdf() {
+  if (window.html2pdf) return;
+  if (!_emailHtml2PdfReady) {
+    _emailHtml2PdfReady = new Promise((resolve, reject) => {
+      const script = document.createElement('script');
+      script.src = '/static/lib/html2pdf.bundle.min.js';
+      script.onload = resolve;
+      script.onerror = () => reject(new Error('Could not load PDF exporter'));
+      document.head.appendChild(script);
+    });
+  }
+  try {
+    await _emailHtml2PdfReady;
+  } catch (error) {
+    _emailHtml2PdfReady = null;
+    throw error;
+  }
+}
+
+async function _downloadSelectedEmailPdf(messages) {
+  if (messages.length > 20) throw new Error('PDF export supports up to 20 emails at a time');
+  await _loadEmailHtml2Pdf();
+
+  const loaded = new Array(messages.length);
+  let nextIndex = 0;
+  const readWorker = async () => {
+    while (nextIndex < messages.length) {
+      const index = nextIndex++;
+      const message = messages[index];
+      const account = message.account_id ? `&account_id=${encodeURIComponent(message.account_id)}` : '';
+      const url = `${API_BASE}/api/email/read/${encodeURIComponent(message.uid)}?folder=${encodeURIComponent(message.folder || 'INBOX')}${account}&mark_seen=false&full=true`;
+      const response = await fetch(url, { credentials: 'same-origin' });
+      if (!response.ok) throw new Error(`Could not load "${message.subject || 'email'}" (HTTP ${response.status})`);
+      const data = await response.json();
+      if (data?.error) throw new Error(data.error);
+      loaded[index] = { message, data };
+    }
+  };
+  await Promise.all(Array.from({ length: Math.min(4, messages.length) }, readWorker));
+
+  const page = document.createElement('div');
+  page.className = 'email-export-pdf';
+  page.style.cssText = 'width:794px;box-sizing:border-box;padding:38px;background:#fff;color:#171717;font:12px/1.55 Arial,Helvetica,sans-serif;';
+  const style = document.createElement('style');
+  style.textContent = `
+    .email-export-pdf-message { page-break-after: always; break-after: page; }
+    .email-export-pdf-message:last-child { page-break-after: auto; break-after: auto; }
+    .email-export-pdf-message h1 { margin: 0 0 18px; font-size: 20px; line-height: 1.3; overflow-wrap: anywhere; }
+    .email-export-pdf-fields { margin: 0 0 20px; padding: 0 0 14px; border-bottom: 1px solid #d8d8d8; }
+    .email-export-pdf-field { display: flex; gap: 10px; margin: 3px 0; overflow-wrap: anywhere; }
+    .email-export-pdf-label { width: 54px; flex: 0 0 54px; color: #666; }
+    .email-export-pdf-body { overflow-wrap: anywhere; word-break: break-word; }
+    .email-export-pdf-body img { max-width: 100%; }
+    .email-export-pdf-body a { color: #135f9b; text-decoration: underline; }
+    .email-export-pdf-body blockquote { margin-left: 12px; padding-left: 10px; border-left: 2px solid #ccc; color: #555; }
+    .email-export-pdf-body pre { white-space: pre-wrap; }
+  `;
+  page.appendChild(style);
+
+  const addField = (parent, label, value) => {
+    if (!value) return;
+    const row = document.createElement('div');
+    row.className = 'email-export-pdf-field';
+    const labelEl = document.createElement('span');
+    labelEl.className = 'email-export-pdf-label';
+    labelEl.textContent = label;
+    const valueEl = document.createElement('span');
+    valueEl.textContent = value;
+    row.append(labelEl, valueEl);
+    parent.appendChild(row);
+  };
+
+  for (const { message, data } of loaded) {
+    const article = document.createElement('article');
+    article.className = 'email-export-pdf-message';
+    const subject = String(data.subject || message.subject || '(no subject)');
+    const title = document.createElement('h1');
+    title.textContent = subject;
+    article.appendChild(title);
+
+    const fields = document.createElement('div');
+    fields.className = 'email-export-pdf-fields';
+    const from = data.from_name && data.from_address
+      ? `${data.from_name} <${data.from_address}>`
+      : data.from_name || data.from_address;
+    addField(fields, 'From', from);
+    addField(fields, 'To', data.to);
+    addField(fields, 'Cc', data.cc);
+    addField(fields, 'Date', data.date_display || data.date || message.date);
+    article.appendChild(fields);
+
+    const body = document.createElement('div');
+    body.className = 'email-export-pdf-body';
+    const safeBody = new DOMParser().parseFromString(_safeRenderEmailBody(data), 'text/html');
+    safeBody.querySelectorAll('img').forEach(img => {
+      const placeholder = safeBody.createElement('span');
+      placeholder.textContent = img.alt ? `[Image: ${img.alt}]` : '[Inline image omitted]';
+      img.replaceWith(placeholder);
+    });
+    body.innerHTML = safeBody.body.innerHTML;
+    body.querySelectorAll('details').forEach(detail => { detail.open = true; });
+    article.appendChild(body);
+    page.appendChild(article);
+  }
+
+  const safeBaseName = messages.length === 1
+    ? String(loaded[0]?.data?.subject || messages[0]?.subject || 'email').replace(/[^\p{L}\p{N} ._-]+/gu, '_').trim().slice(0, 100) || 'email'
+    : 'selected-emails';
+  try {
+    await window.html2pdf().set({
+      margin: 10,
+      filename: `${safeBaseName}.pdf`,
+      image: { type: 'jpeg', quality: 0.92 },
+      html2canvas: { scale: 1.6, useCORS: false, backgroundColor: '#fff' },
+      jsPDF: { unit: 'mm', format: 'a4', orientation: 'portrait' },
+      pagebreak: { mode: ['css', 'legacy'] },
+    }).from(page).save();
+  } finally {
+    page.remove();
+  }
+}
+
+async function _exportSelectedBundle(kind) {
   const messages = _selectedEmailExportPayload();
   if (!messages.length) {
     showToast('Select emails first');
@@ -1150,8 +1273,15 @@ export async function _exportSelectedAttachments() {
     if (deleteBtn) deleteBtn.disabled = true;
     if (cancelBtn) cancelBtn.disabled = true;
     if (selectAll) selectAll.disabled = true;
-    if (countEl) countEl.textContent = `Exporting attachments from ${messages.length}…`;
-    const res = await fetch(`${API_BASE}/api/email/attachments-download-bulk`, {
+    const isEmailExport = kind === 'emails';
+    const isPdfExport = kind === 'pdf';
+    if (countEl) countEl.textContent = `${isPdfExport ? 'Creating PDF' : 'Exporting'} ${isPdfExport ? 'from' : isEmailExport ? 'emails from' : 'attachments from'} ${messages.length}…`;
+    if (isPdfExport) {
+      await _downloadSelectedEmailPdf(messages);
+      showToast(`Exported ${messages.length} email${messages.length === 1 ? '' : 's'} as PDF`);
+      return;
+    }
+    const res = await fetch(`${API_BASE}/api/email/${isEmailExport ? 'messages' : 'attachments'}-download-bulk`, {
       method: 'POST',
       credentials: 'same-origin',
       headers: { 'Content-Type': 'application/json' },
@@ -1169,12 +1299,21 @@ export async function _exportSelectedAttachments() {
       throw new Error(detail || `HTTP ${res.status}`);
     }
     const blob = await res.blob();
-    const filename = _filenameFromContentDisposition(res.headers.get('Content-Disposition')) || 'selected-email-attachments.zip';
+    const filename = _filenameFromContentDisposition(res.headers.get('Content-Disposition'))
+      || (isEmailExport
+        ? (messages.length === 1 ? 'selected-email.eml' : 'selected-emails.zip')
+        : 'selected-email-attachments.zip');
     _downloadBlob(blob, filename);
-    showToast(`Exported attachments from ${messages.length} selected email${messages.length === 1 ? '' : 's'}`);
+    const exported = Number(res.headers.get('X-Exported-Emails')) || messages.length;
+    const skipped = Number(res.headers.get('X-Skipped-Emails')) || 0;
+    showToast(skipped
+      ? `Exported ${exported} email${exported === 1 ? '' : 's'}; ${skipped} unavailable`
+      : isEmailExport
+        ? `Exported ${exported} email${exported === 1 ? '' : 's'} as ${exported === 1 ? 'an .eml file' : '.eml files'}`
+        : `Exported attachments from ${messages.length} selected email${messages.length === 1 ? '' : 's'}`);
   } catch (err) {
-    console.error('Failed to export selected email attachments:', err);
-    showToast(err?.message || 'Failed to export attachments');
+    console.error(`Failed to export selected email ${kind}:`, err);
+    showToast(err?.message || (kind === 'emails' ? 'Failed to export emails' : 'Failed to export attachments'));
   } finally {
     if (busySpinner) busySpinner.destroy();
     if (actionsBtn) {
@@ -1190,6 +1329,18 @@ export async function _exportSelectedAttachments() {
   }
 }
 
+export async function _exportSelectedEmails() {
+  return _exportSelectedBundle('emails');
+}
+
+export async function _exportSelectedEmailPdf() {
+  return _exportSelectedBundle('pdf');
+}
+
+export async function _exportSelectedAttachments() {
+  return _exportSelectedBundle('attachments');
+}
+
 // URL-suffix helper — appends &account_id=... when an account is actively selected.
 // Every email route call in this file goes through here so switching accounts
 // is a single-variable flip.
diff --git a/static/js/emailLibrary/menus.js b/static/js/emailLibrary/menus.js
index da859ecad..3b03f4aba 100644
--- a/static/js/emailLibrary/menus.js
+++ b/static/js/emailLibrary/menus.js
@@ -25,6 +25,8 @@ import {
   _animateEmailCardRemoval,
   _clearDoneResponseTagsLocal,
   _emailMutationQuery,
+  _exportSelectedEmailPdf,
+  _exportSelectedEmails,
   _exportSelectedAttachments,
   _findSiblingEmailCard,
   _fitEmailDropdown,
@@ -585,7 +587,10 @@ export function _showBulkActionsMenu(anchor) {
   const _unreadIco = '<svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="10"/><circle cx="12" cy="12" r="3" fill="currentColor"/></svg>';
   const _doneIco = '<svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"><polyline points="20 6 9 17 4 12"/></svg>';
   const _exportIco = '<svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4"/><polyline points="7 10 12 15 17 10"/><line x1="12" y1="15" x2="12" y2="3"/></svg>';
+  const _emailIco = '<svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="2" y="4" width="20" height="16" rx="2"/><path d="m22 7-8.97 5.7a1.94 1.94 0 0 1-2.06 0L2 7"/></svg>';
+  const _pdfIco = '<svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M14 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8z"/><polyline points="14 2 14 8 20 8"/><path d="M8 15h8M8 18h5"/></svg>';
   const items = [
+    { label: 'Export Emails', icon: _exportIco, submenu: true },
     { label: 'Export Attachments', icon: _exportIco, action: () => _exportSelectedAttachments() },
     { label: 'Done', icon: _doneIco, action: () => _bulkAction('done') },
     { label: 'Mark Read', icon: _readIco, action: () => _bulkAction('read') },
@@ -594,8 +599,45 @@ export function _showBulkActionsMenu(anchor) {
   for (const a of items) {
     const it = document.createElement('div');
     it.className = 'dropdown-item-compact' + (a.danger ? ' dropdown-item-danger' : '');
-    it.innerHTML = `<span class="dropdown-icon">${a.icon}</span><span>${a.label}</span>`;
-    it.addEventListener('click', (e) => { e.stopPropagation(); close(); a.action(); });
+    it.className += a.submenu ? ' email-bulk-submenu-trigger' : '';
+    it.innerHTML = `<span class="dropdown-icon">${a.icon}</span><span>${a.label}</span>${a.submenu ? '<span style="margin-left:auto;opacity:0.55;">›</span>' : ''}`;
+    it.addEventListener('click', (e) => {
+      e.stopPropagation();
+      if (a.submenu) {
+        dropdown.replaceChildren();
+        const back = document.createElement('div');
+        back.className = 'dropdown-item-compact email-bulk-submenu-back';
+        back.innerHTML = '<span style="opacity:.65;margin-right:4px;">‹</span><span>Export Emails</span>';
+        back.addEventListener('click', (ev) => {
+          ev.stopPropagation();
+          close();
+          _showBulkActionsMenu(anchor);
+        });
+        dropdown.appendChild(back);
+        const divider = document.createElement('div');
+        divider.className = 'dropdown-divider';
+        dropdown.appendChild(divider);
+        const options = [
+          { label: 'Email file (.eml)', icon: _emailIco, action: _exportSelectedEmails },
+          { label: 'PDF', icon: _pdfIco, action: _exportSelectedEmailPdf },
+        ];
+        for (const option of options) {
+          const child = document.createElement('div');
+          child.className = 'dropdown-item-compact';
+          child.innerHTML = `<span class="dropdown-icon">${option.icon}</span><span>${option.label}</span>`;
+          child.addEventListener('click', (ev) => {
+            ev.stopPropagation();
+            close();
+            option.action();
+          });
+          dropdown.appendChild(child);
+        }
+        _fitEmailDropdown(dropdown, anchor.getBoundingClientRect());
+        return;
+      }
+      close();
+      a.action();
+    });
     dropdown.appendChild(it);
   }
   // Mobile-only Cancel — matches the per-card and sidebar dropdowns.
diff --git a/tests/test_email_library_bulk_actions.py b/tests/test_email_library_bulk_actions.py
index 4e9930678..64e3f46c1 100644
--- a/tests/test_email_library_bulk_actions.py
+++ b/tests/test_email_library_bulk_actions.py
@@ -41,18 +41,18 @@ def test_email_bulk_read_unread_checks_backend_success_before_syncing_cache():
     assert "_libCacheWriteBack()" in src
 
 
-def test_email_bulk_export_attachments_is_ui_only_selected_context():
+def test_email_bulk_exports_messages_and_attachments_from_selected_context():
     frontend = email_library_source()
     backend = _EMAIL_ROUTES.read_text(encoding="utf-8")
-    export_src = frontend[
-        frontend.index("async function _exportSelectedAttachments()"):
-        frontend.index("\n}\n\n// URL-suffix helper", frontend.index("async function _exportSelectedAttachments()")) + 3
-    ]
+    export_src = _function_source("_exportSelectedBundle")
     payload_src = _function_source("_selectedEmailExportPayload")
 
+    assert "Export Emails" in frontend
+    assert "Email file (.eml)" in frontend
+    assert "_exportSelectedEmailPdf" in frontend
     assert "Export Attachments" in frontend
     assert "All in view" in frontend
-    assert "/api/email/attachments-download-bulk" in export_src
+    assert "${isEmailExport ? 'messages' : 'attachments'}-download-bulk" in export_src
     assert "method: 'POST'" in export_src
     assert "res.blob()" in export_src
     assert "account_id: String(em.account_id || state._libAccountId || '')" in payload_src
@@ -63,6 +63,25 @@ def test_email_bulk_export_attachments_is_ui_only_selected_context():
     assert "_fixture_email_read(uid, folder, owner)" in backend
     assert "_is_likely_signature_image_attachment(att)" in backend
 
+    assert '@router.post("/messages-download-bulk")' in backend
+    assert '"(UID RFC822)"' in backend
+    assert "msg.as_bytes(policy=email_policy.SMTP)" in backend
+    assert 'media_type="message/rfc822"' in backend
+    assert '"X-Exported-Emails"' in backend
+
+
+def test_email_bulk_pdf_export_reads_without_marking_read_and_sanitizes_body():
+    frontend = email_library_source()
+    pdf_src = _function_source("_downloadSelectedEmailPdf")
+    menu_src = js_function_source("_showBulkActionsMenu", frontend)
+
+    assert "mark_seen=false&full=true" in pdf_src
+    assert "_safeRenderEmailBody(data)" in pdf_src
+    assert "new DOMParser()" in pdf_src
+    assert "window.html2pdf()" in pdf_src
+    assert "up to 20 emails" in pdf_src
+    assert "PDF" in menu_src
+
 
 def test_fixture_tag_filter_supports_receipt_tag_flow():
     backend = _EMAIL_ROUTES.read_text(encoding="utf-8")

From b97c1ee50fd1d83c0f1d8c21bc5f13f9be7f4beb Mon Sep 17 00:00:00 2001
From: RaresKeY <158580472+RaresKeY@users.noreply.github.com>
Date: Thu, 15 Oct 2026 15:31:56 +0000
Subject: [PATCH 23/53] docs(maintainers): refine handbook and remove code of
 conduct

---
 CODE_OF_CONDUCT.md                       | 33 ------------------------
 docs/maintainers/README.md               |  2 --
 docs/maintainers/documentation.md        |  1 -
 docs/maintainers/product-and-features.md | 14 ++++++----
 docs/maintainers/review-playbook.md      |  7 ++++-
 docs/maintainers/testing-and-releases.md |  6 +++++
 6 files changed, 21 insertions(+), 42 deletions(-)
 delete mode 100644 CODE_OF_CONDUCT.md

diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
deleted file mode 100644
index f79c0be5b..000000000
--- a/CODE_OF_CONDUCT.md
+++ /dev/null
@@ -1,33 +0,0 @@
-# Code of Conduct
-
-Odysseus project spaces should remain respectful, useful, and focused on the project. Technical disagreement is welcome; personal hostility is not.
-
-## Expected conduct
-
-- Be professional and constructive. Critique ideas, evidence, and implementations, not people.
-- Treat people fairly regardless of experience, background, identity, or role.
-- Explain disagreement with reproducible evidence when possible, and acknowledge uncertainty.
-- Keep project spaces relevant to Odysseus, software engineering, AI, and project work.
-- Help de-escalate discussions that stop being productive, and respect moderation decisions while they are reviewed.
-
-## Unacceptable conduct
-
-- Harassment, discrimination, threats, intimidation, or personal attacks.
-- Trolling, baiting, sustained disruption, or targeted hostility.
-- Doxxing, publishing private correspondence or personal information without permission.
-- Political campaigning, ideological or culture-war disputes, and repeated highly polarizing arguments unrelated to project work.
-- Retaliation against someone who reports a concern in good faith.
-
-These expectations apply to everyone, including administrators and maintainers. Disagreeing about project decisions or criticizing code in good faith is not a violation.
-
-## Scope
-
-This applies across official Odysseus spaces, including GitHub, Matrix, Plane, maintainer channels, and other project-managed community spaces, and to representatives acting on the project's behalf.
-
-## Reporting and enforcement
-
-Report conduct concerns to a Repository Admin or Organization Owner using an appropriate project communication channel. For sensitive concerns, ask for a private channel rather than posting personal details publicly. Security vulnerabilities follow [SECURITY.md](SECURITY.md), not the public conduct-reporting process.
-
-Maintainers may redirect or pause unproductive conversations. Repository Admins handle serious moderation or access decisions, consulting others when appropriate and avoiding conflicts of interest.
-
-Actions may include a reminder, warning, temporary restriction, removal from project spaces, or removal of elevated access. Responses should be proportionate to the behavior and circumstances, with privacy respected and an opportunity to provide context where practical. Retaliation is prohibited.
diff --git a/docs/maintainers/README.md b/docs/maintainers/README.md
index aae60d4df..bd5e93f24 100644
--- a/docs/maintainers/README.md
+++ b/docs/maintainers/README.md
@@ -36,5 +36,3 @@ Maintainers own the changes they take on, including validation, regression preve
 Important product-direction decisions go through the Product Owner. Maintainers retain responsibility for feasibility, implementation, maintainability, and security.
 
 AI coding or review agents can help collect evidence, test hypotheses, and prepare changes, but they are not the qualified human reviewer required for high-risk changes. A maintainer must inspect and accept the evidence.
-
-Project spaces follow the [Code of Conduct](../../CODE_OF_CONDUCT.md).
diff --git a/docs/maintainers/documentation.md b/docs/maintainers/documentation.md
index 0057305f0..91bb5b919 100644
--- a/docs/maintainers/documentation.md
+++ b/docs/maintainers/documentation.md
@@ -16,7 +16,6 @@ Keep root documents easy to find:
 - `README.md`
 - `CONTRIBUTING.md`
 - `SECURITY.md`
-- `CODE_OF_CONDUCT.md`
 
 Not every named directory exists today; do not invent a parallel documentation store just to match this map.
 
diff --git a/docs/maintainers/product-and-features.md b/docs/maintainers/product-and-features.md
index 71b6cf686..b120bd806 100644
--- a/docs/maintainers/product-and-features.md
+++ b/docs/maintainers/product-and-features.md
@@ -4,11 +4,15 @@ Pewds is the Product Owner for Odysseus and has final authority over product dir
 
 ## Which changes require product approval?
 
-**Product Owner approval before implementation:** new features and material changes to product direction or behavior.
+**Product Owner approval before implementation:** substantial new features, changes to product direction, and product changes that are hard to reverse.
 
-**No separate product approval by default:** bug fixes, security fixes, maintenance, tests, CI, documentation, and internal refactors, unless they materially change product behavior or direction.
+**No separate product approval by default:** bug fixes, security fixes, maintenance, tests, CI, documentation, internal refactors, and small, reversible product changes within existing direction.
 
-A security or reliability fix that changes behavior should state the user-visible impact and seek product input when its direction is genuinely ambiguous. Urgent containment need not wait if it preserves existing product intent.
+Maintainers may make those smaller product decisions. Pewds can ask for changes or a rollback; the maintainer owns safe rollback or recovery.
+
+### Urgent security and reliability fixes
+
+Urgent fixes or containment may proceed without prior product approval, even if behavior temporarily changes. Keep the change to what stops the immediate problem, notify Pewds promptly, and record the reason and rollback or recovery plan. Agree on any lasting product-direction change with Pewds afterwards. Normal high-risk review and repository checks still apply.
 
 ## Product Owner initiated
 
@@ -25,7 +29,7 @@ A Product Owner proposal is already product-approved; it is not automatically te
 
 ```text
 Feature proposal
-    -> Product Owner accepts / rejects
+    -> Product Owner accepts / rejects, where approval is required
     -> technical feasibility
     -> plan and implementation
     -> risk-based review and validation
@@ -39,4 +43,4 @@ The Product Owner decides **what belongs in Odysseus**. Maintainers decide **how
 
 A rejected or out-of-scope feature can be maintained independently in a contributor's fork.
 
-If the Product Owner is unavailable, new product-direction decisions wait unless that authority was explicitly delegated. Urgent security and reliability corrections that do not redefine product direction may continue under normal review rules.
+If the Product Owner is unavailable, work requiring prior product approval waits unless authority was explicitly delegated. Smaller decisions and urgent fixes follow the rules above.
diff --git a/docs/maintainers/review-playbook.md b/docs/maintainers/review-playbook.md
index 77c4357e7..e9f0e6f99 100644
--- a/docs/maintainers/review-playbook.md
+++ b/docs/maintainers/review-playbook.md
@@ -4,8 +4,11 @@ Use this as a **repeatable review method**, not as an extra organizational appro
 
 No single checklist replaces engineering judgment. Increase depth with risk.
 
-## 1. Establish provenance and scope
+## 1. Understand the PR and establish its review gates
 
+- Establish the problem, what the PR fundamentally proposes, and why the approach makes sense.
+- Check product direction, architecture fit, and scope before detailed review.
+- Write down the questions the review must answer, the evidence needed, and what would block further review or approval.
 - Confirm repository, source fork, target branch (`dev`), exact **HEAD SHA**, and current base.
 - Review the full effective diff, commit history, issue, prior feedback, and related upstream changes.
 - Confirm the branch is mergeable against the **current** `dev`, not an older local snapshot.
@@ -40,6 +43,8 @@ For substantive or ambiguous work, ask the contributor or prepare a clearly sepa
 
 ## 4. Build an evidence record
 
+Run contributor code under the [runtime isolation rules](testing-and-releases.md#runtime-isolation).
+
 Useful evidence includes:
 
 - Pre-fix reproduction, expected outcome, and actual outcome.
diff --git a/docs/maintainers/testing-and-releases.md b/docs/maintainers/testing-and-releases.md
index ce7c1b59b..23ab33853 100644
--- a/docs/maintainers/testing-and-releases.md
+++ b/docs/maintainers/testing-and-releases.md
@@ -4,6 +4,12 @@ Validation must match the actual change, and evidence must state what was **run*
 
 `dev` is the integration and stabilization branch. `main` is the curated release destination. Changes land in `dev`; a release promotes a verified `dev` revision to `main`.
 
+## Runtime isolation
+
+Run contributor-controlled tests, builds, installs, and repros in an isolated, secretless environment. Use disposable containers or microVMs where appropriate, with no credentials, sensitive host files, production data, or host/container-management sockets exposed. If safe isolation is unavailable, record the check as not run.
+
+Agents may use a skill for the maintainer's preferred environment and handling; the same isolation requirements apply.
+
 ## Change validation
 
 - Run focused tests that cover the modified behavior and failure cases.

From 55b5b7f496887a345c4b1f380a3585672c6ebae9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?L=C3=A9o?= <leograndcontact@gmail.com>
Date: Thu, 15 Oct 2026 18:01:20 +0200
Subject: [PATCH 24/53] docs(maintainers): list website/ in the docs map and
 align CONTRIBUTING

Setup, configuration and deployment docs live in website/, which is
published as the docs site, but the map sent them to /docs and did not
list website/ at all. Add it, and drop the "when those paths are used"
hedge on /specs, which exists.

CODEOWNERS has no rules until #593 settles the per-area map; say so
instead of describing reviewers it does not list.

CONTRIBUTING.md still had a single maintainer curating main, which the
Release Maintainer section replaces. Name the Product Owner's GitHub
account and say where a community proposal starts, matching the
existing issue forms.
---
 CONTRIBUTING.md                          | 2 +-
 docs/maintainers/changes-and-review.md   | 2 +-
 docs/maintainers/documentation.md        | 6 ++++--
 docs/maintainers/product-and-features.md | 4 +++-
 4 files changed, 9 insertions(+), 5 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 2934094d2..8a7160245 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -7,7 +7,7 @@ Thanks for helping. The project is moving quickly, so the best contributions are
 Odysseus has two branches:
 
 - **`dev`** — where all PRs land. Things can be in flux here; the merge button gets used freely.
-- **`main`** — what users run. Curated and tested by the maintainer. Fast-forwarded to a stable `dev` commit at each release.
+- **`main`** — what users run. Curated and tested by the release's [Release Maintainer](docs/maintainers/testing-and-releases.md#release-ownership). Fast-forwarded to a stable `dev` commit at each release.
 
 **Open your PR against `dev`, not `main`.** The GitHub "base" dropdown defaults to `dev`. If you opened a PR against `main` by accident, click "Edit" on the PR and change the base — no rebase needed.
 
diff --git a/docs/maintainers/changes-and-review.md b/docs/maintainers/changes-and-review.md
index fdad31d23..664b2596a 100644
--- a/docs/maintainers/changes-and-review.md
+++ b/docs/maintainers/changes-and-review.md
@@ -43,7 +43,7 @@ A high-risk review should verify the threat or failure model, exact final commit
 
 ## Cross-area changes and CODEOWNERS
 
-Touching multiple areas does **not** automatically require multiple approvals. Consult domain expertise when needed. CODEOWNERS helps identify reviewers and accountable contacts; it is not a blanket approval requirement by itself. See [issue #593](https://github.com/odysseus-dev/odysseus/issues/593) for the ongoing ownership map discussion.
+Touching multiple areas does **not** automatically require multiple approvals. Consult domain expertise when needed. `.github/CODEOWNERS` currently contains no ownership rules; the per-area map is under discussion in [issue #593](https://github.com/odysseus-dev/odysseus/issues/593). Once populated, it helps identify reviewers and accountable contacts; it is not a blanket approval requirement by itself.
 
 ## Validation and UI evidence
 
diff --git a/docs/maintainers/documentation.md b/docs/maintainers/documentation.md
index 91bb5b919..36c88d81d 100644
--- a/docs/maintainers/documentation.md
+++ b/docs/maintainers/documentation.md
@@ -7,8 +7,9 @@ Repository Markdown is the canonical source for project documentation. A public
 | Location | Purpose |
 |---|---|
 | `/design` | Product intent, proposals, and accepted decisions (when those paths are used) |
-| `/specs` | Technical contracts and invariants (when those paths are used) |
-| `/docs` | User, developer, architecture, security, deployment, and maintainer guidance |
+| `/specs` | Technical contracts and invariants |
+| `/website` | User, setup, configuration, and deployment guidance (published as the docs site) |
+| `/docs` | Developer, architecture, security, and maintainer guidance |
 | Root Markdown | Discoverable entry points and policies |
 
 Keep root documents easy to find:
@@ -16,6 +17,7 @@ Keep root documents easy to find:
 - `README.md`
 - `CONTRIBUTING.md`
 - `SECURITY.md`
+- `THREAT_MODEL.md`
 
 Not every named directory exists today; do not invent a parallel documentation store just to match this map.
 
diff --git a/docs/maintainers/product-and-features.md b/docs/maintainers/product-and-features.md
index b120bd806..d41055a7f 100644
--- a/docs/maintainers/product-and-features.md
+++ b/docs/maintainers/product-and-features.md
@@ -1,6 +1,6 @@
 # Product and feature proposals
 
-Pewds is the Product Owner for Odysseus and has final authority over product direction. Maintainers own technical feasibility, implementation, and safety.
+Pewds ([@pewdiepie-archdaemon](https://github.com/pewdiepie-archdaemon)) is the Product Owner for Odysseus and has final authority over product direction. Maintainers own technical feasibility, implementation, and safety.
 
 ## Which changes require product approval?
 
@@ -27,6 +27,8 @@ A Product Owner proposal is already product-approved; it is not automatically te
 
 ## Community or maintainer initiated
 
+Community proposals start as a Feature Request issue. Check [ROADMAP.md](../../ROADMAP.md) and existing issues first; take early ideas to [Discussions](https://github.com/odysseus-dev/odysseus/discussions/categories/ideas).
+
 ```text
 Feature proposal
     -> Product Owner accepts / rejects, where approval is required

From bead6a6797ff466005220002616953334a737db3 Mon Sep 17 00:00:00 2001
From: RaresKeY <158580472+RaresKeY@users.noreply.github.com>
Date: Thu, 15 Oct 2026 16:52:16 +0000
Subject: [PATCH 25/53] docs(specs): routine specifications update

---
 specs/_readme.md                              |  8 +-
 specs/agent-tools.md                          | 96 +++++++++++++++----
 specs/auth-security.md                        | 80 ++++++++--------
 specs/calendar-tasks-notes.md                 | 54 +++++++----
 specs/chat.md                                 | 79 ++++++++-------
 specs/compare.md                              | 16 +++-
 specs/context-building.md                     | 35 +++++--
 specs/cookbook-hwfit.md                       | 18 +++-
 specs/documents-rag-uploads.md                | 79 +++++++--------
 specs/email-contacts.md                       | 53 ++++++----
 specs/frontend.md                             | 54 +++++++----
 specs/gallery-editor-media.md                 | 47 ++++++---
 specs/integrations.md                         | 35 ++++---
 specs/llm-models.md                           | 62 ++++++------
 specs/memory-skills.md                        | 49 ++++++++--
 specs/model-capability-canonical.md           | 61 +++---------
 specs/model-providers/_readme.md              |  3 +-
 specs/model-providers/chatgpt-subscription.md | 45 ++++-----
 specs/model-providers/featherless.md          | 26 +++++
 specs/model-providers/llama-cpp.md            | 27 ++----
 specs/model-quirks.md                         | 29 ++----
 specs/persistence.md                          | 43 +++++----
 specs/research.md                             | 22 ++---
 specs/runtime.md                              | 35 ++++---
 specs/search.md                               | 26 +++--
 specs/settings-admin.md                       | 43 ++++++---
 specs/shell-mcp.md                            | 86 +++++++++++------
 specs/speech.md                               |  6 +-
 specs/testing-devops.md                       | 61 +++++++++---
 29 files changed, 767 insertions(+), 511 deletions(-)
 create mode 100644 specs/model-providers/featherless.md

diff --git a/specs/_readme.md b/specs/_readme.md
index 902c882f4..a8c3a80f0 100644
--- a/specs/_readme.md
+++ b/specs/_readme.md
@@ -1,6 +1,6 @@
 # Specs DocumentMap
 
-Last updated: dev@e71f8ce | 2026-08-25
+Last updated: dev@c74f475 | 2026-10-15
 
 This folder is the compact implementation-truth map for humans and coding agents working on Odysseus. Read this file first, then open only the subsystem specs that match the work.
 
@@ -56,14 +56,14 @@ project documentation.
 - [context-building.md](context-building.md): URL/search/RAG/memory/skills/YouTube/email/tool-output context, untrusted wrapping, unavailable context, intent boundaries.
 - [search.md](search.md): web search providers, ranking, cache/analytics, URL fetch/content extraction, `src.search`/`services.search` split.
 - [documents-rag-uploads.md](documents-rag-uploads.md): uploads, documents, PDF/form handling, personal docs, RAG/vector stores.
-- [memory-skills.md](memory-skills.md): memory storage, semantic memory, skill extraction/formatting, owner isolation.
+- [memory-skills.md](memory-skills.md): memory storage, semantic memory, skill storage/extraction and service-owned audit/evaluation, owner isolation.
 - [research.md](research.md): deep research jobs, synthesis, sources, research library, research UI panel.
-- [calendar-tasks-notes.md](calendar-tasks-notes.md): CalDAV calendars, scheduled tasks, reminders, assistant runs, notes/todos.
+- [calendar-tasks-notes.md](calendar-tasks-notes.md): CalDAV calendars, scheduled tasks, reminders, assistant runs, Notes feature state and lifecycle.
 - [email-contacts.md](email-contacts.md): IMAP/SMTP email, email library, scheduled mail, contacts/CardDAV.
 - [gallery-editor-media.md](gallery-editor-media.md): gallery, generated media, image editor drafts, signatures, emoji/font helpers.
 - [cookbook-hwfit.md](cookbook-hwfit.md): model downloads, local/remote model serving, hardware detection, fit ranking.
 - [speech.md](speech.md): STT and TTS services, routes, settings, optional dependencies.
-- [frontend.md](frontend.md): static SPA, module loading, UI conventions, major JS areas, no-build frontend shape.
+- [frontend.md](frontend.md): static native-ESM SPA, maintained Notes source/deployment graph, module loading, UI conventions and shared ownership.
 - [integrations.md](integrations.md): Codex/Claude scoped APIs, companion pairing, webhooks, external agent access.
 - [shell-mcp.md](shell-mcp.md): shell execution, background jobs, MCP manager, built-in MCP servers.
 - [settings-admin.md](settings-admin.md): settings, preferences, presets, backup/import/export, diagnostics, admin wipe.
diff --git a/specs/agent-tools.md b/specs/agent-tools.md
index c6b7a8184..25cb57b14 100644
--- a/specs/agent-tools.md
+++ b/specs/agent-tools.md
@@ -1,12 +1,14 @@
 # Agent Tools
 
-Last updated: dev@e71f8ce | 2026-08-25
+Last updated: dev@c74f475 | 2026-10-15
 
 ## Scope
 
 This spec covers agent/tool behavior in:
 
-- `src/agent_loop.py`;
+- `src/agent_loop.py`, `src/clean_agent_preview.py`, `src/turn_contract.py`, `src/agent_evidence.py`, and `src/agent_trace.py`;
+- `src/agent_runtime/` authority, resource binding, action journal, durable effects, completion, and context resolution modules;
+- `src/containment.py`, `src/process_ownership.py`, `src/process_lifecycle.py`, and `src/browser_identity.py`;
 - `src/llm_core.py`;
 - `src/tool_schemas.py`;
 - `src/tool_execution.py`;
@@ -17,8 +19,7 @@ This spec covers agent/tool behavior in:
 - `src/tool_capabilities.py`;
 - `src/tool_approval_scopes.py`;
 - `src/tool_approvals.py`;
-- `src/attachment_refs.py` and shared upload lifecycle helpers in
-  `src/upload_handler.py` / `src/tool_utils.py`;
+- `src/attachment_refs.py` and shared upload lifecycle helpers in `src/upload_handler.py` / `src/tool_utils.py`;
 - `src/tool_implementations.py`;
 - `src/tools/*.py`;
 - `src/builtin_actions.py`;
@@ -41,7 +42,7 @@ This spec covers agent/tool behavior in:
 
 `src.llm_core` owns provider payloads, native tool-schema emission, and provider stream parsing. `agent_loop` consumes normalized tool-call events and decides whether and how to execute them.
 
-Agent mode enters through chat routes, including auto-escalation from intent helpers, detached `agent_runs` streaming, resume/stop behavior, and frontend tool-event rendering.
+The legacy loop and the opt-in compact preview share the execution boundary. Agent mode enters through chat routes, including auto-escalation from intent helpers, detached `agent_runs` streaming, resume/stop behavior, and frontend tool-event rendering.
 
 Guide-only/no-tools turns are runtime policy, not prompt advice. `src.tool_policy` detects strong latest-turn directives such as guide-only mode, no-tools mode, and explicit requests not to use tools; it builds a `ToolPolicy` that hides schemas, disables known native tools, disables MCP for that turn, skips tool retrieval, suppresses local/workspace context injection, blocks document streaming/teacher escalation, and gives `tool_execution` a final execution backstop.
 
@@ -64,7 +65,7 @@ Tool registration is split:
 
 When adding, removing, or renaming a tool, update the registry chain, execution dispatch, retrieval text, prompt wording, disabled-tool UI, and tests together.
 
-`src.tool_index.ALWAYS_AVAILABLE` is the retrieval catalog for high-frequency tools such as shell/python, web search/fetch, read/write/edit-file, code-nav, `manage_memory`, `ask_user`, `update_plan`, selected Cookbook serve controls, and `app_api`. Current prompt/schema assembly preserves only selected base tools unconditionally, then adds intent-, skill-, and retrieval-relevant tools so unrelated schemas do not flood small contexts.
+`src.tool_index.ALWAYS_AVAILABLE` is the retrieval catalog for high-frequency tools such as shell/python, web search/fetch, read/write/edit-file, code-nav, `manage_memory`, `ask_user`, `update_plan`, selected Cookbook serve controls, and `app_api`. Compact prompt/schema assembly selects policy-authorized intent-, skill-, and retrieval-relevant tools; the full-schema surface offers all policy-authorized built-ins and MCP schemas. Selection is not authority.
 
 ## Tool Retrieval And Execution
 
@@ -76,7 +77,7 @@ Tool retrieval has domain-specific hooks beyond generic similarity: contact quer
 
 Interaction/session/model helper tools are native first-class tools, not prompt-only conventions. `ask_user` and `update_plan` live in `src.agent_tools.interaction_tools`, model delegation/listing helpers live in `model_interaction_tools`, session creation/list/send/manage helpers live in `session_tools`, and `manage_bg_jobs` lives in `bg_job_tools`.
 
-Prompted-tool parsing includes recovery paths for local/provider text leaks: bare JSON after a web-tool mention, OpenAI-style raw `{"function": ...}` payloads, StepFun/Gemma/DSML markup, Hermes/Qwen JSON bodies nested inside `tool_call` wrappers, and `<function_model><function_call>...</function_call><parameters>...</parameters></function_model>` wrappers from local MLX/Exo models. The Qwen bare end marker requires its pipe delimiter so ordinary text cannot terminate a tool block. Non-dict JSON arguments are rejected back to empty args instead of crashing the turn, common `tex` typos normalize to `text`, and delimiter scans are forward-only so unterminated tool markup cannot drive quadratic rescans. Executed raw tool JSON is stripped from assistant text afterward; this is still not a general-purpose JSON-command parser.
+Prompted-tool parsing includes recovery paths for local/provider text leaks: bare JSON after a web-tool mention, OpenAI-style raw `{"function": ...}` payloads, StepFun/Gemma/DSML markup, Hermes/Qwen JSON bodies nested inside `tool_call` wrappers, and `<function_model><function_call>...</function_call><parameters>...</parameters></function_model>` wrappers from local MLX/Exo models. The Qwen bare end marker requires its pipe delimiter so ordinary text cannot terminate a tool block. Non-dict JSON arguments are rejected back to empty args instead of crashing the turn and common `tex` typos normalize to `text`. Shared finite delimiter scanning lives in `src/text_scanning.py`; supported wrapper recovery and bounded scans are not a general linear-time guarantee for all parsing. Executed raw tool JSON is stripped from assistant text afterward; this is still not a general-purpose JSON-command parser.
 
 Current call sites include:
 
@@ -108,9 +109,7 @@ Approval replay injects the sealed first tool result before the resumed model ro
 - `src.tool_capabilities` classifies each tool's effects and result integrity. Once external/workspace-untrusted content becomes model-visible, the request/session security context permits only explicitly low-impact tools without interruption and requires exact approval for high-impact, unknown, and arbitrary MCP calls.
 - `src.tool_approvals` seals an opaque, expiring exact first action plus server-only selected tools and continuation query to owner, session, origin run, tool content, workspace, capability snapshot, and—when relevant—document id/version/content digest. Chat choices grant the resumed task or the same chat session; both consume the exact first action, task scope bypasses the gate only during that resumed run, and chat scope is reconstructed only from a resolved card bound to the exact session id. The browser never receives selected tools/query and submits only task/chat/deny. Non-chat callers retain single-action behavior; new normal turns and superseding actions retire unresolved approvals without clearing taint.
 - Tool results that expose remote or stored untrusted content arm the gate even when their tool status is failed. Content-free failures and server-generated policy/approval placeholders do not. Native/provider tool messages and fenced results carry model-visible untrusted metadata/wrapping instead of relying on prompt wording alone.
-- Attachment-bearing document, note, and calendar tools owner-reserve internal
-  upload references before durable writes and fail without mutation when the
-  referenced upload is unavailable.
+- Attachment-bearing document, note, and calendar tools owner-reserve internal upload references before durable writes and fail without mutation when the referenced upload is unavailable.
 - Guide-only/no-tools mode blocks tools before prompt assembly, before execution, and in chat preprocessing paths that would otherwise fetch context or start tool-backed research.
 - Plan mode is policy, not prompt advice: mutating native tools are disabled through schema-derived detection plus a static backstop, and write/unknown MCP tools are hidden and runtime-blocked for that turn.
 
@@ -134,12 +133,73 @@ When an email reader is active, browser chat passes active email metadata and th
 
 ## Degraded Behavior
 
-- ToolIndex can degrade to keyword selection when embeddings, Chroma, index
-  warmup, or vector retrieval timeouts fail.
-- Agent mode can degrade from native function schemas to prompted fenced-block parsing based on provider/tool-support heuristics. Local Ollama `/v1` and native `/api` endpoints default to text tools unless the endpoint explicitly advertises `supports_tools`; `gpt-oss` remains text-tool by default unless the endpoint opts in.
+- ToolIndex can degrade to keyword selection when embeddings, Chroma, index warmup, or vector retrieval timeouts fail.
+- Agent mode can degrade from native function schemas to prompted fenced-block parsing based on provider/tool-support heuristics. Legacy local Ollama `/v1` and native `/api` endpoints normally use text tools unless explicitly supported. Compact native surfaces force native schemas unless a text-recovery path is selected; configured compact/full modes and the external request contract participate in surface selection, so the legacy default is not universal.
 - MCP startup failure is non-critical; route/status surfaces expose per-server errors.
 - `ODYSSEUS_DISABLE_MCP`, missing `mcp`, uncached browser MCP packages, and per-server disabled tools can remove tools without blocking the app.
-- Global `builtin_browser` disable behavior may not currently match qualified `mcp__builtin_browser__*` tool names.
+- Native browser page execution is unavailable at the common boundary; browser registration and schemas do not override that denial.
+
+## Request Authority, Resource Identity, And Completion
+
+`src.turn_contract` owns immutable request-scoped tool selection and required-read operations. Selection and retrieval never grant permission. `src.agent_runtime.authority` owns server admission independently of offered schemas; `execute_tool_block()` requires an explicit security context and a bound `RequestAuthority`, intersects child authority with its parent, normalizes exact operations, and checks policy before resource resolution or dispatch. Delegated credentials have a separate early denial backstop.
+
+`src.agent_runtime.resources`, `resource_binding`, `owned_resources`, `remote_resources`, and `process_resources` bind operations to server-owned filesystem, owned-record, backend/configuration, process/job, and browser identities. Exact approvals seal these bindings and revalidate them before use; a changed backend, document, path identity, process incarnation, or browser state can refuse replay. Control-plane stores are excluded from native file operations.
+
+`src.agent_runtime.journal` records proposed, normalized, authorized, dispatched, and settled actions. `effects`, `effect_adapters`, and `effect_log` distinguish intent, executor outcome, observed state, and verified effects; a successful receipt alone does not establish resulting state. `completion.with_completion_gate` decorates `stream_agent_loop`, holds answer deltas until the generator unwinds, and checks completion against the server journal/evidence ledger while tool/progress/interaction events remain live. Cancellation cannot emit successful completion. `src.agent_trace` adapts native SSE, typed traces, and imported trajectories into evidence/completion views.
+
+`src.agent_runtime.runtime_selection` is the shared compact-preview eligibility rule. `src.clean_agent_preview` runs the opt-in clean v3 loop when its contract has `clean_compact_v3_preview` selection mode; regular/full-schema and compatibility surfaces retain the legacy loop. Preview schema validation, bounded retry/search/tool budgets, and evidence-based finish checks supplement the common executor rather than replacing its authority.
+
+Current native tools also include `apply_patch`, `get_workspace`, `host_shell`, `private_browser`, `get_weather`, `youtube_tool`, `inspect_media`, `extract_text`, `transcribe_media`, and `search_chats`. Filesystem, subprocess, web, weather, and media handlers own these implementations; `src.media_ingress` owns bounded local attachment ingestion, and OCR/transcription can depend on optional backends.
+
+## Compact Selection And Evidence Recovery
+
+`src.turn_contract` shares broad-web briefing classification with preview. Named private stores, active editor work, concrete local media and explicit operations take precedence over incidental public lookup words. Standalone social turns and full-match supplied-text proofreading/translation (including correction-only colon payloads) offer no tools; compound save/search requests remain separate. A subjectless lookup can request clarification only without conversation referents or supplied workspace/media/editor context. These lexical guards neither resolve arbitrary language nor grant authority. A core tool floor applies only without recognized families, exact selected tools or a sealed read, and is still intersected with inventory/policy; browser is not a core tool.
+
+Explicit discovery-and-page retrieval can select both web tools; workspace artifact requirements can retain bounded file/Python tools alongside web selection. Memory-use prohibitions suppress sealed memory prerequisites. Concrete media routes prefer OCR for exact text, transcription for captions, otherwise inspection; explicit downstream artifacts or personal actions remain distinct. Tool-family selection and multilingual heuristics do not guarantee execution order or semantic understanding.
+
+Preview rejects blank search queries rather than copying conversational text. It preserves requested temporal/news constraints and adds a PDF constraint only when asked. Discovery is bounded separately from source retrieval: no-evidence/repeated cosmetic searches suppress further search while discovered URLs can remain inspectable. Broad briefing recovery permits one breadth expansion after one successful search and fewer than two attempts, within the remaining round budget; an empty second search cannot restart that expansion. One shallow-answer repair uses an 80-word-or-missing-source-URL heuristic, not substantive grounding proof. Breadth work precedes presentation-only citation/content repair.
+
+Retrieval qualification uses bounded body/access/missing-page/repetition heuristics, including embedded article text and a 100-word/12-shingle duplicate detector. A successful retrieval prompts assessment of missing, stale or contradictory evidence rather than forcing completion. Browser fallback proposals cannot override the common page-execution denial. Failed transports can lead to alternative offered search/source retrieval, not an authorized automatic browser session. A rejected search may synthesize only from earlier usable retrieval. Terminal budget fallback preserves up to five deduplicated source strings with explicit preliminary/insufficient-evidence wording, or reports no usable evidence. Synthesized citations are not automatically filled from arbitrary discovered URLs; deterministic link-only answers require a positive whole-request grammar and enough extracted links. Unknown official-source identity is not inferred from PDF extensions or product words.
+
+Native tool choice normalization can make a uniquely offered named search required, narrow schemas before omitting an unsupported provider choice, or use named/auto compatibility for specific DeepSeek/Kimi/Qwen/Ajax families. It is serialization compatibility, not provider acceptance. Wire messages strip server-only provenance and empty assistant placeholders while preserving legitimate tool-call carriers. Sibling tool receipts remain contiguous before bounded untrusted visual blocks; still-image repeat identity includes path, casefolded query and size. Visual defaults retain one current record/three frames with a bounded 1–8 frame control and retire prior tool pixels separately from user uploads.
+
+Artifact completion is target-specific: off-target/scratch writes and generic successful shell receipts cannot satisfy a required artifact or force early synthesis. Empty runner declarations fall back to prompt-inferred artifacts. Directory requests require meaningful files; source-code writes can unwrap leading/trailing Markdown fences for allowlisted suffixes without certifying syntax. Successful workspace paths can display as `/workspace`, without implying universal path redaction. A reserved final synthesis and tightly bounded malformed-call recovery do not create extra execution authority. `turn_contract` and `agent_step` expose required artifacts/calls-used/pending/write-phase fields; these are progress telemetry, not completion proof. Execution timing metrics record attempted canonical tools even on failure.
+
+## Admission And Bounded Execution Details
+
+Chat-scope bearer admission resolves the credential owner and intersects delegated tool grants with server policy; client runtime metadata, retrieval results and prompted tool names cannot widen it. Interactive approval/session options are refused for delegated credentials. Persistent chat grants are server-signed; a normal new turn retires stale pending approvals, while exact first-action replay is one-use. For a non-inherited ungranted launch lacking a backend launch scope, `ToolApprovalStore.create()` may seal exactly one request resource root (or its sealed workspace fallback); inherited children cannot gain this scope. Local reads through delegated credentials, including local `web_fetch`, file-scheme/workspace reads and absolute-path PDF extraction, have an early denial backstop even when the automatic action gate is disabled or bypassed.
+
+`ODYSSEUS_TOOL_APPROVAL_GATE` defaults on; only normalized `0`, `false`, `no` and `off` disable it. The gate does not replace authority/resource checks. Request authority binds owner, request/thread, workspace and admitted operations; child scopes intersect the parent. Owned record revisions, backend/configuration epochs, filesystem identities and process/job generations are revalidated. Captured server producer observations supply evidence; arbitrary tool output or registry membership is not a trusted producer. Expected admission/resource failures become typed denials; unexpected programming errors are not silently converted into authorization success.
+
+Native file tools use the canonical agent workspace and explicit allowed roots, deny control-plane paths and all hardlinked regular files, and validate path/resource identities. `ls`, `glob` and `grep` share one control-plane snapshot per scan; root and bound-resource checks still observe fresh state. Grep normalizes relative-or-basename glob filters before bounded ripgrep batches, validates regex even with no targets, closes stdin and retains a bounded Python fallback with identity revalidation. Empty file writes require explicit clear intent for nonempty existing files; missing/null content is refused, already-empty files can be no-ops, and missing files use exclusive/staged creation without overwriting a competing creator. These checks do not make filesystem operations universally atomic or race-free.
+
+Bounded required-safe reads use an exact sealed operation from the admitted family; a presentation `max_items` limit is not an owner/database filter. Only one eligible active family is warmed and a failed read does not authorize probing alternate families. Bounded model context keeps actual visible records rather than hidden private overflow. Native call identifiers survive only when arguments match exactly; structured turn replacement preserves tool/result pairing. Supplied documents, email, Notes/Todos, skills and workspace instructions remain untrusted reference data.
+
+Compact preview keeps connections alive without replaying executed tools. It permits at most two qualifying context-size retries per turn with reconstructed paired messages and one pre-response transport retry; yielded stream content is not retried. Pre-execution schema hints are freshly generated from offered schemas/arguments (bounded required/type/enum/additional-property/path guidance). Caught execution exceptions instead use fixed public messages and error categories; raw exception details can remain in server logs. Terminal provider errors use fixed public failure events and do not emit a successful done event.
+
+Repeated successful exact calls are suppressed while changed arguments or pagination can proceed; repeated failed exact calls and ignored corrective nudges have separate bounded stop rules. Artifact workflows reserve bounded calls and require actual usable artifacts, not merely directory existence or a tool receipt. Compact interactive rounds clamp to 1–200 with an eight-round fallback, and nonpositive interactive tool budgets use a large sentinel. Validated native workspaces instead clamp to 1–64 rounds with an eight-round fallback and a fixed 32-call budget. Legacy adaptive handling and UI limits are separate. Budgets are checked between rounds and do not interrupt an already-running call. Optional verifier retries and teacher escalation are separate recovery controls; teacher work starts after the parent stream contexts close.
+
+Durable effects distinguish intended mutations, execution outcome and observed state. Claims are persisted before execution; failure to establish a durable claim prevents execution. The newest eligible authorized observation for a resource wins; partial/undecidable evidence cannot borrow an older success, unknown impacts overlap conservatively, and later mutations/new incarnations stale earlier reads. Whole-file postconditions are all-or-none when derivation is unsupported; partial reads are not whole-file digests. Failed reads establish absence only after confined repeated ENOENT checks. Verifier cancellation remains unsettled; changed undeclared targets contradict completion. Only owned running processes survive as running effects; background settlement does not by itself verify output. External execution may finish with disclosed unverified effects, rather than claiming local containment or verified remote state. Scheduled built-ins and arbitrary remote systems are not all covered by this journal.
+
+## Artifact Recovery And Completion Claims
+
+Artifact delivery contracts narrow offered writer schemas on copied schema objects and bind declared targets without treating directory descendants or filename patterns as filesystem confinement. Binary suffixes refuse text-writer delivery, including relevant bridge paths, and prefer an offered capable writer. Empty, malformed, off-contract, or non-materialized output uses bounded shared recovery attempts; pending sibling calls and late results do not justify claiming an artifact exists. Python literal-output analysis is a planning aid, not execution evidence.
+
+Compact tool-call parsing accepts bounded concatenated complete JSON objects with ordered call identities and normal admission checks. Limited trailing tool markup after a complete supported call is inert; arbitrary prose is not an executable call. Artifact research reserves bounded call/time budget for delivery rather than guaranteeing interruption of an already-running tool.
+
+Completion assessment in `src.agent_runtime` distinguishes a usable artifact, a satisfied obligation, and verified execution. File evidence uses exact normalized identity and bounded regular-file reads, rejecting symlink/nonregular aliases rather than trusting basename matches. Partial reads do not prove whole-file verification, late observations do not retroactively verify earlier claims, and executable verifier results take precedence over optimistic prose.
+
+Final presentation can remove unsupported execution, test-count, coverage, or all-fixed assertions while preserving quoted/explanatory text. It does not invent new obligations from fabricated assistant claims. Provider errors, approval waits, and budget exhaustion remain distinct terminal states; a polished answer is not an execution receipt. Child journals remain separate, teacher review follows closed child execution, and incomplete children do not become successful distillation evidence. Explicit no-web filtering cannot be undone by an unrelated memory/toolset early return.
+
+## Parser And Diagnostic Ownership
+
+`src.text_scanning` supplies forward-only shared scans for the existing staged tool grammars, preserving delimiter priority, mandatory terminal-dot captures and legacy newline behavior. The parser does not become a universal linear-time or arbitrary-language recognizer. Binding catches expected input/resource errors as curated denials; programming defects such as AttributeError are allowed to propagate rather than being relabeled as policy refusal.
+
+Filesystem postconditions derive exact requested content from the producer transforms, including edit newline behavior and universal-newline patch prestate, with bounded identity-checked UTF-8 reads. Unsupported derivation clears the complete obligation set instead of verifying a convenient subset. Only a process-bound launch or detachment can attest RUNNING; unrelated returned lifecycle keys, arbitrary containment dictionaries and external acknowledgements cannot manufacture native cleanup or job observations.
+
+## Trusted MCP Attribution
+
+`src/tool_execution.py` strips caller-provided `_odysseus_*` fields from qualified/legacy MCP JSON and parsed tool arguments. Dispatch then injects trusted owner/session context for email and trusted owner for image MCP tools; missing trusted context does not preserve a forged claim. `_call_mcp_tool()` forwards owner through native/unavailable/disconnected direct fallback paths. Image results from qualified dispatch receive promoted image fields. The image MCP server persists the trimmed owner and registers fresh files; this transport attribution does not replace route authorization.
 
 ## Current Gaps
 
@@ -147,11 +207,7 @@ When an email reader is active, browser chat passes active email metadata and th
 - Agent prompts remain heavy for small local context windows.
 - Some AI-control helpers are still globally wired from app startup rather than a narrower service layer.
 - Tool registry consistency is manual across handler maps, tags, aliases, schemas, retrieval descriptions, execution dispatch, settings/model routes, and frontend toggles.
-- MCP disabled-tool changes can stale-cache tool retrieval because disabled maps are not always an index generation input.
+- Registry and retrieval consistency still requires coordinated updates across native and MCP surfaces.
 - External MCP output still needs a single central size cap before model re-entry; untrusted-result metadata and the post-external-context action gate now cover the prompt-injection/authorization boundary.
 - Auth-disabled/no-login owner propagation is inconsistent between route dependencies and chat/agent execution, so tool-security and native tool storage behavior need dedicated regression coverage.
-- Agent tests mostly cover helpers and targeted regressions, including round-cap
-  and disconnect cancellation paths, but not an end-to-end fake-LLM
-  `stream_agent_loop` path with retrieval, native schemas, prompted blocks,
-  disabled/admin hiding, MCP tools, plan/workspace state, user-time context, and
-  tool-result SSE.
+- Authority, resources, effects, containment, preview, and turn contracts have focused regression suites; live provider and platform behavior still requires separate validation.
diff --git a/specs/auth-security.md b/specs/auth-security.md
index bc1d6ec0d..219bfe2fc 100644
--- a/specs/auth-security.md
+++ b/specs/auth-security.md
@@ -1,6 +1,6 @@
 # Auth And Security
 
-Last updated: dev@e71f8ce | 2026-08-25
+Last updated: dev@c74f475 | 2026-10-15
 
 ## Scope
 
@@ -20,8 +20,7 @@ This spec covers current security and trust-boundary behavior in:
 - `src/prompt_security.py`;
 - `src/url_safety.py` and `src/url_security.py`;
 - `src/host_docker_access.py`;
-- `src/attachment_refs.py` and upload lifecycle enforcement in
-  `src/upload_handler.py` / `routes/upload_routes.py`;
+- `src/attachment_refs.py` and upload lifecycle enforcement in `src/upload_handler.py` / `routes/upload_routes.py`;
 - `src/secret_storage.py`;
 - `src/api_key_manager.py`;
 - `src/integrations.py`;
@@ -56,7 +55,7 @@ Reserved usernames include request-only sentinels `internal-tool`, `api`, `demo`
 
 Public/auth-exempt surfaces are limited to setup, signup/login/logout/status, feature/settings/integration preset reads, health/version/login, `/static/*`, and task webhook trigger paths. `routes/task/task_routes.py` owns validation of `POST /api/tasks/{task_id}/webhook/{token}` path credentials.
 
-Login issues an `HttpOnly`, `SameSite=Lax` cookie with a seven-day max age when "remember" is enabled. `_secure_cookie()` (`routes/auth_routes.py:89`) decides the `Secure` attribute: an explicit `SECURE_COOKIES` of `true` or `false` is authoritative, and any other value, including unset and the present-but-empty value docker-compose injects, derives it from the request, marking the cookie `Secure` when the connection scheme or the first `X-Forwarded-Proto` hop is https. TOTP is checked before session issuance. Logout, password changes, user deletion, rename flows, expired sessions, and deleted-user sessions must keep revocation/migration behavior intact.
+Login issues an `HttpOnly`, `SameSite=Lax` cookie with a seven-day max age when "remember" is enabled. `_secure_cookie()` (`routes/auth_routes.py`) decides the `Secure` attribute: an explicit `SECURE_COOKIES` of `true` or `false` is authoritative, and any other value, including unset and the present-but-empty value docker-compose injects, derives it from the request, marking the cookie `Secure` when the connection scheme or the first `X-Forwarded-Proto` hop is https. TOTP is checked before session issuance. Logout, password changes, user deletion, rename flows, expired sessions, and deleted-user sessions must keep revocation/migration behavior intact.
 
 Deleting a user revokes that user's browser sessions and API-token rows, then the admin delete route invalidates the in-memory bearer-token cache so already-cached tokens stop authenticating.
 
@@ -68,40 +67,26 @@ Admin promotion/demotion is a live auth flag change through `AuthManager.set_adm
 
 Cookie requests use the real username. Bearer-token requests are stamped as `request.state.current_user = "api"` plus `api_token_owner`, `api_token_scopes`, and token id. Routes that support API-token access must explicitly use `effective_user()` or route-local scope helpers instead of treating `"api"` as an owner.
 
-Internal loopback calls may stamp `current_user = "internal-tool"` or a validated `X-Odysseus-Owner` username. Network/proxy validation for that bypass lives in `app.py`; `require_admin()` trusts the stamped sentinel or raw internal header and should be used behind equivalent middleware control.
+Internal loopback calls may stamp `current_user = "internal-tool"` or a validated `X-Odysseus-Owner` username. Network/proxy validation for that bypass lives in `app.py`. Native shell/PID and local Cookbook controls add resource-bound admission and reject an internal header or sentinel as human administration. This boundary is surface-specific: common `core.middleware.require_admin()` still admits a matching internal token or sentinel, including MCP configuration routes; producer-side tool policy is a separate check.
 
 Missing-owner values remain state-dependent at legacy call sites, but new storage-facing code has one normalization contract:
 
 - Auth-enabled, configured auth with no `current_user` is unauthenticated and should fail closed at route dependencies.
-- `AUTH_ENABLED=false` is an explicit local single-user/no-login mode. Existing route dependencies can still return `""`, and admin gates allow the local operator. `effective_storage_owner()` and `storage_owner_for_request()` normalize an absent owner to `__odysseus_local__` only in this mode.
-  Native shell and local Cookbook administration additionally require a direct
-  loopback connection without proxy forwarding, cross-site indicators, or an
-  internal-tool header. Remote/proxied anonymous traffic remains denied at
-  these controls. Auth-enabled administration still requires a human admin.
-  This mode trusts local programs as well as the local operator: a headerless
-  loopback request cannot identify which local program sent it. Agent program
-  launches retain inherited networking; this is not protection against hostile
-  local code. Use authenticated mode when local programs are outside that trust.
-  Local Cookbook tools use a separate one-use capability for an admitted exact
-  request/operation/native backend and resolved launch body; that capability
-  cannot administer shell, PID, SSH-key, or arbitrary Cookbook state routes.
+- `AUTH_ENABLED=false` is an explicit local single-user/no-login mode. Existing route dependencies can still return `""`, and admin gates allow the local operator. `effective_storage_owner()` and `storage_owner_for_request()` normalize an absent owner to `__odysseus_local__` only in this mode. Native shell and local Cookbook administration additionally require a direct loopback connection without proxy forwarding, cross-site indicators, or an internal-tool header. Remote/proxied anonymous traffic remains denied at these controls. Auth-enabled administration still requires a human admin. This mode trusts local programs as well as the local operator: a headerless loopback request cannot identify which local program sent it. Agent program launches retain inherited networking; this is not protection against hostile local code. Use authenticated mode when local programs are outside that trust. Local Cookbook tools use a separate one-use capability for an admitted exact request/operation/native backend and resolved launch body; that capability cannot administer shell, PID, SSH-key, or arbitrary Cookbook state routes.
 - Chat/agent code that reads `get_current_user(request)` directly gets `None` when auth middleware is disabled, because no middleware stamps request state.
 - SQL `NULL`/JSON missing owners remain legacy/shared compatibility data, not the same thing as a logged-out authenticated caller.
 - `"api"` and `"internal-tool"` are request sentinels. They must not be persisted as normal storage owners unless a route explicitly defines that behavior.
 - `__odysseus_local__` is a valid storage owner but never a login or request sentinel. Adoption is incremental: callers that do not use the storage-owner helper can still expose older `None`/empty/null compatibility behavior.
 
-Authenticated `manage_tasks` mutations require an exact stored task-owner
-match and reject both cross-owner and legacy null-owner rows. The `owner=None`
-agent path keeps deliberate auth-disabled single-user compatibility, including
-unscoped list/create/mutation behavior.
+Authenticated `manage_tasks` mutations require an exact stored task-owner match and reject both cross-owner and legacy null-owner rows. The `owner=None` agent path keeps deliberate auth-disabled single-user compatibility, including unscoped list/create/mutation behavior.
 
 Owner-scoped route code should use `require_user()` or equivalent policy before querying per-owner data. Current note CRUD/reorder/reminder routes do this so an auth-enabled request that reaches the route without identity returns `401` instead of falling into single-user/null-owner compatibility behavior.
 
-Scheduled task actions attribute differently again. `_execute_action` (`src/task_scheduler.py:1231`) invokes the action with `owner=task.owner` read from the stored `ScheduledTask` row, so no request and no resolved principal are in flight. These trigger paths converge there: schedule, event bus, manual run (`routes/task/task_routes.py:865`), the `manage_tasks` agent tool (`src/tools/system.py:469`), webhook triggers (`routes/task/task_routes.py:1045`), which are unauthenticated by design with the token as the only credential and execute under the stored `task.owner`, and success-chained tasks (`src/task_scheduler.py:1063-1074`), which additionally require the chained target to share `task.owner` and reject cycles. Trigger-side ownership checks use the `if user and task.owner != user` shape, so a falsy caller skips them. Action bodies that reach owner-scoped storage must treat `task.owner` as the authority; route-level `require_user()` never runs on this path.
+Scheduled task actions attribute differently again. `_execute_action` (`src/task_scheduler.py`) invokes the action with `owner=task.owner` read from the stored `ScheduledTask` row, so no request and no resolved principal are in flight. These trigger paths converge there: schedule, event bus, manual run (`routes/task/task_routes.py`), the `manage_tasks` agent tool (`src/tools/system.py`), webhook triggers (`routes/task/task_routes.py`), which are unauthenticated by design with the token as the only credential and execute under the stored `task.owner`, and success-chained tasks (`src/task_scheduler.py`), which additionally require the chained target to share `task.owner` and reject cycles. Trigger-side ownership checks use the `if user and task.owner != user` shape, so a falsy caller skips them. Action bodies that reach owner-scoped storage must treat `task.owner` as the authority; route-level `require_user()` never runs on this path.
 
 ## API Tokens And Scoped Integrations
 
-`routes/api_token_routes.py` owns token CRUD and scope normalization. Partial updates preserve existing scopes unless new scopes are supplied, write scopes imply the matching read scopes where applicable, and Cookbook scopes are part of the normalized scope set. `app.py` caches active token prefix rows and verifies bearer tokens with bcrypt. API-token requests set `request.state.current_user = "api"` plus token owner/scopes.
+`routes/api_token_routes.py` owns token CRUD and scope normalization. Partial updates preserve existing scopes unless new scopes are supplied, write scopes imply the matching read scopes where applicable, and Cookbook scopes are part of the normalized scope set. `app.py` builds a complete replacement active-prefix map and publishes it by reference, including `app.state`, before verifying bearer tokens with bcrypt. Readers holding an older map are not emptied; this does not guarantee freshest revocation visibility or serialize overlapping refreshes. API-token requests set `request.state.current_user = "api"` plus token owner/scopes.
 
 Current call sites include Codex/Claude scoped APIs, `/api/v1/chat`, webhooks, selected session routes, companion pairing, and external integrations. `/api/codex/*` and `/api/v1/chat` enforce route-local scopes; companion and selected session routes use owner attribution. `companion/pairing.py` can mint chat-scoped tokens outside normal token CRUD.
 
@@ -137,21 +122,12 @@ Current untrusted surfaces include fetched URLs, web results, emails, memories,
 - `src/url_security.py` owns public HTTP(S) validation for integration/API-token supplied URLs. It should fail closed for private IP, loopback, invalid scheme, and unsafe redirect targets.
 - `src/url_safety.py` owns local-first outbound URL safety for model endpoints and similar local services. Loopback/LAN can be allowed by default, and private-IP blocking is an explicit caller policy. Strict `block_private=True` also rejects RFC 6598 shared/CGNAT space (`100.64.0.0/10`) explicitly because Python does not classify that range as private.
 - `core.log_safety.redact_url()` strips URL userinfo, query strings, and fragments before endpoint URLs enter logs. Model, chat/research endpoint, contact/CardDAV, and similar diagnostics should use this helper instead of logging raw admin-configured URLs.
-- `src.webhook_manager` validates webhook URLs at create and delivery time,
-  rejects private/internal targets, disables redirects, and pins delivery to
-  the public IP set that passed validation immediately before the request.
-- `src.integrations` owns admin-configured integration base URLs and secret
-  masking. `api_call` accepts only relative paths, rejects link-local/metadata destinations through `src.url_safety`, can additionally block RFC1918/loopback/private targets with `INTEGRATION_API_BLOCK_PRIVATE_IPS=true`, and pins requests to the IP set that passed SSRF validation while preserving the intended Host/TLS identity.
+- `src.webhook_manager` validates webhook URLs at create and delivery time, rejects private/internal targets, disables redirects, and pins delivery to the public IP set that passed validation immediately before the request.
+- `src.integrations` owns admin-configured integration base URLs and secret masking. `api_call` accepts only relative paths, rejects link-local/metadata destinations through `src.url_safety`, can additionally block RFC1918/loopback/private targets with `INTEGRATION_API_BLOCK_PRIVATE_IPS=true`, and pins requests to the IP set that passed SSRF validation while preserving the intended Host/TLS identity.
 - `src.outbound_fetch` owns reusable public-URL classification, validates every redirect hop, rejects private/local resolved addresses, and pins the HTTP connection to the validated public IP while preserving original URL/SNI/Host semantics. `services.search.content` adapts that transport for extraction and caching.
 - Path-based tools, upload/document/gallery/signature/generated-image routes, embedding cache paths, and research JSON helpers must stay confined to allowed roots and owner-scoped files. Native file/code-navigation tools also apply a case-insensitive sensitive-path denylist so `grep`, `glob`, `ls`, direct reads, and writes cannot reveal `.env`, SSH/GPG material, private-key filenames, or similar secret paths.
-- Durable upload references are owner-reserved before chat/session, document,
-  note, or calendar writes. Cleanup scans every current durable reference
-  surface and fails closed on incomplete discovery or inconsistent upload-index
-  state rather than deleting a possibly live upload.
-- File-backed SQLite startup restricts `app.db` and existing rollback/WAL/SHM
-  sidecars to `0600` on POSIX after resolving the real path from the parsed
-  engine URL. Windows, in-memory, and non-SQLite databases are excluded, and
-  failed POSIX restriction is logged as a secret-file warning.
+- Durable upload references are owner-reserved before chat/session, document, note, or calendar writes. Cleanup scans every current durable reference surface and fails closed on incomplete discovery or inconsistent upload-index state rather than deleting a possibly live upload.
+- File-backed SQLite startup restricts `app.db` and existing rollback/WAL/SHM sidecars to `0600` on POSIX after resolving the real path from the parsed engine URL. Windows, in-memory, and non-SQLite databases are excluded, and failed POSIX restriction is logged as a secret-file warning.
 - Secret-like DB columns use `EncryptedText` or `src.secret_storage`. Email passwords and Google OAuth mail tokens are encrypted manually in `EmailAccount` string columns; Google OAuth state is HMAC-signed and callback writes are owner-checked before token storage. `src.api_key_manager` keeps provider API keys encrypted in `data/api_keys.json`, writes by loading the raw encrypted dict so saving one provider does not rewrite other providers' keys as plaintext, and restricts local key-file permissions where the platform supports chmod. Vault state in `data/vault.json` is a chmod-restricted JSON secret store, not Fernet-encrypted DB storage. Do not log or return decrypted secrets except for intentional admin vault retrieval flows with audit/reason checks.
 - `.env` files are secrets-only inputs and should not be read or printed during agent work.
 
@@ -170,11 +146,39 @@ Host Docker socket access is a high-trust admin/deployment choice, not a normal
 - Legacy migrations claim null-owner SQL/JSON data for the primary admin when possible, and startup repeats a null-owner sweep hourly. Remaining null-owner rows are surface-specific compatibility data that must be deliberately included, no-oped for single-user mode, or rejected for strict ownership gates.
 - `.env` is loaded with `utf-8-sig`, so Windows BOM auth flags still parse.
 
+## Server Admission And Model Execution
+
+`src.agent_runtime.authority.RequestAuthority` is server-owned admission separate from schema availability or intent selection. `execute_tool_block()` requires explicit security context, verifies owner/session/workspace binding, intersects delegated child authority, applies policy denial before approval/bridge dispatch, and resolves typed backend/filesystem/owned/process/browser resource identities. Exact approvals seal and revalidate these bindings; task/chat taint grants cannot manufacture absent backend or resource authority.
+
+Native filesystem operations use `src.path_confinement` and `src.agent_runtime.resources` to reject sensitive/control-plane paths, including runtime effect stores and aliases. Native model shell/Python paths use enforcing containment with required filesystem, process-tree, and wall-clock dimensions; missing required enforcement fails before spawn. This is distinct from direct operator/admin HTTP shell access and declared external execution bridges. Network and resource-limit dimensions are not automatically promised by the default requirements.
+
+`core.auth.AuthManager.reset_user_password()` permits an admin to reset a non-admin account and revokes that account’s sessions. Admin targets and non-admin callers are refused.
+
+## Scoped Admission And Public Error Details
+
+Browser chat/session/history bearer support requires chat scope and resolves the token owner. Delegated callers cannot approve actions, inherit browser chat grants, supply raw session credentials or bypass route validation. Resolved persistent chat grants are HMAC signed and checked; client metadata removes authority-bearing fields. Parent/child task and teacher authority intersects, and local file/workspace/PDF reads have delegated early denials independent of the optional action gate. The automatic high-impact gate defaults on, disabled only by explicit normalized false values; stale threat-model prose describing unrestricted model filesystem access is not the current native contract.
+
+Local-first URL checks classify IPv4-mapped addresses by embedded IPv4 and decode exactly `64:ff9b::/96` with strict embedded-target policy, even when the caller allows private services. Other translation prefixes receive no inferred exemption. IPv6 loopback is checked before reserved-address denial and follows the configured private policy. Mail connection helpers validate the resolved address set and pin actual TCP connection; scholarly metadata validation does not inherit that stronger transport claim.
+
+Host/client run/read/write/patch/poll/cancel bridge clients disable environment proxy trust and carry exact admitted authority, while external execution remains unattested local containment. MCP backend/config and Vault unlock/catalog identities are epoch/revision bound. Native browser page actions and raw global Playwright calls are currently denied unconditionally; metadata-only `session_info` does not restore them. Native filesystem root checks reject NUL/CRLF and all hardlinked regular files, but do not imply every OS path operation is atomic.
+
+Preview validation may expose bounded schema-derived argument guidance before dispatch; caught execution exceptions use fixed public errors/categories. Raw exception text can remain in server logs. Transport/provider terminal errors are distinct from successful completion, and public assertion filtering is not a general secret scrubber. Upload reference reservations, scoped owners and runtime credential custody continue to apply independently.
+
+## Configuration And Generated-Media Boundaries
+
+Auth-route app configuration uses `_require_admin_user()` to honor explicit disabled-auth operator mode for settings/features, document-style extraction and integrations; user-store administration still requires an admin identity. Settings GET exposes full settings to the disabled-auth operator, while auth-enabled anonymous/non-admin reads remain scrubbed. This is a trusted deployment mode, not an anonymous multi-user grant.
+
+Generated-image serving checks filename syntax before identity, then `effective_user()` (cookie or API-token owner) before disk access. A live process-local registration, gallery owner, linked session owner, or owned-chat metadata reference can authorize access; absence/mismatch returns 404 and database verification errors return 503. Disabled auth skips ownership checks. Responses use private revalidation and nosniff headers. Tool argument parsers strip caller `_odysseus_*` fields before server context injects trusted image/email owner/session attribution; see `gallery-editor-media.md` and `agent-tools.md`.
+
+## Upload Route Authorization
+
+Upload routes distinguish disabled-auth operation from unavailable/unconfigured auth infrastructure: explicit no-login bypasses owner gates; auth-enabled missing manager is 503, unconfigured manager 401 and missing/sentinel identity 403, without loopback fallback. Interactive admin override remains available for non-owned/legacy ownerless files. Delegated API credentials require a real token owner, matching non-null file ownership and an appropriate scope; even an admin-owned token has no cross-owner or ownerless override. Read scopes are any of `chat`, `documents:read`, `documents:write`; upload creation/OCR mutation requires `chat` or `documents:write`. See `documents-rag-uploads.md` for transition behavior.
+
 ## Current Gaps
 
-- There is no shell/filesystem sandbox for admin tools.
+- Direct operator/admin HTTP shell execution remains powerful; model-code containment and typed admission must not be generalized into a sandbox claim for every administrative surface.
 - Token scopes remain coarse for some surfaces.
-- `app.py` AuthMiddleware lacks direct regression coverage for bearer-token state/cache behavior, trusted-loopback proxy-header rejection, and internal-tool owner stamping.
+- Auth policy, scoped tokens, and request authority have focused regression tests; full middleware composition and live proxy deployments still need separate validation.
 - Codex/Claude scoped route enforcement still needs stronger regression coverage.
 - `THREAT_MODEL.md` still has stale token-scope and `/api/v1/chat` SSRF gap text that should be reconciled with current route validation.
 - The Default/Local owner contract is canonical but only incrementally adopted; route helper `""`, chat/agent `None`, SQL/JSON null-owner compatibility, and calendar fallback owner behavior still need domain-by-domain migration decisions.
diff --git a/specs/calendar-tasks-notes.md b/specs/calendar-tasks-notes.md
index b3259c932..33386abd1 100644
--- a/specs/calendar-tasks-notes.md
+++ b/specs/calendar-tasks-notes.md
@@ -1,6 +1,6 @@
 # Calendar, Tasks, And Notes
 
-Last updated: dev@e71f8ce | 2026-08-25
+Last updated: dev@c74f475 | 2026-10-15
 
 ## Scope
 
@@ -18,7 +18,7 @@ This spec covers calendar, reminders, tasks, assistant runs, and notes in:
 - scoped Codex wrappers in `routes/codex_routes.py`;
 - database models `CalendarCal`, `CalendarEvent`, `ScheduledTask`, `TaskRun`, `Note`, and `CrewMember`;
 - direct DB CLIs `scripts/odysseus-calendar`, `scripts/odysseus-notes`, and `scripts/odysseus-tasks`;
-- frontend modules `static/js/calendar.js`, `static/js/calendar/*`, `static/js/tasks.js`, `static/js/notes.js`, and `static/js/assistant.js`;
+- frontend modules `static/js/calendar.js`, `static/js/calendar/*`, `static/js/tasks.js`, the `static/js/notes.js` compatibility facade and maintained `frontend/src/features/notes/` graph deployed under `static/js/features/notes/`, and `static/js/assistant.js`;
 - tests covering calendar routes/utilities, CalDAV, recurrence, timezone handling, scheduler behavior, task webhooks, notes CLI/tool behavior, and task CLI behavior.
 
 ## Calendar
@@ -53,6 +53,8 @@ Cookbook serve scheduling crosses this domain. The Cookbook UI creates `cookbook
 
 `routes.task.task_routes` owns task CRUD, status, manual run/stop/cancel, pause/resume, owner-scoped run/activity history, metadata, onboarding defaults, cache clearing, parse endpoints, and webhook-token regeneration. `app.py` imports the canonical package path; `routes/task_routes.py` replaces its module entry with the canonical module for legacy import and monkeypatch compatibility. Chained-task `then_task_id` values are validated as same-owner relationships on create/update, and scheduler execution also rejects cross-owner or cyclic chains.
 
+`src.tools.system.do_manage_tasks()` translates structured schedules: `day_of_month` is an integer 1–31 for monthly tasks, while recurring `weekdays` names plus `scheduled_time` in UTC `HH:MM` become a cron expression. Conflicting day/cron inputs are rejected. One-off `scheduled_date` values are parsed to naive UTC and must be future dates; recurring schedules reject supplied one-off dates, and invalid cron expressions are refused. A time-only edit of an existing five-field cron rewrites its minute/hour fields while preserving calendar fields and recomputes `next_run`; it does not merely update the legacy display clock.
+
 Task webhook paths are auth-exempt at the app middleware layer only for `/api/tasks/{task_id}/webhook/{token}`. The route still validates active task state plus task-specific webhook token before dispatch.
 
 Task runtime behavior:
@@ -65,25 +67,16 @@ Task runtime behavior:
 - event-bus triggers persist counters and `next_run` before scheduler handoff;
 - the in-process scheduler is gated by `ODYSSEUS_INPROCESS_TASKS`, and multiple enabled app processes can double-run work.
 - action tasks with `run_local`, `run_script`, `ssh_command`, or
-  `cookbook_serve` are admin-only. `routes.task_routes` enforces this on
-  create/update/manual run and hides those actions from `/meta/actions` for
-  non-admin owners; webhook and scheduler execution pause the task and clear
-  `next_run` if an admin-only action belongs to a non-admin owner.
+  `cookbook_serve` are admin-only. `routes.task_routes` enforces this on create/update/manual run and hides those actions from `/meta/actions` for non-admin owners; webhook and scheduler execution pause the task and clear `next_run` if an admin-only action belongs to a non-admin owner.
 - background LLM task execution uses the background workload path, and the
-  scheduler can abort/cancel active in-process task runs when foreground browser
-  activity appears.
+  scheduler can abort/cancel active in-process task runs when foreground browser activity appears.
 - `tidy_research` scans all persisted research files because broken JSON has no trustworthy owner stamp, so it runs only for admins or the explicit auth-disabled single-user operator and refuses regular/pre-setup callers before enumeration.
 
 `routes.assistant_routes.py` owns crew/assistant settings and run-status surfaces that use the scheduler. `TaskScheduler.ensure_assistant_defaults()` currently seeds the personal assistant crew member and pinned assistant session, but no longer auto-creates Morning/Midday/Evening check-in tasks. Existing crew-linked check-in tasks are still rendered and managed when present.
 
 ## Notes And Reminders
 
-`routes.note.note_routes` owns notes/todos/reminders, and `app.py` imports that
-canonical path. `routes.note_routes` replaces its module entry with the
-canonical module for legacy import and monkeypatch compatibility. Notes are
-SQLAlchemy `Note` rows and can include due dates, ordering, images, repeat
-state, AI classification, source/session provenance, and agent session
-linkage.
+`routes.note.note_routes` owns notes/todos/reminders, and `app.py` imports that canonical path. `routes.note_routes` replaces its module entry with the canonical module for legacy import and monkeypatch compatibility. Notes are SQLAlchemy `Note` rows and can include due dates, ordering, images, repeat state, AI classification, source/session provenance, and agent session linkage.
 
 Notes CRUD/reorder/reminder routes resolve the acting owner through `require_user()`: auth-enabled anonymous requests fail closed before hitting owner-scoped queries, while documented no-login/single-user modes still resolve to the compatibility owner path.
 
@@ -105,17 +98,15 @@ Reminder dispatch is Note-owned:
 
 Email/ntfy failures degrade into channel result fields rather than blocking every reminder path. ntfy and generic webhook reminder URLs run through outbound URL safety checks, with `REMINDER_WEBHOOK_BLOCK_PRIVATE_IPS` controlling whether private/LAN targets are allowed. ntfy notification titles are converted to ASCII with replacement and capped at 200 characters before entering HTTP headers. Reminder dedupe uses owner-scoped cache files under `data/`.
 
+`src.builtin_actions.action_ping_notes()` counts delivery only when `dispatch_reminder()` reports success for the configured browser/email/ntfy/webhook channel. Typed receipts in `data/note_pings_<owner-slug>.json` record time and channel. A browser fallback or legacy timestamp does not prove external delivery: the next eligible scan retries the configured external channel without queueing the recent browser fallback again. The scanner reloads dispatcher-owned receipts before pruning so it cannot replace a successful channel receipt with a timestamp; total delivery failure is not checkpointed. Retries occur only within 90 seconds of the due time, while recent matching-channel receipts suppress delivery for 25 minutes. Existing retry tests cover webhook/ntfy failures, legacy receipts, browser dedupe, total failure, and receipt-preserving pruning; live channel delivery remains separate validation.
+
 ## Agent, Codex, And CLI Surfaces
 
 `do_manage_tasks`, `do_manage_notes`, and `do_manage_calendar` own agent-side writes. `do_manage_calendar` supports batch event creation plus list range aliases (`start`, `start_time`, `start_date`, `range_start`, `from`, `dtstart`, `since`, and matching end aliases), calendar name/short-id lookup, importance/tag aliases, and reminder offsets expressed as numbers, minute/hour words, or common abbreviations such as `min`/`mins`/`hr`/`hrs`. If a model supplies a loose `query`, `date_range`, or `range` without explicit start/end datetimes, `list_events` returns an error asking the caller to resolve the range and call again instead of guessing. Event classification reads `Memory.text` for personal context before LLM classification. `src.tool_index` encodes the reminder policy that notes/todos own reminders while calendar events own time blocks.
 
 Agent native tool owner handling is not uniform today. `do_manage_tasks()` filters lists only when `owner` is truthy and creates tasks with the passed owner, so `owner=None` can create legacy/null-owner tasks. For authenticated/non-empty owners, edit/delete/pause/resume/run require an exact stored owner match and reject both cross-owner and null-owner rows; `owner=None` retains single-user compatibility. `do_manage_notes()` list/query behavior distinguishes `None` from `""`, with `None` acting as broader single-user compatibility while `""` filters to empty-owner rows in some paths. `do_manage_calendar()` query helpers filter only when owner is not `None`, while calendar creation routes through the calendar fallback owner for default calendars. These are compatibility behaviors, not a cross-user sharing model.
 
-Note and calendar route/tool writers owner-reserve any canonical internal upload
-references in content, checklist/color/image fields, descriptions, and
-locations before their database writes. Missing or wrong-owner uploads fail the
-write instead of creating a dangling durable reference; reservations serialize
-with upload cleanup.
+Note and calendar route/tool writers owner-reserve any canonical internal upload references in content, checklist/color/image fields, descriptions, and locations before their database writes. Missing or wrong-owner uploads fail the write instead of creating a dangling durable reference; reservations serialize with upload cleanup.
 
 Chat forwards browser timezone offset and IANA timezone name so natural-language note/calendar tools can anchor dates to the user clock. A valid IANA zone wins over the fixed offset for current-time/DST reasoning; invalid or absent names fall back to the offset and then server-local/UTC compatibility behavior. Chat can auto-promote note/calendar/reminder intents to agent mode.
 
@@ -171,9 +162,32 @@ Existing coverage is strongest around CalDAV URL hardening/writeback, client cle
 
 Route-level coverage is thinner for full calendar route behavior, task CRUD/security/run controls, live webhook token dispatch, notes owner CRUD/reminder delivery, assistant defaults/run status, event-bus triggers, Codex todo/calendar scopes, and frontend panel wiring.
 
+## Calendar Reminder And Invitation State
+
+Calendar event responses now include reminder note id, due time, minutes-before, and source-email provenance. Create/update accept `reminder_minutes`; an explicitly supplied null clears the reminder, while omission preserves it. Reminders are owner-scoped `Note` todos with calendar label/source. Passed events skip creation, and a reminder whose intended time passed is clamped to now. Legacy matching uses generated title plus due time rather than an event UID; deleting reminders uses the title/source/owner match, so similarly named events remain a compatibility-sensitive boundary. `GET /api/calendar/events/{uid}` resolves recurring occurrence IDs back to the owner-visible base event.
+
+`src/email_calendar_import.py` owns invitation revision state through `EmailCalendarInvitation`: identity hashes owner, normalized sender, ICS UID, and optional recurrence id instead of letting untrusted ICS UIDs address arbitrary local events. Sequence/DTSTAMP ordering suppresses stale replays, cancellation wins equal-version ties and leaves tombstones, and detached occurrences exclude their original series instance. Fixed striped file locks serialize imports across processes. Unsupported reply methods are ignored, and `THISANDFUTURE` revisions require a replacement series.
+
+Task create/update persist sealed `request_authority_json`; execution binds that authority to LLM/research work rather than deriving permission from task output. Task endpoint resolution uses owner-visible registered endpoint bases or their exact derived chat URL before runtime credentials are attached; scheme, host, effective port and full trimmed path must match, with no userinfo, parameters, query or fragment. Legacy shared endpoint visibility is retained. The scheduler helper catches credential resolution exceptions and can continue with empty headers, so this is not a universal no-network-on-resolution-failure guarantee. Authority/effect contracts are owned by `src/agent_runtime`, not the scheduling layer.
+
+## Scheduler Cache And Native Task Details
+
+Scheduler `_cached` requests share one pending future per key with a TTL. Waiters shield the shared work from their own cancellation; completion/failure removes only the matching pending future, and failures can retry rather than being cached as success. Endpoint discovery separately caches successful empty Tailscale results, while discovery failures do not become successful empty cache entries.
+
+Task/assistant endpoint updates accept registered owner-visible routes, canonicalize empty values to no override and reject invalid routes. Local shell/script/Cookbook scheduled actions require their sealed native backend capability; missing capabilities fail closed and raw external/SSH execution cannot borrow it. Headless task/background continuations close their streams in the originating task, preserve authority, honor replacement final responses and distinguish provider failure from successful completion.
+
+`NotificationLog` GET is owner-scoped and non-consuming, defaults to 200 rows and clamps to 1000. Notification insert title/body limits are 200/2000 characters; notification text does not grant task authority. Calendar reminder matching is legacy title/source/owner-based rather than UID-linked: nearest eligible due time within zero to seven days of the base event start can match, while deletion removes all same-title matches rather than discriminating by exact alarm time. Negative offsets clamp to zero, passed events do not create reminders, passed alarm time clamps to now, explicit null clears and omission preserves.
+
+## Notes Frontend State And Lifetimes
+
+The canonical Notes composition entry owns one `createNotesState()` instance, injected HTTP/storage/notification ports, application workflows and UI factories. Domain modules own note rules and local-time recurrence. Application modules own query/order, optimistic submission/card/checklist/deletion, selection, drafts, agent actions and reminders; UI modules delegate mutations and transport through those operations. The legacy facade preserves default/named open/close/toggle/new/openNote/badge methods and aliases, including named-only reminder-dot dismissal, without exposing mutable state.
+
+Background startup is idempotent: after three seconds it loads active notes, then starts a 30-second reminder interval and immediate check. Close/minimize/force-close dispose panel resources but leave that page-owned interval running. Scans use the current shared note collection, skip archived/date-only/fired notes, fire within the previous minute, and advance or mark older reminders; archived-only/error-cleared lists can still defer active reminders. Server synthesis has a 1.5-second local-notification fallback, with toast/highlight persistence. This browser path remains separate from backend delivery receipts.
+
+Drafts persist synchronously on input/change and serialize existing-note network autosaves after 500 ms; successful saves clear only the matching draft, while failure/new/drawing drafts remain recoverable. Canvas bitmaps are not draft JSON. Explicit drawing save awaits PNG upload before optimistic submission. Selection dispatches `odysseus:notes-context-selected` synchronously and exits only when the consumer sets `accepted`; chat retains context/session authority. Closing releases owned portals/listeners/gestures/observers, and late fetch/masonry work checks panel connectivity/open state. It does not add universal async generation guards: fetch remains last-completion-wins, optimistic creation replaces the first remaining temporary note, and bulk actions can swallow individual failures before refetch/reporting requested counts.
+
 ## Current Gaps
 
-- CardDAV still needs URL hardening parity with CalDAV; CalDAV now resolves hostnames during validation and revalidates writeback URLs.
 - `do_manage_notes()` should match HTTP note-route owner behavior for legacy null-owner notes.
 - Auth-disabled agent tools can produce or read broader owner scopes than route handlers because they receive `owner=None`; tasks, notes, and calendar need aligned policy/tests.
 - Task webhook tests should keep exercising live route token behavior and
diff --git a/specs/chat.md b/specs/chat.md
index ca350f692..f843e72ae 100644
--- a/specs/chat.md
+++ b/specs/chat.md
@@ -1,20 +1,19 @@
 # Chat
 
-Last updated: dev@e71f8ce | 2026-08-25
+Last updated: dev@c74f475 | 2026-10-15
 
 ## Scope
 
 This spec covers current chat behavior in:
 
 - `routes/chat_routes.py` and `routes/chat_helpers.py`;
-- `routes/session_routes.py` and canonical `routes/history/history_routes.py`,
-  with `routes/history_routes.py` as a compatibility shim;
+- `routes/session_routes.py` and canonical `routes/history/history_routes.py`, with `routes/history_routes.py` as a compatibility shim;
 - `src/chat_helpers.py`;
-- `src/agent_runs.py`;
+- `src/agent_runs.py` and `src/background_tool_jobs.py`;
+- `src/turn_contract.py`, `src/request_models.py`, and `src/agent_runtime/` request authority/runtime selection/context resolution;
 - `src/chat_handler.py` and `src/chat_processor.py`;
 - `core/session_manager.py` and `core/models.py`;
-- `src/attachment_refs.py` and `src/upload_handler.py` for durable attachment
-  references and write reservations;
+- `src/attachment_refs.py` and `src/upload_handler.py` for durable attachment references and write reservations;
 - `src/context_budget.py`, `src/context_compactor.py`, and `src/topic_analyzer.py`;
 - `src/foreground_model_routing.py`, `src/tool_approval_scopes.py`, `src/tool_approvals.py`, and `src/tool_capabilities.py`;
 - `routes/workspace_routes.py` for workspace selection support;
@@ -41,16 +40,10 @@ Runtime behavior:
 - browser chat sends `X-Tz-Offset` and an IANA timezone name; request-local helpers prefer a valid IANA zone for DST-aware current-time reasoning, then fall back to the fixed offset;
 - browser chat can send a selected workspace path; route code only resolves it for admin/single-user flows, validates it as an existing directory, and forwards it so agent file/shell tools are confined by `src.tool_execution`;
 - stream callbacks can outlive a deleted session, so persistence must fail closed instead of recreating orphan messages;
-- message metadata carries timestamps, metrics, tool events, sources, hidden
-  thinking/reasoning text when providers expose it separately, context-trim
-  metrics, structured attachment references, and related UI state;
+- message metadata carries timestamps, metrics, tool events, sources, hidden thinking/reasoning text when providers expose it separately, context-trim metrics, structured attachment references, and related UI state;
 - metadata preserves requested and actual reply models and endpoints, per-round route transitions, and answering-route cost attribution; stable session ids remain available so prompt/sequence-memory and KV-cache paths can address the same conversation consistently;
-- multimodal content can be a list of content blocks for the live provider call,
-  while persistence collapses raw media into readable text and stable
-  attachment-reference lines;
-- agent streams forward explicit round-cap, tool-budget, repeated-tool-loop,
-  and intent-without-action guard events so the frontend can distinguish a
-  controlled stop from a stalled response.
+- multimodal content can be a list of content blocks for the live provider call, while persistence collapses raw media into readable text and stable attachment-reference lines;
+- agent streams forward explicit round-cap, tool-budget, repeated-tool-loop, and intent-without-action guard events so the frontend can distinguish a controlled stop from a stalled response.
 
 `src.agent_runs` owns detached in-memory stream runs, replay buffers, replacement cancellation, resume subscribers, explicit stop, and terminal-buffer eviction. Closing the SSE connection does not necessarily stop generation. `static/js/chat.js` can live-resume a still-running detached stream through `/api/chat/resume/{session_id}`; rich responses reload from DB for canonical rendering. Detached runs are process-local and do not survive server restart.
 
@@ -81,30 +74,15 @@ Current call sites include:
 - deep research orchestration in `src/research_handler.py`;
 - compare entry points in canonical `routes/compare/compare_routes.py` and frontend compare modules.
 
-Agent-mode tool access is gated in layers. Chat route toggles and privileges
-build a disabled-tool set; incognito and compare mode remove persistence-heavy
-or UI-breaking tools; `src.action_intents.message_needs_tools()` provides
-conservative regex auto-escalation hints; `src.agent_loop`,
-`src.tool_security`, `src.tool_execution`, and internal loopback validation
-remain server-side enforcement owners.
+Agent-mode tool access is gated in layers. Chat route toggles and privileges build a disabled-tool set; incognito and compare mode remove persistence-heavy or UI-breaking tools; `src.action_intents.message_needs_tools()` provides conservative regex auto-escalation hints; `src.agent_loop`, `src.tool_security`, `src.tool_execution`, and internal loopback validation remain server-side enforcement owners.
 
 `allow_bash` and `allow_web_search` can be read from the JSON request body for browser chat posts that do not submit traditional form fields.
 
-Web search tools are per-turn explicit opt-in. Either `allow_web_search=true`
-or `use_web=true` can enable `web_search`/`web_fetch`, but an explicit
-`allow_web_search=false` wins over `use_web=true` and keeps those tools
-disabled. Explicit latest-turn web-search intent can still auto-escalate into
-agent mode and narrows the available tool set toward `web_search`/`web_fetch`,
-but it no longer re-enables web tools after an explicit denial or global
-disable.
+Web search tools are per-turn explicit opt-in. Either `allow_web_search=true` or `use_web=true` can enable `web_search`/`web_fetch`, but an explicit `allow_web_search=false` wins over `use_web=true` and keeps those tools disabled. Explicit latest-turn web-search intent can still auto-escalate into agent mode and narrows the available tool set toward `web_search`/`web_fetch`, but it no longer re-enables web tools after an explicit denial or global disable.
 
 Guide-only/no-tools requests build an effective tool policy before preprocessing and agent dispatch. That policy suppresses tool-backed preprocessing/background extraction/research, disables schemas and MCP for the turn, and is still enforced by `src.tool_execution` if a model emits a tool call anyway.
 
-When route context is trimmed without full compaction, chat emits a
-`context_trimmed` SSE event and carries before/after message/token counts into
-metrics. Provider reasoning/thinking deltas are streamed for live UI handling
-but kept out of the visible saved assistant content and stored in metadata when
-available.
+When route context is trimmed without full compaction, chat emits a `context_trimmed` SSE event and carries before/after message/token counts into metrics. Provider reasoning/thinking deltas are streamed for live UI handling but kept out of the visible saved assistant content and stored in metadata when available.
 
 ## Attachments
 
@@ -112,12 +90,11 @@ available.
 
 Attachment-only sends are valid. Missing or unauthorized ids are skipped during preprocessing, while a missing/wrong-owner durable reference aborts a message/history replacement before existing transcript rows are removed. Upload failures keep pending files for retry, unsupported media can degrade to text markers, optional Office/PDF/VL dependencies can emit extraction banners, Office attachments can create markdown documents when extracted server-side, and fillable-PDF auto-document failures fall back to normal PDF extraction. `chat_messages.content` and FTS do not retain provider data URLs; structured references stay in metadata for reloads. Chat does not own upload bytes or durable document storage; it requests document/upload behavior from those subsystems.
 
-Frontend chat distinguishes normal resend from regenerate-from-here: normal resend appends a fresh user copy and carries upload IDs where available, while regeneration truncates from the selected point. AI-message delete prompts before removing the AI response plus preceding user turn. Desktop Enter submits; mobile Enter inserts a newline unless another platform-specific send control is used.
+Frontend resend normally replaces from the selected user turn: it truncates server history before removing that turn and later DOM/thread state, resolves the persisted message id with index fallback, and aborts if truncation fails. Explicit append-only resend appends a fresh copy; attachments are retained through the respective path. AI-message delete prompts before removing the AI response plus preceding user turn. Desktop Enter submits; mobile Enter inserts a newline unless another platform-specific send control is used.
 
-Native document tool outputs can open or refresh the document editor from
-tool-result metadata, so the UI can recover if a later `doc_update` stream event
-is missed. The chat renderer also hides raw/incomplete leaked tool JSON and
-document fences from normal transcript text.
+The Notes panel can attach selected Note/Todo IDs as reference context for a chat send. `static/js/chat.js` keeps selection in memory per chat session, transfers a pending selection when a new session is materialized, restores the indicator on session switches, and lets the user clear it. A send captures the selected IDs for its current session and includes `selected_note_ids` in the streaming form. This is separate from uploaded attachments and is not durable session storage. The server reloads exact-owner notes and wraps their text as untrusted context; validation and formatting are owned by [context-building.md](context-building.md).
+
+Native document tool outputs can open or refresh the document editor from tool-result metadata, so the UI can recover if a later `doc_update` stream event is missed. The chat renderer also hides raw/incomplete leaked tool JSON and document fences from normal transcript text.
 
 When untrusted external/workspace content has entered the agent context, high-impact tool calls pause as exact approval cards instead of executing. The browser can allow the rest of the interrupted task, allow this chat session, or deny; it submits only the opaque id/decision with an empty control-plane message and does not mutate the composer. The server restores the sealed first action plus private selected tools/query, revalidates policy and document freshness, consumes the first action, and resumes without persisting a synthetic user message. Task scope ends with that resumed run. Chat scope persists the resolved card and marks later context only for that exact session; forks do not inherit it. A normal message retires an unresolved card while preserving taint.
 
@@ -127,7 +104,7 @@ When untrusted external/workspace content has entered the agent context, high-im
 
 The scoped API-token chat surface is `/api/v1/chat`. Browser chat routes can receive bearer-auth state from middleware, but route code must not assume `"api"` is a durable owner; API-token support requires explicit scope checks and token-owner attribution.
 
-Incognito disables memory, skill, and chat-history tools and skips assistant DB persistence, but current user-message persistence and later cleanup are not a strict no-write guarantee. Treat incognito changes as security-sensitive until that contract is clarified.
+Incognito skips durable user and assistant message writes, supplies the current user turn ephemerally without duplicate insertion, avoids loading saved transcript history, and disables memory/skill/history context paths. This is a message-history contract, not a guarantee that every route, session header or auxiliary operation performs no write.
 
 ## Search Boundary
 
@@ -144,11 +121,31 @@ Incognito disables memory, skill, and chat-history tools and skips assistant DB
 - Docker/native endpoint differences are owned by runtime/model setup, but chat sessions depend on the saved endpoint URLs and headers.
 - Copying a response from the UI copies the displayed answer text and omits hidden reasoning/thinking segments.
 
+## Turn Preparation And Durable Background Results
+
+Chat preparation derives request authority separately from tool inventory. `src.turn_contract` selects capability families and required reads for compact/native routes; exact approval continuations, the TUI surface, and full-schema routes opt out of that selection path. Endpoint/model tool modes and the clean-route aliases (`cleanv3`, `preheret`) influence routing; the shared runtime-selection helper determines whether both context preparation and execution use compact v3. Full-schema models retain the complete enabled inventory subject to server permission gates.
+
+Sessions persist independent memory-extraction, memory-injection, and skill-injection toggles, thinking mode, temperature/max-token overrides, workspace `cwd`, endpoint id, accumulated token totals, and cost. Session hydration restores these values. Generated images are preserved when a session is deleted unless image deletion is explicitly requested.
+
+`src.background_tool_jobs.BackgroundToolJobs` stores tool-work origin and once-only chat delivery in `BackgroundToolJob` SQL rows. This is separate from process-local detached SSE buffers and disk-backed shell jobs. Result context is reconstructed from background metadata; a durable completion must remain attributed to its originating owner/session.
+
+## Session Preparation Details
+
+Credential recovery selects the session's bound enabled URL-matching endpoint before resolving its provider-auth id; a deleted/disabled bound endpoint does not trigger selection of another account. Legacy unbound recovery chooses the oldest enabled owner-visible URL-matching `ModelEndpoint` by creation time/id and persists `endpoint_id` before resolving runtime headers. Client/TUI context is bounded untrusted metadata, not admission, workspace grants or permission to execute supplied verifier commands. Context-info exposes bounded tool/skill/AGENTS path inventory rather than instruction bodies; host existence details are admin-only.
+
+Header persistence retries selected SQLite locked failures with bounded backoff and can continue in memory after exhaustion; it does not guarantee durability. Session listing uses owner-filtered unarchived database rows, hides synthetic trace sessions and treats empty sessions according to persisted messages/documents/images or live state. Synthetic `sft_` trace capture is enabled by default unless opted out; prefix selection and trash/tombstones are not data erasure guarantees. Auto-title uses a bounded utility call and a short word-based fallback.
+
+Active document state is owner-checked and chat-bound. An explicitly empty active-document state disables fallback, minimized editors do not resurrect context, and session switches preserve the exact active document rather than selecting the first cached document. A stream run id identifies streamed UI replacement and differs from nested execution-journal identity. Structured turn replacement and terminal error events preserve partial content without claiming a successful completion. Background tool delivery attribution is separate from provider success and disk-backed shell result delivery.
+
+## History Truncation And Cleanup
+
+`routes/history/history_routes.py` verifies session ownership before parsing truncation requests. The body must be a JSON object with an explicit `keep_count` or nonblank string `before_msg_id` (`message_id` alias); null/empty primary IDs fall through to the alias, while other nonstrings fail. Counts accept nonnegative integers or integer strings, rejecting booleans, floats, null and negative values. A missing message boundary returns 404 before history mutation; explicit zero remains a supported clear operation. Invalid JSON/targets return 400 without deleting saved messages or SFT trace pairs. Cleanup uses durable message rows and rechecks the count at deletion; see `persistence.md`.
+
 ## Current Gaps
 
 - Chat, agent, research, and compare orchestration still meet in a large route file.
 - Context preface behavior is spread across `routes/chat_helpers.py`, `src/chat_processor.py`, route injections, and agent/tool paths.
 - Detached stream lifecycle spans `routes/chat_routes.py`, `src/agent_runs.py`, `static/js/chat.js`, `static/js/sessions.js`, and non-chat callers.
 - Some frontend stream state is still global/module-level in `static/js/chat.js` and needs careful session isolation when adding background or resumable flows.
-- Chat lacks route-level SSE regression tests for `/api/chat_stream`, live resume/stop/status, mode handoff, persistence metadata, partial-save behavior, attachment/doc-update events, browser timezone offset/workspace handling, and literal URL context intent.
-- Bearer-token behavior on browser chat routes and incognito persistence need explicit contract decisions and regression coverage.
+- Route scope, stream errors, tool-policy preprocessing, request contracts, and runtime preparation have focused tests; full browser/provider/resume behavior still spans several modules.
+- Scoped bearer admission and incognito message-history handling have focused regressions; they do not establish a universal no-write or live provider guarantee.
diff --git a/specs/compare.md b/specs/compare.md
index a68f39716..3a4d77e6d 100644
--- a/specs/compare.md
+++ b/specs/compare.md
@@ -1,6 +1,6 @@
 # Compare
 
-Last updated: dev@e71f8ce | 2026-08-25
+Last updated: dev@c74f475 | 2026-10-15
 
 ## Scope
 
@@ -40,11 +40,9 @@ Frontend compare behavior is split by responsibility:
 - `panes.js` and `stream.js` own paired response rendering;
 - `vote.js` and `scoreboard.js` own voting and history display.
 
-Compare panes can receive `ask_user` or tool-approval controls from the shared chat stream. `static/js/compare/stream.js` routes those controls into the main chat renderer/control plane, pauses pane completion/autograding while a choice is pending, and can resume the pane after the user decision; compare orchestration keeps its busy state until those continuations settle.
+Compare panes can receive `ask_user` or tool-approval controls from the shared chat stream. `static/js/compare/stream.js` renders shared choice controls inside the originating pane history, pauses pane completion/autograding while a choice is pending, and resumes only while the pane session still matches. Continuation waits for the originating controller to release the pane, restores the card after a ten-second timeout, and refuses to send a stale choice into a replacement controller; compare orchestration keeps its busy state until those continuations settle.
 
-Mobile compare layout collapses multi-pane grids to a single column so panes
-remain readable on narrow screens while the desktop grid still uses the
-selected column count.
+Mobile compare uses selectable pane tabs and one visible active pane; desktop retains the selected multi-column grid. Pane add/remove/shuffle paths keep active-tab and session/settings indices aligned.
 
 ## Ownership Boundaries
 
@@ -69,6 +67,14 @@ Compare frontend code is part of the app DOM security surface. Current stream/se
 - Shared legacy `ModelEndpoint.owner == NULL` rows remain visible through owner filters. Legacy `Comparison.owner == NULL` rows are not treated as shared for authenticated vote/delete/history flows.
 - `/api/compare/start` and `/{comp_id}/vote` remain implemented but are not the active frontend path.
 
+## Per-Pane Generation Controls
+
+`static/js/compare/panes.js` owns per-pane inference controls and saves `thinking_mode`, `temperature_override`, and `max_tokens_override` to `/api/session/{id}/generation-settings`. The backend session/provider path owns the actual generation semantics. Pane creation initializes overrides, removal and shuffle preserve index alignment, and mandatory-thinking model controls are disabled where identified. `stream.js` renders response statistics including token/latency/context/cost metrics and the thinking-off indicator; compare header statistics open a compact details popup.
+
+## Shared Celebration Renderer
+
+`static/js/compare/vote.js` imports and reexports `spawnConfetti` from `static/js/shared/ui/confetti.js`, published from `frontend/src/shared/ui/confetti.js`. Notes imports the shared renderer directly; voting no longer owns its implementation. Vote behavior and callers retain the compatibility export.
+
 ## Current Gaps
 
 - Blind mode is not a confidentiality boundary; client/local state can still expose model identity before vote.
diff --git a/specs/context-building.md b/specs/context-building.md
index 3101e26ee..879128bfe 100644
--- a/specs/context-building.md
+++ b/specs/context-building.md
@@ -1,6 +1,6 @@
 # Context Building
 
-Last updated: dev@e71f8ce | 2026-08-25
+Last updated: dev@86b886c | 2026-10-15
 
 ## Scope
 
@@ -9,10 +9,10 @@ This spec covers model-context construction in:
 - `src/chat_processor.py`;
 - `src/chat_handler.py` and `src/youtube_handler.py`;
 - `routes/chat_helpers.py` and context injection in `routes/chat_routes.py`;
-- `src/agent_loop.py`;
+- `src/agent_loop.py`, `src/clean_agent_preview.py`, `src/turn_contract.py`, and `src/agent_runtime/context_resolution.py`;
+- `src/media_ingress.py`, `src/agent_tools/media_tools.py`, and `src/email_attachment_text.py`;
 - `src/tool_execution.py`;
-- `src/attachment_refs.py` and uploaded-file manifest construction in
-  `routes/chat_helpers.py`;
+- `src/attachment_refs.py` and uploaded-file manifest construction in `routes/chat_helpers.py`;
 - `src/tool_policy.py`;
 - `src/prompt_security.py`;
 - `src/tool_capabilities.py`, `src/tool_approval_scopes.py`, and `src/tool_approvals.py`;
@@ -53,12 +53,9 @@ Current untrusted context sources include:
 - emails and attachments;
 - tool output from external/user-controlled data.
 
-Live multimodal provider blocks can contain data URLs, but persisted and
-tool-facing context uses stable attachment references. Tool manifests carry an
-`odysseus://attachment/<id>` URI and owner-checked read policy; local paths are
-compatibility data added only after owner and root-confinement checks. Persisted
-chat context keeps readable text/reference lines rather than reinserting raw
-media bytes into later turns or search state.
+Live multimodal provider blocks can contain data URLs, but persisted and tool-facing context uses stable attachment references. Tool manifests carry an `odysseus://attachment/<id>` URI and owner-checked read policy; local paths are compatibility data added only after owner and root-confinement checks. Persisted chat context keeps readable text/reference lines rather than reinserting raw media bytes into later turns or search state.
+
+`/api/chat_stream` accepts explicitly selected Notes/Todos through the JSON form field `selected_note_ids`. `routes.chat_routes._parse_selected_note_ids()` limits the encoded field to 8192 characters and the array to 50 nonempty string IDs of at most 128 characters, deduplicating valid IDs and returning `400` for malformed input. The route queries only rows whose `Note.owner` exactly matches `effective_user(request)`; missing or other-owner IDs contribute no context. Titles, content, note type, and checklist item state are formatted by `_format_selected_notes_context()` and passed to `routes.chat_helpers.build_chat_context()` as an untrusted "Selected notes and todos" preface. Selection supplies reference data, not tool authority; the preface discourages redundant retrieval or permission requests just to read those same supplied notes.
 
 ## URL, Search, And Tool-Derived Context
 
@@ -104,6 +101,24 @@ Guide-only/no-tools policy can suppress context acquisition before the model cal
 - `src.tool_execution` for `web_search`, `web_fetch`, file, shell, MCP, and other tool outputs;
 - `src.deep_research` and research handlers for search/fetch/extract flows used by research jobs, with fetched webpage text wrapped before extraction and analyzed URLs tracked separately from source snippets.
 
+## Effective Context And Media Evidence
+
+Compact preview preparation resolves the effective context window once through `src.agent_runtime.context_resolution`; terminal metrics use that stored resolution and do not trigger new discovery. Runtime-confirmed, provider-advertised, operator-declared, static-table, and unknown evidence remain distinct, with conflicts recorded. Operator declarations can cap stronger evidence; unknown is represented as zero rather than an invented known limit. Metadata probing has a three-second preparation deadline, caches remote observations, and re-probes local serving processes. Legacy chat/agent budgeting remains a separate compatibility path.
+
+`src.context_compactor` trims context and prunes multimodal images. Session memory-injection and skill-injection toggles independently control preface construction; memory extraction is a separate session setting. `src.skill_index` semantically ranks native skills using an already-ready ToolIndex embedding lane, with lexical fallback, while `search_chats` retrieves owner-scoped historical messages instead of making all history ambient context.
+
+`src.media_ingress` limits file counts, source/encoded bytes, image dimensions/pixels, document characters, video frames, and probe/extraction time. Native media tools return observed media/text evidence through the same untrusted-result path; filenames and model guesses do not establish inspected image/video content. `src.email_attachment_text` supplies shared attachment text extraction for mail context.
+
+## Resolution And Embedding Limits
+
+`src.agent_runtime.context_resolution.ContextResolution` binds effective context evidence to the resolved endpoint/model before compact preparation shapes history. The stored resolution feeds terminal metrics without another discovery call. A legacy shaping default does not turn unknown evidence into a known limit; a bare integer cannot supply typed provenance. Metadata requests use the turn's provider headers only at configured or server-resolved provider origins, without credential-following redirects, and endpoint URLs stay out of serialized resolution metrics. Remote observations cache for 600 seconds, failures for 60 seconds, while local servers are re-probed.
+
+`src.embeddings` accepts an explicit `FASTEMBED_THREADS` integer from 1 through 256 and raises for malformed or out-of-range values rather than silently changing the requested execution setting. This controls embedding setup, not proof of a ready vector service.
+
+## Compact Source Projection
+
+Compact editor/email preparation can use current memory and bounded prior-source references without importing arbitrary hidden document bodies. The email classifier supplies dependency evidence for the selected path, not a general model-routing authority. Document edits are bounded batches with per-edit outcomes: a saved `doc_update` is distinct from an unapplied suggestion, exact unique-text matching can reject an ambiguous suggestion, and partial success does not mean every proposed edit was saved.
+
 ## Current Gaps
 
 - URL/search context result shape is not unified across chat prefetch, agent tools, and research.
diff --git a/specs/cookbook-hwfit.md b/specs/cookbook-hwfit.md
index 7c9fcb5c0..56b1be6eb 100644
--- a/specs/cookbook-hwfit.md
+++ b/specs/cookbook-hwfit.md
@@ -1,6 +1,6 @@
 # Cookbook And Hardware Fit
 
-Last updated: dev@e71f8ce | 2026-08-25
+Last updated: dev@86b886c | 2026-10-15
 
 ## Scope
 
@@ -40,7 +40,7 @@ Access policy is split by surface:
 
 - download/setup/SSH key/cache scan/serve/GPU/kill/state/task-status are admin/internal-tool surfaces;
 - `/api/cookbook/hf-latest` is authenticated-user gated;
-- HW Fit routes are authenticated read/probe routes through normal middleware, not admin-only operations;
+- HW Fit routes carry a router-wide admin dependency because host/model-path probes can use server SSH/filesystem authority;
 - bearer API tokens do not satisfy Cookbook admin gates.
 
 Runtime behavior:
@@ -130,7 +130,7 @@ Runtime behavior:
 
 - Linux, Windows/PowerShell, macOS, Docker, NVIDIA, AMD, Apple Silicon, and CPU-only systems have different command paths.
 - Remote hosts are accessed through SSH helpers; Cookbook host/port/path inputs must be validated before command construction.
-- HW Fit remote host/port query values currently do not share all Cookbook route-level validation before SSH probing.
+- HW Fit detection targets use shared host/port validation before remote probing; the router-wide admin gate still owns admission.
 - Missing local tools or failed installs should surface command/output/error detail where possible.
 - GPU overlays remain optional and do not break CPU-only deployments.
 - Docker GPU overlays pass host devices/env; they do not install CUDA/ROCm engines by themselves.
@@ -188,6 +188,18 @@ Existing coverage is strongest for helper validation/quoting, SSH host validatio
 
 Route-level auth/security and degraded-return coverage is thinner for Cookbook admin routes, shell dependency routes, `/api/cookbook/hf-latest`, state/status edge cases, HW Fit routes, frontend JS behavior, and helper scripts such as `hf_download.py`, `add_hwfit_models.py`, and `diffusion_server.py`.
 
+## Native Control And Adapter Contracts
+
+`routes/cookbook_routes.py` gates native download/serve producers even when scoped wrappers call them directly. Local tools use a one-use admitted operation/backend/body capability from `src.agent_runtime.local_model_control`; fallback administration uses the shell admin gate. Kill-PID, SSH-key and state mutation do not inherit that model capability. Remote operations retain separate validation and admin requirements.
+
+Cached-model scans pass request-owned script bytes over subprocess stdin instead of sharing `scan_cache.py`; cancellation/timeout terminates that request's scanner. Image serving accepts a shell-safe explicit `runtime_adapter`, passes it as `ODYSSEUS_MLX_IMAGE_ADAPTER`, and retains `auto` detection with dependency preflights. HW Fit ranking carries image dependency-package metadata; native AWQ rows no longer require multiple GPUs on otherwise supported accelerator platforms.
+
+## Native Process And Catalog Limits
+
+Tool-reachable local Cookbook stop refuses legacy unadmitted tmux/process targets with resource-identity denial before scanning or killing; native model capabilities admit only the exact owner/request/backend/body and consume once. Scheduled native serving requires the sealed capability, while remote/operator HTTP flows retain their distinct validation. Procfs discovery returns empty when procfs is unavailable and cannot prove absence or authorize survivor reclamation. Shared process cleanup freezes known descendants, checks start tokens and observes death; uncertain identity is retained, with unavoidable signal/observation races rather than guaranteed portable teardown.
+
+Image collection refresh has a short in-memory and longer disk cache; network failure can preserve stale model data rather than force an empty catalog. Latest lookup and organization prefilters use external metadata and heuristic first-party/format/parameter sizing; fit estimates (including a 90-percent VRAM budget) are recommendations, not measured serving acceptance. Bundled HF/MLX inventories remain empty in final source, and generated inventory inspection is separate from consumer/schema review.
+
 ## Current Gaps
 
 - Cookbook-created model endpoint ownership/shared/null-owner policy needs a deliberate decision.
diff --git a/specs/documents-rag-uploads.md b/specs/documents-rag-uploads.md
index 18914be54..b92cace0d 100644
--- a/specs/documents-rag-uploads.md
+++ b/specs/documents-rag-uploads.md
@@ -1,6 +1,6 @@
 # Documents, RAG, And Uploads
 
-Last updated: dev@e71f8ce | 2026-08-25
+Last updated: dev@c74f475 | 2026-10-15
 
 ## Scope
 
@@ -10,8 +10,7 @@ This spec covers file/document context, document storage, and vector retrieval i
 - `routes/upload_routes.py`, `routes/personal_routes.py`, `routes/embedding_routes.py`, canonical `routes/document/document_routes.py` and `routes/document/document_helpers.py`, plus their top-level compatibility shims;
 - chat attachment paths in `routes/chat_routes.py`, `routes/chat_helpers.py`, `src/chat_handler.py`, and `src/chat_processor.py`;
 - `core/session_manager.py`, `src/attachment_refs.py`, `src/upload_handler.py`,
-  `src/upload_limits.py`, and the public reference contract in
-  `docs/attachments.md`;
+  `src/upload_limits.py`, and the public reference contract in `website/attachments.md`;
 - `src/document_processor.py`, `src/document_actions.py`, `src/personal_docs.py`, and `src/markitdown_runtime.py`;
 - `src/rag_singleton.py`, `src/rag_vector.py`, `src/rag_manager.py`, `src/chroma_client.py`, `src/embeddings.py`, and `src/embedding_lanes.py`;
 - PDF/form helpers in `src/pdf_runtime.py`, `src/pdf_forms.py`, and `src/pdf_form_doc.py`;
@@ -54,45 +53,17 @@ Chat does not own attachment extraction. Runtime flow:
 - `src.document_processor.build_user_content()` produces model-ready text, PDF text, Office/EPUB text when MarkItDown or the DOCX fallback is available, image/multimodal blocks, truncation, and PDF/Office auto-document updates;
 - chat streams attachment, PDF-created `doc_update`, and `rag_sources` events where applicable.
 
-Extensionless image and audio attachments derive their data-URI subtype from
-the detected MIME type, so `image/png` and `audio/mpeg` uploads do not become
-invalid `data:image/;base64` or `data:audio/;base64` blocks when the filename
-has no extension.
+Extensionless image and audio attachments derive their data-URI subtype from the detected MIME type, so `image/png` and `audio/mpeg` uploads do not become invalid `data:image/;base64` or `data:audio/;base64` blocks when the filename has no extension.
 
 ## Durable References And Cleanup
 
-`src.attachment_refs` owns the stable `attachment_ref` shape used outside raw
-upload storage: attachment id, name, MIME type, size, and optional checksum,
-creation time, dimensions, vision text/model, and gallery id. Live provider
-calls may still receive multimodal data URLs for the current turn, but durable
-chat content is normalized to readable text plus compact reference lines.
-Structured references remain in message attachment metadata, and chat FTS
-triggers omit inline media while startup migration scrubs legacy indexed data
-URLs.
+`src.attachment_refs` owns the stable `attachment_ref` shape used outside raw upload storage: attachment id, name, MIME type, size, and optional checksum, creation time, dimensions, vision text/model, and gallery id. Live provider calls may still receive multimodal data URLs for the current turn, but durable chat content is normalized to readable text plus compact reference lines. Structured references remain in message attachment metadata, and chat FTS triggers omit inline media while startup migration scrubs legacy indexed data URLs.
 
-Agent/tool manifests expose `odysseus://attachment/<id>` with
-`read_policy: "owner_checked_upload"`. A compatibility filesystem path is
-included only after owner-aware upload resolution, upload-root confinement, and
-tool-readable-root checks; the stable contract for external tools is the URI
-and attachment id, not host layout.
+Agent/tool manifests expose `odysseus://attachment/<id>` with `read_policy: "owner_checked_upload"`. A compatibility filesystem path is included only after owner-aware upload resolution, upload-root confinement, and tool-readable-root checks; the stable contract for external tools is the URI and attachment id, not host layout.
 
-Writers reserve referenced uploads before committing durable state. This
-includes session message append/replace and history rewrites, document
-create/update and native document edits, note route/tool create/update,
-calendar/event route/tool create/update, and attachment-bearing session
-updates. A missing or wrong-owner reference aborts before destructive
-replacement and surfaces a route conflict or tool error. Reservations serialize
-with cleanup through the upload-index lock and refresh access time.
+Writers reserve referenced uploads before committing durable state. This includes session message append/replace and history rewrites, document create/update and native document edits, note route/tool create/update, calendar/event route/tool create/update, and attachment-bearing session updates. A missing or wrong-owner reference aborts before destructive replacement and surfaces a route conflict or tool error. Reservations serialize with cleanup through the upload-index lock and refresh access time.
 
-Admin cleanup first scans chat content and attachment metadata, current and
-versioned documents including PDF markers, gallery filenames/hashes, note
-image/color/content/checklist fields, and calendar color/description/location
-fields. Reference discovery or index-integrity failure aborts cleanup; the
-lower-level API removes nothing without both completed id and hash snapshots.
-Only expired, unreferenced files with coherent id/path/owner/checksum/timestamp
-metadata are candidates. Matching index rows are persisted away before byte
-deletion and restored if deletion fails. This lock is process-local, so the
-documented race protection assumes the current single-worker deployment.
+Admin cleanup first scans chat content and attachment metadata, current and versioned documents including PDF markers, gallery filenames/hashes, note image/color/content/checklist fields, and calendar color/description/location fields. Reference discovery or index-integrity failure aborts cleanup; the lower-level API removes nothing without both completed id and hash snapshots. Only expired, unreferenced files with coherent id/path/owner/checksum/timestamp metadata are candidates. Matching index rows are persisted away before byte deletion and restored if deletion fails. This lock is process-local, so the documented race protection assumes the current single-worker deployment.
 
 ## Living Documents And PDF
 
@@ -100,19 +71,13 @@ documented race protection assumes the current single-worker deployment.
 
 `static/js/documentLibrary.js` owns local library state after archive/delete actions, including total counts and language chips. Server route truth still owns durable document state.
 
-`static/js/document.js` owns the browser document editor and markdown preview. Preview rendering applies code highlighting when highlight.js is present, renders Mermaid diagrams when the Mermaid runtime is available, refreshes after AI edits, and discards pending AI diffs before switching the active document.
+`static/js/document.js` owns the browser document editor, a sanitized rich-text editing view and Markdown source/preview. Preview rendering applies code highlighting when highlight.js is present, renders Mermaid diagrams when the Mermaid runtime is available, refreshes after AI edits, and discards pending AI diffs before switching the active document.
 
 Document mutations also happen through agent tools, Codex document routes, email attachment import, and scripts. HTTP and native-agent document writers owner-reserve any internal upload/PDF references before persisting new current content or versions. Native document tool outputs include metadata that the browser can use to open/update the editor if a later stream update is missed. Those callers must preserve document owner, attachment, and version semantics.
 
 After external/workspace-untrusted context, a proposed document mutation is sealed into an exact approval with document id, current version, content digest, tool content, owner/session, and workspace. Approval continuation re-reads and verifies those fields before consuming the one-use authorization, so an intervening edit cannot apply a stale approved patch to new content.
 
-Email draft documents are a first-class document language. Create/update paths
-detect the `To`/`Subject`/header shape, coerce language to `email`, and preserve
-protected reply/forward headers such as `In-Reply-To`, `References`,
-`X-Source-UID`, `X-Source-Folder`, attachment headers, and quoted/original
-history when model or UI edits replace the draft body. Creating a draft for the
-same source UID/folder in the same session updates the active draft instead of
-creating a duplicate.
+Email draft documents are a first-class document language. Create/update paths detect the `To`/`Subject`/header shape, coerce language to `email`, and preserve protected reply/forward headers such as `In-Reply-To`, `References`, `X-Source-UID`, `X-Source-Folder`, attachment headers, and quoted/original history when model or UI edits replace the draft body. Creating a draft for the same source UID/folder in the same session updates the active draft instead of creating a duplicate.
 
 `Document` rows own current content and owner. `DocumentVersion` rows own immutable snapshots. Document access should be owner-filtered, not session-id-only; the session document listing path still needs regression coverage for per-document owner filtering after the session owner check.
 
@@ -163,7 +128,7 @@ Some non-route tool/script paths can index ownerless or arbitrary directories an
 ## Optional And Degraded Behavior
 
 - ChromaDB/FastEmbed are default installed dependencies, but Chroma can be offline or unreachable.
-- Native Chroma defaults to `localhost:8100`; Docker uses the `chromadb:8000` compose service and persistent Chroma storage.
+- Native Chroma defaults to `localhost:8100`; Docker uses the `chromadb:8000` compose service with `chromadb-data:/data` in all three Compose variants. Pre-fix containers can hold live vectors in their writable layer; preserve/rescue that data before recreation using `docs/chromadb-volume-migration.md`.
 - HTTP embeddings can fall back to FastEmbed; when both lanes exist, lane separation avoids Chroma dimension conflicts.
 - MarkItDown is optional for Office/EPUB extraction; chat attachments and personal directory indexing have clear degraded behavior, while direct RAG upload does not share the same extraction path.
 - PyMuPDF is optional, unlocks PDF form/render/fill paths, and carries AGPL implications when installed.
@@ -186,7 +151,7 @@ Concrete enforcement points include:
 
 Extracted attachment text is currently appended into the user message rather than wrapped as a separate untrusted-context message. That is current behavior and a prompt-injection hardening gap.
 
-Bearer-token callers are not a scoped document/upload API surface today. Routes that treat token-authenticated users as owners need explicit scope/effective-user policy before they are considered safe token APIs.
+Browser document routes still need explicit bearer-token scope/effective-user policy. Upload endpoints have their own delegated owner/scope gates described below; that contract does not extend to every document/PDF/RAG route.
 
 ## Testing Coverage
 
@@ -194,6 +159,26 @@ Existing useful coverage includes upload owner scope, upload IDs, upload atomici
 
 Route-level coverage is thinner for document CRUD, PDF import/render/export/fill, direct RAG upload, embedding admin/security behavior, and RAG unavailable states.
 
+## Preserved Originals And Document Views
+
+`POST /api/documents/import-docx` requires document privilege, verifies any supplied session owner, stores the original through `UploadHandler`, extracts Markdown, and creates a `docx` document with a `docx_source` upload marker. `GET /api/document/{doc_id}/render-docx` checks document and source-upload visibility, uses Mammoth to return an HTML fragment for client sanitization, and returns 503 when Mammoth is absent. The frontend supplies a paper preview while extracted text remains available for editing/search/model context.
+
+`GET /api/document/{doc_id}/convert-original/{target}` converts preserved DOCX to PDF or PDF to DOCX directly with host LibreOffice/soffice, after document privilege, ownership, and source-upload checks. It uses a temporary output directory and isolated LibreOffice profile in a worker thread with a 120-second subprocess timeout; it does not convert from extracted Markdown. Missing LibreOffice returns 503, timeout 504, and unsuccessful output 502.
+
+Markdown documents can open `GET /api/document/{doc_id}/visual-report`, reusing `src.visual_report.generate_visual_report()` after document ownership validation. ZIP export recognizes email drafts as `.eml` and converts their header/body separator into an RFC-style blank line. The frontend document graph now also includes `documentOutline.js` and `documentStats.js`.
+
+## Editing And Export Boundaries
+
+Rich-text editing mirrors a textarea and supports formatting, checklists, images and tables through sanitized contenteditable content. Internal markers are removed from export; converting rich text/Markdown into simple DOCX paragraphs is lossy and does not preserve arbitrary Word layout. Browser PDF export uses a script-disabled print iframe with same-origin/modal allowances, waits for fonts/styles/images/math and cleans up afterward; server PDF rendering and preserved-original LibreOffice conversion are separate paths.
+
+Per-document save queues serialize requests and track edit revisions so intervening edits remain marked dirty; this does not promise that every cached response body preserves a newer in-memory edit. Restoring the editor targets the exact active document. Suggestions apply only when the exact find text is unique, report partial applied/unapplied suggestion IDs and retain unapplied review state; server-saved edits suppress duplicate frontend application. Protected email envelope/history remains distinct from editable draft content. PDF/signed-reply preparation still has late async ownership/account edge cases requiring targeted checks.
+
+## Upload Authentication And Delegated Scopes
+
+`routes/upload_routes.py` explicitly bypasses upload ownership/auth-service gates only when auth is disabled, including after accounts were configured. With auth enabled, missing auth manager returns 503, an unconfigured manager returns 401, and missing/request-sentinel identity returns 403. Reads, thumbnails and vision reads/edits use `_verify_upload_access()` before confined path access. Interactive owners may access their uploads; verified interactive admins may access other owners and legacy ownerless uploads. Delegated tokens never inherit that administrator override and require an actual token owner matching a non-null file owner.
+
+Delegated creation and OCR edits require any of `chat` or `documents:write`; downloads/thumbnails/OCR reads accept any of `chat`, `documents:read`, `documents:write`. Missing/unrelated scopes and invalid token owners fail with 403; owner mismatch/ownerless token access uses 404. POST saves effective owner attribution and clears request-sentinel owners. No-login anonymous uploads can remain null-owned and become interactive-admin-only after auth is enabled. Size/type/filename/path validation remains active in no-login mode; these gates do not replace the global authentication middleware.
+
 ## Current Gaps
 
 - Direct RAG upload still needs clearer file-type validation and MarkItDown/PDF extraction parity decisions.
@@ -201,5 +186,5 @@ Route-level coverage is thinner for document CRUD, PDF import/render/export/fill
 - Chat RAG can remain degraded after startup even if personal routes later initialize the RAG singleton.
 - PyMuPDF-dependent routes do not all share the same optional-runtime helper/error behavior.
 - Signed-reply preparation needs owner-scoped source email account/signature regression coverage.
-- Document/upload routes need explicit bearer-token scope/effective-user policy.
+- Browser document/PDF/RAG routes need explicit bearer-token scope/effective-user policy beyond the upload endpoint contract above.
 - User-facing document/PDF/RAG route matrices need more regression coverage for owner denial, admin gates, unavailable services, and degraded optional dependencies.
diff --git a/specs/email-contacts.md b/specs/email-contacts.md
index 204a97b57..b2f71841b 100644
--- a/specs/email-contacts.md
+++ b/specs/email-contacts.md
@@ -1,6 +1,6 @@
 # Email And Contacts
 
-Last updated: dev@2e2bb52 | 2026-08-16
+Last updated: dev@c74f475 | 2026-10-15
 
 ## Scope
 
@@ -39,7 +39,7 @@ This spec covers mail and contacts in:
 
 Exactly one default account per owner is enforced as a serialized database transition. Startup normalizes legacy duplicate defaults and installs a unique per-owner default constraint/index; first create, delete/promotion, set-default, demo teardown, and owner rename lock the relevant owner rows and commit atomically. Multi-owner rename acquires locks in canonical order so stale concurrent writers fail closed.
 
-`routes.email_helpers` owns:
+`routes.email.email_helpers` owns (flat imports remain compatibility aliases):
 
 - account owner assertions and config fallback order;
 - IMAP/SMTP connection helpers and related transport utilities;
@@ -57,11 +57,9 @@ Email owner semantics are route-local and compatibility-sensitive:
 - `routes.email_helpers._require_auth()` returns `""` in `AUTH_ENABLED=false` mode, rejects configured auth with no user, and only tolerates first-run anonymous loopback fallback.
 - Empty owner is treated as single-user compatibility: account-ownership assertions no-op, default/first-enabled account fallback can be global, and email cache clauses include `owner = '' OR owner IS NULL`.
 - Non-empty owners scope account/config/cache queries. Legacy ownerless account
-  rows are visible to an authenticated owner only when the row's IMAP username
-  or from-address matches that owner, so old unowned rows do not become global
-  cross-user accounts in configured multi-user deployments.
+  rows are visible to an authenticated owner only when the row's IMAP username or from-address matches that owner, so old unowned rows do not become global cross-user accounts in configured multi-user deployments.
 
-`routes.email_routes` owns the HTTP mail surface:
+`routes.email.email_routes` owns the HTTP mail surface:
 
 - account CRUD, test, default, and masked config reads;
 - Google OAuth authorize/callback for Workspace and .edu Gmail-style accounts;
@@ -91,7 +89,7 @@ IMAP helpers quote mailbox names, raise the Python IMAP line cap for large messa
 
 Scheduled email rows live in `data/scheduled_emails.db` and are owner-scoped. Scheduled send times are normalized before storage.
 
-`routes.email_pollers` owns the scheduled-send poller and single-shot/task/CLI automation passes. Before SMTP work, each poller atomically claims a due row with a conditional `pending` to `sending` update; concurrent in-process/CLI pollers that lose the claim skip the row instead of sending a duplicate. Only the scheduled-send poller starts in-process by default when `ODYSSEUS_INPROCESS_POLLERS` allows it; Docker forwards that gate. Background email automation can also consult the foreground activity gate so auto actions do not compete with active browser/model work. Native cron/systemd can drive one-shot pollers through `scripts/odysseus-mail`.
+`routes.email.email_pollers` owns the scheduled-send poller and single-shot/task/CLI automation passes. Before SMTP work, each poller atomically claims a due row with a conditional `pending` to `sending` update; concurrent in-process/CLI pollers that lose the claim skip the row instead of sending a duplicate. Only the scheduled-send poller starts in-process by default when `ODYSSEUS_INPROCESS_POLLERS` allows it; Docker forwards that gate. Background email automation can also consult the foreground activity gate so auto actions do not compete with active browser/model work. Native cron/systemd can drive one-shot pollers through `scripts/odysseus-mail`.
 
 Manual and scheduled summaries use the shared LLM adapter and owner-scoped cache instead of constructing provider calls locally. Scheduled summaries use background fallback policy and yield to foreground work; provider exception text is shaped before it can reach the browser.
 
@@ -107,9 +105,9 @@ Transport degraded behavior:
 
 ## Caching And Staleness
 
-Email list/read behavior uses short route caches, longer read caches, capped warm prefetch, and owner/account-aware pool/cache keys. The frontend email library has its own session SWR cache, cache-buster refreshes, scheduled/search cache exclusions, and stale-row behavior when refresh fails.
+Email list/read behavior uses short route caches, longer read caches, capped warm prefetch, and owner/account-aware pool/cache keys. The frontend email library has bounded in-memory and local caches, cache-buster refreshes, scheduled/search cache exclusions and stale rows on refresh failure. A cached early return is not a universal stale-while-revalidate guarantee.
 
-Opening an unread message is one authoritative backend IMAP operation. The read route fetches/parses the message and applies `\Seen` over the same connection; cached bodies still await one UID STORE, read-only mailboxes serve content without claiming a mark, and STORE failure returns the body with explicit failure state rather than caching a false read. Inbox/library clients deduplicate opens, carry immutable mailbox context, and ignore late responses after account, folder, or message changes.
+Opening an unread message is one authoritative backend IMAP operation. The read route fetches/parses the message and applies `\Seen` over the same connection; cached bodies still await one UID STORE, read-only mailboxes serve content without claiming a mark, and STORE failure returns the body with explicit failure state rather than caching a false read. Inbox/library clients deduplicate opens and carry mailbox context with selected request-generation guards. Those guards are not universal: some detached/inline completions still use mutable account/folder state, so late-response safety must be assessed per path.
 
 Library prewarm runs only while genuinely idle, as one bounded single-flight request for the default or last-used enabled account and initial page. Visible foreground work, panel lifecycle, account changes, or explicit reads cancel or join it so delayed duplicate IMAP work cannot escape the idle gate.
 
@@ -117,7 +115,7 @@ List/read route caches are owner/account-aware. Helper-side summary, AI-reply, t
 
 ## Attachments And Signed Replies
 
-Compose uploads live under `ODYSSEUS_MAIL_ATTACHMENTS_DIR`; missing staged files are skipped with warnings. Attachment-to-document supports PDF, DOCX, TXT, and MD. DOCX depends on `python-docx`; PDF form/open-in-doc flows can depend on optional PyMuPDF.
+Compose uploads live under `ODYSSEUS_MAIL_ATTACHMENTS_DIR`; missing staged files are skipped with warnings. Attachment-to-document supports PDF, DOCX, TXT, and MD. DOCX attachment-to-document extraction uses MarkItDown first; optional LibreOffice conversion has a 60-second bound and can supply a PDF preview, otherwise extracted Markdown remains available; PDF form/open-in-doc flows can depend on optional PyMuPDF.
 
 Email attachment-as-document flows stamp `Document.source_email_*` provenance. `GET /api/email/attachments-download/{uid}` builds an owner-scoped ZIP of visible non-signature attachments using safe names. `compose-from-odysseus` and `compose-from-odysseus-zip` can stage owner-visible documents and gallery images as compose uploads, preserving legacy session fallback only where the source object remains visible to the owner. `prepare-signed-reply` verifies document ownership, reconstructs reply headers, flattens/stages signed PDFs as compose uploads, and leaves final send/draft review to the compose flow.
 
@@ -135,12 +133,7 @@ When the email reader is active, browser chat sends selected-message metadata. `
 
 `mcp_servers/email_server.py` exposes email tools for MCP/agent use. It has its own account discovery, IMAP/SMTP, attachment, cache, and send paths, but account visibility now mirrors the HTTP owner policy. The active owner comes from a hidden `_odysseus_owner` argument when the caller provides one, or from `ODYSSEUS_MCP_EMAIL_OWNER` / `ODYSSEUS_EMAIL_OWNER`. If any enabled account is owner-scoped and no current/configured owner exists, email MCP returns an owner-scope error instead of listing global accounts.
 
-MCP email account filtering includes owner-owned rows and legacy ownerless rows
-whose mailbox/from-address matches the owner. Confirmation-first `send_email`
-resolves the selected account before stashing an `agent_draft`, so drafts cannot
-be staged against another owner's account. MCP-created draft documents use the
-resolved hidden/configured owner when available, with `ODYSSEUS_DOCUMENT_OWNER`
-and single-admin fallback only as document-visibility compatibility.
+MCP email account filtering includes owner-owned rows and legacy ownerless rows whose mailbox/from-address matches the owner. Confirmation-first `send_email` resolves the selected account before stashing an `agent_draft`, so drafts cannot be staged against another owner's account. MCP-created draft documents use the resolved hidden/configured owner when available, with `ODYSSEUS_DOCUMENT_OWNER` and single-admin fallback only as document-visibility compatibility.
 
 MCP email send behavior is confirmation-first by default: `send_email` and reply send paths stash a `scheduled_emails` row with `status='agent_draft'` when `agent_email_confirm` is true, and browser routes expose pending drafts for approval or cancellation. Separate MCP draft tools create Odysseus compose documents for user review without sending.
 
@@ -161,7 +154,7 @@ Contact runtime behavior:
 - the native contacts CLI is CardDAV-oriented and does not fully match web JSON fallback behavior;
 - agent contact tools reuse helper functions in-process because the HTTP routes require browser/admin auth.
 
-Contacts are global admin-only data today. There is no per-user contact sharing model unless a future spec defines one.
+HTTP contact administration remains admin-gated, but in-process helpers have owner-aware local rows and per-owner caches. Named owners see their own rows plus legacy ownerless contacts; synthetic `sft_` owners do not see ownerless rows and bypass CardDAV. This compatibility does not establish a general cross-user sharing API.
 
 ## Security Policy
 
@@ -177,7 +170,7 @@ Known security policy details:
 - Google OAuth state and callback owner checks are part of the account-boundary contract;
 - scheduled emails must remain owner-scoped;
 - email pre-retrieval contacts context is allowed only for admin/single-user situations;
-- MCP attachment downloads need route-level path-containment parity; current MCP paths are separate from the HTTP compose/attachment helper path.
+- HTTP and MCP attachment extraction share `src.mail_attachment_paths.attachment_scope_dir()` for hashed owner/account/folder/message directories; remaining attachment consumers still need end-to-end scope/path coverage.
 
 CardDAV credentials and URLs are security-sensitive. CardDAV URL setup and derived href writes/deletes pass through outbound URL validation; absolute hrefs from a CardDAV server are constrained back to the configured origin before credentials are reused. CardDAV passwords in settings are encrypted and masked on read; environment-sourced legacy password values are used as supplied.
 
@@ -196,6 +189,30 @@ Existing coverage includes header/envelope/IMAP/SMTP behavior, serialized defaul
 
 Route-level and duplicate-path coverage is still thin for email list/read/search/mutations, account CRUD/security outside the OAuth path, send/draft security, attachments, scheduled-poller failures, contacts admin/CardDAV routes, MCP account/scope behavior, CardDAV degraded mode, and executable frontend behavior.
 
+## Mail Safety And New Library Flows
+
+Mail connection helpers resolve host addresses once and connect only to policy-approved addresses through `src.url_safety.connect_outbound_tcp()`, retaining hostname TLS verification. Link-local, non-loopback reserved, multicast and unspecified destinations are denied. IPv6 loopback and IPv4-mapped loopback follow the private-address policy rather than unconditional reserved-address denial. Exactly `64:ff9b::/96` is decoded to its IPv4 target and evaluated strictly, including all DNS answers; network-specific NAT64 prefixes are not inferred. Private/loopback/shared destinations are denied for ordinary multi-user owners, allowed for admins/auth-disabled operators, and configurable with `EMAIL_ALLOW_PRIVATE_IPS=true`; `EMAIL_BLOCK_PRIVATE_IPS=true` takes precedence and denies them for everyone.
+
+The library adds owner-scoped unread-state, attachment metadata caches, bulk attachment ZIP, flagged-message actions, translation, and reviewed unsubscribe flows. `/unsubscribe/scan` reads newsletter/spam candidates; `/unsubscribe/execute` refetches the chosen message and supports mailto unsubscribe by sending through the selected account. HTTP unsubscribe links remain a manual-open path. `/unsubscribe/cleanup` moves reviewed candidates to Junk/Trash and can expand a sender's unsubscribe-header messages. Scanning alone does not send or move mail.
+
+`src.mail_attachment_paths` hashes the full owner/account/folder/UID scope into an extraction directory so legacy ownerless paths cannot reuse another mailbox's staged attachment. `src.email_attachment_text` centralizes readable attachment extraction. Email calendar pollers apply ICS revisions through `src.email_calendar_import`; invitation state and reminder semantics are described in `calendar-tasks-notes.md`. `src.email_task_intent` supplies email-task intent helpers, and `src.email_reply_stream` handles reply-stream text behavior.
+
+## Mailbox State And Delivery Boundaries
+
+MCP email binds owner and active session in request-local contexts and resets them on exit. Cross-account list caching is short-lived (20 seconds) and listing can use four concurrent workers; it does not promise single-flight freshness. Nonempty local header-index results can suppress a live lookup. MCP sent-time ISO ranges normalize missing zones to UTC and use an inclusive start/exclusive end; browser date-only received-time filters include the end date. Cached/fixture paths do not uniformly apply every date filter. Search pills combine terms; index fallback and at-most-six attachment search terms do not guarantee complete provider search.
+
+MCP bulk UID move fallback checks command statuses and verifies absence from the source; this is not proof of destination delivery. Browser and MCP single-message move paths instead rely on MOVE or COPY/STORE/expunge acknowledgements without a post-move source read.
+
+Browser bulk delete requires a successful native MOVE or recoverable Trash COPY before removing originals. COPY failure retains source/index; fallback STORE batches only copied UIDs for selective RFC 4315 UID EXPUNGE, never mailbox-wide EXPUNGE. Index rows are removed only after confirmed deletion. Failed selective expunge retains the index and attempts to remove newly added `\Deleted` flags while preserving observed pre-existing flags; disconnects can prevent rollback, and a lost acknowledgement is not proof the source survived. Servers without selective expunge can therefore report failure despite a Trash copy. Responses distinguish confirmed deleted and failed UIDs, total failure, and partial success; source and Trash list caches invalidate in `finally` when any deletion was confirmed. Single-message paths retain their separate behavior.
+
+Draft replacement appends the new mailbox draft before removing the old one. Sent draft cleanup follows successful Sent append; SMTP, IMAP and local database state are not one transaction. Scheduled send claims prevent concurrent claim winners, not exactly-once SMTP across a crash after send and before checkpoint.
+
+Composer sends first save a recovery mailbox draft, then use `wait_for_delivery` and preserve exact draft UID/folder for delivery cleanup. Failures/cancellation retain recoverable draft state. AI reply application checks generation/document/body snapshots and intervening manual input before overwriting. Confirmation-first MCP pending drafts are a distinct workflow. Reply-by-Message-ID resolves owner/account/UID context rather than trusting a global id; recursive fallback work is bounded and gathered on cancellation. Reply generation disables thinking, uses bounded initial output and one larger retry; this does not guarantee provider delivery.
+
+Unsubscribe scanning inspects at most the newest 500 candidates and deduplicates senders; bulk operations are bounded and can partially fail. A sent mailto attempt can move its source to Trash, while pending confirmation leaves it untouched; successful send-attempt bookkeeping is not confirmation that a remote subscription ended. Blocked-sender JSON is owner-keyed but not transactionally coupled to mailbox changes. Bulk attachment ZIP is capped at 250 messages in batches of twenty, skips failed messages, uses safe names and assembles in memory.
+
+Reader HTML snapshots use inert parsing/sanitization and sandbox/CSP constraints; blocked network in browser tests is a test condition rather than universal runtime network isolation. Attachment-only/media-only bodies remain meaningful; a thumbnail `img.src` is not itself a URL sanitizer. Local reminder metadata can identify folder/UID without an account and is a narrower compatibility path than canonical mailbox identity. Contact cache success/failure windows and shared refresh locking do not turn a CardDAV outage into local-write success.
+
 ## Current Gaps
 
 - Owner-keyed cache policy still needs an explicit decision for thread boundaries, plus continued migration/query audits for every email side table.
diff --git a/specs/frontend.md b/specs/frontend.md
index 825f81f73..8e2ed56de 100644
--- a/specs/frontend.md
+++ b/specs/frontend.md
@@ -1,6 +1,6 @@
 # Frontend
 
-Last updated: dev@e71f8ce | 2026-08-25
+Last updated: dev@c74f475 | 2026-10-15
 
 ## Scope
 
@@ -11,14 +11,14 @@ This spec covers the current browser app in:
 - `static/index.html`;
 - `static/login.html`;
 - `static/app.js`;
-- `static/style.css`;
+- ordered stylesheets under `static/css/`;
 - `static/js/*.js` and `static/js/*/*.js`;
 - vendor libraries under `static/lib/*`;
 - custom fonts and static assets under `static/fonts/*`;
 - `static/sw.js` and `static/manifest.json`;
 - frontend-oriented tests in `tests/*_js.py`, `tests/*.mjs`, `tests/bombadil-spec.ts`, static DOM/CSS/source-shape tests, and app/static tests such as `tests/test_app_static_mime.py`.
 
-`/backgrounds` currently targets `static/backgrounds.html`; if that route remains, the file must exist or the route should be removed.
+`/backgrounds` remains registered in `app.py` but targets the absent `static/backgrounds.html`. Authentication middleware also gates it when auth is enabled, despite its handler docstring describing a public prototype page. This is a known route/static gap; the page is not a working frontend surface at the checked revision.
 
 `static/manifest.json`, `static/index.html`, and `static/login.html` reference first-party PWA icon files under `static/icons/` (192px, 512px, and maskable). At runtime, route-specific manifests can also be generated as Blob URLs when supported, and per-route favicon links use generated inline SVG.
 
@@ -35,7 +35,7 @@ This spec covers the current browser app in:
 
 ## Runtime Shape
 
-The frontend is a raw static SPA served by FastAPI. There is no Vite, React, TypeScript, bundler, or generated build output.
+The browser runtime is a static native-ES-module SPA served by FastAPI, without a runtime Node/build dependency. Incremental maintained sources now live under `frontend/src/`, with explicit source-to-deployment mappings in `frontend/modules.json`; the map publishes `shared/actionMenuOrder.js`, the Notes feature graph and shared confetti to committed `static/js/` outputs. `scripts/build_frontend.py` publishes/checks those bytes during development, never application startup. Legacy modules remain authored under `static/`; there is no Vite/React/TypeScript bundle.
 
 `app.py` owns:
 
@@ -49,7 +49,11 @@ The frontend is a raw static SPA served by FastAPI. There is no Vite, React, Typ
 
 The two first-paint Fira Code faces are preloaded so the shell does not wait for later CSS discovery. `static/js/startupShell.js` lets the visible shell initialize before session loading completes; session/transcript hydration is deferred and coordinated by `static/js/sessions.js` plus history/session routes rather than blocking first paint.
 
-Exact script URL identity matters. Versioned script tags, unversioned imports, and service-worker precache entries must stay aligned. `static/sw.js` deliberately separates first-paint `PRECACHE` from lazy `PANEL_PRECACHE`; the latter currently contains the image-editor module graph so an editor never opened online can still open offline. KaTeX scripts/styles/fonts are also precached. Current service-worker coverage is not a generated full module-graph manifest, so changes still need direct verification.
+Exact script URL identity matters. Versioned script tags, unversioned imports, and service-worker precache entries must stay aligned. `static/sw.js` deliberately separates first-paint `PRECACHE` from lazy `PANEL_PRECACHE`; the latter contains the image-editor module graph so an editor never opened online can still open offline. The Notes feature graph and shared confetti are explicitly in `PRECACHE`, together with their exact legacy helper URLs. KaTeX scripts/styles/fonts are also precached. Current service-worker coverage is not a generated full module-graph manifest, so changes still need direct verification.
+
+`static/style.css` has been removed. `static/index.html` loads numbered `static/css/00-tokens.css` through `17-research.css` in order, followed by the three domain panel stylesheets. `static/sw.js` precaches those exact versioned URLs; cascade order remains part of behavior.
+
+New extracted owners include `static/js/turnRendering.js` for live/canonical turn DOM reconciliation, `backgroundToolJobs.js` for deduplicated background deliveries and research status cards, `emailReplyStream.js` for email reply streams, and `chatgptSubscriptionUsage.js` for account usage UI. Settings panel modules now also include `agent.js`, `api.js`, `imageModels.js`, `speech.js`, and `writingStyle.js`.
 
 ## Security Policy
 
@@ -76,7 +80,7 @@ Storage/secrets policy:
 `static/sw.js` owns PWA cache behavior:
 
 - API and non-GET requests are bypassed;
-- root navigation uses stale-while-revalidate;
+- only `/` navigation uses network-first with cached-shell fallback; other navigation URLs are not replaced with the app shell;
 - JS/CSS use network-first behavior;
 - other static assets use cache-first with background refresh;
 - `CACHE_NAME` bumps and `PRECACHE` updates must accompany cache policy or shell asset changes.
@@ -97,7 +101,7 @@ Current major frontend areas include:
 - image editor integration in `static/js/galleryEditor.js` plus leaves under `static/js/editor/`;
 - gallery, email inbox/library, calendar, research panel/jobs/synapse, notes/tasks, assistant, memory/skills, Cookbook/HW Fit, workspace picker, provider device flow, composer ArrowUp recall, theme, modal/window utilities, storage, and accessibility helpers.
 
-`static/js/emailLibrary/` is the one JS package with module-graph coverage: `tests/test_email_library_module_graph_js.py` pins the wrapper's public surface against the entry module's exports, evaluates every module on its own in a browser so an import cycle cannot hide a temporal-dead-zone read, and requires each module to be in the `sw.js` precache. Assertions about its source go through `tests/helpers/js_modules.py`, which reads the whole package, for the same reason `tests/helpers/stylesheets.py` reads the whole cascade.
+`static/js/emailLibrary.js` is a compatibility wrapper over one unversioned package entry and explicit leaves for reader, menus, attachments, reply, settings and unsubscribe behavior; the final wrapper has ten named exports. `tests/test_email_library_module_graph_js.py` compares the unversioned public surface, imports immediate package modules in synthetic browser shells and checks quoted service-worker URLs. It does not prove every callback, nested module, load order or offline behavior. `tests/helpers/js_modules.py` uses immediate entry-first file enumeration and column-zero source extraction; its package-name binding regex is not lexical-scope analysis.
 
 Coordinator ownership:
 
@@ -116,9 +120,15 @@ Recent browser behavior contracts include mobile chat Enter inserting newlines w
 
 The Settings finder and navigation are registry-backed, hide admin-only destinations from non-admin users, lazy-load admin panels, and keep the registry synchronized with DOM panels. Email OAuth connect preserves SMTP security and reopens the settings surface; unread message opens use one authoritative backend read/mark-seen request with stale-response guards; email-library prewarm is idle-only, single-flight, bounded to the initial page, and cancelled around visible foreground work.
 
+## Notes Feature Ownership
+
+`frontend/src/features/notes/index.js` composes one canonical Notes instance from domain rules/recurrence, application operations/state, infrastructure ports and UI factories. `frontend/modules.json` publishes its source modules byte-for-byte under `static/js/features/notes/` and shared confetti under `static/js/shared/ui/`. `static/js/notes.js` is the compatibility facade: it reexports the canonical methods/default, assigns `window.notesModule` and starts idempotent background reminders. Versioned/unversioned facade imports converge on the unversioned canonical entry. `static/app.js` retains the versioned facade caller; Compare voting imports and reexports shared confetti rather than owning it.
+
+State mutations belong to `application/state.js`; UI gets live read-only views, and operation writes unwrap nested views to keep stored note data cloneable. The composition injects HTTP, persistence, clock/scheduler, notification and shared platform callbacks. Panel disposal releases owned portals, document/window listeners, gesture state and masonry observers; detached/closed-panel checks prevent late completions from recreating observers. Tablet reorder rewiring replaces stale binding sentinels. Reminder scheduling is page-owned and survives close/minimize; custom reminder date initialization uses DOM value assignment rather than HTML interpolation. Domain-specific drafts/reminder/selection contracts and remaining races are in `calendar-tasks-notes.md`.
+
 ## UI Policy
 
-- New code must run as browser ES modules without a build step.
+- New runtime code remains native browser ES modules; manifest-selected maintained sources use the development publication/check step without adding a startup build.
 - Reuse existing CSS variables, modal/window patterns, icon style, storage helpers, and route conventions.
 - Custom font handling includes bundled OpenDyslexic assets plus user-supplied fonts exposed through `/api/fonts/custom`; font and text-size settings must stay coordinated between settings UI, theme helpers, and CSS variables.
 - Avoid relying on stale module summaries.
@@ -138,25 +148,37 @@ The Settings finder and navigation are registry-backed, hide admin-only destinat
 
 Existing frontend coverage is a mix of Node-executed helper tests, `.mjs` tests, static DOM/CSS/source-shape tests, browser exploration specs, and app/static tests. Many tests are useful source-shape regressions but do not replace browser/module-graph execution.
 
-`tests/test_css_computed_style_snapshot.py` pins `getComputedStyle` for a fixed element inventory across pages, viewports, themes and density modes, so a `static/style.css` restructuring that changes which declaration wins fails a test instead of shipping; see `tests/css_snapshot/README.md` for what it does and does not cover.
+`tests/test_css_computed_style_snapshot.py` pins `getComputedStyle` for a fixed element inventory across pages, viewports, themes and density modes, so a stylesheet cascade restructuring that changes which declaration wins fails a test instead of shipping; see `tests/css_snapshot/README.md` for what it does and does not cover.
 
 Recent focused coverage includes model-key matching under Node, document-library counters, chat resend/delete/mobile Enter/ArrowUp, scoped approval continuation and compare routing, route provenance, live-thinking throttling, startup shell/history hydration, shared app-config caching/invalidation, settings registry/navigation/finder/lifecycle, lazy panel loading/offline editor precache, vendored lazy KaTeX/Mermaid rendering, email read dedup/prewarm, Markdown restoration, malformed keybinds, currency-safe inline math, notes/calendar/modal/manifest/admin-log behavior, Markdown XSS helpers, and CardDAV unchanged-password handling.
 
-Missing coverage includes:
+Areas that still need explicit behavior verification include:
 
 - SPA route/static auth and no-cache headers;
 - CSP header contents and nonce injection for `/` and `/login`;
 - service-worker API/non-GET bypass and cache strategy;
-- service-worker precache versus `index.html` script/module tags, including query strings (stylesheet links and their `?v=` strings are covered by `tests/test_static_stylesheet_manifest.py`; script and module tags are not);
-- ongoing manifest/icon reference drift;
-- module graph/load-order validation;
+- complete service-worker precache membership versus HTML scripts/modules: stylesheet parity is covered by `tests/test_static_stylesheet_manifest.py`, and `tests/test_frontend_module_version_parity.py` checks selected app/index/SW versions plus regex-discovered JS/index URL identities, but neither proves complete graph evaluation;
+- ongoing manifest/icon reference drift; `sw.js` now explicitly precaches the default manifest and three PWA icons;
+- complete legacy module graph/load-order behavior beyond maintained-source architecture gates and the email-library browser graph;
 - degraded vendor-library/browser API behavior, including Pyodide's remaining CDN path.
 
+## Rendering, Provider UI And Static Checks
+
+`turnRendering.js` reconciles canonical/live ownership with turn replacement metadata while keeping tool activity. Compact corrected/final events can replace earlier prose; the server completion gate can buffer answer deltas, so this is not a promise of immediate streaming. Ordinary ask-user choices have 1–3 keyboard shortcuts; tool approval cards are excluded. Active document state restores the exact chat-bound document; editor rich-only font controls and stats portal z-order are independent of chat tool authority. The research map SVG has an image role and accessible name, without proving complete accessibility.
+
+Usage ledgers use nested Maps to preserve arbitrary legacy keys as data, while fresh writes require a nonempty session id and reject reserved session/run keys before accounting. JSON conversion preserves wire shape; metrics with a run id replace that run's previous value, while legacy writes without one add to aggregate totals and use per-object recorded/pending guards. Web Locks are used when available and bounded entries fold into totals, so evicted run replay is not forever deduplicated. Admin provider cards hide ChatGPT/recognized Featherless base URLs; optional fingerprints and displayed version/source commit are informational rather than byte attestation. Featherless catalog search is debounced/paginated with bounded results; optimistic pin/tool-mode PATCH saves and load-more handling do not guarantee acknowledged persistence or universal stale-response cancellation. Collapsed account usage cards retain loaded DOM, including errors, rather than proving fresh telemetry.
+
+Markdown SVG uses an empty-sandbox, no-referrer iframe and restrictive CSP; title extraction is flat escaped text rather than parent-DOM parsing. Fenced and complete raw SVG are separate from generic HTML fences, with bounded aspect ratio. This does not confer the different permissions used by document print/run iframes. Remote mail rendering and image thumbnail assignment retain their own sanitizer/network boundaries.
+
+Stylesheet helpers read the shell-ordered complete app cascade, exclude vendored libraries and share cache-token checks. Recursive lexical hygiene rejects deleted-monolith references with bounded exceptions; comment-stripped keyframe counting catches duplicate global names. Document-source helpers enumerate implementation files and scan braces lexically; quoted import/SW membership and minimum callable export tests are narrower than semantic module execution. The fixed computed-style snapshot covers 676 elements across its configured page/viewport/theme/density cases, freezes animation timing and checks a global rule-swap sensitivity count; it is not arbitrary browser/layout coverage. Manual benchmark HTML and historical screenshots are not newly reproduced acceptance.
+
+The website has seven hover/focus/tap preview clips, ambient video, failure placeholders and thresholded swipe navigation. Reduced-motion CSS disables selected animation rather than guaranteeing all video stops. Restored branding/PWA assets do not prove license clearance or decoded-image review; the known `/backgrounds` absent-file/auth gap remains.
+
 ## Current Gaps
 
-- `static/style.css` and large coordinators remain high-risk owners: `static/js/document.js`, `static/js/settings.js`, `static/js/chat.js`, and `static/app.js`.
-- There is no build-time type checking, module graph validation, or script-order validation. Service-worker precache validation exists for stylesheets, and for the `static/js/emailLibrary/` package only.
+- The ordered stylesheet cascade and large coordinators remain high-risk owners: `static/js/document.js`, `static/js/settings.js`, `static/js/chat.js`, and `static/app.js`.
+- There is no general build-time type checking or complete legacy script-order validation. `scripts/check_frontend.mjs` checks maintained-source imports, layer boundaries, explicit legacy exceptions, deployment URL/precache identity, and dependency cycles; its inventory mode reports legacy static imports/cycles. These gates cover the manifest-selected maintained graph, not every legacy module. Service-worker checks also cover stylesheet URLs and the email-library package.
 - Frontend state is mostly module/global/localStorage driven, so cross-session and cross-user behavior needs explicit care.
 - `window.*` compatibility bridges remain widespread.
 - PWA/static-serving behavior may deserve a separate spec if service worker, manifests, route-specific icons, and cache policy keep growing.
-- The static asset/route manifest regression covers stylesheets referenced by app-owned HTML and `sw.js`; scripts, modules and `manifest.json` icon references are still unverified.
+- Static regressions cover stylesheet references, selected script/module URL identities and maintained-output precache membership; complete legacy graph membership/evaluation and ongoing manifest icon drift still require checks.
diff --git a/specs/gallery-editor-media.md b/specs/gallery-editor-media.md
index edc4efa20..6a3b693b1 100644
--- a/specs/gallery-editor-media.md
+++ b/specs/gallery-editor-media.md
@@ -1,6 +1,6 @@
 # Gallery, Editor, And Media
 
-Last updated: dev@e71f8ce | 2026-08-25
+Last updated: dev@c74f475 | 2026-10-15
 
 ## Scope
 
@@ -28,7 +28,7 @@ This spec covers media surfaces in:
 
 - gallery upload, library, album, tag, favorite, ZIP, delete, and saved-project views;
 - chat-generated image rendering/edit/delete bubbles;
-- agent `generate_image` and stale `edit_image` tool paths;
+- agent `generate_image` and owner-scoped `edit_image` tool paths;
 - MCP image-generation rows/files;
 - image editor AI tools and model endpoint pickers;
 - document PDF signing with stored signatures;
@@ -51,11 +51,13 @@ Generated media provenance:
 - upload `file_hash` is a separate metadata field;
 - generated files live under `data/generated_images`;
 - chat image generation writes files and inserts `GalleryImage` rows through `src.ai_interaction`;
-- MCP image generation can create ownerless rows/files;
+- MCP image generation stamps the trusted dispatched owner when present, trims empty owner values to null, and can still create ownerless rows/files without that context;
 - generated-but-not-yet-imported images can have no gallery row;
 - once a gallery row exists, owner checks decide visibility where the route enforces them.
 
-`app.py` owns direct `/api/generated-image/{filename}` serving through `src.generated_images.resolve_generated_image_path()`. It validates hex-like image/video filenames, rejects path escape and missing files, serves rowless generated files, checks row owner when a row exists, allows null-owner compatibility rows, and uses immutable/nosniff cache headers. Gallery replace/rotate/save/delete/ZIP paths also resolve filenames through a shared generated-image path helper so database filenames cannot escape `data/generated_images`. Replace/rotate/save-over-original flows can mutate bytes under the same filename, so frontend cache busting matters.
+`app.py` owns direct `/api/generated-image/{filename}` serving through `src.generated_images.resolve_generated_image_path()`. It validates filename syntax before ownership and disk probing. With auth enabled, `effective_user()` resolves cookie/API-token owners. A live registry entry is checked first: a matching owner authorizes, while a mismatch returns 404 without database fallback. Only absent registration reaches the gallery lookup: a nonempty row owner must match; a row without an owner instead requires a matching linked-session owner. If that lookup finds no gallery row, it requires a chat metadata reference in an owned session. Unattributed/mismatched files return 404 and database verification failures return 503. Disabled auth skips ownership verification. Confined path/existence checks follow authorization, and responses use `private, no-cache, must-revalidate` plus nosniff headers. Gallery replace/rotate/save/delete/ZIP paths also resolve filenames through a shared generated-image path helper so database filenames cannot escape `data/generated_images`. Replace/rotate/save-over-original flows can mutate bytes under the same filename, so frontend cache busting matters.
+
+`src/generated_images.py` owns a lock-protected, process-local one-hour recent-owner registry. Image generation/edit writers in `src/ai_interaction.py` register trusted owners after writing bytes; the image MCP server stamps gallery ownership and registers after commit when an owner exists. Registry entries are ephemeral, not durable gallery ownership, and matching registry access can survive a database outage. Tool dispatch strips caller-reserved attribution keys before injecting verified owner context, including qualified image MCP and direct fallback paths.
 
 ## Image Tools And Providers
 
@@ -92,7 +94,7 @@ Optional dependency behavior:
 
 ## Editor Drafts
 
-`routes.editor_draft_routes` owns server-backed image editor project payloads. `EditorDraft` rows store title, payload JSON, thumbnail, source image, timestamps, and owner.
+`routes.editor_draft_routes` owns server-backed image editor project payloads. `EditorDraft` rows store name, dimensions, payload JSON, thumbnail, source image, timestamps, and owner.
 
 Frontend editor behavior is split across `static/js/editor/*` and `static/js/galleryEditor.js`: canvas state, layer panel, masks, history, snapping, stroke pipeline, inpaint/rembg/harmonize tools, AI tool runner, model pickers, an AI edit command box that routes natural-language edit requests into existing inpaint/remove/upscale/background/style actions where possible, import wiring, topbar controls, auto-save, resume by draft ID or source image, draft-only open, and cleanup after close. `static/js/panels.js` loads this module graph on first editor use, shares concurrent imports, retries failed loads, and `static/sw.js` keeps the lazy graph in a separate offline panel precache.
 
@@ -126,11 +128,11 @@ Known boundaries:
 
 - image-generation routes require `can_generate_images`;
 - image proxy/editor endpoints currently resolve client-selected, DB-selected, or fallback image model endpoints without full owner-scoped endpoint-key policy or uniform outbound revalidation;
-- generated-file serving allows rowless files and null-owner compatibility rows;
+- rowless generated files require an owned chat reference or recent registration; null-owner gallery rows require a matching owned session;
 - uploads are byte-limited and extension-gated, with content sniffing available through `UploadHandler.detect_content_type()` when `python-magic`/`libmagic` is installed;
 - several base64 JSON editor routes accept large decoded image payloads and need route-level size discipline;
 - gallery DB filenames should be joined through shared generated-media path helpers before filesystem operations;
-- editor draft source image IDs, payloads, and thumbnails are owner-scoped by draft owner but do not fully validate source-gallery ownership or payload size;
+- editor drafts owner-scope rows for identified users and cap serialized payload bytes, but source-gallery ownership and thumbnail size still need separate validation;
 - emoji proxy constrains codepoint filenames and degrades invalid, unknown, or unreachable SVGs to transparent no-store placeholders, but remote SVG content still deserves security review;
 - visual report Markdown HTML/link/image output needs continued sanitization coverage.
 - `scripts/mlx_image_server.py` pins generation/edit routing to the process-start model and ignores request-selected model names, preventing unauthenticated callers from selecting a local model directory/repository whose model-specific script or bridge would execute.
@@ -142,24 +144,41 @@ Known boundaries:
 - Missing generated files are skipped in ZIP downloads; if all are missing, the route returns no files found.
 - Soft delete commits the gallery row state before removing the disk file, so a failed DB write does not orphan a missing image row.
 - AI tagging can fail when disk files are missing.
-- Static JS/CSS/HTML assets revalidate because there is no frontend build/versioning.
+- Static assets revalidate; most editor modules remain static ES modules, while `frontend/modules.json` and the committed generated-output freshness gate govern the manifest-selected native ES modules published by byte-for-byte copying to committed deployment outputs.
 - Gallery/editor frontend state includes stale-while-revalidate and listener cleanup to avoid stale handlers.
-- `edit_image` tool schema/implementation currently appears stale against implemented `/api/image/*` and `/api/gallery/*` routes.
+- `src/tools/image.py` implements `edit_image` in-process: prompt edits call the model adapter, upscale creates a 2x/4x Lanczos copy, and rembg creates a copy when the optional package is installed. It checks exact gallery owner and confined source path; uploaded attachment URIs support prompt edits after owner-aware resolution.
 
 ## Testing Coverage
 
 Existing tests cover EXIF dimensions, owner-filter helper behavior, direct upload limits, image-generation privilege source shape, sharpen auth, gallery null-user denial, endpoint SSRF/source checks, editor draft payload validation, lazy editor loading/offline precache, MLX request-model pinning, font family derivation, visual-report helper behavior, gallery CLI previews, and selected security regressions.
 
-Route-level coverage is thin for full gallery CRUD/album/tag/download/delete flows, generated-image serving, editor draft owner CRUD, signature owner CRUD, emoji proxy/cache behavior, image-tool degraded responses, optional dependency fallbacks, and frontend editor behavior.
+Route-level coverage is thin for full gallery CRUD/album/tag/download/delete flows, generated-image serving, editor draft owner CRUD, signature owner CRUD, emoji proxy/cache behavior, image-tool degraded responses, optional dependency fallbacks, and full browser editor integration. Focused codec, layer/mask/group, transform, history, worker, and draft-budget regressions are present; this maintenance pass did not execute them.
+
+## Versioned Editor Documents And Budgets
+
+`static/js/editor/document-codec.js` is the shared project-file/autosave serialization boundary, currently document version 15. It migrates older versions, rejects future versions, validates layer/group/mask/selection and geometry data, and bounds canvas pixels, layer counts, total surfaces, and embedded image data. Masks, adjustments, effects, groups, vector text/shapes, placed layers and view/guide state pass through this codec rather than a second hand-written draft shape, subject to serialization/decode and history limitations below; this is not lossless persistence of every mask/effect property.
+
+Editor responsibilities now include `document-geometry.js` and layer geometry for canvas transforms, `layer-groups.js`/`layer-selection.js` for grouping/multi-selection, `selection-mask.js` for selections, `text-layer.js`/`shape-layer.js` for vector content, and `adjustment-layer.js`/`effects.js` with worker paths for compositing operations. `history-budget.js` bounds raw ImageData history adaptively; rendering cancellation prevents stale asynchronous results from applying after newer edits.
+
+`routes/editor_draft_routes.py` uses `EDITOR_DRAFT_MAX_BYTES` both for early rejection of oversized declared Content-Length on writes and for the authoritative serialized-payload byte check. Missing/malformed Content-Length still reaches the latter check after parsing. This cap does not supply source-gallery ownership or a separate thumbnail budget.
+
+`src/media_ingress.py` separately builds bounded local multimodal attachments for supported image/video/audio/document paths with source hashes, encoding/dimension/frame limits, and artifact metadata. Agent evidence/trace consumers record ingress metadata; it is not the browser upload storage or editor serialization owner.
+
+## Editor Persistence And Operation Limits
+
+Codec limits count canvas/surface allocations and embedded strings rather than universally bounding decoded bytes. Failed canvas encoding or image restoration can omit/drop data; effect-mask normalization and history snapshots do not preserve every mask density/feather property. Async capture can span intervening edits, so it is not an immutable atomic pixel snapshot. History deduplicates shared pixel buffers and trims older snapshots to a budget while retaining the newest even when oversized; it does not serialize the entire history into a draft.
+
+Draft autosave reserves one in-flight capture and uses session/generation checks for assigning returned ids, with PUT404 recreation. Those checks do not cancel an old server request. The current persist chain can clear an earlier error and display Saved after catch/early return; the badge is not a durable-write receipt. Project state uses server draft ids and a compact session descriptor rather than a full browser-sessionStorage payload. Restore can drop failed raster/mask/placed sources and is not a lossless project recovery promise.
+
+Placed transforms, crop/resize/flip, linked versus document-space masks, grouped effects and rasterization retain distinct geometry paths. Duplicate/merge/copy operations do not guarantee independent preservation of every effect-mask/retained metadata field; raw layer copying differs from flattened canonical output. Pixel/position locks are checked on selected mutation paths rather than proving every control respects every lock. Escape cancellation is operation-specific (including crop/transform/filter prompts), not a universal rollback guarantee. Filter/worker generations prevent selected stale results, but shared intermediate canvases and Quick Edit busy-end polling do not establish atomic pixels or successful downstream AI work.
 
 ## Current Gaps
 
 - Owner-scoped endpoint-key resolution is needed for image proxy/editor routes.
 - Media routes need a clear API-token policy: reject token callers, or implement owner/scope handling.
-- Generated-image serving needs live route tests for invalid filenames, rowless files, owned rows, null-owner rows, MIME/cache headers, and cross-owner behavior.
-- Mutable generated filenames plus immutable cache headers need cache-busting tests for replace/save-over-original flows.
+- Direct handler ownership/cache tests cover generated-image denial and fallback branches; middleware-mounted serving, MIME/account-switch and live browser cache behavior still need broader checks.
+- Private revalidation replaces immutable generated-media caching; replace/save-over-original and account-switch behavior still warrant browser cache tests.
 - Base64 JSON editor payload size limits need hardening; upload content sniffing should keep native/Docker parity coverage as dependencies change.
-- MCP image generation needs an owner attribution decision or explicit admin-only documentation.
-- `edit_image` tool route mapping appears stale.
+- Image MCP now receives trusted server-dispatch ownership; direct out-of-band MCP callers and cross-process recent-registry behavior remain separate trust/availability limits.
 - Emoji SVG proxy/cache and visual-report raw HTML/link sanitization need stronger tests.
 - Optional image dependency fallbacks are mostly untested.
diff --git a/specs/integrations.md b/specs/integrations.md
index 06a574e11..a23f6129f 100644
--- a/specs/integrations.md
+++ b/specs/integrations.md
@@ -1,6 +1,6 @@
 # Integrations
 
-Last updated: dev@e71f8ce | 2026-08-25
+Last updated: dev@c74f475 | 2026-10-15
 
 ## Scope
 
@@ -80,17 +80,11 @@ The Cookbook scoped-agent surface currently exposes `cookbook:read` and `cookboo
 
 `src.integrations` owns generic API integration presets, `data/integrations.json`, API-key encryption/decryption, secret masking, plaintext-key migration, enabled integration prompt text, and `execute_api_call()`.
 
-`routes.auth_routes` owns admin-only HTTP CRUD/test routes for these integrations. Presets are public metadata. The ntfy test route is special: it publishes a real test notification to the configured reminder topic instead of only probing server health.
+`routes.auth_routes` owns HTTP CRUD/test routes for these integrations, requiring an admin unless auth is explicitly disabled. Presets are public metadata. The ntfy test route is special: it publishes a real test notification to the configured reminder topic instead of only probing server health.
 
 `api_call` is the agent/tool execution path for configured integrations. It is blocked for non-admin/public users by tool security, accepts only relative paths, uses the admin-configured base URL/auth settings, and returns truncated external responses to the model, including a sentinel when long JSON lists are shortened. Admin-authored integration descriptions are prompt context; external responses remain untrusted data.
 
-`execute_api_call()` normalizes base URLs to HTTP(S) scheme, hostname, and
-path-only values, rejects request paths that are not relative absolute paths
-(`/...`) or that carry schemes/fragments, treats `/` as the base URL without
-appending an extra slash, and checks the final URL through `src.url_safety`.
-Link-local/metadata targets are always rejected; setting
-`INTEGRATION_API_BLOCK_PRIVATE_IPS=true` also rejects loopback/RFC1918/private
-addresses for operators who do not need LAN integrations.
+`execute_api_call()` normalizes base URLs to HTTP(S) scheme, hostname, and path-only values, rejects request paths that are not relative absolute paths (`/...`) or that carry schemes/fragments, treats `/` as the base URL without appending an extra slash, and checks the final URL through `src.url_safety`. Link-local/metadata targets are always rejected; setting `INTEGRATION_API_BLOCK_PRIVATE_IPS=true` also rejects loopback/RFC1918/private addresses for operators who do not need LAN integrations.
 
 After validation, `execute_api_call()` pins the outbound connection to the validated IP snapshot while preserving the configured URL, Host header, TLS server name, and redirect policy. DNS cannot select a different destination between SSRF validation and transport.
 
@@ -159,8 +153,7 @@ This spec owns the cross-integration framing and agent/token/webhook surfaces. D
 - Missing or corrupt `data/integrations.json` loads as an empty list; non-object rows are ignored.
 - Plaintext generic integration API keys migrate to encrypted storage on load.
 - Webhook delivery has no retry/backoff queue; the persisted state is last status or sanitized last error.
-- Webhook URLs are validated at create and delivery time, redirects are disabled,
-  and delivery connects to the IP set validated immediately before the request.
+- Webhook URLs are validated at create and delivery time, redirects are disabled, and delivery connects to the IP set validated immediately before the request.
 - Companion LAN detection is best-effort and falls back to local host/port defaults unless a valid `COMPANION_BASE_URL` is configured.
 - `ODYSSEUS_URL` must be reachable from the external coding agent; no Docker/native URL rewrite is performed.
 
@@ -182,12 +175,30 @@ Current targeted coverage includes API-token CRUD basics, chat-scoped `/api/mode
 
 The integration audit also ran the targeted venv subset covering those areas with 52 passing tests and one warning.
 
+## Bound External Backends
+
+Tool-backed integration calls consume `src.agent_runtime.remote_resources` backend identity. `src.integrations.execute_api_call()` refuses a bound call when the saved integration identity differs from the admitted resource; a changed configuration cannot silently inherit an earlier approval. MCP and client/host bridges have their own producer/configuration identities and do not gain permission from advertised schemas.
+
+Scoped Cookbook adapters reject internal-tool transport/header calls instead of treating internal owner attribution as an external scoped credential. In auth-disabled mode they still require the native local-operator boundary before borrowing endpoint functions. Public API-token scopes remain distinct from browser admin and internal-loopback authority.
+
+## Adapter Admission Limits
+
+Generic `app_api` refuses decoded `/api/codex/cookbook` selectors before dispatch, so it cannot wrap the dedicated scoped adapter to borrow its permissions. Integration requests preserve their explicit query/body inputs and owner/backend binding; an observed `api_call` response is an external acknowledgement, not sealed proof of remote poststate. Public scoped credentials, browser admin access and native local operator admission remain separate boundaries.
+
+## App Configuration Compatibility
+
+Integration list/create/update/delete/connectivity-test handlers in `routes/auth_routes.py` use `_require_admin_user()`: explicit disabled-auth operator mode is admitted without a session, while auth-enabled access still requires an admin. Integration listing continues masking keys. This app-configuration exception does not relax user-store administration or scoped external API authorization.
+
+## Delegated Upload Access
+
+`routes/upload_routes.py` applies a separate delegated-token owner/scope gate to browser-compatible upload endpoints. `chat` or `documents:write` permits creation/OCR edits; either of those or `documents:read` permits download/thumbnail/OCR reads. Scope is an any-of intersection, not a requirement for every listed scope. Tokens remain confined to their actual owner's non-null-owned files even when the owner is an interactive admin; invalid/missing/sentinel token identity fails closed. This supplements global token middleware rather than changing other scoped API contracts.
+
 ## Current Gaps
 
 - Codex/Claude scoped routes, owner restoration, degraded 503 behavior, plugin zip contents, and helper-script path refusal need focused regression tests.
 - Token profile/update behavior and Settings agent-token scope toggles need direct coverage.
 - Codex Cookbook scopes need continued Settings, route-check, and `ALLOWED_SCOPES` regression coverage.
-- Generic integration HTTP CRUD/test routes, `execute_api_call()` auth modes, response shaping, and frontend Settings/Admin flows need direct coverage.
+- Generic integration route fixtures cover CRUD/test admission with auth enabled and disabled, using substituted stores and network calls. Live notification delivery, `execute_api_call()` auth modes, response shaping, and frontend Settings/Admin integration still need broader coverage.
 - `do_manage_tokens()` does not match `/api/tokens` semantics for `ody_` prefix, owner, scopes, and cache invalidation.
 - `do_manage_webhooks()` bypasses route behavior and does not cover signing-secret parity.
 - Companion read endpoints should either require `chat` scope or be documented as an explicit scope-policy exception.
diff --git a/specs/llm-models.md b/specs/llm-models.md
index 2613b2ee8..8bbde0077 100644
--- a/specs/llm-models.md
+++ b/specs/llm-models.md
@@ -1,6 +1,6 @@
 # LLM Models And Endpoints
 
-Last updated: dev@e71f8ce | 2026-08-25
+Last updated: dev@86b886c | 2026-10-15
 
 ## Scope
 
@@ -10,7 +10,7 @@ This spec covers model/provider behavior in:
 - `src/endpoint_resolver.py`;
 - `src/foreground_model_routing.py`;
 - `src/model_discovery.py`;
-- `src/model_context.py`;
+- `src/model_context.py`, `src/generation_budget.py`, `src/model_pricing.py`, `src/model_profiles.py`, and `src/utility_effort.py`;
 - `src/model_capabilities.py`;
 - `src/model_capability_readers/`;
 - `src/task_endpoint.py`;
@@ -32,41 +32,19 @@ This spec covers model/provider behavior in:
 
 `llm_core` owns payload shape. Route files and chat/agent code should request a call; they should not duplicate provider-specific payload quirks.
 
-Kimi Code User-Agent discovery has both sync and async implementations. Async
-post and stream paths probe `/models` through their existing async client and
-await each candidate, so header negotiation does not block the event loop; both
-paths share the accepted-value cache and 403 fallback policy.
+Kimi Code User-Agent discovery has both sync and async implementations. Async post and stream paths probe `/models` through their existing async client and await each candidate, so header negotiation does not block the event loop; both paths share the accepted-value cache and 403 fallback policy.
 
 Provider-specific behavior is part of this layer: `LLM_CONNECT_TIMEOUT` controls the connect budget for sync and streaming calls, Kimi Code endpoints retry a small whitelisted User-Agent set on 403 and cache the accepted value, official Moonshot/Kimi Code and Anthropic Opus 4.7+ payloads omit sampling controls where required, and major-only Opus IDs such as `claude-opus-5` also omit temperature instead of falling through numeric minor-version parsing. Reasoning models omit or clamp unsupported temperature values, while self-hosted compatible endpoints keep normal parameters unless detected otherwise. Mistral structured content is normalized in async utility calls as well as stream/chat paths, and Mistral/Moonshot/Kimi reasoning content, `gpt-oss` harmony output, DeepSeek V4 thinking identifiers, and native/OpenAI-compatible Ollama thinking formats keep hidden reasoning separate from visible text. Tool names that collide with GPT-OSS built-ins are aliased on the provider boundary and mapped back before execution. Copilot request metadata remains defensive against malformed `request_flags`.
 
 ## Canonical Provider And Model Shape
 
-`src.model_capabilities` owns canonical model family, task, modality,
-capability, limit, evidence, assertion, deterministic-control, probe-result,
-reasoning-control token, and display-query values.
-`src.model_capability_readers` owns endpoint-scoped stable identity, lightweight
-provider detection, record serialization, and normalization of already-fetched
-provider payloads. Readers do no network I/O. Model-specific observations are
-kept in `model-quirks.md`, not a runtime registry without a consumer.
+`src.model_capabilities` owns canonical model family, task, modality, capability, limit, evidence, assertion, deterministic-control, probe-result, reasoning-control token, and display-query values. `src.model_capability_readers` owns endpoint-scoped stable identity, lightweight provider detection, record serialization, and normalization of already-fetched provider payloads. Readers do no network I/O. Model-specific observations are kept in `model-quirks.md`, not a runtime registry without a consumer.
 
-Provider support and model support are different facts. A provider may expose
-tools, reasoning, vision, or multiple APIs while individual models differ.
-Provider-native readers describe where model evidence can appear. Current
-concrete readers cover generic OpenAI-compatible identity, OpenAI, OpenRouter,
-Google, Ollama, LM Studio, and llama.cpp. Identity-only model lists remain
-unknown.
+Provider support and model support are different facts. A provider may expose tools, reasoning, vision, or multiple APIs while individual models differ. Provider-native readers describe where model evidence can appear. Current concrete readers cover generic OpenAI-compatible identity, OpenAI, OpenRouter, Google, Ollama, LM Studio, and llama.cpp. Identity-only model lists remain unknown.
 
-Reader dispatch uses an explicit vendor first, then endpoint kind, label-bounded hostname suffix, and common local-port hints. Generic payload handling accepts `data[]`
-or `models[]` items with `id`, `name`, or `model`; it does not accept a bare
-list and never promotes capability-looking fields. Unknown fields remain in
-the in-memory raw record. See [model-capability-canonical.md](model-capability-canonical.md),
-[model-quirks.md](model-quirks.md), and the
-[provider map](model-providers/_readme.md).
+Reader dispatch uses an explicit vendor first, then endpoint kind, label-bounded hostname suffix, and common local-port hints. Generic payload handling accepts `data[]` or `models[]` items with `id`, `name`, or `model`; it does not accept a bare list and never promotes capability-looking fields. Unknown fields remain in the in-memory raw record. See [model-capability-canonical.md](model-capability-canonical.md), [model-quirks.md](model-quirks.md), and the [provider map](model-providers/_readme.md).
 
-This canonical layer is currently exercised by focused unit tests but is not
-wired into runtime discovery, endpoint resolution, model context, request
-shaping, or frontend pickers. `routes/model_routes.py` model probes continue to
-return model IDs through their existing runtime path.
+Canonical records are exercised by focused unit tests but are not wired into runtime discovery, endpoint resolution, model context, request shaping, or frontend pickers. The reader package’s `detect_vendor()` helper does have narrow runtime consumers in `src/ai_interaction.py` and gallery routes for OpenRouter image transport; that does not integrate canonical capability records. `routes/model_routes.py` model probes continue to return model IDs through their existing runtime path.
 
 Route-level probe helpers in `routes/model_routes.py` are the current exception: they build minimal provider-specific probe payloads using `llm_core` detection helpers. Keep probe behavior aligned with `llm_core` provider adapters. LLM provider HTTP clients and endpoint probes share `src.tls_overrides.llm_verify()`, which can add an operator-provided `LLM_CA_BUNDLE` on top of normal certificate verification without turning verification off or widening that trust to arbitrary URL fetches.
 
@@ -86,7 +64,7 @@ OpenAI-compatible model-list URL construction preserves `/v1` bases and inserts
 
 `routes/session_routes.py` owns binding sessions to endpoint IDs, owner-scoped header construction, raw-endpoint rejection for non-admin users, model validation, and persisted session headers. Compare panes and normal chat session creation use this path.
 
-`ModelEndpoint` rows own API keys, base URLs, cached/hidden/pinned models, model type, endpoint kind, refresh mode/interval/timeout, supports-tools state, nullable owner, optional provider-auth linkage, and provider metadata. `owner = NULL` means legacy/shared; non-null rows are private to that owner, while admins can see all. Secret fields must remain encrypted and scrubbed in responses.
+`ModelEndpoint` rows own API keys, base URLs, cached/hidden/pinned models, model type, endpoint kind, refresh mode/interval/timeout, supports-tools state, per-model tool-mode overrides, nullable owner, optional provider-auth linkage, and provider metadata. `owner = NULL` means legacy/shared; non-null rows are private to that owner, while ordinary admin inventory can see all. ChatGPT Subscription rows are an exception: account visibility requires exact effective-owner equality even for admins. Secret fields must remain encrypted and scrubbed in responses.
 
 Decrypted endpoint headers can be copied into session metadata for chat use. Endpoint deletion must clear dependent settings and copied session headers.
 
@@ -94,7 +72,7 @@ Decrypted endpoint headers can be copied into session metadata for chat use. End
 
 `src.model_discovery` owns host/env/Tailscale/local-port scanning for model servers. Admin `/api/providers` and `/api/discover` use that scanner; endpoint CRUD, test, refresh, and hidden-model controls are frontend-owned by `static/js/admin.js`.
 
-`/api/models` is the normal picker/catalog surface. It is auth/owner scoped, per-user/admin-flag cached briefly, can trigger background refresh, preserves offline endpoint rows, filters hidden models, and preserves pinned model IDs for UI selection. API-token callers must carry `chat` scope and a token owner before they can list models. API/proxy endpoint inventory is visible by default until an explicit `pinned_models` allow-list is saved; an explicit empty list means show none, and legacy hidden-list state is upgraded to the equivalent pins so endpoint settings, picker checkboxes, and chat agree. Proxy/API endpoints can be marked cached-first/manual so large upstream catalogs are not repeatedly probed, while explicit refresh paths use longer manual timeouts. Local endpoints get cheap reachability probes before expensive refreshes where possible, and endpoint responses can include explicit `supports_tools` state for schema-emission heuristics. Google Gemini API endpoints use the native paginated `generativelanguage.googleapis.com/v1beta/models` catalog, send API keys in `x-goog-api-key`, retain only content-generation model IDs, and default to manual refresh unless the caller explicitly chooses another mode. Probe failure returns no curated Google fallback. `static/js/models.js` and `static/js/modelPicker.js` own the sidebar/picker catalog; `static/js/model/matchKey.js` owns longest-substring model-info/pricing key matching; `static/js/settings.js` owns default, utility, vision, image, TTS, STT, and fallback selectors.
+`/api/models` is the normal picker/catalog surface. It is auth/owner scoped, per-user/admin-flag cached briefly, can trigger background refresh, preserves offline endpoint rows, filters hidden models, and preserves pinned model IDs for UI selection. API-token callers must carry `chat` scope and a token owner before they can list models. API/proxy endpoint inventory is visible by default until an explicit `pinned_models` allow-list is saved; an explicit empty list means show none, and legacy hidden-list state is upgraded to the equivalent pins so endpoint settings, picker checkboxes, and chat agree. Proxy/API endpoints can be marked cached-first/manual so large upstream catalogs are not repeatedly probed, while explicit refresh paths use longer manual timeouts. Local endpoints get cheap reachability probes before expensive refreshes where possible, and endpoint responses can include explicit `supports_tools` state for schema-emission heuristics. Google Gemini API endpoints use the native paginated `generativelanguage.googleapis.com/v1beta/models` catalog, send API keys in `x-goog-api-key`, retain only content-generation model IDs, and default to manual refresh unless the caller explicitly chooses another mode. Probe failure returns no curated Google fallback. `static/js/models.js` and `static/js/modelPicker.js` own the sidebar/picker catalog; `static/js/model/matchKey.js` owns longest-substring model-info/pricing key matching; `static/js/settings.js` coordinates default, utility, vision and fallback selectors; `static/js/settings/imageModels.js` and `static/js/settings/speech.js` own their extracted image and TTS/STT panels.
 
 `src.task_endpoint` owns background-task endpoint/model resolution for task routes and scheduler callers. It resolves `task_endpoint_id`/`task_model` through the normal endpoint resolver with owner context.
 
@@ -102,7 +80,7 @@ Cookbook and HWFit own local model download, serve, ranking, and auto-registrati
 
 ## Context Length
 
-`src.model_context` owns model context-length lookup/query and token estimation. Cache keys include endpoint plus model so identical model names on different endpoints do not bleed context-window data. Unknown proxy/API models can pick up real context windows from endpoint catalog metadata such as `context_length`; otherwise unknown lengths stay explicit unknowns rather than default values. Known lengths feed chat/agent token-budget scaling through `src.context_budget`. Token estimation counts assistant `tool_calls` arguments so compaction sees tool-only turns instead of underestimating them. Chat/agent context budgeting should call this layer instead of hardcoding model windows.
+`src.model_context` owns model context-length lookup/query and token estimation. Cache keys include endpoint plus model so identical model names on different endpoints do not bleed context-window data. Local llama.cpp context probes try `/slots` and then `/props.default_generation_settings.n_ctx`. Unknown proxy/API models can pick up real context windows from endpoint catalog metadata such as `context_length`; otherwise unknown lengths stay explicit unknowns rather than default values. Known lengths feed chat/agent token-budget scaling through `src.context_budget`. Token estimation counts assistant `tool_calls` arguments so compaction sees tool-only turns instead of underestimating them. Chat/agent context budgeting should call this layer instead of hardcoding model windows.
 
 ## Runtime Fallback And Routing
 
@@ -127,6 +105,18 @@ Provider tool calls are untrusted requests, not authorization. `supports_tools`
 - SSE/stream parsers tolerate null choice/usage/tool-call entries and null streaming tool-call arguments; provider events should degrade to empty text or shaped stream errors instead of crashing the chat loop.
 - Provider adapters carry small model-specific quirks: Opus 4.7+ and official Kimi/Moonshot code payloads omit `temperature`, Kimi/Moonshot/Mistral reasoning content is preserved separately, ChatGPT Subscription refreshes bearer credentials, native Ollama can handle multimodal content, and Ollama `/v1` responses for Qwen3/Gemma4-style thinking can suppress thinking text when requested.
 
+## Additional Runtime Owners
+
+`src.generation_budget` estimates native tool-schema and image reserve costs, fits output limits to the remaining context budget, and parses provider context errors for bounded recovery. `llm_core` uses these helpers in async/streaming paths; recovery is separate from switching to a fallback model. `src.model_context.estimate_text_tokens()` counts non-ASCII characters individually and Latin characters at roughly 0.3 tokens each, including tool-call names/arguments. These remain estimates, not tokenizer guarantees.
+
+`src.model_profiles` selects the Odysseus compact schema and progressive-thinking profile from bounded `odysseus`/`ajax` tokens in the model ID leaf. `supports_user_thinking_toggle()` uses explicit model-family patterns and suppresses the toggle for that profile and GPT/o-series leaves; these are runtime heuristics outside the canonical reader. Endpoint `model_tool_modes` accepts `none`, `compact`, or `full` per model, with legacy aliases normalized by model routes. This is schema/routing configuration, not tool execution authority.
+
+`src.utility_effort` resolves owner-aware utility effort, including fallback-specific overrides and eligible session-route effort. Validation currently uses ChatGPT model metadata, including maintained defaults and model-name fallback metadata; it is not evidence from the canonical reader. `src.model_pricing` owns server-side known-price estimates; unknown models return no estimate and local/subscription endpoints are excluded from per-token cost tracking.
+
+Featherless endpoints use an explicit pin inventory instead of bulk catalog refresh. Admin `GET /api/model-endpoints/{ep_id}/catalog-search` searches active conversational models available on the current plan with bounded pagination and a 45-second in-memory query cache. New Featherless rows default to an empty pin list. `/api/models?refresh=true&wait_refresh=true` can wait up to 15 seconds on the shared background refresh.
+
+`src.endpoint_resolver.resolve_owner_registered_endpoint()` accepts only an enabled owner-visible registered base or its derived chat URL, returning the server-owned row. URL identity includes scheme, host, effective port, and path; caller credentials, query strings and fragments are rejected. `same_endpoint_base()` governs exact origin/base-path credential reuse. Native runtimes can rewrite persisted `host.docker.internal` bases to loopback.
+
 ## Security Policy
 
 - Endpoint API keys are encrypted in `ModelEndpoint.api_key` and never returned by endpoint APIs; admin surfaces return key presence only.
@@ -143,9 +133,15 @@ Provider tool calls are untrusted requests, not authorization. `supports_tools`
 - utility model fallbacks for summarization/extraction;
 - frontend Settings and model picker endpoint management.
 
+## Discovery And Route Identity Details
+
+`src.model_discovery` timestamps successful Tailscale host queries, including an empty result, for the 60-second cache. A failed query does not become a successful empty observation. This discovery cache is separate from endpoint URL resolution and model-context probe caches.
+
+Exact registered endpoint authority rejects URL credentials, parameters, and any query or fragment delimiter, including an empty one; it accepts the registered base or an explicitly derived inference route rather than broad same-host aliases. Owner-visible shared endpoint rows remain distinct from exact-owner-only data. Utility effort forwarding remains explicit at participating callers; a configured off/none/default selection can suppress session effort rather than being treated as a missing override.
+
 ## Current Gaps
 
-- Runtime provider detection, model curation, and frontend logos are still split across `llm_core`, `model_routes`, and `providers.js`; the canonical reader package has no production consumer yet.
+- Runtime provider detection, model curation, and frontend logos are still split across `llm_core`, `model_routes`, and `providers.js`; canonical records have no runtime model-catalog consumer yet, while provider detection is reused by media paths.
 - Provider-specific behavior is concentrated in `llm_core.py`, which is large and easy to regress.
 - Several runtime request builders still use model-name heuristics. They should migrate only after endpoint/provider code supplies structured identity and a real consumer contract; the canonical catalog does not add a parallel quirk matcher.
 - Endpoint identity and fallback behavior need careful review when new OAuth/subscription providers are added.
diff --git a/specs/memory-skills.md b/specs/memory-skills.md
index 2933c6c68..291061b5b 100644
--- a/specs/memory-skills.md
+++ b/specs/memory-skills.md
@@ -1,6 +1,6 @@
 # Memory And Skills
 
-Last updated: dev@2e2bb52 | 2026-08-16
+Last updated: dev@c74f475 | 2026-10-15
 
 ## Scope
 
@@ -14,7 +14,7 @@ This spec covers persistent memory and user skills in:
 - provider abstractions in `src/memory_provider.py`;
 - LLM extraction/audit in `services/memory/memory_extractor.py`;
 - skill storage, format, import, and extraction in `services/memory/skills.py`, `services/memory/skill_format.py`, `services/memory/skill_importer.py`, and `services/memory/skill_extractor.py`;
-- skill routes in `routes/skills_routes.py`;
+- skill HTTP/compatibility bindings in `routes/skills_routes.py` and evaluation/audit/job/model/prompt/publication services under `services/skills/`;
 - prompt/tool call sites in `src/chat_processor.py`, `src/agent_loop.py`, `src/ai_interaction.py`, `src/tool_implementations.py`, `src/tool_execution.py`, `src/tool_schemas.py`, and `src/tool_security.py`;
 - MCP and Codex surfaces in `mcp_servers/memory_server.py` and `routes/codex_routes.py`;
 - backup/admin/CLI surfaces in `routes/backup_routes.py`, canonical `routes/admin_wipe/admin_wipe_routes.py` plus its shim, `scripts/odysseus-memory`, `scripts/odysseus-skills`, and `scripts/odysseus-backup`;
@@ -43,25 +43,23 @@ Extraction handles reasoning-model response shapes and records explicit dislike/
 
 `services/memory/skills.py` owns disk-backed skill storage under `data/skills/<category>/<name>/SKILL.md`, plus `_usage.json` usage/audit sidecars. Legacy `data/skills.json` is a read-only fallback/import source, not the current write shape.
 
-`services/memory/skill_format.py` owns frontmatter/body parsing and emission. Quoted scalar parsing/emission is symmetric: JSON escapes decode once, UTF-8/non-ASCII stays intact, emitted values escape line separators safely, and invalid JSON-style escapes fall back to literal text instead of compounding backslashes on every save. `services/memory/skill_importer.py` resolves public GitHub/skills URLs, fetches bundle files with strict public-network URL safety, and chooses/imports `SKILL.md`. Import disables automatic redirects, follows at most five hops, validates and resolves each hop, then connects only to the validated IP snapshot through a pinned transport while preserving URL, Host, and TLS identity; GitHub final-host checks and file/size limits still apply. `routes/skills_routes.py` owns CRUD/search/index/import, owner filtering, skill test/audit jobs, and admin-gated built-in tool instruction overrides.
+`services/memory/skill_format.py` owns frontmatter/body parsing and emission. Quoted scalar parsing/emission is symmetric: JSON escapes decode once, UTF-8/non-ASCII stays intact, emitted values escape line separators safely, and invalid JSON-style escapes fall back to literal text instead of compounding backslashes on every save. `services/memory/skill_importer.py` resolves public GitHub/skills URLs, fetches bundle files with strict public-network URL safety, and chooses/imports `SKILL.md`. Import disables automatic redirects, follows at most five hops, validates and resolves each hop, then connects only to the validated IP snapshot through a pinned transport while preserving URL, Host, and TLS identity; GitHub final-host checks and file/size limits still apply. `routes/skills_routes.py` owns HTTP CRUD/search/index/import, authentication/owner verification, exact approval validation, request models and admin-gated built-in instruction overrides. Evaluation, execution, job coordination, audit sequencing and publication policy now live under `services/skills/`; durable identity/storage/lifecycle remains in `services/memory/skills.py`.
 
 Skill extraction is owned by `services/memory/skill_extractor.py`. It can suggest or save skills from conversations, tries valid brace-delimited JSON candidates with `JSONDecoder.raw_decode()`, rejects ambiguous multiple top-level JSON objects instead of guessing, and saved skills remain user-editable data.
 
 Agent skill behavior:
 
 - matched skills are owner-scoped, confidence-gated, usage-counted, and wrapped as untrusted context;
-- `index_for()` exposes published skills plus teacher-escalation drafts gated by platform and toolsets; `active_toolsets=None` means the caller has no explicit toolset knowledge and does not hide `requires_toolsets` skills, while an explicit list applies the gate;
+- `index_for()` exposes built-ins and eligible user skills gated by current approval policy, platform, local-model status, and toolsets; `active_toolsets=None` means the caller has no explicit toolset knowledge and does not hide `requires_toolsets` skills, while an explicit list applies the gate;
 - user prefs such as skills enabled, auto-approve, and max injected skills shape runtime insertion;
-- the level-0 base skill index currently calls `index_for(owner=None)`, so it is not fully owner-scoped.
+- the level-0 skill index passes the acting owner into `index_for()`, applies active-toolset/platform and local-model gates, and returns its user-editable index block separately for untrusted-context wrapping.
 - skill tests use the configured utility model rather than the chat default and wrap user-editable skill text as untrusted context; approval continuation for a test or teacher-generated skill uses the same exact-action gate as the normal agent loop.
 
 ## Tools, MCP, And Backup
 
 Native `manage_memory` and `manage_skills` tool paths pass owner context and use in-process policy gates. `manage_skills` requires an explicit action instead of silently defaulting a malformed call. Manual memory add can choose a category, and route-side manual add validates the source session owner before attaching session-derived memories. `mcp_servers/memory_server.py` lazy-initializes `src` managers and exposes list/add/edit/delete/search. It can scope to `ODYSSEUS_MCP_MEMORY_OWNER` or `ODYSSEUS_MEMORY_OWNER`; if the JSON store contains owner-bearing entries and no owner env is configured, it returns an owner-scope error instead of listing or mutating across owners. Ownerless stores remain ownerless compatibility mode.
 
-The direct `odysseus-memory add` CLI tolerates non-object legacy/corrupt rows
-when checking whether its newly added entry is already present; it ignores
-those rows instead of calling mapping methods on them and crashing the add.
+The direct `odysseus-memory add` CLI tolerates non-object legacy/corrupt rows when checking whether its newly added entry is already present; it ignores those rows instead of calling mapping methods on them and crashing the add.
 
 `/api/export` owner-filters memories and skills. `/api/import` imports skills through current disk-backed `SkillsManager` APIs, stamping missing owners to the importer and preserving supported skill metadata. Full data snapshots through `scripts/odysseus-backup` preserve on-disk skill trees, memory JSON, and caches differently from JSON import/export.
 
@@ -92,7 +90,7 @@ Owner isolation is surface-specific:
 - native memory/skill tools are expected to pass owner context;
 - Codex exposes scoped token memory behavior separately;
 - normal memory/skills routes are cookie/current-user surfaces, not scoped token APIs;
-- MCP memory uses an environment-configured owner for owner-scoped stores, while the agent level-0 skill index currently has ownerless/global behavior;
+- MCP memory uses an environment-configured owner for owner-scoped stores, while the agent level-0 skill index now passes the acting owner;
 - vector dedup during memory extraction suppresses only same-owner or legacy-ownerless vector matches.
 
 Skill test/audit flows intentionally run user-editable `SKILL.md` content as instructions inside controlled jobs. Those jobs rely on route owner checks, admin gates where applicable, and tool execution policy.
@@ -107,10 +105,41 @@ Existing tests cover memory extraction/degraded vectors, owner isolation, unread
 
 Route-level memory CRUD/security, skills route security, MCP memory behavior, vector degraded writes, compatibility facade owner behavior, backup skill import, admin vector cleanup, and frontend endpoint wiring need broader coverage.
 
+## Skill Approval, Retrieval, And Persona Continuity
+
+`services/memory/builtin_skills.py` synchronizes tracked `BUILTIN_SKILLS_DIR` procedures at startup into an immutable ownerless shared catalog, published with confidence 1.0. Owner-aware list/view paths expose these built-ins alongside the owner's skills; built-ins skip user audits. User-editable memories and imported/extracted skills retain their untrusted-context treatment.
+
+`SkillsManager.index_for()` excludes failing user audits and unnecessary skills. With automatic approval enabled, a user skill needs published status, a passing audit, and confidence at the owner's current threshold; a stale published flag alone is insufficient. Manual publication supplies approval when automatic approval is disabled. `remote-only` skills are hidden from local/private-endpoint model indices. Search also gates toolsets and platforms, combining lexical scores with optional semantic scores from `src/skill_index.py`; semantic retrieval reuses an already-ready ToolIndex embedding lane and falls back to lexical search without a foreground cold model load.
+
+Skill audit protocol v2 separates functional pass/fail from no-skill baseline utility, storing summary, baseline verdict, usefulness, saved turns/tool calls, and audit version in `_usage.json`. Legacy inconclusive v1 results are eligible for re-audit. `services/memory/skill_lifecycle.py` supplies a bounded automatic queue: transient/inconclusive checks retry daily, failed/needs-work repairs weekly, and built-in/binned/pass/skipped entries are excluded. Route jobs preserve request authority and exact-action approval continuation.
+
+Memory extraction automatically pins new identity/contact facts only while the count of already-pinned identity/contact entries for the acting owner and compatible ownerless entries is below five; it does not unpin older entries. Extra facts remain retrievable by relevance. Persona continuity extraction stores concise notes in preset/persona data through `PresetManager.update_persona_memory()`, separately from global memory JSON; health personas use a cautious medical brief schema and persona deletion removes its notes.
+
+## Mutation And Audit Lifecycle Limits
+
+Memory edit/delete paths reject empty identities instead of allowing an empty substring match, and mutating operations preserve unreadable-store refusal. Persona extraction updates an existing persona rather than creating a missing persona implicitly; persona notes remain separate from global memory.
+
+`services/skills/publication.py` implements batch finalization behind the route compatibility wrapper `_finalize_audit_batch()` and changes only skills processed by that job, protects approval-required results, and retains binned duplicates on disk while excluding them from retrieval. Name normalization and a 0.38 token-Jaccard threshold group potential duplicates; this heuristic is not semantic equivalence. Functional success and baseline usefulness remain separate audit dimensions, so a successful baseline does not itself make the skill functionally inconclusive.
+
+`SkillAuditUnavailable` stops the batch without treating infrastructure failure as a skill verdict. Other audit errors can record inconclusive results. Manual test and audit agent streams use `contextlib.aclosing`, including early exits for exact-action approval, so the originating agent task closes rather than remaining suspended behind a pending choice. These lifecycle guarantees do not establish successful model execution when the provider or containment backend is unavailable.
+
+## Skill Test Endpoint Recovery
+
+Skill tests prefer the configured utility route; their registered fallback resolves server-owned runtime credentials and does not trust caller-supplied provider headers. The audit-arm path raises `SkillAuditUnavailable` on stream failure and stops the batch without a skill verdict. Manual primary-stream exceptions instead retain a partial transcript for subsequent baseline/evaluation; if grading returns `fail`, confidence can still decrease. An unavailable result is not guaranteed for every manual-test failure.
+
+## Skills Service Boundaries
+
+`services/skills/evaluation.py` owns verdict parsing/grading, necessity/retrieval assessment, efficiency fields and markdown improvement. `agent_runner.py` owns manual/audit agent streams, transcripts, request/exact-approval authority and same-task `aclosing`. `audit_workflow.py` owns per-skill checks, self-edit/worker retry, optional distinct-teacher rewrite, sequential batches and scheduled selection. `job_coordinator.py` owns transient job transitions, candidate selection, safe polling projections and cancellation requests. `model_selection.py` resolves owner-scoped worker/teacher credentials and utility fallback; `prompts.py` constructs tasks and explicitly untrusted skill messages. `publication.py` applies confidence/duplicate/publishing policy through SkillsManager; its preferences adapter still imports `routes.prefs_routes`.
+
+Routes retain patchable aliases/wrappers, including the service-owned manual/audit registry dictionaries and `SkillAuditUnavailable`. A frozen `AuditDependencies` is built from current route bindings at service entry, preserving caller/test seams without rebinding service globals or importing the Skills route module from services. `app.py` still registers the same router and built-in actions still use route compatibility helpers. Registries are process-local jobs, not durable stores.
+
+Manual completion adjusts confidence (pass .95, needs_work .6, fail .4) without publishing. Audits compare skill/no-skill arms on one task; clean/self-edit/teacher passes use .95/.85/.8, and continued non-pass after retries becomes draft at .35. Initial unknown/inconclusive verdicts preserve publication state during per-skill finalization; this does not cover rewrite retries or later batch duplicate finalization. Per-skill auto-publish requires enabled owner policy/threshold and no necessity/utility/duplicate blocker. Batch duplicate finalization instead selects a processed passing keeper at or above the threshold, can publish it under the owner policy without reapplying those per-skill blockers, and bins other eligible processed duplicates; approval-required and unrelated skills remain protected from that batch mutation.
+
+Approval validation stays in HTTP: pending job/id/owner/empty-session must match and the sealed grant is consumed with `allow_continuation=False` before continuation. Resumed skill/transcript context remains untrusted; unattended arms deny encountered approvals. Infrastructure unavailability stops a batch without a skill verdict or finalization. Existing limits remain: rewrite retry results other than pass, including unknown/inconclusive or an approval pause, can still lead to demotion, and manual cancellation may retain private continuation state. Extraction does not add model/containment availability or broad behavioral equivalence guarantees.
+
 ## Current Gaps
 
 - `services/memory/service.py` needs an explicit owner-scope/support decision before it is treated as a public memory API.
-- The agent level-0 skill index should thread owner or be documented as an intentional local/global index.
 - MCP memory still needs a deliberate multi-user UX/config decision, but current behavior avoids cross-owner access when owner-bearing rows exist without an explicit MCP owner env.
 - Memory JSON import does not rebuild vector indexes.
 - Admin wipe vector clearing is currently ineffective.
diff --git a/specs/model-capability-canonical.md b/specs/model-capability-canonical.md
index 75e646f37..5648c61c9 100644
--- a/specs/model-capability-canonical.md
+++ b/specs/model-capability-canonical.md
@@ -1,6 +1,6 @@
 # Canonical Provider And Model Capability Layer
 
-Last updated: dev@e71f8ce | 2026-08-25
+Last updated: dev@86b886c | 2026-10-14
 
 ## Scope
 
@@ -15,14 +15,9 @@ This spec covers the implementation introduced on current `dev` in:
 - regression coverage in `tests/test_model_capabilities.py` and
   `tests/test_model_capability_readers.py`.
 
-The layer normalizes already-fetched JSON-compatible values. It performs no
-network I/O, does not shape provider requests, does not persist its output, and
-does not authorize model or tool use. No production caller currently consumes
-the canonical records outside this package; runtime integration remains later
-work.
+The layer normalizes already-fetched JSON-compatible values. It performs no network I/O, does not shape provider requests, does not persist its output, and does not authorize model or tool use. No production caller currently consumes the canonical records outside this package; runtime integration remains later work.
 
-There is no `src/provider_capability_schemas.py`, capability-specific
-diagnostics module, or runtime model-quirk registry on current `dev`.
+There is no `src/provider_capability_schemas.py`, capability-specific diagnostics module, or runtime model-quirk registry on current `dev`.
 
 ## Layer Boundaries
 
@@ -47,9 +42,7 @@ diagnostics module, or runtime model-quirk registry on current `dev`.
   capability object, assertions, deterministic controls, and optional raw
   provider evidence.
 
-Provider transport support and per-model support are separate facts. Request
-and response adapters remain in `src.llm_core` and related provider modules.
-Model-specific observations remain in [model-quirks.md](model-quirks.md).
+Provider transport support and per-model support are separate facts. Request and response adapters remain in `src.llm_core` and related provider modules. Model-specific observations remain in [model-quirks.md](model-quirks.md).
 
 ## Current Serialized Shapes
 
@@ -70,20 +63,13 @@ Model-specific observations remain in [model-quirks.md](model-quirks.md).
 }
 ```
 
-`ModelCapabilityRecord.to_dict()` wraps that value with `vendor`, `model_id`,
-`stable_model_id`, `display_name`, `capability_assertions`, and
-`deterministic_controls`. It does not currently emit a schema version or the
-flat `provider`/`model`/`features`/`controls` shape. Raw provider fields are
-included only when the caller passes `include_raw=True`.
+`ModelCapabilityRecord.to_dict()` wraps that value with `vendor`, `model_id`, `stable_model_id`, `display_name`, `capability_assertions`, and `deterministic_controls`. It does not currently emit a schema version or the flat `provider`/`model`/`features`/`controls` shape. Raw provider fields are included only when the caller passes `include_raw=True`.
 
-Endpoint configuration can explicitly map `model_type=llm` to chat and
-`model_type=image` to image generation. Missing or unrecognized endpoint types
-stay unknown rather than silently becoming chat-capable in this schema layer.
+Endpoint configuration can explicitly map `model_type=llm` to chat and `model_type=image` to image generation. Missing or unrecognized endpoint types stay unknown rather than silently becoming chat-capable in this schema layer.
 
 ## Identity And Reader Dispatch
 
-`records_from_payload()` selects a reader from an explicit `vendor`, or from
-`detect_vendor(base_url, endpoint_kind)` when no vendor is supplied.
+`records_from_payload()` selects a reader from an explicit `vendor`, or from `detect_vendor(base_url, endpoint_kind)` when no vendor is supplied.
 
 Current detection order and behavior are:
 
@@ -94,11 +80,7 @@ Current detection order and behavior are:
 
 These are normalization hints, not authorization. Hostname checks accept an exact domain or its dot-delimited subdomains after lowercasing and removing a trailing dot, so names such as `notopenai.com` do not match `openai.com`; local-port mappings remain intentionally covered by tests. Callers must not treat any result as proof of endpoint trust.
 
-Implemented reader modules are `generic_openai`, `openai`, `openrouter`,
-`google`, `llamacpp`, `ollama`, and `lmstudio`. Anthropic, Hugging Face,
-SGLang, and vLLM have placeholder vendor IDs but currently dispatch through the
-generic identity-only reader. Other explicitly supplied vendor strings are
-also preserved while using that generic reader.
+Implemented reader modules are `generic_openai`, `openai`, `openrouter`, `google`, `llamacpp`, `ollama`, and `lmstudio`. Anthropic, Hugging Face, SGLang, and vLLM have placeholder vendor IDs but currently dispatch through the generic identity-only reader. Other explicitly supplied vendor strings are also preserved while using that generic reader.
 
 Stable model identity is scoped in this order:
 
@@ -108,15 +90,9 @@ Stable model identity is scoped in this order:
 
 ## Generic Identity-Only Contract
 
-The generic reader accepts mapping payloads containing `data[]` or `models[]`.
-Each item must itself be a mapping and provide `id`, `name`, or `model`.
-Bare-list payloads and `key`/`slug`-only items are not accepted by the current
-implementation.
+The generic reader accepts mapping payloads containing `data[]` or `models[]`. Each item must itself be a mapping and provide `id`, `name`, or `model`. Bare-list payloads and `key`/`slug`-only items are not accepted by the current implementation.
 
-The reader deliberately returns unknown family, modalities, capabilities, and
-controls. It preserves the raw item on the in-memory record but does not parse
-type/task fields, descriptions, ownership, supported-parameter lists,
-capability-looking booleans, or token limits.
+The reader deliberately returns unknown family, modalities, capabilities, and controls. It preserves the raw item on the in-memory record but does not parse type/task fields, descriptions, ownership, supported-parameter lists, capability-looking booleans, or token limits.
 
 ## Provider-Native Readers
 
@@ -136,22 +112,13 @@ capability-looking booleans, or token limits.
   served model. It records tool/streaming claims, explicit unsupported
   vision/audio assertions, controls, and runtime/training/size limits.
 
-Readers tolerate non-object entries and unknown fields where their helpers
-permit it. They do not infer authoritative capability from model IDs or display
-names.
+Readers tolerate non-object entries and unknown fields where their helpers permit it. They do not infer authoritative capability from model IDs or display names.
 
 ## Evidence Semantics
 
-The canonical vocabulary includes admin override, endpoint configuration,
-provider reader, Cookbook/Hugging Face, maintained registries, heuristic,
-probe, and unknown sources. It also defines explicit, provider-reported,
-registry, heuristic, and unknown confidence values.
+The canonical vocabulary includes admin override, endpoint configuration, provider reader, Cookbook/Hugging Face, maintained registries, heuristic, probe, and unknown sources. It also defines explicit, provider-reported, registry, heuristic, and unknown confidence values.
 
-Those tokens make evidence representable; current `dev` does not implement a
-global precedence, merge, expiry, or conflict-resolution engine. Assertions
-generated by readers are usually `claimed`; a `CapabilityProbeResult` maps pass
-to verified, fail to unsupported, and partial to claimed at the scope carried
-by that object.
+Those tokens make evidence representable; current `dev` does not implement a global precedence, merge, expiry, or conflict-resolution engine. Assertions generated by readers are usually `claimed`; a `CapabilityProbeResult` maps pass to verified, fail to unsupported, and partial to claimed at the scope carried by that object.
 
 ## Tests
 
@@ -165,6 +132,8 @@ Focused tests pin:
 - OpenRouter, Google, Ollama, LM Studio, and llama.cpp mappings;
 - negative cases that avoid name-based media/capability inference.
 
+The provider detector has narrow production consumers in `src/ai_interaction.py` and `routes/gallery/gallery_routes.py` for selecting OpenRouter media request behavior. `ModelCapabilityRecord` normalization remains disconnected from runtime model discovery and request builders; helper reuse must not be described as full canonical integration.
+
 ## Current Gaps
 
 - Canonical records are not yet used by runtime discovery, endpoint resolution, model context, request shaping, or frontend pickers.
diff --git a/specs/model-providers/_readme.md b/specs/model-providers/_readme.md
index 61d89b902..b2f300756 100644
--- a/specs/model-providers/_readme.md
+++ b/specs/model-providers/_readme.md
@@ -1,6 +1,6 @@
 # Provider Capability Specs
 
-Last updated: dev@e71f8ce | 2026-08-25
+Last updated: dev@86b886c | 2026-10-14
 
 ## Scope
 
@@ -54,6 +54,7 @@ Current reader dispatch does not infer a provider from payload shape. It uses an
 - [github-copilot.md](github-copilot.md): account model-list observations and required runtime headers.
 - [chatgpt-subscription.md](chatgpt-subscription.md): Codex model identity and Responses event shape.
 - [cohere.md](cohere.md): native endpoint/catalog observations; not currently normalized.
+- [featherless.md](featherless.md): plan-filtered catalog search and explicit picker pins without bulk discovery.
 
 ### Other provider identity and general/identity-only observations
 
diff --git a/specs/model-providers/chatgpt-subscription.md b/specs/model-providers/chatgpt-subscription.md
index a961c1714..3ab9e67fc 100644
--- a/specs/model-providers/chatgpt-subscription.md
+++ b/specs/model-providers/chatgpt-subscription.md
@@ -1,43 +1,40 @@
 # ChatGPT Subscription Provider Shape
 
-Last updated: dev@e57f60b | 2026-07-20
+Last updated: dev@86b886c | 2026-10-15
 
 ## Scope
 
-Canonical provider ID `chatgpt_subscription`; Codex Responses transport;
-auth and runtime code in `src/chatgpt_subscription.py`,
-`routes/chatgpt_subscription_routes.py`, and `src/llm_core.py`.
-There is no dedicated ChatGPT Subscription canonical reader on current `dev`.
+Canonical provider ID `chatgpt_subscription`; Codex Responses transport; auth and runtime code in `src/chatgpt_subscription.py`, `routes/chatgpt_subscription_routes.py`, and `src/llm_core.py`. There is no dedicated ChatGPT Subscription canonical reader on current `dev`.
 
 ## Catalog Shape
 
-The account-scoped Codex models endpoint returns root `models[]`; `slug` is the
-request identity and `visibility`/`priority` control availability/order. These
-fields do not prove tools, reasoning, vision, or context. Null/malformed model
-lists fail soft rather than crashing discovery (#5280/#5281).
+The account-scoped Codex models endpoint returns root `models[]`; `slug` is the request identity and `visibility`/`priority` control availability/order. These fields do not prove tools, reasoning, vision, or context. Null/malformed model lists fail soft rather than crashing discovery (#5280/#5281).
 
-The canonical generic reader does not accept `slug`-only items, so this runtime
-catalog is not currently normalized into `ModelCapabilityRecord` values.
+The canonical generic reader does not accept `slug`-only items, so this runtime catalog is not currently normalized into `ModelCapabilityRecord` values.
 
 ## Request And Response Shape
 
-Transport uses a ChatGPT backend Responses endpoint, `input` items, flattened
-function tools, streamed function-call argument events, exact `call_id`, and
-`function_call_output` continuation. Parallel calls and encrypted reasoning
-continuity require preserving typed output/history rather than coercing all
-roles to text. This shape is supported by the existing adapter and the focused
-tool-calling follow-up evidence in #5490; unmerged observations remain claimed
-until integrated/reproduced.
+Transport uses an inference-only ChatGPT backend Responses payload allowlist: model, instructions, input, stream, store, optional temperature and reasoning effort. It drops native tools, tool choice, previous-response/background fields and unrelated options. `build_responses_input()` flattens conversation history into text input/output items; multipart image blocks are not preserved. Native tool calls/results and encrypted typed reasoning continuity are not preserved as a general protocol. Agent tools therefore use the text protocol on this provider rather than a claimed native function-call continuation.
 
-OAuth/device credentials and refresh are provider-session behavior. Expired
-credentials should return an actionable reconnect error, not generic model
-failure.
+OAuth/device credentials and refresh are provider-session behavior. Expired credentials should return an actionable reconnect error, not generic model failure.
 
 ## Fallback And Safety
 
-Only the explicit internal base/ChatGPT host selects this provider. Never send
-subscription credentials to a custom OpenAI-compatible URL. Catalog slugs stay
-identity-only unless account-scoped fields or probes supply capability.
+Only the explicit internal base/ChatGPT host selects this provider. Never send subscription credentials to a custom OpenAI-compatible URL. Catalog slugs alone remain identity-only. Runtime catalog metadata can retain advertised reasoning levels, but the runtime also supplies maintained defaults and model-name fallback metadata; those are not canonical verified capability cards.
+
+## Account And Usage Ownership
+
+Device-flow setup supports multiple accounts using stable provider-auth IDs; display labels are not identity. Reconnect, delete, inventory and account usage are owner-scoped. Subscription endpoint inventory applies exact effective-owner equality even for admins, and refresh deduplication includes the provider-auth ID to keep accounts separate.
+
+`GET /api/chatgpt-subscription/accounts/{auth_id}/usage` returns normalized rate-limit telemetry for exactly one owned auth session. `src.chatgpt_subscription.UsageCache` keeps deep-copied normalized snapshots for 45 seconds, bounded to 256 auth-id entries with FIFO eviction rather than single-flight refresh, and ownership is checked before cache hits. Forced refresh replaces the snapshot; reconnect/deletion invalidates cached usage. Errors return credential-free unavailable payloads. `static/js/chatgptSubscriptionUsage.js` owns the frontend read/display flow.
+
+Runtime catalog metadata retains supported/default reasoning levels and is exposed through `/api/models` model metadata. `validate_reasoning_effort()` omits unsupported overrides; its maintained defaults and name-based fallback are runtime compatibility rules rather than canonical provider evidence.
+
+## Binding And Telemetry Limits
+
+New account setup creates a distinct auth/endpoint pair. Sessions persist endpoint id so the bound endpoint wins over labels; removed or disabled bound endpoints fail closed rather than borrowing another login. Legacy unbound sessions can bind the oldest enabled owner-visible URL-matching endpoint before resolving its exact owner-scoped auth session. Runtime bearer credentials are attached request-locally only to the registered subscription route. Forked session account identity and usage cache ownership remain independent of chat approval grants.
+
+Usage parsing bounds finite numeric telemetry, preserves missing values as unknown and shapes credential-free errors; a JWT claim can supply unverified routing metadata without becoming verified identity. Usage cache and optimistic UI expansion do not guarantee fresh quota or live provider acceptance. Session `effort:<level>` is validated on model changes/partial generation settings, and reasoning effort partitions inference cache identity; metadata defaults/name fallbacks remain compatibility evidence.
 
 ## Current Gaps
 
diff --git a/specs/model-providers/featherless.md b/specs/model-providers/featherless.md
new file mode 100644
index 000000000..e49c3e332
--- /dev/null
+++ b/specs/model-providers/featherless.md
@@ -0,0 +1,26 @@
+# Featherless Provider Shape
+
+Last updated: dev@86b886c | 2026-10-15
+
+## Scope
+
+Runtime provider ID `featherless`; OpenAI-compatible calls in `src/llm_core.py`, catalog and picker ownership in `routes/model_routes.py`, and setup/selection UI in `static/js/admin.js` and `static/js/providers.js`. No dedicated canonical capability reader exists.
+
+## Catalog And Picker
+
+Normal endpoint probing returns no bulk Featherless inventory. New rows use API endpoint kind and an explicit empty pin list; only selected model IDs become picker inventory. Admin `GET /api/model-endpoints/{ep_id}/catalog-search` queries `/v1/models` with `q`, `available_on_current_plan=true`, `status=active`, `conversational=true`, and bounded `page`/`per_page` (maximum 100). Its in-memory cache lasts 45 seconds and keys endpoint ID, normalized query and pagination. Upstream authorization, rate-limit and timeout failures become route errors rather than fabricated model cards.
+
+Reachability tries `/v1/plan` and then a one-item plan-filtered model query. Endpoint status and selected model inventory are distinct facts; a reachable account need not have any pinned models.
+
+## Request And Capability Boundaries
+
+Calls use the OpenAI-compatible runtime adapter. Model availability on the current plan does not prove native tools, reasoning, modality, or context. Per-model endpoint tool modes are operator configuration; canonical generic normalization remains identity-only.
+
+## Selection UI Limits
+
+The admin picker debounces queries after two characters, pages bounded catalog results and saves pins/tool modes optimistically. Initial search cancellation does not establish equivalent load-more generation guards, and ignored PATCH response status does not prove accepted persistence. Lowercased query cache identity, explicit empty pins and endpoint reachability remain separate from provider plan/capability acceptance.
+
+## Current Gaps
+
+- No native canonical reader maps plan/catalog evidence into capability records.
+- Catalog search is a live provider dependency; cache and pins do not guarantee continued account availability.
diff --git a/specs/model-providers/llama-cpp.md b/specs/model-providers/llama-cpp.md
index 6073c5bbb..86d61bc57 100644
--- a/specs/model-providers/llama-cpp.md
+++ b/specs/model-providers/llama-cpp.md
@@ -1,17 +1,14 @@
 # llama.cpp Provider Shape
 
-Last updated: dev@e57f60b | 2026-07-20
+Last updated: dev@86b886c | 2026-10-14
 
 ## Scope
 
-Canonical provider ID `llamacpp`; OpenAI Chat/Responses and Anthropic Messages
-compatibility plus native server metadata; reader
-`src/model_capability_readers/llamacpp.py`.
+Canonical provider ID `llamacpp`; OpenAI Chat/Responses and Anthropic Messages compatibility plus native server metadata; reader `src/model_capability_readers/llamacpp.py`.
 
 ## Metadata Shapes
 
-`/v1/models` provides served identity and can include server model entries;
-native `/props` is authoritative for the running model/server combination:
+`/v1/models` provides served identity and can include server model entries; native `/props` is authoritative for the running model/server combination:
 
 - `model_alias`/`model_path`;
 - `default_generation_settings.n_ctx` and sampling `params`;
@@ -20,25 +17,17 @@ native `/props` is authoritative for the running model/server combination:
 - `modalities.vision|audio`;
 - current server/build state.
 
-Capability depends on weights, projection/model assets, chat template, parser,
-and launch flags. It is endpoint evidence, not a checkpoint-name claim.
-`/props` and `/v1/models` can be merged only for the same served identity.
+Capability depends on weights, projection/model assets, chat template, parser, and launch flags. It is endpoint evidence, not a checkpoint-name claim. `/props` and `/v1/models` can be merged only for the same served identity.
 
 ## Request And Response Shape
 
-llama-server supports several OpenAI-compatible tasks and native extensions.
-Do not infer embeddings/rerank/chat solely from the OpenAI model card; use an
-explicit server model capability field or endpoint configuration. Tool and
-reasoning correctness can depend on selected chat template and parser.
+llama-server supports several OpenAI-compatible tasks and native extensions. Do not infer embeddings/rerank/chat solely from the OpenAI model card; use an explicit server model capability field or endpoint configuration. Tool and reasoning correctness can depend on selected chat template and parser.
 
 ## Fallback And Safety
 
-The registry selects llama.cpp through an explicit vendor or endpoint kind; it
-does not auto-detect `/props` from payload shape. Port 8000 currently maps to
-the vLLM placeholder, while 8080 falls through to generic OpenAI-compatible.
-llama.cpp-only `session_id` and `cache_prompt` affinity fields must remain local
-endpoint behavior and never leak to strict cloud providers (#4640 and current
-affinity tests).
+The registry selects llama.cpp through an explicit vendor or endpoint kind; it does not auto-detect `/props` from payload shape. Port 8000 currently maps to the vLLM placeholder, while 8080 falls through to generic OpenAI-compatible. llama.cpp-only `session_id` and `cache_prompt` affinity fields must remain local endpoint behavior and never leak to strict cloud providers (#4640 and current affinity tests).
+
+Runtime context lookup in `src/model_context.py` tries `/slots` first and falls back to `/props.default_generation_settings.n_ctx`, covering servers launched without `--slots`. This runtime path remains separate from canonical reader merging.
 
 ## Current Gaps
 
diff --git a/specs/model-quirks.md b/specs/model-quirks.md
index 3faafa3a0..3bab5f7b7 100644
--- a/specs/model-quirks.md
+++ b/specs/model-quirks.md
@@ -1,19 +1,12 @@
 # Model Behavior Observations
 
-Last updated: dev@2e2bb52 | 2026-08-16
+Last updated: dev@86b886c | 2026-10-14
 
 ## Scope
 
-This file records model- or provider+model-specific behavior observed in
-Odysseus code, tests, Issues, PRs, commits, and provider documentation. It is a
-compact evidence map, not a runtime matcher. General canonical rules belong in
-[model-capability-canonical.md](model-capability-canonical.md); provider-wide
-transport belongs in [the provider map](model-providers/_readme.md).
+This file records model- or provider+model-specific behavior observed in Odysseus code, tests, Issues, PRs, commits, and provider documentation. It is a compact evidence map, not a runtime matcher. General canonical rules belong in [model-capability-canonical.md](model-capability-canonical.md); provider-wide transport belongs in [the provider map](model-providers/_readme.md).
 
-The canonical capability layer intentionally has no
-`src/model_behavior_quirks.py`.
-Adding a registry before runtime call sites carry structured provider, model,
-version, and dialect identity would create another model-name matching layer.
+The canonical capability layer intentionally has no `src/model_behavior_quirks.py`. Adding a registry before runtime call sites carry structured provider, model, version, and dialect identity would create another model-name matching layer.
 
 ## General Observation Template
 
@@ -27,9 +20,7 @@ Record only the fields supported by the evidence:
 - source, confidence, status, and reproduction date;
 - whether the behavior is already implemented in runtime code.
 
-If exact structured identity is unavailable, keep the observation here and in
-its current tested runtime location. Do not promote it through substring,
-regex, prose, or serialized-prompt parsing in the canonical layer.
+If exact structured identity is unavailable, keep the observation here and in its current tested runtime location. Do not promote it through substring, regex, prose, or serialized-prompt parsing in the canonical layer.
 
 ## Model-Specific Observation Map
 
@@ -43,9 +34,7 @@ regex, prose, or serialized-prompt parsing in the canonical layer.
 | Ollama native `gpt-oss` reasoning level | `gpt-oss` served through Ollama native | `think` accepts low/medium/high and does not represent off | provider docs; deployment scoped |
 | Ollama compatibility disable observation | Ollama 0.20.6+, observed Qwen3.5 compatibility path | `reasoning_effort: none` was reported to disable reasoning | #5503; unmerged/low confidence until reproduced |
 
-Issue and commit references are evidence identifiers, not runtime dependencies.
-Open or unmerged observations remain provisional until reproduced or supported
-by current provider documentation.
+Issue and commit references are evidence identifiers, not runtime dependencies. Open or unmerged observations remain provisional until reproduced or supported by current provider documentation.
 
 ## Other Model-Level Observations
 
@@ -73,13 +62,11 @@ by current provider documentation.
   #1704, #1478). Native engine metadata or a verified endpoint probe outranks
   a model-family name list.
 
+Current `src.model_profiles` is a separate runtime schema/thinking profile helper: bounded `odysseus`/`ajax` tokens in the model ID leaf select compact schema and progressive thinking. It is not the absent canonical behavior registry. `src.utility_effort` validates utility effort against ChatGPT metadata that includes maintained/model-name defaults; callers must not describe those defaults as verified provider capability.
+
 ## Promotion Gate
 
-Before an observation becomes canonical runtime behavior, a consumer must
-already have the necessary structured identity and tests must cover both its
-positive scope and a neighboring negative scope. Request control and response
-visibility remain separate: hiding reasoning text is not the same as disabling
-reasoning at the provider (#2905).
+Before an observation becomes canonical runtime behavior, a consumer must already have the necessary structured identity and tests must cover both its positive scope and a neighboring negative scope. Request control and response visibility remain separate: hiding reasoning text is not the same as disabling reasoning at the provider (#2905).
 
 ## Current Gaps
 
diff --git a/specs/persistence.md b/specs/persistence.md
index 39224f9cc..50249841b 100644
--- a/specs/persistence.md
+++ b/specs/persistence.md
@@ -1,6 +1,6 @@
 # Persistence
 
-Last updated: dev@e71f8ce | 2026-08-25
+Last updated: dev@c74f475 | 2026-10-15
 
 ## Scope
 
@@ -13,8 +13,7 @@ This spec covers durable state in:
 - `core/models.py`;
 - `core/session_manager.py`;
 - `core/atomic_io.py`;
-- `src/attachment_refs.py`, `src/upload_handler.py`, and
-  `routes/upload_routes.py` for durable upload references and retention;
+- `src/attachment_refs.py`, `src/upload_handler.py`, and `routes/upload_routes.py` for durable upload references and retention;
 - JSON stores managed by `core/auth.py`, `src/settings.py`, `src/api_key_manager.py`, `src/preset_manager.py`, `src/integrations.py`, `src/upload_handler.py`, `src/personal_docs.py`, `src/research_handler.py`, `src/bg_jobs.py`, `routes/prefs_routes.py`, canonical `routes/contacts/contacts_routes.py` and `routes/vault/vault_routes.py` plus their shims, `routes/cookbook_routes.py`, and memory/skills managers;
 - canonical `routes/email/email_helpers.py` scheduled-email storage;
 - `routes/backup_routes.py` and `scripts/odysseus-backup`;
@@ -24,15 +23,9 @@ This spec covers durable state in:
 
 `core/database.py` owns SQLAlchemy models and startup migrations. `src/database.py` is a compatibility re-export for legacy imports. Route and service code commonly owns its own `SessionLocal()` lifecycle instead of using one central unit-of-work wrapper.
 
-The default database is SQLite at `DATA_DIR/app.db`. `src.runtime_paths` and `src.constants` own the data-dir default: source runs use the repository `data/` directory, frozen builds default to `~/.odysseus/data`, and `ODYSSEUS_DATA_DIR` overrides both. SQLAlchemy can point at a non-SQLite `DATABASE_URL`, but current startup migrations/backfills are SQLite-first and often use `sqlite3`, `PRAGMA`, or SQLite catalog queries. External DBs are not fully migration-compatible unless those helpers are made backend-neutral.
+The default database is SQLite at `DATA_DIR/app.db`. `src.runtime_paths` and `src.constants` own the data-dir default: source runs use the repository `data/` directory, frozen builds default to `~/.odysseus/data`, and `ODYSSEUS_DATA_DIR` overrides both. The core requirements include `psycopg2-binary` for PostgreSQL driver availability. SQLAlchemy can point at a non-SQLite `DATABASE_URL`, but current startup migrations/backfills are SQLite-first and often use `sqlite3`, `PRAGMA`, or SQLite catalog queries. External DBs are not fully migration-compatible unless those helpers are made backend-neutral.
 
-After `Base.metadata.create_all()`, `init_db()` resolves file-backed SQLite
-paths from SQLAlchemy's parsed engine URL and attempts to restrict the main
-database plus existing `-journal`, `-wal`, and `-shm` sidecars to `0600` on
-POSIX. Driver-qualified, query-tagged, and local `file:` URI forms are covered;
-non-SQLite, in-memory SQLite, and Windows paths are skipped. A failed POSIX
-chmod is logged because the database and sidecars can contain password/token
-hashes and encrypted provider material.
+After `Base.metadata.create_all()`, `init_db()` resolves file-backed SQLite paths from SQLAlchemy's parsed engine URL and attempts to restrict the main database plus existing `-journal`, `-wal`, and `-shm` sidecars to `0600` on POSIX. Driver-qualified, query-tagged, and local `file:` URI forms are covered; non-SQLite, in-memory SQLite, and Windows paths are skipped. A failed POSIX chmod is logged because the database and sidecars can contain password/token hashes and encrypted provider material.
 
 Timestamp defaults use `utcnow_naive()` so existing naive `DateTime` columns stay UTC without the deprecated `datetime.utcnow()` default.
 
@@ -44,17 +37,15 @@ Current model families include:
 - email accounts, model endpoints, MCP servers, comparisons;
 - provider auth sessions for OAuth/device-flow-backed provider credentials;
 - API tokens, admin-global webhooks, user tools/tool data, integrations;
-- crew members, scheduled tasks, task runs, notes;
-- memory rows, calendar calendars, and calendar events.
+- crew members, scheduled tasks, task runs, notification logs, background tool jobs, notes;
+- memory rows, calendar calendars, calendar events, and email-calendar invitation revision/tombstone state.
 
-Chat persistence stores model-readable text plus compact attachment-reference
-lines in `chat_messages.content`, while structured references remain in message
-metadata. Provider data URLs used by the live turn are not duplicated into the
-durable transcript. The FTS migration recreates insert/update triggers to omit
-inline media and scrubs legacy indexed rows that still contain data URLs.
+Chat persistence stores model-readable text plus compact attachment-reference lines in `chat_messages.content`, while structured references remain in message metadata. Provider data URLs used by the live turn are not duplicated into the durable transcript. The FTS migration recreates insert/update triggers to omit inline media and scrubs legacy indexed rows that still contain data URLs.
 
 Current calendar/task persistence includes CalDAV remote identity columns (`CalendarCal.remote_href`, `CalendarCal.remote_etag`, `CalendarEvent.remote_href`, `CalendarEvent.remote_etag`), `CalendarEvent.caldav_sync_pending` for retryable writeback state, and `ScheduledTask.character_id` for built-in task persona selection.
 
+`Note.gallery_id` links drawing notes to stable gallery images. `CalendarEvent` source-email identifiers preserve invitation provenance; `EmailCalendarInvitation` keeps owner/sender/source/recurrence revision and cancellation state for replay decisions.
+
 `EmailAccount` includes encrypted password fields plus Google OAuth fields (`oauth_provider`, encrypted access/refresh tokens, token expiry) and optional `display_name`. Startup migrations add those OAuth/display columns idempotently for older databases.
 
 Email default-account state is serialized per owner. Startup normalizes legacy duplicate defaults and installs a per-owner unique default constraint/index; create, delete/promotion, set-default, demo teardown, and user rename perform their default transition in one locked transaction. Multi-owner rename locks are acquired in canonical order, so a stale concurrent default mutation fails closed instead of recreating multiple defaults.
@@ -127,6 +118,20 @@ Docker bind-mounts `data/`, `logs/`, cache/local state, and optional Chroma stat
 
 ChromaDB/vector stores are optional durable storage outside `data/app.db`; missing Chroma degrades RAG, memory-vector, and tool-index features without blocking core SQLite/JSON persistence. Vector collections can be lane-suffixed for custom HTTP embeddings versus FastEmbed fallback. See `documents-rag-uploads.md`.
 
+## Run Evidence And New Durable State
+
+`Session` adds `cwd`, endpoint id, memory-extraction/injection and skill-injection toggles, thinking mode, temperature/max-token overrides, and cumulative cost. `ModelEndpoint.model_tool_modes` stores per-model tool-schema preferences. `ScheduledTask.request_authority_json` stores the server-only admitted request snapshot. Startup migration helpers add these columns to legacy schemas. `BackgroundToolJob` holds origin owner/session/tool/query, status, payload/summary, and delivered message id; `NotificationLog` persists owner-attributed task completion/error notification text.
+
+`src.agent_runtime.effect_log` stores append-only claims, outcomes, and observations in `DATA_DIR/effects/<root-run-id>.jsonl`, with launch-generation indexes alongside them. Claims are fsynced before backend invocation; persistence failure refuses execution. Reload appends interrupted outcomes for unsettled non-running claims, while eligible owned `RUNNING` process claims survive for background lifecycle settlement; it never manufactures success or fresh state. Appends merge durable history under an advisory lock before allocating positions. Cross-process locking and directory-fsync guarantees are POSIX-specific; other platforms have narrower guarantees. Claim files use restrictive creation, no-follow/regular-file/single-link checks, strict row validation and a tolerated torn final tail. Non-claim persistence can degrade to volatile evidence; durable claim failure still refuses invocation. Advisory-lock append merges durable rows, allocates positions and repairs only a torn tail; reader locking does not silently repair. Launch indexes use fsync/replace ordering, with narrower non-POSIX guarantees. These checks do not imply authenticated tamper-proof logs, constant-cost growth or identical index hardlink checks. This store is evidence, not operation authority.
+
+`data/containment_grants.json` and `data/bg_jobs.json` preserve containment/process identity across restart. Browser producer state resolves through `BROWSER_RESOURCES_DIR` in shared constants. These server control-plane stores are denied to native model filesystem operations; ownership and runtime integrity must remain separate from editable user artifacts.
+
+## Cleanup Counts And Chroma Volumes
+
+`src/cleanup_service.py` derives preview and deletion eligibility from durable message rows, not the session counter. Recent-session protection uses a limited ID query; final DELETE rechecks owner/archive/age/importance/message threshold. DELETE RETURNING identifies cleanup-owned deletions where supported; legacy SQLite uses rowcount plus survivor queries, with estimated space attribution bounded to the deleted count. Session-cache eviction occurs after commit.
+
+The standard, AMD and NVIDIA Compose files mount `chromadb-data` at `/data`; native Chroma uses `data/chroma/`. Pre-fix Docker stores may have live data in the old container writable layer despite an empty volume at `/chroma/chroma`; recreation can destroy that layer. `docs/chromadb-volume-migration.md` documents cold rescue, image preservation, empty-volume seeding and staging/count verification before cutover. This is an operator procedure, not startup migration or proof of data recovery.
+
 ## Current Gaps
 
 - Migration behavior is centralized but long and manual.
@@ -134,4 +139,4 @@ ChromaDB/vector stores are optional durable storage outside `data/app.db`; missi
 - Some JSON store shapes are only documented by manager code and tests.
 - Startup migrations lack a legacy-schema/idempotence test harness for owner backfills, encrypted-secret rewrites, and repeated runs.
 - JSON-store atomicity is inconsistent across stores, though shared atomic writers, upload metadata recovery, prefs, and strict memory mutations now have focused coverage.
-- Agent filesystem tools currently allow broad `data/` access; secret-bearing files under `data/` need explicit deny coverage.
+- New local stores require explicit ownership, backup, and control-plane access decisions; a filesystem root alone does not grant access to server state.
diff --git a/specs/research.md b/specs/research.md
index 6ea3a1907..67491d072 100644
--- a/specs/research.md
+++ b/specs/research.md
@@ -1,6 +1,6 @@
 # Research
 
-Last updated: dev@e71f8ce | 2026-08-25
+Last updated: dev@86b886c | 2026-10-15
 
 ## Scope
 
@@ -50,8 +50,8 @@ Agent tools and the CLI read and mutate persisted research JSON directly. They a
 `src.deep_research.DeepResearcher` owns multi-round research work:
 
 - date/context setup;
-- search provider selection and fallback through `src.search.providers` and `src.search.core`;
-- URL/content fetching through `src.search.fetch_webpage_content`;
+- search provider selection and fallback through `src.research_navigator.ResearchNavigator`, which dispatches the shared provider chain;
+- URL/content fetching through `ResearchNavigator.fetch()` and the canonical service content fetcher, with structured unavailable results for disabled private-browser reads;
 - separate tracking of analyzed URLs, last search errors, and empty-round limits;
 - source summarization/extraction;
 - synthesis into final answers/reports;
@@ -80,12 +80,7 @@ Spinoff/Discuss creates a new chat session from a saved report. It seeds the rep
 
 Research persistence uses `data/deep_research/<session_id>.json`. Current JSON can include result/report text, raw report, sources, raw findings, stats, category, archived state, hidden images, owner, timestamps, and consumed state.
 
-Route access to persisted report files is path-confined. Browser routes validate
-session ids against `^[a-zA-Z0-9-]{1,128}$`, enumerate trusted `*.json` files
-under the resolved research storage root, match by exact filename, reject
-symlink/path escapes after `resolve().relative_to(root)`, and then perform owner
-checks before detail/archive/delete/result-peek/spinoff reads or mutations.
-Invalid ids return 400; missing or cross-owner reports return 404.
+Route access to persisted report files is path-confined. Browser routes validate session ids against `^[a-zA-Z0-9-]{1,128}$`, enumerate trusted `*.json` files under the resolved research storage root, match by exact filename, reject symlink/path escapes after `resolve().relative_to(root)`, and then perform owner checks before detail/archive/delete/result-peek/spinoff reads or mutations. Invalid ids return 400; missing or cross-owner reports return 404.
 
 `src.visual_report` owns HTML report generation from markdown-like research output, heading/TOC processing, category styling, image injection, allowlist sanitization of untrusted rendered HTML, and client-side controls for hiding images and discussing reports.
 
@@ -119,8 +114,7 @@ The active FastAPI app path uses `src.research_handler.ResearchHandler`.
 
 `services/research/service.py` is a public wrapper around a duplicate `services.research.research_handler.ResearchHandler`. That services handler remains compatibility/cleanup surface rather than canonical runtime truth; check parity before assuming it has every active-route field or policy behavior.
 
-Its source extraction skips non-dict finding rows so one malformed cached or
-generated entry does not discard later valid URL/title/summary sources.
+Its source extraction skips non-dict finding rows so one malformed cached or generated entry does not discard later valid URL/title/summary sources.
 
 Search compatibility also matters: `src.search.core`, `src.search.providers`, and `src.search.content` alias the service search path so old imports stay live without a second fetch implementation.
 
@@ -145,6 +139,12 @@ Existing useful coverage includes deep-research runtime/degraded tests, handler/
 
 Coverage is still thin around live job route ownership, `/api/research/start` route behavior, SSE/result-peek/cancel edges, spinoff endpoint ownership, tool/CLI direct JSON access, remote-image policy, and frontend panel/jobs behavior.
 
+## Bounded Navigation And Evidence
+
+`src.research_navigator.py` owns parsed `ResearchAction` requests, normalized `ResearchPage` responses, and source assessments. Search uses the shared provider chain off the event loop; ordinary fetch uses the canonical URL-safe content fetcher, while `browser_read` requests the private browser tool and currently receives the common denial for page actions. `DeepResearcher` chooses bounded navigation actions, records retrieval mode/provider use and source coverage, and can request a browser retry for weak fetches; the current disabled page-action policy prevents that retry from supplying page evidence.
+
+Small local model heuristics select a simpler fact/research path with smaller planning calls. Findings-window synthesis and extraction concurrency/timeouts still bound work; useful source text remains a dependency; private-browser page actions are currently unavailable. Scheduled research binds sealed task authority around the handler call; direct handler/route behavior must not be assumed to share that scheduling wrapper. Saved reports retain gathered evidence and fallback reports when model synthesis cannot complete.
+
 ## Current Gaps
 
 - Consolidate, retire, or clearly deprecate `services/research/research_handler.py`.
diff --git a/specs/runtime.md b/specs/runtime.md
index 47b76a839..9295f27f3 100644
--- a/specs/runtime.md
+++ b/specs/runtime.md
@@ -1,6 +1,6 @@
 # Runtime
 
-Last updated: dev@e71f8ce | 2026-08-25
+Last updated: dev@c74f475 | 2026-10-15
 
 ## Scope
 
@@ -13,10 +13,10 @@ This spec covers current app runtime wiring in:
 - `core/constants.py`;
 - `src/constants.py`;
 - `src/interactive_gate.py`;
+- `src/process_reaper.py`, `src/process_lifecycle.py`, and `src/process_ownership.py`;
 - `src/host_docker_access.py`;
 - `core/middleware.py`;
-- all route setup functions registered from `app.py`, including canonical
-  `routes/admin_wipe/`, `routes/cleanup/`, `routes/compare/`, `routes/contacts/`, `routes/document/`, `routes/gallery/`, `routes/history/`, `routes/mcp/`, `routes/memory/`, `routes/note/`, `routes/research/`, `routes/search/`, `routes/task/`, `routes/vault/`, and `routes/webhook/` packages plus top-level compatibility shims;
+- all route setup functions registered from `app.py`, including canonical `routes/admin_wipe/`, `routes/cleanup/`, `routes/compare/`, `routes/contacts/`, `routes/document/`, `routes/gallery/`, `routes/history/`, `routes/mcp/`, `routes/memory/`, `routes/note/`, `routes/research/`, `routes/search/`, `routes/task/`, `routes/vault/`, and `routes/webhook/` packages plus top-level compatibility shims;
 - `routes/prefs_routes.py`, `routes/workspace_routes.py`, and `companion/routes.py`;
 - `src/generated_images.py` for generated-media file resolution;
 - `launcher.py`, `Odysseus.spec`, and platform launcher scripts where frozen/native startup changes runtime paths;
@@ -30,9 +30,7 @@ This spec covers current app runtime wiring in:
 
 `app.py` separately owns runtime singletons and integration hooks for auth, vector RAG, TTS/STT, webhooks, scheduled tasks, MCP, assistant log globals, event bus wiring, AI interaction globals, API-token cache invalidation, and foreground activity tracking. `src.runtime_paths` owns source-versus-frozen app/data path resolution; `src.constants` derives `DATA_DIR` from `ODYSSEUS_DATA_DIR` or that runtime default. `core/constants.py` and `src/constants.py` are both live import paths and are not fully identical today, so new constants need explicit placement/compatibility decisions.
 
-The shared upload handler is also installed on the session manager and tool
-helper, and `app.py` injects it into attachment-bearing route factories so
-durable writers and cleanup use one lifecycle owner.
+The shared upload handler is also installed on the session manager and tool helper, and `app.py` injects it into attachment-bearing route factories so durable writers and cleanup use one lifecycle owner.
 
 ## Routes And Static Serving
 
@@ -46,9 +44,9 @@ Admin wipe, cleanup, compare, contacts, documents, gallery, history, MCP, memory
 
 The SPA routes `/`, `/notes`, `/calendar`, `/cookbook`, `/email`, `/memory`, `/gallery`, `/tasks`, and `/library` all serve `static/index.html`. `static/` is served with revalidation for `.js`, `.css`, and `.html` because the frontend ships raw browser modules with no hashed build output.
 
-Direct app-owned endpoints include `/api/generated-image/{filename}`, `/backgrounds`, `/login`, `/api/version`, `/api/health`, `/api/ready`, `/api/runtime`, and `/api/activity/heartbeat`. `/backgrounds` points at `static/backgrounds.html`; if that file is absent or the route remains auth-gated, that is route/static drift rather than an intentional public contract.
+Direct app-owned endpoints include `/api/generated-image/{filename}`, `/backgrounds`, `/login`, `/api/version`, `/api/health`, `/api/ready`, `/api/runtime`, and `/api/activity/heartbeat`. The `/backgrounds` prototype route points at the absent `static/backgrounds.html` and is auth-gated when authentication is enabled despite its handler docstring describing it as public. This remains known route/static drift at the checked revision.
 
-`/static/*` is auth-exempt and public. SPA HTML routes are auth-gated except `/login`, and they are nonce-injected dynamic `HTMLResponse` values outside the static mount. Generated images and videos are served from `data/generated_images` through the generated-image resolver with immutable/nosniff caching.
+`/static/*` is auth-exempt and public. SPA HTML routes are auth-gated except `/login`, and they are nonce-injected dynamic `HTMLResponse` values outside the static mount. Generated images and videos are served from `data/generated_images` through the generated-image resolver with private, no-cache, must-revalidate/nosniff headers; access checks precede disk probing and database verification errors return 503 (see `gallery-editor-media.md`).
 
 ## Runtime Security Boundaries
 
@@ -58,7 +56,7 @@ Security headers include HSTS and a restrictive `Permissions-Policy` that disabl
 
 `_TIMEOUT_EXEMPT_PREFIXES` owns hard-timeout bypass policy. It is prefix-based and currently exempts all subroutes under `/api/chat`, `/api/shell/stream`, `/api/research`, `/api/model/download`, `/api/model/probe`, `/api/model-endpoints`, `/api/cookbook/setup`, `/api/upload`, `/api/image`, and `/api/memory/audit`. Memory audit has its own longer inactivity timeout.
 
-Generated-image path resolution fails closed for invalid names, path escape, and missing files. Ownership checks are best-effort when a current user exists: gallery rows owned by a different user return 404, rowless generated files are allowed, and DB/helper failures fail open. See `auth-security.md` for `LOCALHOST_BYPASS`, internal-tool loopback, proxy-header exclusion, and owner-impersonation policy.
+Generated-image serving validates filename syntax before identity and access checks, then resolves the confined path and verifies file existence. With auth enabled, missing identity returns 401; recent registration, gallery ownership, linked-session ownership or an owned-chat metadata reference supplies the implemented access criterion. Missing or mismatched access returns 404, and database verification failures return 503. Explicit disabled-auth mode skips ownership verification. See `gallery-editor-media.md` for branch ordering and registry lifetime, and `auth-security.md` for `LOCALHOST_BYPASS`, internal-tool loopback, proxy-header exclusion, and owner-impersonation policy.
 
 ## Runtime Behavior
 
@@ -70,12 +68,11 @@ Generated-image path resolution fails closed for invalid names, path escape, and
 
 ## Lifespan Startup
 
-Upload cleanup first snapshots durable chat, document, gallery, note, and
-calendar references and aborts on scan or upload-index integrity failure.
+Upload cleanup first snapshots durable chat, document, gallery, note, and calendar references and aborts on scan or upload-index integrity failure.
 
 Startup purges leftover incognito sessions, reconciles default scheduled tasks before the task runner starts, and backfills legacy skill owners when possible.
 
-Startup fire-and-forget work includes upload cleanup, background-job monitoring, MCP built-in registration and user-server connection, tool-index warmup, model-endpoint warmup, endpoint keepalive, Cookbook serve lifecycle monitoring, hourly null-owner sweeps, and nightly skill audit. The in-process task scheduler is gated by `ODYSSEUS_INPROCESS_TASKS`; email polling is started from email route setup and gated separately by `ODYSSEUS_INPROCESS_POLLERS`. Foreground-gate knobs are `BACKGROUND_TASK_FOREGROUND_GATE`, `BACKGROUND_TASK_QUIET_MS`, `BACKGROUND_TASK_MAX_WAIT_SECONDS`, and `BACKGROUND_TASK_BROWSER_ACTIVE_SECONDS`.
+Startup fire-and-forget work includes upload cleanup, background-job monitoring, MCP built-in registration and user-server connection, tool-index warmup, model-endpoint warmup, endpoint keepalive, Cookbook serve lifecycle monitoring, and hourly null-owner sweeps. Skills Audit is scheduled per owner by `TaskScheduler`; app lifespan deliberately does not start a second ownerless audit. The in-process task scheduler is gated by `ODYSSEUS_INPROCESS_TASKS`; email polling is started from email route setup and gated separately by `ODYSSEUS_INPROCESS_POLLERS`. Foreground-gate knobs are `BACKGROUND_TASK_FOREGROUND_GATE`, `BACKGROUND_TASK_QUIET_MS`, `BACKGROUND_TASK_MAX_WAIT_SECONDS`, and `BACKGROUND_TASK_BROWSER_ACTIVE_SECONDS`.
 
 Shutdown cancels upload cleanup, stops the task scheduler, closes the webhook manager, and disconnects MCP servers.
 
@@ -90,10 +87,20 @@ Shutdown cancels upload cleanup, stops the task scheduler, closes the webhook ma
 - `src.host_docker_access` treats host Docker access from inside the container as opt-in. Default Compose does not mount `/var/run/docker.sock`; `docker/host-docker.yml` plus `ODYSSEUS_ENABLE_HOST_DOCKER=true` are required before local container code considers the host Docker daemon available.
 - Chroma-backed consumers degrade independently: personal-doc RAG can return route-level 503s, semantic memory vectors can be dropped from chat/memory wiring, and the tool index can fall back when vector retrieval is unavailable.
 - RAG startup failure is throttled so failed clients do not poison later retries.
-- MCP startup is asynchronous and non-critical. User-server connection is bounded, failures surface through MCP status routes, and builtin MCP calls can reconnect after crashes.
-- `/api/health` is liveness only. `/api/ready` checks database reachability, writable data dir, and local-first storage metadata; it does not prove optional subsystem health for RAG, Chroma, MCP, memory vectors, tool index, or endpoint warmups.
+- MCP startup is asynchronous and non-critical. User-server connection is bounded, failures surface through MCP status routes, and unbound builtin MCP calls can reconnect after crashes; incarnation-bound calls return failure rather than silently replacing the backend.
+- `/api/health` is liveness only. `src.readiness.check_readiness()` reports database reachability, writable data dir, informational local-first storage metadata and tool-index state. Database/data-dir checks gate `/api/ready`; `ODYSSEUS_REQUIRE_TOOL_INDEX_READY` additionally makes tool-index readiness critical when enabled. Default readiness does not certify RAG, Chroma, MCP, memory vectors or endpoint warmups.
 - `/api/diagnostics/services` is an admin diagnostics endpoint for optional service health. It reports bounded, non-intrusive checks for ChromaDB, SearXNG, email accounts, ntfy, and model provider endpoints with `ok`/`degraded`/`down`/`disabled` style status values and strips secret-bearing URLs/errors. `/api/diagnostics/logs` returns a bounded tail of the app log for admin troubleshooting.
 
+## Startup Process Reconciliation
+
+Lifespan calls `src.process_reaper` once to reconcile persisted containment grants and detached job identities from previous server runs. Verified orphan processes under abandoned containment grants are torn down; owned detached jobs intentionally survive restart. Unverifiable containment grants remain active and unsignalled, while `src.bg_jobs.disown_unverified()` marks foreign/unverifiable running job records failed without signalling and preserves pending follow-up. Retiring a record does not establish process death. `src.process_lifecycle` owns identity checks, TERM/KILL escalation, and observed-death receipts; caller-specific containment/browser/Cookbook policy remains outside it.
+
+## Process And Service-Home Limits
+
+Native launch readiness is a bounded functional containment probe plus exact supervisor/worker acknowledgement, not executable presence. Startup reconciliation retains unverified ownership and running detached job generations instead of fabricating death or renewed permission. Background delivery revalidates linkage after asynchronous continuation and retires exact observed-dead launch records; invalidated jobs do not prevent registry cleanup during shutdown. Missing procfs degrades discovery/command-line evidence and does not authorize signaling.
+
+`core.platform_compat.service_home()` uses Windows `Path.home()` without importing `pwd`. Successful POSIX real-UID passwd lookup ignores a child HOME override; a missing passwd entry or lookup OS error falls back to `Path.home()`, which can honor that override. Model-visible runtime/context metadata is bounded and untrusted; environment-key allowlists do not scrub explicitly supplied values. Readiness errors expose bounded error categories rather than raw exception details, and readiness still does not certify optional provider/browser/model health.
+
 ## Current Gaps
 
 - `app.py` is still a large route registry and runtime orchestrator. There is no generated route manifest or smaller runtime composition layer yet.
diff --git a/specs/search.md b/specs/search.md
index 09fc8082a..c967aee8f 100644
--- a/specs/search.md
+++ b/specs/search.md
@@ -1,6 +1,6 @@
 # Search
 
-Last updated: dev@e71f8ce | 2026-08-25
+Last updated: dev@86b886c | 2026-10-15
 
 ## Scope
 
@@ -64,13 +64,11 @@ Runtime behavior:
 - rejection of localhost, metadata, private, reserved, multicast, and link-local targets;
 - redirect revalidation on each hop;
 - one-time public DNS resolution per hop plus an `httpcore`/`httpx` pinned
-  transport that connects to the validated public IP while preserving the
-  original URL, Host header, and TLS SNI, closing DNS-rebinding time-of-check
-  drift;
+  transport that connects to the validated public IP while preserving the original URL, Host header, and TLS SNI, closing DNS-rebinding time-of-check drift;
 - metadata, Open Graph image, list, table, code block, PDF, and text extraction;
 - readable text extraction for `text/*`, Markdown, `.txt`, `.json`, `.jsonl`, and JSON content types;
 - central User-Agent behavior through `WEB_FETCH_USER_AGENT`;
-- soft and hard download byte caps through `WEB_FETCH_SOFT_MAX_BYTES` and `WEB_FETCH_HARD_MAX_BYTES`, with declared-length and streaming-budget checks; requests prefer identity transfer encoding so compressed bodies cannot bypass the effective body cap;
+- soft and hard download byte caps through `WEB_FETCH_SOFT_MAX_BYTES` and `WEB_FETCH_HARD_MAX_BYTES`, with declared-length and streaming-budget checks; decoded response bytes are capped even for compressed transfer encodings, and truncation is reported;
 - JS-heavy empty result hints;
 - cache writes;
 - empty/error result shape, including explicit HTTP-status failures instead of raising through callers.
@@ -124,12 +122,28 @@ Deep research wraps fetched webpage content through `untrusted_context_message("
 
 ## Optional And Platform Behavior
 
-`ddgs` is optional; provider code has an HTML fallback. Search cache and analytics state live under the shared data dir and mkdir failures in read-only image layers are tolerated where possible. PDF extraction uses `pdfminer.six` only when installed. Native SearXNG defaults to `http://localhost:8080`; Docker uses the compose `searxng` service URL and pins the SearXNG image with a healthcheck.
+`ddgs` is optional; provider code has an HTML fallback. Search cache and analytics state live under the shared data dir and mkdir failures in read-only image layers are tolerated where possible. PDF extraction prefers pypdf layout text with a plain-text compatibility fallback and page labels, then optional pdfminer; a truncated soft-budget PDF can retry within the hard cap when its declared size allows. Native SearXNG defaults to `http://localhost:8080`; Docker uses the compose `searxng` service URL and pins the SearXNG image with a healthcheck.
 
 Compose preserves retained SearXNG settings but runs `scripts/migrate_searxng_settings.py` before startup to add missing `use_default_settings: true` inheritance. The migration accepts only a regular single-document YAML mapping, preserves BOM/newline/style/ownership/mode, writes and directory-fsyncs atomically, and no-ops when the key exists. Compose treats migration failure as non-fatal so SearXNG health reports the retained-file problem instead of the wrapper command preventing startup.
 
 `httpx` and BeautifulSoup are required runtime dependencies for the active search/fetch path.
 
+## Query Repair And Extractive Observations
+
+`services/search/core.py` normalizes conversational provider queries, filters low-relevance results, respects explicit site scope, retries bounded broadened queries after empty results, and reapplies relevance/ranking on cache hits. Completed empty provider responses advance through the chain instead of repeating the same request as if it were a transport error. Named scholarly work lookup can use arXiv/OpenAlex metadata before generic search, and exact arXiv identifiers have a direct source path.
+
+`src/search_intent.py` distinguishes requested publication windows from current reference information: current documentation/configuration alone does not imply recently published pages. `src/search_passages.py` owns literal, query-relevant excerpts and balanced bounded search observations across fetched sources, preserving explicit omission markers and source headers rather than prefix-truncating away later sources. These are extractive observations, not generated source claims. Deep research shares provider primitives through its navigator but retains its own result and failure shapes.
+
+## Retrieval Limits And Source Selection
+
+When SearXNG is primary and `searxng_yep` is absent from the configured chain, `_build_provider_chain()` inserts that separate candidate at index one, including when SearXNG is the only configured provider. An already configured YEP position is retained; other primary providers do not get the automatic insertion. Missing keyed providers are excluded. Exact-empty query relaxation is bounded and disabled for explicit operators, quotes or exclusions. Low-relevance filtering can retain scoped results rather than invent a confident match. Temporal qualifiers can exclude a year from product-number overlap checks, while genuine numeric model names remain significant.
+
+News category and publication window are independent: current events infer a day and news a week where no explicit window exists, while current reference documentation does not imply recent publication. Software release hints can retain general category; explicit windows survive JSON-to-HTML and news-to-general fallback along with language/engines/SafeSearch. The optional DuckDuckGo HTML request has a maximum five-second request timeout, not a bound on the complete multi-provider search.
+
+HTML extraction removes chrome from a parsed copy, prefers semantic main content and a sole substantial article (at least 200 stripped characters), and avoids ancestor duplication; multiple article cards retain main context. Thin-body and access-challenge rules are heuristics. An exact challenge title with corroborating short body is an unavailable page even under HTTP200 and is not cached as article evidence. XML/Atom preserves bounded raw text; failed arXiv category/date listings can return a suggested start-zero/max100 Atom URL without fetching it or claiming completeness. Extractor caches use the current semantic-links namespace rather than old parser results.
+
+Scholarly metadata uses a versioned User-Agent, a 12-second lookup timeout and shared 20-second monotonic budget, with at most three manually checked redirects and cleared original query parameters after redirect. This helper checks destinations but uses ordinary HTTP transport rather than claiming the separate outbound-fetch DNS connection pinning contract. Title/identifier matching remains heuristic metadata lookup, not independent verification of a paper. Direct browser-source citations and search snippets remain untrusted and insufficient to certify full-report evidence.
+
 ## Current Gaps
 
 - Search route handlers need direct tests for request body formats, provider validation, provider availability, and route error/empty-result shapes.
diff --git a/specs/settings-admin.md b/specs/settings-admin.md
index ef468bf35..9b008ad19 100644
--- a/specs/settings-admin.md
+++ b/specs/settings-admin.md
@@ -1,6 +1,6 @@
 # Settings And Admin Surfaces
 
-Last updated: dev@e71f8ce | 2026-08-25
+Last updated: dev@c74f475 | 2026-10-15
 
 ## Scope
 
@@ -20,7 +20,7 @@ This spec covers settings and admin surfaces in:
 - `routes/model_routes.py` for `/api/tools` and settings-bound model endpoint references;
 - `src/agent_tools/admin_tools.py`, `src/tool_implementations.py`, `src/tool_execution.py`, `src/tool_schemas.py`, and `src/tool_index.py` for `manage_settings`;
 - `src/agent_loop.py` for stale agent prompt references to settings APIs;
-- frontend modules `static/js/appConfig.js`, `static/js/settings.js`, `static/js/settings/{registry,navigation,lifecycle,search,dom,sidebar,shell,peek,oauthReturn}.js`, `static/js/admin.js`, `static/js/presets.js`, `static/js/theme.js`, and `static/js/storage.js`;
+- frontend modules `static/js/appConfig.js`, `static/js/settings.js`, `static/js/settings/{registry,navigation,lifecycle,search,dom,sidebar,shell,peek,oauthReturn,agent,api,imageModels,speech,writingStyle}.js`, `static/js/admin.js`, `static/js/presets.js`, `static/js/theme.js`, and `static/js/storage.js`;
 - CLI helpers `scripts/odysseus-preset` and `scripts/odysseus-theme`.
 
 Generic API integrations are cross-referenced in `integrations.md`. Model endpoint CRUD and endpoint cleanup are covered in `llm-models.md`. Email/contact/calendar legacy setting fallbacks stay with their domain specs.
@@ -54,10 +54,10 @@ Other active stores include:
 Settings runtime:
 
 - `GET /api/auth/features` is public feature visibility metadata;
-- `POST /api/auth/features` is admin-only;
-- `GET /api/auth/settings` returns full settings to admins;
-- non-admin or unauthenticated `GET /api/auth/settings` returns `scrub_settings()` output;
-- `POST /api/auth/settings` is admin-only and only writes keys present in `DEFAULT_SETTINGS`.
+- `POST /api/auth/features` requires admin unless auth is explicitly disabled;
+- `GET /api/auth/settings` returns full settings to admins and the disabled-auth operator;
+- with auth enabled, non-admin or unauthenticated `GET /api/auth/settings` returns `scrub_settings()` output;
+- `POST /api/auth/settings` requires admin unless auth is explicitly disabled and only writes keys present in `DEFAULT_SETTINGS`.
 
 `src.settings_scrub` owns deep secret-key scrubbing for non-admin settings reads, including snake_case and camelCase secret-like key names. It preserves structure while blanking secret-shaped string values.
 
@@ -75,7 +75,7 @@ Admin gates inherit the auth contracts in `auth-security.md`: normal deployments
 - bundled accessibility font selection such as OpenDyslexic and text-size variable application;
 - CSS variable application.
 
-`static/js/settings.js` owns domain panel load/save behavior and compatibility exports, while `static/js/settings/registry.js` is the canonical group/panel metadata inventory. `navigation.js` activates panels and lazy admin content, `search.js` implements the registry-backed finder while filtering admin-only entries, `lifecycle.js` owns modal open/close/Escape/drag/docking behavior, `sidebar.js` owns persisted collapse/resize state, and `dom.js` holds shared DOM helpers. `shell.js` owns the coordination above those primitives — per-panel activation side effects, the admin-controller handoff, `.admin-only` visibility, and the public `open()`/`close()` entry points — holding no panel state of its own and taking what it needs from `settings.js` as injected callbacks. `peek.js` owns the Appearance window-fade chrome and clearing it when the user leaves that panel, and `oauthReturn.js` owns the once-per-load return path from the Google OAuth redirect into the Integrations panel. Registry/DOM consistency is a tested contract; new panels must update both the registry metadata and actual DOM. `static/js/appConfig.js` shares one promise cache for settings and tool reads across frontend modules, consumes a login-page settings prefetch once, drops rejected promises for retry, and requires settings/tool writers to invalidate the matching cache; `/api/tools` writes invalidate both entries because disabled tools live in settings state.
+`static/js/settings.js` coordinates compatibility exports and delegates Agent, image-model, speech and writing-style panel initialization to their named leaf modules; while `static/js/settings/registry.js` is the canonical group/panel metadata inventory. `navigation.js` activates panels and lazy admin content, `search.js` implements the registry-backed finder while filtering admin-only entries, `lifecycle.js` owns modal open/close/Escape/drag/docking behavior, `sidebar.js` owns persisted collapse/resize state, and `dom.js` holds shared DOM helpers. `shell.js` owns the coordination above those primitives — per-panel activation side effects, the admin-controller handoff, `.admin-only` visibility, and the public `open()`/`close()` entry points — holding no panel state of its own and taking what it needs from `settings.js` as injected callbacks. `peek.js` owns the Appearance window-fade chrome and clearing it when the user leaves that panel, and `oauthReturn.js` owns the once-per-load return path from the Google OAuth redirect into the Integrations panel. Registry/DOM consistency is a tested contract; new panels must update both the registry metadata and actual DOM. `static/js/appConfig.js` shares one promise cache for settings and tool reads across frontend modules, consumes a login-page settings prefetch once, drops rejected promises for retry, and requires settings/tool writers to invalidate the matching cache; `/api/tools` writes invalidate both entries because disabled tools live in settings state.
 
 Settings panels cover provider/model/search/research/reminder/email/CalDAV/CardDAV/vault, accessibility/font/text-size, scoped tokens, and unified integrations. The hidden legacy fallback editor was removed; no current Settings panel exposes the new foreground fallback keys, so opt-in exists only through owner-scoped preferences/internal callers until a deliberate UI is added. Email OAuth connect preserves the selected SMTP security mode and returns to the Settings surface after callback. `static/js/admin.js` owns user/admin panels, model endpoints, builtin tool toggles, MCP forms, feature toggles, token/webhook panels, diagnostics, backup/import, and danger-zone wipes.
 
@@ -95,6 +95,14 @@ Runtime behavior:
 
 `scripts/odysseus-preset` is a local CLI for preset store maintenance and backup of `presets.json`.
 
+Custom presets now carry optional persona continuity notes, a `general`/`health` memory schema, `thinking_mode` (`on`, `off`, or provider default), and `show_persona_name`. `PresetManager.update_persona_memory()` updates matching active and saved personas; these remain shared preset data. The default custom output limit is 32,768 tokens.
+
+## Writing Style And Admin Controls
+
+`document_writing_style` and `email_writing_style` are separate global settings. `POST /api/auth/settings/document-style/extract` requires an admin unless auth is explicitly disabled. It reads a bounded document upload, extracts prose, and calls the owner-resolved Utility model (Default Chat if unavailable) with at most 30,000 sample characters. Its prompt treats the sample as untrusted data; the response is a proposed style string, and the temporary file is removed in `finally`. `static/js/settings/writingStyle.js` owns the UI. This is a model inference path rather than a deterministic style parser.
+
+`auto_compact_threshold_percent` defaults to 85 and settings writes clamp it to 50–95. `utility_reasoning_effort` is an allowed per-user override; utility fallback entries can specify their own effort. Admin `PUT /api/auth/users/{username}/password` delegates to `AuthManager.reset_user_password`, accepts only existing non-admin targets, revokes their sessions after reset, and validates minimum length and the 72-byte UTF-8 limit.
+
 ## Tools Settings
 
 `routes.model_routes` owns `/api/tools`, which writes `settings.json:disabled_tools` for global builtin tool toggles.
@@ -150,8 +158,8 @@ Vault tool paths duplicate some route behavior and can return vault item secrets
 
 ## Security And Provenance
 
-- Non-admin and unauthenticated settings reads are scrubbed.
-- Admin settings reads, admin edit forms, vault flows, backup files, and local CLI artifacts can contain secrets and must remain admin-only or locally protected.
+- With auth enabled, non-admin and unauthenticated settings reads are scrubbed; explicit disabled-auth operator reads return full settings.
+- Full settings responses, admin edit forms, vault flows, backup files, and local CLI artifacts can contain secrets and need their applicable access and storage protections.
 - Backup artifacts are sensitive because settings may include API keys, passwords, tokens, and endpoint credentials.
 - Diagnostics and logs should avoid adding secret-bearing values.
 - Admin wipe is global per kind and crosses owners.
@@ -171,14 +179,25 @@ Vault tool paths duplicate some route behavior and can return vault item secrets
 - Theme/preset frontend helpers tolerate malformed localStorage values.
 - CLI helpers are local maintenance surfaces and may bypass HTTP route policy.
 
+## App Configuration Gates And Cleanup
+
+`routes/auth_routes.py` uses `_require_admin_user()` for settings writes, feature writes, document-style extraction and integration management. Explicit `AUTH_ENABLED=false` admits the operator without a session identity, and settings GET returns unscrubbed values in that mode; auth-enabled callers need an admin for writes and get scrubbed reads unless admin. User-store administration still requires a real admin identity. `static/js/settings.js` reports shortcut save failure with a toast; settings writes use the existing response-status-checking API helper.
+
+`src/cleanup_service.py` previews and deletes using durable `ChatMessage` row counts rather than `Session.message_count`; it selects only the configured most-recent IDs for protection. The DELETE rechecks owner, archive state, age, importance and actual message threshold. Supported databases use DELETE RETURNING to attribute deleted rows and estimated space; legacy SQLite has a rowcount/survivor fallback with bounded estimate attribution. Cache eviction follows commit and includes observed externally removed candidates; estimates are not a measurement of reclaimed database bytes.
+
 ## Testing Notes
 
 Current targeted coverage includes settings store fallback/error paths, settings scrub, shared frontend config caching/invalidation/prefetch behavior, prefs no-clobber behavior, atomic preset store/migration/CLI/localStorage helpers, backup import cross-user dedup, backup CLI restore/list-race safety, cleanup owner scope, diagnostics admin-gate/source/service-health/log-tail checks, admin promote/demote, admin wipe gallery, font family derivation, theme helper behavior, vault password-not-in-argv checks, setup/auth regressions, reserved usernames, Google email OAuth route/helper behavior, and a token-budget `manage_settings` path.
 
+## Panel Save And Vault Identity Details
+
+`static/js/settings/api.js` centralizes settings POSTs, rejects non-OK/403 responses and invalidates the shared cache in finally even on failure. Older per-panel unchecked-response behavior is superseded by this final helper; individual UI completion is not model/provider acceptance. Image model selectors retain the final mixed eligibility filter rather than an image-only historical rule. Sidebar build information fetches public version/build/source-commit metadata, hides failed/unknown responses and abbreviates hexadecimal commits for display; arbitrary overrides are not byte attestation.
+
+Vault tool bindings require an explicit matching configuration owner and pin backend/config/session incarnations plus exact observed item identities. `routes/vault/vault_routes.py` checks configuration ownership on save and clears session/unlock time when adopting ownerless legacy state. Same-owner configuration edits retain saved session/unlock fields while invalidating bindings whose configuration incarnation changes. Configuration reads and login/unlock/lock/logout use common `require_admin()` without that owner-binding check. Observed catalog names or selectors cannot renew a revoked tool backend; search observations can update selected entries without proving every remote account/session is fresh.
+
 ## Current Gaps
 
-- Add route tests for `/api/auth/settings`: anonymous/non-admin scrubbed reads, admin full reads, non-admin POST rejection, and unknown-key ignore behavior.
-- Add route tests for `/api/auth/features` admin writes.
+- Settings/features route tests cover disabled-auth operation, auth-enabled read scrubbing, admin/non-admin writes, numeric validation and ignoring unknown keys; real auth-middleware integration and broader store-failure combinations still need coverage.
 - Add `/api/tools` and `manage_settings` tests for secret write refusal, enum/integer coercion failures, structured-setting refusal, reset/default behavior, endpoint/model resolution, and tool enable/disable aliases.
 - Add backup tests for secret-bearing export policy, owner-scoped exported sections, invalid import handling, skills dedup, settings/features merge, and admin gates.
 - Add diagnostics tests for broader error redaction and sensitive output limits.
@@ -187,4 +206,4 @@ Current targeted coverage includes settings store fallback/error paths, settings
 - Add broader frontend behavior coverage for Settings/Admin panel save/load flows, vault password clearing, diagnostics buttons, cleanup/wipe confirmations, custom font/theme wiring, and tab state; registry/navigation/finder/lifecycle contracts now have focused source/JS tests, and the real-ESM coordinator smoke in `tests/helpers/test_settings_shell_coordinator.mjs` additionally covers the shell's admin-only visibility, admin-controller handoff and Peek fade/clear behavior.
 - Decide whether `user_templates` and `group_presets` should remain shared despite user-facing names.
 - Decide whether backup/import should preserve explicit owner fields or force imported owner ownership.
-- Continue decomposing the still-large `static/js/settings.js` (5,583 lines) and `static/js/admin.js` (4,122 lines) without duplicating registry ownership. The shell and navigation concerns now live in `static/js/settings/`; what remains in `settings.js` is panel code, and `initUnifiedIntegrations()` alone is ~2,140 lines of it. `admin.js` has no extracted shell of its own yet.
+- Settings panel code now has additional domain modules, but `static/js/settings.js` and `static/js/admin.js` remain substantial coordinators; future extraction must preserve registry and lifecycle ownership.
diff --git a/specs/shell-mcp.md b/specs/shell-mcp.md
index cd0087891..a137f16ef 100644
--- a/specs/shell-mcp.md
+++ b/specs/shell-mcp.md
@@ -1,6 +1,6 @@
 # Shell And MCP
 
-Last updated: dev@2e2bb52 | 2026-08-16
+Last updated: dev@c74f475 | 2026-10-15
 
 ## Scope
 
@@ -9,6 +9,8 @@ This spec covers shell and MCP behavior in:
 - shell routes in `routes/shell_routes.py`;
 - the standalone shell helper in `services/shell/service.py`;
 - agent shell/background execution in `src/tool_execution.py`, `src/agent_tools/subprocess_tools.py`, `src/bg_jobs.py`, and `src/bg_monitor.py`;
+- `src/containment.py`, `src/containment_worker.py`, `src/process_ownership.py`, `src/process_lifecycle.py`, and `src/process_reaper.py`;
+- `src/browser_identity.py`, `src/browser_lifecycle.py`, `src/browser_observation.py`, and `src/agent_runtime/process_resources.py`;
 - app wiring and startup/shutdown in `app.py`;
 - MCP configuration routes in canonical `routes/mcp/mcp_routes.py`, with `routes/mcp_routes.py` as a compatibility shim;
 - MCP runtime state in `src/mcp_manager.py`;
@@ -49,11 +51,11 @@ Those endpoints probe local or SSH-remote packages, prepend user install bins fo
 
 ## Agent Shell And Background Jobs
 
-`src.tool_execution` owns agent-side `bash` execution and the `#!bg` marker. A `bash` block whose first line is `#!bg` starts a detached background job instead of holding the chat stream open. On Windows, request-scoped workspace shell execution prefers Git Bash when available so POSIX-style agent commands and path confinement use the intended shell instead of `cmd.exe` parsing.
+`src.tool_execution` owns policy/dispatch for agent-side `bash` execution and the `#!bg` marker; `src.agent_tools.subprocess_tools` owns native shell/Python/host-bridge handlers. A `bash` block whose first line is `#!bg` starts a detached background job instead of holding the chat stream open. Native enforcing execution is unavailable on unsupported platforms, including Windows; compatibility/admin shell selection is a separate path and does not establish native containment.
 
 `src.bg_jobs` owns disk-backed job state under `data/bg_jobs.json` and `data/bg_jobs/*`. It stores wrapper scripts, logs, exit-code files, timestamps, status, and capped result text.
 
-`src.bg_monitor` owns polling and auto-continuation. When a job finishes, it injects the job result into the session, drains the agent stream, persists only the assistant continuation plus `bg_result` metadata, and marks the job followed up.
+`src.bg_monitor` owns polling and auto-continuation. A completed job follows up only after exact owner/request/thread/generation linkage is checked, including revalidation after draining the continuation stream. Busy sessions retry; missing/terminal authority does not renew itself. Only after assistant persistence is follow-up marked delivered; suppression of an unfollowable result is distinct from delivery.
 
 Runtime behavior:
 
@@ -75,10 +77,7 @@ Runtime behavior:
 
 `src.mcp_manager.McpManager` owns live connection state, stdio/SSE/Streamable HTTP transports, sessions, tool schemas, qualified names, and tool calls. HTTP route operations update both database state and live manager state where applicable. Streamable HTTP connects in a background task, can report `connecting` or `needs_auth`, and surfaces an authorization URL when the OAuth client flow redirects. Enabled configured servers connect concurrently at startup; each server has its own 20-second connection timeout and records `timeout` state without delaying siblings. The startup task has no second outer timeout.
 
-Stdio and SSE connection setup registers the session, exit stack, tool list,
-and status as one completed unit. If initialization or tool discovery fails
-before registration, the partial `AsyncExitStack` is closed so transports do
-not leak into later reconnect attempts.
+Stdio and SSE connection setup registers the session, exit stack, tool list, and status as one completed unit. If initialization or tool discovery fails before registration, the partial `AsyncExitStack` is closed so transports do not leak into later reconnect attempts.
 
 `src.agent_tools.admin_tools.do_manage_mcp()` is the agent/admin tool path for MCP config and is re-exported lazily through `src.tool_implementations` for compatibility. It is narrower than the HTTP routes: add is stdio-only, command values are checked against an allowlist/denylist before persistence, and enable/disable primarily flips DB config. `scripts/odysseus-mcp` is config-only; it reads and mutates database rows, redacts env values by default, and does not report live manager connection state.
 
@@ -93,20 +92,11 @@ Python stdio built-ins:
 - RAG;
 - email.
 
-The optional browser built-in uses `npx -y @playwright/mcp@latest --headless --caps vision`. It is cache-gated by checking npm's `_npx` cache for the requested package and falling back to `npx --no-install`; uncached/missing browser MCP is logged with install guidance and skipped rather than blocking startup or downloading packages at boot. Python built-ins are omitted from OpenAI function schemas because native/code-block paths already describe those capabilities; the browser built-in is exposed through MCP function schemas when connected.
+The optional browser built-in uses `npx -y @playwright/mcp@latest --headless --caps vision`. It is cache-gated by checking npm's `_npx` cache for the requested package and falling back to `npx --no-install`; uncached/missing browser MCP is logged with install guidance and skipped rather than blocking startup or downloading packages at boot. Image, memory and RAG Python built-ins normally defer to native/code-block descriptions; email remains a qualified MCP schema/prompt exception. Connected browser schemas do not authorize page execution.
 
-Built-in Python servers prepend the app root to inherited `PYTHONPATH` rather
-than replacing the environment, so container/dev site-packages remain visible
-on initial connect and automatic reconnect. They can be reconnected once on
-tool-call failure. User-configured MCP servers return the call failure instead
-of automatic reconnect.
+Built-in Python servers prepend the app root to inherited `PYTHONPATH` rather than replacing the environment, so container/dev site-packages remain visible on initial connect and automatic reconnect. `McpManager.call_tool()` can reconnect a built-in once after an exception only when the call has no bound backend identity. Bound calls return the failure so a fresh connection cannot silently replace the sealed backend incarnation. User-configured MCP servers return the call failure instead of automatic reconnect. Browser calls have a bounded timeout; timed-out calls are abandoned without retry because page state is unknown.
 
-The built-in email MCP server is owner-aware when an owner is supplied by the
-caller or configured through `ODYSSEUS_MCP_EMAIL_OWNER` /
-`ODYSSEUS_EMAIL_OWNER`; if owner-scoped email accounts exist and no owner is
-available, email MCP fails closed instead of exposing global accounts. Other
-built-in servers remain process-global/admin trust-boundary tools unless their
-own subsystem spec says otherwise.
+The built-in email MCP server is owner-aware when an owner is supplied by the caller or configured through `ODYSSEUS_MCP_EMAIL_OWNER` / `ODYSSEUS_EMAIL_OWNER`; if owner-scoped email accounts exist and no owner is available, email MCP fails closed instead of exposing global accounts. Other built-in servers remain process-global/admin trust-boundary tools unless their own subsystem spec says otherwise.
 
 ## Agent MCP Exposure
 
@@ -128,9 +118,7 @@ After model-visible external/workspace context, arbitrary MCP actions classify f
 ## Degraded And Platform Behavior
 
 - `app.py` starts the background monitor and MCP startup tasks asynchronously; MCP startup is non-critical to app readiness.
-- Configured MCP servers start concurrently with a per-server 20-second bound;
-  timeout state is stored per server and partial connection resources are
-  closed before returning.
+- Configured MCP servers start concurrently with a per-server 20-second bound; timeout state is stored per server and partial connection resources are closed before returning.
 - Missing Python `mcp` dependency degrades attempted MCP connections to error status.
 - Missing or uncached browser NPX package is optional and log-only during built-in startup; startup should not perform an implicit package download.
 - Windows does not support POSIX PTY/tmux paths; streaming falls back to pipes or detached logfile behavior.
@@ -141,16 +129,13 @@ After model-visible external/workspace context, arbitrary MCP actions classify f
 ## Security And Provenance
 
 - Admin shell is intentional host command execution; do not expose shell routes or shell tools to regular users.
-- `_require_admin()` gates shell routes and MCP config routes. The internal-tool loopback can be admin-equivalent only after auth middleware validates the internal token and loopback client.
+- `routes.shell_routes._require_admin()` gates shell and selected Cookbook native controls, rejecting internal-tool identity/header administration. Auth-disabled operator access requires direct loopback without forwarding or disallowed browser-origin metadata; an Authorization header alone is not excluded by this transport helper. Auth-enabled administration requires a present auth manager and human admin. MCP configuration instead uses common `core.middleware.require_admin()`, which admits a matching internal token/sentinel or explicit auth-disabled mode; it does not inherit the shell gate's transport/resource rules.
 - `_reject_cross_site()` currently applies to `/api/cookbook/packages`; `/api/shell/exec`, `/api/shell/stream`, package install, rebuild, and MCP write/OAuth routes do not call it directly.
 - Shell helper paths use argv-based SSH, reject option-like hosts, validate SSH ports through shared helpers, restrict remote venv characters, and allowlist package installs.
 - Non-admin/public tool policy blocks `bash`, `python`, file tools, `manage_mcp`, and all `mcp__*` tools.
 - MCP stdio server registration is arbitrary host process execution and is admin-only.
 - MCP OAuth key/token file paths supplied through routes are confined under `data/mcp_oauth`; generic Streamable HTTP OAuth token state is encrypted in the database.
-- Built-in MCP servers are local/admin trust-boundary tools and are not
-  automatically equivalent to owner-scoped HTTP route behavior. Email MCP is
-  the current exception with explicit owner filtering; other built-ins need
-  their own owner policy before being treated as scoped surfaces.
+- Built-in MCP servers are local/admin trust-boundary tools and are not automatically equivalent to owner-scoped HTTP route behavior. Email MCP is the current exception with explicit owner filtering; other built-ins need their own owner policy before being treated as scoped surfaces.
 - MCP output is external-untrusted tool output and arms the high-impact continuation gate when model-visible. Current MCP text output is still not centrally capped before model re-entry.
 
 ## Testing Notes
@@ -159,15 +144,54 @@ Current targeted coverage includes Windows PTY import degradation, PTY unsupport
 
 The shell/MCP audit ran the targeted venv subset with 78 passing tests and one warning.
 
+## Contained Execution And Native Browser Identity
+
+Model-reachable native shell/Python execution uses `src.containment.agent_spec()` with enforcing filesystem, process-tree, and wall-clock requirements. Missing required mechanisms return containment-unavailable results before code runs; optional network/memory/process-count dimensions are recorded separately and must not be assumed enforced. Bubblewrap provides the Linux filesystem/namespace path when available. Direct admin HTTP shell routes remain a distinct operator surface. Host/client bridges declare external execution rather than claiming local sandbox enforcement.
+
+Process identity is PID plus start token, not PID alone. `src.process_ownership` probes identities; `src.process_lifecycle` protects the server process group and reports death only after observation. Durable callers require positive PID/start-token identity; the generic tree helper also retains a compatibility mode without that requirement, so this is not a universal signaling guarantee. Background jobs persist launch generation, containment, and process identity so stop/restart paths can refuse stale targets.
+
+`private_browser` currently admits only `session_info`. All page navigation, snapshots, screenshots, close/batch/recovery actions and raw global Playwright browser operations are denied unconditionally at the common boundary before binding or dispatch. `src.browser_identity` and lifecycle/observation modules retain owner/thread/session/incarnation machinery and metadata-only prompt support, but these do not enable page execution. The pinned agent-browser 0.35 Linux x64/arm64 discovery, clean environment and read-only bounded CDP observations do not amount to usable browser acceptance; metadata lookup does not adopt or create an unrelated launch.
+
+`McpManager` additionally registers backend incarnations and exposes server-owned resource observations for admitted calls. Built-in connection owner tasks keep AnyIO transport scopes alive until disconnect; changed connections invalidate sealed backend identities. Existing transport configuration and schema discovery remain manager-owned.
+
+## Launch, Cleanup And Bridge Boundaries
+
+Linux native containment requires a functional bounded bubblewrap mount/PID probe, not merely an installed executable. The supervisor/worker ready acknowledgement holds user code until containment publication, durable job state, sidecar and exact launch receipt are verified. Filesystem, process-tree and wall-clock dimensions are required; missing mechanisms fail before code execution. Captured init/leader PID plus start tokens and optional pidfd support cleanup; both deaths must be observed. Unknown identity remains unverified, foreign identity is never a signal target, and no later PID lookup can manufacture a launch receipt. Startup timeout includes bootstrap/stdin; cancellation shields spawn cleanup. Optional network/memory/process-count dimensions are not implied enforcement.
+
+Native background work uses generation-bound launches rather than agent tmux. Operator HTTP tmux remains a compatibility surface. PTY cleanup freezes known descendants before signaling and protects the server group; missing launch PID/token does not trigger PID/group recapture. Unverifiable containment grants remain active; detached jobs with foreign/unverifiable ownership can retire failed without signalling, retaining follow-up history rather than declaring successful cleanup. Publication retirement checks exact launch identity and its caller-specific lifetime rule; foreground startup recovery can also remove publications whose receipt is genuinely absent. Unreadable or malformed nonempty startup state is retained. Dead launch retention/pruning and delivered result retention are bounded lifecycle policies, not proof of task success. Store transaction locks serialize background read/modify/write, not every application store.
+
+`core.platform_compat.service_home()` uses `Path.home()` on Windows and lazy POSIX real-UID passwd lookup. Successful POSIX lookup keeps a child HOME override from choosing the service cache; the missing-entry/OS-error fallback uses `Path.home()` and can honor that override. Default native child environments allow selected keys with fixed HOME/terminal values; an explicitly supplied subprocess environment is not value-scrubbed. This is separate from inherited built-in MCP environments.
+
+Host shell/file bridges declare external execution and normalize the admitted URL authority while replacing the operation path and dropping query/fragment components. Every bridge run/read/write/patch/poll/cancel client uses `trust_env=False`. HTTP admission accepts the explicit loopback/host-docker/LAN/CGNAT or actual Docker-gateway cases, not every private network or arbitrary TLS host; this bridge rule does not apply to every other HTTP client. SSH/external raw shell calls cannot borrow native launch/stop authority. Cookbook and scheduled native launches carry sealed backend capabilities; missing capabilities fail closed.
+
+MCP add-server argument text must decode to a JSON array before mutation; an empty value means an empty array, without an element-type guarantee. Bound backend calls cannot silently reconnect into a different incarnation. Browser timeout abandonment remains no-retry: EOF or partial transport state is not exactly-once execution proof. Email MCP owner and session ContextVars are reset in finally; its owner-filtered listing/index behavior is documented with email ownership.
+
+## Compatibility Process Evidence
+
+Python execution confinement validates the read-only interpreter-prefix mounts it relies on instead of treating an arbitrary interpreter path as admitted. Process inspection helpers retain platform-specific uncertainty: unavailable procfs inspection is not proof that a process died, and generic compatibility liveness helpers are not substitutes for the stored exact launch identities required by background execution cleanup.
+
+## Result Publication And Continuation
+
+Native execution reports containment, teardown and capture truncation independently. Verified timeout uses exit 124; unverified process death is teardown failure rather than successful cleanup, and Python child-runtime failure cannot hide behind exit zero. Detached supervisors publish result JSON before exit metadata; setup failure releases an unstarted grant and falls back to stderr when its failure log cannot be written. Successful exit does not imply complete captured output.
+
+PTY teardown freezes its leader identity and verified session group. FOREIGN identity is not signalled, absent/unverifiable identity does not prove death, and a gone leader can permit cleanup of its recorded surviving group without rediscovering a replacement PID. Timeout SSE reports surviving processes; quiet disconnect/error paths log failed cleanup. Generic compatibility tree helpers still require durable callers to request identity verification.
+
+Background historical lookup does not reap unrelated cached handles: selected running records need their exact frozen PID/start token. Continuation validates immutable job, owner, request, thread and authority linkage before and after awaits, settles the linked launch effect from lifecycle facts rather than output, and persists delivery before marking followed-up. Missing sessions or invalid linkage become terminal_unfollowable; busy sessions/managers retry, and a changed snapshot prevents stale suppression. This is not an atomic lock over the entire chat session.
+
+Foreground startup retirement retains unreadable/malformed stores. With an existing receipt it requires exact linkage and an observed GONE/FOREIGN manager; live or unverifiable managers retain publication even after child teardown. A genuinely missing receipt also permits retirement of a valid foreground publication because attachment cannot resume. Ordinary producer-finally retirement uses verified teardown. One-use launch reservations are shared across approval copies, so deleting publication does not renew dispatch. Retirement is bookkeeping, not authority to signal or proof of process-tree death. Protected-root overlays are refused after normalization; an external bridge response heuristic does not attest local effects.
+
+## Image MCP Ownership
+
+`mcp_servers/image_gen_server.py` reads the hidden trusted-dispatch `_odysseus_owner`, trims blank values to null, stamps `GalleryImage.owner`, and registers a fresh image after gallery commit when an owner exists. There is no image-owner environment fallback. `src/tool_execution.py` removes caller-reserved attribution fields before injecting server owner context for legacy and qualified image calls; direct fallbacks retain the trusted owner. Generated-file access uses the independent fail-closed policy in `gallery-editor-media.md`.
+
 ## Current Gaps
 
 - Decide whether `/api/shell/exec`, `/api/shell/stream`, package install, rebuild, and MCP config/OAuth writes should call `_reject_cross_site()` directly.
-- Add route-level shell exec/stream tests for admin gate, cross-site behavior, empty command, plain exec, timeout, PTY, tmux, and Windows detached fallback.
-- Add background job tests for launch isolation, output truncation, done/failed/timeout/died states, pending follow-ups, and result text.
+- Shell route/service and process-lifecycle tests cover selected execution paths; PTY/tmux/Windows behavior remains platform-dependent.
+- Background identity, containment, and follow-up paths have focused tests; restart/platform integration still needs separate validation.
 - Add route-level MCP CRUD/OAuth/disabled-tool tests with a fake manager and temp database.
 - Add hard per-server disabled MCP execution checks or document disabled tools as prompt/schema filtering only.
-- Make MCP tool indexing sensitive to disabled-map changes, not only manager generation.
-- Fix stale outer prompt/cache behavior when MCP disabled tools change.
+- MCP prompt descriptions cache against both disabled maps and manager generation; downstream index refresh still needs coordinated invalidation.
 - Add one central truncation layer for MCP result text and images before model re-entry; untrusted-result marking and exact-action continuation approval are now implemented.
 - Decide whether `McpServer.env` and OAuth key files need masking, encryption, and chmod beyond admin-only access.
 - Decide whether built-in MCP servers should become owner-aware or remain documented as admin/global compatibility surfaces.
diff --git a/specs/speech.md b/specs/speech.md
index 9dab0703a..d5cd55024 100644
--- a/specs/speech.md
+++ b/specs/speech.md
@@ -1,6 +1,6 @@
 # Speech
 
-Last updated: dev@e71f8ce | 2026-08-25
+Last updated: dev@86b886c | 2026-10-15
 
 ## Scope
 
@@ -16,7 +16,7 @@ This spec covers speech behavior in:
 - settings routes in `routes/auth_routes.py`;
 - model endpoint cleanup in `routes/model_routes.py`;
 - settings/tool aliases in `src/tool_implementations.py`;
-- frontend modules `static/js/voiceRecorder.js`, `static/js/tts-ai.js`, `static/app.js`, `static/js/chat.js`, `static/js/slashCommands.js`, `static/js/keyboard-shortcuts.js`, `static/js/settings.js`, and `static/index.html`;
+- frontend modules `static/js/voiceRecorder.js`, `static/js/tts-ai.js`, `static/app.js`, `static/js/chat.js`, `static/js/slashCommands.js`, `static/js/keyboard-shortcuts.js`, `static/js/settings.js`, `static/js/settings/speech.js`, and `static/index.html`;
 - optional dependency declarations in `requirements-optional.txt`;
 - runtime cache path `data/tts_cache/`;
 - tests covering speech service toggles, TTS speed/cache, STT temp cleanup, upload limits, settings scrubbing, and model endpoint cleanup.
@@ -80,7 +80,7 @@ Route behavior:
 
 Speech providers are global settings under `data/settings.json`, with defaults in `src/settings.py`. Settings reads are scrubbed for non-admin callers, writes are admin-only, and `manage_settings` can change non-secret speech settings through aliases.
 
-Visible UI state is not complete: backend and JS speech settings exist, the TTS settings card is currently hidden, and the STT settings JS exits when its removed DOM nodes are absent.
+`static/js/settings/speech.js` owns TTS/STT settings initialization and provider selectors; the Settings coordinator imports those initializers. Visible UI state is not complete: backend and JS speech settings exist, the TTS settings card is currently hidden, and the STT settings JS exits when its removed DOM nodes are absent.
 
 `routes.model_routes` clears `tts_provider` and `stt_provider` references when a referenced model endpoint is deleted.
 
diff --git a/specs/testing-devops.md b/specs/testing-devops.md
index 46d0fed18..9f0a13d78 100644
--- a/specs/testing-devops.md
+++ b/specs/testing-devops.md
@@ -1,6 +1,6 @@
 # Testing And Devops
 
-Last updated: dev@e71f8ce | 2026-08-25
+Last updated: dev@c74f475 | 2026-10-15
 
 ## Scope
 
@@ -15,7 +15,7 @@ This spec covers development and validation surfaces in:
 - `scripts/`, `scripts/odysseus`, `scripts/_lib/cli.py`, `scripts/_completion/*`, `scripts/pr_blocker_audit.py`, and `scripts/odysseus-*`;
 - GPU helper scripts `scripts/check-docker-gpu.sh` and `scripts/check-docker-amd-gpu.sh`;
 - `.github/` templates, workflows, and description-check scripts;
-- contributor workflow docs in `CONTRIBUTING.md` and `docs/pr-blocker-audit.md`;
+- contributor workflow docs in `CONTRIBUTING.md` and `website/pr-blocker-audit.md`;
 - platform launchers `launch-windows.ps1`, `launcher.py`, `Odysseus.spec`, `build-windows-portable.ps1`, `start-macos.sh`, `build-macos-app.sh`, and `update_windows.bat`;
 - setup/service files such as `setup.py`, `install-service.sh`, and `odysseus-ui.service`.
 
@@ -37,7 +37,7 @@ Activated-venv `python -m pytest <test path>` is equivalent. System/global `pyte
 
 `tests/conftest.py` inserts the repo root on `sys.path` and conditionally stubs missing heavy/runtime dependencies such as SQLAlchemy, FastAPI, Starlette, Pydantic, httpx, bcrypt, and pyotp. Tests that need real dependencies use explicit imports/skips. Tests that stub `sys.modules`, environment variables, globals, or parent packages must restore them with `monkeypatch` or an equivalent cleanup pattern.
 
-The suite currently contains roughly 728 `test_*.py` files. Treat that count as a moving source metric, not a target; focused regression tests are still preferred for narrow changes.
+The suite currently contains a growing set of `test_*.py` files. Treat that count as a moving source metric, not a target; focused regression tests are still preferred for narrow changes.
 
 Focused regression tests are preferred for narrow behavior changes. Broaden tests when touching shared contracts such as auth, owner filtering, OAuth/token custody, tool output, context building, provider calls, persistence, frontend rendering, or route/API shapes.
 
@@ -45,7 +45,7 @@ Focused regression tests are preferred for narrow behavior changes. Broaden test
 
 ## JS And UI Tests
 
-The repo has no frontend build pipeline, npm test script, or type-check script. `package.json` owns Node dependencies for Bombadil and the Anthropic SDK, and `package-lock.json` owns npm integrity/version state.
+`frontend/modules.json` maps canonical `frontend/src/` modules to committed outputs under `static/`. `scripts/build_frontend.py --check` verifies output freshness/publication attributes; `scripts/check_frontend.mjs` checks architecture/import boundaries. Root `package.json` owns Bombadil, Playwright and Acorn plus photo-editor browser-test scripts; the lockfile owns npm integrity/version state. This is an incremental source migration rather than a bundler-wide conversion.
 
 Current frontend/JS validation includes:
 
@@ -57,13 +57,14 @@ Use `node --check static/js/<changed-file>.js` for syntax checks on changed JS f
 
 ## Dependencies
 
-`requirements.txt` owns core runtime and test dependencies, including pytest, pytest-asyncio, MCP, Chroma HTTP client, fastembed, qrcode, and core parsing/search/calendar dependencies.
+`requirements.txt` owns core runtime and test dependencies, including `psycopg2-binary`, pytest, pytest-asyncio, MCP, Chroma HTTP client, fastembed, qrcode, and core parsing/search/calendar dependencies.
 
 `requirements-optional.txt` owns optional feature dependencies:
 
 - `faster-whisper` for local STT;
 - `kokoro==0.9.4` and `soundfile` for local TTS on Python 3.11-3.12 only; Kokoro is deliberately skipped on Python 3.13+ because its package metadata excludes those runtimes, and a CUDA-capable torch/GPU is still required at runtime;
 - `ddgs` for DDG library support, while provider code can fall back to HTML scraping;
+- `rapidocr==3.9.2` and `onnxruntime>=1.20,<2` for local OCR, and `psd-tools` for PSD previews/layer inspection;
 - `PyMuPDF` for PDF forms/rendering with AGPL implications for a network-served app;
 - `markitdown[docx,pptx,xlsx,xls]` for Office/EPUB extraction, pinned to a release older than 30 days.
 
@@ -96,6 +97,8 @@ Compose variants forward `ODYSSEUS_TTS_CACHE_MAX_BYTES`, defaulting in the servi
 
 Docker does not mount the host Docker socket by default. Mounting it would grant powerful host access and is outside the default trust boundary. `docker/host-docker.yml` is the explicit opt-in overlay and sets `ODYSSEUS_ENABLE_HOST_DOCKER=true`; tests guard that the default and GPU compose files do not enable host Docker accidentally.
 
+Compose selects `ODYSSEUS_IMAGE` (default GHCR `latest`) alongside a local build and publishes container port 7000 on default host port 7011. SearXNG is tag-and-digest pinned. `docker/host-workspace.yml` explicitly mounts a selected host workspace; `docker/host-network.yml` opts into Linux host networking, resets published ports, and starts uvicorn on the configured host bind/port. These overlays expand access beyond default deployment. The image includes Chromium, Noto CJK fonts, network inspection utilities, pinned `agent-browser@0.35.0`, and redistribution notices. Entrypoint ownership repair touches HuggingFace cache roots without traversing existing model files.
+
 ## GPU And Platform
 
 Base `docker-compose.yml` plus `docker/gpu.nvidia.yml` or `docker/gpu.amd.yml` are the GPU source of truth. Top-level `docker-compose.gpu-nvidia.yml` and `docker-compose.gpu-amd.yml` are standalone mirrors for stack-management UIs that accept one compose file. `tests/test_gpu_compose_standalone.py` guards drift between those forms.
@@ -145,7 +148,7 @@ When route/API behavior changes, check whether a matching CLI script depends on
 
 ## GitHub Metadata
 
-`.github/` owns issue/PR templates, a copyable PR review template, description-check workflows, security/governance workflows, Docker publishing, and CI. Current CI runs on pushes to `main` and `dev` plus pull requests, compiles Python with `python -m compileall`, syntax-checks first-party JS with `node --check`, emits focused-test guidance for changed code, and runs the configured `python -m pytest -q` scope as an authoritative failing job; pytest still skips documentation-only changes.
+`.github/` owns issue/PR templates, a copyable PR review template, description-check workflows, security/governance workflows, Docker publishing, and CI. Current CI runs on pushes to `main` and `dev` plus pull requests, compiles Python, checks committed frontend outputs, validates frontend architecture/syntax, emits report-only focused-test guidance, and partitions pytest across four file-based shards through `tests/_shards.py`. Pytest setup requires functional bubblewrap PID/mount containment, FFmpeg and Chromium. Its prose-only bypass excludes `website/` and `assets/branding/`; those published-file contracts remain tested.
 
 `CONTRIBUTING.md` owns the branch model: PRs target `dev`; `main` is the curated user-running branch fast-forwarded from stable `dev` commits. Contributors who accidentally target `main` should retarget the PR base without rebasing.
 
@@ -169,9 +172,9 @@ Issue description checks:
 - update a bot comment and swap status labels;
 - remove the workflow-owned review label when an issue closes so closed issues do not retain stale readiness state.
 
-Security metadata includes container Trivy SARIF upload, Dockerfile lint, dependency review, secret scan, workflow security linting, GitHub default-setup CodeQL, Dependabot metadata, and hardened PR/issue description checks that avoid unsafe head-branch execution. `docs/security-ci.md` documents CodeQL as a dynamic GitHub default-setup workflow; the repo should not add a checked-in CodeQL workflow while that default setup is active.
+Security metadata includes container Trivy SARIF upload, Dockerfile lint, dependency review, secret scan, workflow security linting, GitHub default-setup CodeQL, Dependabot metadata, and hardened PR/issue description checks that avoid unsafe head-branch execution. `website/security-ci.md` documents CodeQL as a dynamic GitHub default-setup workflow; the repo should not add a checked-in CodeQL workflow while that default setup is active.
 
-`scripts/pr_blocker_audit.py` is a read-only maintainer/contributor triage helper documented in `docs/pr-blocker-audit.md`. It can fetch or ingest open PR metadata, estimate hot files and possible duplicate groups, and emit Markdown, JSON, or terminal reports. Its duplicate/blocker output is advisory, not an authority that a PR is blocked.
+`scripts/pr_blocker_audit.py` is a read-only maintainer/contributor triage helper documented in `website/pr-blocker-audit.md`. It can fetch or ingest open PR metadata, estimate hot files and possible duplicate groups, and emit Markdown, JSON, or terminal reports. Its duplicate/blocker output is advisory, not an authority that a PR is blocked.
 
 Before posting PRs or issues, compare drafts against current templates on latest `main` or current `dev` as appropriate for the target. Keep unpublished drafts and raw related-search exports out of tracked implementation specs unless intentionally promoted.
 
@@ -201,18 +204,50 @@ Run the app for user-facing or integration changes. Unit tests and syntax checks
 
 `tests/helpers/` owns reusable test scaffolding. `cli_loader.load_script()` loads CLI files without running their `main()` entrypoint. `db_stubs` owns small DB stand-ins for tests that should not import a real app database. `import_state` owns conservative `sys.modules` and parent-module-attribute restoration for tests that install fake modules or import route files under alternate stubs. `tests/README.md` documents helper conventions and review expectations.
 
+`tests/test_runtime_behavior_regressions.py` drives the agent loop with a fake streaming model to check offered tools, clarification/plan policy, explicit native request scope and mocked browser cleanup. Negative-web cases require a model call, an answer delta and terminal completion while withholding web tools. These deterministic runtime assertions do not establish live-model or browser acceptance.
+
+## Harness And Publication Boundaries
+
+`tests/conftest.py` defaults the static origin to an ephemeral loopback port and publishes/restores `ODYSSEUS_TEST_STATIC_ORIGIN`; an explicit validated port can still collide. Threaded serving avoids idle-connection head-of-line blocking. Per-process random private data/mail/embedding/cache/temp paths and optional xdist basetemp avoid sharing runtime state; explicit basetemp wins. Disposable database helpers use isolated factories/cleanup rather than ORM reloads. A teardown guard removes and fails newly leaked bare `src`/`core` modules, using exact ModuleType/falsey-file detection; preexisting modules and mocks are outside that guard. The Unix socket path length fixture is character-bounded, not a universal byte-length proof.
+
+`tests/_shards.py` partitions collected files deterministically by weights and lexical tie-breaks across four CI shards; deselection occurs after collection/import. Optional parallel smoke and serial-only guards do not make every test xdist-safe. Pytest CI uses Node 20, locked npm dependencies, cached Chromium downloads keyed by OS/lockfile, system browser libraries, FFmpeg and a functional unprivileged bubblewrap probe. It uses setup-uv cache without automatic prune and pytest skip reasons/duration reporting. These workflow provisions are not evidence that every browser, media or containment test passed on another host.
+
+`tests/helpers/document_source.py` provides ordered implementation membership and lexical construct extraction; email JS helper enumeration is immediate rather than recursive. Stylesheet helpers follow shell order and cache identities; keyframe/hygiene/import/procfs guards are bounded textual or AST checks, not full semantic control-flow/browser proofs. The computed-style fixture, browser artifacts and reported historical suite counts remain specific to their recorded environments.
+
+`scripts/odysseus-dev` owns separate development data/database/browser-cache paths, path-hashed port blocks, service/reserved-port refusal, readiness login and fingerprinted stop state. Hash collisions, released fallback-port races and environment-derived defaults prevent a universal isolation guarantee. `scripts/odysseus-smoke` exercises deterministic model/email HTTP scenarios and reports declared gaps; it is not full browser/product acceptance and cleanup/reused-instance state remains scoped. `scripts/ref_parity_audit.py` compares heuristic added-line probes and exact filtered tree-path sets, not behavioral equivalence; mutable refs can be reread during a run. `scripts/generate_env_reference.py` checks generated reference bytes and handwritten notes from bounded AST/helper/regex discovery, not exhaustive runtime environment use; malformed Python can yield no detected rows and source citations are file-based.
+
+`.github/workflows/deploy-pages.yml` builds `website/` into `_site`; preview encoding targets website assets and branding lives under `assets/branding/`. Docker excludes both website and branding source roots. The macOS app script uses moved branding with best-effort `sips` icon generation; no native build or license clearance follows from source inspection. Docker publishing emits version/short-SHA trace tags and inspects those plus latest, without registry-enforced immutability. Trivy jobs use the Docker Buildx driver and free local build cache before vulnerability database work; this is CI lifecycle behavior, not an instruction to prune controller state.
+
+Description checks retain the public numeric Linked Issue requirement; an exact maintainer-preview repository allows a beginning `N/A` value while still requiring the section after comment stripping. This checks syntax, not issue existence or branch rulesets. Dependency-review blocking applies to canonical repository pull requests; fork pip-audit advice is a separate policy. None of these workflows grants publication authority.
+
+Maintained frontend publication requires repository-owned LF text attributes on both mapped paths, checked through isolated Git attribute evaluation. It validates the complete plan before writes, copies bytes without rewriting imports or bundling and never deletes unowned static assets; publication is not a transactional live deployment. Acorn checks manifest-selected dependency direction, canonical URL identity, used legacy exceptions, exact precache arrays and cycles, not all legacy browser behavior.
+
+## Chroma Mount And Focused Safety Regressions
+
+All three Compose variants mount `chromadb-data:/data`, matching the current image configuration rather than pre-1.0 `/chroma/chroma`. Existing writable-layer data needs rescue before container recreation; `docs/chromadb-volume-migration.md` describes writer shutdown/cold backup, preserved backup image, SQLite/HNSW checks, empty-volume seeding, isolated staging and count comparison. `website/backup-restore.md` links that procedure. Static YAML/document tests cover declared paths and safety markers; they do not execute or certify migration against a live Chroma image.
+
+Focused regressions now cover invalid history truncation preserving messages, failed bulk Trash moves/selective expunge, disabled-auth app configuration gates, durable cleanup message counts/delete-boundary races and generated-image ownership/cache/attribution. Test presence and historical counts do not establish a new successful run; runtime validation evidence is separate.
+
+## Notes Extraction Validation Surface
+
+Notes tests include domain/characterization/application/infrastructure/reminder/workflow contracts, recurrence differential cases across timezones, raw-state cloneability, draft timing and selected-context acceptance. Browser fixtures exercise canonical/facade identity, desktop/mobile/tablet interactions, teardown and first-time offline graph loading; source guards now read feature modules through `tests/helpers/notes_source.py`. `scripts/verify_frontend_runtime.py` checks all manifest outputs in a Python-only distribution, while `scripts/verify_notes_browser_runtime.py` probes an authenticated temporary native app. These require their declared dependencies/browser environment; committed receipts and screenshots are historical evidence, not a fresh acceptance run. Runtime serving still requires no frontend build or Node installation.
+
+## Skills Extraction And Upload Contract Tests
+
+`tests/test_skills_audit_characterization.py` freezes 22 route declarations, 28 Python interfaces and canonical OpenAPI (17 paths, 22 operations, five schemas) from committed fixtures; constrained fields, supported default factories, model configuration and aliases are checked structurally. Unsupported factories fail without execution. `tests/test_skills_audit_services.py` exercises real route/service wiring with offline model/agent/manager substitutes, including prompt seams, owner/request authority, one-use approvals and cancellation/stream closure. Fixtures do not prove arbitrary validators, live execution or authorization by themselves. ReDoS guards now scan/import `services/skills/evaluation.py`. The Gitleaks exception is constrained to one exact historical digest, the generic-api-key rule and two named paths; this maintenance does not claim a new full-history scan.
+
+`tests/test_upload_no_login.py` covers disabled-auth access after setup, missing/unconfigured manager failures, token ownership/scopes, legacy ownerless uploads and OCR preservation on rejection. Its loopback-host parametrization does not itself change TestClient transport identity, so source behavior and narrower assertions remain the evidence for absence of a loopback bypass.
+
 ## Current Gaps
 
 - Fresh install smoke coverage across Linux native, Docker, macOS native/app, Windows native, WSL/Git Bash, missing Node/npm, missing Chroma service, and GPU overlays remains a roadmap item.
-- There is no frontend build/type-check/npm test pipeline.
-- CI now covers Python compile, first-party JS syntax, focused-test guidance,
-  and pytest smoke; it does not cover Docker compose validation, launcher smoke
-  tests, browser/module-graph execution, or platform installs.
+- Frontend source/output and architecture gates exist; they do not establish full browser or platform correctness.
+- Real deployment, GPU and cross-platform install verification still require separate runs beyond CI gates.
 - Optional dependency behavior is broad; remaining gaps include local STT missing-`faster-whisper`, Kokoro's Python/GPU degraded matrix, and provider/OAuth combinations not covered by focused tests.
 - GitHub description-check scripts and `scripts/pr_blocker_audit.py` need continued local fixtures for section parsing, placeholder stripping, label swaps, workflow-safe behavior, and duplicate/hot-file heuristics.
 - Spec bootstrap rules lack meta tests for reading `_readme.md`, spec shape, `.env*` handling, draft/report placement, and shared helper conventions.
 - NVIDIA helper install/`.env` mutation paths and real Docker/GPU startup are not covered by local tests.
 - Bash/Zsh completion behavior is not covered.
-- There is no canonical full-suite known-failing/flaky ledger.
+- `tests/KNOWN_FAILURES.md` records observed environment-dependent full-suite failures and prerequisites; its measured basis is historical, so verify applicability rather than treating it as a passing waiver.
 - There is no central CLI redaction/sensitive-output regression matrix across backup, logs, mail, MCP, tasks, and webhook scripts.
 - Dependency/image pinning policy is mixed: Python requirements are mostly unpinned, SearXNG is pinned, Chroma image currently uses `latest`, npm uses a lockfile, and browser MCP uses cache-gated `@playwright/mcp@latest`.

From 15099ebabbd824c2235f9f81eb8e1d436d0686e2 Mon Sep 17 00:00:00 2001
From: PrinceThummar011 <princethummar011@gmail.com>
Date: Fri, 16 Oct 2026 17:16:15 +0530
Subject: [PATCH 26/53] refactor(mcp): unify OAuth flow resolution and
 distinguish missing params from expired state (#5598)

---
 routes/mcp/mcp_routes.py | 60 +++++++++++++++++++++++-----------------
 tests/test_mcp_oauth.py  | 42 ++++++++++++++++++++++++++++
 2 files changed, 76 insertions(+), 26 deletions(-)

diff --git a/routes/mcp/mcp_routes.py b/routes/mcp/mcp_routes.py
index 385cf09e3..5d14ba8c3 100644
--- a/routes/mcp/mcp_routes.py
+++ b/routes/mcp/mcp_routes.py
@@ -114,6 +114,18 @@ def _mcp_oauth_redirect_uri() -> str:
     return REDIRECT_URI
 
 
+def _is_legacy_google_flow(identifier: str) -> bool:
+    """Determine whether an identifier is the server_id of a configured Google OAuth MCP server."""
+    if not identifier:
+        return False
+    db = SessionLocal()
+    try:
+        srv = db.query(McpServer).filter(McpServer.id == identifier).first()
+        return bool(srv and srv.oauth_config)
+    finally:
+        db.close()
+
+
 def setup_mcp_routes(mcp_manager: McpManager):
     """Setup MCP routes with the provided manager."""
 
@@ -490,24 +502,23 @@ def setup_mcp_routes(mcp_manager: McpManager):
     async def oauth_callback(code: str = "", state: str = "", request: Request = None):
         """Handle OAuth callback. Generic MCP OAuth flows resolve via the
         pending-state registry; Google flows fall through to the legacy path."""
+        if not state:
+            return HTMLResponse(_oauth_result_page("Error", "No OAuth state parameter found in the callback URL."), status_code=400)
+        if not code:
+            return HTMLResponse(_oauth_result_page("Error", "No authorization code found in the URL. Make sure you copied the full URL from your browser."), status_code=400)
+
         from src.mcp_oauth import resolve_pending
-        if state and code and resolve_pending(state, code):
+        if resolve_pending(state, code):
             return HTMLResponse(_oauth_result_page(
                 "Authorization Successful",
                 "The MCP server is connecting. You can close this window and return to Odysseus.",
                 success=True,
             ))
 
-        # Legacy Google path: state is the server_id
-        if state:
-            db = SessionLocal()
-            try:
-                srv = db.query(McpServer).filter(McpServer.id == state).first()
-                if srv and srv.oauth_config:
-                    require_admin(request)
-                    return await _exchange_and_connect(state, code, request)
-            finally:
-                db.close()
+        # Check if this callback belongs to a legacy Google flow vs expired generic flow
+        if _is_legacy_google_flow(state):
+            require_admin(request)
+            return await _exchange_and_connect(state, code, request)
 
         return HTMLResponse(_oauth_result_page(
             "Authorization Expired",
@@ -527,31 +538,28 @@ def setup_mcp_routes(mcp_manager: McpManager):
         except Exception:
             return HTMLResponse(_oauth_result_page("Error", "Invalid URL format."), status_code=400)
 
+        state = params.get("state", [None])[0]
+        if not state:
+            return HTMLResponse(_oauth_result_page("Error", "No OAuth state parameter found in the callback URL."), status_code=400)
+
         # Generic MCP OAuth: if the pasted URL carries a state we are waiting on,
         # resolve it directly (the background connect finishes the handshake).
-        state = params.get("state", [None])[0]
         from src.mcp_oauth import resolve_pending
-        if state and resolve_pending(state, code):
+        if resolve_pending(state, code):
             return HTMLResponse(_oauth_result_page(
                 "Authorization Successful",
                 "The MCP server is connecting. You can close this window and return to Odysseus.",
                 success=True,
             ))
 
-        db = SessionLocal()
-        try:
-            srv = db.query(McpServer).filter(McpServer.id == server_id).first()
-            if not srv:
-                return HTMLResponse(_oauth_result_page("Error", "Server not found."), status_code=404)
-            if not srv.oauth_config:
-                return HTMLResponse(_oauth_result_page(
-                    "Authorization Expired",
-                    "This authorization round has expired. Press Reconnect in Odysseus and try again.",
-                ), status_code=400)
-        finally:
-            db.close()
+        # Check if this exchange belongs to a legacy Google flow vs expired generic flow
+        if _is_legacy_google_flow(server_id):
+            return await _exchange_and_connect(server_id, code, request)
 
-        return await _exchange_and_connect(server_id, code, request)
+        return HTMLResponse(_oauth_result_page(
+            "Authorization Expired",
+            "This authorization round has expired. Press Reconnect in Odysseus and try again.",
+        ), status_code=400)
 
     async def _exchange_and_connect(server_id: str, code: str, request: Request):
         """Exchange auth code for tokens and connect the MCP server."""
diff --git a/tests/test_mcp_oauth.py b/tests/test_mcp_oauth.py
index 24f52820e..a0ba8a6a2 100644
--- a/tests/test_mcp_oauth.py
+++ b/tests/test_mcp_oauth.py
@@ -450,3 +450,45 @@ def test_oauth_exchange_expired_generic_state_returns_expired_page(monkeypatch):
         in resp.text
     )
     assert "No OAuth config." not in resp.text
+
+
+def test_oauth_callback_missing_state_returns_malformed_error_not_expired():
+    """Missing state parameter in callback must return a bad-request error and must
+    not be treated as an expired authorization round."""
+    from unittest.mock import MagicMock
+    from fastapi import FastAPI
+    from fastapi.testclient import TestClient
+    from routes.mcp import mcp_routes
+
+    app = FastAPI()
+    manager = MagicMock()
+    router = mcp_routes.setup_mcp_routes(manager)
+    app.include_router(router)
+    client = TestClient(app)
+
+    resp = client.get("/api/mcp/oauth/callback?code=some-code")
+    assert resp.status_code == 400
+    assert "No OAuth state parameter found in the callback URL." in resp.text
+    assert "Authorization Expired" not in resp.text
+    assert "This authorization round has expired" not in resp.text
+
+
+def test_oauth_callback_missing_code_returns_malformed_error_not_expired():
+    """Missing code parameter in callback must return a bad-request error and must
+    not be treated as an expired authorization round."""
+    from unittest.mock import MagicMock
+    from fastapi import FastAPI
+    from fastapi.testclient import TestClient
+    from routes.mcp import mcp_routes
+
+    app = FastAPI()
+    manager = MagicMock()
+    router = mcp_routes.setup_mcp_routes(manager)
+    app.include_router(router)
+    client = TestClient(app)
+
+    resp = client.get("/api/mcp/oauth/callback?state=some-state")
+    assert resp.status_code == 400
+    assert "No authorization code found in the URL." in resp.text
+    assert "Authorization Expired" not in resp.text
+    assert "This authorization round has expired" not in resp.text

From 88772b3278183949413e9da7d57e741057302e5e Mon Sep 17 00:00:00 2001
From: Afonso Coutinho <afonso@yack.com.br>
Date: Mon, 19 Oct 2026 14:04:10 +0100
Subject: [PATCH 27/53] fix(tasks): apply the admin-only action policy in
 manage_tasks (#6358)

POST /api/tasks and the scheduler both refuse action tasks whose action
is in ADMIN_ONLY_TASK_ACTIONS (run_local, run_script, ssh_command,
cookbook_serve) for owners without admin task privileges: those actions
reach subprocess.run(shell=True) or SSH with no sandbox. The model-facing
manage_tasks tool applied neither check, so an agent could create or edit
such a task, resume it, or trigger it, and only the scheduler's
execution-time guard stood in the way (pausing the task after the fact).

Route the tool through the same src.task_action_policy helpers the HTTP
route uses: create checks the requested type/action, edit checks the task
as it would be after the edit (so an llm task cannot be flipped into a
shell action), and resume/run check the stored task. Admins, non-
privileged actions and llm/research tasks are unaffected; pause still
works for everyone since it only narrows.

Fixes #6021


Claude-Session: https://claude.ai/code/session_01UAB5sz5srMKR7rbeDFtdMH

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
Co-authored-by: Alexandre Teixeira <111787685+alteixeira20@users.noreply.github.com>
---
 src/tools/system.py                           |  37 +++
 .../test_manage_tasks_admin_action_policy.py  | 289 ++++++++++++++++++
 2 files changed, 326 insertions(+)
 create mode 100644 tests/test_manage_tasks_admin_action_policy.py

diff --git a/src/tools/system.py b/src/tools/system.py
index a5e9d340b..9b0e6d1bb 100644
--- a/src/tools/system.py
+++ b/src/tools/system.py
@@ -325,6 +325,26 @@ def _task_structured_schedule(args, fallback_time=None):
             'cron_expression': f'{parsed.minute} {parsed.hour} * * {cron_days}'}
 
 
+def _admin_task_action_denied(owner: Optional[str], task_type: Optional[str], action_name: Optional[str]) -> Optional[Dict]:
+    """Apply the shared admin-only task-action policy to a tool call.
+
+    ``POST /api/tasks`` and the scheduler both refuse ``run_local``,
+    ``run_script``, ``ssh_command`` and ``cookbook_serve`` action tasks for
+    owners without admin task privileges (``src.task_action_policy``).
+    Those actions reach ``subprocess.run(shell=True)`` / SSH with no sandbox,
+    so the model-facing tool must apply the same policy at create/edit/
+    resume/run time instead of storing a task the scheduler will only pause
+    later. Returns the tool error dict to hand back, or None when allowed.
+    """
+    from src.task_action_policy import (
+        is_admin_only_task_action,
+        owner_has_admin_task_privileges,
+    )
+    if is_admin_only_task_action(task_type, action_name) and not owner_has_admin_task_privileges(owner):
+        return {"error": f"Action '{action_name}' requires admin privileges", "exit_code": 1}
+    return None
+
+
 async def do_manage_tasks(content: str, owner: Optional[str] = None) -> Dict:
     """Handle manage_tasks tool calls: CRUD on scheduled tasks."""
     import uuid as _uuid
@@ -462,6 +482,9 @@ async def do_manage_tasks(content: str, owner: Optional[str] = None) -> Dict:
                 return {"error": "Prompt is required for llm/research tasks", "exit_code": 1}
             if task_type == "action" and not args.get("action_name"):
                 return {"error": "action_name is required for action tasks", "exit_code": 1}
+            denied = _admin_task_action_denied(owner, task_type, args.get("action_name"))
+            if denied:
+                return denied
 
             # Compute next_run for schedule triggers
             next_run = None
@@ -525,6 +548,14 @@ async def do_manage_tasks(content: str, owner: Optional[str] = None) -> Dict:
             if owner and task.owner != owner:
                 return {"error": "Access denied", "exit_code": 1}
 
+            # Check the policy against the task as it would be after the
+            # edit, so an llm task can't be flipped into a shell action.
+            next_task_type = args["task_type"] if args.get("task_type") is not None else task.task_type
+            next_action = args["action_name"] if args.get("action_name") is not None else task.action
+            denied = _admin_task_action_denied(owner, next_task_type, next_action)
+            if denied:
+                return denied
+
             if 'weekdays' in args or 'day_of_month' in args:
                 clock = task.scheduled_time
                 if task.schedule == 'cron':
@@ -624,6 +655,9 @@ async def do_manage_tasks(content: str, owner: Optional[str] = None) -> Dict:
             if action == "pause":
                 task.status = "paused"
             else:
+                denied = _admin_task_action_denied(owner, task.task_type, task.action)
+                if denied:
+                    return denied
                 task.status = "active"
                 if (task.trigger_type or "schedule") == "schedule":
                     task.next_run = compute_next_run(
@@ -644,6 +678,9 @@ async def do_manage_tasks(content: str, owner: Optional[str] = None) -> Dict:
                 return error
             if owner and task.owner != owner:
                 return {"error": "Access denied", "exit_code": 1}
+            denied = _admin_task_action_denied(owner, task.task_type, task.action)
+            if denied:
+                return denied
 
             from src.event_bus import get_task_scheduler
             scheduler = get_task_scheduler()
diff --git a/tests/test_manage_tasks_admin_action_policy.py b/tests/test_manage_tasks_admin_action_policy.py
new file mode 100644
index 000000000..b30446d62
--- /dev/null
+++ b/tests/test_manage_tasks_admin_action_policy.py
@@ -0,0 +1,289 @@
+"""manage_tasks must apply the admin-only task-action policy.
+
+``POST /api/tasks`` (routes/task/task_routes.py) and the scheduler
+(src/task_scheduler.py) both refuse ``action`` tasks whose action is in
+``ADMIN_ONLY_TASK_ACTIONS`` (run_local, run_script, ssh_command,
+cookbook_serve) for owners without admin task privileges — those actions run
+``subprocess.run(shell=True)`` or SSH with no sandbox. The model-facing
+``do_manage_tasks`` applied neither check, so an agent could store such a task
+on create/edit and resume/run it; the scheduler would only pause it at
+execution time. Regression for issue #6021: the tool now enforces the same
+policy on create, edit, resume and run, and keeps allowing admins and the
+non-privileged actions.
+"""
+
+import json
+import tempfile
+
+import pytest
+from sqlalchemy import create_engine
+from sqlalchemy.orm import sessionmaker
+from sqlalchemy.pool import NullPool
+
+from tests.helpers.import_state import clear_fake_database_modules
+
+clear_fake_database_modules()
+
+import core.database as cdb
+from core.database import ScheduledTask
+import src.task_action_policy as policy_mod
+import src.tools.system as system_mod
+from src.tools.system import do_manage_tasks
+
+_TMPDB = tempfile.NamedTemporaryFile(suffix=".db", delete=False)
+_ENGINE = create_engine(
+    f"sqlite:///{_TMPDB.name}",
+    connect_args={"check_same_thread": False},
+    poolclass=NullPool,
+)
+cdb.Base.metadata.create_all(_ENGINE)
+_TS = sessionmaker(bind=_ENGINE, autoflush=False, autocommit=False)
+
+
+@pytest.fixture(autouse=True)
+def _bind_session_factory(monkeypatch):
+    # do_manage_tasks does `from core.database import SessionLocal` at call
+    # time. Bind it per test (not at import) so this file stays
+    # order-independent from sibling files that point it at their own DB.
+    monkeypatch.setattr(cdb, "SessionLocal", _TS)
+
+
+@pytest.fixture
+def privileges(monkeypatch):
+    """Drive owner_has_admin_task_privileges from a plain dict."""
+    admins = {"root"}
+    monkeypatch.setattr(
+        policy_mod, "owner_has_admin_task_privileges",
+        lambda owner: owner in admins,
+    )
+    return admins
+
+
+def _seed(task_id, owner, task_type="llm", action=None, status="active"):
+    db = _TS()
+    try:
+        db.add(ScheduledTask(
+            id=task_id, owner=owner, name=task_id, prompt="original",
+            task_type=task_type, action=action, trigger_type="webhook",
+            status=status, output_target="session",
+        ))
+        db.commit()
+    finally:
+        db.close()
+
+
+def _get(task_id):
+    db = _TS()
+    try:
+        return db.query(ScheduledTask).filter(ScheduledTask.id == task_id).first()
+    finally:
+        db.close()
+
+
+def _count(owner):
+    db = _TS()
+    try:
+        return db.query(ScheduledTask).filter(ScheduledTask.owner == owner).count()
+    finally:
+        db.close()
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("action_name", sorted(policy_mod.ADMIN_ONLY_TASK_ACTIONS))
+async def test_create_admin_only_action_denied_for_non_admin(privileges, action_name):
+    before = _count("alice")
+    out = await do_manage_tasks(json.dumps({
+        "action": "create", "task_type": "action", "action_name": action_name,
+        "name": "pwn", "schedule": "daily", "scheduled_time": "09:00",
+    }), owner="alice")
+    assert out["exit_code"] == 1, out
+    assert "requires admin privileges" in out["error"]
+    assert _count("alice") == before
+
+
+@pytest.mark.asyncio
+async def test_create_admin_only_action_allowed_for_admin(privileges):
+    out = await do_manage_tasks(json.dumps({
+        "action": "create", "task_type": "action", "action_name": "run_local",
+        "name": "ok", "schedule": "daily", "scheduled_time": "09:00",
+    }), owner="root")
+    assert out["exit_code"] == 0, out
+    assert _get(out["task_id"]).action == "run_local"
+
+
+@pytest.mark.asyncio
+async def test_create_regular_action_allowed_for_non_admin(privileges):
+    out = await do_manage_tasks(json.dumps({
+        "action": "create", "task_type": "action", "action_name": "tidy_sessions",
+        "name": "ok", "schedule": "daily", "scheduled_time": "09:00",
+    }), owner="alice")
+    assert out["exit_code"] == 0, out
+
+
+@pytest.mark.asyncio
+async def test_create_llm_task_allowed_for_non_admin(privileges):
+    out = await do_manage_tasks(json.dumps({
+        "action": "create", "task_type": "llm", "prompt": "summarize",
+        "schedule": "daily", "scheduled_time": "09:00",
+    }), owner="alice")
+    assert out["exit_code"] == 0, out
+
+
+@pytest.mark.asyncio
+async def test_edit_cannot_turn_llm_task_into_shell_action(privileges):
+    _seed("alice-llm", "alice")
+    out = await do_manage_tasks(json.dumps({
+        "action": "edit", "task_id": "alice-llm",
+        "task_type": "action", "action_name": "ssh_command",
+    }), owner="alice")
+    assert out["exit_code"] == 1, out
+    assert "requires admin privileges" in out["error"]
+    task = _get("alice-llm")
+    assert task.task_type == "llm" and task.action is None
+
+
+@pytest.mark.asyncio
+async def test_edit_cannot_swap_action_name_to_admin_only(privileges):
+    _seed("alice-action", "alice", task_type="action", action="tidy_sessions")
+    out = await do_manage_tasks(json.dumps({
+        "action": "edit", "task_id": "alice-action", "action_name": "run_script",
+    }), owner="alice")
+    assert out["exit_code"] == 1, out
+    assert _get("alice-action").action == "tidy_sessions"
+
+
+@pytest.mark.asyncio
+async def test_edit_of_unrelated_field_on_admin_only_task_denied_for_non_admin(privileges):
+    # A task that slipped in before the policy (or via demotion of its owner)
+    # cannot be kept alive by a non-admin: the route rejects the same edit.
+    _seed("alice-legacy", "alice", task_type="action", action="run_local")
+    out = await do_manage_tasks(json.dumps({
+        "action": "edit", "task_id": "alice-legacy", "name": "renamed",
+    }), owner="alice")
+    assert out["exit_code"] == 1, out
+    assert _get("alice-legacy").name == "alice-legacy"
+
+
+@pytest.mark.asyncio
+async def test_resume_admin_only_task_denied_for_non_admin(privileges):
+    _seed("alice-paused", "alice", task_type="action", action="run_local", status="paused")
+    out = await do_manage_tasks(json.dumps({
+        "action": "resume", "task_id": "alice-paused",
+    }), owner="alice")
+    assert out["exit_code"] == 1, out
+    assert _get("alice-paused").status == "paused"
+
+
+@pytest.mark.asyncio
+async def test_pause_admin_only_task_still_allowed(privileges):
+    # Narrowing is always fine: a non-admin may pause a task they own.
+    _seed("alice-active", "alice", task_type="action", action="run_local")
+    out = await do_manage_tasks(json.dumps({
+        "action": "pause", "task_id": "alice-active",
+    }), owner="alice")
+    assert out["exit_code"] == 0, out
+    assert _get("alice-active").status == "paused"
+
+
+@pytest.mark.asyncio
+async def test_run_admin_only_task_denied_before_scheduler(privileges, monkeypatch):
+    _seed("alice-run", "alice", task_type="action", action="ssh_command")
+    calls = []
+
+    class _Sched:
+        async def run_task_now(self, task_id):
+            calls.append(task_id)
+            return True
+
+    import src.event_bus as event_bus
+    monkeypatch.setattr(event_bus, "get_task_scheduler", lambda: _Sched())
+    out = await do_manage_tasks(json.dumps({
+        "action": "run", "task_id": "alice-run",
+    }), owner="alice")
+    assert out["exit_code"] == 1, out
+    assert calls == []
+
+
+@pytest.mark.asyncio
+async def test_run_admin_only_task_allowed_for_admin(privileges, monkeypatch):
+    _seed("root-run", "root", task_type="action", action="ssh_command")
+    calls = []
+
+    class _Sched:
+        async def run_task_now(self, task_id):
+            calls.append(task_id)
+            return True
+
+    import src.event_bus as event_bus
+    monkeypatch.setattr(event_bus, "get_task_scheduler", lambda: _Sched())
+    out = await do_manage_tasks(json.dumps({
+        "action": "run", "task_id": "root-run",
+    }), owner="root")
+    assert out["exit_code"] == 0, out
+    assert calls == ["root-run"]
+
+
+def test_policy_helper_uses_shared_constants(privileges):
+    # The tool must consult the shared policy module, not a private copy of
+    # the action names, so a new admin-only action is covered everywhere.
+    assert system_mod._admin_task_action_denied("alice", "action", "run_local") is not None
+    assert system_mod._admin_task_action_denied("root", "action", "run_local") is None
+    assert system_mod._admin_task_action_denied("alice", "action", "tidy_sessions") is None
+    assert system_mod._admin_task_action_denied("alice", "llm", "run_local") is None
+
+
+@pytest.mark.asyncio
+async def test_run_admin_only_task_by_name_denied_for_non_admin(privileges, monkeypatch):
+    _seed("alice-run-name", "alice", task_type="action", action="ssh_command")
+    calls = []
+
+    class _Sched:
+        async def run_task_now(self, task_id):
+            calls.append(task_id)
+            return True
+
+    import src.event_bus as event_bus
+    monkeypatch.setattr(event_bus, "get_task_scheduler", lambda: _Sched())
+    out = await do_manage_tasks(json.dumps({
+        "action": "run", "name": "alice-run-name",
+    }), owner="alice")
+    assert out["exit_code"] == 1, out
+    assert "requires admin privileges" in out["error"]
+    assert calls == []
+
+
+@pytest.mark.asyncio
+async def test_create_admin_only_action_seals_authority_for_admin(privileges):
+    out = await do_manage_tasks(json.dumps({
+        "action": "create", "task_type": "action", "action_name": "run_local",
+        "name": "sealed-task", "schedule": "daily", "scheduled_time": "09:00",
+    }), owner="root")
+    assert out["exit_code"] == 0, out
+    task = _get(out["task_id"])
+    assert task.action == "run_local"
+    assert task.request_authority_json is not None
+
+
+def test_real_owner_has_admin_task_privileges_branches(monkeypatch):
+    """Verify owner_has_admin_task_privileges without mocking."""
+    # Auth disabled branch
+    monkeypatch.setenv("AUTH_ENABLED", "false")
+    assert policy_mod.owner_has_admin_task_privileges("alice") is True
+    assert policy_mod.owner_has_admin_task_privileges(None) is True
+
+    # Auth enabled branch with configured AuthManager
+    monkeypatch.delenv("AUTH_ENABLED", raising=False)
+
+    class FakeAuth:
+        is_configured = True
+
+        def is_admin(self, u):
+            return u == "admin"
+
+    import core.auth as c_auth
+    monkeypatch.setattr(c_auth, "AuthManager", lambda: FakeAuth())
+
+    assert policy_mod.owner_has_admin_task_privileges("admin") is True
+    assert policy_mod.owner_has_admin_task_privileges("alice") is False
+    assert policy_mod.owner_has_admin_task_privileges("internal-tool") is True
+    assert policy_mod.owner_has_admin_task_privileges(None) is False

From c1d90beeffa94c25a4363a77c00f17ee82109e17 Mon Sep 17 00:00:00 2001
From: Alexandre Teixeira <111787685+alteixeira20@users.noreply.github.com>
Date: Mon, 19 Oct 2026 14:13:01 +0100
Subject: [PATCH 28/53] fix(scheduler): catch OverflowError on non-finite
 research settings

Catch OverflowError in addition to TypeError and ValueError when converting
research_max_tokens, research_extraction_timeout_seconds, and
research_extraction_concurrency to int. Non-finite numbers parsed from JSON
(such as 1e309 or -1e309 representing float infinity) raise OverflowError on
int() conversion, which previously escaped the handler and crashed scheduled
research execution. Also add unit tests covering exponent overflow values.
---
 src/task_scheduler.py                         |  6 ++---
 .../test_scheduler_research_settings_guard.py | 23 +++++++++++++++++++
 2 files changed, 26 insertions(+), 3 deletions(-)

diff --git a/src/task_scheduler.py b/src/task_scheduler.py
index 7b3c6e765..50613ae72 100644
--- a/src/task_scheduler.py
+++ b/src/task_scheduler.py
@@ -368,19 +368,19 @@ def _resolve_research_settings(get_setting_fn):
     """
     try:
         max_tokens = int(get_setting_fn("research_max_tokens", 8192))
-    except (TypeError, ValueError):
+    except (TypeError, ValueError, OverflowError):
         max_tokens = 8192
     try:
         extraction_timeout = int(
             get_setting_fn("research_extraction_timeout_seconds", 90) or 90
         )
-    except (TypeError, ValueError):
+    except (TypeError, ValueError, OverflowError):
         extraction_timeout = 90
     try:
         extraction_concurrency = int(
             get_setting_fn("research_extraction_concurrency", 3) or 3
         )
-    except (TypeError, ValueError):
+    except (TypeError, ValueError, OverflowError):
         extraction_concurrency = 3
     return max_tokens, extraction_timeout, extraction_concurrency
 
diff --git a/tests/test_scheduler_research_settings_guard.py b/tests/test_scheduler_research_settings_guard.py
index 0cdfa2b87..a6448fc9c 100644
--- a/tests/test_scheduler_research_settings_guard.py
+++ b/tests/test_scheduler_research_settings_guard.py
@@ -15,6 +15,8 @@ same reads defensively; this is the scheduler's equivalent.
 
 from __future__ import annotations
 
+import json
+
 from src.task_scheduler import _resolve_research_settings
 
 
@@ -77,3 +79,24 @@ def test_valid_ints_pass_through():
     )
 
     assert _resolve_research_settings(get) == (2048, 120, 6)
+
+
+def test_non_finite_json_numbers_fall_back_individually():
+    """JSON exponent overflow produces infinity, which int() cannot convert."""
+    keys = (
+        "research_max_tokens",
+        "research_extraction_timeout_seconds",
+        "research_extraction_concurrency",
+    )
+    valid = (4096, 45, 2)
+    defaults = (8192, 90, 3)
+
+    for non_finite in (json.loads("1e309"), json.loads("-1e309")):
+        for index, key in enumerate(keys):
+            values = dict(zip(keys, valid))
+            values[key] = non_finite
+            expected = list(valid)
+            expected[index] = defaults[index]
+            assert _resolve_research_settings(
+                _fake_get_setting(values)
+            ) == tuple(expected)

From b2613b21064e9e8654ffb90848c9e708e8d9f4ac Mon Sep 17 00:00:00 2001
From: Gr33nbl00d <G_Rehm@ich-habe-fertig.com>
Date: Wed, 23 Sep 2026 20:13:25 +0200
Subject: [PATCH 29/53] fix(ui): respect iOS safe areas, screen height and
 landscape layout

---
 frontend/src/features/notes/ui/panel.js |  2 +-
 static/css/00-tokens.css                | 27 ++++++++-
 static/css/01-agent-chat.css            | 76 +++++++++++++++++--------
 static/css/02-compare.css               | 20 ++++---
 static/css/03-agent-chat.css            |  6 +-
 static/css/05-documents.css             |  4 +-
 static/css/06-admin-settings.css        | 26 +++++----
 static/css/07-documents.css             | 44 +++++++-------
 static/css/13-image-editor.css          |  2 +-
 static/css/14-email.css                 |  7 ++-
 static/css/17-research.css              |  4 +-
 static/index.html                       |  7 +++
 static/js/chat.js                       |  7 ---
 static/js/emailLibrary/index.js         |  9 +--
 static/js/emailLibrary/reader.js        |  3 +-
 static/js/features/notes/ui/panel.js    |  2 +-
 static/js/init.js                       | 25 ++++++++
 static/js/modalSnap.js                  | 52 ++++++++++++++---
 static/js/sidebar-layout.js             |  6 +-
 static/js/windowResize.js               |  9 ++-
 20 files changed, 243 insertions(+), 95 deletions(-)

diff --git a/frontend/src/features/notes/ui/panel.js b/frontend/src/features/notes/ui/panel.js
index 0a6031233..2265897c0 100644
--- a/frontend/src/features/notes/ui/panel.js
+++ b/frontend/src/features/notes/ui/panel.js
@@ -190,7 +190,7 @@ export function createPanel({
     // which left it as a side panel squeezing the chat).
     if (window.innerWidth <= 768) {
       pane.style.position = 'fixed';
-      pane.style.inset = '0';
+      pane.style.inset = 'var(--sheet-top) 0 0';
       pane.style.width = '100%';
       pane.style.maxWidth = '100%';
       pane.style.zIndex = '170';
diff --git a/static/css/00-tokens.css b/static/css/00-tokens.css
index e502f7670..1105ba70c 100644
--- a/static/css/00-tokens.css
+++ b/static/css/00-tokens.css
@@ -82,6 +82,28 @@
   /* Warm accent — used by the Goals/Today UI in Notes. Lives as a token so
      themes can override without touching the goal CSS. */
   --accent-warm: #d19a66;
+
+  /* Device safe areas (notch, Dynamic Island, home indicator) */
+  --safe-top: env(safe-area-inset-top, 0px);
+  --safe-right: env(safe-area-inset-right, 0px);
+  --safe-bottom: env(safe-area-inset-bottom, 0px);
+  --safe-left: env(safe-area-inset-left, 0px);
+  /* Full-height sheets start clear of the status-bar blur; flush when there is no inset */
+  --sheet-top: calc(var(--safe-top) + min(var(--safe-top), 24px));
+  --app-height: 100dvh;
+}
+/* The on-screen keyboard covers the home indicator */
+:root.keyboard-open { --safe-bottom: 0px; }
+/* iOS standalone web apps report dvh (and the viewport) short by the status bar
+   height; lvh still matches the screen. Body becomes the containing block for
+   fixed elements so overlays reach the real bottom edge as well. Containment
+   stops body's background reaching the canvas, so html paints it instead. */
+@media (display-mode: standalone) {
+  @supports (-webkit-touch-callout: none) {
+    :root { --app-height: 100lvh; }
+    html { height: var(--app-height); background-color: var(--bg); }
+    body { contain: layout; overflow: clip; }
+  }
 }
 
 :root.light {
@@ -121,9 +143,12 @@ body {
   font-family: var(--font-family, 'Fira Code', monospace);
   display: flex;
   height: 100%;
-  height: 100dvh; /* dynamic viewport height — adapts when mobile keyboard opens */
+  height: var(--app-height);
+  padding: var(--safe-top) var(--safe-right) var(--safe-bottom) var(--safe-left);
   overflow: hidden;
 }
+/* iOS keeps the full height when the keyboard opens; size the shell to what is visible */
+:root.keyboard-open body { height: var(--keyboard-viewport-height, var(--app-height)); }
 
 /* Self-hosted Fira Code font */
 @font-face { font-family: 'Fira Code'; font-weight: 300; font-style: normal; font-display: swap; src: url('/static/fonts/FiraCode-Light.woff2') format('woff2'); }
diff --git a/static/css/01-agent-chat.css b/static/css/01-agent-chat.css
index 7db3115a6..506d04e81 100644
--- a/static/css/01-agent-chat.css
+++ b/static/css/01-agent-chat.css
@@ -562,8 +562,8 @@ body.bg-pattern-ascii-fireflies {
     /* Fixed hamburger — always visible, toggles sidebar */
     .hamburger-btn {
       position: fixed;
-      top: 12px;
-      left: 9px;
+      top: calc(12px + var(--safe-top));
+      left: calc(9px + var(--safe-left));
       right: auto;
       z-index: 210;
       width: 30px;
@@ -583,7 +583,7 @@ body.bg-pattern-ascii-fireflies {
     }
     body.hamburger-right .hamburger-btn {
       left: auto;
-      right: 9px;
+      right: calc(9px + var(--safe-right));
     }
     .mobile-new-chat-btn {
       display: none;
@@ -655,6 +655,25 @@ body.bg-pattern-ascii-fireflies {
       border-right: none;
       border-left: 1px solid var(--border);
     }
+    /* Edge columns bleed into the safe-area strips instead of leaving bare background */
+    @media (min-width: 769px) {
+      .sidebar:not(.hidden) {
+        margin-bottom: calc(-1 * var(--safe-bottom));
+        padding-bottom: var(--safe-bottom);
+      }
+      .sidebar:not(.hidden):not(.right-side) {
+        margin-left: calc(-1 * var(--safe-left));
+        padding-left: var(--safe-left);
+      }
+      .sidebar.right-side:not(.hidden) {
+        margin-right: calc(-1 * var(--safe-right));
+        padding-right: var(--safe-right);
+      }
+      .icon-rail {
+        margin-bottom: calc(-1 * var(--safe-bottom));
+        padding-bottom: calc(8px + var(--safe-bottom));
+      }
+    }
     .icon-rail-divider {
       width: 24px;
       height: 1px;
@@ -4800,7 +4819,7 @@ body.bg-pattern-ascii-fireflies {
 
     .toast {
       position:fixed;
-      top: 16px; right: 16px;
+      top: calc(16px + var(--safe-top)); right: calc(16px + var(--safe-right));
       left: auto; bottom: auto;
       background:var(--panel); color:var(--fg);
       border:1px solid color-mix(in srgb, var(--accent) 30%, transparent);
@@ -4984,8 +5003,8 @@ body.bg-pattern-ascii-fireflies {
     .toast.toast-panel-offset.exiting { transform: translateX(-120%); }
     @media (max-width: 768px) {
       .toast {
-        top: 12px;
-        right: 12px;
+        top: calc(12px + var(--safe-top));
+        right: calc(12px + var(--safe-right));
         max-width: calc(100vw - 24px);
         /* Receive touches so the swipe-to-dismiss gesture works (desktop keeps
            pointer-events:none so the toast never blocks clicks). Horizontal pan
@@ -5109,6 +5128,7 @@ body.bg-pattern-ascii-fireflies {
            --sidebar-bg. */
         background: var(--sidebar-bg, var(--panel)) !important;
         backdrop-filter: none !important;
+        padding: var(--safe-top) 0 var(--safe-bottom) var(--safe-left);
       }
       .sidebar.hidden {
         width: 80% !important;
@@ -5122,6 +5142,8 @@ body.bg-pattern-ascii-fireflies {
       .sidebar.right-side {
         left: auto; right: 0;
         box-shadow: -4px 0 20px rgba(0,0,0,0.5);
+        padding-left: 0;
+        padding-right: var(--safe-right);
       }
       html.ody-sidebar-off .sidebar,
       html.ody-mobile-startup-sidebar-hidden .sidebar {
@@ -5315,9 +5337,9 @@ body.bg-pattern-ascii-fireflies {
       .hamburger-btn {
         width: 44px;
         height: 44px;
-        top: 6px;
+        top: calc(6px + var(--safe-top));
         left: auto !important;
-        right: 4px !important;
+        right: calc(4px + var(--safe-right)) !important;
         -webkit-tap-highlight-color: transparent;
       }
       .hamburger-btn:hover,
@@ -5330,8 +5352,8 @@ body.bg-pattern-ascii-fireflies {
       .mobile-new-chat-btn {
         display: flex;
         position: fixed;
-        top: 12px;
-        left: 8px;
+        top: calc(12px + var(--safe-top));
+        left: calc(8px + var(--safe-left));
         z-index: 210;
         width: 32px;
         height: 32px;
@@ -5400,10 +5422,6 @@ body.bg-pattern-ascii-fireflies {
         padding: 6px !important;
         border-radius: 12px !important;
       }
-      /* Safe area padding for notched devices */
-      .chat-input-bar {
-        padding-bottom: calc(10px + env(safe-area-inset-bottom, 0px));
-      }
       /* Mode toggle — larger touch targets */
       .mode-toggle {
         height: 34px;
@@ -5447,15 +5465,15 @@ body.bg-pattern-ascii-fireflies {
            URL-bar show/hide. Order matters: later same-specificity rule
            wins, so dvh must come after vh. */
         max-height: 100vh !important;
-        max-height: 100dvh !important;
+        max-height: calc(var(--app-height) - var(--sheet-top)) !important;
         height: 100vh;
-        height: 100dvh;
+        height: calc(var(--app-height) - var(--sheet-top));
         border-radius: 14px 14px 0 0 !important;
         border: none !important;
         border-top: 1px solid var(--border) !important;
         box-shadow: none !important;
         padding: 6px !important;
-        padding-bottom: env(safe-area-inset-bottom, 6px) !important;
+        padding-bottom: var(--safe-bottom) !important;
         margin: 0 !important;
         overflow-y: auto;
         -webkit-overflow-scrolling: touch;
@@ -5536,7 +5554,7 @@ body.bg-pattern-ascii-fireflies {
            (against the flex-sized grid) as a definite height, so grid/flex
            children never filled. An explicit px height is unambiguous. */
         margin: 0 !important;
-        padding: 8px 10px calc(8px + env(safe-area-inset-bottom, 0px)) !important;
+        padding: 8px 10px calc(8px + var(--safe-bottom)) !important;
         background: var(--bg) !important;
         /* Flex column. JS (_fillSkillCardHeight) sets EXPLICIT px heights on
            the preview + <pre>; in a flex column an explicit-height item
@@ -5615,7 +5633,7 @@ body.bg-pattern-ascii-fireflies {
       /* Small bottom padding now that the load-more no longer steals space —
          the action bar sits low, just clearing the home-indicator safe area. */
       #doclib-modal [data-doclib-panel="documents"] .doclib-card.doclib-card-expanded .doclib-card-preview {
-        padding-bottom: calc(18px + env(safe-area-inset-bottom, 0px)) !important;
+        padding-bottom: calc(18px + var(--safe-bottom)) !important;
       }
       #doclib-modal .doclib-card.doclib-card-expanded .doclib-card-preview pre,
       #doclib-modal .doclib-card.doclib-card-expanded .doclib-card-preview .doclib-card-pdf-frame,
@@ -6127,6 +6145,7 @@ body.bg-pattern-ascii-fireflies {
       z-index:250;
       backdrop-filter:none;
       pointer-events:none;
+      padding: var(--safe-top) var(--safe-right) var(--safe-bottom) var(--safe-left);
     }
     /* Cookbook always sits above Gallery so the "Serve a model in
        Cookbook…" flow (and any other "open Cookbook from inside another
@@ -6160,6 +6179,17 @@ body.bg-pattern-ascii-fireflies {
            centered window glides instead of jumping when the nav toggles. */
         transition: left 0.25s ease, width 0.25s ease;
       }
+      /* A right-side nav reserves its width on the right instead */
+      body.hamburger-right :is(#calendar-modal, #gallery-modal, #tasks-modal, #memory-modal, #doclib-modal,
+        #compare-model-overlay, #research-overlay, #theme-modal, #settings-modal, #email-lib-modal) {
+        left: 0;
+      }
+      /* Windows never grow past the area between the nav and the safe areas */
+      :is(#calendar-modal, #gallery-modal, #tasks-modal, #memory-modal, #doclib-modal,
+        #compare-model-overlay, #research-overlay, #theme-modal, #settings-modal, #email-lib-modal)
+        > :is(.modal-content, .memory-modal-content, .settings-modal-content, .doclib-modal-content) {
+        max-width: calc(100vw - var(--safe-left) - var(--safe-right) - var(--icon-rail-w, 48px) - var(--sidebar-w, 0px));
+      }
     }
     .modal-content {
       background:var(--panel);
@@ -6689,8 +6719,8 @@ body.bg-pattern-ascii-fireflies {
     /* Agent indicator */
     #agent-indicator {
       position: fixed;
-      top: 20px;
-      right: 20px;
+      top: calc(20px + var(--safe-top));
+      right: calc(20px + var(--safe-right));
       background: var(--bg);
       color: var(--fg);
       border: 1px solid var(--border);
@@ -7016,7 +7046,7 @@ body.bg-pattern-ascii-fireflies {
     #compare-model-overlay .modal-content {
       display: flex;
       flex-direction: column;
-      max-height: min(720px, calc(100dvh - 48px));
+      max-height: min(720px, calc(var(--app-height) - 48px));
       overflow: hidden;
       min-height: 180px;
     }
@@ -7433,7 +7463,7 @@ body.bg-pattern-ascii-fireflies {
 
     #recording-indicator {
       position: fixed;
-      top: 10px;
+      top: calc(10px + var(--safe-top));
       left: 0;
       right: 0;
       background: rgba(0, 0, 0, 0.8);
diff --git a/static/css/02-compare.css b/static/css/02-compare.css
index ae04ba663..21fd7b555 100644
--- a/static/css/02-compare.css
+++ b/static/css/02-compare.css
@@ -172,9 +172,8 @@
            position:fixed; height:100% = the layout viewport, whose bottom sits
            UNDER Firefox Android's bottom URL bar — so flex-end parked the sheet
            (and its footer / Start button) beneath the bar. dvh excludes the bar
-           so the footer lands above it. Extra safe-area pad for iOS home bar. */
-        height: 100dvh;
-        padding-bottom: env(safe-area-inset-bottom, 0px);
+           so the footer lands above it. */
+        height: var(--app-height);
       }
       /* Confirm dialog stays centered, not a bottom sheet */
       #styled-confirm-overlay {
@@ -204,7 +203,7 @@
         border-radius: 14px 14px 0 0;
         border: none;
         border-top: 1px solid var(--border);
-        padding: 6px 12px 12px;
+        padding: 6px 12px calc(12px + var(--safe-bottom));
         animation: sheet-enter 0.2s ease-out forwards;
         overflow-y: hidden !important;
       }
@@ -252,12 +251,12 @@
       #email-lib-modal .modal-content,
       #doclib-modal .doclib-modal-content {
         max-height: 90vh !important;
-        max-height: 90dvh !important;
+        max-height: calc(var(--app-height) * 0.9) !important;
         height: auto !important;
         /* Reserve the iOS home-indicator / bottom-bar strip so an expanded
            skill card's footer (Delete / Edit / Run) isn't hidden under it.
            dvh already excludes the URL bar; this handles the safe area. */
-        padding-bottom: env(safe-area-inset-bottom, 0px) !important;
+        padding-bottom: var(--safe-bottom) !important;
       }
       /* Grab handle pill on the non-standard content classes too. Memory's
          desktop rule defines a radial-glow ::before later in the file —
@@ -305,7 +304,7 @@
            visible viewport on Chrome/Safari mobile (URL bar covered the
            action buttons row). */
         max-height: 90vh !important;
-        max-height: 90dvh !important;
+        max-height: calc(var(--app-height) * 0.9) !important;
         height: auto !important;
       }
       /* Anchor those modals to the top so the full height is usable */
@@ -314,8 +313,11 @@
       #email-lib-modal,
       #doclib-modal,
       #gallery-modal,
-      #tasks-modal {
-        padding-top: 0 !important;
+      #tasks-modal,
+      #memory-modal,
+      #settings-modal {
+        padding-top: var(--sheet-top) !important;
+        padding-bottom: 0 !important;
         align-items: stretch !important;
       }
       /* Deep Research already gets the swipe grab-handle pill from the
diff --git a/static/css/03-agent-chat.css b/static/css/03-agent-chat.css
index 0536fe3b6..0e8c95f91 100644
--- a/static/css/03-agent-chat.css
+++ b/static/css/03-agent-chat.css
@@ -410,8 +410,8 @@ button.hamburger {
 /* Agent indicator */
 #agent-indicator {
   position: fixed;
-  top: 20px;
-  right: 20px;
+  top: calc(20px + var(--safe-top));
+  right: calc(20px + var(--safe-right));
   background: var(--sidebar-bg, var(--panel));
   color: var(--fg);
   border: 1px solid var(--border);
@@ -894,7 +894,7 @@ button.hamburger {
 /* Recording indicator */
 #recording-indicator {
   position: fixed;
-  top: 10px;
+  top: calc(10px + var(--safe-top));
   left: 0;
   right: 0;
   background: rgba(0, 0, 0, 0.8);
diff --git a/static/css/05-documents.css b/static/css/05-documents.css
index b1bb54a22..c069c10cc 100644
--- a/static/css/05-documents.css
+++ b/static/css/05-documents.css
@@ -2666,11 +2666,13 @@ mark.doc-find-mark.current {
        render it as a narrow side pane ("sidebar") on a phone. */
     position: fixed !important;
     inset: 0 !important;
-    top: 0 !important; right: 0 !important; bottom: 0 !important; left: 0 !important;
+    top: var(--sheet-top) !important; right: 0 !important; bottom: 0 !important; left: 0 !important;
+    height: auto !important;
     max-width: 100% !important;
     width: 100% !important;
     flex: none !important;
     z-index: 170;
+    padding-bottom: var(--safe-bottom);
     /* Stroke the top edge so the rounded corners read as a curved sheet edge. */
     border: 1px solid var(--border);
     border-bottom: none;
diff --git a/static/css/06-admin-settings.css b/static/css/06-admin-settings.css
index 425b9ad6d..788470329 100644
--- a/static/css/06-admin-settings.css
+++ b/static/css/06-admin-settings.css
@@ -1181,8 +1181,8 @@ span[id$="-logo"] svg:not([width]) {
     opacity: 0;
     transform-origin: center center;
     position: absolute;
-    right: calc(16px + env(safe-area-inset-right, 0px));
-    bottom: calc(18px + env(safe-area-inset-bottom, 0px));
+    right: calc(16px + var(--safe-right));
+    bottom: calc(18px + var(--safe-bottom));
     height: var(--fab-size);
     min-width: var(--fab-size);
     padding: 0 20px 0 18px;
@@ -1298,17 +1298,23 @@ span[id$="-logo"] svg:not([width]) {
    instead of becoming a side panel. */
 #doclib-modal.doclib-fullscreen:not(.modal-right-docked) .doclib-modal-content {
   position: fixed !important;
-  top: 0 !important;
-  left: calc(var(--icon-rail-w, 48px) + var(--sidebar-w, 0px)) !important;
-  right: 0 !important;
-  bottom: 0 !important;
+  top: var(--safe-top) !important;
+  left: calc(var(--safe-left) + var(--icon-rail-w, 48px) + var(--sidebar-w, 0px)) !important;
+  right: var(--safe-right) !important;
+  bottom: var(--safe-bottom) !important;
   width: auto !important;
   max-width: none !important;
-  height: 100vh !important;
-  max-height: 100vh !important;
+  height: auto !important;
+  max-height: none !important;
   border-radius: 0 !important;
   transform: none !important;
 }
+@media (min-width: 769px) {
+  body.hamburger-right #doclib-modal.doclib-fullscreen:not(.modal-right-docked) .doclib-modal-content {
+    left: var(--safe-left) !important;
+    right: calc(var(--safe-right) + var(--icon-rail-w, 48px) + var(--sidebar-w, 0px)) !important;
+  }
+}
 #doclib-modal.doclib-fullscreen .modal-header,
 #doclib-modal.doclib-fullscreen .lib-tabs,
 #doclib-modal.modal-right-docked .modal-header,
@@ -1415,10 +1421,10 @@ span[id$="-logo"] svg:not([width]) {
    panes reserve room with margins so left + right docks can be active at the
    same time without skewing the entire body box. */
 body.right-dock-active {
-  padding-right: 0;
+  padding-right: var(--safe-right);
 }
 body.left-dock-active {
-  padding-left: 0;
+  padding-left: var(--safe-left);
 }
 body.left-dock-active:not(.email-doc-split-active) .chat-container {
   margin-left: var(--left-dock-w, 0px);
diff --git a/static/css/07-documents.css b/static/css/07-documents.css
index ea843c0ca..acfa56ae8 100644
--- a/static/css/07-documents.css
+++ b/static/css/07-documents.css
@@ -447,13 +447,11 @@
    edges and let the inner body absorb the remaining height. */
 body:not(.email-doc-split-active) .email-window-modal.email-window-fullscreen .modal-content {
   position: fixed !important;
-  inset: 0 !important;
-  left: 0 !important;
-  top: 0 !important;
-  width: 100vw !important;
-  max-width: 100vw !important;
-  height: 100vh !important;
-  max-height: 100vh !important;
+  inset: var(--safe-top) var(--safe-right) var(--safe-bottom) var(--safe-left) !important;
+  width: auto !important;
+  max-width: none !important;
+  height: auto !important;
+  max-height: none !important;
   border-radius: 0 !important;
   transform: none !important;
   display: flex !important;
@@ -472,17 +470,23 @@ body:not(.email-doc-split-active) .email-window-modal.email-window-fullscreen .e
    one of the two CSS vars is 0 at any given time, set by init.js). */
 body:not(.email-doc-split-active) #email-lib-modal.email-lib-fullscreen:not(.modal-right-docked) .modal-content {
   position: fixed !important;
-  top: 0 !important;
-  left: calc(var(--icon-rail-w, 48px) + var(--sidebar-w, 0px)) !important;
-  right: 0 !important;
-  bottom: 0 !important;
+  top: var(--safe-top) !important;
+  left: calc(var(--safe-left) + var(--icon-rail-w, 48px) + var(--sidebar-w, 0px)) !important;
+  right: var(--safe-right) !important;
+  bottom: var(--safe-bottom) !important;
   width: auto !important;
   max-width: none !important;
-  height: 100vh !important;
-  max-height: 100vh !important;
+  height: auto !important;
+  max-height: none !important;
   border-radius: 0 !important;
   transform: none !important;
 }
+@media (min-width: 769px) {
+  body.hamburger-right:not(.email-doc-split-active) #email-lib-modal.email-lib-fullscreen:not(.modal-right-docked) .modal-content {
+    left: var(--safe-left) !important;
+    right: calc(var(--safe-right) + var(--icon-rail-w, 48px) + var(--sidebar-w, 0px)) !important;
+  }
+}
 /* Mobile: the /email route adds .email-lib-fullscreen, but the desktop full-
    bleed rule above squares off the corners and offsets the email by the icon
    rail. On phones the email should be the normal bottom-sheet — full width,
@@ -490,12 +494,14 @@ body:not(.email-doc-split-active) #email-lib-modal.email-lib-fullscreen:not(.mod
    so it wins on mobile. */
 @media (max-width: 768px) {
   body:not(.email-doc-split-active) #email-lib-modal.email-lib-fullscreen:not(.modal-right-docked) .modal-content {
-    left: 0 !important;
-    right: 0 !important;
-    width: 100vw !important;
-    max-width: 100vw !important;
-    height: 100dvh !important;
-    max-height: 100dvh !important;
+    top: var(--sheet-top) !important;
+    left: var(--safe-left) !important;
+    right: var(--safe-right) !important;
+    bottom: 0 !important;
+    width: auto !important;
+    max-width: none !important;
+    height: auto !important;
+    max-height: none !important;
     border-radius: 14px 14px 0 0 !important;
     border-top: 1px solid var(--border) !important;
   }
diff --git a/static/css/13-image-editor.css b/static/css/13-image-editor.css
index 257e2805e..1fb216bc2 100644
--- a/static/css/13-image-editor.css
+++ b/static/css/13-image-editor.css
@@ -4502,7 +4502,7 @@ button .spinner-whirlpool {
     left: 8px !important;
     right: 8px !important;
     top: auto !important;
-    bottom: calc(env(safe-area-inset-bottom, 0px) + 8px) !important;
+    bottom: calc(var(--safe-bottom) + 8px) !important;
     width: auto !important;
     min-width: 0 !important;
     max-width: calc(100vw - 16px) !important;
diff --git a/static/css/14-email.css b/static/css/14-email.css
index 0ef60aca4..f42f6b6d1 100644
--- a/static/css/14-email.css
+++ b/static/css/14-email.css
@@ -4638,13 +4638,14 @@ body.notes-view .chat-container { flex: 1; min-width: 0; }
 @media (max-width: 768px) {
   body.notes-view .notes-pane {
     position: fixed;
-    inset: 0;
+    inset: var(--sheet-top) 0 0;
     max-width: 100%;
     width: 100% !important;
     /* Desktop sets height: min(80vh, 820px) which wins over inset:0's bottom:0
        and leaves a gap at the bottom of the viewport. Force full height here. */
-    height: 100dvh !important;
-    max-height: 100dvh !important;
+    height: calc(var(--app-height) - var(--sheet-top)) !important;
+    max-height: calc(var(--app-height) - var(--sheet-top)) !important;
+    padding-bottom: var(--safe-bottom);
     z-index: 170;
     /* Bottom-sheet treatment like the document editor: stroked, rounded top,
        slides up from the bottom. */
diff --git a/static/css/17-research.css b/static/css/17-research.css
index d2fa2b1d1..c4de5cb75 100644
--- a/static/css/17-research.css
+++ b/static/css/17-research.css
@@ -1439,7 +1439,7 @@ body.theme-frosted .modal {
   /* Bottom-sheet: 90dvh tall (a touch smaller than full-screen) anchored to the
      bottom, so there's a small gap at the top and it reads as a sheet. The body
      still scrolls within the bounded height. */
-  #research-overlay { align-items: flex-end !important; justify-content: stretch !important; }
+  #research-overlay { align-items: flex-end !important; justify-content: stretch !important; padding-bottom: 0 !important; }
   #research-pane {
     height: 90dvh !important;
     max-height: 90dvh !important;
@@ -1451,7 +1451,7 @@ body.theme-frosted .modal {
      browser's bottom toolbar / safe area and can always be scrolled into view
      (otherwise the form fits the viewport and there's no room to reach them). */
   #research-pane .research-pane-body {
-    padding-bottom: calc(env(safe-area-inset-bottom, 0px) + 40px) !important;
+    padding-bottom: calc(var(--safe-bottom) + 40px) !important;
     touch-action: pan-y;
     overscroll-behavior: contain;
   }
diff --git a/static/index.html b/static/index.html
index 5fc386a5c..89836d27a 100644
--- a/static/index.html
+++ b/static/index.html
@@ -16,6 +16,13 @@
   <link rel="apple-touch-icon" href="/static/icons/icon-192.png">
   <script nonce="{{CSP_NONCE}}">
   window._odysseusLoadTime = Date.now();
+  // Stops iOS focus-zoom on every field; iOS still allows pinch-zoom, other platforms would not.
+  (function(){
+    var ua = navigator.userAgent || '';
+    var isIOS = /iPad|iPhone|iPod/.test(ua) || (/Macintosh/.test(ua) && navigator.maxTouchPoints > 1);
+    var vp = document.querySelector('meta[name="viewport"]');
+    if (isIOS && vp) vp.setAttribute('content', vp.getAttribute('content') + ', maximum-scale=1');
+  })();
   (function(){
     try {
       var t = JSON.parse(localStorage.getItem('odysseus-theme'));
diff --git a/static/js/chat.js b/static/js/chat.js
index c42f5382b..7b0d70418 100644
--- a/static/js/chat.js
+++ b/static/js/chat.js
@@ -6929,13 +6929,6 @@ import { invalidateSettings } from './appConfig.js';
           }
         });
       }
-      // Smooth viewport resize when keyboard opens/closes
-      if (window.visualViewport) {
-        window.visualViewport.addEventListener('resize', () => {
-          document.documentElement.style.setProperty('--vh', window.visualViewport.height + 'px');
-        });
-        document.documentElement.style.setProperty('--vh', window.visualViewport.height + 'px');
-      }
     }
 
     // If the browser discarded and restored this tab, reload the current session
diff --git a/static/js/emailLibrary/index.js b/static/js/emailLibrary/index.js
index 82f76b0c5..2cba1edd6 100644
--- a/static/js/emailLibrary/index.js
+++ b/static/js/emailLibrary/index.js
@@ -22,7 +22,7 @@ import {
 } from './utils.js';
 import { state } from './state.js';
 import { getSettings } from '../appConfig.js';
-import { collapseSidebarToRail } from '../modalSnap.js';
+import { clampWindowLeft, collapseSidebarToRail, leftNavRight, safeInsetPx } from '../modalSnap.js';
 import { emailApiUrl } from '../emailShared.js';
 import {
   bindMenuDismiss,
@@ -823,7 +823,7 @@ function _readCssPx(name) {
 }
 
 function _emailSplitLeftEdge() {
-  return _readCssPx('--icon-rail-w') + _readCssPx('--sidebar-w');
+  return leftNavRight();
 }
 
 function _setEmailDocumentSplit(leftEdge, emailWidth) {
@@ -899,7 +899,8 @@ function _clearEmailDocumentSplit() {
 // rail. Used by the "try collapsing the sidebar first" path so we can decide
 // whether collapsing recovers enough room before minimizing email.
 function _emailSplitLeftEdgeIfSidebarCollapsed() {
-  return _readCssPx('--icon-rail-w');
+  const navOnRight = document.getElementById('sidebar')?.classList.contains('right-side');
+  return safeInsetPx('left') + (navOnRight ? 0 : _readCssPx('--icon-rail-w'));
 }
 
 function _hasDesktopRoomForEmailAndDocument(modal, opts = {}) {
@@ -2415,7 +2416,7 @@ export function openEmailLibrary(opts = {}) {
       requestAnimationFrame(() => {
         const w = content.offsetWidth;
         const refH = window.innerHeight * 0.85;
-        content.style.left = Math.max(20, (window.innerWidth - w) / 2) + 'px';
+        content.style.left = clampWindowLeft(Math.max(20, (window.innerWidth - w) / 2), w) + 'px';
         content.style.top = Math.max(20, (window.innerHeight - refH) / 2) + 'px';
         content.style.transform = 'none';
       });
diff --git a/static/js/emailLibrary/reader.js b/static/js/emailLibrary/reader.js
index b4765f870..6dc296185 100644
--- a/static/js/emailLibrary/reader.js
+++ b/static/js/emailLibrary/reader.js
@@ -11,6 +11,7 @@
 
 import spinnerModule from '../spinner.js';
 import * as Modals from '../modalManager.js';
+import { clampWindowLeft } from '../modalSnap.js';
 import { showToast } from '../ui.js?v=20260916largetoolscroll1';
 import { state } from './state.js';
 import { _esc, _extractName, _renderEmailSummaryError } from './utils.js';
@@ -428,7 +429,7 @@ export async function _openEmailWindow(em, folder) {
     requestAnimationFrame(() => {
       const w = content.offsetWidth, h = content.offsetHeight;
       const off = (_emailWindowSeq % 6) * 28;
-      content.style.left = Math.max(20, (window.innerWidth  - w) / 2 + off) + 'px';
+      content.style.left = clampWindowLeft(Math.max(20, (window.innerWidth  - w) / 2 + off), w) + 'px';
       content.style.top  = Math.max(20, (window.innerHeight - h) / 3 + off) + 'px';
     });
   }
diff --git a/static/js/features/notes/ui/panel.js b/static/js/features/notes/ui/panel.js
index 0a6031233..2265897c0 100644
--- a/static/js/features/notes/ui/panel.js
+++ b/static/js/features/notes/ui/panel.js
@@ -190,7 +190,7 @@ export function createPanel({
     // which left it as a side panel squeezing the chat).
     if (window.innerWidth <= 768) {
       pane.style.position = 'fixed';
-      pane.style.inset = '0';
+      pane.style.inset = 'var(--sheet-top) 0 0';
       pane.style.width = '100%';
       pane.style.maxWidth = '100%';
       pane.style.zIndex = '170';
diff --git a/static/js/init.js b/static/js/init.js
index e961a3d75..e554deaa7 100644
--- a/static/js/init.js
+++ b/static/js/init.js
@@ -369,6 +369,31 @@ document.addEventListener('DOMContentLoaded', markComposerUserEdited, { once: tr
 /* ---- Mobile viewport fix — keep chat visible when virtual keyboard opens ---- */
 {
   if (window.visualViewport) {
+    const root = document.documentElement;
+    // iOS overlays the keyboard without resizing the layout viewport and scrolls
+    // the page to reveal the field, leaving it shifted after the keyboard closes.
+    const _syncKeyboardViewport = function() {
+      const vv = window.visualViewport;
+      if (vv.scale > 1.01) return;
+      const keyboardOpen = window.innerHeight - vv.height > 120;
+      root.classList.toggle('keyboard-open', keyboardOpen);
+      if (keyboardOpen) root.style.setProperty('--keyboard-viewport-height', vv.height + 'px');
+      else root.style.removeProperty('--keyboard-viewport-height');
+      if (window.scrollY) window.scrollTo(0, 0);
+    };
+    // iOS fires visualViewport resize only once, mid-animation, and no focusin when
+    // the tapped field already had focus (e.g. the composer after a new chat)
+    const _syncThroughKeyboardAnimation = () => {
+      _syncKeyboardViewport();
+      for (const delay of [100, 300, 600, 1000]) setTimeout(_syncKeyboardViewport, delay);
+    };
+    _syncKeyboardViewport();
+    window.visualViewport.addEventListener('resize', _syncThroughKeyboardAnimation);
+    window.visualViewport.addEventListener('scroll', _syncKeyboardViewport);
+    document.addEventListener('focusin', _syncThroughKeyboardAnimation);
+    document.addEventListener('focusout', _syncThroughKeyboardAnimation);
+    window.addEventListener('scroll', () => { if (window.scrollY) window.scrollTo(0, 0); }, { passive: true });
+
     let _lastVVHeight = window.visualViewport.height;
     window.visualViewport.addEventListener('resize', function() {
       const vv = window.visualViewport;
diff --git a/static/js/modalSnap.js b/static/js/modalSnap.js
index 48b3922ac..d02bd8dd3 100644
--- a/static/js/modalSnap.js
+++ b/static/js/modalSnap.js
@@ -110,7 +110,7 @@ function _clampRightDockWidth(width) {
   const min = _minEdgeDockWidth();
   const navRight = _leftNavRight();
   const leftDockW = _activeDockWidth('left');
-  const maxByChat = window.innerWidth - navRight - leftDockW - MIN_CHAT_WIDTH;
+  const maxByChat = window.innerWidth - navRight - _rightNavInset() - leftDockW - MIN_CHAT_WIDTH;
   const max = Math.min(Math.round(window.innerWidth * 0.82), maxByChat);
   return _clampDockWidthToSpace(width, min, max);
 }
@@ -118,7 +118,7 @@ function _clampRightDockWidth(width) {
 function _clampLeftDockWidth(width, left = _leftNavRight()) {
   const min = _minEdgeDockWidth();
   const rightDockW = _activeDockWidth('right');
-  const available = Math.max(0, window.innerWidth - left - rightDockW);
+  const available = Math.max(0, window.innerWidth - left - _rightNavInset() - rightDockW);
   const max = Math.min(Math.round(available * 0.82), available - MIN_CHAT_WIDTH);
   return _clampDockWidthToSpace(width, min, max);
 }
@@ -170,13 +170,23 @@ function _shouldAutoCollapseSidebar(dockW) {
   return remaining < MIN_CHAT_WIDTH;
 }
 
+function _navOnRight() {
+  return !!document.getElementById('sidebar')?.classList.contains('right-side');
+}
+
+// Body padding carries the device safe-area insets (notch, Dynamic Island).
+function _bodyPaddingPx(side) {
+  return parseFloat(window.getComputedStyle(document.body)[side === 'left' ? 'paddingLeft' : 'paddingRight']) || 0;
+}
+
 // Right edge (px) of whatever left navigation is currently showing — the
 // expanded sidebar if visible, otherwise the icon rail. Used to anchor the
 // left dock so it always sits flush to the right of the nav.
 function _leftNavRight() {
   const sidebar = document.getElementById('sidebar');
   const rail = document.getElementById('icon-rail');
-  let x = 0;
+  let x = _bodyPaddingPx('left');
+  if (_navOnRight()) return x;
   if (sidebar && !sidebar.classList.contains('hidden')) {
     const r = sidebar.getBoundingClientRect();
     if (r.width) x = Math.max(x, r.right);
@@ -188,8 +198,36 @@ function _leftNavRight() {
   return x;
 }
 
+// Distance (px) from the viewport's right edge that a right-side nav and the
+// safe area occupy. The right dock sits flush to the left of it.
+function _rightNavInset() {
+  const sidebar = document.getElementById('sidebar');
+  const rail = document.getElementById('icon-rail');
+  let inset = _bodyPaddingPx('right');
+  if (!_navOnRight()) return inset;
+  if (sidebar && !sidebar.classList.contains('hidden')) {
+    const r = sidebar.getBoundingClientRect();
+    if (r.width) inset = Math.max(inset, window.innerWidth - r.left);
+  }
+  if (rail && window.getComputedStyle(rail).display !== 'none') {
+    const r = rail.getBoundingClientRect();
+    if (r.width) inset = Math.max(inset, window.innerWidth - r.left);
+  }
+  return inset;
+}
+
+export function leftNavRight() { return _leftNavRight(); }
+export function rightNavInset() { return _rightNavInset(); }
+export function safeInsetPx(side) { return _bodyPaddingPx(side); }
+
+// Keeps a floating window between the nav and the safe areas
+export function clampWindowLeft(left, width) {
+  const max = window.innerWidth - _rightNavInset() - width;
+  return Math.max(_leftNavRight(), Math.min(left, max));
+}
+
 function _clampEmailDocSplitWidth(width, left = _leftNavRight()) {
-  const available = Math.max(0, window.innerWidth - left);
+  const available = Math.max(0, window.innerWidth - left - _rightNavInset());
   if (!available) return 0;
   const compact = available < 760;
   const minEmail = compact ? 260 : 340;
@@ -235,7 +273,7 @@ function _applyEmailDocSplitGeometry(left, emailWidth) {
   if (!docPane || window.innerWidth <= 768) return;
   docPane.style.setProperty('position', 'fixed', 'important');
   docPane.style.setProperty('left', `${x}px`, 'important');
-  docPane.style.setProperty('right', 'var(--right-dock-w, 0px)', 'important');
+  docPane.style.setProperty('right', `calc(var(--right-dock-w, 0px) + ${_rightNavInset()}px)`, 'important');
   docPane.style.setProperty('top', '0px', 'important');
   docPane.style.setProperty('bottom', '0px', 'important');
   docPane.style.setProperty('width', 'auto', 'important');
@@ -497,7 +535,7 @@ function _applyDockInternal(modal, side, dockClass) {
   } else {
     w = _resolveRightDockWidth(modal, content);
     content.style.left = 'auto';
-    content.style.right = '0';
+    content.style.right = _rightNavInset() + 'px';
     content.style.width = w + 'px';
     content.style.maxWidth = w + 'px';
     document.body.classList.add('right-dock-active');
@@ -872,7 +910,7 @@ export function makeEdgeDockController(modal, side = 'right', dockClass) {
       w = _clampRightDockWidth(window.innerWidth - clientX);
       content._userDockWidth = w;
       content.style.left = 'auto';
-      content.style.right = '0';
+      content.style.right = _rightNavInset() + 'px';
       content.style.width = w + 'px';
       content.style.maxWidth = w + 'px';
       document.body.classList.add('right-dock-active');
diff --git a/static/js/sidebar-layout.js b/static/js/sidebar-layout.js
index 949ec532f..745c1e334 100644
--- a/static/js/sidebar-layout.js
+++ b/static/js/sidebar-layout.js
@@ -75,12 +75,15 @@ export function initSidebarLayout(Storage, opts) {
     _setSidebarModeClasses(mode);
   }
 
+  // Phones in landscape get the desktop layout, but the icon rail is too small to use there
+  const _phoneLandscape = window.matchMedia('(pointer: coarse) and (max-height: 500px)');
+
   function _syncRailSideCore() {
     const sidebar = document.getElementById('sidebar');
     if (!iconRail) return;
     const isRight = sidebar.classList.contains('right-side');
     const sidebarHidden = sidebar.classList.contains('hidden');
-    const railHidden = iconRail.classList.contains('rail-hidden');
+    const railHidden = iconRail.classList.contains('rail-hidden') || _phoneLandscape.matches;
     const isMobileMini = iconRail.classList.contains('mobile-mini');
     iconRail.classList.toggle('right-side', isRight);
     // On mobile mini mode, JS already set inline styles — don't touch
@@ -118,6 +121,7 @@ export function initSidebarLayout(Storage, opts) {
   // Set initial reference and expose globally
   _syncRailSideFn = _syncRailSideCore;
   window.syncRailSide = syncRailSide;
+  _phoneLandscape.addEventListener('change', () => syncRailSide());
 
   // Restore sidebar side preference
   if (Storage.get(Storage.KEYS.SIDEBAR_SIDE) === 'right') {
diff --git a/static/js/windowResize.js b/static/js/windowResize.js
index 6efdbfc2d..b71feac51 100644
--- a/static/js/windowResize.js
+++ b/static/js/windowResize.js
@@ -257,12 +257,19 @@ export function makeWindowResizable(content, options = {}) {
       try {
         const saved = JSON.parse(localStorage.getItem(storageKey) || 'null');
         if (saved && saved.w && saved.h) {
-          const w = Math.max(minW, Math.min(saved.w, window.innerWidth));
+          const bodyStyle = getComputedStyle(document.body);
+          const padLeft = parseFloat(bodyStyle.paddingLeft) || 0;
+          const padRight = parseFloat(bodyStyle.paddingRight) || 0;
+          const w = Math.max(minW, Math.min(saved.w, window.innerWidth - padLeft - padRight));
           const h = Math.max(minH, Math.min(saved.h, window.innerHeight));
           content.style.width = w + 'px';
           content.style.height = h + 'px';
           content.style.maxWidth = 'none';
           content.style.maxHeight = 'none';
+          const left = parseFloat(content.style.left);
+          if (Number.isFinite(left) && left + w > window.innerWidth - padRight) {
+            content.style.left = Math.max(padLeft, window.innerWidth - padRight - w) + 'px';
+          }
         }
       } catch (_) {}
     });

From 63e18a46c72b17e25fd716a49967dc2071e593ab Mon Sep 17 00:00:00 2001
From: PR #6029 Reviewer <reviewer@odysseus-review.local>
Date: Tue, 20 Oct 2026 01:01:35 +0100
Subject: [PATCH 30/53] test(css): update snapshots for iOS safe-area layout

---
 tests/css_snapshot/baseline.json | 90 ++++++++++++++++----------------
 1 file changed, 45 insertions(+), 45 deletions(-)

diff --git a/tests/css_snapshot/baseline.json b/tests/css_snapshot/baseline.json
index 41640ebeb..a144f9f53 100644
--- a/tests/css_snapshot/baseline.json
+++ b/tests/css_snapshot/baseline.json
@@ -1,10 +1,10 @@
 {
- "digest": "9868d50a542b7ad1",
+ "digest": "f7e60e4a567c46dc",
  "elements": {
   "app-shell": {
    "app-loader": "f04ad5bf6312d53f",
    "attach-strip": "a6474951e2481214",
-   "body": "58df17f0afa190b9",
+   "body": "4956f449e6a30e93",
    "chat-container": "b00a7c6be4e107b1",
    "chat-context-pill": "dd905b87245a9a71",
    "chat-history": "e65bdc51f4d1675f",
@@ -23,8 +23,8 @@
    "input-icon-btn": "3d1c773acd84a825",
    "memory-close-btn": "c3f4ba99098a6e4b",
    "memory-list": "da9a37a3de3c1a31",
-   "memory-modal": "5efc81537eab4526",
-   "memory-modal-content": "3cadc8581361436e",
+   "memory-modal": "e2f97b123dc9bc55",
+   "memory-modal-content": "5c5fe055c711e642",
    "memory-modal-header": "a8c822fe8c6d20e7",
    "memory-search-input": "8b0fbb33401750d4",
    "memory-toolbar-btn": "9f985efa7c896f90",
@@ -42,7 +42,7 @@
    "rail-new-chat": "f8f1c2f6be426ab9",
    "reasoning-effort-btn": "2a07cdd8ec2b4d26",
    "rename-session-modal": "9345624780009d14",
-   "root": "820190c144fda419",
+   "root": "a9f7ace2c1cefb24",
    "save-custom-preset": "443da70ef5fe9b88",
    "scroll-bottom-btn": "24602d72e2949991",
    "search-input": "53b94f3e5fdb384d",
@@ -54,7 +54,7 @@
    "settings-btn-sm": "c31bcb9bdfbae10d",
    "settings-fallbacks": "e339280590935fe3",
    "settings-logs-tab": "e470140373597143",
-   "settings-modal": "5efc81537eab4526",
+   "settings-modal": "e2f97b123dc9bc55",
    "settings-nav-search": "f4484b2980f2ccc5",
    "settings-row": "de568724268cec6e",
    "settings-select": "a96e8430b0ec6668",
@@ -69,7 +69,7 @@
    "theme-grid": "4d4b2aeb8952cc6f",
    "theme-io-btn": "859f222c79a8c721",
    "theme-modal": "0a65ca916656cdbb",
-   "theme-popup": "3aa65e6f313bbc65",
+   "theme-popup": "fb86cc5f81d0aaa6",
    "theme-tabs": "0cc4987f39876dce",
    "toast": "c60c6a60d4982005",
    "tool-indicator": "0dee45eaca8b703a",
@@ -83,7 +83,7 @@
    "#agent-indicator": "09a1b8d94b1487ee",
    "#agent-indicator.active": "67e2ad3fa48acd3b",
    "#compare-model-overlay .modal-body": "0b1ee357313551b9",
-   "#compare-model-overlay .modal-content": "56883147d181bd9c",
+   "#compare-model-overlay .modal-content": "9b2145292f439a88",
    "#cookbook-modal .cookbook-body": "20bd8a7268cee788",
    "#cookbook-modal .hwfit-cached-list.cookbook-serve-models-just-loaded > .doclib-card": "48f6787a3df3f19e",
    "#cookbook-modal .modal-content": "0c4e1e686df0990e",
@@ -101,7 +101,7 @@
    "#email-lib-modal .email-lib-sync-status": "6d1a0374a16cf7f4",
    "#email-lib-modal .email-reader-atts": "c5d68ecda3c14bb8",
    "#email-lib-modal .email-reader-header": "85afca11c8cbd38e",
-   "#email-lib-modal .modal-content": "d8b8fff38c613c95",
+   "#email-lib-modal .modal-content": "262753f287410717",
    "#email-lib-settings-btn": "9ae15bf04b6a22ce",
    "#email-unread-dot.sidebar-notif-dot": "c80f1e03592983b6",
    "#export-compact-btn": "7d0325a38e51134b",
@@ -686,44 +686,44 @@
  },
  "variants": {
   "app-shell": {
-   "desktop-dark-comfortable": "65b23a35b5a34126",
-   "desktop-dark-compact": "1bac3a0aa4467555",
-   "desktop-dark-spacious": "944583b1854fecbb",
-   "desktop-light-comfortable": "d279432f8c120b58",
-   "desktop-light-compact": "aa768c34ba3c7abc",
-   "desktop-light-spacious": "b74f53e95bfa1d82",
-   "laptop-dark-comfortable": "d98d16f3d60ed275",
-   "laptop-dark-compact": "c3eaf3c4278a0120",
-   "laptop-dark-spacious": "a085fe0f7d9eb66c",
-   "laptop-light-comfortable": "0d7c64f324bebe87",
-   "laptop-light-compact": "da50bf03b0f1be58",
-   "laptop-light-spacious": "a6789fd05a66bf5a",
-   "phone-dark-comfortable": "21b94f88da549eb5",
-   "phone-dark-compact": "b9aa7def2b85414e",
-   "phone-dark-spacious": "21b94f88da549eb5",
-   "phone-light-comfortable": "4a0cf45db775ea7d",
-   "phone-light-compact": "f7fbcb94d99c8730",
-   "phone-light-spacious": "4a0cf45db775ea7d",
-   "tablet-dark-comfortable": "e18256ce58398f11",
-   "tablet-dark-compact": "3cf3e52a10313d44",
-   "tablet-dark-spacious": "e18256ce58398f11",
-   "tablet-light-comfortable": "c2a45155c391f26c",
-   "tablet-light-compact": "9fa7dc03dd02b723",
-   "tablet-light-spacious": "c2a45155c391f26c"
+   "desktop-dark-comfortable": "0c9123117135e362",
+   "desktop-dark-compact": "c694f5d5118ac0e2",
+   "desktop-dark-spacious": "90a67613e8cfdf5d",
+   "desktop-light-comfortable": "17727a9945ccc77b",
+   "desktop-light-compact": "2a887c30d231e357",
+   "desktop-light-spacious": "94b4666734b87625",
+   "laptop-dark-comfortable": "26d334b139b653f2",
+   "laptop-dark-compact": "fea30bad6824357d",
+   "laptop-dark-spacious": "4fdb28deaaaec870",
+   "laptop-light-comfortable": "c7fc986a7e70aac8",
+   "laptop-light-compact": "147645431229ddff",
+   "laptop-light-spacious": "d513c285d30c8289",
+   "phone-dark-comfortable": "551761344bec8d09",
+   "phone-dark-compact": "293d66518c3ec994",
+   "phone-dark-spacious": "551761344bec8d09",
+   "phone-light-comfortable": "cb41acd3f9af3578",
+   "phone-light-compact": "dbef6e9e373e9c10",
+   "phone-light-spacious": "cb41acd3f9af3578",
+   "tablet-dark-comfortable": "0f682621b4ead393",
+   "tablet-dark-compact": "e6f3fece5e716a2c",
+   "tablet-dark-spacious": "0f682621b4ead393",
+   "tablet-light-comfortable": "6e398df9ca69c58b",
+   "tablet-light-compact": "dca75981c8675bfa",
+   "tablet-light-spacious": "6e398df9ca69c58b"
   },
   "bench": {
-   "desktop-dark-comfortable": "f9fa9d54db5ad45a",
-   "desktop-dark-compact": "7603a804cb2e23a2",
-   "desktop-dark-spacious": "b0c69306349fc078",
-   "desktop-light-comfortable": "d3e98c4c1e90686f",
-   "desktop-light-compact": "a04ae70088bc8b35",
-   "desktop-light-spacious": "4aa01a125f541429",
-   "laptop-dark-comfortable": "025e60ebe84e0f98",
-   "laptop-dark-compact": "53d6555bb7a6b5bb",
-   "laptop-dark-spacious": "c124d9ce1633d027",
-   "laptop-light-comfortable": "e8328c45f5127bb0",
-   "laptop-light-compact": "dc2da3534534c888",
-   "laptop-light-spacious": "abe5483724c987e0",
+   "desktop-dark-comfortable": "a9709cb47eec7544",
+   "desktop-dark-compact": "bfab96cb72fd6faf",
+   "desktop-dark-spacious": "25469178b443428a",
+   "desktop-light-comfortable": "2166794d643fae4c",
+   "desktop-light-compact": "81d8ab64407b1d9a",
+   "desktop-light-spacious": "d6d19f33476665af",
+   "laptop-dark-comfortable": "57169e64e1fb5324",
+   "laptop-dark-compact": "6ac903cd8a711bcf",
+   "laptop-dark-spacious": "a47535332e9c5de7",
+   "laptop-light-comfortable": "1e2b381de3556fac",
+   "laptop-light-compact": "6dbfb465121949c1",
+   "laptop-light-spacious": "1b8bfcd4bc4ed214",
    "phone-dark-comfortable": "67ca3c78e6b9495a",
    "phone-dark-compact": "ad6f3a9f5c8d81cd",
    "phone-dark-spacious": "1e6f66e56519ba5d",

From 8eaf742b431e3771b811bbae3dfbc63fe082defe Mon Sep 17 00:00:00 2001
From: Alexandre Teixeira <111787685+alteixeira20@users.noreply.github.com>
Date: Tue, 20 Oct 2026 10:14:55 +0100
Subject: [PATCH 31/53] fix(email): replace html2pdf with Print / save PDF and
 harden EML export

SAN-157 removed the html2pdf client library. The PDF export code added
in the original PR commit referenced the deleted library and would fail
at runtime. Replace the html2pdf-based _downloadSelectedEmailPdf with a
browser Print / save PDF workflow using a sandboxed iframe and
window.print(), matching the established pattern in document.js and
compare/index.js.

Changes:
- Replace _loadEmailHtml2Pdf and _downloadSelectedEmailPdf with
  _printSelectedEmails using a sandboxed iframe + contentWindow.print()
- Update menu label from 'PDF' to 'Print / save PDF'
- Add 512 MiB total size cap to /messages-download-bulk to prevent
  unbounded memory growth when exporting many large messages
- Update test assertions to verify the browser print pattern and
  confirm html2pdf is not referenced
- Add regression tests for size cap, selection count validation,
  non-numeric UID rejection, and partial batch failure accounting
---
 routes/email/email_routes.py             |  10 ++
 static/js/emailLibrary/index.js          | 163 +++++++++++------------
 static/js/emailLibrary/menus.js          |   2 +-
 tests/test_email_library_bulk_actions.py |  73 ++++++++--
 4 files changed, 157 insertions(+), 91 deletions(-)

diff --git a/routes/email/email_routes.py b/routes/email/email_routes.py
index 99b429f6e..c3d08f785 100644
--- a/routes/email/email_routes.py
+++ b/routes/email/email_routes.py
@@ -4216,6 +4216,10 @@ def setup_email_routes():
         used_names: set[str] = set()
         exported = 0
         skipped = 0
+        total_bytes = 0
+        # 512 MiB safety cap prevents unbounded memory growth when exporting
+        # many large messages.
+        max_total_bytes = 512 * 1024 * 1024
         single_export: tuple[str, bytes] | None = None
 
         def _email_filename(row: dict, uid: str) -> str:
@@ -4299,6 +4303,9 @@ def setup_email_routes():
                         suffix += 1
                     used_names.add(unique_name.lower())
                     message_bytes = _fixture_message_bytes(fixture, uid, folder)
+                    total_bytes += len(message_bytes)
+                    if total_bytes > max_total_bytes:
+                        raise HTTPException(status_code=413, detail="Export too large")
                     zf.writestr(f"{export_folder}/{unique_name}", message_bytes)
                     single_export = (unique_name, message_bytes)
                     exported += 1
@@ -4336,6 +4343,9 @@ def setup_email_routes():
                                     suffix += 1
                                 used_names.add(unique_name.lower())
                                 message_bytes = bytes(raw_message)
+                                total_bytes += len(message_bytes)
+                                if total_bytes > max_total_bytes:
+                                    raise HTTPException(status_code=413, detail="Export too large")
                                 zf.writestr(f"{export_folder}/{unique_name}", message_bytes)
                                 single_export = (unique_name, message_bytes)
                                 found.add(uid)
diff --git a/static/js/emailLibrary/index.js b/static/js/emailLibrary/index.js
index 7de542fe8..6dd013bf5 100644
--- a/static/js/emailLibrary/index.js
+++ b/static/js/emailLibrary/index.js
@@ -1122,29 +1122,9 @@ function _filenameFromContentDisposition(header) {
   return bare ? bare[1].trim() : '';
 }
 
-let _emailHtml2PdfReady = null;
-async function _loadEmailHtml2Pdf() {
-  if (window.html2pdf) return;
-  if (!_emailHtml2PdfReady) {
-    _emailHtml2PdfReady = new Promise((resolve, reject) => {
-      const script = document.createElement('script');
-      script.src = '/static/lib/html2pdf.bundle.min.js';
-      script.onload = resolve;
-      script.onerror = () => reject(new Error('Could not load PDF exporter'));
-      document.head.appendChild(script);
-    });
-  }
-  try {
-    await _emailHtml2PdfReady;
-  } catch (error) {
-    _emailHtml2PdfReady = null;
-    throw error;
-  }
-}
-
-async function _downloadSelectedEmailPdf(messages) {
-  if (messages.length > 20) throw new Error('PDF export supports up to 20 emails at a time');
-  await _loadEmailHtml2Pdf();
+async function _printSelectedEmails(messages) {
+  if (messages.length > 20) throw new Error('Print / save PDF supports up to 20 emails at a time');
+  if (typeof window.print !== 'function') throw new Error('Browser printing is unavailable');
 
   const loaded = new Array(messages.length);
   let nextIndex = 0;
@@ -1163,85 +1143,105 @@ async function _downloadSelectedEmailPdf(messages) {
   };
   await Promise.all(Array.from({ length: Math.min(4, messages.length) }, readWorker));
 
-  const page = document.createElement('div');
-  page.className = 'email-export-pdf';
-  page.style.cssText = 'width:794px;box-sizing:border-box;padding:38px;background:#fff;color:#171717;font:12px/1.55 Arial,Helvetica,sans-serif;';
-  const style = document.createElement('style');
-  style.textContent = `
-    .email-export-pdf-message { page-break-after: always; break-after: page; }
-    .email-export-pdf-message:last-child { page-break-after: auto; break-after: auto; }
-    .email-export-pdf-message h1 { margin: 0 0 18px; font-size: 20px; line-height: 1.3; overflow-wrap: anywhere; }
-    .email-export-pdf-fields { margin: 0 0 20px; padding: 0 0 14px; border-bottom: 1px solid #d8d8d8; }
-    .email-export-pdf-field { display: flex; gap: 10px; margin: 3px 0; overflow-wrap: anywhere; }
-    .email-export-pdf-label { width: 54px; flex: 0 0 54px; color: #666; }
-    .email-export-pdf-body { overflow-wrap: anywhere; word-break: break-word; }
-    .email-export-pdf-body img { max-width: 100%; }
-    .email-export-pdf-body a { color: #135f9b; text-decoration: underline; }
-    .email-export-pdf-body blockquote { margin-left: 12px; padding-left: 10px; border-left: 2px solid #ccc; color: #555; }
-    .email-export-pdf-body pre { white-space: pre-wrap; }
-  `;
-  page.appendChild(style);
-
-  const addField = (parent, label, value) => {
+  const addField = (doc, parent, label, value) => {
     if (!value) return;
-    const row = document.createElement('div');
+    const row = doc.createElement('div');
     row.className = 'email-export-pdf-field';
-    const labelEl = document.createElement('span');
+    const labelEl = doc.createElement('span');
     labelEl.className = 'email-export-pdf-label';
     labelEl.textContent = label;
-    const valueEl = document.createElement('span');
+    const valueEl = doc.createElement('span');
     valueEl.textContent = value;
     row.append(labelEl, valueEl);
     parent.appendChild(row);
   };
 
+  // Build sanitized HTML for the print frame -- scripts and event handlers
+  // cannot execute inside the sandboxed iframe.
+  const articles = [];
   for (const { message, data } of loaded) {
-    const article = document.createElement('article');
-    article.className = 'email-export-pdf-message';
     const subject = String(data.subject || message.subject || '(no subject)');
-    const title = document.createElement('h1');
-    title.textContent = subject;
-    article.appendChild(title);
-
-    const fields = document.createElement('div');
-    fields.className = 'email-export-pdf-fields';
     const from = data.from_name && data.from_address
       ? `${data.from_name} <${data.from_address}>`
       : data.from_name || data.from_address;
-    addField(fields, 'From', from);
-    addField(fields, 'To', data.to);
-    addField(fields, 'Cc', data.cc);
-    addField(fields, 'Date', data.date_display || data.date || message.date);
-    article.appendChild(fields);
 
-    const body = document.createElement('div');
-    body.className = 'email-export-pdf-body';
     const safeBody = new DOMParser().parseFromString(_safeRenderEmailBody(data), 'text/html');
     safeBody.querySelectorAll('img').forEach(img => {
       const placeholder = safeBody.createElement('span');
       placeholder.textContent = img.alt ? `[Image: ${img.alt}]` : '[Inline image omitted]';
       img.replaceWith(placeholder);
     });
-    body.innerHTML = safeBody.body.innerHTML;
-    body.querySelectorAll('details').forEach(detail => { detail.open = true; });
-    article.appendChild(body);
-    page.appendChild(article);
+    safeBody.querySelectorAll('details').forEach(detail => { detail.open = true; });
+    const bodyHtml = safeBody.body.innerHTML;
+
+    const fieldParts = [];
+    for (const [lbl, val] of [['From', from], ['To', data.to], ['Cc', data.cc], ['Date', data.date_display || data.date || message.date]]) {
+      if (!val) continue;
+      const esc = (s) => String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+      fieldParts.push(`<div class="email-export-pdf-field"><span class="email-export-pdf-label">${esc(lbl)}</span><span>${esc(val)}</span></div>`);
+    }
+
+    const esc = (s) => String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+    articles.push(
+      `<article class="email-export-pdf-message">` +
+      `<h1>${esc(subject)}</h1>` +
+      `<div class="email-export-pdf-fields">${fieldParts.join('')}</div>` +
+      `<div class="email-export-pdf-body">${bodyHtml}</div>` +
+      `</article>`
+    );
   }
 
+  const printCss = [
+    'html,body{background:#fff;color:#171717;font:12px/1.55 Arial,Helvetica,sans-serif;margin:0;padding:0}',
+    '.email-export-pdf{max-width:794px;margin:0 auto;padding:38px;box-sizing:border-box}',
+    '.email-export-pdf-message{page-break-after:always;break-after:page}',
+    '.email-export-pdf-message:last-child{page-break-after:auto;break-after:auto}',
+    '.email-export-pdf-message h1{margin:0 0 18px;font-size:20px;line-height:1.3;overflow-wrap:anywhere}',
+    '.email-export-pdf-fields{margin:0 0 20px;padding:0 0 14px;border-bottom:1px solid #d8d8d8}',
+    '.email-export-pdf-field{display:flex;gap:10px;margin:3px 0;overflow-wrap:anywhere}',
+    '.email-export-pdf-label{width:54px;flex:0 0 54px;color:#666}',
+    '.email-export-pdf-body{overflow-wrap:anywhere;word-break:break-word}',
+    '.email-export-pdf-body img{max-width:100%}',
+    '.email-export-pdf-body a{color:#135f9b;text-decoration:underline}',
+    '.email-export-pdf-body blockquote{margin-left:12px;padding-left:10px;border-left:2px solid #ccc;color:#555}',
+    '.email-export-pdf-body pre{white-space:pre-wrap}',
+    '@page{margin:10mm}',
+  ].join('\n');
+
   const safeBaseName = messages.length === 1
     ? String(loaded[0]?.data?.subject || messages[0]?.subject || 'email').replace(/[^\p{L}\p{N} ._-]+/gu, '_').trim().slice(0, 100) || 'email'
     : 'selected-emails';
+
+  // Use a sandboxed same-origin iframe following the established document.js
+  // Print / save PDF pattern (SAN-157). The browser opens a print dialog;
+  // saving, cancellation and pagination belong to the browser.
+  document.getElementById('email-browser-print-frame')?.remove();
+  const frame = document.createElement('iframe');
+  frame.id = 'email-browser-print-frame';
+  frame.title = 'Email print view';
+  frame.setAttribute('sandbox', 'allow-same-origin allow-modals');
+  frame.style.cssText = 'position:fixed;left:-10000px;top:0;width:800px;height:600px;border:0;';
+  document.body.appendChild(frame);
   try {
-    await window.html2pdf().set({
-      margin: 10,
-      filename: `${safeBaseName}.pdf`,
-      image: { type: 'jpeg', quality: 0.92 },
-      html2canvas: { scale: 1.6, useCORS: false, backgroundColor: '#fff' },
-      jsPDF: { unit: 'mm', format: 'a4', orientation: 'portrait' },
-      pagebreak: { mode: ['css', 'legacy'] },
-    }).from(page).save();
-  } finally {
-    page.remove();
+    const printDoc = frame.contentDocument;
+    printDoc.open();
+    printDoc.write('<!DOCTYPE html><html><head><meta charset="utf-8"></head><body></body></html>');
+    printDoc.close();
+    printDoc.title = safeBaseName;
+    const printStyle = printDoc.createElement('style');
+    printStyle.textContent = printCss;
+    printDoc.head.appendChild(printStyle);
+    const container = printDoc.createElement('div');
+    container.className = 'email-export-pdf';
+    container.innerHTML = articles.join('');
+    printDoc.body.appendChild(container);
+    await printDoc.fonts.ready;
+    frame.contentWindow.addEventListener('afterprint', () => frame.remove(), { once: true });
+    frame.contentWindow.focus();
+    frame.contentWindow.print();
+  } catch (error) {
+    frame.remove();
+    throw error;
   }
 }
 
@@ -1274,11 +1274,10 @@ async function _exportSelectedBundle(kind) {
     if (cancelBtn) cancelBtn.disabled = true;
     if (selectAll) selectAll.disabled = true;
     const isEmailExport = kind === 'emails';
-    const isPdfExport = kind === 'pdf';
-    if (countEl) countEl.textContent = `${isPdfExport ? 'Creating PDF' : 'Exporting'} ${isPdfExport ? 'from' : isEmailExport ? 'emails from' : 'attachments from'} ${messages.length}…`;
-    if (isPdfExport) {
-      await _downloadSelectedEmailPdf(messages);
-      showToast(`Exported ${messages.length} email${messages.length === 1 ? '' : 's'} as PDF`);
+    const isPrintExport = kind === 'print';
+    if (countEl) countEl.textContent = `${isPrintExport ? 'Preparing print' : 'Exporting'} ${isPrintExport ? 'for' : isEmailExport ? 'emails from' : 'attachments from'} ${messages.length}…`;
+    if (isPrintExport) {
+      await _printSelectedEmails(messages);
       return;
     }
     const res = await fetch(`${API_BASE}/api/email/${isEmailExport ? 'messages' : 'attachments'}-download-bulk`, {
@@ -1313,7 +1312,7 @@ async function _exportSelectedBundle(kind) {
         : `Exported attachments from ${messages.length} selected email${messages.length === 1 ? '' : 's'}`);
   } catch (err) {
     console.error(`Failed to export selected email ${kind}:`, err);
-    showToast(err?.message || (kind === 'emails' ? 'Failed to export emails' : 'Failed to export attachments'));
+    showToast(err?.message || (kind === 'emails' ? 'Failed to export emails' : kind === 'print' ? 'Could not open browser print' : 'Failed to export attachments'));
   } finally {
     if (busySpinner) busySpinner.destroy();
     if (actionsBtn) {
@@ -1334,7 +1333,7 @@ export async function _exportSelectedEmails() {
 }
 
 export async function _exportSelectedEmailPdf() {
-  return _exportSelectedBundle('pdf');
+  return _exportSelectedBundle('print');
 }
 
 export async function _exportSelectedAttachments() {
diff --git a/static/js/emailLibrary/menus.js b/static/js/emailLibrary/menus.js
index 3b03f4aba..57f7284e1 100644
--- a/static/js/emailLibrary/menus.js
+++ b/static/js/emailLibrary/menus.js
@@ -619,7 +619,7 @@ export function _showBulkActionsMenu(anchor) {
         dropdown.appendChild(divider);
         const options = [
           { label: 'Email file (.eml)', icon: _emailIco, action: _exportSelectedEmails },
-          { label: 'PDF', icon: _pdfIco, action: _exportSelectedEmailPdf },
+          { label: 'Print / save PDF', icon: _pdfIco, action: _exportSelectedEmailPdf },
         ];
         for (const option of options) {
           const child = document.createElement('div');
diff --git a/tests/test_email_library_bulk_actions.py b/tests/test_email_library_bulk_actions.py
index 64e3f46c1..99e77313e 100644
--- a/tests/test_email_library_bulk_actions.py
+++ b/tests/test_email_library_bulk_actions.py
@@ -70,17 +70,74 @@ def test_email_bulk_exports_messages_and_attachments_from_selected_context():
     assert '"X-Exported-Emails"' in backend
 
 
-def test_email_bulk_pdf_export_reads_without_marking_read_and_sanitizes_body():
+def test_email_print_pdf_export_reads_without_marking_read_and_sanitizes_body():
+    """Print / save PDF export must use the browser print dialog (SAN-157).
+
+    The removed html2pdf library must not be loaded or referenced. Instead
+    the export uses a sandboxed iframe and window.print(), matching the
+    established pattern in document.js.
+    """
     frontend = email_library_source()
-    pdf_src = _function_source("_downloadSelectedEmailPdf")
+    print_src = _function_source("_printSelectedEmails")
     menu_src = js_function_source("_showBulkActionsMenu", frontend)
 
-    assert "mark_seen=false&full=true" in pdf_src
-    assert "_safeRenderEmailBody(data)" in pdf_src
-    assert "new DOMParser()" in pdf_src
-    assert "window.html2pdf()" in pdf_src
-    assert "up to 20 emails" in pdf_src
-    assert "PDF" in menu_src
+    assert "mark_seen=false&full=true" in print_src
+    assert "_safeRenderEmailBody(data)" in print_src
+    assert "new DOMParser()" in print_src
+    assert "up to 20 emails" in print_src
+    assert "Print / save PDF" in menu_src
+
+    # SAN-157: must NOT reference the removed html2pdf library.
+    assert "html2pdf" not in print_src
+    assert "html2pdf" not in frontend
+
+    # Must use the browser print pattern with a sandboxed iframe.
+    assert "contentWindow.print()" in print_src
+    assert "sandbox" in print_src
+    assert "allow-same-origin" in print_src
+    assert "allow-modals" in print_src
+    assert "afterprint" in print_src
+    assert "email-browser-print-frame" in print_src
+
+
+def test_email_eml_export_bounds_total_size():
+    """The /messages-download-bulk endpoint must enforce a total size cap
+    to prevent unbounded memory growth when exporting many large messages."""
+    backend = _EMAIL_ROUTES.read_text(encoding="utf-8")
+
+    assert "max_total_bytes" in backend
+    assert "total_bytes" in backend
+    assert "Export too large" in backend
+    assert "status_code=413" in backend
+
+
+def test_email_eml_export_validates_selection_count():
+    """The /messages-download-bulk endpoint must reject oversized selections."""
+    backend = _EMAIL_ROUTES.read_text(encoding="utf-8")
+
+    assert 'len(messages) > 250' in backend
+    assert '"Too many emails selected"' in backend
+
+
+def test_email_eml_export_rejects_non_numeric_remote_uids():
+    """Non-numeric UIDs must not be passed to IMAP UID FETCH."""
+    backend = _EMAIL_ROUTES.read_text(encoding="utf-8")
+
+    # After fixture lookup fails, non-numeric UIDs are skipped.
+    assert 're.fullmatch(r"\\d+", uid)' in backend
+
+
+def test_email_eml_export_handles_partial_batch_failures():
+    """When an IMAP fetch batch returns partial results, exported/skipped
+    accounting must remain correct."""
+    backend = _EMAIL_ROUTES.read_text(encoding="utf-8")
+
+    # The skipped counter increments for UIDs not found in the batch response.
+    assert "skipped += len(batch) - len(found)" in backend
+    # Whole-connection failures count all rows as skipped.
+    assert "skipped += len(rows)" in backend
+    assert '"X-Exported-Emails"' in backend
+    assert '"X-Skipped-Emails"' in backend
 
 
 def test_fixture_tag_filter_supports_receipt_tag_flow():

From 550ac015eb88e5eec8c538cffa49fda55bfbe14b Mon Sep 17 00:00:00 2001
From: Alexandre Teixeira <111787685+alteixeira20@users.noreply.github.com>
Date: Tue, 20 Oct 2026 10:35:30 +0100
Subject: [PATCH 32/53] fix(email): enforce account ownership and correct
 partial failure accounting

- Validate account ownership with _assert_owns_account for every account_id
- Deduplicate items in selection to prevent duplicate files and skewed accounting
- Fix exception handling in IMAP batching to avoid double-counting on partial failures
- Re-raise HTTPException so 413 memory cap errors are not swallowed
- Remove unused addField helper in emailLibrary print exporter
- Add behavioral test suite covering empty/oversized validation, rfc822 export,
  zip export, partial failure/dedup, and cross-tenant account isolation
---
 routes/email/email_routes.py             |  19 ++-
 static/js/emailLibrary/index.js          |  13 --
 tests/test_email_library_bulk_actions.py | 168 ++++++++++++++++++++++-
 3 files changed, 183 insertions(+), 17 deletions(-)

diff --git a/routes/email/email_routes.py b/routes/email/email_routes.py
index c3d08f785..0af2d0a11 100644
--- a/routes/email/email_routes.py
+++ b/routes/email/email_routes.py
@@ -4281,6 +4281,7 @@ def setup_email_routes():
                     logger.debug("Skipping malformed fixture email attachment uid=%s", uid, exc_info=True)
             return msg.as_bytes(policy=email_policy.SMTP)
 
+        seen_items: set[tuple[str | None, str, str]] = set()
         remote_groups: dict[tuple[str | None, str], dict[str, tuple[str, dict]]] = {}
         with zipfile.ZipFile(zip_buf, "w", compression=zipfile.ZIP_DEFLATED) as zf:
             for row in messages:
@@ -4293,6 +4294,15 @@ def setup_email_routes():
                     continue
                 folder = str(row.get("folder") or "INBOX").strip() or "INBOX"
                 account_id = str(row.get("account_id") or row.get("account") or "").strip() or None
+                if account_id:
+                    _assert_owns_account(account_id, owner)
+
+                item_key = (account_id, folder, uid)
+                if item_key in seen_items:
+                    skipped += 1
+                    continue
+                seen_items.add(item_key)
+
                 fixture = _fixture_email_read(uid, folder, owner)
                 if fixture is not None and not fixture.get("error"):
                     filename = _email_filename(row, uid)
@@ -4319,6 +4329,7 @@ def setup_email_routes():
             # Fetch original RFC822 data in batches and store it byte-for-byte.
             for (account_id, folder), rows_by_uid in remote_groups.items():
                 rows = list(rows_by_uid.items())
+                remaining_rows = len(rows)
                 try:
                     with _imap(account_id, owner=owner) as conn:
                         conn.select(_q(folder), readonly=True)
@@ -4329,6 +4340,7 @@ def setup_email_routes():
                             status, msg_data = _imap_uid_fetch(conn, uid_set, "(UID RFC822)")
                             if status != "OK" or not msg_data:
                                 skipped += len(batch)
+                                remaining_rows -= len(batch)
                                 continue
                             found: set[str] = set()
                             for meta, raw_message in _group_uid_fetch_records(msg_data):
@@ -4351,9 +4363,12 @@ def setup_email_routes():
                                 found.add(uid)
                                 exported += 1
                             skipped += len(batch) - len(found)
+                            remaining_rows -= len(batch)
+                except HTTPException:
+                    raise
                 except Exception as exc:
-                    skipped += len(rows)
-                    logger.warning("Bulk email export skipped mailbox folder=%s account=%s count=%s: %s", folder, account_id, len(rows), exc)
+                    skipped += remaining_rows
+                    logger.warning("Bulk email export skipped mailbox folder=%s account=%s count=%s: %s", folder, account_id, remaining_rows, exc)
 
         if exported <= 0:
             raise HTTPException(status_code=404, detail="No selected emails could be exported")
diff --git a/static/js/emailLibrary/index.js b/static/js/emailLibrary/index.js
index 6dd013bf5..543fdfd55 100644
--- a/static/js/emailLibrary/index.js
+++ b/static/js/emailLibrary/index.js
@@ -1143,19 +1143,6 @@ async function _printSelectedEmails(messages) {
   };
   await Promise.all(Array.from({ length: Math.min(4, messages.length) }, readWorker));
 
-  const addField = (doc, parent, label, value) => {
-    if (!value) return;
-    const row = doc.createElement('div');
-    row.className = 'email-export-pdf-field';
-    const labelEl = doc.createElement('span');
-    labelEl.className = 'email-export-pdf-label';
-    labelEl.textContent = label;
-    const valueEl = doc.createElement('span');
-    valueEl.textContent = value;
-    row.append(labelEl, valueEl);
-    parent.appendChild(row);
-  };
-
   // Build sanitized HTML for the print frame -- scripts and event handlers
   // cannot execute inside the sandboxed iframe.
   const articles = [];
diff --git a/tests/test_email_library_bulk_actions.py b/tests/test_email_library_bulk_actions.py
index 99e77313e..6840b5916 100644
--- a/tests/test_email_library_bulk_actions.py
+++ b/tests/test_email_library_bulk_actions.py
@@ -134,12 +134,26 @@ def test_email_eml_export_handles_partial_batch_failures():
 
     # The skipped counter increments for UIDs not found in the batch response.
     assert "skipped += len(batch) - len(found)" in backend
-    # Whole-connection failures count all rows as skipped.
-    assert "skipped += len(rows)" in backend
+    # Whole-connection failures count remaining unprocessed rows as skipped.
+    assert "skipped += remaining_rows" in backend
     assert '"X-Exported-Emails"' in backend
     assert '"X-Skipped-Emails"' in backend
 
 
+def test_email_eml_export_enforces_account_ownership():
+    """The /messages-download-bulk endpoint must assert account ownership."""
+    backend = _EMAIL_ROUTES.read_text(encoding="utf-8")
+
+    assert "_assert_owns_account(account_id, owner)" in backend
+
+
+def test_email_eml_export_deduplicates_selection():
+    """Duplicate items in selection must be skipped to avoid duplicate files."""
+    backend = _EMAIL_ROUTES.read_text(encoding="utf-8")
+
+    assert "seen_items" in backend
+
+
 def test_fixture_tag_filter_supports_receipt_tag_flow():
     backend = _EMAIL_ROUTES.read_text(encoding="utf-8")
 
@@ -247,3 +261,153 @@ def test_email_compose_can_attach_gallery_images():
     assert "GalleryImage" in backend
     assert "_gallery_image_path(img.filename)" in backend
     assert "_stage_compose_file" in backend
+
+
+class _MockImapConn:
+    def __init__(self, messages_by_uid: dict[str, bytes] | None = None, fetch_exc: Exception | None = None):
+        self.messages = messages_by_uid or {}
+        self.fetch_exc = fetch_exc
+
+    def select(self, folder, readonly=True):
+        return "OK", [b"1"]
+
+    def uid(self, command, *args):
+        if command == "FETCH":
+            if self.fetch_exc is not None:
+                raise self.fetch_exc
+            uid_set_b = args[0]
+            uid_set = uid_set_b.decode() if isinstance(uid_set_b, bytes) else str(uid_set_b)
+            uids = [u.strip() for u in uid_set.split(",") if u.strip()]
+            res = []
+            for u in uids:
+                if u in self.messages:
+                    meta = f"1 (UID {u} RFC822 {{{len(self.messages[u])}}}".encode()
+                    res.append((meta, self.messages[u]))
+                    res.append(b")")
+            return "OK", res
+        return "NO", []
+
+
+def _create_test_app(monkeypatch, mailbox: _MockImapConn | None = None, assert_owns_fn=None):
+    from contextlib import contextmanager
+    from fastapi import FastAPI
+    from fastapi.testclient import TestClient
+    from routes.email import email_routes as routes
+
+    conn = mailbox or _MockImapConn()
+
+    @contextmanager
+    def mock_imap(account_id=None, owner=""):
+        yield conn
+
+    monkeypatch.setattr(routes, "_start_poller", lambda: None)
+    monkeypatch.setattr(routes, "_POOL_HOOKS", {})
+    monkeypatch.setattr(routes, "_imap", mock_imap)
+    if assert_owns_fn:
+        monkeypatch.setattr(routes, "_assert_owns_account", assert_owns_fn)
+
+    app = FastAPI()
+    app.include_router(routes.setup_email_routes())
+    app.dependency_overrides[routes.require_owner] = lambda: "test-user"
+    return TestClient(app)
+
+
+def test_messages_download_bulk_validates_empty_and_oversized_payload(monkeypatch):
+    client = _create_test_app(monkeypatch)
+
+    res_empty = client.post("/api/email/messages-download-bulk", json={"messages": []})
+    assert res_empty.status_code == 400
+    assert "No emails selected" in res_empty.text
+
+    oversized = [{"uid": str(i)} for i in range(251)]
+    res_over = client.post("/api/email/messages-download-bulk", json={"messages": oversized})
+    assert res_over.status_code == 400
+    assert "Too many emails selected" in res_over.text
+
+
+def test_messages_download_bulk_single_message_eml_export(monkeypatch):
+    raw_rfc822 = b"From: sender@example.com\r\nTo: test-user\r\nSubject: Report\r\n\r\nReport content"
+    mailbox = _MockImapConn({"101": raw_rfc822})
+    client = _create_test_app(monkeypatch, mailbox=mailbox)
+
+    res = client.post("/api/email/messages-download-bulk", json={
+        "messages": [{"uid": "101", "subject": "Quarterly Report", "date": "2026-10-20"}]
+    })
+
+    assert res.status_code == 200
+    assert res.headers["content-type"].startswith("message/rfc822")
+    assert res.headers["x-exported-emails"] == "1"
+    assert res.headers["x-skipped-emails"] == "0"
+    assert "email.eml" in res.headers["content-disposition"]
+    assert res.content == raw_rfc822
+
+
+def test_messages_download_bulk_multi_message_zip_export(monkeypatch):
+    import io
+    import zipfile
+
+    msg1 = b"From: a@example.com\r\nSubject: First\r\n\r\nOne"
+    msg2 = b"From: b@example.com\r\nSubject: Second\r\n\r\nTwo"
+    mailbox = _MockImapConn({"101": msg1, "102": msg2})
+    client = _create_test_app(monkeypatch, mailbox=mailbox)
+
+    res = client.post("/api/email/messages-download-bulk", json={
+        "messages": [
+            {"uid": "101", "subject": "First Msg", "date": "2026-10-18"},
+            {"uid": "102", "subject": "Second Msg", "date": "2026-10-19"},
+        ]
+    })
+
+    assert res.status_code == 200
+    assert res.headers["content-type"] == "application/zip"
+    assert res.headers["x-exported-emails"] == "2"
+    assert res.headers["x-skipped-emails"] == "0"
+
+    zf = zipfile.ZipFile(io.BytesIO(res.content))
+    namelist = zf.namelist()
+    assert len(namelist) == 2
+    assert any("101.eml" in name for name in namelist)
+    assert any("102.eml" in name for name in namelist)
+
+
+def test_messages_download_bulk_partial_failure_and_duplicate_dedup(monkeypatch):
+    import io
+    import zipfile
+
+    msg1 = b"From: a@example.com\r\nSubject: Exists\r\n\r\nExists body"
+    # UID 101 exists, UID 999 does not exist in mailbox
+    mailbox = _MockImapConn({"101": msg1})
+    client = _create_test_app(monkeypatch, mailbox=mailbox)
+
+    res = client.post("/api/email/messages-download-bulk", json={
+        "messages": [
+            {"uid": "101", "subject": "Exists"},
+            {"uid": "999", "subject": "Missing"},
+            {"uid": "101", "subject": "Duplicate"}, # duplicate must be skipped
+        ]
+    })
+
+    assert res.status_code == 200
+    assert res.headers["content-type"] == "application/zip"
+    assert res.headers["x-exported-emails"] == "1"
+    assert res.headers["x-skipped-emails"] == "2"
+
+    zf = zipfile.ZipFile(io.BytesIO(res.content))
+    assert len(zf.namelist()) == 1
+
+
+def test_messages_download_bulk_enforces_account_ownership_guard(monkeypatch):
+    from fastapi import HTTPException
+
+    def mock_assert_owns(account_id, owner):
+        if account_id == "other-tenant-acct":
+            raise HTTPException(status_code=404, detail="Account not found")
+
+    client = _create_test_app(monkeypatch, assert_owns_fn=mock_assert_owns)
+
+    res = client.post("/api/email/messages-download-bulk", json={
+        "messages": [{"uid": "101", "account_id": "other-tenant-acct"}]
+    })
+
+    assert res.status_code == 404
+    assert "Account not found" in res.text

From c7d1555eea99c388d60a0d0c3ae9a12d4e63ba43 Mon Sep 17 00:00:00 2001
From: Alexandre Teixeira <111787685+alteixeira20@users.noreply.github.com>
Date: Tue, 20 Oct 2026 11:38:12 +0100
Subject: [PATCH 33/53] fix(email): resolve memory safety, print rendering, and
 accounting defects

- Use SpooledTemporaryFile with 32 MiB spool threshold for export ZIP archives
- Add IMAP size preflight via (UID RFC822.SIZE) and cap batch payload at 10 MiB
- Enforce 64 MiB per-message ceiling and fail closed with 500 on corrupted ZIP
- Stream spooled archive chunks with generator cleanup on disconnect/cancellation
- Bypass ZIP creation for single raw EML message downloads
- Memoize account ownership checks per request to eliminate N+1 database queries
- Replace interactive image placeholders in print view with clean text notices
- Strip interactive buttons, icons, and image actions from print document
- Implement partial print success policy printing loaded items and reporting omitted
- Harden print iframe lifecycle with window afterprint listener and fallback timer
- Correct mid-batch exception accounting so exported plus skipped equals requested
- Add executable behavioral tests for limits, mid-batch accounting, and memoization
---
 routes/email/email_routes.py             | 338 ++++++++++++++++-------
 static/js/emailLibrary/index.js          |  90 ++++--
 tests/test_email_library_bulk_actions.py | 158 +++++++++++
 3 files changed, 469 insertions(+), 117 deletions(-)

diff --git a/routes/email/email_routes.py b/routes/email/email_routes.py
index 0af2d0a11..541a7189f 100644
--- a/routes/email/email_routes.py
+++ b/routes/email/email_routes.py
@@ -25,6 +25,7 @@ import json
 import re
 import html
 import io
+import tempfile
 import zipfile
 from urllib.parse import parse_qs, quote, unquote, urlparse
 from html.parser import HTMLParser as _HTMLParser
@@ -642,6 +643,11 @@ def _uid_from_fetch_meta(meta_b: bytes) -> str:
     return m.group(1).decode() if m else ""
 
 
+def _size_from_fetch_meta(meta_b: bytes) -> int | None:
+    m = re.search(rb"\bRFC822\.SIZE\s+(\d+)\b", meta_b, re.IGNORECASE)
+    return int(m.group(1)) if m else None
+
+
 def _parse_list_unsubscribe_header(value: str | None) -> list[dict]:
     """Parse RFC List-Unsubscribe entries into safe reviewable actions.
 
@@ -4212,15 +4218,16 @@ def setup_email_routes():
             date_span = selected_dates[0] if len(selected_dates) == 1 else f"{selected_dates[0]} - {selected_dates[-1]}"
         export_folder = f"emails-{category}" + (f" ({date_span})" if date_span else "")
 
-        zip_buf = io.BytesIO()
+        # 512 MiB safety cap prevents unbounded memory growth when exporting
+        # many large messages.
+        max_total_bytes = 512 * 1024 * 1024
+        max_message_bytes = 64 * 1024 * 1024
+        spool_threshold_bytes = 32 * 1024 * 1024
         used_names: set[str] = set()
         exported = 0
         skipped = 0
         total_bytes = 0
-        # 512 MiB safety cap prevents unbounded memory growth when exporting
-        # many large messages.
-        max_total_bytes = 512 * 1024 * 1024
-        single_export: tuple[str, bytes] | None = None
+        validated_accounts: set[str] = set()
 
         def _email_filename(row: dict, uid: str) -> str:
             date = str(row.get("date") or "").strip()
@@ -4281,120 +4288,249 @@ def setup_email_routes():
                     logger.debug("Skipping malformed fixture email attachment uid=%s", uid, exc_info=True)
             return msg.as_bytes(policy=email_policy.SMTP)
 
-        seen_items: set[tuple[str | None, str, str]] = set()
-        remote_groups: dict[tuple[str | None, str], dict[str, tuple[str, dict]]] = {}
-        with zipfile.ZipFile(zip_buf, "w", compression=zipfile.ZIP_DEFLATED) as zf:
-            for row in messages:
-                if not isinstance(row, dict):
-                    skipped += 1
-                    continue
-                uid = str(row.get("uid") or "").strip()
-                if not uid:
-                    skipped += 1
-                    continue
-                folder = str(row.get("folder") or "INBOX").strip() or "INBOX"
-                account_id = str(row.get("account_id") or row.get("account") or "").strip() or None
-                if account_id:
-                    _assert_owns_account(account_id, owner)
+        # Optimization: single message exports return raw .eml directly without ZIP compression.
+        if len(messages) == 1:
+            row = messages[0]
+            if not isinstance(row, dict):
+                raise HTTPException(status_code=404, detail="No selected emails could be exported")
+            uid = str(row.get("uid") or "").strip()
+            if not uid:
+                raise HTTPException(status_code=404, detail="No selected emails could be exported")
+            folder = str(row.get("folder") or "INBOX").strip() or "INBOX"
+            account_id = str(row.get("account_id") or row.get("account") or "").strip() or None
+            if account_id:
+                _assert_owns_account(account_id, owner)
 
-                item_key = (account_id, folder, uid)
-                if item_key in seen_items:
-                    skipped += 1
-                    continue
-                seen_items.add(item_key)
+            filename = _email_filename(row, uid)
+            message_bytes: bytes | None = None
 
-                fixture = _fixture_email_read(uid, folder, owner)
-                if fixture is not None and not fixture.get("error"):
-                    filename = _email_filename(row, uid)
-                    unique_name = filename
-                    suffix = 2
-                    while unique_name.lower() in used_names:
-                        unique_name = f"{Path(filename).stem}-{suffix}.eml"
-                        suffix += 1
-                    used_names.add(unique_name.lower())
-                    message_bytes = _fixture_message_bytes(fixture, uid, folder)
-                    total_bytes += len(message_bytes)
-                    if total_bytes > max_total_bytes:
-                        raise HTTPException(status_code=413, detail="Export too large")
-                    zf.writestr(f"{export_folder}/{unique_name}", message_bytes)
-                    single_export = (unique_name, message_bytes)
-                    exported += 1
-                    continue
-                if not re.fullmatch(r"\d+", uid):
-                    skipped += 1
-                    continue
-                group = remote_groups.setdefault((account_id, folder), {})
-                group.setdefault(uid, (_email_filename(row, uid), row))
-
-            # Fetch original RFC822 data in batches and store it byte-for-byte.
-            for (account_id, folder), rows_by_uid in remote_groups.items():
-                rows = list(rows_by_uid.items())
-                remaining_rows = len(rows)
+            fixture = _fixture_email_read(uid, folder, owner)
+            if fixture is not None and not fixture.get("error"):
+                message_bytes = _fixture_message_bytes(fixture, uid, folder)
+            elif re.fullmatch(r"\d+", uid):
                 try:
                     with _imap(account_id, owner=owner) as conn:
                         conn.select(_q(folder), readonly=True)
-                        for batch_start in range(0, len(rows), 20):
-                            batch = rows[batch_start:batch_start + 20]
-                            wanted = {uid: filename for uid, (filename, _row) in batch}
-                            uid_set = ",".join(wanted).encode()
-                            status, msg_data = _imap_uid_fetch(conn, uid_set, "(UID RFC822)")
-                            if status != "OK" or not msg_data:
-                                skipped += len(batch)
-                                remaining_rows -= len(batch)
-                                continue
-                            found: set[str] = set()
-                            for meta, raw_message in _group_uid_fetch_records(msg_data):
-                                uid = _uid_from_fetch_meta(meta)
-                                if uid not in wanted or not raw_message:
-                                    continue
-                                filename = wanted[uid]
-                                unique_name = filename
-                                suffix = 2
-                                while unique_name.lower() in used_names:
-                                    unique_name = f"{Path(filename).stem}-{suffix}.eml"
-                                    suffix += 1
-                                used_names.add(unique_name.lower())
-                                message_bytes = bytes(raw_message)
-                                total_bytes += len(message_bytes)
-                                if total_bytes > max_total_bytes:
-                                    raise HTTPException(status_code=413, detail="Export too large")
-                                zf.writestr(f"{export_folder}/{unique_name}", message_bytes)
-                                single_export = (unique_name, message_bytes)
-                                found.add(uid)
-                                exported += 1
-                            skipped += len(batch) - len(found)
-                            remaining_rows -= len(batch)
+                        uid_b = uid.encode()
+                        try:
+                            st_sz, sz_data = _imap_uid_fetch(conn, uid_b, "(UID RFC822.SIZE)")
+                            if st_sz == "OK" and sz_data:
+                                for item in sz_data:
+                                    meta = item[0] if isinstance(item, tuple) else item
+                                    if isinstance(meta, bytes):
+                                        sz = _size_from_fetch_meta(meta)
+                                        if sz is not None and (sz > max_message_bytes or sz > max_total_bytes):
+                                            raise HTTPException(status_code=413, detail="Export too large")
+                        except HTTPException:
+                            raise
+                        except Exception as sz_err:
+                            logger.debug("Single message size preflight error: %s", sz_err)
+
+                        st, msg_data = _imap_uid_fetch(conn, uid_b, "(UID RFC822)")
+                        if st == "OK" and msg_data:
+                            for meta, raw in _group_uid_fetch_records(msg_data):
+                                if _uid_from_fetch_meta(meta) == uid and raw:
+                                    message_bytes = bytes(raw)
+                                    break
                 except HTTPException:
                     raise
                 except Exception as exc:
-                    skipped += remaining_rows
-                    logger.warning("Bulk email export skipped mailbox folder=%s account=%s count=%s: %s", folder, account_id, remaining_rows, exc)
+                    logger.warning("Single email export failed for uid=%s folder=%s: %s", uid, folder, exc)
+
+            if not message_bytes:
+                raise HTTPException(status_code=404, detail="No selected emails could be exported")
+
+            if len(message_bytes) > max_message_bytes or len(message_bytes) > max_total_bytes:
+                raise HTTPException(status_code=413, detail="Export too large")
 
-        if exported <= 0:
-            raise HTTPException(status_code=404, detail="No selected emails could be exported")
-        if len(messages) == 1 and single_export:
-            filename, message_bytes = single_export
             return StreamingResponse(
                 io.BytesIO(message_bytes),
                 media_type="message/rfc822",
                 headers={
                     "Content-Disposition": f"attachment; filename=\"email.eml\"; filename*=UTF-8''{quote(filename, safe='')}",
                     "X-Exported-Emails": "1",
+                    "X-Skipped-Emails": "0",
+                },
+            )
+
+        seen_items: set[tuple[str | None, str, str]] = set()
+        remote_groups: dict[tuple[str | None, str], dict[str, tuple[str, dict]]] = {}
+        spooled_file = tempfile.SpooledTemporaryFile(max_size=spool_threshold_bytes, mode="w+b")
+        response_started = False
+        try:
+            with zipfile.ZipFile(spooled_file, "w", compression=zipfile.ZIP_DEFLATED) as zf:
+                for row in messages:
+                    if not isinstance(row, dict):
+                        skipped += 1
+                        continue
+                    uid = str(row.get("uid") or "").strip()
+                    if not uid:
+                        skipped += 1
+                        continue
+                    folder = str(row.get("folder") or "INBOX").strip() or "INBOX"
+                    account_id = str(row.get("account_id") or row.get("account") or "").strip() or None
+                    if account_id and account_id not in validated_accounts:
+                        _assert_owns_account(account_id, owner)
+                        validated_accounts.add(account_id)
+
+                    item_key = (account_id, folder, uid)
+                    if item_key in seen_items:
+                        skipped += 1
+                        continue
+                    seen_items.add(item_key)
+
+                    fixture = _fixture_email_read(uid, folder, owner)
+                    if fixture is not None and not fixture.get("error"):
+                        filename = _email_filename(row, uid)
+                        unique_name = filename
+                        suffix = 2
+                        while unique_name.lower() in used_names:
+                            unique_name = f"{Path(filename).stem}-{suffix}.eml"
+                            suffix += 1
+                        used_names.add(unique_name.lower())
+                        message_bytes = _fixture_message_bytes(fixture, uid, folder)
+                        if len(message_bytes) > max_message_bytes:
+                            raise HTTPException(status_code=413, detail="Export too large")
+                        total_bytes += len(message_bytes)
+                        if total_bytes > max_total_bytes:
+                            raise HTTPException(status_code=413, detail="Export too large")
+                        try:
+                            zf.writestr(f"{export_folder}/{unique_name}", message_bytes)
+                        except Exception as zip_err:
+                            logger.error("ZIP entry write failed for fixture: %s", zip_err)
+                            raise HTTPException(status_code=500, detail="Failed to create export archive")
+                        exported += 1
+                        continue
+                    if not re.fullmatch(r"\d+", uid):
+                        skipped += 1
+                        continue
+                    group = remote_groups.setdefault((account_id, folder), {})
+                    group.setdefault(uid, (_email_filename(row, uid), row))
+
+                # Fetch original RFC822 data in batches and store it byte-for-byte.
+                for (account_id, folder), rows_by_uid in remote_groups.items():
+                    rows = list(rows_by_uid.items())
+                    remaining_rows = len(rows)
+                    try:
+                        with _imap(account_id, owner=owner) as conn:
+                            conn.select(_q(folder), readonly=True)
+
+                            # Size preflight query to catch oversized exports early and bound batch sizes.
+                            uid_set_all = ",".join(uid for uid, _ in rows).encode()
+                            size_by_uid: dict[str, int] = {}
+                            try:
+                                st_sz, sz_data = _imap_uid_fetch(conn, uid_set_all, "(UID RFC822.SIZE)")
+                                if st_sz == "OK" and sz_data:
+                                    for item in sz_data:
+                                        meta = item[0] if isinstance(item, tuple) else item
+                                        if isinstance(meta, bytes):
+                                            u = _uid_from_fetch_meta(meta)
+                                            s = _size_from_fetch_meta(meta)
+                                            if u and s is not None:
+                                                size_by_uid[u] = s
+                            except Exception as sz_err:
+                                logger.debug("IMAP size preflight query failed or unsupported: %s", sz_err)
+
+                            if size_by_uid:
+                                for u, s in size_by_uid.items():
+                                    if s > max_message_bytes:
+                                        raise HTTPException(status_code=413, detail="Export too large")
+                                if total_bytes + sum(size_by_uid.values()) > max_total_bytes:
+                                    raise HTTPException(status_code=413, detail="Export too large")
+
+                            # Form batches with at most 20 messages and capped at 10 MiB payload.
+                            batches: list[list[tuple[str, tuple[str, dict]]]] = []
+                            cur_batch: list[tuple[str, tuple[str, dict]]] = []
+                            cur_batch_bytes = 0
+                            max_batch_bytes = 10 * 1024 * 1024
+                            for item in rows:
+                                uid_val = item[0]
+                                sz = size_by_uid.get(uid_val, 0)
+                                if cur_batch and (
+                                    len(cur_batch) >= 20 or
+                                    (sz > 0 and cur_batch_bytes + sz > max_batch_bytes)
+                                ):
+                                    batches.append(cur_batch)
+                                    cur_batch = []
+                                    cur_batch_bytes = 0
+                                cur_batch.append(item)
+                                cur_batch_bytes += sz
+                            if cur_batch:
+                                batches.append(cur_batch)
+
+                            for batch in batches:
+                                wanted = {uid: filename for uid, (filename, _row) in batch}
+                                uid_set = ",".join(wanted).encode()
+                                status, msg_data = _imap_uid_fetch(conn, uid_set, "(UID RFC822)")
+                                if status != "OK" or not msg_data:
+                                    skipped += len(batch)
+                                    remaining_rows -= len(batch)
+                                    continue
+                                found: set[str] = set()
+                                for meta, raw_message in _group_uid_fetch_records(msg_data):
+                                    uid = _uid_from_fetch_meta(meta)
+                                    if uid not in wanted or not raw_message:
+                                        continue
+                                    filename = wanted[uid]
+                                    unique_name = filename
+                                    suffix = 2
+                                    while unique_name.lower() in used_names:
+                                        unique_name = f"{Path(filename).stem}-{suffix}.eml"
+                                        suffix += 1
+                                    used_names.add(unique_name.lower())
+                                    message_bytes = bytes(raw_message)
+                                    if len(message_bytes) > max_message_bytes:
+                                        raise HTTPException(status_code=413, detail="Export too large")
+                                    total_bytes += len(message_bytes)
+                                    if total_bytes > max_total_bytes:
+                                        raise HTTPException(status_code=413, detail="Export too large")
+                                    try:
+                                        zf.writestr(f"{export_folder}/{unique_name}", message_bytes)
+                                    except Exception as zip_err:
+                                        logger.error("ZIP entry write failed for remote message: %s", zip_err)
+                                        raise HTTPException(status_code=500, detail="Failed to create export archive")
+                                    found.add(uid)
+                                    exported += 1
+                                    remaining_rows -= 1
+                                missing = len(batch) - len(found)
+                                skipped += len(batch) - len(found)
+                                remaining_rows -= missing
+                    except HTTPException:
+                        raise
+                    except Exception as exc:
+                        skipped += remaining_rows
+                        logger.warning("Bulk email export skipped mailbox folder=%s account=%s count=%s: %s", folder, account_id, remaining_rows, exc)
+
+            if exported <= 0:
+                raise HTTPException(status_code=404, detail="No selected emails could be exported")
+
+            spooled_file.seek(0)
+            zip_name = _safe_attachment_zip_name(f"{export_folder}.zip", "selected-emails.zip")
+            logger.info("Bulk email export complete owner=%s selected=%s exported=%s skipped=%s", owner, len(messages), exported, skipped)
+
+            def _iter_spooled(f, chunk_size=64 * 1024):
+                try:
+                    while True:
+                        chunk = f.read(chunk_size)
+                        if not chunk:
+                            break
+                        yield chunk
+                finally:
+                    f.close()
+
+            response_started = True
+            return StreamingResponse(
+                _iter_spooled(spooled_file),
+                media_type="application/zip",
+                headers={
+                    "Content-Disposition": f'attachment; filename="{zip_name}"',
+                    "X-Exported-Emails": str(exported),
                     "X-Skipped-Emails": str(skipped),
                 },
             )
-        zip_buf.seek(0)
-        zip_name = _safe_attachment_zip_name(f"{export_folder}.zip", "selected-emails.zip")
-        logger.info("Bulk email export complete owner=%s selected=%s exported=%s skipped=%s", owner, len(messages), exported, skipped)
-        return StreamingResponse(
-            zip_buf,
-            media_type="application/zip",
-            headers={
-                "Content-Disposition": f'attachment; filename="{zip_name}"',
-                "X-Exported-Emails": str(exported),
-                "X-Skipped-Emails": str(skipped),
-            },
-        )
+        finally:
+            if not response_started:
+                spooled_file.close()
 
     @router.get("/inline-image/{uid}")
     async def inline_image(
diff --git a/static/js/emailLibrary/index.js b/static/js/emailLibrary/index.js
index 543fdfd55..cc08f2d0c 100644
--- a/static/js/emailLibrary/index.js
+++ b/static/js/emailLibrary/index.js
@@ -1132,32 +1132,70 @@ async function _printSelectedEmails(messages) {
     while (nextIndex < messages.length) {
       const index = nextIndex++;
       const message = messages[index];
-      const account = message.account_id ? `&account_id=${encodeURIComponent(message.account_id)}` : '';
-      const url = `${API_BASE}/api/email/read/${encodeURIComponent(message.uid)}?folder=${encodeURIComponent(message.folder || 'INBOX')}${account}&mark_seen=false&full=true`;
-      const response = await fetch(url, { credentials: 'same-origin' });
-      if (!response.ok) throw new Error(`Could not load "${message.subject || 'email'}" (HTTP ${response.status})`);
-      const data = await response.json();
-      if (data?.error) throw new Error(data.error);
-      loaded[index] = { message, data };
+      try {
+        const account = message.account_id ? `&account_id=${encodeURIComponent(message.account_id)}` : '';
+        const url = `${API_BASE}/api/email/read/${encodeURIComponent(message.uid)}?folder=${encodeURIComponent(message.folder || 'INBOX')}${account}&mark_seen=false&full=true`;
+        const response = await fetch(url, { credentials: 'same-origin' });
+        if (!response.ok) throw new Error(`HTTP ${response.status}`);
+        const data = await response.json();
+        if (data?.error) throw new Error(data.error);
+        loaded[index] = { ok: true, message, data };
+      } catch (err) {
+        loaded[index] = { ok: false, message, error: err?.message || 'Failed to load' };
+      }
     }
   };
   await Promise.all(Array.from({ length: Math.min(4, messages.length) }, readWorker));
 
+  const successful = loaded.filter(item => item && item.ok);
+  const omitted = loaded.filter(item => !item || !item.ok);
+
+  if (successful.length === 0) {
+    throw new Error('None of the selected emails could be loaded for printing');
+  }
+
   // Build sanitized HTML for the print frame -- scripts and event handlers
   // cannot execute inside the sandboxed iframe.
   const articles = [];
-  for (const { message, data } of loaded) {
+  if (omitted.length > 0) {
+    const count = omitted.length;
+    articles.push(
+      `<div class="email-export-pdf-omitted-notice">Note: ${count} selected email${count === 1 ? ' was' : 's were'} unavailable and omitted from this print.</div>`
+    );
+  }
+
+  for (const { message, data } of successful) {
     const subject = String(data.subject || message.subject || '(no subject)');
     const from = data.from_name && data.from_address
       ? `${data.from_name} <${data.from_address}>`
       : data.from_name || data.from_address;
 
     const safeBody = new DOMParser().parseFromString(_safeRenderEmailBody(data), 'text/html');
-    safeBody.querySelectorAll('img').forEach(img => {
-      const placeholder = safeBody.createElement('span');
-      placeholder.textContent = img.alt ? `[Image: ${img.alt}]` : '[Inline image omitted]';
-      img.replaceWith(placeholder);
+
+    // Replace interactive image placeholder components with clean print-safe notices
+    safeBody.querySelectorAll('.email-inline-image-placeholder').forEach(ph => {
+      const title = ph.querySelector('.email-inline-image-title')?.textContent?.trim();
+      const ariaLabel = ph.getAttribute('aria-label')?.trim();
+      const label = title || ariaLabel || '';
+      const isGeneric = !label || /^inline image$|^remote image$|^image unavailable$|^image$/i.test(label);
+      const span = safeBody.createElement('span');
+      span.className = 'email-export-image-notice';
+      span.textContent = isGeneric ? '[Image omitted]' : `[Image: ${label}]`;
+      ph.replaceWith(span);
     });
+
+    // Replace any remaining raw <img> tags
+    safeBody.querySelectorAll('img').forEach(img => {
+      const alt = (img.getAttribute('alt') || img.getAttribute('title') || '').trim();
+      const span = safeBody.createElement('span');
+      span.className = 'email-export-image-notice';
+      span.textContent = alt ? `[Image: ${alt}]` : '[Image omitted]';
+      img.replaceWith(span);
+    });
+
+    // Strip interactive controls (buttons, inputs, actions) from the print document
+    safeBody.querySelectorAll('button, input, select, textarea, .email-inline-image-actions, .email-inline-image-btn').forEach(el => el.remove());
+
     safeBody.querySelectorAll('details').forEach(detail => { detail.open = true; });
     const bodyHtml = safeBody.body.innerHTML;
 
@@ -1192,11 +1230,14 @@ async function _printSelectedEmails(messages) {
     '.email-export-pdf-body a{color:#135f9b;text-decoration:underline}',
     '.email-export-pdf-body blockquote{margin-left:12px;padding-left:10px;border-left:2px solid #ccc;color:#555}',
     '.email-export-pdf-body pre{white-space:pre-wrap}',
+    '.email-inline-image-placeholder,.email-inline-image-actions,.email-inline-image-btn{display:none !important}',
+    '.email-export-image-notice{display:inline-block;color:#666;font-style:italic;font-size:11px;margin:4px 0}',
+    '.email-export-pdf-omitted-notice{margin:0 0 16px;padding:8px 12px;background:#f8f9fa;border:1px solid #e2e8f0;border-radius:4px;font-size:11px;color:#64748b}',
     '@page{margin:10mm}',
   ].join('\n');
 
-  const safeBaseName = messages.length === 1
-    ? String(loaded[0]?.data?.subject || messages[0]?.subject || 'email').replace(/[^\p{L}\p{N} ._-]+/gu, '_').trim().slice(0, 100) || 'email'
+  const safeBaseName = successful.length === 1
+    ? String(successful[0]?.data?.subject || successful[0]?.message?.subject || 'email').replace(/[^\p{L}\p{N} ._-]+/gu, '_').trim().slice(0, 100) || 'email'
     : 'selected-emails';
 
   // Use a sandboxed same-origin iframe following the established document.js
@@ -1209,6 +1250,17 @@ async function _printSelectedEmails(messages) {
   frame.setAttribute('sandbox', 'allow-same-origin allow-modals');
   frame.style.cssText = 'position:fixed;left:-10000px;top:0;width:800px;height:600px;border:0;';
   document.body.appendChild(frame);
+
+  let cleanedUp = false;
+  const cleanupFrame = () => {
+    if (cleanedUp) return;
+    cleanedUp = true;
+    try {
+      frame.remove();
+    } catch (_) {}
+    window.removeEventListener('afterprint', cleanupFrame);
+  };
+
   try {
     const printDoc = frame.contentDocument;
     printDoc.open();
@@ -1223,11 +1275,17 @@ async function _printSelectedEmails(messages) {
     container.innerHTML = articles.join('');
     printDoc.body.appendChild(container);
     await printDoc.fonts.ready;
-    frame.contentWindow.addEventListener('afterprint', () => frame.remove(), { once: true });
+    frame.contentWindow?.addEventListener('afterprint', cleanupFrame, { once: true });
+    window.addEventListener('afterprint', cleanupFrame, { once: true });
+    setTimeout(cleanupFrame, 60000);
     frame.contentWindow.focus();
     frame.contentWindow.print();
+    if (omitted.length > 0) {
+      const msg = `Printed ${successful.length} email${successful.length === 1 ? '' : 's'}; ${omitted.length} unavailable`;
+      showToast(msg);
+    }
   } catch (error) {
-    frame.remove();
+    cleanupFrame();
     throw error;
   }
 }
diff --git a/tests/test_email_library_bulk_actions.py b/tests/test_email_library_bulk_actions.py
index 6840b5916..1d8464270 100644
--- a/tests/test_email_library_bulk_actions.py
+++ b/tests/test_email_library_bulk_actions.py
@@ -411,3 +411,161 @@ def test_messages_download_bulk_enforces_account_ownership_guard(monkeypatch):
 
     assert res.status_code == 404
     assert "Account not found" in res.text
+
+
+def test_messages_download_bulk_mid_batch_failure_accounting(monkeypatch):
+    """When an exception occurs mid-batch after partial progress, already-exported
+    records must not be double-counted as skipped."""
+    class MidBatchFailImap:
+        def select(self, folder, readonly=True):
+            return "OK", [b"1"]
+        def uid(self, command, *args):
+            records = []
+            for i in range(1, 5):
+                records.append((f"{i} (UID {i} RFC822 {{{10}}}".encode(), f"Subject: Msg {i}\r\n\r\nBody {i}".encode()))
+            class BadRecord:
+                def __bytes__(self):
+                    raise RuntimeError("Corrupt memory buffer")
+            records.append((b"5 (UID 5 RFC822 {10}", BadRecord()))
+            return "OK", records
+
+    from contextlib import contextmanager
+    from fastapi import FastAPI
+    from fastapi.testclient import TestClient
+    from routes.email import email_routes as routes
+
+    @contextmanager
+    def mock_imap(account_id=None, owner=""):
+        yield MidBatchFailImap()
+
+    monkeypatch.setattr(routes, "_start_poller", lambda: None)
+    monkeypatch.setattr(routes, "_POOL_HOOKS", {})
+    monkeypatch.setattr(routes, "_imap", mock_imap)
+
+    app = FastAPI()
+    app.include_router(routes.setup_email_routes())
+    app.dependency_overrides[routes.require_owner] = lambda: "test-user"
+    client = TestClient(app)
+
+    rows = [{"uid": str(i)} for i in range(1, 11)]
+    res = client.post("/api/email/messages-download-bulk", json={"messages": rows})
+    assert res.status_code == 200
+    exp = int(res.headers.get("x-exported-emails"))
+    skp = int(res.headers.get("x-skipped-emails"))
+    assert exp == 4
+    assert skp == 6
+    assert exp + skp == 10
+
+
+def test_messages_download_bulk_size_cap_413_boundary(monkeypatch):
+    """Cumulative export size exceeding max_total_bytes returns HTTP 413."""
+    class LargeMessageImap:
+        def select(self, folder, readonly=True):
+            return "OK", [b"1"]
+        def uid(self, command, *args):
+            raw_uids = args[0] if isinstance(args[0], str) else args[0].decode()
+            if "(UID RFC822.SIZE)" in str(args):
+                records = []
+                for u in raw_uids.split(","):
+                    records.append(f"{u} (UID {u} RFC822.SIZE 10485760)".encode())
+                return "OK", records
+            records = []
+            big_chunk = b"X" * (10 * 1024 * 1024)
+            for u in raw_uids.split(","):
+                records.append((f"{u} (UID {u} RFC822".encode(), big_chunk))
+            return "OK", records
+
+    from contextlib import contextmanager
+    from fastapi import FastAPI
+    from fastapi.testclient import TestClient
+    from routes.email import email_routes as routes
+
+    @contextmanager
+    def mock_imap(account_id=None, owner=""):
+        yield LargeMessageImap()
+
+    monkeypatch.setattr(routes, "_start_poller", lambda: None)
+    monkeypatch.setattr(routes, "_POOL_HOOKS", {})
+    monkeypatch.setattr(routes, "_imap", mock_imap)
+
+    app = FastAPI()
+    app.include_router(routes.setup_email_routes())
+    app.dependency_overrides[routes.require_owner] = lambda: "test-user"
+    client = TestClient(app)
+
+    # 52 messages of 10 MB = 520 MB > 512 MiB limit
+    payload_52 = [{"uid": str(i + 1), "subject": f"Big {i}"} for i in range(52)]
+    res = client.post("/api/email/messages-download-bulk", json={"messages": payload_52})
+    assert res.status_code == 413
+    assert res.json()["detail"] == "Export too large"
+
+
+def test_messages_download_bulk_per_message_limit_413(monkeypatch):
+    """A single oversized message (>64 MiB) triggers HTTP 413."""
+    class HugeSingleMsgImap:
+        def select(self, folder, readonly=True):
+            return "OK", [b"1"]
+        def uid(self, command, *args):
+            return "OK", [b"1 (UID 101 RFC822.SIZE 73400320)"]
+
+    from contextlib import contextmanager
+    from fastapi import FastAPI
+    from fastapi.testclient import TestClient
+    from routes.email import email_routes as routes
+
+    @contextmanager
+    def mock_imap(account_id=None, owner=""):
+        yield HugeSingleMsgImap()
+
+    monkeypatch.setattr(routes, "_start_poller", lambda: None)
+    monkeypatch.setattr(routes, "_POOL_HOOKS", {})
+    monkeypatch.setattr(routes, "_imap", mock_imap)
+
+    app = FastAPI()
+    app.include_router(routes.setup_email_routes())
+    app.dependency_overrides[routes.require_owner] = lambda: "test-user"
+    client = TestClient(app)
+
+    res = client.post("/api/email/messages-download-bulk", json={
+        "messages": [{"uid": "101", "subject": "Huge Email"}]
+    })
+    assert res.status_code == 413
+    assert res.json()["detail"] == "Export too large"
+
+
+def test_messages_download_bulk_account_ownership_memoization(monkeypatch):
+    """Account ownership validation is memoized per distinct account_id to eliminate N+1 DB queries."""
+    owns_calls = []
+    def counting_assert_owns(account_id, owner):
+        owns_calls.append(account_id)
+
+    raw_rfc822 = b"From: sender@example.com\r\nSubject: Test\r\n\r\nBody"
+    msgs = {str(i): raw_rfc822 for i in range(1, 26)}
+    mailbox = _MockImapConn(msgs)
+    client = _create_test_app(monkeypatch, mailbox=mailbox, assert_owns_fn=counting_assert_owns)
+
+    # 25 messages all referencing the same account_id
+    payload = [{"uid": str(i), "account_id": "acc-shared"} for i in range(1, 26)]
+    res = client.post("/api/email/messages-download-bulk", json={"messages": payload})
+    assert res.status_code == 200
+    assert len(owns_calls) == 1
+
+
+def test_messages_download_bulk_corrupt_zip_fails_closed(monkeypatch):
+    """If ZIP construction fails (e.g. disk error), fail closed with 500 instead of returning corrupt archive."""
+    import zipfile
+    raw_rfc822 = b"From: sender@example.com\r\nSubject: Test\r\n\r\nBody"
+    mailbox = _MockImapConn({"101": raw_rfc822, "102": raw_rfc822})
+
+    orig_writestr = zipfile.ZipFile.writestr
+    def failing_writestr(self, zinfo_or_arcname, data=None, *args, **kwargs):
+        raise OSError("Disk write failed: No space left on device")
+
+    monkeypatch.setattr(zipfile.ZipFile, "writestr", failing_writestr)
+    client = _create_test_app(monkeypatch, mailbox=mailbox)
+
+    res = client.post("/api/email/messages-download-bulk", json={
+        "messages": [{"uid": "101"}, {"uid": "102"}]
+    })
+    assert res.status_code == 500
+    assert "Failed to create export archive" in res.json()["detail"]

From 75df766358c2e6e04368c6416dbc8c5d1a500412 Mon Sep 17 00:00:00 2001
From: Alexandre Teixeira <111787685+alteixeira20@users.noreply.github.com>
Date: Tue, 20 Oct 2026 14:09:47 +0100
Subject: [PATCH 34/53] fix(email): harden RFC822.SIZE preflight validation and
 ignore duplicate IMAP records

- Require valid RFC822.SIZE preflight metadata for every message before body FETCH
- Fail safely with HTTP 502 without body fetching on NO, malformed, or inconsistent sizes
- Distinguish missing mail (HTTP 404) from bad size preflight (HTTP 502)
- Discard duplicate IMAP response records for already-processed UIDs in batch loop
- Correct print notification toast to "Prepared N emails for printing; M unavailable"
- Add dedicated Playwright browser regression test script to repository test suite
- Add request-level tests for preflight NO, empty, partial, malformed, and duplicates
---
 routes/email/email_routes.py               | 124 ++++++--
 static/js/emailLibrary/index.js            |   2 +-
 tests/test_email_library_bulk_actions.py   | 206 ++++++++++++-
 tests/test_email_library_print_browser.cjs | 331 +++++++++++++++++++++
 4 files changed, 633 insertions(+), 30 deletions(-)
 create mode 100644 tests/test_email_library_print_browser.cjs

diff --git a/routes/email/email_routes.py b/routes/email/email_routes.py
index 541a7189f..8443df3c1 100644
--- a/routes/email/email_routes.py
+++ b/routes/email/email_routes.py
@@ -4312,20 +4312,37 @@ def setup_email_routes():
                     with _imap(account_id, owner=owner) as conn:
                         conn.select(_q(folder), readonly=True)
                         uid_b = uid.encode()
+                        st_sz, sz_data = None, None
                         try:
                             st_sz, sz_data = _imap_uid_fetch(conn, uid_b, "(UID RFC822.SIZE)")
-                            if st_sz == "OK" and sz_data:
-                                for item in sz_data:
-                                    meta = item[0] if isinstance(item, tuple) else item
-                                    if isinstance(meta, bytes):
-                                        sz = _size_from_fetch_meta(meta)
-                                        if sz is not None and (sz > max_message_bytes or sz > max_total_bytes):
-                                            raise HTTPException(status_code=413, detail="Export too large")
-                        except HTTPException:
-                            raise
                         except Exception as sz_err:
-                            logger.debug("Single message size preflight error: %s", sz_err)
+                            logger.warning("Single message size preflight query error for uid=%s: %s", uid, sz_err)
 
+                        if st_sz != "OK":
+                            logger.warning("Single message size preflight status=%s for uid=%s", st_sz, uid)
+                            raise HTTPException(status_code=502, detail="Unable to verify email size safety")
+
+                        if not sz_data:
+                            # Message does not exist in mailbox (missing mail)
+                            raise HTTPException(status_code=404, detail="No selected emails could be exported")
+
+                        sz: int | None = None
+                        for item in sz_data:
+                            meta = item[0] if isinstance(item, tuple) else item
+                            if isinstance(meta, bytes):
+                                u = _uid_from_fetch_meta(meta)
+                                if u == uid:
+                                    sz = _size_from_fetch_meta(meta)
+                                    break
+
+                        if sz is None or sz < 0:
+                            logger.warning("Single message size preflight returned invalid/malformed size for uid=%s", uid)
+                            raise HTTPException(status_code=502, detail="Invalid email size metadata from server")
+
+                        if sz > max_message_bytes or sz > max_total_bytes:
+                            raise HTTPException(status_code=413, detail="Export too large")
+
+                        # Preflight size safety established; perform RFC822 fetch.
                         st, msg_data = _imap_uid_fetch(conn, uid_b, "(UID RFC822)")
                         if st == "OK" and msg_data:
                             for meta, raw in _group_uid_fetch_records(msg_data):
@@ -4407,7 +4424,14 @@ def setup_email_routes():
                     group = remote_groups.setdefault((account_id, folder), {})
                     group.setdefault(uid, (_email_filename(row, uid), row))
 
+                preflight_error: HTTPException | None = None
+
                 # Fetch original RFC822 data in batches and store it byte-for-byte.
+                # Note on IMAP memory-safety: Python's standard imaplib buffers socket responses into
+                # memory before returning literals to application code. Preflight verification ensures
+                # we do not intentionally fetch messages exceeding limits, but an untrusted or non-compliant
+                # IMAP server sending unexpectedly large literals cannot be bounded at the transport level
+                # without custom socket streaming. Post-fetch checks guard application-level storage.
                 for (account_id, folder), rows_by_uid in remote_groups.items():
                     rows = list(rows_by_uid.items())
                     remaining_rows = len(rows)
@@ -4417,26 +4441,64 @@ def setup_email_routes():
 
                             # Size preflight query to catch oversized exports early and bound batch sizes.
                             uid_set_all = ",".join(uid for uid, _ in rows).encode()
-                            size_by_uid: dict[str, int] = {}
+                            st_sz, sz_data = None, None
                             try:
                                 st_sz, sz_data = _imap_uid_fetch(conn, uid_set_all, "(UID RFC822.SIZE)")
-                                if st_sz == "OK" and sz_data:
-                                    for item in sz_data:
-                                        meta = item[0] if isinstance(item, tuple) else item
-                                        if isinstance(meta, bytes):
-                                            u = _uid_from_fetch_meta(meta)
-                                            s = _size_from_fetch_meta(meta)
-                                            if u and s is not None:
-                                                size_by_uid[u] = s
                             except Exception as sz_err:
-                                logger.debug("IMAP size preflight query failed or unsupported: %s", sz_err)
+                                logger.warning("IMAP size preflight query failed for folder=%s: %s", folder, sz_err)
 
-                            if size_by_uid:
-                                for u, s in size_by_uid.items():
-                                    if s > max_message_bytes:
-                                        raise HTTPException(status_code=413, detail="Export too large")
-                                if total_bytes + sum(size_by_uid.values()) > max_total_bytes:
+                            if st_sz != "OK":
+                                logger.warning("IMAP size preflight status=%s for folder=%s account=%s", st_sz, folder, account_id)
+                                preflight_error = HTTPException(status_code=502, detail="Unable to verify email size safety")
+                                skipped += remaining_rows
+                                remaining_rows = 0
+                                continue
+
+                            if not sz_data:
+                                # All requested UIDs in this mailbox are missing on server
+                                skipped += remaining_rows
+                                remaining_rows = 0
+                                continue
+
+                            reported_sizes: dict[str, int | None] = {}
+                            for item in sz_data:
+                                meta = item[0] if isinstance(item, tuple) else item
+                                if isinstance(meta, bytes):
+                                    u = _uid_from_fetch_meta(meta)
+                                    if u:
+                                        reported_sizes[u] = _size_from_fetch_meta(meta)
+
+                            # Categorize requested UIDs
+                            malformed_uids = [
+                                uid for uid, _ in rows
+                                if uid in reported_sizes and (reported_sizes[uid] is None or reported_sizes[uid] < 0)
+                            ]
+                            if malformed_uids:
+                                logger.warning("IMAP size preflight returned invalid/malformed size for uids=%s in folder=%s", malformed_uids, folder)
+                                preflight_error = HTTPException(status_code=502, detail="Invalid email size metadata from server")
+                                skipped += remaining_rows
+                                remaining_rows = 0
+                                continue
+
+                            # Identify missing mail (requested UIDs not returned in preflight)
+                            missing_uids = {uid for uid, _ in rows if uid not in reported_sizes}
+                            if missing_uids:
+                                skipped += len(missing_uids)
+                                remaining_rows -= len(missing_uids)
+                                rows = [item for item in rows if item[0] not in missing_uids]
+
+                            if not rows:
+                                continue
+
+                            size_by_uid: dict[str, int] = {
+                                uid: reported_sizes[uid] for uid, _ in rows
+                            }
+
+                            for u, s in size_by_uid.items():
+                                if s > max_message_bytes:
                                     raise HTTPException(status_code=413, detail="Export too large")
+                            if total_bytes + sum(size_by_uid.values()) > max_total_bytes:
+                                raise HTTPException(status_code=413, detail="Export too large")
 
                             # Form batches with at most 20 messages and capped at 10 MiB payload.
                             batches: list[list[tuple[str, tuple[str, dict]]]] = []
@@ -4445,10 +4507,10 @@ def setup_email_routes():
                             max_batch_bytes = 10 * 1024 * 1024
                             for item in rows:
                                 uid_val = item[0]
-                                sz = size_by_uid.get(uid_val, 0)
+                                sz = size_by_uid[uid_val]
                                 if cur_batch and (
                                     len(cur_batch) >= 20 or
-                                    (sz > 0 and cur_batch_bytes + sz > max_batch_bytes)
+                                    (cur_batch_bytes + sz > max_batch_bytes)
                                 ):
                                     batches.append(cur_batch)
                                     cur_batch = []
@@ -4469,7 +4531,11 @@ def setup_email_routes():
                                 found: set[str] = set()
                                 for meta, raw_message in _group_uid_fetch_records(msg_data):
                                     uid = _uid_from_fetch_meta(meta)
-                                    if uid not in wanted or not raw_message:
+                                    if not uid or uid not in wanted or not raw_message:
+                                        continue
+                                    if uid in found:
+                                        # P2: Reject duplicate IMAP response records for an already-processed UID
+                                        logger.debug("Ignoring duplicate IMAP FETCH record for uid=%s in folder=%s", uid, folder)
                                         continue
                                     filename = wanted[uid]
                                     unique_name = filename
@@ -4502,6 +4568,8 @@ def setup_email_routes():
                         logger.warning("Bulk email export skipped mailbox folder=%s account=%s count=%s: %s", folder, account_id, remaining_rows, exc)
 
             if exported <= 0:
+                if preflight_error is not None:
+                    raise preflight_error
                 raise HTTPException(status_code=404, detail="No selected emails could be exported")
 
             spooled_file.seek(0)
diff --git a/static/js/emailLibrary/index.js b/static/js/emailLibrary/index.js
index cc08f2d0c..832549f31 100644
--- a/static/js/emailLibrary/index.js
+++ b/static/js/emailLibrary/index.js
@@ -1281,7 +1281,7 @@ async function _printSelectedEmails(messages) {
     frame.contentWindow.focus();
     frame.contentWindow.print();
     if (omitted.length > 0) {
-      const msg = `Printed ${successful.length} email${successful.length === 1 ? '' : 's'}; ${omitted.length} unavailable`;
+      const msg = `Prepared ${successful.length} email${successful.length === 1 ? '' : 's'} for printing; ${omitted.length} unavailable`;
       showToast(msg);
     }
   } catch (error) {
diff --git a/tests/test_email_library_bulk_actions.py b/tests/test_email_library_bulk_actions.py
index 1d8464270..362749044 100644
--- a/tests/test_email_library_bulk_actions.py
+++ b/tests/test_email_library_bulk_actions.py
@@ -264,21 +264,33 @@ def test_email_compose_can_attach_gallery_images():
 
 
 class _MockImapConn:
-    def __init__(self, messages_by_uid: dict[str, bytes] | None = None, fetch_exc: Exception | None = None):
+    def __init__(self, messages_by_uid: dict[str, bytes] | None = None, fetch_exc: Exception | None = None, fetch_cb=None):
         self.messages = messages_by_uid or {}
         self.fetch_exc = fetch_exc
+        self.fetch_cb = fetch_cb
+        self.fetch_calls: list = []
 
     def select(self, folder, readonly=True):
         return "OK", [b"1"]
 
     def uid(self, command, *args):
         if command == "FETCH":
+            self.fetch_calls.append(args)
             if self.fetch_exc is not None:
                 raise self.fetch_exc
+            if self.fetch_cb:
+                return self.fetch_cb(args)
             uid_set_b = args[0]
             uid_set = uid_set_b.decode() if isinstance(uid_set_b, bytes) else str(uid_set_b)
             uids = [u.strip() for u in uid_set.split(",") if u.strip()]
+            fetch_cmd = str(args[1]) if len(args) > 1 else ""
             res = []
+            if "RFC822.SIZE" in fetch_cmd:
+                for u in uids:
+                    if u in self.messages:
+                        meta = f"1 (UID {u} RFC822.SIZE {len(self.messages[u])})".encode()
+                        res.append(meta)
+                return "OK", res
             for u in uids:
                 if u in self.messages:
                     meta = f"1 (UID {u} RFC822 {{{len(self.messages[u])}}}".encode()
@@ -420,6 +432,9 @@ def test_messages_download_bulk_mid_batch_failure_accounting(monkeypatch):
         def select(self, folder, readonly=True):
             return "OK", [b"1"]
         def uid(self, command, *args):
+            fetch_cmd = str(args[1]) if len(args) > 1 else ""
+            if "RFC822.SIZE" in fetch_cmd:
+                return "OK", [f"{i} (UID {i} RFC822.SIZE 100)".encode() for i in range(1, 11)]
             records = []
             for i in range(1, 5):
                 records.append((f"{i} (UID {i} RFC822 {{{10}}}".encode(), f"Subject: Msg {i}\r\n\r\nBody {i}".encode()))
@@ -569,3 +584,192 @@ def test_messages_download_bulk_corrupt_zip_fails_closed(monkeypatch):
     })
     assert res.status_code == 500
     assert "Failed to create export archive" in res.json()["detail"]
+
+
+def test_messages_download_bulk_preflight_no_fails_safe_no_body_fetch(monkeypatch):
+    """When preflight returns NO, size safety is unknown: fail safely (502) and do not fetch bodies."""
+    mailbox = _MockImapConn({"101": b"dummy", "102": b"dummy"})
+    mailbox.fetch_cb = lambda args: ("NO", []) if "RFC822.SIZE" in str(args) else ("OK", [])
+    client = _create_test_app(monkeypatch, mailbox=mailbox)
+
+    res = client.post("/api/email/messages-download-bulk", json={"messages": [{"uid": "101"}, {"uid": "102"}]})
+    assert res.status_code == 502
+    assert "Unable to verify email size safety" in res.json()["detail"]
+    assert not any("(UID RFC822)" in str(call) for call in mailbox.fetch_calls)
+
+
+def test_messages_download_bulk_preflight_empty_missing_mail(monkeypatch):
+    """When preflight returns empty data, all requested messages are missing on server: returns 404 with no body fetch."""
+    mailbox = _MockImapConn()  # no messages
+    client = _create_test_app(monkeypatch, mailbox=mailbox)
+
+    res = client.post("/api/email/messages-download-bulk", json={"messages": [{"uid": "101"}, {"uid": "102"}]})
+    assert res.status_code == 404
+    assert "No selected emails could be exported" in res.json()["detail"]
+    assert not any("(UID RFC822)" in str(call) for call in mailbox.fetch_calls)
+
+
+def test_messages_download_bulk_preflight_malformed_fails_safe_no_body_fetch(monkeypatch):
+    """When preflight returns records without RFC822.SIZE, fail safely (502) and do not fetch bodies."""
+    mailbox = _MockImapConn({"101": b"dummy"})
+    mailbox.fetch_cb = lambda args: ("OK", [b"1 (UID 101 FLAGS (\\Seen))"]) if "RFC822.SIZE" in str(args) else ("OK", [])
+    client = _create_test_app(monkeypatch, mailbox=mailbox)
+
+    res = client.post("/api/email/messages-download-bulk", json={"messages": [{"uid": "101"}]})
+    assert res.status_code == 502
+    assert "Invalid email size metadata from server" in res.json()["detail"]
+    assert not any("(UID RFC822)" in str(call) for call in mailbox.fetch_calls)
+
+
+def test_messages_download_bulk_preflight_inconsistent_fails_safe_no_body_fetch(monkeypatch):
+    """When preflight returns negative or corrupted size values, fail safely (502) and do not fetch bodies."""
+    mailbox = _MockImapConn({"101": b"dummy"})
+    mailbox.fetch_cb = lambda args: ("OK", [b"1 (UID 101 RFC822.SIZE -50)"]) if "RFC822.SIZE" in str(args) else ("OK", [])
+    client = _create_test_app(monkeypatch, mailbox=mailbox)
+
+    res = client.post("/api/email/messages-download-bulk", json={"messages": [{"uid": "101"}]})
+    assert res.status_code == 502
+    assert "Invalid email size metadata from server" in res.json()["detail"]
+    assert not any("(UID RFC822)" in str(call) for call in mailbox.fetch_calls)
+
+
+def test_messages_download_bulk_preflight_partial_missing_omitted_from_body_fetch(monkeypatch):
+    """When some requested UIDs do not exist on the server, omit them from body fetch and export verified items."""
+    msg1 = b"From: a@example.com\r\nSubject: Only One\r\n\r\nBody"
+    mailbox = _MockImapConn({"101": msg1})  # 102 does not exist on server
+    client = _create_test_app(monkeypatch, mailbox=mailbox)
+
+    res = client.post("/api/email/messages-download-bulk", json={
+        "messages": [{"uid": "101"}, {"uid": "102"}]
+    })
+    assert res.status_code == 200
+    assert res.headers["x-exported-emails"] == "1"
+    assert res.headers["x-skipped-emails"] == "1"
+
+    # Verify body fetch was only requested for 101, NOT 102
+    body_fetches = [call for call in mailbox.fetch_calls if "(UID RFC822)" in str(call)]
+    assert len(body_fetches) == 1
+    requested_uids = body_fetches[0][0].decode() if isinstance(body_fetches[0][0], bytes) else str(body_fetches[0][0])
+    assert requested_uids == "101"
+    assert "102" not in requested_uids
+
+
+def test_messages_download_bulk_duplicate_imap_records_rejected(monkeypatch):
+    """Duplicate IMAP FETCH response records for the same UID must be ignored.
+    They must not produce duplicate archive entries or corrupt accounting."""
+    import io
+    import zipfile
+
+    msg1 = b"From: a@example.com\r\nSubject: Unique\r\n\r\nBody 1"
+    mailbox = _MockImapConn({"101": msg1})
+
+    def custom_fetch(args):
+        fetch_cmd = str(args[1]) if len(args) > 1 else ""
+        if "RFC822.SIZE" in fetch_cmd:
+            return "OK", [b"1 (UID 101 RFC822.SIZE 100)", b"2 (UID 102 RFC822.SIZE 100)"]
+        # In body fetch, server sends duplicate records for 101, and nothing for 102
+        records = [
+            (b"1 (UID 101 RFC822 {50}", msg1),
+            b")",
+            (b"1 (UID 101 RFC822 {50}", msg1),  # DUPLICATE RECORD
+            b")",
+        ]
+        return "OK", records
+
+    mailbox.fetch_cb = custom_fetch
+    client = _create_test_app(monkeypatch, mailbox=mailbox)
+
+    res = client.post("/api/email/messages-download-bulk", json={
+        "messages": [{"uid": "101"}, {"uid": "102"}]
+    })
+    assert res.status_code == 200
+    assert res.headers["x-exported-emails"] == "1"
+    assert res.headers["x-skipped-emails"] == "1"
+
+    zf = zipfile.ZipFile(io.BytesIO(res.content))
+    assert len(zf.namelist()) == 1
+    assert "101.eml" in zf.namelist()[0]
+
+
+def test_messages_download_bulk_single_message_preflight_failure_no_body_fetch(monkeypatch):
+    """In single message mode, bad preflight or missing mail fails safely without body fetch."""
+    mailbox = _MockImapConn({"101": b"dummy"})
+
+    # Case A: preflight NO -> 502
+    mailbox.fetch_cb = lambda args: ("NO", []) if "RFC822.SIZE" in str(args) else ("OK", [])
+    client = _create_test_app(monkeypatch, mailbox=mailbox)
+    res_no = client.post("/api/email/messages-download-bulk", json={"messages": [{"uid": "101"}]})
+    assert res_no.status_code == 502
+    assert not any("(UID RFC822)" in str(call) for call in mailbox.fetch_calls)
+
+    # Case B: missing mail -> 404
+    mailbox.fetch_calls.clear()
+    mailbox.fetch_cb = lambda args: ("OK", []) if "RFC822.SIZE" in str(args) else ("OK", [])
+    res_miss = client.post("/api/email/messages-download-bulk", json={"messages": [{"uid": "101"}]})
+    assert res_miss.status_code == 404
+    assert not any("(UID RFC822)" in str(call) for call in mailbox.fetch_calls)
+
+    # Case C: malformed metadata -> 502
+    mailbox.fetch_calls.clear()
+    mailbox.fetch_cb = lambda args: ("OK", [b"1 (UID 101 NO_SIZE)"]) if "RFC822.SIZE" in str(args) else ("OK", [])
+    res_mal = client.post("/api/email/messages-download-bulk", json={"messages": [{"uid": "101"}]})
+    assert res_mal.status_code == 502
+    assert not any("(UID RFC822)" in str(call) for call in mailbox.fetch_calls)
+
+
+def test_messages_download_bulk_spooled_stream_lifecycle():
+    """Verify that _iter_spooled closes the underlying SpooledTemporaryFile on completion and GeneratorExit."""
+    import tempfile
+    from routes.email.email_routes import setup_email_routes
+
+    # Test normal completion
+    f = tempfile.SpooledTemporaryFile(max_size=1024, mode="w+b")
+    f.write(b"Hello world payload")
+    f.seek(0)
+    # Re-create generator helper pattern
+    def _iter(file_obj, chunk_size=64):
+        try:
+            while True:
+                chunk = file_obj.read(chunk_size)
+                if not chunk:
+                    break
+                yield chunk
+        finally:
+            file_obj.close()
+
+    gen = _iter(f)
+    chunks = list(gen)
+    assert b"".join(chunks) == b"Hello world payload"
+    assert f.closed
+
+    # Test early disconnect / cancellation (GeneratorExit)
+    f2 = tempfile.SpooledTemporaryFile(max_size=1024, mode="w+b")
+    f2.write(b"Chunk1Chunk2Chunk3")
+    f2.seek(0)
+    gen2 = _iter(f2, chunk_size=6)
+    next(gen2)
+    assert not f2.closed
+    gen2.close()  # Simulates client disconnect / generator cancellation
+    assert f2.closed
+
+
+def test_email_print_browser_behaviors():
+    """Real Chromium DOM: placeholder stripping, button removal, and partial failure."""
+    import shutil
+    import subprocess
+    if not shutil.which('node'):
+        import pytest
+        pytest.skip('Node is required')
+    probe = subprocess.run(['node', '-e', "require.resolve('playwright')"], cwd=_REPO, capture_output=True)
+    if probe.returncode:
+        import pytest
+        pytest.skip('Playwright is required')
+    result = subprocess.run(
+        ['node', str(_REPO / 'tests/test_email_library_print_browser.cjs')],
+        cwd=_REPO,
+        capture_output=True,
+        text=True,
+        timeout=60,
+    )
+    assert result.returncode == 0, result.stdout + result.stderr
+    assert "ALL_BROWSER_TESTS_PASSED" in result.stdout
diff --git a/tests/test_email_library_print_browser.cjs b/tests/test_email_library_print_browser.cjs
new file mode 100644
index 000000000..62ca7a108
--- /dev/null
+++ b/tests/test_email_library_print_browser.cjs
@@ -0,0 +1,331 @@
+const http = require('http');
+const fs = require('fs');
+const path = require('path');
+const { chromium } = require('playwright');
+
+const ROOT = path.resolve(__dirname, '..');
+
+// Find available chromium executable or default to Playwright's cached browser
+function findChromiumPath() {
+  const candidates = [
+    '/home/alteixeira20/.cache/ms-playwright/chromium_headless_shell-1248/chrome-headless-shell-linux64/chrome-headless-shell',
+    '/home/alteixeira20/.cache/ms-playwright/chromium-1248/chrome-linux/chrome',
+  ];
+  for (const c of candidates) {
+    if (fs.existsSync(c)) return c;
+  }
+  return undefined;
+}
+
+async function run() {
+  const server = http.createServer((req, res) => {
+    const url = new URL(req.url, 'http://127.0.0.1');
+    if (url.pathname.startsWith('/api/email/read/')) {
+      const uid = url.pathname.replace('/api/email/read/', '');
+      if (uid === 'fail_uid' || uid === 'net_fail') {
+        res.writeHead(500, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: 'Mailbox disconnected' }));
+        return;
+      }
+      if (uid === 'crash_network') {
+        req.destroy();
+        return;
+      }
+
+      const markSeen = url.searchParams.get('mark_seen');
+      if (markSeen !== 'false') {
+        res.writeHead(400, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: 'mark_seen must be false' }));
+        return;
+      }
+
+      let body_html = '';
+      if (uid === 'img_test') {
+        body_html = [
+          '<div>',
+          '<p>Email with diverse images</p>',
+          '<!-- Inline image with alt text -->',
+          '<img src="cid:logo123" alt="Company Brand Logo">',
+          '<!-- Remote image with title -->',
+          '<img src="https://example.com/tracker.png" title="Tracking Pixel">',
+          '<!-- Image without alt or title -->',
+          '<img src="https://example.com/no-alt.jpg">',
+          '<!-- Interactive control that shouldn\'t be in print -->',
+          '<button type="button" class="btn-action">Interactive Action</button>',
+          '<!-- XSS payload -->',
+          '<script>window.__pwned = true;</script>',
+          '</div>'
+        ].join('\n');
+      } else if (uid === 'long_msg') {
+        body_html = `<div><p>${'A'.repeat(5000)}</p></div>`;
+      } else {
+        body_html = `<div><p>Standard message body for ${uid}</p></div>`;
+      }
+
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({
+        uid: uid,
+        subject: `Subject ${uid}`,
+        from_name: 'Sender',
+        from_address: 'sender@example.com',
+        to: 'user@example.com',
+        date: '2026-10-20',
+        date_display: 'Oct 20, 2026',
+        body: `Plain text for ${uid}`,
+        body_html: body_html,
+      }));
+      return;
+    }
+
+    let filePath = path.join(ROOT, url.pathname);
+    if (fs.existsSync(filePath) && fs.statSync(filePath).isFile()) {
+      const ext = path.extname(filePath);
+      const mime = ext === '.js' ? 'application/javascript' : ext === '.html' ? 'text/html' : ext === '.css' ? 'text/css' : 'text/plain';
+      res.writeHead(200, { 'Content-Type': mime });
+      res.end(fs.readFileSync(filePath));
+      return;
+    }
+    res.writeHead(404);
+    res.end('Not found');
+  });
+
+  await new Promise(r => server.listen(0, '127.0.0.1', r));
+  const port = server.address().port;
+  const origin = `http://127.0.0.1:${port}`;
+
+  const launchOpts = { headless: true };
+  const chromePath = findChromiumPath();
+  if (chromePath) launchOpts.executablePath = chromePath;
+
+  const browser = await chromium.launch(launchOpts);
+  const context = await browser.newContext();
+  const page = await context.newPage();
+
+  const results = {};
+
+  try {
+    await page.goto(`${origin}/static/index.html`);
+    await page.evaluate(() => {
+      if (!document.getElementById('email-lib-bulk-actions')) {
+        const d = document.createElement('div'); d.id = 'email-lib-bulk-actions'; document.body.appendChild(d);
+      }
+      if (!document.getElementById('email-lib-selected-count')) {
+        const d = document.createElement('div'); d.id = 'email-lib-selected-count'; document.body.appendChild(d);
+      }
+    });
+
+    // TEST 1: Full Print Image Sanitization and Replacement
+    const printImageResult = await page.evaluate(async (base) => {
+      window.API_BASE = base;
+      const mod = await import(`${base}/static/js/emailLibrary/index.js`);
+      const stateMod = await import(`${base}/static/js/emailLibrary/state.js`);
+
+      stateMod.state._selectedUids = new Set(['img_test']);
+      stateMod.state._libEmails = [{ uid: 'img_test', subject: 'Image Test', folder: 'INBOX' }];
+
+      let iframePrintInvoked = false;
+      let printDocHtml = '';
+      let afterPrintTriggered = false;
+      let hasPlaceholderElement = false;
+
+      const observer = new MutationObserver(() => {
+        const frame = document.getElementById('email-browser-print-frame');
+        if (frame && frame.contentWindow && !frame._patched) {
+          frame._patched = true;
+          frame.contentWindow.print = function() {
+            iframePrintInvoked = true;
+            printDocHtml = frame.contentDocument ? frame.contentDocument.documentElement.outerHTML : '';
+            const body = frame.contentDocument ? frame.contentDocument.body : null;
+            hasPlaceholderElement = !!body?.querySelector('.email-inline-image-placeholder');
+            frame.contentWindow.dispatchEvent(new Event('afterprint'));
+            afterPrintTriggered = true;
+          };
+        }
+      });
+      observer.observe(document.body, { childList: true });
+
+      await mod._exportSelectedEmailPdf();
+      observer.disconnect();
+
+      const frameAfter = document.getElementById('email-browser-print-frame');
+
+      return {
+        iframePrintInvoked,
+        afterPrintTriggered,
+        frameRemovedAfterPrint: frameAfter === null,
+        hasLogoNotice: printDocHtml.includes('[Image: Company Brand Logo]'),
+        hasTrackerNotice: printDocHtml.includes('[Image: Tracking Pixel]'),
+        hasNoAltNotice: printDocHtml.includes('[Image omitted]'),
+        hasPlaceholderElement,
+        hasRemoteImageBlockedText: printDocHtml.includes('Remote image blocked'),
+        hasDownloadButton: printDocHtml.includes('email-inline-image-download-btn'),
+        hasInteractiveActionBtn: printDocHtml.includes('btn-action'),
+        hasXSS: printDocHtml.includes('<script>') || printDocHtml.includes('window.__pwned'),
+      };
+    }, origin);
+
+    results.printImageSanitization = printImageResult;
+
+    // TEST 2: Partial Failure - 1 failure out of 3 emails
+    const partialFailureResult = await page.evaluate(async (base) => {
+      window.API_BASE = base;
+      const mod = await import(`${base}/static/js/emailLibrary/index.js`);
+      const stateMod = await import(`${base}/static/js/emailLibrary/state.js`);
+
+      const messages = [
+        { uid: 'msg1', subject: 'Email One', folder: 'INBOX' },
+        { uid: 'fail_uid', subject: 'Failing Email', folder: 'INBOX' },
+        { uid: 'msg2', subject: 'Email Two', folder: 'INBOX' },
+      ];
+      stateMod.state._selectedUids = new Set(messages.map(m => m.uid));
+      stateMod.state._libEmails = messages;
+
+      let printInvoked = false;
+      let printDocHtml = '';
+
+      const observer = new MutationObserver(() => {
+        const frame = document.getElementById('email-browser-print-frame');
+        if (frame && frame.contentWindow && !frame._patched) {
+          frame._patched = true;
+          frame.contentWindow.print = function() {
+            printInvoked = true;
+            printDocHtml = frame.contentDocument ? frame.contentDocument.documentElement.outerHTML : '';
+            frame.contentWindow.dispatchEvent(new Event('afterprint'));
+          };
+        }
+      });
+      observer.observe(document.body, { childList: true });
+
+      await mod._exportSelectedEmailPdf();
+      observer.disconnect();
+
+      const toast = document.getElementById('toast')?.textContent || '';
+
+      return {
+        printInvoked,
+        toast,
+        hasMsg1: printDocHtml.includes('Subject msg1'),
+        hasMsg2: printDocHtml.includes('Subject msg2'),
+        hasOmittedNotice: printDocHtml.includes('1 selected email was unavailable and omitted from this print'),
+      };
+    }, origin);
+
+    results.partialFailureTest = partialFailureResult;
+
+    // TEST 3: All emails fail
+    const allFailedResult = await page.evaluate(async (base) => {
+      window.API_BASE = base;
+      const mod = await import(`${base}/static/js/emailLibrary/index.js`);
+      const stateMod = await import(`${base}/static/js/emailLibrary/state.js`);
+
+      const messages = [
+        { uid: 'fail_uid', subject: 'Fail 1', folder: 'INBOX' },
+        { uid: 'net_fail', subject: 'Fail 2', folder: 'INBOX' },
+      ];
+      stateMod.state._selectedUids = new Set(messages.map(m => m.uid));
+      stateMod.state._libEmails = messages;
+
+      let printInvoked = false;
+      const observer = new MutationObserver(() => {
+        const frame = document.getElementById('email-browser-print-frame');
+        if (frame && frame.contentWindow && !frame._patched) {
+          frame._patched = true;
+          frame.contentWindow.print = function() {
+            printInvoked = true;
+          };
+        }
+      });
+      observer.observe(document.body, { childList: true });
+
+      let thrownError = null;
+      try {
+        await mod._exportSelectedEmailPdf();
+      } catch (err) {
+        thrownError = err.message || String(err);
+      }
+      observer.disconnect();
+
+      const frame = document.getElementById('email-browser-print-frame');
+      const toast = document.getElementById('toast')?.textContent || '';
+
+      return {
+        printInvoked,
+        frameOpened: frame !== null,
+        thrownError,
+        toast,
+      };
+    }, origin);
+
+    results.allFailedTest = allFailedResult;
+
+    // TEST 4: Idempotent Iframe Cleanup & Window Afterprint
+    const cleanupResult = await page.evaluate(async (base) => {
+      window.API_BASE = base;
+      const mod = await import(`${base}/static/js/emailLibrary/index.js`);
+      const stateMod = await import(`${base}/static/js/emailLibrary/state.js`);
+
+      stateMod.state._selectedUids = new Set(['msg1']);
+      stateMod.state._libEmails = [{ uid: 'msg1', subject: 'Cleanup Test', folder: 'INBOX' }];
+
+      const observer = new MutationObserver(() => {
+        const frame = document.getElementById('email-browser-print-frame');
+        if (frame && frame.contentWindow && !frame._patched) {
+          frame._patched = true;
+          frame.contentWindow.print = function() {
+            window.dispatchEvent(new Event('afterprint'));
+          };
+        }
+      });
+      observer.observe(document.body, { childList: true });
+
+      await mod._exportSelectedEmailPdf();
+      observer.disconnect();
+
+      const frameAfter = document.getElementById('email-browser-print-frame');
+      return {
+        frameRemovedViaWindowAfterprint: frameAfter === null,
+      };
+    }, origin);
+
+    results.cleanupTest = cleanupResult;
+
+  } finally {
+    await browser.close();
+    server.close();
+  }
+
+  // Assertions
+  const t1 = results.printImageSanitization;
+  if (!t1.iframePrintInvoked) throw new Error('Assertion failed: print not invoked');
+  if (!t1.frameRemovedAfterPrint) throw new Error('Assertion failed: frame not removed');
+  if (!t1.hasLogoNotice) throw new Error('Assertion failed: [Image: Company Brand Logo] missing');
+  if (!t1.hasTrackerNotice) throw new Error('Assertion failed: [Image: Tracking Pixel] missing');
+  if (!t1.hasNoAltNotice) throw new Error('Assertion failed: [Image omitted] missing');
+  if (t1.hasPlaceholderElement) throw new Error('Assertion failed: .email-inline-image-placeholder found in print doc');
+  if (t1.hasRemoteImageBlockedText) throw new Error('Assertion failed: Remote image blocked leaked into print doc');
+  if (t1.hasDownloadButton) throw new Error('Assertion failed: download button leaked into print doc');
+  if (t1.hasInteractiveActionBtn) throw new Error('Assertion failed: interactive button leaked into print doc');
+  if (t1.hasXSS) throw new Error('Assertion failed: script tag found');
+
+  const t2 = results.partialFailureTest;
+  if (!t2.printInvoked) throw new Error('Assertion failed: partial print was not invoked');
+  if (!t2.hasMsg1 || !t2.hasMsg2) throw new Error('Assertion failed: successful messages missing from print');
+  if (!t2.hasOmittedNotice) throw new Error('Assertion failed: omitted notice banner missing');
+  if (!t2.toast.includes('Prepared 2 emails for printing; 1 unavailable')) {
+    throw new Error('Assertion failed: toast text mismatch: ' + t2.toast);
+  }
+
+  const t3 = results.allFailedTest;
+  if (t3.printInvoked) throw new Error('Assertion failed: print should NOT be invoked when all fail');
+  if (t3.frameOpened) throw new Error('Assertion failed: print frame should NOT remain in DOM');
+
+  const t4 = results.cleanupTest;
+  if (!t4.frameRemovedViaWindowAfterprint) throw new Error('Assertion failed: top window afterprint did not clean up frame');
+
+  console.log('ALL_BROWSER_TESTS_PASSED');
+}
+
+run().catch(err => {
+  console.error('Browser test failed:', err);
+  process.exit(1);
+});

From 057ae92c17d0c01e9988a9baa89e06c8622aecc0 Mon Sep 17 00:00:00 2001
From: Alexandre Teixeira <111787685+alteixeira20@users.noreply.github.com>
Date: Tue, 20 Oct 2026 15:00:13 +0100
Subject: [PATCH 35/53] fix(email): support case-insensitive IMAP atoms and
 portable browser discovery

- Make _uid_from_fetch_meta case-insensitive with re.IGNORECASE matching size extraction
- Remove hardcoded developer home paths from test_email_library_print_browser.cjs
- Implement standard Playwright Chromium discovery with environment variable overrides and actionable launch failures
- Add executable tests for uppercase, lowercase, mixed-case IMAP atoms, malformed metadata, and preflight security
---
 routes/email/email_routes.py               |   2 +-
 tests/test_email_library_bulk_actions.py   | 105 +++++++++++++++++
 tests/test_email_library_print_browser.cjs | 125 +++++++++++++++++++--
 3 files changed, 222 insertions(+), 10 deletions(-)

diff --git a/routes/email/email_routes.py b/routes/email/email_routes.py
index 8443df3c1..277da3937 100644
--- a/routes/email/email_routes.py
+++ b/routes/email/email_routes.py
@@ -639,7 +639,7 @@ def _message_id_chain(*values: str) -> list[str]:
 
 
 def _uid_from_fetch_meta(meta_b: bytes) -> str:
-    m = re.search(rb"\bUID\s+(\d+)\b", meta_b)
+    m = re.search(rb"\bUID\s+(\d+)\b", meta_b, re.IGNORECASE)
     return m.group(1).decode() if m else ""
 
 
diff --git a/tests/test_email_library_bulk_actions.py b/tests/test_email_library_bulk_actions.py
index 362749044..165c506a5 100644
--- a/tests/test_email_library_bulk_actions.py
+++ b/tests/test_email_library_bulk_actions.py
@@ -753,6 +753,111 @@ def test_messages_download_bulk_spooled_stream_lifecycle():
     assert f2.closed
 
 
+def test_uid_and_size_from_fetch_meta_case_insensitivity_and_validation():
+    """Unit test: _uid_from_fetch_meta and _size_from_fetch_meta case insensitivity and boundary validation."""
+    from routes.email.email_routes import _uid_from_fetch_meta, _size_from_fetch_meta
+
+    # 1. Standard uppercase UID and RFC822.SIZE
+    meta_upper = b"1 (UID 101 RFC822.SIZE 1234)"
+    assert _uid_from_fetch_meta(meta_upper) == "101"
+    assert _size_from_fetch_meta(meta_upper) == 1234
+
+    # 2. Lowercase uid and rfc822.size
+    meta_lower = b"1 (uid 202 rfc822.size 5678)"
+    assert _uid_from_fetch_meta(meta_lower) == "202"
+    assert _size_from_fetch_meta(meta_lower) == 5678
+
+    # 3. Mixed-case combinations
+    combos = [
+        (b"1 (Uid 303 Rfc822.Size 1000)", "303", 1000),
+        (b"1 (uID 404 RFC822.size 2000)", "404", 2000),
+        (b"1 (UID 505 rfc822.size 3000)", "505", 3000),
+        (b"1 (uid 606 RFC822.SIZE 4000)", "606", 4000),
+        (b"1 (uId 707 Rfc822.SIZE 5000)", "707", 5000),
+        (b"1 (FLAGS (\\Seen) uid 808 rfc822.Size 6000)", "808", 6000),
+    ]
+    for meta_bytes, exp_uid, exp_sz in combos:
+        assert _uid_from_fetch_meta(meta_bytes) == exp_uid
+        assert _size_from_fetch_meta(meta_bytes) == exp_sz
+
+    # 4. Malformed metadata cases
+    assert _uid_from_fetch_meta(b"1 (rfc822.size 1234)") == ""
+    assert _size_from_fetch_meta(b"1 (uid 101 flags (\\seen))") is None
+    assert _uid_from_fetch_meta(b"1 (uid abc rfc822.size 1234)") == ""
+    assert _size_from_fetch_meta(b"1 (uid 101 rfc822.size invalid)") is None
+    assert _size_from_fetch_meta(b"1 (uid 101 rfc822.size -50)") is None
+
+    # 5. Boundary integrity (must not match substrings like UUID, GUID, NOT_RFC822.SIZE)
+    assert _uid_from_fetch_meta(b"1 (UUID 101 GUID 202 NOT_RFC822.SIZE 1234)") == ""
+    assert _size_from_fetch_meta(b"1 (UUID 101 GUID 202 NOT_RFC822.SIZE 1234)") is None
+    assert _uid_from_fetch_meta(b"1 (uid101 rfc822.size1234)") == ""
+    assert _size_from_fetch_meta(b"1 (uid101 rfc822.size1234)") is None
+    assert _uid_from_fetch_meta(b"") == ""
+    assert _size_from_fetch_meta(b"") is None
+
+
+def test_messages_download_bulk_case_insensitive_imap_atoms(monkeypatch):
+    """End-to-end: Bulk and single-message export with lowercase and mixed-case IMAP atoms."""
+    import io
+    import zipfile
+
+    msg101 = b"From: a@example.com\r\nSubject: Item 101\r\n\r\nBody 1"
+    msg102 = b"From: b@example.com\r\nSubject: Item 102\r\n\r\nBody 2"
+    mailbox = _MockImapConn({"101": msg101, "102": msg102})
+
+    def custom_fetch(args):
+        fetch_cmd = str(args[1]) if len(args) > 1 else ""
+        if "RFC822.SIZE" in fetch_cmd or "rfc822.size" in fetch_cmd.lower():
+            # Server returns lowercase/mixed-case atoms
+            return "OK", [
+                b"1 (uid 101 rfc822.size " + str(len(msg101)).encode() + b")",
+                b"2 (Uid 102 Rfc822.Size " + str(len(msg102)).encode() + b")",
+            ]
+        # In body fetch, server returns mixed-case atoms
+        return "OK", [
+            (b"1 (uid 101 rfc822 {" + str(len(msg101)).encode(), msg101),
+            b")",
+            (b"2 (Uid 102 RFC822 {" + str(len(msg102)).encode(), msg102),
+            b")",
+        ]
+
+    mailbox.fetch_cb = custom_fetch
+    client = _create_test_app(monkeypatch, mailbox=mailbox)
+
+    # 1. Bulk download (2 items) with lowercase / mixed-case IMAP responses
+    res_bulk = client.post("/api/email/messages-download-bulk", json={
+        "messages": [{"uid": "101"}, {"uid": "102"}]
+    })
+    assert res_bulk.status_code == 200
+    assert res_bulk.headers["x-exported-emails"] == "2"
+    assert res_bulk.headers["x-skipped-emails"] == "0"
+    zf = zipfile.ZipFile(io.BytesIO(res_bulk.content))
+    assert len(zf.namelist()) == 2
+
+    # 2. Single message download fast path with lowercase IMAP response
+    mailbox.fetch_calls.clear()
+    res_single = client.post("/api/email/messages-download-bulk", json={
+        "messages": [{"uid": "101"}]
+    })
+    assert res_single.status_code == 200
+    assert res_single.headers["content-type"].startswith("message/rfc822")
+    assert res_single.content == msg101
+
+    # 3. Lowercase malformed preflight fails safely with 502 and NO body fetch
+    mailbox.fetch_calls.clear()
+    mailbox.fetch_cb = lambda args: (
+        ("OK", [b"1 (uid 101 rfc822.size NaN)"])
+        if "RFC822.SIZE" in str(args) or "rfc822.size" in str(args).lower()
+        else ("OK", [])
+    )
+    res_malformed = client.post("/api/email/messages-download-bulk", json={
+        "messages": [{"uid": "101"}]
+    })
+    assert res_malformed.status_code == 502
+    assert "Invalid email size metadata from server" in res_malformed.json()["detail"]
+    assert not any("(UID RFC822)" in str(call) for call in mailbox.fetch_calls)
+
+
 def test_email_print_browser_behaviors():
     """Real Chromium DOM: placeholder stripping, button removal, and partial failure."""
     import shutil
diff --git a/tests/test_email_library_print_browser.cjs b/tests/test_email_library_print_browser.cjs
index 62ca7a108..9ad84dc23 100644
--- a/tests/test_email_library_print_browser.cjs
+++ b/tests/test_email_library_print_browser.cjs
@@ -1,19 +1,115 @@
+/**
+ * Browser print regression tests for Email Library print and PDF export.
+ *
+ * Requirements:
+ * - Node.js (v20+)
+ * - Playwright (`npm ci` or `npm install -D @playwright/test`)
+ * - Chromium browser binary:
+ *     - Standard Playwright install: `npx playwright install chromium`
+ *     - Or custom executable via env vars:
+ *         - `PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH=/path/to/chrome`
+ *         - `CHROME_PATH=/path/to/chrome`
+ *     - Or custom browsers cache dir via:
+ *         - `PLAYWRIGHT_BROWSERS_PATH=/path/to/cache`
+ */
+
 const http = require('http');
 const fs = require('fs');
 const path = require('path');
-const { chromium } = require('playwright');
+const os = require('os');
+
+let chromium;
+try {
+  ({ chromium } = require('playwright'));
+} catch (err) {
+  if (err && err.code === 'MODULE_NOT_FOUND') {
+    console.error(
+      'Error: Playwright module not found.\n' +
+      'Please install dependencies by running:\n' +
+      '  npm ci\n' +
+      'or ensure NODE_PATH contains the playwright package.'
+    );
+    process.exit(1);
+  }
+  throw err;
+}
 
 const ROOT = path.resolve(__dirname, '..');
 
-// Find available chromium executable or default to Playwright's cached browser
+// Discover available Chromium executable using standard Playwright resolution,
+// custom environment variables, standard cache paths, or system binaries.
 function findChromiumPath() {
-  const candidates = [
-    '/home/alteixeira20/.cache/ms-playwright/chromium_headless_shell-1248/chrome-headless-shell-linux64/chrome-headless-shell',
-    '/home/alteixeira20/.cache/ms-playwright/chromium-1248/chrome-linux/chrome',
-  ];
-  for (const c of candidates) {
-    if (fs.existsSync(c)) return c;
+  // 1. Explicit environment variable overrides
+  if (process.env.PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH && fs.existsSync(process.env.PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH)) {
+    return process.env.PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH;
   }
+  if (process.env.CHROME_PATH && fs.existsSync(process.env.CHROME_PATH)) {
+    return process.env.CHROME_PATH;
+  }
+
+  // 2. Playwright's configured/default executable path
+  try {
+    const defaultPath = chromium.executablePath();
+    if (defaultPath && fs.existsSync(defaultPath)) {
+      return defaultPath;
+    }
+  } catch (e) {
+    // chromium.executablePath() may throw if no default browser is installed
+  }
+
+  // 3. Inspect standard Playwright browser cache directories
+  const cacheDirs = [];
+  if (process.env.PLAYWRIGHT_BROWSERS_PATH) {
+    cacheDirs.push(process.env.PLAYWRIGHT_BROWSERS_PATH);
+  }
+  if (process.platform === 'win32') {
+    if (process.env.LOCALAPPDATA) {
+      cacheDirs.push(path.join(process.env.LOCALAPPDATA, 'ms-playwright'));
+    }
+    cacheDirs.push(path.join(os.homedir(), 'AppData', 'Local', 'ms-playwright'));
+  } else if (process.platform === 'darwin') {
+    cacheDirs.push(path.join(os.homedir(), 'Library', 'Caches', 'ms-playwright'));
+  } else {
+    cacheDirs.push(path.join(os.homedir(), '.cache', 'ms-playwright'));
+  }
+
+  for (const cacheDir of cacheDirs) {
+    if (!fs.existsSync(cacheDir)) continue;
+    try {
+      const entries = fs.readdirSync(cacheDir).sort().reverse();
+      for (const entry of entries) {
+        const entryPath = path.join(cacheDir, entry);
+        const candidates = [
+          path.join(entryPath, 'chrome-headless-shell-linux64', 'chrome-headless-shell'),
+          path.join(entryPath, 'chrome-linux64', 'chrome'),
+          path.join(entryPath, 'chrome-linux', 'chrome'),
+          path.join(entryPath, 'chrome-win64', 'chrome.exe'),
+          path.join(entryPath, 'chrome-win', 'chrome.exe'),
+          path.join(entryPath, 'chrome-mac', 'Chromium.app', 'Contents', 'MacOS', 'Chromium'),
+        ];
+        for (const candidate of candidates) {
+          if (fs.existsSync(candidate)) {
+            return candidate;
+          }
+        }
+      }
+    } catch (e) {}
+  }
+
+  // 4. System browser fallbacks
+  const systemCandidates = process.platform === 'win32' ? [
+    path.join(process.env['PROGRAMFILES'] || 'C:\\Program Files', 'Google', 'Chrome', 'Application', 'chrome.exe'),
+    path.join(process.env['PROGRAMFILES(X86)'] || 'C:\\Program Files (x86)', 'Google', 'Chrome', 'Application', 'chrome.exe'),
+  ] : [
+    '/usr/bin/google-chrome',
+    '/usr/bin/chromium',
+    '/usr/bin/chromium-browser',
+    '/snap/bin/chromium',
+  ];
+  for (const sc of systemCandidates) {
+    if (fs.existsSync(sc)) return sc;
+  }
+
   return undefined;
 }
 
@@ -97,7 +193,18 @@ async function run() {
   const chromePath = findChromiumPath();
   if (chromePath) launchOpts.executablePath = chromePath;
 
-  const browser = await chromium.launch(launchOpts);
+  let browser;
+  try {
+    browser = await chromium.launch(launchOpts);
+  } catch (launchErr) {
+    throw new Error(
+      `Failed to launch Chromium browser: ${launchErr.message}\n` +
+      'Missing or unexecutable Chromium binary.\n' +
+      'To install Playwright Chromium, run:\n' +
+      '  npx playwright install chromium\n' +
+      'Or set PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH to a valid Chromium executable.'
+    );
+  }
   const context = await browser.newContext();
   const page = await context.newPage();
 

From 377070ab7951d161b10542a62c02740408bba2d3 Mon Sep 17 00:00:00 2001
From: Alexandre Teixeira <111787685+alteixeira20@users.noreply.github.com>
Date: Tue, 20 Oct 2026 15:36:16 +0100
Subject: [PATCH 36/53] fix(email): propagate preflight safety failure across
 all mailbox groups

- Propagate preflight HTTPException(status_code=502) regardless of whether other mailbox groups exported messages into the temporary ZIP
- Guarantee temporary file cleanup via SpooledTemporaryFile.close() on preflight failure
- Preserve partial success (HTTP 200) for genuinely missing mail
- Add executable tests for multi-group preflight failure orderings, missing mail, and zero body fetches
---
 routes/email/email_routes.py             |   5 +-
 tests/test_email_library_bulk_actions.py | 188 +++++++++++++++++++++++
 2 files changed, 191 insertions(+), 2 deletions(-)

diff --git a/routes/email/email_routes.py b/routes/email/email_routes.py
index 277da3937..81173f889 100644
--- a/routes/email/email_routes.py
+++ b/routes/email/email_routes.py
@@ -4567,9 +4567,10 @@ def setup_email_routes():
                         skipped += remaining_rows
                         logger.warning("Bulk email export skipped mailbox folder=%s account=%s count=%s: %s", folder, account_id, remaining_rows, exc)
 
+            if preflight_error is not None:
+                raise preflight_error
+
             if exported <= 0:
-                if preflight_error is not None:
-                    raise preflight_error
                 raise HTTPException(status_code=404, detail="No selected emails could be exported")
 
             spooled_file.seek(0)
diff --git a/tests/test_email_library_bulk_actions.py b/tests/test_email_library_bulk_actions.py
index 165c506a5..fc46399c5 100644
--- a/tests/test_email_library_bulk_actions.py
+++ b/tests/test_email_library_bulk_actions.py
@@ -858,6 +858,194 @@ def test_messages_download_bulk_case_insensitive_imap_atoms(monkeypatch):
     assert not any("(UID RFC822)" in str(call) for call in mailbox.fetch_calls)
 
 
+def test_messages_download_bulk_multi_group_preflight_failure_propagates_502(monkeypatch):
+    """A preflight safety failure in any group produces HTTP 502 for the entire request,
+    even when another group has already exported messages into the temporary ZIP.
+    Confirms temporary-file cleanup, zero body FETCH for the failed group, and both group orderings."""
+    import tempfile
+
+    msg101 = b"From: a@example.com\r\nSubject: Good\r\n\r\nBody 1"
+
+    spooled_instances: list[tempfile.SpooledTemporaryFile] = []
+    orig_spooled = tempfile.SpooledTemporaryFile
+
+    def tracking_spooled(*args, **kwargs):
+        inst = orig_spooled(*args, **kwargs)
+        spooled_instances.append(inst)
+        return inst
+
+    monkeypatch.setattr(tempfile, "SpooledTemporaryFile", tracking_spooled)
+
+    class MultiMailboxConn:
+        def __init__(self):
+            self.fetch_calls: list[tuple[str, tuple]] = []
+            self.current_folder = "INBOX"
+
+        def select(self, folder, readonly=True):
+            self.current_folder = str(folder)
+            return "OK", [b"1"]
+
+        def uid(self, command, *args):
+            self.fetch_calls.append((self.current_folder, args))
+            fetch_cmd = str(args[1]) if len(args) > 1 else ""
+            uid_set = args[0].decode() if isinstance(args[0], bytes) else str(args[0])
+
+            if "RFC822.SIZE" in fetch_cmd:
+                if "folder-fail" in self.current_folder:
+                    return "NO", []  # Preflight failure for folder-fail
+                return "OK", [f"1 (UID {uid_set} RFC822.SIZE 100)".encode()]
+
+            # Body fetch
+            if "folder-fail" in self.current_folder:
+                return "NO", []
+            return "OK", [(f"1 (UID {uid_set} RFC822 {{100}}".encode(), msg101), b")"]
+
+    # 1. Successful group followed by failed preflight
+    conn1 = MultiMailboxConn()
+    client1 = _create_test_app(monkeypatch, mailbox=conn1)
+    spooled_instances.clear()
+
+    res1 = client1.post("/api/email/messages-download-bulk", json={
+        "messages": [
+            {"uid": "101", "folder": "folder-good"},
+            {"uid": "202", "folder": "folder-fail"},
+        ]
+    })
+    assert res1.status_code == 502
+    assert "Unable to verify email size safety" in res1.json()["detail"]
+
+    # No RFC822 body FETCH for the failed group
+    failed_body_fetches1 = [
+        call for folder, call in conn1.fetch_calls
+        if "folder-fail" in folder and "(UID RFC822)" in str(call)
+    ]
+    assert len(failed_body_fetches1) == 0
+
+    # Temporary file cleanup confirmed
+    assert len(spooled_instances) == 1
+    assert spooled_instances[0].closed
+
+    # 2. Failed preflight followed by successful group
+    conn2 = MultiMailboxConn()
+    client2 = _create_test_app(monkeypatch, mailbox=conn2)
+    spooled_instances.clear()
+
+    res2 = client2.post("/api/email/messages-download-bulk", json={
+        "messages": [
+            {"uid": "202", "folder": "folder-fail"},
+            {"uid": "101", "folder": "folder-good"},
+        ]
+    })
+    assert res2.status_code == 502
+    assert "Unable to verify email size safety" in res2.json()["detail"]
+
+    # No RFC822 body FETCH for the failed group
+    failed_body_fetches2 = [
+        call for folder, call in conn2.fetch_calls
+        if "folder-fail" in folder and "(UID RFC822)" in str(call)
+    ]
+    assert len(failed_body_fetches2) == 0
+
+    # Temporary file cleanup confirmed
+    assert len(spooled_instances) == 1
+    assert spooled_instances[0].closed
+
+
+def test_messages_download_bulk_multi_group_both_successful(monkeypatch):
+    """When both groups succeed preflight and body fetch, return 200 with all messages in ZIP."""
+    import io
+    import zipfile
+
+    msg101 = b"From: a@example.com\r\nSubject: Item 1\r\n\r\nBody 1"
+    msg202 = b"From: b@example.com\r\nSubject: Item 2\r\n\r\nBody 2"
+
+    class MultiMailboxConn:
+        def __init__(self):
+            self.current_folder = "INBOX"
+
+        def select(self, folder, readonly=True):
+            self.current_folder = str(folder)
+            return "OK", [b"1"]
+
+        def uid(self, command, *args):
+            fetch_cmd = str(args[1]) if len(args) > 1 else ""
+            uid_set = args[0].decode() if isinstance(args[0], bytes) else str(args[0])
+            msg = msg101 if "101" in uid_set else msg202
+            if "RFC822.SIZE" in fetch_cmd:
+                return "OK", [f"1 (UID {uid_set} RFC822.SIZE {len(msg)})".encode()]
+            return "OK", [(f"1 (UID {uid_set} RFC822 {{{len(msg)}}}".encode(), msg), b")"]
+
+    conn = MultiMailboxConn()
+    client = _create_test_app(monkeypatch, mailbox=conn)
+
+    res = client.post("/api/email/messages-download-bulk", json={
+        "messages": [
+            {"uid": "101", "folder": "folder-1"},
+            {"uid": "202", "folder": "folder-2"},
+        ]
+    })
+    assert res.status_code == 200
+    assert res.headers["x-exported-emails"] == "2"
+    assert res.headers["x-skipped-emails"] == "0"
+    zf = zipfile.ZipFile(io.BytesIO(res.content))
+    assert len(zf.namelist()) == 2
+
+
+def test_messages_download_bulk_multi_group_genuinely_missing_message(monkeypatch):
+    """Genuinely missing messages (unreturned by preflight) do not cause 502;
+    they are skipped while verified messages in any group are successfully exported."""
+    import io
+    import zipfile
+
+    msg101 = b"From: a@example.com\r\nSubject: Exists\r\n\r\nBody"
+
+    class MissingMailboxConn:
+        def __init__(self):
+            self.fetch_calls: list = []
+            self.current_folder = "INBOX"
+
+        def select(self, folder, readonly=True):
+            self.current_folder = str(folder)
+            return "OK", [b"1"]
+
+        def uid(self, command, *args):
+            self.fetch_calls.append((self.current_folder, args))
+            fetch_cmd = str(args[1]) if len(args) > 1 else ""
+            uid_set = args[0].decode() if isinstance(args[0], bytes) else str(args[0])
+            if "RFC822.SIZE" in fetch_cmd:
+                # 101 exists on server; 999 is genuinely missing (unreported in size metadata)
+                res = []
+                if "101" in uid_set:
+                    res.append(f"1 (UID 101 RFC822.SIZE {len(msg101)})".encode())
+                return "OK", res
+            # Body fetch only returns 101
+            return "OK", [(f"1 (UID 101 RFC822 {{{len(msg101)}}}".encode(), msg101), b")"]
+
+    conn = MissingMailboxConn()
+    client = _create_test_app(monkeypatch, mailbox=conn)
+
+    res = client.post("/api/email/messages-download-bulk", json={
+        "messages": [
+            {"uid": "101", "folder": "folder-1"},
+            {"uid": "999", "folder": "folder-1"},
+        ]
+    })
+    assert res.status_code == 200
+    assert res.headers["x-exported-emails"] == "1"
+    assert res.headers["x-skipped-emails"] == "1"
+
+    zf = zipfile.ZipFile(io.BytesIO(res.content))
+    assert len(zf.namelist()) == 1
+
+    # Verify 999 was never requested in body fetch
+    body_fetches = [
+        call for folder, call in conn.fetch_calls
+        if "(UID RFC822)" in str(call)
+    ]
+    assert len(body_fetches) == 1
+    assert "999" not in str(body_fetches[0])
+
+
 def test_email_print_browser_behaviors():
     """Real Chromium DOM: placeholder stripping, button removal, and partial failure."""
     import shutil

From df1c2c8b192f693fdbcad5020df4b1545db99910 Mon Sep 17 00:00:00 2001
From: RaresKeY <158580472+RaresKeY@users.noreply.github.com>
Date: Wed, 21 Oct 2026 18:27:05 +0000
Subject: [PATCH 37/53] fix: refresh outbound HTTPS trust and installer
 bootstrap

---
 .github/workflows/ci.yml                |  15 ++-
 .github/workflows/dependency-review.yml |   4 +
 .github/workflows/docker-publish.yml    |   1 +
 .github/workflows/workflow-security.yml |   4 +
 Dockerfile                              |  17 ++-
 build-windows-portable.ps1              |   3 +-
 docs/tls-trust.md                       |  34 +++++
 launch-windows.ps1                      |   3 +-
 requirements-bootstrap.txt              |   8 ++
 requirements.txt                        |   2 +
 scripts/check_ca_trust.py               |  96 ++++++++++++++
 start-macos.sh                          |   4 +-
 tests/fixtures/ca-trust/README.md       |   5 +
 tests/test_ca_trust.py                  | 168 ++++++++++++++++++++++++
 14 files changed, 355 insertions(+), 9 deletions(-)
 create mode 100644 docs/tls-trust.md
 create mode 100644 requirements-bootstrap.txt
 create mode 100644 scripts/check_ca_trust.py
 create mode 100644 tests/fixtures/ca-trust/README.md
 create mode 100644 tests/test_ca_trust.py

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 42f0651f0..29f303ca4 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -93,7 +93,7 @@ jobs:
           persist-credentials: false
       - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020  # v7.0.0
         with:
-          node-version: "20"
+          node-version: "22.23.4"
       - run: npm ci --ignore-scripts --no-audit --no-fund
       - name: Check frontend architecture
         run: node scripts/check_frontend.mjs
@@ -160,15 +160,18 @@ jobs:
       - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7  # v10.2.0
         if: steps.docs-check.outputs.docs_only != 'true'
         with:
+          version: "0.13.4"
           enable-cache: true
           cache-dependency-glob: requirements.txt
           prune-cache: false
-      - run: uv pip install --system -r requirements.txt
+      - run: |
+          uv pip install --system --require-hashes --only-binary=:all: --no-deps -r requirements-bootstrap.txt
+          uv pip install --system -r requirements.txt
         if: steps.docs-check.outputs.docs_only != 'true'
       - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020  # v7.0.0
         if: steps.docs-check.outputs.docs_only != 'true'
         with:
-          node-version: "20"
+          node-version: "22.23.4"
           cache: npm
       - run: npm ci
         if: steps.docs-check.outputs.docs_only != 'true'
@@ -190,10 +193,14 @@ jobs:
         if: steps.docs-check.outputs.docs_only != 'true'
         run: |
           sudo apt-get update
-          sudo apt-get install -y --no-install-recommends ffmpeg bubblewrap
+          sudo apt-get install -y --no-install-recommends ffmpeg bubblewrap ca-certificates
           command -v ffmpeg
           ffmpeg -version | head -n 1
 
+      - name: Validate Python and system CA trust
+        if: steps.docs-check.outputs.docs_only != 'true'
+        run: python scripts/check_ca_trust.py --system --python
+
       - name: Establish functional bubblewrap containment
         if: steps.docs-check.outputs.docs_only != 'true'
         shell: bash
diff --git a/.github/workflows/dependency-review.yml b/.github/workflows/dependency-review.yml
index 0e4f9a1f1..e78bba158 100644
--- a/.github/workflows/dependency-review.yml
+++ b/.github/workflows/dependency-review.yml
@@ -70,5 +70,9 @@ jobs:
       - name: Run pip-audit on requirements
         run: |
           set -euo pipefail
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends ca-certificates
+          python scripts/check_ca_trust.py --system
+          python -m pip install --require-hashes --only-binary=:all: --no-deps -r requirements-bootstrap.txt
           pip install pip-audit==2.10.0
           pip-audit -r requirements.txt -r requirements-optional.txt --strict
diff --git a/.github/workflows/docker-publish.yml b/.github/workflows/docker-publish.yml
index da41c7140..2cb8221ec 100644
--- a/.github/workflows/docker-publish.yml
+++ b/.github/workflows/docker-publish.yml
@@ -65,6 +65,7 @@ jobs:
         uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a  # v7.3.0
         with:
           context: .
+          pull: true
           platforms: ${{ matrix.platform }}
           outputs: type=image,name=${{ env.REGISTRY }}/${{ env.IMAGE_NAME }},push-by-digest=true,name-canonical=true,push=true
           cache-from: type=gha,scope=${{ matrix.arch }}
diff --git a/.github/workflows/workflow-security.yml b/.github/workflows/workflow-security.yml
index b00cd03a4..18a197eb0 100644
--- a/.github/workflows/workflow-security.yml
+++ b/.github/workflows/workflow-security.yml
@@ -76,5 +76,9 @@ jobs:
       - name: Run zizmor
         run: |
           set -euo pipefail
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends ca-certificates
+          python scripts/check_ca_trust.py --system
+          python -m pip install --require-hashes --only-binary=:all: --no-deps -r requirements-bootstrap.txt
           pip install zizmor==1.25.2
           zizmor --offline --min-severity=low .github/workflows/
diff --git a/Dockerfile b/Dockerfile
index d6e7ca48f..2e49c6ed6 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -4,8 +4,13 @@
 # the final image / Cookbook never has to compile the broken sdists. See
 # docker/build-realesrgan-wheels.sh for the full rationale.
 FROM python:3.14-slim AS realesrgan-wheels
-RUN apt-get update && apt-get install -y --no-install-recommends curl \
+RUN apt-get update && apt-get install -y --no-install-recommends curl ca-certificates \
     && rm -rf /var/lib/apt/lists/*
+COPY scripts/check_ca_trust.py /usr/local/bin/check-ca-trust.py
+RUN python /usr/local/bin/check-ca-trust.py --system
+COPY requirements-bootstrap.txt /tmp/requirements-bootstrap.txt
+RUN python -m pip install --no-cache-dir --require-hashes --only-binary=:all: --no-deps -r /tmp/requirements-bootstrap.txt \
+    && python /usr/local/bin/check-ca-trust.py --python
 COPY docker/build-realesrgan-wheels.sh /usr/local/bin/build-realesrgan-wheels.sh
 RUN bash /usr/local/bin/build-realesrgan-wheels.sh /wheels
 
@@ -28,6 +33,7 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
     build-essential \
     cmake \
     curl \
+    ca-certificates \
     git \
     nodejs \
     npm \
@@ -48,6 +54,15 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
     libmagic1 \
     && rm -rf /var/lib/apt/lists/*
 
+# Refresh both Python trust bundles before installing application dependencies.
+# System roots also serve web fetches, webhooks, curl, and Node's OpenSSL mode.
+COPY scripts/check_ca_trust.py /usr/local/bin/check-ca-trust.py
+RUN python /usr/local/bin/check-ca-trust.py --system
+COPY requirements-bootstrap.txt /tmp/requirements-bootstrap.txt
+RUN python -m pip install --no-cache-dir --require-hashes --only-binary=:all: --no-deps -r /tmp/requirements-bootstrap.txt \
+    && python /usr/local/bin/check-ca-trust.py --python
+ENV NODE_OPTIONS=--use-openssl-ca
+
 # Private browser automation wrapper used by the native `private_browser` tool.
 # Chromium is installed above, so agent-browser can drive the existing browser
 # binary without paying `npx` startup/install overhead on each tool call.
diff --git a/build-windows-portable.ps1 b/build-windows-portable.ps1
index 7da912f73..634ae8068 100644
--- a/build-windows-portable.ps1
+++ b/build-windows-portable.ps1
@@ -47,7 +47,8 @@ if (-not $pyExe) {
 Write-Host ("Using Python: " + $pyExe)
 
 Write-Step "Installing build dependencies"
-& $pyExe -m pip install --upgrade pip --quiet
+& $pyExe -m pip install --quiet --require-hashes --only-binary=:all: --no-deps -r requirements-bootstrap.txt
+if ($LASTEXITCODE -ne 0) { Fail "TLS build dependency bootstrap failed." }
 & $pyExe -m pip install -r requirements.txt pyinstaller pystray Pillow
 if ($LASTEXITCODE -ne 0) { Fail "Dependency install failed." }
 
diff --git a/docs/tls-trust.md b/docs/tls-trust.md
new file mode 100644
index 000000000..3d91e08cd
--- /dev/null
+++ b/docs/tls-trust.md
@@ -0,0 +1,34 @@
+# Outbound HTTPS trust
+
+Odysseus uses both Python package CA bundles and system trust. HTTPX uses certifi by default; the guarded web/PDF fetcher and webhook delivery explicitly use Python's system SSL context. A configured `LLM_CA_BUNDLE` adds certificates to system trust for model calls. Upgrading certifi alone cannot repair every outbound HTTPS path.
+
+For the October 2026 eMudhra incident, use certifi 2026.10.19 or newer, pip 26.2.2 or newer, and uv 0.13.4 or newer wherever uv is used. Pip has its own vendored certifi and also loads system roots. Update the operating system's certificate package separately. See the [Python security announcement](https://discuss.python.org/t/109576) and [incident details](https://emudhra.we-have-a-problem.com/).
+
+Before other pip installs, bootstrap the selected environment with the integrity-pinned wheels:
+
+```sh
+python -m pip install --require-hashes --only-binary=:all: --no-deps -r requirements-bootstrap.txt
+python -m pip install -r requirements.txt
+```
+
+The pinned bootstrap protects package integrity even when the old installer's certificate bundle is affected. It is not an operating-system trust-store update. Native Windows/macOS trust and command-line OpenSSL PEM stores may differ; follow the platform vendor's remediation for every store in use. Restart Odysseus and its subprocesses after updating trust.
+
+On Linux/OpenSSL deployments, inspect both the effective CA file and hashed CA directory, plus the two Python bundles:
+
+```sh
+python scripts/check_ca_trust.py --system --python
+```
+
+Explicit PEM bundles can also be passed as positional arguments. The check rejects the incident's known root fingerprints and malformed/empty bundles. It does not model native OS intermediate revocation, custom TLS implementations, or arbitrary certificates added by an operator.
+
+Both Docker build stages refresh system CA certificates and bootstrap pip/certifi before dependency installation. The build fails if affected roots remain. Node uses the corrected system store through `--use-openssl-ca`. Rebuild with a fresh base and dependency layers when remediating an existing deployment:
+
+```sh
+docker compose build --pull --no-cache odysseus
+docker compose up -d odysseus
+docker compose exec odysseus python scripts/check_ca_trust.py --system --python
+```
+
+SearXNG is a separate HTTPS client and image; updating the Odysseus image does not patch it. Inspect its effective CA path and update or rebuild that image independently. Also inspect persisted `/app/.local` packages, remote Cookbook environments, and externally configured MCP runtimes. Image replacement does not necessarily replace those environments.
+
+For behavioral validation, all twelve [published test chains](https://emudhra.we-have-a-problem.com/chains.zip), including the AAA cross-signs, must fail certificate verification through the effective stores. Confirm that an ordinary known-good HTTPS request still succeeds. Package versions and a successful image build alone do not prove that a running deployment selects the corrected store.
diff --git a/launch-windows.ps1 b/launch-windows.ps1
index ab0e3542b..31c45a5fb 100644
--- a/launch-windows.ps1
+++ b/launch-windows.ps1
@@ -131,7 +131,8 @@ if (-not (Test-Path $venvPy)) {
 
 # 3. Install / update dependencies
 Write-Step "Installing dependencies (first run can take a few minutes)"
-& $venvPy -m pip install --upgrade pip --quiet
+& $venvPy -m pip install --quiet --require-hashes --only-binary=:all: --no-deps -r requirements-bootstrap.txt
+if ($LASTEXITCODE -ne 0) { Fail "TLS dependency bootstrap failed." }
 & $venvPy -m pip install -r requirements.txt
 if ($LASTEXITCODE -ne 0) { Fail "Dependency install failed. Scroll up for the pip error." }
 
diff --git a/requirements-bootstrap.txt b/requirements-bootstrap.txt
new file mode 100644
index 000000000..8b39dc69b
--- /dev/null
+++ b/requirements-bootstrap.txt
@@ -0,0 +1,8 @@
+# Integrity-pinned bootstrap for the October 2026 eMudhra CA incident.
+# Install with --require-hashes --only-binary=:all: --no-deps before other pip work.
+# pip vendors its own certifi; updating the application bundle cannot update it.
+# Direct universal wheels avoid index resolution through the old trust store.
+pip @ https://files.pythonhosted.org/packages/3f/06/3e4420302363fbb71be3c7f35ce042f54bfca330e3e66b3a2e3c4cca579f/pip-26.2.2-py3-none-any.whl \
+    --hash=sha256:fd7f4dfa8190e014013b9f08f3e973f4e4c26ffd179a204895533a7254813a70
+certifi @ https://files.pythonhosted.org/packages/c4/51/29046e48f693c54e5b7412216d447a1d8362c9653148d98c02cdf65fa733/certifi-2026.10.19-py3-none-any.whl \
+    --hash=sha256:42d35340cc5b9ba78e818ddbff0c5b1c2b779de448a340fd1b989f5fa8670e1b
diff --git a/requirements.txt b/requirements.txt
index 7fabaae93..4d794537d 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -3,6 +3,8 @@ uvicorn
 python-multipart
 python-dotenv
 httpx
+# HTTPS clients using certifi must distrust the compromised eMudhra CA paths.
+certifi>=2026.10.19
 httpcore>=1.0,<2.0
 pydantic>=2.13.4
 pydantic-settings>=2.14.1
diff --git a/scripts/check_ca_trust.py b/scripts/check_ca_trust.py
new file mode 100644
index 000000000..c675dc6f3
--- /dev/null
+++ b/scripts/check_ca_trust.py
@@ -0,0 +1,96 @@
+#!/usr/bin/env python3
+"""Reject the eMudhra incident's root certificates in PEM trust stores.
+
+This checks certificate contents, including OpenSSL's lazily loaded CA directory.
+It does not model native OS certificate revocation or arbitrary custom clients.
+Incident fingerprints: https://emudhra.we-have-a-problem.com/roots.json
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import importlib
+import os
+from pathlib import Path
+import re
+import ssl
+import sys
+
+
+BLOCKED_ROOTS = {
+    "86a1ecba089c4a8d3bbe2734c612ba341d813e043cf9e8a862cd5c57a36bbe6b": "emSign ECC Root CA - G3",
+    "d7a7a0fb5d7e2731d771e9484ebcdef71d5f0c3e0a2948782bc83ee0ea699ef4": "AAA Certificate Services",
+    "7dd78d5f4f13459a83dff9abbba62edbaf6f2d102bf257fd712f4d9f2746ed8d": "emSign Root TLS CA - G3",
+    "f2edaaff3d9b701fb4d14c9f285f8c0bad90fc3bcc1fa07d47f4718edaba34a5": "emSign Root CS CA - G3",
+}
+
+
+def check_bundle(path: Path) -> None:
+    """Raise on an unreadable, empty, malformed, or affected CA bundle."""
+    context = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
+    context.load_verify_locations(cafile=str(path))
+    certificates = context.get_ca_certs(binary_form=True)
+    if not certificates:
+        raise ValueError("no CA certificates")
+    blocked = {
+        BLOCKED_ROOTS[fingerprint]
+        for certificate in certificates
+        if (fingerprint := hashlib.sha256(certificate).hexdigest()) in BLOCKED_ROOTS
+    }
+    if blocked:
+        raise ValueError("affected roots: " + ", ".join(sorted(blocked)))
+
+
+def system_paths() -> list[Path]:
+    """Inspect both the effective OpenSSL CA file and hashed directory entries."""
+    defaults = ssl.get_default_verify_paths()
+    paths = [Path(defaults.cafile)] if defaults.cafile else []
+    # get_default_verify_paths() can report None for a colon-separated
+    # SSL_CERT_DIR even though OpenSSL consumes each directory in that list.
+    capath = os.environ.get(defaults.openssl_capath_env, defaults.capath)
+    if capath:
+        for directory in filter(None, capath.split(os.pathsep)):
+            paths.extend(
+                path
+                for path in Path(directory).iterdir()
+                if re.fullmatch(r"[0-9a-fA-F]{8}\.[0-9]+", path.name) and path.is_file()
+            )
+    if not paths:
+        raise ValueError("no effective OpenSSL PEM CA store found")
+    return paths
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("bundles", nargs="*", type=Path)
+    parser.add_argument("--system", action="store_true", help="check effective OpenSSL PEM stores")
+    parser.add_argument("--python", action="store_true", help="check certifi and pip's separate vendored bundle")
+    args = parser.parse_args(argv)
+    if not (args.bundles or args.system or args.python):
+        parser.error("select --system, --python, or explicit PEM bundle paths")
+    try:
+        paths = list(args.bundles)
+        if args.system:
+            paths.extend(system_paths())
+        if args.python:
+            for name in ("certifi", "pip._vendor.certifi"):
+                paths.append(Path(importlib.import_module(name).where()))
+        paths = list(dict.fromkeys(path.resolve() for path in paths))
+        errors = []
+        for path in paths:
+            try:
+                check_bundle(path)
+            except (OSError, ValueError, ssl.SSLError) as exc:
+                errors.append(f"{path}: {exc}")
+        if errors:
+            raise ValueError("\n".join(errors))
+    except (ImportError, OSError, ValueError, ssl.SSLError) as exc:
+        print(str(exc), file=sys.stderr)
+        return 1
+    print(f"Validated {len(paths)} CA bundle file(s): no eMudhra incident roots")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/start-macos.sh b/start-macos.sh
index 3e9048547..b9178792f 100755
--- a/start-macos.sh
+++ b/start-macos.sh
@@ -140,11 +140,11 @@ if [ ! -x "$VENV_PY" ] || ! "$VENV_PY" -m pip --version >/dev/null 2>&1; then
     echo "▶ Creating Python environment…"
     "$PY" -m venv venv
 fi
-REQ_HASH="$(md5 -q requirements.txt 2>/dev/null || md5sum requirements.txt | cut -d' ' -f1)"
+REQ_HASH="$("$VENV_PY" -c 'import hashlib, pathlib; print(hashlib.sha256(b"".join(pathlib.Path(p).read_bytes() for p in ("requirements.txt", "requirements-bootstrap.txt"))).hexdigest())')"
 REQ_HASH_FILE="venv/.requirements_hash"
 if [ ! -f "$REQ_HASH_FILE" ] || [ "$REQ_HASH" != "$(cat "$REQ_HASH_FILE" 2>/dev/null)" ]; then
   echo "▶ Installing Python packages (first run downloads a few — can take a few minutes)…"
-  "$VENV_PY" -m pip install --quiet --upgrade pip
+  "$VENV_PY" -m pip install --quiet --require-hashes --only-binary=:all: --no-deps -r requirements-bootstrap.txt
   # Not --quiet: this is the slow step, so show progress (and any real errors).
   "$VENV_PY" -m pip install -r requirements.txt
   echo "$REQ_HASH" > "$REQ_HASH_FILE"
diff --git a/tests/fixtures/ca-trust/README.md b/tests/fixtures/ca-trust/README.md
new file mode 100644
index 000000000..47e440ac1
--- /dev/null
+++ b/tests/fixtures/ca-trust/README.md
@@ -0,0 +1,5 @@
+# CA trust regression fixtures
+
+The public CA certificates embedded in `tests/test_ca_trust.py` exercise the October 2026 eMudhra trust-store check. They contain no private keys. `emsign-g3.pem` and `aaa.pem` are the incident's affected trust anchors; `emsign-g1.pem` is an unaffected emSign anchor that must remain usable. The test creates temporary PEM files from these public constants. The certificate fingerprints are the factual identity of each fixture.
+
+Sources: the [incident root list](https://emudhra.we-have-a-problem.com/roots.json) and the public Mozilla root certificates distributed in Debian's `ca-certificates` package. Behavioral chain verification should also cover the incident site's separate [twelve published server chains](https://emudhra.we-have-a-problem.com/chains.zip).
diff --git a/tests/test_ca_trust.py b/tests/test_ca_trust.py
new file mode 100644
index 000000000..b8e7b1bb0
--- /dev/null
+++ b/tests/test_ca_trust.py
@@ -0,0 +1,168 @@
+"""Offline regressions for incident roots, unaffected roots, and CA directories."""
+
+import contextlib
+import importlib.util
+import io
+import os
+from pathlib import Path
+import ssl
+import tempfile
+import unittest
+from unittest.mock import patch
+
+
+ROOT = Path(__file__).resolve().parents[1]
+SPEC = importlib.util.spec_from_file_location("check_ca_trust", ROOT / "scripts/check_ca_trust.py")
+checker = importlib.util.module_from_spec(SPEC)
+SPEC.loader.exec_module(checker)
+
+
+class CATrustTests(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):
+        # Public certificate data is embedded below. Tests create temporary
+        # PEM files from these constants; no fixture contains a private key.
+        cls.temporary = tempfile.TemporaryDirectory()
+        cls.fixtures = Path(cls.temporary.name)
+        for name, pem in PUBLIC_CERTIFICATES.items():
+            (cls.fixtures / name).write_text(pem)
+
+    @classmethod
+    def tearDownClass(cls):
+        cls.temporary.cleanup()
+
+    def test_unaffected_emsign_root_remains_usable(self):
+        checker.check_bundle(self.fixtures / "emsign-g1.pem")
+
+    def test_compromised_emsign_path_is_rejected(self):
+        with self.assertRaisesRegex(ValueError, "emSign ECC Root CA - G3"):
+            checker.check_bundle(self.fixtures / "emsign-g3.pem")
+
+    def test_aaa_cross_sign_path_is_rejected(self):
+        with self.assertRaisesRegex(ValueError, "AAA Certificate Services"):
+            checker.check_bundle(self.fixtures / "aaa.pem")
+
+    def test_mixed_bundle_does_not_hide_an_affected_root(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            bundle = Path(tmp) / "mixed.pem"
+            bundle.write_bytes((self.fixtures / "emsign-g1.pem").read_bytes() + (self.fixtures / "aaa.pem").read_bytes())
+            with self.assertRaisesRegex(ValueError, "AAA Certificate Services"):
+                checker.check_bundle(bundle)
+
+    def test_empty_malformed_and_missing_bundles_fail_closed(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            for content in ("", "not a certificate"):
+                path = Path(tmp) / "bad.pem"
+                path.write_text(content)
+                with self.subTest(content=content), self.assertRaises((ssl.SSLError, ValueError)):
+                    checker.check_bundle(path)
+            with self.assertRaises(OSError):
+                checker.check_bundle(Path(tmp) / "missing.pem")
+
+    def test_safe_cafile_does_not_hide_stale_hashed_directory(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            directory = Path(tmp)
+            (directory / "14bc7599.0").symlink_to(self.fixtures / "emsign-g3.pem")
+            defaults = ssl.get_default_verify_paths()._replace(
+                cafile=str(self.fixtures / "emsign-g1.pem"), capath=str(directory)
+            )
+            errors = io.StringIO()
+            with patch.object(checker.ssl, "get_default_verify_paths", return_value=defaults), patch.dict(
+                os.environ, {defaults.openssl_capath_env: str(directory)}
+            ):
+                with contextlib.redirect_stderr(errors):
+                    result = checker.main(["--system"])
+            self.assertEqual(result, 1)
+            self.assertIn("emSign ECC Root CA - G3", errors.getvalue())
+
+    def test_multiple_ca_directories_are_all_checked(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            clean, stale = Path(tmp) / "clean", Path(tmp) / "stale"
+            clean.mkdir()
+            stale.mkdir()
+            (stale / "ee64a828.0").symlink_to(self.fixtures / "aaa.pem")
+            defaults = ssl.get_default_verify_paths()._replace(
+                cafile=str(self.fixtures / "emsign-g1.pem"), capath=None
+            )
+            errors = io.StringIO()
+            with patch.object(checker.ssl, "get_default_verify_paths", return_value=defaults), patch.dict(
+                os.environ, {defaults.openssl_capath_env: os.pathsep.join(map(str, (clean, stale)))}
+            ):
+                with contextlib.redirect_stderr(errors):
+                    result = checker.main(["--system"])
+            self.assertEqual(result, 1)
+            self.assertIn("AAA Certificate Services", errors.getvalue())
+
+
+# Public Mozilla CA certificates; provenance: tests/fixtures/ca-trust/README.md.
+PUBLIC_CERTIFICATES = {
+    'aaa.pem': """-----BEGIN CERTIFICATE-----
+MIIEMjCCAxqgAwIBAgIBATANBgkqhkiG9w0BAQUFADB7MQswCQYDVQQGEwJHQjEb
+MBkGA1UECAwSR3JlYXRlciBNYW5jaGVzdGVyMRAwDgYDVQQHDAdTYWxmb3JkMRow
+GAYDVQQKDBFDb21vZG8gQ0EgTGltaXRlZDEhMB8GA1UEAwwYQUFBIENlcnRpZmlj
+YXRlIFNlcnZpY2VzMB4XDTA0MDEwMTAwMDAwMFoXDTI4MTIzMTIzNTk1OVowezEL
+MAkGA1UEBhMCR0IxGzAZBgNVBAgMEkdyZWF0ZXIgTWFuY2hlc3RlcjEQMA4GA1UE
+BwwHU2FsZm9yZDEaMBgGA1UECgwRQ29tb2RvIENBIExpbWl0ZWQxITAfBgNVBAMM
+GEFBQSBDZXJ0aWZpY2F0ZSBTZXJ2aWNlczCCASIwDQYJKoZIhvcNAQEBBQADggEP
+ADCCAQoCggEBAL5AnfRu4ep2hxxNRUSOvkbIgwadwSr+GB+O5AL686tdUIoWMQua
+BtDFcCLNSS1UY8y2bmhGC1Pqy0wkwLxyTurxFa70VJoSCsN6sjNg4tqJVfMiWPPe
+3M/vg4aijJRPn2jymJBGhCfHdr/jzDUsi14HZGWCwEiwqJH5YZ92IFCokcdmtet4
+YgNW8IoaE+oxox6gmf049vYnMlhvB/VruPsUK6+3qszWY19zjNoFmag4qMsXeDZR
+rOme9Hg6jc8P2ULimAyrL58OAd7vn5lJ8S3frHRNG5i1R8XlKdH5kBjHYpy+g8cm
+ez6KJcfA3Z3mNWgQIJ2P2N7Sw4ScDV7oL8kCAwEAAaOBwDCBvTAdBgNVHQ4EFgQU
+oBEKIz6W8Qfs4q8p74Klf9AwpLQwDgYDVR0PAQH/BAQDAgEGMA8GA1UdEwEB/wQF
+MAMBAf8wewYDVR0fBHQwcjA4oDagNIYyaHR0cDovL2NybC5jb21vZG9jYS5jb20v
+QUFBQ2VydGlmaWNhdGVTZXJ2aWNlcy5jcmwwNqA0oDKGMGh0dHA6Ly9jcmwuY29t
+b2RvLm5ldC9BQUFDZXJ0aWZpY2F0ZVNlcnZpY2VzLmNybDANBgkqhkiG9w0BAQUF
+AAOCAQEACFb8AvCb6P+k+tZ7xkSAzk/ExfYAWMymtrwUSWgEdujm7l3sAg9g1o1Q
+GE8mTgHj5rCl7r+8dFRBv/38ErjHT1r0iWAFf2C3BUrz9vHCv8S5dIa2LX1rzNLz
+Rt0vxuBqw8M0Ayx9lt1awg6nCpnBBYurDC/zXDrPbDdVCYfeU0BsWO/8tqtlbgT2
+G9w84FoVxp7Z8VlIMCFlA2zs6SFz7JsDoeA3raAVGI/6ugLOpyypEBMs1OUIJqsi
+l2D4kF501KKaU73yqWjgom7C12yxow+ev+to51byrvLjKzg6CYG1a4XXvi3tPxq3
+smPi9WIsgtRqAEFQ8TmDn5XpNpaYbg==
+-----END CERTIFICATE-----
+""",
+    'emsign-g1.pem': """-----BEGIN CERTIFICATE-----
+MIIDlDCCAnygAwIBAgIKMfXkYgxsWO3W2DANBgkqhkiG9w0BAQsFADBnMQswCQYD
+VQQGEwJJTjETMBEGA1UECxMKZW1TaWduIFBLSTElMCMGA1UEChMcZU11ZGhyYSBU
+ZWNobm9sb2dpZXMgTGltaXRlZDEcMBoGA1UEAxMTZW1TaWduIFJvb3QgQ0EgLSBH
+MTAeFw0xODAyMTgxODMwMDBaFw00MzAyMTgxODMwMDBaMGcxCzAJBgNVBAYTAklO
+MRMwEQYDVQQLEwplbVNpZ24gUEtJMSUwIwYDVQQKExxlTXVkaHJhIFRlY2hub2xv
+Z2llcyBMaW1pdGVkMRwwGgYDVQQDExNlbVNpZ24gUm9vdCBDQSAtIEcxMIIBIjAN
+BgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAk0u76WaK7p1b1TST0Bsew+eeuGQz
+f2N4aLTNLnF115sgxk0pvLZoYIr3IZpWNVrzdr3YzZr/k1ZLpVkGoZM0Kd0WNHVO
+8oG0x5ZOrRkVUkr+PHB1cM2vK6sVmjM8qrOLqs1D/fXqcP/tzxE7lM5OMhbTI0Aq
+d7OvPAEsbO2ZLIvZTmmYsvePQbAyeGHWDV/D+qJAkh1cF+ZwPjXnorfCYuKrpDhM
+tTk1b+oDafo6VGiFbdbyL0NVHpENDtjVaqSW0RM8LHhQ6DqS0hdW5TUaQBw+jSzt
+Od9C4INBdN+jzcKGYEho42kLVACL5HZpIQ15TjQIXhTCzLG3rdd8cIrHhQIDAQAB
+o0IwQDAdBgNVHQ4EFgQU++8Nhp6w492pufEhF38+/PB3KxowDgYDVR0PAQH/BAQD
+AgEGMA8GA1UdEwEB/wQFMAMBAf8wDQYJKoZIhvcNAQELBQADggEBAFn/8oz1h31x
+PaOfG1vR2vjTnGs2vZupYeveFix0PZ7mddrXuqe8QhfnPZHr5X3dPpzxz5KsbEjM
+wiI/aTvFthUvozXGaCocV685743QNcMYDHsAVhzNixl03r4PEuDQqqE/AjSxcM6d
+GNYIAwlG7mDgfrbESQRRfXBgvKqy/3lyeqYdPV8q+Mri/Tm3R7nrft8EI6/6nAYH
+6ftjk4BAtcZsCjEozgyfz7MjNYBBjWzEN3uBL4ChQEKF6dk4jeihU80Bv2noWgby
+RQuQ+q7hv53yrlc8pa6yVvSLZUDp/TGBLPQ5Cdjua6e0ph0VpZj3AYHYhX3zUVxx
+iN66zB+Afko=
+-----END CERTIFICATE-----
+""",
+    'emsign-g3.pem': """-----BEGIN CERTIFICATE-----
+MIICTjCCAdOgAwIBAgIKPPYHqWhwDtqLhDAKBggqhkjOPQQDAzBrMQswCQYDVQQG
+EwJJTjETMBEGA1UECxMKZW1TaWduIFBLSTElMCMGA1UEChMcZU11ZGhyYSBUZWNo
+bm9sb2dpZXMgTGltaXRlZDEgMB4GA1UEAxMXZW1TaWduIEVDQyBSb290IENBIC0g
+RzMwHhcNMTgwMjE4MTgzMDAwWhcNNDMwMjE4MTgzMDAwWjBrMQswCQYDVQQGEwJJ
+TjETMBEGA1UECxMKZW1TaWduIFBLSTElMCMGA1UEChMcZU11ZGhyYSBUZWNobm9s
+b2dpZXMgTGltaXRlZDEgMB4GA1UEAxMXZW1TaWduIEVDQyBSb290IENBIC0gRzMw
+djAQBgcqhkjOPQIBBgUrgQQAIgNiAAQjpQy4LRL1KPOxst3iAhKAnjlfSU2fySU0
+WXTsuwYc58Byr+iuL+FBVIcUqEqy6HyC5ltqtdyzdc6LBtCGI79G1Y4PPwT01xyS
+fvalY8L1X44uT6EYGQIrMgqCZH0Wk9GjQjBAMB0GA1UdDgQWBBR8XQKEE9TMipuB
+zhccLikenEhjQjAOBgNVHQ8BAf8EBAMCAQYwDwYDVR0TAQH/BAUwAwEB/zAKBggq
+hkjOPQQDAwNpADBmAjEAvvNhzwIQHWSVB7gYboiFBS+DCBeQyh+KTOgNG3qxrdWB
+CUfvO6wIBHxcmbHtRwfSAjEAnbpV/KlK6O3t5nYBQnvI+GDZjVGLVTv7jHvrZQnD
++JbNR6iC8hZVdyR+EhCVBCyj
+-----END CERTIFICATE-----
+""",
+}
+
+
+if __name__ == "__main__":
+    unittest.main()

From c4fdaf59b3d74377b191938b028a710ee5aad5c7 Mon Sep 17 00:00:00 2001
From: RaresKeY <158580472+RaresKeY@users.noreply.github.com>
Date: Wed, 21 Oct 2026 18:59:02 +0000
Subject: [PATCH 38/53] fix(tls): accept hashed non-CA certificates during
 trust checks

---
 scripts/check_ca_trust.py         |  7 +++++--
 tests/fixtures/ca-trust/README.md |  2 +-
 tests/test_ca_trust.py            | 24 ++++++++++++++++++++++++
 3 files changed, 30 insertions(+), 3 deletions(-)

diff --git a/scripts/check_ca_trust.py b/scripts/check_ca_trust.py
index c675dc6f3..36457fe17 100644
--- a/scripts/check_ca_trust.py
+++ b/scripts/check_ca_trust.py
@@ -30,9 +30,12 @@ def check_bundle(path: Path) -> None:
     """Raise on an unreadable, empty, malformed, or affected CA bundle."""
     context = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
     context.load_verify_locations(cafile=str(path))
+    # A hashed OpenSSL directory can include valid non-CA certificates (for
+    # example Ubuntu's snakeoil server certificate). get_ca_certs() omits them;
+    # use the total X.509 count to distinguish these from an empty store.
+    if not context.cert_store_stats()["x509"]:
+        raise ValueError("no certificates")
     certificates = context.get_ca_certs(binary_form=True)
-    if not certificates:
-        raise ValueError("no CA certificates")
     blocked = {
         BLOCKED_ROOTS[fingerprint]
         for certificate in certificates
diff --git a/tests/fixtures/ca-trust/README.md b/tests/fixtures/ca-trust/README.md
index 47e440ac1..98b57d82d 100644
--- a/tests/fixtures/ca-trust/README.md
+++ b/tests/fixtures/ca-trust/README.md
@@ -1,5 +1,5 @@
 # CA trust regression fixtures
 
-The public CA certificates embedded in `tests/test_ca_trust.py` exercise the October 2026 eMudhra trust-store check. They contain no private keys. `emsign-g3.pem` and `aaa.pem` are the incident's affected trust anchors; `emsign-g1.pem` is an unaffected emSign anchor that must remain usable. The test creates temporary PEM files from these public constants. The certificate fingerprints are the factual identity of each fixture.
+The public certificates embedded in `tests/test_ca_trust.py` exercise the October 2026 eMudhra trust-store check. They contain no private keys. `emsign-g3.pem` and `aaa.pem` are the incident's affected trust anchors; `emsign-g1.pem` is an unaffected emSign anchor that must remain usable. `localhost-leaf.pem` is a synthetic self-signed Ed25519 server certificate with `CA:FALSE`, generated solely to reproduce hashed non-CA certificates found in Ubuntu's OpenSSL directory; its private key was discarded. The test creates temporary PEM files from these public constants. The certificate fingerprints are the factual identity of each fixture.
 
 Sources: the [incident root list](https://emudhra.we-have-a-problem.com/roots.json) and the public Mozilla root certificates distributed in Debian's `ca-certificates` package. Behavioral chain verification should also cover the incident site's separate [twelve published server chains](https://emudhra.we-have-a-problem.com/chains.zip).
diff --git a/tests/test_ca_trust.py b/tests/test_ca_trust.py
index b8e7b1bb0..88a5a343f 100644
--- a/tests/test_ca_trust.py
+++ b/tests/test_ca_trust.py
@@ -75,6 +75,20 @@ class CATrustTests(unittest.TestCase):
             self.assertEqual(result, 1)
             self.assertIn("emSign ECC Root CA - G3", errors.getvalue())
 
+    def test_hashed_non_ca_certificate_does_not_reject_clean_store(self):
+        # Ubuntu's OpenSSL directory can also hash ssl-cert-snakeoil.pem.
+        # A valid server certificate has no CA entries in get_ca_certs().
+        with tempfile.TemporaryDirectory() as tmp:
+            directory = Path(tmp)
+            (directory / "ce275665.0").symlink_to(self.fixtures / "localhost-leaf.pem")
+            defaults = ssl.get_default_verify_paths()._replace(
+                cafile=str(self.fixtures / "emsign-g1.pem"), capath=str(directory)
+            )
+            with patch.object(checker.ssl, "get_default_verify_paths", return_value=defaults), patch.dict(
+                os.environ, {defaults.openssl_capath_env: str(directory)}
+            ), contextlib.redirect_stdout(io.StringIO()):
+                self.assertEqual(checker.main(["--system"]), 0)
+
     def test_multiple_ca_directories_are_all_checked(self):
         with tempfile.TemporaryDirectory() as tmp:
             clean, stale = Path(tmp) / "clean", Path(tmp) / "stale"
@@ -96,6 +110,16 @@ class CATrustTests(unittest.TestCase):
 
 # Public Mozilla CA certificates; provenance: tests/fixtures/ca-trust/README.md.
 PUBLIC_CERTIFICATES = {
+    'localhost-leaf.pem': """-----BEGIN CERTIFICATE-----
+MIIBOTCB7KADAgECAhRcVxnOQNEFWf92K4dm4I8ChyjVMzAFBgMrZXAwFDESMBAG
+A1UEAwwJbG9jYWxob3N0MB4XDTI2MTAyMTE4NTgwN1oXDTM2MTAxODE4NTgwN1ow
+FDESMBAGA1UEAwwJbG9jYWxob3N0MCowBQYDK2VwAyEARglphvNgp9qRCESLHnuu
+W8VC5urdZl+YgS+Ux1BoLryjUDBOMB0GA1UdDgQWBBSaEckyR/76lX3a5Ijh8B42
+oJwN1DAfBgNVHSMEGDAWgBSaEckyR/76lX3a5Ijh8B42oJwN1DAMBgNVHRMBAf8E
+AjAAMAUGAytlcANBAJkq9ayy+d4AUZnjhWM31rFke5DT+l9QFcPl34+dpVhqJV/L
+m4IpPHYagqrBRHn9Dv/C8qYyPBKnAwJRpNptsgw=
+-----END CERTIFICATE-----
+""",
     'aaa.pem': """-----BEGIN CERTIFICATE-----
 MIIEMjCCAxqgAwIBAgIBATANBgkqhkiG9w0BAQUFADB7MQswCQYDVQQGEwJHQjEb
 MBkGA1UECAwSR3JlYXRlciBNYW5jaGVzdGVyMRAwDgYDVQQHDAdTYWxmb3JkMRow

From 5d0a219edee63039f48cb7e2c98188a17d7571ec Mon Sep 17 00:00:00 2001
From: RaresKeY <158580472+RaresKeY@users.noreply.github.com>
Date: Wed, 21 Oct 2026 20:09:54 +0000
Subject: [PATCH 39/53] fix: distrust incident certificates in Chromium and
 gRPC

---
 Dockerfile                       | 11 ++++++++-
 docker/chromium-ca-policy.md     | 20 ++++++++++++++++
 docker/chromium-emudhra.json     | 12 ++++++++++
 docs/tls-trust.md                | 10 +++++---
 scripts/check_ca_trust.py        | 21 ++++++++++++++--
 tests/test_ca_trust.py           | 36 ++++++++++++++++++++++++++++
 tests/test_chromium_ca_policy.py | 41 ++++++++++++++++++++++++++++++++
 7 files changed, 145 insertions(+), 6 deletions(-)
 create mode 100644 docker/chromium-ca-policy.md
 create mode 100644 docker/chromium-emudhra.json
 create mode 100644 tests/test_chromium_ca_policy.py

diff --git a/Dockerfile b/Dockerfile
index 2e49c6ed6..28653ab7c 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -61,7 +61,12 @@ RUN python /usr/local/bin/check-ca-trust.py --system
 COPY requirements-bootstrap.txt /tmp/requirements-bootstrap.txt
 RUN python -m pip install --no-cache-dir --require-hashes --only-binary=:all: --no-deps -r /tmp/requirements-bootstrap.txt \
     && python /usr/local/bin/check-ca-trust.py --python
-ENV NODE_OPTIONS=--use-openssl-ca
+ENV NODE_OPTIONS=--use-openssl-ca \
+    GRPC_DEFAULT_SSL_ROOTS_FILE_PATH=/etc/ssl/certs/ca-certificates.crt
+
+# Chromium has a separate root store. Distrust the compromised intermediate
+# public keys explicitly, including cross-signs, without waiting for CRL updates.
+COPY docker/chromium-emudhra.json /etc/chromium/policies/managed/odysseus-emudhra.json
 
 # Private browser automation wrapper used by the native `private_browser` tool.
 # Chromium is installed above, so agent-browser can drive the existing browser
@@ -123,6 +128,10 @@ COPY --from=realesrgan-wheels /wheels/ /tmp/odysseus-wheels/
 RUN pip install --no-cache-dir --no-deps /tmp/odysseus-wheels/*.whl \
     && rm -rf /tmp/odysseus-wheels
 
+# Check gRPC's effective defaults after all Python dependencies are installed.
+# Its wheel can retain affected roots even when pip/certifi are current.
+RUN python /usr/local/bin/check-ca-trust.py --system --python --grpc
+
 # Copy app code
 COPY . .
 # Require the redistribution notices in the image build context.
diff --git a/docker/chromium-ca-policy.md b/docker/chromium-ca-policy.md
new file mode 100644
index 000000000..b4852ac3a
--- /dev/null
+++ b/docker/chromium-ca-policy.md
@@ -0,0 +1,20 @@
+# Chromium incident distrust policy
+
+`chromium-emudhra.json` is installed in the Docker image at `/etc/chromium/policies/managed/odysseus-emudhra.json`. Chromium 132 and later support `CADistrustedCertificates`: a list of base64-encoded DER X.509 certificates whose public keys must not be accepted for TLS server authentication. Matching is by SubjectPublicKeyInfo (SPKI), so one certificate per compromised key also blocks its cross-signs. This policy adds no trust, disables no certificate checks, and does not require a revocation-list download. Native browsers and other browser distributions require separately managed installation of the appropriate policy.
+
+Policy semantics: [Chromium's version-155 definition](https://github.com/chromium/chromium/blob/155.0.8059.79/components/policy/resources/templates/policy_definitions/CertificateManagement/CADistrustedCertificates.yaml). Linux installation paths: [Chromium policy documentation](https://www.chromium.org/administrators/configuring-policy-for-extensions/#linux).
+
+Public certificate source, retrieved 2026-10-21: [incident intermediate inventory](https://emudhra.we-have-a-problem.com/impacted-intermediates.json). Its downloaded JSON has SHA-256 `f67b3abe9b4879f4e91874ed041beccd71257f1db41c588c724ccf12aa90c59e`. Each selected certificate's DER fingerprint and public-key fingerprint were checked against that inventory before inclusion. The eight unique keys below are covered, including the code-signing intermediate keys listed in the incident. The policy contains only public certificates; no private key is included.
+
+| Intermediate | SHA-256 of DER SPKI |
+| --- | --- |
+| EM OV TLS CA - G3B | `43bffa19d6ef651451f6841e019931e96f6f2eaeff28ab4b6f1ce4576de2717b` |
+| EM DV TLS CA - G3C | `49dd353dc2b919a3770645117d0e60c16115e7d1bc259eefe734b00ea434fe5f` |
+| EM EV TLS CA - G3C | `5c0660a2b164910d8ff589c18e14552e9e0ec237dcefe2cb736d41a4811f81a0` |
+| EM OV TLS CA - G3C | `63ecefee431d49523bc1136c4e72d0206a477086caf606cd5cf025686c109cf8` |
+| EM OV CS CA - G3C | `92c063d67e8f14db71d288e11266ffdaf69cbf115f7bab14f3bc2f68d25e0e30` |
+| EM EV TLS CA - G3B | `e0254c7fcdc265e2f0f8a428dabb75ab4ae039b4872d62f5ee57f0877d5a8a41` |
+| EM DV TLS CA - G3B | `ebed6475c2c2d80fcb199f3fe8dd6e6b3ce60b77eb15d4e42c3dec0c6f5b5105` |
+| EM OV CS CA - G3B | `ec4ffa1ad0ac88081314b7aaffef6a91f97cd57291bb5ba686c5415f5eb4f6b6` |
+
+`tests/test_chromium_ca_policy.py` verifies that the policy distrusts exactly these eight keys using valid intermediate CA certificates and adds no trust settings. Changes to the encoded material need a fresh source/fingerprint check and behavioral validation: all twelve published incident HTTPS chains must be rejected by the actual Chromium binary while ordinary HTTPS still succeeds. Confirm loading and any policy errors at `chrome://policy`. Do not treat a passing PEM-store check as a browser-policy check.
diff --git a/docker/chromium-emudhra.json b/docker/chromium-emudhra.json
new file mode 100644
index 000000000..104f82f60
--- /dev/null
+++ b/docker/chromium-emudhra.json
@@ -0,0 +1,12 @@
+{
+  "CADistrustedCertificates": [
+    "MIIDZjCCAu2gAwIBAgIPbK2jZ/scEACIEg6iAtVoMAoGCCqGSM49BAMDMFYxCzAJBgNVBAYTAklOMSUwIwYDVQQKDBxlTXVkaHJhIFRlY2hub2xvZ2llcyBMaW1pdGVkMSAwHgYDVQQDDBdlbVNpZ24gUm9vdCBUTFMgQ0EgLSBHMzAeFw0yNTA0MzAxNjAwMTJaFw00MDA0MjgxODMwMDBaMD8xCzAJBgNVBAYTAk5MMRMwEQYDVQQKDAplTXVkaHJhIEJWMRswGQYDVQQDDBJFTSBPViBUTFMgQ0EgLSBHM0IwdjAQBgcqhkjOPQIBBgUrgQQAIgNiAARziXqg6zz9yosSQC/68KvE4SErr43ud4rJ7i1tuD+sKAxeBWOK56Ks1xwyKo42HN659pxDArndjXPRzGyqsswK7k4hbOl53VGKSvS2JuVoTN1lgDftDIVOTMEvTPhkbQ2jggGWMIIBkjAfBgNVHSMEGDAWgBThOqshfPHjTVSu1HK3/YtZQiCQVDAdBgNVHQ4EFgQUm9hlUa/n5yw3rQjuaRnZvzeErgowHQYDVR0lBBYwFAYIKwYBBQUHAwEGCCsGAQUFBwMCMF0GA1UdIARWMFQwOQYLKwYBBAGDjiEBAAEwKjAoBggrBgEFBQcCARYcaHR0cDovL3JlcG9zaXRvcnkuZW1zaWduLmNvbTANBgsrBgEEAYOOIQECbjAIBgZngQwBAgIwdQYIKwYBBQUHAQEEaTBnMCQGCCsGAQUFBzABhhhodHRwOi8vb2NzcC1iLmVtc2lnbi5jb20wPwYIKwYBBQUHMAKGM2h0dHA6Ly9yZXBvc2l0b3J5LmVtc2lnbi5jb20vY2VydHMvRU1PVlRMU0NBRzNCLnA3YzA3BgNVHR8EMDAuMCygKqAohiZodHRwOi8vY3JsLmVtc2lnbi5jb20vP3Jvb3R0bHNjYWczLmNybDAOBgNVHQ8BAf8EBAMCAQYwEgYDVR0TAQH/BAgwBgEB/wIBADAKBggqhkjOPQQDAwNnADBkAjBAk+5BizdJhrED3wb7F2Gm7bWI60dlNd075nghT2TrR4NWKZtJZcbc28xxIY/NONICMF6mPdsjosaqmvEMWqKcBh4vsIvXSKnQj5o8zrFB4oKS+accjYTe8Dz3bQjauvy9uw==",
+    "MIIDaDCCAu6gAwIBAgIPWIsuPCu4zaE+GhIJJUMhMAoGCCqGSM49BAMDMFYxCzAJBgNVBAYTAklOMSUwIwYDVQQKDBxlTXVkaHJhIFRlY2hub2xvZ2llcyBMaW1pdGVkMSAwHgYDVQQDDBdlbVNpZ24gUm9vdCBUTFMgQ0EgLSBHMzAeFw0yNTA0MzAxNTM1MDlaFw00MDA0MjgxODMwMDBaMEAxCzAJBgNVBAYTAlVTMRQwEgYDVQQKDAtlTXVkaHJhIEluYzEbMBkGA1UEAwwSRU0gRFYgVExTIENBIC0gRzNDMHYwEAYHKoZIzj0CAQYFK4EEACIDYgAEOnp4YsjETTJN3WkDOmeCwO/u/kBV5ooSP6A3G6O9kZRRTuFypDPjYw8CvRiAN9nlFJ+bd9uUooHfmHsv6oiLdL3+j9pMEJnubKGVZv4+8OX2sJpVbMyLpQVh3xsqRB0Bo4IBljCCAZIwHwYDVR0jBBgwFoAU4TqrIXzx401UrtRyt/2LWUIgkFQwHQYDVR0OBBYEFK5+EFw8KZbBqEcnBVnx4D3U5QrzMB0GA1UdJQQWMBQGCCsGAQUFBwMBBggrBgEFBQcDAjBdBgNVHSAEVjBUMDkGCysGAQQBg44hAQABMCowKAYIKwYBBQUHAgEWHGh0dHA6Ly9yZXBvc2l0b3J5LmVtc2lnbi5jb20wDQYLKwYBBAGDjiEBAmQwCAYGZ4EMAQIBMHUGCCsGAQUFBwEBBGkwZzAkBggrBgEFBQcwAYYYaHR0cDovL29jc3AtYy5lbXNpZ24uY29tMD8GCCsGAQUFBzAChjNodHRwOi8vcmVwb3NpdG9yeS5lbXNpZ24uY29tL2NlcnRzL0VNRFZUTFNDQUczQy5wN2MwNwYDVR0fBDAwLjAsoCqgKIYmaHR0cDovL2NybC5lbXNpZ24uY29tLz9yb290dGxzY2FnMy5jcmwwDgYDVR0PAQH/BAQDAgEGMBIGA1UdEwEB/wQIMAYBAf8CAQAwCgYIKoZIzj0EAwMDaAAwZQIxAMEN2HWMocbuWdy1d33pH6JpMvP/V/DIS5PtZbv1Q7TXEbxrcyxgyuddOJscYDJJlAIwB4sH1BpbScDzkdD4tJBSwrG/1Mx82vb8YaySehNuu1+1oXNdAEKwaJ0mVzScy2+6",
+    "MIIDaDCCAu6gAwIBAgIQAIAJkopkEHYBrwX6LxnxCTAKBggqhkjOPQQDAzBWMQswCQYDVQQGEwJJTjElMCMGA1UECgwcZU11ZGhyYSBUZWNobm9sb2dpZXMgTGltaXRlZDEgMB4GA1UEAwwXZW1TaWduIFJvb3QgVExTIENBIC0gRzMwHhcNMjUwNDMwMTUzOTMxWhcNNDAwNDI4MTgzMDAwWjBAMQswCQYDVQQGEwJVUzEUMBIGA1UECgwLZU11ZGhyYSBJbmMxGzAZBgNVBAMMEkVNIEVWIFRMUyBDQSAtIEczQzB2MBAGByqGSM49AgEGBSuBBAAiA2IABC1W6Cmm+4LGSkaX2WCvlR6QZ66R+SbTQwbaSKiq63hptqZ+bSdCbgRCqgOzbhmI3/Y2UU7hzwf1uks/8qBmRa59MdWGatMao9JG6wsxd+6Zy3VmxRbOdICKZo+R8MR/yqOCAZUwggGRMB8GA1UdIwQYMBaAFOE6qyF88eNNVK7Ucrf9i1lCIJBUMB0GA1UdDgQWBBSmJV6AqU2385Z8G8eR35K87kvrXzAdBgNVHSUEFjAUBggrBgEFBQcDAQYIKwYBBQUHAwIwXAYDVR0gBFUwUzA5BgsrBgEEAYOOIQEAATAqMCgGCCsGAQUFBwIBFhxodHRwOi8vcmVwb3NpdG9yeS5lbXNpZ24uY29tMA0GCysGAQQBg44hAQJ4MAcGBWeBDAEBMHUGCCsGAQUFBwEBBGkwZzAkBggrBgEFBQcwAYYYaHR0cDovL29jc3AtYy5lbXNpZ24uY29tMD8GCCsGAQUFBzAChjNodHRwOi8vcmVwb3NpdG9yeS5lbXNpZ24uY29tL2NlcnRzL0VNRVZUTFNDQUczQy5wN2MwNwYDVR0fBDAwLjAsoCqgKIYmaHR0cDovL2NybC5lbXNpZ24uY29tLz9yb290dGxzY2FnMy5jcmwwDgYDVR0PAQH/BAQDAgEGMBIGA1UdEwEB/wQIMAYBAf8CAQAwCgYIKoZIzj0EAwMDaAAwZQIwBy1wTnzH4lXDTy2PD91ysLjvnlVN3JbJmc1BIMEU8TOLkYVHibMc9HeyonikFSfmAjEA6uE3QRxlrZTz/1/lXPTEMUhoauAtycagtlNFp79kjhvNa2/fAal1GNxsOutLnr0Y",
+    "MIIDaDCCAu6gAwIBAgIPKWkmwiejoVJjkrGUgqUEMAoGCCqGSM49BAMDMFYxCzAJBgNVBAYTAklOMSUwIwYDVQQKDBxlTXVkaHJhIFRlY2hub2xvZ2llcyBMaW1pdGVkMSAwHgYDVQQDDBdlbVNpZ24gUm9vdCBUTFMgQ0EgLSBHMzAeFw0yNTA0MzAxNTM3NDFaFw00MDA0MjgxODMwMDBaMEAxCzAJBgNVBAYTAlVTMRQwEgYDVQQKDAtlTXVkaHJhIEluYzEbMBkGA1UEAwwSRU0gT1YgVExTIENBIC0gRzNDMHYwEAYHKoZIzj0CAQYFK4EEACIDYgAEE4JRzVKskpjByKrZdzId65fnCb0LTKCspV3IrVHc/J0ViaFZfjpRIOHv1jHGPhg1ysrimGmmLhYx6KKBgatWYW3EXZGKvAnzqw5jz3kqpNztc4e+N7ulaVSfHAKycO1no4IBljCCAZIwHwYDVR0jBBgwFoAU4TqrIXzx401UrtRyt/2LWUIgkFQwHQYDVR0OBBYEFDTq6gzryQra+dDF4u2beMmHnhtsMB0GA1UdJQQWMBQGCCsGAQUFBwMBBggrBgEFBQcDAjBdBgNVHSAEVjBUMDkGCysGAQQBg44hAQABMCowKAYIKwYBBQUHAgEWHGh0dHA6Ly9yZXBvc2l0b3J5LmVtc2lnbi5jb20wDQYLKwYBBAGDjiEBAm4wCAYGZ4EMAQICMHUGCCsGAQUFBwEBBGkwZzAkBggrBgEFBQcwAYYYaHR0cDovL29jc3AtYy5lbXNpZ24uY29tMD8GCCsGAQUFBzAChjNodHRwOi8vcmVwb3NpdG9yeS5lbXNpZ24uY29tL2NlcnRzL0VNT1ZUTFNDQUczQy5wN2MwNwYDVR0fBDAwLjAsoCqgKIYmaHR0cDovL2NybC5lbXNpZ24uY29tLz9yb290dGxzY2FnMy5jcmwwDgYDVR0PAQH/BAQDAgEGMBIGA1UdEwEB/wQIMAYBAf8CAQAwCgYIKoZIzj0EAwMDaAAwZQIxAMSZt2xsPeumRdeSMSQ3CbzIZeQ/q7GDCWfeE1Pq+mhgA6gRM44cNVF3xJ+wsxJk+wIwFJbaDMokD8Ei6eNOiA8yUMYvfzQyngmrhZQMdPCK1SewrR794rSb9vGqxZzelQth",
+    "MIIDWzCCAuGgAwIBAgIPVEt/kiwxriIKSpIpFvbmMAoGCCqGSM49BAMDMFUxCzAJBgNVBAYTAklOMSUwIwYDVQQKDBxlTXVkaHJhIFRlY2hub2xvZ2llcyBMaW1pdGVkMR8wHQYDVQQDDBZlbVNpZ24gUm9vdCBDUyBDQSAtIEczMB4XDTI1MDQzMDE2Mzg0MFoXDTQwMDQyODE4MzAwMFowPzELMAkGA1UEBhMCVVMxFDASBgNVBAoMC2VNdWRocmEgSW5jMRowGAYDVQQDDBFFTSBPViBDUyBDQSAtIEczQzB2MBAGByqGSM49AgEGBSuBBAAiA2IABLnw4GNHAqacpqrdRDz9YsQbm6SyCSRpfXl052kaEm+5avs+NML9O8X0gwYfJl3CpYQ2NHMjUQQ2so8E84YjYwZ5gOJQPgJTLWVGI1pxZaJZoe9Jb3QbX97neHII5Lj676OCAYswggGHMB8GA1UdIwQYMBaAFGh0A/iFyo1UUFcdFuDI3kUNq80tMB0GA1UdDgQWBBTub3MpjW+/p7Mbw5U09hVWRHhmtzATBgNVHSUEDDAKBggrBgEFBQcDAzBeBgNVHSAEVzBVMDkGCysGAQQBg44hAQABMCowKAYIKwYBBQUHAgEWHGh0dHA6Ly9yZXBvc2l0b3J5LmVtc2lnbi5jb20wDgYMKwYBBAGDjiEBAoFIMAgGBmeBDAEEATB0BggrBgEFBQcBAQRoMGYwJAYIKwYBBQUHMAGGGGh0dHA6Ly9vY3NwLWMuZW1zaWduLmNvbTA+BggrBgEFBQcwAoYyaHR0cDovL3JlcG9zaXRvcnkuZW1zaWduLmNvbS9jZXJ0cy9FTU9WQ1NDQUczQy5wN2MwNgYDVR0fBC8wLTAroCmgJ4YlaHR0cDovL2NybC5lbXNpZ24uY29tLz9yb290Y3NjYWczLmNybDAOBgNVHQ8BAf8EBAMCAQYwEgYDVR0TAQH/BAgwBgEB/wIBADAKBggqhkjOPQQDAwNoADBlAjEA8yPg8sntOhLwV2QXJ5LEaKSpo/fnE3uOgTadK73fDhyjiqr0Io9GVuQTYqBPbQ2TAjBgeuApmBS486+iei03lRrp139dPw6k28jjGNvWsAU7A1N86J1zPJVDEyVH+nMAWC0=",
+    "MIIDaDCCAu2gAwIBAgIQAMfEHv6S2CXwXq6EGkqCwTAKBggqhkjOPQQDAzBWMQswCQYDVQQGEwJJTjElMCMGA1UECgwcZU11ZGhyYSBUZWNobm9sb2dpZXMgTGltaXRlZDEgMB4GA1UEAwwXZW1TaWduIFJvb3QgVExTIENBIC0gRzMwHhcNMjUwNDMwMTYwMzMxWhcNNDAwNDI4MTgzMDAwWjA/MQswCQYDVQQGEwJOTDETMBEGA1UECgwKZU11ZGhyYSBCVjEbMBkGA1UEAwwSRU0gRVYgVExTIENBIC0gRzNCMHYwEAYHKoZIzj0CAQYFK4EEACIDYgAEJduoWmTTl9oLEFLp6lRuSHvv6pydnWigxerc/u91ppu11vwB9Cv7ym60C81kwHZ+Nv/QXZeoE8WqDGyVMOec9fCGZGjxOAZCCqXIUYQLHiUlQOeQ5LZUw4Uu1krx6GV9o4IBlTCCAZEwHwYDVR0jBBgwFoAU4TqrIXzx401UrtRyt/2LWUIgkFQwHQYDVR0OBBYEFD7cINmJRpiHe4c/2IFHslwV2EcGMB0GA1UdJQQWMBQGCCsGAQUFBwMBBggrBgEFBQcDAjBcBgNVHSAEVTBTMDkGCysGAQQBg44hAQABMCowKAYIKwYBBQUHAgEWHGh0dHA6Ly9yZXBvc2l0b3J5LmVtc2lnbi5jb20wDQYLKwYBBAGDjiEBAngwBwYFZ4EMAQEwdQYIKwYBBQUHAQEEaTBnMCQGCCsGAQUFBzABhhhodHRwOi8vb2NzcC1iLmVtc2lnbi5jb20wPwYIKwYBBQUHMAKGM2h0dHA6Ly9yZXBvc2l0b3J5LmVtc2lnbi5jb20vY2VydHMvRU1FVlRMU0NBRzNCLnA3YzA3BgNVHR8EMDAuMCygKqAohiZodHRwOi8vY3JsLmVtc2lnbi5jb20vP3Jvb3R0bHNjYWczLmNybDAOBgNVHQ8BAf8EBAMCAQYwEgYDVR0TAQH/BAgwBgEB/wIBADAKBggqhkjOPQQDAwNpADBmAjEA9Jq999oaOUKhFwopw33iCmt0OHIn3gjT43GfuOHR/YckXdwoNdDAlIEhz0NgRO3/AjEAvY/a3OMvktIZLYjn+WLKmp0QhrIMV+e6EpS7j4GVeOKouNp6MN/P+ByGeiRMghzB",
+    "MIIDaDCCAu6gAwIBAgIQAKSu5njyM2K0wORgt3LyFDAKBggqhkjOPQQDAzBWMQswCQYDVQQGEwJJTjElMCMGA1UECgwcZU11ZGhyYSBUZWNobm9sb2dpZXMgTGltaXRlZDEgMB4GA1UEAwwXZW1TaWduIFJvb3QgVExTIENBIC0gRzMwHhcNMjUwNDMwMTU1NDA4WhcNNDAwNDI4MTgzMDAwWjA/MQswCQYDVQQGEwJOTDETMBEGA1UECgwKZU11ZGhyYSBCVjEbMBkGA1UEAwwSRU0gRFYgVExTIENBIC0gRzNCMHYwEAYHKoZIzj0CAQYFK4EEACIDYgAE557ZwEqXc8RzXlERHahawr1eZKs3S4DhLLwgOOweTw47gS/JhZ4eZ6+wTi+LyX90hbplqpEe6KTkW2LVzAPVa+Z4s8OMtNyTfKJGDiOEU8iSk10p1E+R4VYGtjzO2rRoo4IBljCCAZIwHwYDVR0jBBgwFoAU4TqrIXzx401UrtRyt/2LWUIgkFQwHQYDVR0OBBYEFOIeL+ccGTkOVUtiwSAkVzUkiiUUMB0GA1UdJQQWMBQGCCsGAQUFBwMBBggrBgEFBQcDAjBdBgNVHSAEVjBUMDkGCysGAQQBg44hAQABMCowKAYIKwYBBQUHAgEWHGh0dHA6Ly9yZXBvc2l0b3J5LmVtc2lnbi5jb20wDQYLKwYBBAGDjiEBAmQwCAYGZ4EMAQIBMHUGCCsGAQUFBwEBBGkwZzAkBggrBgEFBQcwAYYYaHR0cDovL29jc3AtYi5lbXNpZ24uY29tMD8GCCsGAQUFBzAChjNodHRwOi8vcmVwb3NpdG9yeS5lbXNpZ24uY29tL2NlcnRzL0VNRFZUTFNDQUczQi5wN2MwNwYDVR0fBDAwLjAsoCqgKIYmaHR0cDovL2NybC5lbXNpZ24uY29tLz9yb290dGxzY2FnMy5jcmwwDgYDVR0PAQH/BAQDAgEGMBIGA1UdEwEB/wQIMAYBAf8CAQAwCgYIKoZIzj0EAwMDaAAwZQIwLmsGXi6oFMJ2klkcEMXMug6gvxQWZWkewiDWVzQyl2L6z6DuQfPOIbh1grvdULDCAjEAxZvLlxUavG69J6wnSjC8XBbqNIQsJ6CE2QdNOe84Ptxb6VG8gt2TlfJbHii+KNvK",
+    "MIIDWzCCAuCgAwIBAgIPeBiTP4+FtGGaKzX7qD0KMAoGCCqGSM49BAMDMFUxCzAJBgNVBAYTAklOMSUwIwYDVQQKDBxlTXVkaHJhIFRlY2hub2xvZ2llcyBMaW1pdGVkMR8wHQYDVQQDDBZlbVNpZ24gUm9vdCBDUyBDQSAtIEczMB4XDTI1MDQzMDE2MDgyN1oXDTQwMDQyODE4MzAwMFowPjELMAkGA1UEBhMCTkwxEzARBgNVBAoMCmVNdWRocmEgQlYxGjAYBgNVBAMMEUVNIE9WIENTIENBIC0gRzNCMHYwEAYHKoZIzj0CAQYFK4EEACIDYgAEqrsPsGZqz88B+tUr/P1MK/LLPDSX3nOVDlgZth/mlQmHQcjEkUObNKBDHK/+W/m0wcjorgAB+fTcitgsWfNjnpbNbD1NsM7+wmw9YlF7N3YTcnQ/jordd7EAZPKr5eBQo4IBizCCAYcwHwYDVR0jBBgwFoAUaHQD+IXKjVRQVx0W4MjeRQ2rzS0wHQYDVR0OBBYEFHn66OzP2w11jaRY1p+27dx8Sd7mMBMGA1UdJQQMMAoGCCsGAQUFBwMDMF4GA1UdIARXMFUwOQYLKwYBBAGDjiEBAAEwKjAoBggrBgEFBQcCARYcaHR0cDovL3JlcG9zaXRvcnkuZW1zaWduLmNvbTAOBgwrBgEEAYOOIQECgUgwCAYGZ4EMAQQBMHQGCCsGAQUFBwEBBGgwZjAkBggrBgEFBQcwAYYYaHR0cDovL29jc3AtYi5lbXNpZ24uY29tMD4GCCsGAQUFBzAChjJodHRwOi8vcmVwb3NpdG9yeS5lbXNpZ24uY29tL2NlcnRzL0VNT1ZDU0NBRzNCLnA3YzA2BgNVHR8ELzAtMCugKaAnhiVodHRwOi8vY3JsLmVtc2lnbi5jb20vP3Jvb3Rjc2NhZzMuY3JsMA4GA1UdDwEB/wQEAwIBBjASBgNVHRMBAf8ECDAGAQH/AgEAMAoGCCqGSM49BAMDA2kAMGYCMQC/zr03YEELsNKqzUtH2dVFi4BaKFdyrr/6G1dIWp8KAVgsw2/u4lyyboUDaC9jDvICMQC9HTxku84tNX9dmHOtH7aC2Nu/JM0jTf6KjZAvovCJzzv1IFWSZpVLZibynMLXOrM="
+  ]
+}
diff --git a/docs/tls-trust.md b/docs/tls-trust.md
index 3d91e08cd..ed89d2011 100644
--- a/docs/tls-trust.md
+++ b/docs/tls-trust.md
@@ -21,14 +21,18 @@ python scripts/check_ca_trust.py --system --python
 
 Explicit PEM bundles can also be passed as positional arguments. The check rejects the incident's known root fingerprints and malformed/empty bundles. It does not model native OS intermediate revocation, custom TLS implementations, or arbitrary certificates added by an operator.
 
-Both Docker build stages refresh system CA certificates and bootstrap pip/certifi before dependency installation. The build fails if affected roots remain. Node uses the corrected system store through `--use-openssl-ca`. Rebuild with a fresh base and dependency layers when remediating an existing deployment:
+Both Docker build stages refresh system CA certificates and bootstrap pip/certifi before dependency installation. The build fails if affected roots remain. Node uses the corrected system store through `--use-openssl-ca`. Python gRPC uses that same PEM file through `GRPC_DEFAULT_SSL_ROOTS_FILE_PATH`; updating certifi alone does not replace gRPC's independent wheel bundle. After dependency installation, the image checks gRPC's selected file as well. An explicit gRPC override must be readable and free of the incident roots: gRPC can otherwise fall back to its affected bundled defaults.
+
+Chromium uses a separate trust store. The Docker image installs a managed `CADistrustedCertificates` policy for the eight compromised intermediate public keys, covering their cross-signs without depending on background revocation updates. It adds no trusted certificate and does not disable certificate verification. The policy and public-certificate provenance are documented in [the browser policy note](../docker/chromium-ca-policy.md). Native browser installations and independently managed profiles require their own platform policy or vendor update; this image policy does not configure host browsers.
+
+Rebuild with a fresh base and dependency layers when remediating an existing deployment:
 
 ```sh
 docker compose build --pull --no-cache odysseus
 docker compose up -d odysseus
-docker compose exec odysseus python scripts/check_ca_trust.py --system --python
+docker compose exec odysseus python scripts/check_ca_trust.py --system --python --grpc
 ```
 
 SearXNG is a separate HTTPS client and image; updating the Odysseus image does not patch it. Inspect its effective CA path and update or rebuild that image independently. Also inspect persisted `/app/.local` packages, remote Cookbook environments, and externally configured MCP runtimes. Image replacement does not necessarily replace those environments.
 
-For behavioral validation, all twelve [published test chains](https://emudhra.we-have-a-problem.com/chains.zip), including the AAA cross-signs, must fail certificate verification through the effective stores. Confirm that an ordinary known-good HTTPS request still succeeds. Package versions and a successful image build alone do not prove that a running deployment selects the corrected store.
+For behavioral validation, all twelve [published test chains](https://emudhra.we-have-a-problem.com/chains.zip), including the AAA cross-signs, must fail certificate verification through the effective stores. Confirm that an ordinary known-good HTTPS request still succeeds. In Chromium, confirm the managed policy is loaded at `chrome://policy` and test the incident endpoints through the actual browser path with certificate verification enabled. The PEM checker cannot inspect Chromium's policy or its active verifier. Package versions and a successful image build alone do not prove that a running deployment selects the corrected store.
diff --git a/scripts/check_ca_trust.py b/scripts/check_ca_trust.py
index 36457fe17..c1db2f2cc 100644
--- a/scripts/check_ca_trust.py
+++ b/scripts/check_ca_trust.py
@@ -11,6 +11,7 @@ from __future__ import annotations
 import argparse
 import hashlib
 import importlib
+import importlib.util
 import os
 from pathlib import Path
 import re
@@ -64,14 +65,28 @@ def system_paths() -> list[Path]:
     return paths
 
 
+def grpc_roots_path() -> Path:
+    """Select gRPC's override or its independent Python-wheel default bundle."""
+    override = os.environ.get("GRPC_DEFAULT_SSL_ROOTS_FILE_PATH")
+    if override:
+        # gRPC can fall back to its bundled roots when this file is unreadable.
+        # Check the configured file strictly instead of blessing that fallback.
+        return Path(override)
+    spec = importlib.util.find_spec("grpc")
+    if spec is None or spec.origin is None:
+        raise ImportError("grpcio is not installed; cannot check its default roots")
+    return Path(spec.origin).parent / "_cython" / "_credentials" / "roots.pem"
+
+
 def main(argv: list[str] | None = None) -> int:
     parser = argparse.ArgumentParser(description=__doc__)
     parser.add_argument("bundles", nargs="*", type=Path)
     parser.add_argument("--system", action="store_true", help="check effective OpenSSL PEM stores")
     parser.add_argument("--python", action="store_true", help="check certifi and pip's separate vendored bundle")
+    parser.add_argument("--grpc", action="store_true", help="check gRPC's selected default CA file")
     args = parser.parse_args(argv)
-    if not (args.bundles or args.system or args.python):
-        parser.error("select --system, --python, or explicit PEM bundle paths")
+    if not (args.bundles or args.system or args.python or args.grpc):
+        parser.error("select --system, --python, --grpc, or explicit PEM bundle paths")
     try:
         paths = list(args.bundles)
         if args.system:
@@ -79,6 +94,8 @@ def main(argv: list[str] | None = None) -> int:
         if args.python:
             for name in ("certifi", "pip._vendor.certifi"):
                 paths.append(Path(importlib.import_module(name).where()))
+        if args.grpc:
+            paths.append(grpc_roots_path())
         paths = list(dict.fromkeys(path.resolve() for path in paths))
         errors = []
         for path in paths:
diff --git a/tests/test_ca_trust.py b/tests/test_ca_trust.py
index 88a5a343f..b2ab32d40 100644
--- a/tests/test_ca_trust.py
+++ b/tests/test_ca_trust.py
@@ -7,6 +7,7 @@ import os
 from pathlib import Path
 import ssl
 import tempfile
+from types import SimpleNamespace
 import unittest
 from unittest.mock import patch
 
@@ -107,6 +108,41 @@ class CATrustTests(unittest.TestCase):
             self.assertEqual(result, 1)
             self.assertIn("AAA Certificate Services", errors.getvalue())
 
+    def test_grpc_bundled_roots_are_checked_without_an_override(self):
+        with tempfile.TemporaryDirectory() as temporary:
+            package = Path(temporary) / "grpc"
+            bundle = package / "_cython" / "_credentials" / "roots.pem"
+            bundle.parent.mkdir(parents=True)
+            bundle.write_bytes((self.fixtures / "emsign-g3.pem").read_bytes())
+            errors = io.StringIO()
+            with patch.dict(os.environ, {"GRPC_DEFAULT_SSL_ROOTS_FILE_PATH": ""}), patch.object(
+                checker.importlib.util, "find_spec", return_value=SimpleNamespace(origin=str(package / "__init__.py"))
+            ), contextlib.redirect_stderr(errors):
+                self.assertEqual(checker.main(["--grpc"]), 1)
+            self.assertIn("emSign ECC Root CA - G3", errors.getvalue())
+
+    def test_grpc_explicit_clean_store_replaces_the_independent_bundle(self):
+        with patch.dict(os.environ, {"GRPC_DEFAULT_SSL_ROOTS_FILE_PATH": str(self.fixtures / "emsign-g1.pem")}), patch.object(
+            checker.importlib.util, "find_spec", side_effect=AssertionError("must use the explicit store")
+        ), contextlib.redirect_stdout(io.StringIO()):
+            self.assertEqual(checker.main(["--grpc"]), 0)
+
+    def test_grpc_invalid_override_does_not_fall_back_silently(self):
+        with tempfile.TemporaryDirectory() as temporary:
+            for name, content in (("empty.pem", ""), ("malformed.pem", "not a certificate"), ("affected.pem", PUBLIC_CERTIFICATES["aaa.pem"])):
+                bundle = Path(temporary) / name
+                bundle.write_text(content)
+                with self.subTest(name=name), patch.dict(os.environ, {"GRPC_DEFAULT_SSL_ROOTS_FILE_PATH": str(bundle)}), contextlib.redirect_stderr(io.StringIO()):
+                    self.assertEqual(checker.main(["--grpc"]), 1)
+            with patch.dict(os.environ, {"GRPC_DEFAULT_SSL_ROOTS_FILE_PATH": str(Path(temporary) / "missing.pem")}), contextlib.redirect_stderr(io.StringIO()):
+                self.assertEqual(checker.main(["--grpc"]), 1)
+
+    def test_grpc_check_reports_a_missing_installation(self):
+        with patch.dict(os.environ, {"GRPC_DEFAULT_SSL_ROOTS_FILE_PATH": ""}), patch.object(
+            checker.importlib.util, "find_spec", return_value=None
+        ), contextlib.redirect_stderr(io.StringIO()):
+            self.assertEqual(checker.main(["--grpc"]), 1)
+
 
 # Public Mozilla CA certificates; provenance: tests/fixtures/ca-trust/README.md.
 PUBLIC_CERTIFICATES = {
diff --git a/tests/test_chromium_ca_policy.py b/tests/test_chromium_ca_policy.py
new file mode 100644
index 000000000..a8b8a47e1
--- /dev/null
+++ b/tests/test_chromium_ca_policy.py
@@ -0,0 +1,41 @@
+"""The managed browser policy must distrust exactly the incident's eight keys."""
+
+import base64
+import hashlib
+import json
+from pathlib import Path
+import unittest
+
+from cryptography import x509
+from cryptography.hazmat.primitives import serialization
+
+
+ROOT = Path(__file__).resolve().parents[1]
+# Public incident inventory: impacted-intermediates.json, 2026-10-21.
+COMPROMISED_SPKIS = {
+    "43bffa19d6ef651451f6841e019931e96f6f2eaeff28ab4b6f1ce4576de2717b",
+    "49dd353dc2b919a3770645117d0e60c16115e7d1bc259eefe734b00ea434fe5f",
+    "5c0660a2b164910d8ff589c18e14552e9e0ec237dcefe2cb736d41a4811f81a0",
+    "63ecefee431d49523bc1136c4e72d0206a477086caf606cd5cf025686c109cf8",
+    "92c063d67e8f14db71d288e11266ffdaf69cbf115f7bab14f3bc2f68d25e0e30",
+    "e0254c7fcdc265e2f0f8a428dabb75ab4ae039b4872d62f5ee57f0877d5a8a41",
+    "ebed6475c2c2d80fcb199f3fe8dd6e6b3ce60b77eb15d4e42c3dec0c6f5b5105",
+    "ec4ffa1ad0ac88081314b7aaffef6a91f97cd57291bb5ba686c5415f5eb4f6b6",
+}
+
+
+class ChromiumCATrustTests(unittest.TestCase):
+    def test_policy_distrusts_each_compromised_key_without_adding_trust(self):
+        policy = json.loads((ROOT / "docker" / "chromium-emudhra.json").read_text())
+        self.assertEqual(set(policy), {"CADistrustedCertificates"})
+        self.assertEqual(len(policy["CADistrustedCertificates"]), 8)
+        keys = set()
+        for encoded in policy["CADistrustedCertificates"]:
+            certificate = x509.load_der_x509_certificate(base64.b64decode(encoded, validate=True))
+            self.assertTrue(certificate.extensions.get_extension_for_class(x509.BasicConstraints).value.ca)
+            self.assertNotEqual(certificate.subject, certificate.issuer)
+            public_key = certificate.public_key().public_bytes(
+                serialization.Encoding.DER, serialization.PublicFormat.SubjectPublicKeyInfo
+            )
+            keys.add(hashlib.sha256(public_key).hexdigest())
+        self.assertEqual(keys, COMPROMISED_SPKIS)

From cd9f1f734fc12d3479de3039558902cf421c5454 Mon Sep 17 00:00:00 2001
From: RaresKeY <158580472+RaresKeY@users.noreply.github.com>
Date: Wed, 21 Oct 2026 20:48:34 +0000
Subject: [PATCH 40/53] fix(security): detect incident CAs in custom trust
 stores

Reject the published compromised intermediates and cross-signed G3 issuer when supplied as trust anchors. Add explicit CA-override inspection and offline chain regressions with a fixed verification time and affected positive control.
---
 docs/tls-trust.md                     |  12 ++-
 scripts/check_ca_trust.py             |  81 ++++++++++++++---
 tests/fixtures/ca-trust/README.md     |  12 ++-
 tests/fixtures/ca-trust/incident.json | 121 ++++++++++++++++++++++++++
 tests/test_ca_trust.py                | 119 +++++++++++++++++++++++++
 5 files changed, 327 insertions(+), 18 deletions(-)
 create mode 100644 tests/fixtures/ca-trust/incident.json

diff --git a/docs/tls-trust.md b/docs/tls-trust.md
index ed89d2011..8e0351c68 100644
--- a/docs/tls-trust.md
+++ b/docs/tls-trust.md
@@ -16,12 +16,16 @@ The pinned bootstrap protects package integrity even when the old installer's ce
 On Linux/OpenSSL deployments, inspect both the effective CA file and hashed CA directory, plus the two Python bundles:
 
 ```sh
-python scripts/check_ca_trust.py --system --python
+python scripts/check_ca_trust.py --system --python --overrides
 ```
 
-Explicit PEM bundles can also be passed as positional arguments. The check rejects the incident's known root fingerprints and malformed/empty bundles. It does not model native OS intermediate revocation, custom TLS implementations, or arbitrary certificates added by an operator.
+Explicit PEM bundles can also be passed as positional arguments. The check rejects the four published root fingerprints, all sixteen published intermediate certificates (including their cross-signs), the cross-signed G3 issuer in the published test chains, and malformed/empty bundles. Checking intermediates matters because adding one as a custom trust anchor can restore an affected chain even after its roots have been removed.
 
-Both Docker build stages refresh system CA certificates and bootstrap pip/certifi before dependency installation. The build fails if affected roots remain. Node uses the corrected system store through `--use-openssl-ca`. Python gRPC uses that same PEM file through `GRPC_DEFAULT_SSL_ROOTS_FILE_PATH`; updating certifi alone does not replace gRPC's independent wheel bundle. After dependency installation, the image checks gRPC's selected file as well. An explicit gRPC override must be readable and free of the incident roots: gRPC can otherwise fall back to its affected bundled defaults.
+`--overrides` checks every nonempty `LLM_CA_BUNDLE`, `SSL_CERT_FILE`, `REQUESTS_CA_BUNDLE`, `CURL_CA_BUNDLE`, `PIP_CERT`, `NODE_EXTRA_CA_CERTS` and `GRPC_DEFAULT_SSL_ROOTS_FILE_PATH` setting in the checker's process environment, including configured fallback settings. Requests/pip hashed-directory overrides are inspected too; `--system` covers `SSL_CERT_DIR`. Run with the application's environment and filesystem access. The script does not load `.env` or application configuration files; pass any CA paths configured only there explicitly, for example `python scripts/check_ca_trust.py --system --python /path/to/private-ca.pem`. Missing or invalid configured files fail the check. Selecting only `--overrides` with no configured paths also fails instead of reporting that stores were validated.
+
+This is an offline inventory check of known certificate fingerprints. It does not modify stores, reject requests at runtime, model native OS revocation, or detect arbitrary reissued certificates sharing the compromised keys. Chromium's policy separately matches public keys. Check mounted or replaced CA files again after deployment, remove affected trust through the owning platform/client configuration, and restart clients that cache SSL contexts. A passing build cannot validate custom files introduced later.
+
+Both Docker build stages refresh system CA certificates and bootstrap pip/certifi before dependency installation. The build fails if known affected CA certificates remain. Node uses the corrected system store through `--use-openssl-ca`. Python gRPC uses that same PEM file through `GRPC_DEFAULT_SSL_ROOTS_FILE_PATH`; updating certifi alone does not replace gRPC's independent wheel bundle. After dependency installation, the image checks gRPC's selected file as well. An explicit gRPC override must be readable and free of known affected CA certificates: gRPC can otherwise fall back to its affected bundled defaults. Upstream gRPC has [merged a bundle update](https://github.com/grpc/grpc/commit/8b32af3bf498c2ba9667410eaa8c836e700e97e6); as checked on 2026-10-21, its [release backport](https://github.com/grpc/grpc/pull/43700) is still open and the latest published grpcio wheel is 1.84.0. Retain the checked override until a released replacement's actual trust behavior has been verified.
 
 Chromium uses a separate trust store. The Docker image installs a managed `CADistrustedCertificates` policy for the eight compromised intermediate public keys, covering their cross-signs without depending on background revocation updates. It adds no trusted certificate and does not disable certificate verification. The policy and public-certificate provenance are documented in [the browser policy note](../docker/chromium-ca-policy.md). Native browser installations and independently managed profiles require their own platform policy or vendor update; this image policy does not configure host browsers.
 
@@ -30,7 +34,7 @@ Rebuild with a fresh base and dependency layers when remediating an existing dep
 ```sh
 docker compose build --pull --no-cache odysseus
 docker compose up -d odysseus
-docker compose exec odysseus python scripts/check_ca_trust.py --system --python --grpc
+docker compose exec odysseus python scripts/check_ca_trust.py --system --python --grpc --overrides
 ```
 
 SearXNG is a separate HTTPS client and image; updating the Odysseus image does not patch it. Inspect its effective CA path and update or rebuild that image independently. Also inspect persisted `/app/.local` packages, remote Cookbook environments, and externally configured MCP runtimes. Image replacement does not necessarily replace those environments.
diff --git a/scripts/check_ca_trust.py b/scripts/check_ca_trust.py
index c1db2f2cc..7f017fe3d 100644
--- a/scripts/check_ca_trust.py
+++ b/scripts/check_ca_trust.py
@@ -1,9 +1,11 @@
 #!/usr/bin/env python3
-"""Reject the eMudhra incident's root certificates in PEM trust stores.
+"""Reject the eMudhra incident's known CA certificates in PEM trust stores.
 
 This checks certificate contents, including OpenSSL's lazily loaded CA directory.
 It does not model native OS certificate revocation or arbitrary custom clients.
 Incident fingerprints: https://emudhra.we-have-a-problem.com/roots.json
+and https://emudhra.we-have-a-problem.com/impacted-intermediates.json
+Cross-signed issuer: https://emudhra.we-have-a-problem.com/chains.zip
 """
 
 from __future__ import annotations
@@ -19,12 +21,35 @@ import ssl
 import sys
 
 
-BLOCKED_ROOTS = {
+BLOCKED_CERTIFICATES = {
     "86a1ecba089c4a8d3bbe2734c612ba341d813e043cf9e8a862cd5c57a36bbe6b": "emSign ECC Root CA - G3",
     "d7a7a0fb5d7e2731d771e9484ebcdef71d5f0c3e0a2948782bc83ee0ea699ef4": "AAA Certificate Services",
     "7dd78d5f4f13459a83dff9abbba62edbaf6f2d102bf257fd712f4d9f2746ed8d": "emSign Root TLS CA - G3",
     "f2edaaff3d9b701fb4d14c9f285f8c0bad90fc3bcc1fa07d47f4718edaba34a5": "emSign Root CS CA - G3",
+    "3094025792039a68af6e553686410bdab7c0d4a36b9084cba64202e35d6ebbdd": "emSign Root TLS CA - G3 (cross-signed)",
+    # Intermediates can themselves be operator-supplied trust anchors. Include
+    # both published signatures for each key, without parsing SPKI in stdlib.
+    "42c4accd12c4f59597925e1a08a7a90102608543809308d50ec427e118ba1493": "EM DV TLS CA - G3B (eMudhra)",
+    "45a883f349aedfd5f3a649b5498ffb121712ba8b448f3f2a91dbc5a766fcddbe": "EM DV TLS CA - G3B (Sectigo)",
+    "98b896625c0c230adeec3eb2cf6aad5001ecf9156a68644e82374ce5833bc25b": "EM OV TLS CA - G3B (eMudhra)",
+    "5f1ded4dd590af74631290cf073b122a2aac6a1fa479778a0bd43579bd832699": "EM OV TLS CA - G3B (Sectigo)",
+    "e7568fe6e12331f4fd7de61da4c7559d0f8eb192a218d4741a3ba75184333838": "EM EV TLS CA - G3B (eMudhra)",
+    "579480aea166290bd3c643589e795fc0d0e54e86505d180f1dff99efd3199512": "EM EV TLS CA - G3B (Sectigo)",
+    "0164d7ceae5bb909c272af151ff44b1177ae9b47d9424b94f1d9558c30934d19": "EM DV TLS CA - G3C (eMudhra)",
+    "62b7f9868263f72f6911fc78ceaf72c1979158b7368bf648683bb2aa39b02e72": "EM DV TLS CA - G3C (Sectigo)",
+    "cb6e15165ac802e9b3f993f16c25d41f4e81c21ebde71ae1b012ac00bf9c7c3f": "EM OV TLS CA - G3C (eMudhra)",
+    "7485b51c0ed192878fa1d2f948fb529ae1842cc5086c4b67f7be5b2039de9489": "EM OV TLS CA - G3C (Sectigo)",
+    "432ec25f0d28de9006d97bf752f17bbb2cd41f669933fcb072d9a1148d0261f3": "EM EV TLS CA - G3C (eMudhra)",
+    "fd9d5c2dbbd4995ab69b8d50c439d9527b00529199c2fd01b2174eb58f07021f": "EM EV TLS CA - G3C (Sectigo)",
+    "9e39de2881273acc225a149c72ba3e0f51424963669ab633ee1dc7df5db067b4": "EM OV CS CA - G3B (eMudhra)",
+    "a496e23ac0cab8155fc9b117b97eae368efcbb9041aec8804d5a308d2d01c2d8": "EM OV CS CA - G3B (Sectigo)",
+    "4b2460a466f95fd40113bcdcca2ceb29b3b093921de45474da7df48874c630b1": "EM OV CS CA - G3C (eMudhra)",
+    "84112972b8e59d14560ae7e7119654474aad119990cf3722bfc1e3b91615e1fd": "EM OV CS CA - G3C (Sectigo)",
 }
+OVERRIDE_ENV_VARS = (
+    "LLM_CA_BUNDLE", "SSL_CERT_FILE", "REQUESTS_CA_BUNDLE", "CURL_CA_BUNDLE",
+    "PIP_CERT", "NODE_EXTRA_CA_CERTS", "GRPC_DEFAULT_SSL_ROOTS_FILE_PATH",
+)
 
 
 def check_bundle(path: Path) -> None:
@@ -38,12 +63,20 @@ def check_bundle(path: Path) -> None:
         raise ValueError("no certificates")
     certificates = context.get_ca_certs(binary_form=True)
     blocked = {
-        BLOCKED_ROOTS[fingerprint]
+        BLOCKED_CERTIFICATES[fingerprint]
         for certificate in certificates
-        if (fingerprint := hashlib.sha256(certificate).hexdigest()) in BLOCKED_ROOTS
+        if (fingerprint := hashlib.sha256(certificate).hexdigest()) in BLOCKED_CERTIFICATES
     }
     if blocked:
-        raise ValueError("affected roots: " + ", ".join(sorted(blocked)))
+        raise ValueError("affected CA certificates: " + ", ".join(sorted(blocked)))
+
+
+def ca_directory_paths(directory: Path) -> list[Path]:
+    """Return the hashed certificate files consumed by OpenSSL's CApath."""
+    return [
+        path for path in directory.iterdir()
+        if re.fullmatch(r"[0-9a-fA-F]{8}\.[0-9]+", path.name) and path.is_file()
+    ]
 
 
 def system_paths() -> list[Path]:
@@ -55,16 +88,33 @@ def system_paths() -> list[Path]:
     capath = os.environ.get(defaults.openssl_capath_env, defaults.capath)
     if capath:
         for directory in filter(None, capath.split(os.pathsep)):
-            paths.extend(
-                path
-                for path in Path(directory).iterdir()
-                if re.fullmatch(r"[0-9a-fA-F]{8}\.[0-9]+", path.name) and path.is_file()
-            )
+            paths.extend(ca_directory_paths(Path(directory)))
     if not paths:
         raise ValueError("no effective OpenSSL PEM CA store found")
     return paths
 
 
+def override_paths() -> list[Path]:
+    """Inspect every configured override, including client fallback settings."""
+    paths = []
+    for name in OVERRIDE_ENV_VARS:
+        value = os.environ.get(name, "")
+        if name == "LLM_CA_BUNDLE":
+            value = value.strip()  # Match src/tls_overrides.py.
+        if not value:
+            continue
+        path = Path(value)
+        # Requests (also used by pip) accepts either a file or a hashed directory.
+        if name in ("REQUESTS_CA_BUNDLE", "CURL_CA_BUNDLE", "PIP_CERT") and path.is_dir():
+            entries = ca_directory_paths(path)
+            if not entries:
+                raise ValueError(f"{name}: no hashed certificates in {path}")
+            paths.extend(entries)
+        else:
+            paths.append(path)
+    return paths
+
+
 def grpc_roots_path() -> Path:
     """Select gRPC's override or its independent Python-wheel default bundle."""
     override = os.environ.get("GRPC_DEFAULT_SSL_ROOTS_FILE_PATH")
@@ -84,9 +134,10 @@ def main(argv: list[str] | None = None) -> int:
     parser.add_argument("--system", action="store_true", help="check effective OpenSSL PEM stores")
     parser.add_argument("--python", action="store_true", help="check certifi and pip's separate vendored bundle")
     parser.add_argument("--grpc", action="store_true", help="check gRPC's selected default CA file")
+    parser.add_argument("--overrides", action="store_true", help="check configured LLM/HTTPX/Requests/pip/Node/gRPC CA overrides")
     args = parser.parse_args(argv)
-    if not (args.bundles or args.system or args.python or args.grpc):
-        parser.error("select --system, --python, --grpc, or explicit PEM bundle paths")
+    if not (args.bundles or args.system or args.python or args.grpc or args.overrides):
+        parser.error("select --system, --python, --grpc, --overrides, or explicit PEM bundle paths")
     try:
         paths = list(args.bundles)
         if args.system:
@@ -96,7 +147,11 @@ def main(argv: list[str] | None = None) -> int:
                 paths.append(Path(importlib.import_module(name).where()))
         if args.grpc:
             paths.append(grpc_roots_path())
+        if args.overrides:
+            paths.extend(override_paths())
         paths = list(dict.fromkeys(path.resolve() for path in paths))
+        if not paths:
+            raise ValueError("no CA bundle files selected; also select --system, --python, or an explicit path")
         errors = []
         for path in paths:
             try:
@@ -108,7 +163,7 @@ def main(argv: list[str] | None = None) -> int:
     except (ImportError, OSError, ValueError, ssl.SSLError) as exc:
         print(str(exc), file=sys.stderr)
         return 1
-    print(f"Validated {len(paths)} CA bundle file(s): no eMudhra incident roots")
+    print(f"Validated {len(paths)} CA bundle file(s): no known eMudhra incident CA certificates")
     return 0
 
 
diff --git a/tests/fixtures/ca-trust/README.md b/tests/fixtures/ca-trust/README.md
index 98b57d82d..3feef0f40 100644
--- a/tests/fixtures/ca-trust/README.md
+++ b/tests/fixtures/ca-trust/README.md
@@ -2,4 +2,14 @@
 
 The public certificates embedded in `tests/test_ca_trust.py` exercise the October 2026 eMudhra trust-store check. They contain no private keys. `emsign-g3.pem` and `aaa.pem` are the incident's affected trust anchors; `emsign-g1.pem` is an unaffected emSign anchor that must remain usable. `localhost-leaf.pem` is a synthetic self-signed Ed25519 server certificate with `CA:FALSE`, generated solely to reproduce hashed non-CA certificates found in Ubuntu's OpenSSL directory; its private key was discarded. The test creates temporary PEM files from these public constants. The certificate fingerprints are the factual identity of each fixture.
 
-Sources: the [incident root list](https://emudhra.we-have-a-problem.com/roots.json) and the public Mozilla root certificates distributed in Debian's `ca-certificates` package. Behavioral chain verification should also cover the incident site's separate [twelve published server chains](https://emudhra.we-have-a-problem.com/chains.zip).
+Sources: the [incident root list](https://emudhra.we-have-a-problem.com/roots.json) and the public Mozilla root certificates distributed in Debian's `ca-certificates` package.
+
+`incident.json` contains the four published roots, sixteen [compromised intermediate certificates and cross-signs](https://emudhra.we-have-a-problem.com/impacted-intermediates.json), and the [twelve published server chains](https://emudhra.we-have-a-problem.com/chains.zip), retrieved on 2026-10-21. Certificates are deduplicated by SHA-256 of DER; each chain lists its leaf first. The additional cross-signed `emSign Root TLS CA - G3` issuer comes from those chains and has fingerprint `3094025792039a68af6e553686410bdab7c0d4a36b9084cba64202e35d6ebbdd`. Like the intermediates, it must not be accepted as a custom trust anchor. All data is public certificate material, with no private keys.
+
+Downloaded source SHA-256 values:
+
+- `roots.json`: `119f32cd81a6b5a4e3c4c2df5fe07daa90dc43cafa123a62f0394f1895d92380`
+- `impacted-intermediates.json`: `f67b3abe9b4879f4e91874ed041beccd71257f1db41c588c724ccf12aa90c59e`
+- `chains.zip`: `8a2edc81b6c51e3ad27d45ca1e441ec84c961e2dee0fc547f2a02c0f74315f95`
+
+The offline OpenSSL regression verifies server purpose, hostname and strict certificate rules with partial-chain trust, at `2026-10-21T12:00:00Z` (`1792584000`). Fixing the verification date keeps later certificate expiry from masking a broken mitigation. All twelve chains must verify against the affected positive-control roots and fail against the unaffected G1-only store. Adding the compromised DV G3B intermediate restores two paths, which the checker must reject. The regression makes no network requests and skips chain verification if the OpenSSL executable is unavailable; certificate-inventory tests still run using Python's standard library.
diff --git a/tests/fixtures/ca-trust/incident.json b/tests/fixtures/ca-trust/incident.json
new file mode 100644
index 000000000..771a341f2
--- /dev/null
+++ b/tests/fixtures/ca-trust/incident.json
@@ -0,0 +1,121 @@
+{
+  "verification_time": 1792584000,
+  "roots": {
+    "7dd78d5f4f13459a83dff9abbba62edbaf6f2d102bf257fd712f4d9f2746ed8d": "emSign Root TLS CA - G3",
+    "f2edaaff3d9b701fb4d14c9f285f8c0bad90fc3bcc1fa07d47f4718edaba34a5": "emSign Root CS CA - G3",
+    "d7a7a0fb5d7e2731d771e9484ebcdef71d5f0c3e0a2948782bc83ee0ea699ef4": "AAA Certificate Services",
+    "86a1ecba089c4a8d3bbe2734c612ba341d813e043cf9e8a862cd5c57a36bbe6b": "emSign ECC Root CA - G3"
+  },
+  "intermediates": {
+    "42c4accd12c4f59597925e1a08a7a90102608543809308d50ec427e118ba1493": "EM DV TLS CA - G3B (eMudhra)",
+    "45a883f349aedfd5f3a649b5498ffb121712ba8b448f3f2a91dbc5a766fcddbe": "EM DV TLS CA - G3B (Sectigo)",
+    "98b896625c0c230adeec3eb2cf6aad5001ecf9156a68644e82374ce5833bc25b": "EM OV TLS CA - G3B (eMudhra)",
+    "5f1ded4dd590af74631290cf073b122a2aac6a1fa479778a0bd43579bd832699": "EM OV TLS CA - G3B (Sectigo)",
+    "e7568fe6e12331f4fd7de61da4c7559d0f8eb192a218d4741a3ba75184333838": "EM EV TLS CA - G3B (eMudhra)",
+    "579480aea166290bd3c643589e795fc0d0e54e86505d180f1dff99efd3199512": "EM EV TLS CA - G3B (Sectigo)",
+    "0164d7ceae5bb909c272af151ff44b1177ae9b47d9424b94f1d9558c30934d19": "EM DV TLS CA - G3C (eMudhra)",
+    "62b7f9868263f72f6911fc78ceaf72c1979158b7368bf648683bb2aa39b02e72": "EM DV TLS CA - G3C (Sectigo)",
+    "cb6e15165ac802e9b3f993f16c25d41f4e81c21ebde71ae1b012ac00bf9c7c3f": "EM OV TLS CA - G3C (eMudhra)",
+    "7485b51c0ed192878fa1d2f948fb529ae1842cc5086c4b67f7be5b2039de9489": "EM OV TLS CA - G3C (Sectigo)",
+    "432ec25f0d28de9006d97bf752f17bbb2cd41f669933fcb072d9a1148d0261f3": "EM EV TLS CA - G3C (eMudhra)",
+    "fd9d5c2dbbd4995ab69b8d50c439d9527b00529199c2fd01b2174eb58f07021f": "EM EV TLS CA - G3C (Sectigo)",
+    "9e39de2881273acc225a149c72ba3e0f51424963669ab633ee1dc7df5db067b4": "EM OV CS CA - G3B (eMudhra)",
+    "a496e23ac0cab8155fc9b117b97eae368efcbb9041aec8804d5a308d2d01c2d8": "EM OV CS CA - G3B (Sectigo)",
+    "4b2460a466f95fd40113bcdcca2ceb29b3b093921de45474da7df48874c630b1": "EM OV CS CA - G3C (eMudhra)",
+    "84112972b8e59d14560ae7e7119654474aad119990cf3722bfc1e3b91615e1fd": "EM OV CS CA - G3C (Sectigo)"
+  },
+  "certificates": {
+    "0164d7ceae5bb909c272af151ff44b1177ae9b47d9424b94f1d9558c30934d19": "-----BEGIN CERTIFICATE-----\nMIIDaDCCAu6gAwIBAgIPWIsuPCu4zaE+GhIJJUMhMAoGCCqGSM49BAMDMFYxCzAJ\nBgNVBAYTAklOMSUwIwYDVQQKDBxlTXVkaHJhIFRlY2hub2xvZ2llcyBMaW1pdGVk\nMSAwHgYDVQQDDBdlbVNpZ24gUm9vdCBUTFMgQ0EgLSBHMzAeFw0yNTA0MzAxNTM1\nMDlaFw00MDA0MjgxODMwMDBaMEAxCzAJBgNVBAYTAlVTMRQwEgYDVQQKDAtlTXVk\naHJhIEluYzEbMBkGA1UEAwwSRU0gRFYgVExTIENBIC0gRzNDMHYwEAYHKoZIzj0C\nAQYFK4EEACIDYgAEOnp4YsjETTJN3WkDOmeCwO/u/kBV5ooSP6A3G6O9kZRRTuFy\npDPjYw8CvRiAN9nlFJ+bd9uUooHfmHsv6oiLdL3+j9pMEJnubKGVZv4+8OX2sJpV\nbMyLpQVh3xsqRB0Bo4IBljCCAZIwHwYDVR0jBBgwFoAU4TqrIXzx401UrtRyt/2L\nWUIgkFQwHQYDVR0OBBYEFK5+EFw8KZbBqEcnBVnx4D3U5QrzMB0GA1UdJQQWMBQG\nCCsGAQUFBwMBBggrBgEFBQcDAjBdBgNVHSAEVjBUMDkGCysGAQQBg44hAQABMCow\nKAYIKwYBBQUHAgEWHGh0dHA6Ly9yZXBvc2l0b3J5LmVtc2lnbi5jb20wDQYLKwYB\nBAGDjiEBAmQwCAYGZ4EMAQIBMHUGCCsGAQUFBwEBBGkwZzAkBggrBgEFBQcwAYYY\naHR0cDovL29jc3AtYy5lbXNpZ24uY29tMD8GCCsGAQUFBzAChjNodHRwOi8vcmVw\nb3NpdG9yeS5lbXNpZ24uY29tL2NlcnRzL0VNRFZUTFNDQUczQy5wN2MwNwYDVR0f\nBDAwLjAsoCqgKIYmaHR0cDovL2NybC5lbXNpZ24uY29tLz9yb290dGxzY2FnMy5j\ncmwwDgYDVR0PAQH/BAQDAgEGMBIGA1UdEwEB/wQIMAYBAf8CAQAwCgYIKoZIzj0E\nAwMDaAAwZQIxAMEN2HWMocbuWdy1d33pH6JpMvP/V/DIS5PtZbv1Q7TXEbxrcyxg\nyuddOJscYDJJlAIwB4sH1BpbScDzkdD4tJBSwrG/1Mx82vb8YaySehNuu1+1oXNd\nAEKwaJ0mVzScy2+6\n-----END CERTIFICATE-----\n",
+    "21f57f83631a93c98e867050075746b3361e0433c9e0e969462852476784f6f0": "-----BEGIN CERTIFICATE-----\nMIICPzCCAcagAwIBAgIUH0gWfBRnOiSjcduti/cukjDGAjIwCgYIKoZIzj0EAwIw\nPzELMAkGA1UEBhMCTkwxEzARBgNVBAoMCmVNdWRocmEgQlYxGzAZBgNVBAMMEkVN\nIE9WIFRMUyBDQSAtIEczQjAeFw0yNjEwMjAwMjIyNDJaFw0yNzA1MDMwMjI3NDJa\nMDMxMTAvBgNVBAMMKG92LWczYi1hYWEtZW11ZGhyYS53ZS1oYXZlLWEtcHJvYmxl\nbS5jb20wWTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAAQ3EfjVE+6fUm9gr7UoUv6N\nYPttIdILR9OMZnAdTj+RWT1Z4fp7dpC5mat1gbIo4J6EDelcOQQz5/oGeB3gFJKw\no4GrMIGoMAwGA1UdEwEB/wQCMAAwDgYDVR0PAQH/BAQDAgeAMBMGA1UdJQQMMAoG\nCCsGAQUFBwMBMDMGA1UdEQQsMCqCKG92LWczYi1hYWEtZW11ZGhyYS53ZS1oYXZl\nLWEtcHJvYmxlbS5jb20wHQYDVR0OBBYEFKzQPp6gTBOWb0TBxZbkL5zsQn3oMB8G\nA1UdIwQYMBaAFJvYZVGv5+csN60I7mkZ2b83hK4KMAoGCCqGSM49BAMCA2cAMGQC\nMARKrRRBEWY2Ix1d80DGUvC7bWENP1Q9pf6BOGF4+84UiwV5+nAuht/+hdpAanWB\nsQIwJF2dW8tpPN6lTm1kDerzG6yJAJOz4drotaTthMF2+efuv5W2FL7Dr8qZSd1z\n201o\n-----END CERTIFICATE-----\n",
+    "3094025792039a68af6e553686410bdab7c0d4a36b9084cba64202e35d6ebbdd": "-----BEGIN CERTIFICATE-----\nMIIDdDCCAvmgAwIBAgIQAJYaPvsTWVdu0EAFtGhKWzAKBggqhkjOPQQDAzBrMQsw\nCQYDVQQGEwJJTjETMBEGA1UECxMKZW1TaWduIFBLSTElMCMGA1UEChMcZU11ZGhy\nYSBUZWNobm9sb2dpZXMgTGltaXRlZDEgMB4GA1UEAxMXZW1TaWduIEVDQyBSb290\nIENBIC0gRzMwHhcNMjQwNzExMTU0MzM2WhcNMzkwNzA5MTgzMDAwWjBWMQswCQYD\nVQQGEwJJTjElMCMGA1UECgwcZU11ZGhyYSBUZWNobm9sb2dpZXMgTGltaXRlZDEg\nMB4GA1UEAwwXZW1TaWduIFJvb3QgVExTIENBIC0gRzMwdjAQBgcqhkjOPQIBBgUr\ngQQAIgNiAARfD9w/q1cWxL6D9bMGH6CQ4u+gAV6GN9s+PwQx9Bl4hC+0iU8QOk8m\nWO/RwXQy10DCSxT8vSIJClHKp+Ao4qJKdYeV0SwZ7LMQziyLfxIUOY6Grja/sQFw\nLKYf8EdDXAyjggF1MIIBcTAfBgNVHSMEGDAWgBR8XQKEE9TMipuBzhccLikenEhj\nQjAdBgNVHQ4EFgQU4TqrIXzx401UrtRyt/2LWUIgkFQwHQYDVR0lBBYwFAYIKwYB\nBQUHAwEGCCsGAQUFBwMCMD0GA1UdIAQ2MDQwMgYEVR0gADAqMCgGCCsGAQUFBwIB\nFhxodHRwOi8vcmVwb3NpdG9yeS5lbXNpZ24uY29tMHgGCCsGAQUFBwEBBGwwajAi\nBggrBgEFBQcwAYYWaHR0cDovL29jc3AuZW1zaWduLmNvbTBEBggrBgEFBQcwAoY4\naHR0cDovL3JlcG9zaXRvcnkuZW1zaWduLmNvbS9jZXJ0cy9lbVNpZ25FQ0NSb290\nQ0FHMy5jcnQwMwYDVR0fBCwwKjAooCagJIYiaHR0cDovL2NybC5lbXNpZ24uY29t\nP1Jvb3RDQUczLmNybDAOBgNVHQ8BAf8EBAMCAQYwEgYDVR0TAQH/BAgwBgEB/wIB\nATAKBggqhkjOPQQDAwNpADBmAjEAt9CIpRGp46QHQYDUBnLKw+vvK0/h9vmilEAg\nTroUl/anH4x2rXHqiCtBTBfgKDegAjEA8WpG1LTZdAIL0FSYqxXeREaeTSxEofM0\n1jJH3jGvCXC79LU9UPJ2o3TU+UIj2gMV\n-----END CERTIFICATE-----\n",
+    "346cdd962e97189b59aee5526d1ae8fa714bb1a64094dfa67bef768ee93f36b5": "-----BEGIN CERTIFICATE-----\nMIICODCCAb+gAwIBAgIUbWvtwSNK/Qro223vAqyz323+VBAwCgYIKoZIzj0EAwIw\nQDELMAkGA1UEBhMCVVMxFDASBgNVBAoMC2VNdWRocmEgSW5jMRswGQYDVQQDDBJF\nTSBEViBUTFMgQ0EgLSBHM0MwHhcNMjYxMDIwMDA1OTM2WhcNMjcwNTAzMDEwNDM2\nWjAvMS0wKwYDVQQDDCRkdi1nM2MtZW11ZGhyYS53ZS1oYXZlLWEtcHJvYmxlbS5j\nb20wWTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAAScdBQpNUOOCcag6YEVFccNRSFe\nUIl02iH53vDfoWPJFS005WzqF3CPDclB/kygP2gWF4pg/r5gPYdnI3/6Vdzro4Gn\nMIGkMAwGA1UdEwEB/wQCMAAwDgYDVR0PAQH/BAQDAgeAMBMGA1UdJQQMMAoGCCsG\nAQUFBwMBMC8GA1UdEQQoMCaCJGR2LWczYy1lbXVkaHJhLndlLWhhdmUtYS1wcm9i\nbGVtLmNvbTAdBgNVHQ4EFgQUBj2yGO/TzDOE/u/6QeUvcW8y1iMwHwYDVR0jBBgw\nFoAUrn4QXDwplsGoRycFWfHgPdTlCvMwCgYIKoZIzj0EAwIDZwAwZAIwBQOOQqG9\nccdzM/7XIlXLtota1esALaLmgEN/ZweosBIvk4xabHcERZInWVIwO45NAjBos8Ue\nNwDe1X3ahdK2lkxqBEoBMtUHJN18TnJKs2nK1gmXpMbmY5oKnAQQgCEZPA4=\n-----END CERTIFICATE-----\n",
+    "42c4accd12c4f59597925e1a08a7a90102608543809308d50ec427e118ba1493": "-----BEGIN CERTIFICATE-----\nMIIDaDCCAu6gAwIBAgIQAKSu5njyM2K0wORgt3LyFDAKBggqhkjOPQQDAzBWMQsw\nCQYDVQQGEwJJTjElMCMGA1UECgwcZU11ZGhyYSBUZWNobm9sb2dpZXMgTGltaXRl\nZDEgMB4GA1UEAwwXZW1TaWduIFJvb3QgVExTIENBIC0gRzMwHhcNMjUwNDMwMTU1\nNDA4WhcNNDAwNDI4MTgzMDAwWjA/MQswCQYDVQQGEwJOTDETMBEGA1UECgwKZU11\nZGhyYSBCVjEbMBkGA1UEAwwSRU0gRFYgVExTIENBIC0gRzNCMHYwEAYHKoZIzj0C\nAQYFK4EEACIDYgAE557ZwEqXc8RzXlERHahawr1eZKs3S4DhLLwgOOweTw47gS/J\nhZ4eZ6+wTi+LyX90hbplqpEe6KTkW2LVzAPVa+Z4s8OMtNyTfKJGDiOEU8iSk10p\n1E+R4VYGtjzO2rRoo4IBljCCAZIwHwYDVR0jBBgwFoAU4TqrIXzx401UrtRyt/2L\nWUIgkFQwHQYDVR0OBBYEFOIeL+ccGTkOVUtiwSAkVzUkiiUUMB0GA1UdJQQWMBQG\nCCsGAQUFBwMBBggrBgEFBQcDAjBdBgNVHSAEVjBUMDkGCysGAQQBg44hAQABMCow\nKAYIKwYBBQUHAgEWHGh0dHA6Ly9yZXBvc2l0b3J5LmVtc2lnbi5jb20wDQYLKwYB\nBAGDjiEBAmQwCAYGZ4EMAQIBMHUGCCsGAQUFBwEBBGkwZzAkBggrBgEFBQcwAYYY\naHR0cDovL29jc3AtYi5lbXNpZ24uY29tMD8GCCsGAQUFBzAChjNodHRwOi8vcmVw\nb3NpdG9yeS5lbXNpZ24uY29tL2NlcnRzL0VNRFZUTFNDQUczQi5wN2MwNwYDVR0f\nBDAwLjAsoCqgKIYmaHR0cDovL2NybC5lbXNpZ24uY29tLz9yb290dGxzY2FnMy5j\ncmwwDgYDVR0PAQH/BAQDAgEGMBIGA1UdEwEB/wQIMAYBAf8CAQAwCgYIKoZIzj0E\nAwMDaAAwZQIwLmsGXi6oFMJ2klkcEMXMug6gvxQWZWkewiDWVzQyl2L6z6DuQfPO\nIbh1grvdULDCAjEAxZvLlxUavG69J6wnSjC8XBbqNIQsJ6CE2QdNOe84Ptxb6VG8\ngt2TlfJbHii+KNvK\n-----END CERTIFICATE-----\n",
+    "4314941cf242a4ea4149aa7e9cdf77a15de2771a79984b809fc04443fea013c8": "-----BEGIN CERTIFICATE-----\nMIICOTCCAb+gAwIBAgIUXcJ4+VeNEICJ9JbBANtIyfP96EowCgYIKoZIzj0EAwIw\nQDELMAkGA1UEBhMCVVMxFDASBgNVBAoMC2VNdWRocmEgSW5jMRswGQYDVQQDDBJF\nTSBPViBUTFMgQ0EgLSBHM0MwHhcNMjYxMDIwMDA1OTM3WhcNMjcwNTAzMDEwNDM3\nWjAvMS0wKwYDVQQDDCRvdi1nM2MtZW11ZGhyYS53ZS1oYXZlLWEtcHJvYmxlbS5j\nb20wWTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAATLEvRHdoPc0Z9ovgqlYmoKTHPU\nApwd6lAp0ou1G63SzuESyBzIW6Tl64CsKzlV9ggkZjX+L9/tOx97/1wmSTYvo4Gn\nMIGkMAwGA1UdEwEB/wQCMAAwDgYDVR0PAQH/BAQDAgeAMBMGA1UdJQQMMAoGCCsG\nAQUFBwMBMC8GA1UdEQQoMCaCJG92LWczYy1lbXVkaHJhLndlLWhhdmUtYS1wcm9i\nbGVtLmNvbTAdBgNVHQ4EFgQUrytBb+px+b58Df+d5vP8GpTW+/wwHwYDVR0jBBgw\nFoAUNOrqDOvJCtr50MXi7Zt4yYeeG2wwCgYIKoZIzj0EAwIDaAAwZQIwNdoOUOKz\nMLV1OFEoMjBeUqvkQAwsajvVWu0A23qyyvYlosyMp8aFv0gxURW6Yj6DAjEAhe0z\nkOQmmqb0eyhjh7weF4fHtwMtLi4jNFA6M/EfPTfkqE91MN9fSin5uhua5xhk\n-----END CERTIFICATE-----\n",
+    "432ec25f0d28de9006d97bf752f17bbb2cd41f669933fcb072d9a1148d0261f3": "-----BEGIN CERTIFICATE-----\nMIIDaDCCAu6gAwIBAgIQAIAJkopkEHYBrwX6LxnxCTAKBggqhkjOPQQDAzBWMQsw\nCQYDVQQGEwJJTjElMCMGA1UECgwcZU11ZGhyYSBUZWNobm9sb2dpZXMgTGltaXRl\nZDEgMB4GA1UEAwwXZW1TaWduIFJvb3QgVExTIENBIC0gRzMwHhcNMjUwNDMwMTUz\nOTMxWhcNNDAwNDI4MTgzMDAwWjBAMQswCQYDVQQGEwJVUzEUMBIGA1UECgwLZU11\nZGhyYSBJbmMxGzAZBgNVBAMMEkVNIEVWIFRMUyBDQSAtIEczQzB2MBAGByqGSM49\nAgEGBSuBBAAiA2IABC1W6Cmm+4LGSkaX2WCvlR6QZ66R+SbTQwbaSKiq63hptqZ+\nbSdCbgRCqgOzbhmI3/Y2UU7hzwf1uks/8qBmRa59MdWGatMao9JG6wsxd+6Zy3Vm\nxRbOdICKZo+R8MR/yqOCAZUwggGRMB8GA1UdIwQYMBaAFOE6qyF88eNNVK7Ucrf9\ni1lCIJBUMB0GA1UdDgQWBBSmJV6AqU2385Z8G8eR35K87kvrXzAdBgNVHSUEFjAU\nBggrBgEFBQcDAQYIKwYBBQUHAwIwXAYDVR0gBFUwUzA5BgsrBgEEAYOOIQEAATAq\nMCgGCCsGAQUFBwIBFhxodHRwOi8vcmVwb3NpdG9yeS5lbXNpZ24uY29tMA0GCysG\nAQQBg44hAQJ4MAcGBWeBDAEBMHUGCCsGAQUFBwEBBGkwZzAkBggrBgEFBQcwAYYY\naHR0cDovL29jc3AtYy5lbXNpZ24uY29tMD8GCCsGAQUFBzAChjNodHRwOi8vcmVw\nb3NpdG9yeS5lbXNpZ24uY29tL2NlcnRzL0VNRVZUTFNDQUczQy5wN2MwNwYDVR0f\nBDAwLjAsoCqgKIYmaHR0cDovL2NybC5lbXNpZ24uY29tLz9yb290dGxzY2FnMy5j\ncmwwDgYDVR0PAQH/BAQDAgEGMBIGA1UdEwEB/wQIMAYBAf8CAQAwCgYIKoZIzj0E\nAwMDaAAwZQIwBy1wTnzH4lXDTy2PD91ysLjvnlVN3JbJmc1BIMEU8TOLkYVHibMc\n9HeyonikFSfmAjEA6uE3QRxlrZTz/1/lXPTEMUhoauAtycagtlNFp79kjhvNa2/f\nAal1GNxsOutLnr0Y\n-----END CERTIFICATE-----\n",
+    "45a883f349aedfd5f3a649b5498ffb121712ba8b448f3f2a91dbc5a766fcddbe": "-----BEGIN CERTIFICATE-----\nMIIDzjCCAragAwIBAgIRAKAk/fS6Zlx4XOSgIEg4WLcwDQYJKoZIhvcNAQELBQAw\nezELMAkGA1UEBhMCR0IxGzAZBgNVBAgMEkdyZWF0ZXIgTWFuY2hlc3RlcjEQMA4G\nA1UEBwwHU2FsZm9yZDEaMBgGA1UECgwRQ29tb2RvIENBIExpbWl0ZWQxITAfBgNV\nBAMMGEFBQSBDZXJ0aWZpY2F0ZSBTZXJ2aWNlczAeFw0yNTA1MTQwMDAwMDBaFw0y\nODEyMzEyMzU5NTlaMD8xCzAJBgNVBAYTAk5MMRMwEQYDVQQKDAplTXVkaHJhIEJW\nMRswGQYDVQQDDBJFTSBEViBUTFMgQ0EgLSBHM0IwdjAQBgcqhkjOPQIBBgUrgQQA\nIgNiAATnntnASpdzxHNeUREdqFrCvV5kqzdLgOEsvCA47B5PDjuBL8mFnh5nr7BO\nL4vJf3SFumWqkR7opORbYtXMA9Vr5nizw4y03JN8okYOI4RTyJKTXSnUT5HhVga2\nPM7atGijggE1MIIBMTAfBgNVHSMEGDAWgBSgEQojPpbxB+zirynvgqV/0DCktDAd\nBgNVHQ4EFgQU4h4v5xwZOQ5VS2LBICRXNSSKJRQwDgYDVR0PAQH/BAQDAgEGMBIG\nA1UdEwEB/wQIMAYBAf8CAQAwHQYDVR0lBBYwFAYIKwYBBQUHAwEGCCsGAQUFBwMC\nMDEGA1UdIAQqMCgwCAYGZ4EMAQIBMA0GCysGAQQBg44hAQABMA0GCysGAQQBg44h\nAQJkMEMGA1UdHwQ8MDowOKA2oDSGMmh0dHA6Ly9jcmwuY29tb2RvY2EuY29tL0FB\nQUNlcnRpZmljYXRlU2VydmljZXMuY3JsMDQGCCsGAQUFBwEBBCgwJjAkBggrBgEF\nBQcwAYYYaHR0cDovL29jc3AuY29tb2RvY2EuY29tMA0GCSqGSIb3DQEBCwUAA4IB\nAQBzQ1IoqpdotM6gFrR4Q3YrKifOLeaj5XXunldpVE/vZn2TxC2y0s8oYiLR5ICE\nwqVXSB7N6BM1Mp+Nif7Jbhb2IswAfSR4Iik8+B0iRmi7lYoNlycCgHjmsjOmZaxM\nQkPmjXAJbG5f4V41OsvJZmS7lI3r0IuvEDVX3GAZ13on6IImSs9ybNpHQ7NCqkMQ\n7wH4uAO1dtpFycgJSdHaCOhHjrox2BTYGLdpUrYwY3EOAjlZ8UGgsxs7mG+xquMl\nbN1LFURwfnkVMP3T/DBIZ/ys2+lNFyxK3FlArrV4/000uTnVB1lO8oGORYdXoT5V\nGUyRCEIDhF5TBUuKF4E3kf1h\n-----END CERTIFICATE-----\n",
+    "4b2460a466f95fd40113bcdcca2ceb29b3b093921de45474da7df48874c630b1": "-----BEGIN CERTIFICATE-----\nMIIDWzCCAuGgAwIBAgIPVEt/kiwxriIKSpIpFvbmMAoGCCqGSM49BAMDMFUxCzAJ\nBgNVBAYTAklOMSUwIwYDVQQKDBxlTXVkaHJhIFRlY2hub2xvZ2llcyBMaW1pdGVk\nMR8wHQYDVQQDDBZlbVNpZ24gUm9vdCBDUyBDQSAtIEczMB4XDTI1MDQzMDE2Mzg0\nMFoXDTQwMDQyODE4MzAwMFowPzELMAkGA1UEBhMCVVMxFDASBgNVBAoMC2VNdWRo\ncmEgSW5jMRowGAYDVQQDDBFFTSBPViBDUyBDQSAtIEczQzB2MBAGByqGSM49AgEG\nBSuBBAAiA2IABLnw4GNHAqacpqrdRDz9YsQbm6SyCSRpfXl052kaEm+5avs+NML9\nO8X0gwYfJl3CpYQ2NHMjUQQ2so8E84YjYwZ5gOJQPgJTLWVGI1pxZaJZoe9Jb3Qb\nX97neHII5Lj676OCAYswggGHMB8GA1UdIwQYMBaAFGh0A/iFyo1UUFcdFuDI3kUN\nq80tMB0GA1UdDgQWBBTub3MpjW+/p7Mbw5U09hVWRHhmtzATBgNVHSUEDDAKBggr\nBgEFBQcDAzBeBgNVHSAEVzBVMDkGCysGAQQBg44hAQABMCowKAYIKwYBBQUHAgEW\nHGh0dHA6Ly9yZXBvc2l0b3J5LmVtc2lnbi5jb20wDgYMKwYBBAGDjiEBAoFIMAgG\nBmeBDAEEATB0BggrBgEFBQcBAQRoMGYwJAYIKwYBBQUHMAGGGGh0dHA6Ly9vY3Nw\nLWMuZW1zaWduLmNvbTA+BggrBgEFBQcwAoYyaHR0cDovL3JlcG9zaXRvcnkuZW1z\naWduLmNvbS9jZXJ0cy9FTU9WQ1NDQUczQy5wN2MwNgYDVR0fBC8wLTAroCmgJ4Yl\naHR0cDovL2NybC5lbXNpZ24uY29tLz9yb290Y3NjYWczLmNybDAOBgNVHQ8BAf8E\nBAMCAQYwEgYDVR0TAQH/BAgwBgEB/wIBADAKBggqhkjOPQQDAwNoADBlAjEA8yPg\n8sntOhLwV2QXJ5LEaKSpo/fnE3uOgTadK73fDhyjiqr0Io9GVuQTYqBPbQ2TAjBg\neuApmBS486+iei03lRrp139dPw6k28jjGNvWsAU7A1N86J1zPJVDEyVH+nMAWC0=\n-----END CERTIFICATE-----\n",
+    "579480aea166290bd3c643589e795fc0d0e54e86505d180f1dff99efd3199512": "-----BEGIN CERTIFICATE-----\nMIIDzTCCArWgAwIBAgIRANj4aF5PK9nYJAKoWhwetzEwDQYJKoZIhvcNAQELBQAw\nezELMAkGA1UEBhMCR0IxGzAZBgNVBAgMEkdyZWF0ZXIgTWFuY2hlc3RlcjEQMA4G\nA1UEBwwHU2FsZm9yZDEaMBgGA1UECgwRQ29tb2RvIENBIExpbWl0ZWQxITAfBgNV\nBAMMGEFBQSBDZXJ0aWZpY2F0ZSBTZXJ2aWNlczAeFw0yNTA1MTQwMDAwMDBaFw0y\nODEyMzEyMzU5NTlaMD8xCzAJBgNVBAYTAk5MMRMwEQYDVQQKDAplTXVkaHJhIEJW\nMRswGQYDVQQDDBJFTSBFViBUTFMgQ0EgLSBHM0IwdjAQBgcqhkjOPQIBBgUrgQQA\nIgNiAAQl26haZNOX2gsQUunqVG5Ie+/qnJ2daKDF6tz+73Wmm7XW/AH0K/vKbrQL\nzWTAdn42/9Bdl6gTxaoMbJUw55z18IZkaPE4BkIKpchRhAseJSVA55DktlTDhS7W\nSvHoZX2jggE0MIIBMDAfBgNVHSMEGDAWgBSgEQojPpbxB+zirynvgqV/0DCktDAd\nBgNVHQ4EFgQUPtwg2YlGmId7hz/YgUeyXBXYRwYwDgYDVR0PAQH/BAQDAgEGMBIG\nA1UdEwEB/wQIMAYBAf8CAQAwHQYDVR0lBBYwFAYIKwYBBQUHAwEGCCsGAQUFBwMC\nMDAGA1UdIAQpMCcwBwYFZ4EMAQEwDQYLKwYBBAGDjiEBAAEwDQYLKwYBBAGDjiEB\nAngwQwYDVR0fBDwwOjA4oDagNIYyaHR0cDovL2NybC5jb21vZG9jYS5jb20vQUFB\nQ2VydGlmaWNhdGVTZXJ2aWNlcy5jcmwwNAYIKwYBBQUHAQEEKDAmMCQGCCsGAQUF\nBzABhhhodHRwOi8vb2NzcC5jb21vZG9jYS5jb20wDQYJKoZIhvcNAQELBQADggEB\nAJNFuAFW9Gnw/8+kCO4KIlZdnM1Sh2u+8cK0EYAHhXpb5FlGvYkcARigo5oS7VoM\n7FOYlTueV6yICZKNAYawZPJPhNCGK+rp3cQBEz6d0n8OZEYZov9lb3ll8ORgSDuf\nFVIW6Gagg/UnOamLBTOR8eD5V73SCme/B2cHUDw+m5E8cc+0Ujzz3Cn3ex5JrhXk\n2T3s8PoVzEmhTgGboFfcWO1EYhPPrYwdxPYRQIXAXUXhLEOVNL9ASbZJLFI8E1IM\nm7NwxVN2s38jWpaCUaaF0tg7hfiy7oe13rzJfHsdqldJVTTUTPWVx8TC4ju0VLet\nbAlwhwFT6AP8uIVMGUHNw24=\n-----END CERTIFICATE-----\n",
+    "59cf0386b56bc2414a0c06241ea9e25e01a9c93bac7a596648747f9d0ded4906": "-----BEGIN CERTIFICATE-----\nMIICQTCCAcegAwIBAgIULuWnWW6kFV6QZxp2ls8r18NCjXkwCgYIKoZIzj0EAwIw\nQDELMAkGA1UEBhMCVVMxFDASBgNVBAoMC2VNdWRocmEgSW5jMRswGQYDVQQDDBJF\nTSBPViBUTFMgQ0EgLSBHM0MwHhcNMjYxMDIwMDIyMjQyWhcNMjcwNTAzMDIyNzQy\nWjAzMTEwLwYDVQQDDChvdi1nM2MtYWFhLWVtdWRocmEud2UtaGF2ZS1hLXByb2Js\nZW0uY29tMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEb7+5g2YHNYwH2eQERrZc\nTmVuf/RmvzsGGMSwXmZke6vn35Ut5HME7UOOU3Muy+BSfjfpo6fjL5KOs3Ndz67d\nOKOBqzCBqDAMBgNVHRMBAf8EAjAAMA4GA1UdDwEB/wQEAwIHgDATBgNVHSUEDDAK\nBggrBgEFBQcDATAzBgNVHREELDAqgihvdi1nM2MtYWFhLWVtdWRocmEud2UtaGF2\nZS1hLXByb2JsZW0uY29tMB0GA1UdDgQWBBQ7oBzq3jpTuvntbIkzMV12Ps3O0TAf\nBgNVHSMEGDAWgBQ06uoM68kK2vnQxeLtm3jJh54bbDAKBggqhkjOPQQDAgNoADBl\nAjEA/Y7AZ4M2MYbN5Od9tREaUfFjZKoOjczfIKPjKNMjtGxTdL9WUXvAT4QDgktn\n/IJdAjAbORTkAXD5hggyG6K7p0MBz3lFZJb2l/LndZlrttJWBLP8QGrc44hrZZtK\nIq0d1dE=\n-----END CERTIFICATE-----\n",
+    "5f1ded4dd590af74631290cf073b122a2aac6a1fa479778a0bd43579bd832699": "-----BEGIN CERTIFICATE-----\nMIIDzjCCAragAwIBAgIRAOlCI73pL5FOWrmsq/2sNxAwDQYJKoZIhvcNAQELBQAw\nezELMAkGA1UEBhMCR0IxGzAZBgNVBAgMEkdyZWF0ZXIgTWFuY2hlc3RlcjEQMA4G\nA1UEBwwHU2FsZm9yZDEaMBgGA1UECgwRQ29tb2RvIENBIExpbWl0ZWQxITAfBgNV\nBAMMGEFBQSBDZXJ0aWZpY2F0ZSBTZXJ2aWNlczAeFw0yNTA1MTQwMDAwMDBaFw0y\nODEyMzEyMzU5NTlaMD8xCzAJBgNVBAYTAk5MMRMwEQYDVQQKDAplTXVkaHJhIEJW\nMRswGQYDVQQDDBJFTSBPViBUTFMgQ0EgLSBHM0IwdjAQBgcqhkjOPQIBBgUrgQQA\nIgNiAARziXqg6zz9yosSQC/68KvE4SErr43ud4rJ7i1tuD+sKAxeBWOK56Ks1xwy\nKo42HN659pxDArndjXPRzGyqsswK7k4hbOl53VGKSvS2JuVoTN1lgDftDIVOTMEv\nTPhkbQ2jggE1MIIBMTAfBgNVHSMEGDAWgBSgEQojPpbxB+zirynvgqV/0DCktDAd\nBgNVHQ4EFgQUm9hlUa/n5yw3rQjuaRnZvzeErgowDgYDVR0PAQH/BAQDAgEGMBIG\nA1UdEwEB/wQIMAYBAf8CAQAwHQYDVR0lBBYwFAYIKwYBBQUHAwEGCCsGAQUFBwMC\nMDEGA1UdIAQqMCgwCAYGZ4EMAQICMA0GCysGAQQBg44hAQABMA0GCysGAQQBg44h\nAQJuMEMGA1UdHwQ8MDowOKA2oDSGMmh0dHA6Ly9jcmwuY29tb2RvY2EuY29tL0FB\nQUNlcnRpZmljYXRlU2VydmljZXMuY3JsMDQGCCsGAQUFBwEBBCgwJjAkBggrBgEF\nBQcwAYYYaHR0cDovL29jc3AuY29tb2RvY2EuY29tMA0GCSqGSIb3DQEBCwUAA4IB\nAQALRoOSvkzRa+tN5Rje9W5GiXd/qsicd9N6Gnh0SWC7VyWH+HycIqAnFCMYZznj\nCeGusomFYHE42SHWr85JDIbgzy6y3dO4i9n9w0Bx7yrXWBbDzFS8VgA3+EY4Cg7y\nmtoC3RPOJVtaXXPZ+68X804g1Mj+3vCSHj2lNPVgco0OzSIOJ/KMg1R9MLBkiKzb\nbERAGZHejY0HBhYd76IINZN8z6bBNah2UdFYxsOisLynPQUkol6gRLum024/FzVl\nCCDfnUusrkr+mAfPAvD/Vb8bhpA7jYtepuU+2mIdShj5lLlvAwZphn+ypWycuo2x\n0k9mldz2dqI9nhCiY+TTIOOR\n-----END CERTIFICATE-----\n",
+    "62b7f9868263f72f6911fc78ceaf72c1979158b7368bf648683bb2aa39b02e72": "-----BEGIN CERTIFICATE-----\nMIIDzzCCAregAwIBAgIRAJHzR/Glt9OZYrleDuTimdEwDQYJKoZIhvcNAQELBQAw\nezELMAkGA1UEBhMCR0IxGzAZBgNVBAgMEkdyZWF0ZXIgTWFuY2hlc3RlcjEQMA4G\nA1UEBwwHU2FsZm9yZDEaMBgGA1UECgwRQ29tb2RvIENBIExpbWl0ZWQxITAfBgNV\nBAMMGEFBQSBDZXJ0aWZpY2F0ZSBTZXJ2aWNlczAeFw0yNTA1MTQwMDAwMDBaFw0y\nODEyMzEyMzU5NTlaMEAxCzAJBgNVBAYTAlVTMRQwEgYDVQQKDAtlTXVkaHJhIElu\nYzEbMBkGA1UEAwwSRU0gRFYgVExTIENBIC0gRzNDMHYwEAYHKoZIzj0CAQYFK4EE\nACIDYgAEOnp4YsjETTJN3WkDOmeCwO/u/kBV5ooSP6A3G6O9kZRRTuFypDPjYw8C\nvRiAN9nlFJ+bd9uUooHfmHsv6oiLdL3+j9pMEJnubKGVZv4+8OX2sJpVbMyLpQVh\n3xsqRB0Bo4IBNTCCATEwHwYDVR0jBBgwFoAUoBEKIz6W8Qfs4q8p74Klf9AwpLQw\nHQYDVR0OBBYEFK5+EFw8KZbBqEcnBVnx4D3U5QrzMA4GA1UdDwEB/wQEAwIBBjAS\nBgNVHRMBAf8ECDAGAQH/AgEAMB0GA1UdJQQWMBQGCCsGAQUFBwMBBggrBgEFBQcD\nAjAxBgNVHSAEKjAoMAgGBmeBDAECATANBgsrBgEEAYOOIQEAATANBgsrBgEEAYOO\nIQECZDBDBgNVHR8EPDA6MDigNqA0hjJodHRwOi8vY3JsLmNvbW9kb2NhLmNvbS9B\nQUFDZXJ0aWZpY2F0ZVNlcnZpY2VzLmNybDA0BggrBgEFBQcBAQQoMCYwJAYIKwYB\nBQUHMAGGGGh0dHA6Ly9vY3NwLmNvbW9kb2NhLmNvbTANBgkqhkiG9w0BAQsFAAOC\nAQEAr7b6Mx11TIJgVzHt6EH5qGNWeiiqoMrp8E5/k8s+jvupx1n083pZ5XOzUzND\nwEUe0W4C4FIGUHNQ4XDwqOw0yK42xqm2dvCKgsko2UvDlT0haZVtTCeWMQOe5J/J\nziaMfZwsZNfZ3aaI6XPtWDZtwY8AaNfyaeCpbtm5GcGnyNWk4jSNpbtpo6NjfXuP\nCFOm3rTjJ4zytP7Tso6iMm0L01cYFOlTmoPv4515R2r3SPnKDtijoB/D/vgxzojv\nDafgyG9afX8+laO9NbMMz4sqC1vZx3984i/sBNFiugm3Vvdq5OdJRjuGC1QILIs6\ndg/K3i8VQqRpbfaM9kIlMzZ3dQ==\n-----END CERTIFICATE-----\n",
+    "66374ae64962c437bd815a2aae546c76e30c2eafac8335192c8e517c15a246ed": "-----BEGIN CERTIFICATE-----\nMIICNzCCAb6gAwIBAgIUPfthO0PYGAYKs9lQ4gp1IOkOr2MwCgYIKoZIzj0EAwIw\nPzELMAkGA1UEBhMCTkwxEzARBgNVBAoMCmVNdWRocmEgQlYxGzAZBgNVBAMMEkVN\nIEVWIFRMUyBDQSAtIEczQjAeFw0yNjEwMjAwMDU5MzZaFw0yNzA1MDMwMTA0MzZa\nMC8xLTArBgNVBAMMJGV2LWczYi1lbXVkaHJhLndlLWhhdmUtYS1wcm9ibGVtLmNv\nbTBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IABPZPwlA3io/AX/pMwu0dNl9WMxrr\nC9j/xMLHgG72cWVzoX62REmvp9zyXQ04kHP9/sW6KnCcm5ZZ5i4YoJbDPASjgacw\ngaQwDAYDVR0TAQH/BAIwADAOBgNVHQ8BAf8EBAMCB4AwEwYDVR0lBAwwCgYIKwYB\nBQUHAwEwLwYDVR0RBCgwJoIkZXYtZzNiLWVtdWRocmEud2UtaGF2ZS1hLXByb2Js\nZW0uY29tMB0GA1UdDgQWBBSvX4QR4ERW5uNUaMq0yYzXCZf0ZjAfBgNVHSMEGDAW\ngBQ+3CDZiUaYh3uHP9iBR7JcFdhHBjAKBggqhkjOPQQDAgNnADBkAjACy/uJR01M\n/O9IEZyRHX1LSU28bmg542K0IX9jDRTrZXUqkDWfiZIL7xfnrRrBpHoCMFbBIaOa\nWwWtFtDg9ZqQvktsWS950u5qfW1sChgWNya/E3IMKFgtoHm2xrZsmfwLSQ==\n-----END CERTIFICATE-----\n",
+    "7485b51c0ed192878fa1d2f948fb529ae1842cc5086c4b67f7be5b2039de9489": "-----BEGIN CERTIFICATE-----\nMIIDzzCCAregAwIBAgIRAI1aSBGTnvRH13ERzdmEmukwDQYJKoZIhvcNAQELBQAw\nezELMAkGA1UEBhMCR0IxGzAZBgNVBAgMEkdyZWF0ZXIgTWFuY2hlc3RlcjEQMA4G\nA1UEBwwHU2FsZm9yZDEaMBgGA1UECgwRQ29tb2RvIENBIExpbWl0ZWQxITAfBgNV\nBAMMGEFBQSBDZXJ0aWZpY2F0ZSBTZXJ2aWNlczAeFw0yNTA1MTQwMDAwMDBaFw0y\nODEyMzEyMzU5NTlaMEAxCzAJBgNVBAYTAlVTMRQwEgYDVQQKDAtlTXVkaHJhIElu\nYzEbMBkGA1UEAwwSRU0gT1YgVExTIENBIC0gRzNDMHYwEAYHKoZIzj0CAQYFK4EE\nACIDYgAEE4JRzVKskpjByKrZdzId65fnCb0LTKCspV3IrVHc/J0ViaFZfjpRIOHv\n1jHGPhg1ysrimGmmLhYx6KKBgatWYW3EXZGKvAnzqw5jz3kqpNztc4e+N7ulaVSf\nHAKycO1no4IBNTCCATEwHwYDVR0jBBgwFoAUoBEKIz6W8Qfs4q8p74Klf9AwpLQw\nHQYDVR0OBBYEFDTq6gzryQra+dDF4u2beMmHnhtsMA4GA1UdDwEB/wQEAwIBBjAS\nBgNVHRMBAf8ECDAGAQH/AgEAMB0GA1UdJQQWMBQGCCsGAQUFBwMBBggrBgEFBQcD\nAjAxBgNVHSAEKjAoMAgGBmeBDAECAjANBgsrBgEEAYOOIQEAATANBgsrBgEEAYOO\nIQECbjBDBgNVHR8EPDA6MDigNqA0hjJodHRwOi8vY3JsLmNvbW9kb2NhLmNvbS9B\nQUFDZXJ0aWZpY2F0ZVNlcnZpY2VzLmNybDA0BggrBgEFBQcBAQQoMCYwJAYIKwYB\nBQUHMAGGGGh0dHA6Ly9vY3NwLmNvbW9kb2NhLmNvbTANBgkqhkiG9w0BAQsFAAOC\nAQEAHlbhZpjhkPEAQVhPHRtBDaHqiisVD20pQ1TUeSx3l62Qe7NQ0b7vWQy7DN0i\nKOu7BGpP5EnIjvXbz9FhpfPJ4FhKEt3tQ51rqXz2oD8vRaryvExWPobDUz3j7HN6\nOzBsVMIe3PD7AAkpky0x8zMSi/ep5R9OMzybmNptbtppyuB5ytgq+h7lQdRIP+CQ\nTaJX3qTgfMqzntYre5GljmEB5hU2/rSn8zoSU2APkJidlZFpghtgbD4I2VRHZvCw\nFFr/SrFM9pwrgbJNZ1MtyTSVgI5NlNb0aMfLR+/r6jJt3ROeY2yh2QQ2dx+Yqgdb\nuL5ChFWOQU+ErSDnUq7yr+pjBQ==\n-----END CERTIFICATE-----\n",
+    "7dd78d5f4f13459a83dff9abbba62edbaf6f2d102bf257fd712f4d9f2746ed8d": "-----BEGIN CERTIFICATE-----\nMIICKTCCAa+gAwIBAgIQDnYGcvFDRZ/I/gqwvAXjlDAKBggqhkjOPQQDAzBWMQsw\nCQYDVQQGEwJJTjElMCMGA1UECgwcZU11ZGhyYSBUZWNobm9sb2dpZXMgTGltaXRl\nZDEgMB4GA1UEAwwXZW1TaWduIFJvb3QgVExTIENBIC0gRzMwHhcNMjQwMjA4MDgx\nOTMyWhcNNDkwMjA3MDgxOTMyWjBWMQswCQYDVQQGEwJJTjElMCMGA1UECgwcZU11\nZGhyYSBUZWNobm9sb2dpZXMgTGltaXRlZDEgMB4GA1UEAwwXZW1TaWduIFJvb3Qg\nVExTIENBIC0gRzMwdjAQBgcqhkjOPQIBBgUrgQQAIgNiAARfD9w/q1cWxL6D9bMG\nH6CQ4u+gAV6GN9s+PwQx9Bl4hC+0iU8QOk8mWO/RwXQy10DCSxT8vSIJClHKp+Ao\n4qJKdYeV0SwZ7LMQziyLfxIUOY6Grja/sQFwLKYf8EdDXAyjQjBAMB0GA1UdDgQW\nBBThOqshfPHjTVSu1HK3/YtZQiCQVDAOBgNVHQ8BAf8EBAMCAQYwDwYDVR0TAQH/\nBAUwAwEB/zAKBggqhkjOPQQDAwNoADBlAjBhCFTkly7Yl7+s4hiw+k6ZJTXT2AiI\nrvmsmfqPr5E7ecwXb6kXA5LTFd6rjwTuV3sCMQC9w6ZSbVq1mveMO6dKFziOzClT\nKCT2RFT6yXtq6nzgRICgBmiXbJAXsmZ8yAwjyWc=\n-----END CERTIFICATE-----\n",
+    "7e02622ab6d745c1edb4b431bb1c551e667305c3dd3eb0c7cc6dfdb523807424": "-----BEGIN CERTIFICATE-----\nMIICQDCCAcagAwIBAgIUU3mgjls/8ZJ8upmukdlSQR1IF/UwCgYIKoZIzj0EAwIw\nPzELMAkGA1UEBhMCTkwxEzARBgNVBAoMCmVNdWRocmEgQlYxGzAZBgNVBAMMEkVN\nIERWIFRMUyBDQSAtIEczQjAeFw0yNjEwMjAwMjIyNDFaFw0yNzA1MDMwMjI3NDFa\nMDMxMTAvBgNVBAMMKGR2LWczYi1hYWEtZW11ZGhyYS53ZS1oYXZlLWEtcHJvYmxl\nbS5jb20wWTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAATK3sfcOxxtM2Vdq9Qbw/GR\nNsHlJcnqINEInXO3fkWhw/FYT80hkqGk0jSN/EKib3YZJsr5GyfkYcpEiA2rwMgm\no4GrMIGoMAwGA1UdEwEB/wQCMAAwDgYDVR0PAQH/BAQDAgeAMBMGA1UdJQQMMAoG\nCCsGAQUFBwMBMDMGA1UdEQQsMCqCKGR2LWczYi1hYWEtZW11ZGhyYS53ZS1oYXZl\nLWEtcHJvYmxlbS5jb20wHQYDVR0OBBYEFDggfJFz1eeToKmzFBSYkMCvpAu0MB8G\nA1UdIwQYMBaAFOIeL+ccGTkOVUtiwSAkVzUkiiUUMAoGCCqGSM49BAMCA2gAMGUC\nMDqDDOt7K313QIH0rhn/ZKnzFu8+/9W8OlTuFtDfVCTRDfRmqdyfsCfLsEk7xqHq\nuQIxAJqyLERABmU98U46OCuT5bp5h0ytuSEIGM7orTpKci5S1u1B/AOmwv162U7R\nTcVPHA==\n-----END CERTIFICATE-----\n",
+    "84112972b8e59d14560ae7e7119654474aad119990cf3722bfc1e3b91615e1fd": "-----BEGIN CERTIFICATE-----\nMIIDxTCCAq2gAwIBAgIRANal72E7OQ8y75zfNJ93KEEwDQYJKoZIhvcNAQELBQAw\nezELMAkGA1UEBhMCR0IxGzAZBgNVBAgMEkdyZWF0ZXIgTWFuY2hlc3RlcjEQMA4G\nA1UEBwwHU2FsZm9yZDEaMBgGA1UECgwRQ29tb2RvIENBIExpbWl0ZWQxITAfBgNV\nBAMMGEFBQSBDZXJ0aWZpY2F0ZSBTZXJ2aWNlczAeFw0yNTA1MTQwMDAwMDBaFw0y\nODEyMzEyMzU5NTlaMD8xCzAJBgNVBAYTAlVTMRQwEgYDVQQKDAtlTXVkaHJhIElu\nYzEaMBgGA1UEAwwRRU0gT1YgQ1MgQ0EgLSBHM0MwdjAQBgcqhkjOPQIBBgUrgQQA\nIgNiAAS58OBjRwKmnKaq3UQ8/WLEG5uksgkkaX15dOdpGhJvuWr7PjTC/TvF9IMG\nHyZdwqWENjRzI1EENrKPBPOGI2MGeYDiUD4CUy1lRiNacWWiWaHvSW90G1/e53hy\nCOS4+u+jggEsMIIBKDAfBgNVHSMEGDAWgBSgEQojPpbxB+zirynvgqV/0DCktDAd\nBgNVHQ4EFgQU7m9zKY1vv6ezG8OVNPYVVkR4ZrcwDgYDVR0PAQH/BAQDAgEGMBIG\nA1UdEwEB/wQIMAYBAf8CAQAwEwYDVR0lBAwwCgYIKwYBBQUHAwMwMgYDVR0gBCsw\nKTAIBgZngQwBBAEwDQYLKwYBBAGDjiEBAAEwDgYMKwYBBAGDjiEBAoFIMEMGA1Ud\nHwQ8MDowOKA2oDSGMmh0dHA6Ly9jcmwuY29tb2RvY2EuY29tL0FBQUNlcnRpZmlj\nYXRlU2VydmljZXMuY3JsMDQGCCsGAQUFBwEBBCgwJjAkBggrBgEFBQcwAYYYaHR0\ncDovL29jc3AuY29tb2RvY2EuY29tMA0GCSqGSIb3DQEBCwUAA4IBAQBgGbZ+NDkn\n2Fr5dCVs/51+6cT5iEPP1stglX4TI2UaNh9LmPdltxXw3crV8gK5L8i+d+ScGibF\ny0obtBHNTldXDgLnAHIzY3n+pceyKj7O2ae9CYnyuu5RBifeI3XYKowWE+oXnVGF\nOy0CvCJ/JsdP6aYgoCa9hGnAYicYQQL6MOMQZ5PuhcSM8t4giIzrpgrEkUP93GYE\nemDG5Z8BYwKs80lLeQNBnwg/VHJ3iEF/o84RXYwrlrKqJ+33C094o6LNikMJCqOK\n/WYHZSR8Xyhf8GXFAj5pZuI6Bcpug2V/E7i42j8OBhc25aNYDqK+B0qmb90sjNUB\ng3tJeSIb/599\n-----END CERTIFICATE-----\n",
+    "86a1ecba089c4a8d3bbe2734c612ba341d813e043cf9e8a862cd5c57a36bbe6b": "-----BEGIN CERTIFICATE-----\nMIICTjCCAdOgAwIBAgIKPPYHqWhwDtqLhDAKBggqhkjOPQQDAzBrMQswCQYDVQQG\nEwJJTjETMBEGA1UECxMKZW1TaWduIFBLSTElMCMGA1UEChMcZU11ZGhyYSBUZWNo\nbm9sb2dpZXMgTGltaXRlZDEgMB4GA1UEAxMXZW1TaWduIEVDQyBSb290IENBIC0g\nRzMwHhcNMTgwMjE4MTgzMDAwWhcNNDMwMjE4MTgzMDAwWjBrMQswCQYDVQQGEwJJ\nTjETMBEGA1UECxMKZW1TaWduIFBLSTElMCMGA1UEChMcZU11ZGhyYSBUZWNobm9s\nb2dpZXMgTGltaXRlZDEgMB4GA1UEAxMXZW1TaWduIEVDQyBSb290IENBIC0gRzMw\ndjAQBgcqhkjOPQIBBgUrgQQAIgNiAAQjpQy4LRL1KPOxst3iAhKAnjlfSU2fySU0\nWXTsuwYc58Byr+iuL+FBVIcUqEqy6HyC5ltqtdyzdc6LBtCGI79G1Y4PPwT01xyS\nfvalY8L1X44uT6EYGQIrMgqCZH0Wk9GjQjBAMB0GA1UdDgQWBBR8XQKEE9TMipuB\nzhccLikenEhjQjAOBgNVHQ8BAf8EBAMCAQYwDwYDVR0TAQH/BAUwAwEB/zAKBggq\nhkjOPQQDAwNpADBmAjEAvvNhzwIQHWSVB7gYboiFBS+DCBeQyh+KTOgNG3qxrdWB\nCUfvO6wIBHxcmbHtRwfSAjEAnbpV/KlK6O3t5nYBQnvI+GDZjVGLVTv7jHvrZQnD\n+JbNR6iC8hZVdyR+EhCVBCyj\n-----END CERTIFICATE-----\n",
+    "9200d153c3cac272cc06bf68f9ea163fc24659fc3331e77668236fe00645ae52": "-----BEGIN CERTIFICATE-----\nMIICQjCCAcegAwIBAgIUMH3z62Z6agEULBZqrfhpw9/ZpCAwCgYIKoZIzj0EAwIw\nQDELMAkGA1UEBhMCVVMxFDASBgNVBAoMC2VNdWRocmEgSW5jMRswGQYDVQQDDBJF\nTSBEViBUTFMgQ0EgLSBHM0MwHhcNMjYxMDIwMDIyMjQxWhcNMjcwNTAzMDIyNzQx\nWjAzMTEwLwYDVQQDDChkdi1nM2MtYWFhLWVtdWRocmEud2UtaGF2ZS1hLXByb2Js\nZW0uY29tMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEAMPpHsQqEqIerrj/durO\nEN7gkUVJSVgIPN6+VJ2sEGXDyqXAN1fnNzGuASP/4WEr0RIhht3cYvuUYp2SYofr\nw6OBqzCBqDAMBgNVHRMBAf8EAjAAMA4GA1UdDwEB/wQEAwIHgDATBgNVHSUEDDAK\nBggrBgEFBQcDATAzBgNVHREELDAqgihkdi1nM2MtYWFhLWVtdWRocmEud2UtaGF2\nZS1hLXByb2JsZW0uY29tMB0GA1UdDgQWBBT8CNQz4OLVnIwrQYZBF+++9jTCvzAf\nBgNVHSMEGDAWgBSufhBcPCmWwahHJwVZ8eA91OUK8zAKBggqhkjOPQQDAgNpADBm\nAjEAp3ZLdfBvKcZxgR2p8LZaxWzP6uB7zU/EZ9BA49Ds2P5ByYkRodwK5qcwt4J/\nVL/vAjEAnnxrcrDX7SzoJxuho604GBh6eyBLJLCdmcy+qb+LA3u5oxP/OjAzCA4x\nv1kw6Tm4\n-----END CERTIFICATE-----\n",
+    "98b896625c0c230adeec3eb2cf6aad5001ecf9156a68644e82374ce5833bc25b": "-----BEGIN CERTIFICATE-----\nMIIDZjCCAu2gAwIBAgIPbK2jZ/scEACIEg6iAtVoMAoGCCqGSM49BAMDMFYxCzAJ\nBgNVBAYTAklOMSUwIwYDVQQKDBxlTXVkaHJhIFRlY2hub2xvZ2llcyBMaW1pdGVk\nMSAwHgYDVQQDDBdlbVNpZ24gUm9vdCBUTFMgQ0EgLSBHMzAeFw0yNTA0MzAxNjAw\nMTJaFw00MDA0MjgxODMwMDBaMD8xCzAJBgNVBAYTAk5MMRMwEQYDVQQKDAplTXVk\naHJhIEJWMRswGQYDVQQDDBJFTSBPViBUTFMgQ0EgLSBHM0IwdjAQBgcqhkjOPQIB\nBgUrgQQAIgNiAARziXqg6zz9yosSQC/68KvE4SErr43ud4rJ7i1tuD+sKAxeBWOK\n56Ks1xwyKo42HN659pxDArndjXPRzGyqsswK7k4hbOl53VGKSvS2JuVoTN1lgDft\nDIVOTMEvTPhkbQ2jggGWMIIBkjAfBgNVHSMEGDAWgBThOqshfPHjTVSu1HK3/YtZ\nQiCQVDAdBgNVHQ4EFgQUm9hlUa/n5yw3rQjuaRnZvzeErgowHQYDVR0lBBYwFAYI\nKwYBBQUHAwEGCCsGAQUFBwMCMF0GA1UdIARWMFQwOQYLKwYBBAGDjiEBAAEwKjAo\nBggrBgEFBQcCARYcaHR0cDovL3JlcG9zaXRvcnkuZW1zaWduLmNvbTANBgsrBgEE\nAYOOIQECbjAIBgZngQwBAgIwdQYIKwYBBQUHAQEEaTBnMCQGCCsGAQUFBzABhhho\ndHRwOi8vb2NzcC1iLmVtc2lnbi5jb20wPwYIKwYBBQUHMAKGM2h0dHA6Ly9yZXBv\nc2l0b3J5LmVtc2lnbi5jb20vY2VydHMvRU1PVlRMU0NBRzNCLnA3YzA3BgNVHR8E\nMDAuMCygKqAohiZodHRwOi8vY3JsLmVtc2lnbi5jb20vP3Jvb3R0bHNjYWczLmNy\nbDAOBgNVHQ8BAf8EBAMCAQYwEgYDVR0TAQH/BAgwBgEB/wIBADAKBggqhkjOPQQD\nAwNnADBkAjBAk+5BizdJhrED3wb7F2Gm7bWI60dlNd075nghT2TrR4NWKZtJZcbc\n28xxIY/NONICMF6mPdsjosaqmvEMWqKcBh4vsIvXSKnQj5o8zrFB4oKS+accjYTe\n8Dz3bQjauvy9uw==\n-----END CERTIFICATE-----\n",
+    "9dcb21b1841d75313b3c888f4bb9cc01f8f51379a76fbaa241ca492b668839e7": "-----BEGIN CERTIFICATE-----\nMIICOTCCAb6gAwIBAgIUY1R/PHrtXShV0uhLJ5EyjsHvMi0wCgYIKoZIzj0EAwIw\nPzELMAkGA1UEBhMCTkwxEzARBgNVBAoMCmVNdWRocmEgQlYxGzAZBgNVBAMMEkVN\nIERWIFRMUyBDQSAtIEczQjAeFw0yNjEwMjAwMDU5MzZaFw0yNzA1MDMwMTA0MzZa\nMC8xLTArBgNVBAMMJGR2LWczYi1lbXVkaHJhLndlLWhhdmUtYS1wcm9ibGVtLmNv\nbTBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IABFpE24ACBFHQLzpg+7D767thJ3+Q\nNIoJJugUMT/OftEz6G6uDdxlS+9VfXYBDglHjJirjEPFNglOGJoQNQuiz7Gjgacw\ngaQwDAYDVR0TAQH/BAIwADAOBgNVHQ8BAf8EBAMCB4AwEwYDVR0lBAwwCgYIKwYB\nBQUHAwEwLwYDVR0RBCgwJoIkZHYtZzNiLWVtdWRocmEud2UtaGF2ZS1hLXByb2Js\nZW0uY29tMB0GA1UdDgQWBBT4r5v4etYNuG21BqBqs273OkcHiDAfBgNVHSMEGDAW\ngBTiHi/nHBk5DlVLYsEgJFc1JIolFDAKBggqhkjOPQQDAgNpADBmAjEAlxNF+/8l\nAPpgibawACy15yn5bcvTksz2Zw0R9z9nUK9e3MSSk+hXagg7LVb7V4NtAjEA4qyR\nlaFPkaokrnTjqQieq8CgDQ6tIz3FjBvj3D7vkhKXHaml6zD2zT5ih2Y+lD2h\n-----END CERTIFICATE-----\n",
+    "9e39de2881273acc225a149c72ba3e0f51424963669ab633ee1dc7df5db067b4": "-----BEGIN CERTIFICATE-----\nMIIDWzCCAuCgAwIBAgIPeBiTP4+FtGGaKzX7qD0KMAoGCCqGSM49BAMDMFUxCzAJ\nBgNVBAYTAklOMSUwIwYDVQQKDBxlTXVkaHJhIFRlY2hub2xvZ2llcyBMaW1pdGVk\nMR8wHQYDVQQDDBZlbVNpZ24gUm9vdCBDUyBDQSAtIEczMB4XDTI1MDQzMDE2MDgy\nN1oXDTQwMDQyODE4MzAwMFowPjELMAkGA1UEBhMCTkwxEzARBgNVBAoMCmVNdWRo\ncmEgQlYxGjAYBgNVBAMMEUVNIE9WIENTIENBIC0gRzNCMHYwEAYHKoZIzj0CAQYF\nK4EEACIDYgAEqrsPsGZqz88B+tUr/P1MK/LLPDSX3nOVDlgZth/mlQmHQcjEkUOb\nNKBDHK/+W/m0wcjorgAB+fTcitgsWfNjnpbNbD1NsM7+wmw9YlF7N3YTcnQ/jord\nd7EAZPKr5eBQo4IBizCCAYcwHwYDVR0jBBgwFoAUaHQD+IXKjVRQVx0W4MjeRQ2r\nzS0wHQYDVR0OBBYEFHn66OzP2w11jaRY1p+27dx8Sd7mMBMGA1UdJQQMMAoGCCsG\nAQUFBwMDMF4GA1UdIARXMFUwOQYLKwYBBAGDjiEBAAEwKjAoBggrBgEFBQcCARYc\naHR0cDovL3JlcG9zaXRvcnkuZW1zaWduLmNvbTAOBgwrBgEEAYOOIQECgUgwCAYG\nZ4EMAQQBMHQGCCsGAQUFBwEBBGgwZjAkBggrBgEFBQcwAYYYaHR0cDovL29jc3At\nYi5lbXNpZ24uY29tMD4GCCsGAQUFBzAChjJodHRwOi8vcmVwb3NpdG9yeS5lbXNp\nZ24uY29tL2NlcnRzL0VNT1ZDU0NBRzNCLnA3YzA2BgNVHR8ELzAtMCugKaAnhiVo\ndHRwOi8vY3JsLmVtc2lnbi5jb20vP3Jvb3Rjc2NhZzMuY3JsMA4GA1UdDwEB/wQE\nAwIBBjASBgNVHRMBAf8ECDAGAQH/AgEAMAoGCCqGSM49BAMDA2kAMGYCMQC/zr03\nYEELsNKqzUtH2dVFi4BaKFdyrr/6G1dIWp8KAVgsw2/u4lyyboUDaC9jDvICMQC9\nHTxku84tNX9dmHOtH7aC2Nu/JM0jTf6KjZAvovCJzzv1IFWSZpVLZibynMLXOrM=\n-----END CERTIFICATE-----\n",
+    "a496e23ac0cab8155fc9b117b97eae368efcbb9041aec8804d5a308d2d01c2d8": "-----BEGIN CERTIFICATE-----\nMIIDwzCCAqugAwIBAgIQQeMrc6wYXWzg10gLrPhOaTANBgkqhkiG9w0BAQsFADB7\nMQswCQYDVQQGEwJHQjEbMBkGA1UECAwSR3JlYXRlciBNYW5jaGVzdGVyMRAwDgYD\nVQQHDAdTYWxmb3JkMRowGAYDVQQKDBFDb21vZG8gQ0EgTGltaXRlZDEhMB8GA1UE\nAwwYQUFBIENlcnRpZmljYXRlIFNlcnZpY2VzMB4XDTI1MDUxNDAwMDAwMFoXDTI4\nMTIzMTIzNTk1OVowPjELMAkGA1UEBhMCTkwxEzARBgNVBAoMCmVNdWRocmEgQlYx\nGjAYBgNVBAMMEUVNIE9WIENTIENBIC0gRzNCMHYwEAYHKoZIzj0CAQYFK4EEACID\nYgAEqrsPsGZqz88B+tUr/P1MK/LLPDSX3nOVDlgZth/mlQmHQcjEkUObNKBDHK/+\nW/m0wcjorgAB+fTcitgsWfNjnpbNbD1NsM7+wmw9YlF7N3YTcnQ/jordd7EAZPKr\n5eBQo4IBLDCCASgwHwYDVR0jBBgwFoAUoBEKIz6W8Qfs4q8p74Klf9AwpLQwHQYD\nVR0OBBYEFHn66OzP2w11jaRY1p+27dx8Sd7mMA4GA1UdDwEB/wQEAwIBBjASBgNV\nHRMBAf8ECDAGAQH/AgEAMBMGA1UdJQQMMAoGCCsGAQUFBwMDMDIGA1UdIAQrMCkw\nCAYGZ4EMAQQBMA0GCysGAQQBg44hAQABMA4GDCsGAQQBg44hAQKBSDBDBgNVHR8E\nPDA6MDigNqA0hjJodHRwOi8vY3JsLmNvbW9kb2NhLmNvbS9BQUFDZXJ0aWZpY2F0\nZVNlcnZpY2VzLmNybDA0BggrBgEFBQcBAQQoMCYwJAYIKwYBBQUHMAGGGGh0dHA6\nLy9vY3NwLmNvbW9kb2NhLmNvbTANBgkqhkiG9w0BAQsFAAOCAQEAIh0OzWsdBYhY\n7+yxPGyosRL+uUSN6/Mrd30fBuougs5FVWQ3cRgLhImnUUgXADY9buugWhMmfT3c\nyU5T1MFXZXClCILm5mfg+oqm/ikUWJl3Ayf2GvYf2O++6vzqvkn418nI5Lpdt0O7\nLi524YS/3CZHDA+zZQ7rrHpZXgQ9Hmp8AUQ4FneaGjNanFoYxiZxwCyW5z4u7AoK\n0bmOVqKtcDFoVNz5++G9TYDJdhWOXmKKgzqRo1MK0PjazNT7MGHqknP93SqMVJ1g\nmX/qNWxYteAjlvFanQxBNX/+TRxDjuFsEHO/7BvqSpIIck0UEEfizhN8zNpWLbcl\nEqVgl0g39A==\n-----END CERTIFICATE-----\n",
+    "bc88231a840e54cced148da48806169e8d0b1c0a96267a427aeccda9d10e6145": "-----BEGIN CERTIFICATE-----\nMIICQDCCAcagAwIBAgIUUYu3O8bpN1GPvCIHqWpT/FYUNDowCgYIKoZIzj0EAwIw\nPzELMAkGA1UEBhMCTkwxEzARBgNVBAoMCmVNdWRocmEgQlYxGzAZBgNVBAMMEkVN\nIEVWIFRMUyBDQSAtIEczQjAeFw0yNjEwMjAwMjIyNDFaFw0yNzA1MDMwMjI3NDFa\nMDMxMTAvBgNVBAMMKGV2LWczYi1hYWEtZW11ZGhyYS53ZS1oYXZlLWEtcHJvYmxl\nbS5jb20wWTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAASjDLpnVdmvXM6R3UB2o42a\n1GnrYfxRXo7UII36mBl9mIS7p9MkAryhPdxitFHkgTrrbypVtzpydNtJIGGGXUwE\no4GrMIGoMAwGA1UdEwEB/wQCMAAwDgYDVR0PAQH/BAQDAgeAMBMGA1UdJQQMMAoG\nCCsGAQUFBwMBMDMGA1UdEQQsMCqCKGV2LWczYi1hYWEtZW11ZGhyYS53ZS1oYXZl\nLWEtcHJvYmxlbS5jb20wHQYDVR0OBBYEFEVBY1ecTN9bLMDl4ifdnN2WZL+WMB8G\nA1UdIwQYMBaAFD7cINmJRpiHe4c/2IFHslwV2EcGMAoGCCqGSM49BAMCA2gAMGUC\nMQCyvr9gktgmtsuTuFleFV+YExNNKLf3GZieuUprQcERrzh798oYKavTqZeYf9Kz\nRhECMCVs1B7KPh7/lgHRly14Z8RJA8ApR7e2cRREW5uPKFOSDlZ/RIezxsfEzsQ4\nlAODeA==\n-----END CERTIFICATE-----\n",
+    "bcd6ab59ea95fd520bfe7709679b1f682abbd79c77367e84e25415b91de37753": "-----BEGIN CERTIFICATE-----\nMIICQDCCAcegAwIBAgIUTMUrGzSU+0BySFdrN3ALZq9Spv8wCgYIKoZIzj0EAwIw\nQDELMAkGA1UEBhMCVVMxFDASBgNVBAoMC2VNdWRocmEgSW5jMRswGQYDVQQDDBJF\nTSBFViBUTFMgQ0EgLSBHM0MwHhcNMjYxMDIwMDIyMjQyWhcNMjcwNTAzMDIyNzQy\nWjAzMTEwLwYDVQQDDChldi1nM2MtYWFhLWVtdWRocmEud2UtaGF2ZS1hLXByb2Js\nZW0uY29tMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEglClDbotLFFeY9SpryT4\nk958tvriY2DDnaPsmjQaecRhB6+L/8hLw6FMt+HT8SLvjIZnFY+AH92cBjedcNST\nAKOBqzCBqDAMBgNVHRMBAf8EAjAAMA4GA1UdDwEB/wQEAwIHgDATBgNVHSUEDDAK\nBggrBgEFBQcDATAzBgNVHREELDAqgihldi1nM2MtYWFhLWVtdWRocmEud2UtaGF2\nZS1hLXByb2JsZW0uY29tMB0GA1UdDgQWBBSVtGbn6xUT1iosUeaGA15Nq640aTAf\nBgNVHSMEGDAWgBSmJV6AqU2385Z8G8eR35K87kvrXzAKBggqhkjOPQQDAgNnADBk\nAjAg7b5bIK9X50QEX0U6G8fQh12BnFQ079Iluzd0Y2TJWCjtVXZi3nOciM8RzNKM\ntZECMCBf0JOyMt8RNS93Wj8kYbWkCtoKoUrqx7G3JTfGReKci+DdTvkF8/3F6doi\n9KB22Q==\n-----END CERTIFICATE-----\n",
+    "cb6e15165ac802e9b3f993f16c25d41f4e81c21ebde71ae1b012ac00bf9c7c3f": "-----BEGIN CERTIFICATE-----\nMIIDaDCCAu6gAwIBAgIPKWkmwiejoVJjkrGUgqUEMAoGCCqGSM49BAMDMFYxCzAJ\nBgNVBAYTAklOMSUwIwYDVQQKDBxlTXVkaHJhIFRlY2hub2xvZ2llcyBMaW1pdGVk\nMSAwHgYDVQQDDBdlbVNpZ24gUm9vdCBUTFMgQ0EgLSBHMzAeFw0yNTA0MzAxNTM3\nNDFaFw00MDA0MjgxODMwMDBaMEAxCzAJBgNVBAYTAlVTMRQwEgYDVQQKDAtlTXVk\naHJhIEluYzEbMBkGA1UEAwwSRU0gT1YgVExTIENBIC0gRzNDMHYwEAYHKoZIzj0C\nAQYFK4EEACIDYgAEE4JRzVKskpjByKrZdzId65fnCb0LTKCspV3IrVHc/J0ViaFZ\nfjpRIOHv1jHGPhg1ysrimGmmLhYx6KKBgatWYW3EXZGKvAnzqw5jz3kqpNztc4e+\nN7ulaVSfHAKycO1no4IBljCCAZIwHwYDVR0jBBgwFoAU4TqrIXzx401UrtRyt/2L\nWUIgkFQwHQYDVR0OBBYEFDTq6gzryQra+dDF4u2beMmHnhtsMB0GA1UdJQQWMBQG\nCCsGAQUFBwMBBggrBgEFBQcDAjBdBgNVHSAEVjBUMDkGCysGAQQBg44hAQABMCow\nKAYIKwYBBQUHAgEWHGh0dHA6Ly9yZXBvc2l0b3J5LmVtc2lnbi5jb20wDQYLKwYB\nBAGDjiEBAm4wCAYGZ4EMAQICMHUGCCsGAQUFBwEBBGkwZzAkBggrBgEFBQcwAYYY\naHR0cDovL29jc3AtYy5lbXNpZ24uY29tMD8GCCsGAQUFBzAChjNodHRwOi8vcmVw\nb3NpdG9yeS5lbXNpZ24uY29tL2NlcnRzL0VNT1ZUTFNDQUczQy5wN2MwNwYDVR0f\nBDAwLjAsoCqgKIYmaHR0cDovL2NybC5lbXNpZ24uY29tLz9yb290dGxzY2FnMy5j\ncmwwDgYDVR0PAQH/BAQDAgEGMBIGA1UdEwEB/wQIMAYBAf8CAQAwCgYIKoZIzj0E\nAwMDaAAwZQIxAMSZt2xsPeumRdeSMSQ3CbzIZeQ/q7GDCWfeE1Pq+mhgA6gRM44c\nNVF3xJ+wsxJk+wIwFJbaDMokD8Ei6eNOiA8yUMYvfzQyngmrhZQMdPCK1SewrR79\n4rSb9vGqxZzelQth\n-----END CERTIFICATE-----\n",
+    "ccd80467f9cac38f115dcb6e4f57e4d74f5efa519814ea934aeb3be53b83a191": "-----BEGIN CERTIFICATE-----\nMIICOTCCAb+gAwIBAgIUOcw5N4XGLiB/3GvB05bJuGoZPR0wCgYIKoZIzj0EAwIw\nQDELMAkGA1UEBhMCVVMxFDASBgNVBAoMC2VNdWRocmEgSW5jMRswGQYDVQQDDBJF\nTSBFViBUTFMgQ0EgLSBHM0MwHhcNMjYxMDIwMDA1OTM3WhcNMjcwNTAzMDEwNDM3\nWjAvMS0wKwYDVQQDDCRldi1nM2MtZW11ZGhyYS53ZS1oYXZlLWEtcHJvYmxlbS5j\nb20wWTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAAQo7U02MAUO8EEMomXwIl+kSQzm\nb+nvXKIZ/hC4rZ1GpXchv4SzTrV1SB/Qg+pD6OBEXbBBnPmQNkePNQTlujqRo4Gn\nMIGkMAwGA1UdEwEB/wQCMAAwDgYDVR0PAQH/BAQDAgeAMBMGA1UdJQQMMAoGCCsG\nAQUFBwMBMC8GA1UdEQQoMCaCJGV2LWczYy1lbXVkaHJhLndlLWhhdmUtYS1wcm9i\nbGVtLmNvbTAdBgNVHQ4EFgQUqxe+7qS+MxNyioJZhQsL5MEEw6swHwYDVR0jBBgw\nFoAUpiVegKlNt/OWfBvHkd+SvO5L618wCgYIKoZIzj0EAwIDaAAwZQIwC/CxSIov\nwcar3sV98B8cL+QuR2kkJdLdXsFKzg/HDSJ1MOjqTGm924LB6r9nl0f7AjEAzcwr\nWQOYY9eycqIz+LG2daYS6LOctj+CjoAk/CLugWPxGxp4Aerfau2P1z1h5jAA\n-----END CERTIFICATE-----\n",
+    "d7a7a0fb5d7e2731d771e9484ebcdef71d5f0c3e0a2948782bc83ee0ea699ef4": "-----BEGIN CERTIFICATE-----\nMIIEMjCCAxqgAwIBAgIBATANBgkqhkiG9w0BAQUFADB7MQswCQYDVQQGEwJHQjEb\nMBkGA1UECAwSR3JlYXRlciBNYW5jaGVzdGVyMRAwDgYDVQQHDAdTYWxmb3JkMRow\nGAYDVQQKDBFDb21vZG8gQ0EgTGltaXRlZDEhMB8GA1UEAwwYQUFBIENlcnRpZmlj\nYXRlIFNlcnZpY2VzMB4XDTA0MDEwMTAwMDAwMFoXDTI4MTIzMTIzNTk1OVowezEL\nMAkGA1UEBhMCR0IxGzAZBgNVBAgMEkdyZWF0ZXIgTWFuY2hlc3RlcjEQMA4GA1UE\nBwwHU2FsZm9yZDEaMBgGA1UECgwRQ29tb2RvIENBIExpbWl0ZWQxITAfBgNVBAMM\nGEFBQSBDZXJ0aWZpY2F0ZSBTZXJ2aWNlczCCASIwDQYJKoZIhvcNAQEBBQADggEP\nADCCAQoCggEBAL5AnfRu4ep2hxxNRUSOvkbIgwadwSr+GB+O5AL686tdUIoWMQua\nBtDFcCLNSS1UY8y2bmhGC1Pqy0wkwLxyTurxFa70VJoSCsN6sjNg4tqJVfMiWPPe\n3M/vg4aijJRPn2jymJBGhCfHdr/jzDUsi14HZGWCwEiwqJH5YZ92IFCokcdmtet4\nYgNW8IoaE+oxox6gmf049vYnMlhvB/VruPsUK6+3qszWY19zjNoFmag4qMsXeDZR\nrOme9Hg6jc8P2ULimAyrL58OAd7vn5lJ8S3frHRNG5i1R8XlKdH5kBjHYpy+g8cm\nez6KJcfA3Z3mNWgQIJ2P2N7Sw4ScDV7oL8kCAwEAAaOBwDCBvTAdBgNVHQ4EFgQU\noBEKIz6W8Qfs4q8p74Klf9AwpLQwDgYDVR0PAQH/BAQDAgEGMA8GA1UdEwEB/wQF\nMAMBAf8wewYDVR0fBHQwcjA4oDagNIYyaHR0cDovL2NybC5jb21vZG9jYS5jb20v\nQUFBQ2VydGlmaWNhdGVTZXJ2aWNlcy5jcmwwNqA0oDKGMGh0dHA6Ly9jcmwuY29t\nb2RvLm5ldC9BQUFDZXJ0aWZpY2F0ZVNlcnZpY2VzLmNybDANBgkqhkiG9w0BAQUF\nAAOCAQEACFb8AvCb6P+k+tZ7xkSAzk/ExfYAWMymtrwUSWgEdujm7l3sAg9g1o1Q\nGE8mTgHj5rCl7r+8dFRBv/38ErjHT1r0iWAFf2C3BUrz9vHCv8S5dIa2LX1rzNLz\nRt0vxuBqw8M0Ayx9lt1awg6nCpnBBYurDC/zXDrPbDdVCYfeU0BsWO/8tqtlbgT2\nG9w84FoVxp7Z8VlIMCFlA2zs6SFz7JsDoeA3raAVGI/6ugLOpyypEBMs1OUIJqsi\nl2D4kF501KKaU73yqWjgom7C12yxow+ev+to51byrvLjKzg6CYG1a4XXvi3tPxq3\nsmPi9WIsgtRqAEFQ8TmDn5XpNpaYbg==\n-----END CERTIFICATE-----\n",
+    "e7568fe6e12331f4fd7de61da4c7559d0f8eb192a218d4741a3ba75184333838": "-----BEGIN CERTIFICATE-----\nMIIDaDCCAu2gAwIBAgIQAMfEHv6S2CXwXq6EGkqCwTAKBggqhkjOPQQDAzBWMQsw\nCQYDVQQGEwJJTjElMCMGA1UECgwcZU11ZGhyYSBUZWNobm9sb2dpZXMgTGltaXRl\nZDEgMB4GA1UEAwwXZW1TaWduIFJvb3QgVExTIENBIC0gRzMwHhcNMjUwNDMwMTYw\nMzMxWhcNNDAwNDI4MTgzMDAwWjA/MQswCQYDVQQGEwJOTDETMBEGA1UECgwKZU11\nZGhyYSBCVjEbMBkGA1UEAwwSRU0gRVYgVExTIENBIC0gRzNCMHYwEAYHKoZIzj0C\nAQYFK4EEACIDYgAEJduoWmTTl9oLEFLp6lRuSHvv6pydnWigxerc/u91ppu11vwB\n9Cv7ym60C81kwHZ+Nv/QXZeoE8WqDGyVMOec9fCGZGjxOAZCCqXIUYQLHiUlQOeQ\n5LZUw4Uu1krx6GV9o4IBlTCCAZEwHwYDVR0jBBgwFoAU4TqrIXzx401UrtRyt/2L\nWUIgkFQwHQYDVR0OBBYEFD7cINmJRpiHe4c/2IFHslwV2EcGMB0GA1UdJQQWMBQG\nCCsGAQUFBwMBBggrBgEFBQcDAjBcBgNVHSAEVTBTMDkGCysGAQQBg44hAQABMCow\nKAYIKwYBBQUHAgEWHGh0dHA6Ly9yZXBvc2l0b3J5LmVtc2lnbi5jb20wDQYLKwYB\nBAGDjiEBAngwBwYFZ4EMAQEwdQYIKwYBBQUHAQEEaTBnMCQGCCsGAQUFBzABhhho\ndHRwOi8vb2NzcC1iLmVtc2lnbi5jb20wPwYIKwYBBQUHMAKGM2h0dHA6Ly9yZXBv\nc2l0b3J5LmVtc2lnbi5jb20vY2VydHMvRU1FVlRMU0NBRzNCLnA3YzA3BgNVHR8E\nMDAuMCygKqAohiZodHRwOi8vY3JsLmVtc2lnbi5jb20vP3Jvb3R0bHNjYWczLmNy\nbDAOBgNVHQ8BAf8EBAMCAQYwEgYDVR0TAQH/BAgwBgEB/wIBADAKBggqhkjOPQQD\nAwNpADBmAjEA9Jq999oaOUKhFwopw33iCmt0OHIn3gjT43GfuOHR/YckXdwoNdDA\nlIEhz0NgRO3/AjEAvY/a3OMvktIZLYjn+WLKmp0QhrIMV+e6EpS7j4GVeOKouNp6\nMN/P+ByGeiRMghzB\n-----END CERTIFICATE-----\n",
+    "f2edaaff3d9b701fb4d14c9f285f8c0bad90fc3bcc1fa07d47f4718edaba34a5": "-----BEGIN CERTIFICATE-----\nMIICKDCCAa2gAwIBAgIQAY/OySfBFvWcmX7cDM0uKzAKBggqhkjOPQQDAzBVMQsw\nCQYDVQQGEwJJTjElMCMGA1UECgwcZU11ZGhyYSBUZWNobm9sb2dpZXMgTGltaXRl\nZDEfMB0GA1UEAwwWZW1TaWduIFJvb3QgQ1MgQ0EgLSBHMzAeFw0yNDAyMDgwODMz\nMTRaFw00OTAyMDcwODMzMTRaMFUxCzAJBgNVBAYTAklOMSUwIwYDVQQKDBxlTXVk\naHJhIFRlY2hub2xvZ2llcyBMaW1pdGVkMR8wHQYDVQQDDBZlbVNpZ24gUm9vdCBD\nUyBDQSAtIEczMHYwEAYHKoZIzj0CAQYFK4EEACIDYgAESl9kM5D0VA/Og76dz5Xz\nw1hnGQ4fSR9993/qBkkvI48pXQVKOdyHCgAZThgWejQ8OpFRiTISjpabn4tfRFOY\nuzhApR/XxGbkg9X+2cEtbyghF9CdoF91W22V/R2EVe4xo0IwQDAdBgNVHQ4EFgQU\naHQD+IXKjVRQVx0W4MjeRQ2rzS0wDgYDVR0PAQH/BAQDAgEGMA8GA1UdEwEB/wQF\nMAMBAf8wCgYIKoZIzj0EAwMDaQAwZgIxAK9OlACrFod3UgWY1ai+DF9sGFhahU59\nrv4jJyV01QaxGn0HErZ8gjHkngqe+tcFogIxAPTdW0hBmrGjhxBWdv9mZNdVFiJ4\nlrZ3ahvimsLhTQpnDBgiGKv6Ov1Fx/CE6yjIAg==\n-----END CERTIFICATE-----\n",
+    "f3c3c15bc7edf2b3ebdc922af112f2a0c414eb509901099ef0488c0942e77efe": "-----BEGIN CERTIFICATE-----\nMIICODCCAb6gAwIBAgIUPXjC97k7buQHZ7p5ehDU8QNyrR4wCgYIKoZIzj0EAwIw\nPzELMAkGA1UEBhMCTkwxEzARBgNVBAoMCmVNdWRocmEgQlYxGzAZBgNVBAMMEkVN\nIE9WIFRMUyBDQSAtIEczQjAeFw0yNjEwMjAwMDU5MzdaFw0yNzA1MDMwMTA0Mzda\nMC8xLTArBgNVBAMMJG92LWczYi1lbXVkaHJhLndlLWhhdmUtYS1wcm9ibGVtLmNv\nbTBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IABA1haD+95Albk0UN6YtDCPpqevTv\nYUmEhsIVpb/hnhsbBlH0yLthSE2JLH14ywiQJXttoc/pDWC9eoICW6CJXL2jgacw\ngaQwDAYDVR0TAQH/BAIwADAOBgNVHQ8BAf8EBAMCB4AwEwYDVR0lBAwwCgYIKwYB\nBQUHAwEwLwYDVR0RBCgwJoIkb3YtZzNiLWVtdWRocmEud2UtaGF2ZS1hLXByb2Js\nZW0uY29tMB0GA1UdDgQWBBQUhzc4s202Hn62G0srmgguYdY2MTAfBgNVHSMEGDAW\ngBSb2GVRr+fnLDetCO5pGdm/N4SuCjAKBggqhkjOPQQDAgNoADBlAjEAoJ6d4zzA\nxE349yGHHrwKZpVCC/HBFutcOpOfzQoe8ikbmaaBTdtKai5TEllwt3dBAjBeHGiX\nVheDhJfewbei99cw1MfYB5tPwdfuY5pe1MJz0Tg9zJ4JgxBvF6LTT0OOXZ4=\n-----END CERTIFICATE-----\n",
+    "fd9d5c2dbbd4995ab69b8d50c439d9527b00529199c2fd01b2174eb58f07021f": "-----BEGIN CERTIFICATE-----\nMIIDzTCCArWgAwIBAgIQBfB4dS3s56G7hZXTAxZxcTANBgkqhkiG9w0BAQsFADB7\nMQswCQYDVQQGEwJHQjEbMBkGA1UECAwSR3JlYXRlciBNYW5jaGVzdGVyMRAwDgYD\nVQQHDAdTYWxmb3JkMRowGAYDVQQKDBFDb21vZG8gQ0EgTGltaXRlZDEhMB8GA1UE\nAwwYQUFBIENlcnRpZmljYXRlIFNlcnZpY2VzMB4XDTI1MDUxNDAwMDAwMFoXDTI4\nMTIzMTIzNTk1OVowQDELMAkGA1UEBhMCVVMxFDASBgNVBAoMC2VNdWRocmEgSW5j\nMRswGQYDVQQDDBJFTSBFViBUTFMgQ0EgLSBHM0MwdjAQBgcqhkjOPQIBBgUrgQQA\nIgNiAAQtVugppvuCxkpGl9lgr5UekGeukfkm00MG2kioqut4abamfm0nQm4EQqoD\ns24ZiN/2NlFO4c8H9bpLP/KgZkWufTHVhmrTGqPSRusLMXfumct1ZsUWznSAimaP\nkfDEf8qjggE0MIIBMDAfBgNVHSMEGDAWgBSgEQojPpbxB+zirynvgqV/0DCktDAd\nBgNVHQ4EFgQUpiVegKlNt/OWfBvHkd+SvO5L618wDgYDVR0PAQH/BAQDAgEGMBIG\nA1UdEwEB/wQIMAYBAf8CAQAwHQYDVR0lBBYwFAYIKwYBBQUHAwEGCCsGAQUFBwMC\nMDAGA1UdIAQpMCcwBwYFZ4EMAQEwDQYLKwYBBAGDjiEBAAEwDQYLKwYBBAGDjiEB\nAngwQwYDVR0fBDwwOjA4oDagNIYyaHR0cDovL2NybC5jb21vZG9jYS5jb20vQUFB\nQ2VydGlmaWNhdGVTZXJ2aWNlcy5jcmwwNAYIKwYBBQUHAQEEKDAmMCQGCCsGAQUF\nBzABhhhodHRwOi8vb2NzcC5jb21vZG9jYS5jb20wDQYJKoZIhvcNAQELBQADggEB\nAIFfHiaMSjnrdZygRYV4ekRBmG7ybcFk4hGQWMMyMFi0cAEk2+dGfz5bl8IaIbLq\nz+uVJzhOgVEX7WqIfgbWfFsfPYHYjPHBmy7SlZ3BwA86IQ6qF/etpX2/qL9A5yRN\nN3nVowUpaqV6H3aCpkAh3wR2ZNkvAbLDvPz3J0l+sEWjWv+ZISOV4R+hXDTdPXV0\n1lKxnbwqEsdo/sE2QkCDKwFrZh/0uKjWspydJj+jSaDLTrGNx50Dgmn7VEcD1ZI5\nFXjknVUiO25YlmS1dtVZSBbyUKSjlrP/yDwPcZunoAsmCAAtCKsFLviLaymzvsKI\neSSDGxpSySp2VCxompGDk8g=\n-----END CERTIFICATE-----\n"
+  },
+  "chains": {
+    "dv-g3b-aaa-emudhra.we-have-a-problem.com": [
+      "7e02622ab6d745c1edb4b431bb1c551e667305c3dd3eb0c7cc6dfdb523807424",
+      "45a883f349aedfd5f3a649b5498ffb121712ba8b448f3f2a91dbc5a766fcddbe"
+    ],
+    "dv-g3b-emudhra.we-have-a-problem.com": [
+      "9dcb21b1841d75313b3c888f4bb9cc01f8f51379a76fbaa241ca492b668839e7",
+      "42c4accd12c4f59597925e1a08a7a90102608543809308d50ec427e118ba1493",
+      "3094025792039a68af6e553686410bdab7c0d4a36b9084cba64202e35d6ebbdd"
+    ],
+    "dv-g3c-aaa-emudhra.we-have-a-problem.com": [
+      "9200d153c3cac272cc06bf68f9ea163fc24659fc3331e77668236fe00645ae52",
+      "62b7f9868263f72f6911fc78ceaf72c1979158b7368bf648683bb2aa39b02e72"
+    ],
+    "dv-g3c-emudhra.we-have-a-problem.com": [
+      "346cdd962e97189b59aee5526d1ae8fa714bb1a64094dfa67bef768ee93f36b5",
+      "0164d7ceae5bb909c272af151ff44b1177ae9b47d9424b94f1d9558c30934d19",
+      "3094025792039a68af6e553686410bdab7c0d4a36b9084cba64202e35d6ebbdd"
+    ],
+    "ev-g3b-aaa-emudhra.we-have-a-problem.com": [
+      "bc88231a840e54cced148da48806169e8d0b1c0a96267a427aeccda9d10e6145",
+      "579480aea166290bd3c643589e795fc0d0e54e86505d180f1dff99efd3199512"
+    ],
+    "ev-g3b-emudhra.we-have-a-problem.com": [
+      "66374ae64962c437bd815a2aae546c76e30c2eafac8335192c8e517c15a246ed",
+      "e7568fe6e12331f4fd7de61da4c7559d0f8eb192a218d4741a3ba75184333838",
+      "3094025792039a68af6e553686410bdab7c0d4a36b9084cba64202e35d6ebbdd"
+    ],
+    "ev-g3c-aaa-emudhra.we-have-a-problem.com": [
+      "bcd6ab59ea95fd520bfe7709679b1f682abbd79c77367e84e25415b91de37753",
+      "fd9d5c2dbbd4995ab69b8d50c439d9527b00529199c2fd01b2174eb58f07021f"
+    ],
+    "ev-g3c-emudhra.we-have-a-problem.com": [
+      "ccd80467f9cac38f115dcb6e4f57e4d74f5efa519814ea934aeb3be53b83a191",
+      "432ec25f0d28de9006d97bf752f17bbb2cd41f669933fcb072d9a1148d0261f3",
+      "3094025792039a68af6e553686410bdab7c0d4a36b9084cba64202e35d6ebbdd"
+    ],
+    "ov-g3b-aaa-emudhra.we-have-a-problem.com": [
+      "21f57f83631a93c98e867050075746b3361e0433c9e0e969462852476784f6f0",
+      "5f1ded4dd590af74631290cf073b122a2aac6a1fa479778a0bd43579bd832699"
+    ],
+    "ov-g3b-emudhra.we-have-a-problem.com": [
+      "f3c3c15bc7edf2b3ebdc922af112f2a0c414eb509901099ef0488c0942e77efe",
+      "98b896625c0c230adeec3eb2cf6aad5001ecf9156a68644e82374ce5833bc25b",
+      "3094025792039a68af6e553686410bdab7c0d4a36b9084cba64202e35d6ebbdd"
+    ],
+    "ov-g3c-aaa-emudhra.we-have-a-problem.com": [
+      "59cf0386b56bc2414a0c06241ea9e25e01a9c93bac7a596648747f9d0ded4906",
+      "7485b51c0ed192878fa1d2f948fb529ae1842cc5086c4b67f7be5b2039de9489"
+    ],
+    "ov-g3c-emudhra.we-have-a-problem.com": [
+      "4314941cf242a4ea4149aa7e9cdf77a15de2771a79984b809fc04443fea013c8",
+      "cb6e15165ac802e9b3f993f16c25d41f4e81c21ebde71ae1b012ac00bf9c7c3f",
+      "3094025792039a68af6e553686410bdab7c0d4a36b9084cba64202e35d6ebbdd"
+    ]
+  },
+  "cross_signed_roots": {
+    "3094025792039a68af6e553686410bdab7c0d4a36b9084cba64202e35d6ebbdd": "emSign Root TLS CA - G3 (emSign ECC Root CA - G3 cross-sign)"
+  }
+}
diff --git a/tests/test_ca_trust.py b/tests/test_ca_trust.py
index b2ab32d40..24855ea8e 100644
--- a/tests/test_ca_trust.py
+++ b/tests/test_ca_trust.py
@@ -1,11 +1,15 @@
 """Offline regressions for incident roots, unaffected roots, and CA directories."""
 
 import contextlib
+import hashlib
 import importlib.util
 import io
+import json
 import os
 from pathlib import Path
+import shutil
 import ssl
+import subprocess
 import tempfile
 from types import SimpleNamespace
 import unittest
@@ -16,6 +20,7 @@ ROOT = Path(__file__).resolve().parents[1]
 SPEC = importlib.util.spec_from_file_location("check_ca_trust", ROOT / "scripts/check_ca_trust.py")
 checker = importlib.util.module_from_spec(SPEC)
 SPEC.loader.exec_module(checker)
+INCIDENT = json.loads((ROOT / "tests/fixtures/ca-trust/incident.json").read_text())
 
 
 class CATrustTests(unittest.TestCase):
@@ -27,6 +32,10 @@ class CATrustTests(unittest.TestCase):
         cls.fixtures = Path(cls.temporary.name)
         for name, pem in PUBLIC_CERTIFICATES.items():
             (cls.fixtures / name).write_text(pem)
+        for fingerprint, pem in INCIDENT["certificates"].items():
+            if hashlib.sha256(ssl.PEM_cert_to_DER_cert(pem)).hexdigest() != fingerprint:
+                raise ValueError("incident fixture fingerprint mismatch")
+            (cls.fixtures / f"{fingerprint}.pem").write_text(pem)
 
     @classmethod
     def tearDownClass(cls):
@@ -50,6 +59,74 @@ class CATrustTests(unittest.TestCase):
             with self.assertRaisesRegex(ValueError, "AAA Certificate Services"):
                 checker.check_bundle(bundle)
 
+    def test_all_published_intermediates_and_cross_signs_are_rejected(self):
+        self.assertEqual(len(INCIDENT["intermediates"]), 16)
+        for fingerprint, name in INCIDENT["intermediates"].items():
+            with self.subTest(certificate=name), self.assertRaisesRegex(ValueError, "affected CA certificates"):
+                checker.check_bundle(self.fixtures / f"{fingerprint}.pem")
+
+    def test_published_roots_and_cross_signed_issuer_are_rejected(self):
+        certificates = INCIDENT["roots"] | INCIDENT["cross_signed_roots"]
+        self.assertEqual(len(certificates), 5)
+        for fingerprint, name in certificates.items():
+            with self.subTest(certificate=name), self.assertRaises(ValueError):
+                checker.check_bundle(self.fixtures / f"{fingerprint}.pem")
+
+    def test_clean_roots_do_not_hide_an_added_compromised_intermediate(self):
+        fingerprint = next(iter(INCIDENT["intermediates"]))
+        with tempfile.TemporaryDirectory() as tmp:
+            bundle = Path(tmp) / "custom.pem"
+            bundle.write_text(PUBLIC_CERTIFICATES["emsign-g1.pem"] + INCIDENT["certificates"][fingerprint])
+            with self.assertRaisesRegex(ValueError, "EM DV TLS CA - G3B"):
+                checker.check_bundle(bundle)
+
+    @unittest.skipUnless(shutil.which("openssl"), "offline chain verification requires OpenSSL")
+    def test_published_chains_and_custom_anchor_with_affected_positive_control(self):
+        # Freeze time inside the public fixtures' validity interval. Otherwise
+        # expiry could make an ineffective trust-store fix appear successful.
+        help_result = subprocess.run(["openssl", "verify", "-help"], capture_output=True, text=True)
+        no_store = ["-no-CAstore"] if "-no-CAstore" in help_result.stdout + help_result.stderr else []
+        with tempfile.TemporaryDirectory() as tmp:
+            directory = Path(tmp)
+            affected = directory / "affected.pem"
+            affected.write_text("".join(INCIDENT["certificates"][key] for key in INCIDENT["roots"]))
+            clean = self.fixtures / "emsign-g1.pem"
+            custom = directory / "custom.pem"
+            fingerprint = next(iter(INCIDENT["intermediates"]))
+            custom.write_text(clean.read_text() + INCIDENT["certificates"][fingerprint])
+            self.assertEqual(len(INCIDENT["chains"]), 12)
+            custom_accepted = []
+            for hostname, chain in INCIDENT["chains"].items():
+                leaf, intermediates = directory / "leaf.pem", directory / "chain.pem"
+                leaf.write_text(INCIDENT["certificates"][chain[0]])
+                intermediates.write_text("".join(INCIDENT["certificates"][key] for key in chain[1:]))
+
+                def verify(bundle):
+                    return subprocess.run([
+                        "openssl", "verify", "-no-CApath", *no_store,
+                        "-attime", str(INCIDENT["verification_time"]),
+                        "-partial_chain", "-x509_strict", "-purpose", "sslserver",
+                        "-verify_hostname", hostname, "-CAfile", str(bundle),
+                        "-untrusted", str(intermediates), str(leaf),
+                    ], capture_output=True, text=True)
+
+                with self.subTest(hostname=hostname):
+                    positive = verify(affected)
+                    self.assertEqual(positive.returncode, 0, positive.stderr)
+                    negative = verify(clean)
+                    self.assertNotEqual(negative.returncode, 0)
+                    self.assertIn("unable to get local issuer certificate", negative.stderr)
+                    if verify(custom).returncode == 0:
+                        custom_accepted.append(hostname)
+            self.assertEqual(custom_accepted, [
+                "dv-g3b-aaa-emudhra.we-have-a-problem.com",
+                "dv-g3b-emudhra.we-have-a-problem.com",
+            ])
+            checker.check_bundle(clean)
+            for bundle in (affected, custom):
+                with self.subTest(bundle=bundle.name), self.assertRaises(ValueError):
+                    checker.check_bundle(bundle)
+
     def test_empty_malformed_and_missing_bundles_fail_closed(self):
         with tempfile.TemporaryDirectory() as tmp:
             for content in ("", "not a certificate"):
@@ -60,6 +137,48 @@ class CATrustTests(unittest.TestCase):
             with self.assertRaises(OSError):
                 checker.check_bundle(Path(tmp) / "missing.pem")
 
+    def test_each_configured_override_is_checked(self):
+        fingerprint = next(iter(INCIDENT["intermediates"]))
+        affected = self.fixtures / f"{fingerprint}.pem"
+        clean = self.fixtures / "emsign-g1.pem"
+        for name in ("LLM_CA_BUNDLE", "SSL_CERT_FILE", "REQUESTS_CA_BUNDLE", "CURL_CA_BUNDLE",
+                     "PIP_CERT", "NODE_EXTRA_CA_CERTS", "GRPC_DEFAULT_SSL_ROOTS_FILE_PATH"):
+            for bundle, expected in ((clean, 0), (affected, 1)):
+                with self.subTest(variable=name, bundle=bundle.name), patch.dict(
+                    os.environ, {name: str(bundle)}, clear=True
+                ), contextlib.redirect_stdout(io.StringIO()), contextlib.redirect_stderr(io.StringIO()):
+                    self.assertEqual(checker.main(["--overrides", str(clean)]), expected)
+
+    def test_invalid_override_is_not_hidden_by_a_clean_explicit_bundle(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            directory = Path(tmp)
+            for name, content in (("empty.pem", ""), ("malformed.pem", "invalid")):
+                (directory / name).write_text(content)
+            for name in ("missing.pem", "empty.pem", "malformed.pem"):
+                with self.subTest(file=name), patch.dict(
+                    os.environ, {"LLM_CA_BUNDLE": str(directory / name)}, clear=True
+                ), contextlib.redirect_stderr(io.StringIO()):
+                    self.assertEqual(checker.main(["--overrides", str(self.fixtures / "emsign-g1.pem")]), 1)
+
+    def test_no_configured_overrides_does_not_report_validated_stores(self):
+        with patch.dict(os.environ, {"LLM_CA_BUNDLE": "  "}, clear=True), contextlib.redirect_stderr(io.StringIO()):
+            self.assertEqual(checker.main(["--overrides"]), 1)
+
+    def test_requests_directory_override_checks_hashed_intermediates(self):
+        fingerprint = next(iter(INCIDENT["intermediates"]))
+        with tempfile.TemporaryDirectory() as tmp:
+            directory = Path(tmp)
+            for name in ("REQUESTS_CA_BUNDLE", "CURL_CA_BUNDLE", "PIP_CERT"):
+                with self.subTest(variable=name), patch.dict(os.environ, {name: str(directory)}, clear=True):
+                    for content, expected in ((PUBLIC_CERTIFICATES["emsign-g1.pem"], 0),
+                                              (INCIDENT["certificates"][fingerprint], 1)):
+                        (directory / "12345678.0").write_text(content)
+                        with contextlib.redirect_stdout(io.StringIO()), contextlib.redirect_stderr(io.StringIO()):
+                            self.assertEqual(checker.main(["--overrides"]), expected)
+                    (directory / "12345678.0").unlink()
+                    with contextlib.redirect_stderr(io.StringIO()):
+                        self.assertEqual(checker.main(["--overrides"]), 1)
+
     def test_safe_cafile_does_not_hide_stale_hashed_directory(self):
         with tempfile.TemporaryDirectory() as tmp:
             directory = Path(tmp)

From 77a02c30ffd3f86a34f1bc9e2843589acad76e67 Mon Sep 17 00:00:00 2001
From: RaresKeY <158580472+RaresKeY@users.noreply.github.com>
Date: Wed, 21 Oct 2026 21:40:05 +0000
Subject: [PATCH 41/53] fix(security): verify deployed trust before dependency
 work

---
 .github/workflows/ci.yml                  | 22 +++++++------
 docs/tls-trust.md                         | 31 +++++++++++++++---
 scripts/check_ca_trust.py                 |  9 ++++++
 tests/test_ca_trust.py                    | 38 +++++++++++++++++++++++
 tests/test_ci_authoritative_validation.py | 13 ++++++++
 5 files changed, 99 insertions(+), 14 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 29f303ca4..93dcb5e37 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -155,6 +155,17 @@ jobs:
         if: steps.docs-check.outputs.docs_only != 'true'
         with:
           python-version: "3.11"
+      # Establish system trust before dependency installers or their hooks run.
+      # Keep one apt pass for FFmpeg and bubblewrap; containment is checked later.
+      - name: Install FFmpeg and bubblewrap and validate system CA trust
+        if: steps.docs-check.outputs.docs_only != 'true'
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends ffmpeg bubblewrap ca-certificates
+          python scripts/check_ca_trust.py --system
+          command -v ffmpeg
+          ffmpeg -version | head -n 1
+
       # uv resolves the same versions as pip but installs ~5x faster, and its
       # cache keeps each shard from re-downloading the whole requirement set.
       - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7  # v10.2.0
@@ -166,6 +177,7 @@ jobs:
           prune-cache: false
       - run: |
           uv pip install --system --require-hashes --only-binary=:all: --no-deps -r requirements-bootstrap.txt
+          python scripts/check_ca_trust.py --python
           uv pip install --system -r requirements.txt
         if: steps.docs-check.outputs.docs_only != 'true'
       - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020  # v7.0.0
@@ -187,16 +199,6 @@ jobs:
         if: steps.docs-check.outputs.docs_only != 'true'
       - run: mkdir -p data  # sqlite DB lives at ./data/app.db
         if: steps.docs-check.outputs.docs_only != 'true'
-      # One apt pass for FFmpeg (media integration tests) and bubblewrap
-      # (containment, verified in the next step).
-      - name: Install FFmpeg and bubblewrap
-        if: steps.docs-check.outputs.docs_only != 'true'
-        run: |
-          sudo apt-get update
-          sudo apt-get install -y --no-install-recommends ffmpeg bubblewrap ca-certificates
-          command -v ffmpeg
-          ffmpeg -version | head -n 1
-
       - name: Validate Python and system CA trust
         if: steps.docs-check.outputs.docs_only != 'true'
         run: python scripts/check_ca_trust.py --system --python
diff --git a/docs/tls-trust.md b/docs/tls-trust.md
index 8e0351c68..fd5d9776d 100644
--- a/docs/tls-trust.md
+++ b/docs/tls-trust.md
@@ -16,27 +16,50 @@ The pinned bootstrap protects package integrity even when the old installer's ce
 On Linux/OpenSSL deployments, inspect both the effective CA file and hashed CA directory, plus the two Python bundles:
 
 ```sh
-python scripts/check_ca_trust.py --system --python --overrides
+python scripts/check_ca_trust.py --system --python --overrides --verbose
 ```
 
 Explicit PEM bundles can also be passed as positional arguments. The check rejects the four published root fingerprints, all sixteen published intermediate certificates (including their cross-signs), the cross-signed G3 issuer in the published test chains, and malformed/empty bundles. Checking intermediates matters because adding one as a custom trust anchor can restore an affected chain even after its roots have been removed.
 
 `--overrides` checks every nonempty `LLM_CA_BUNDLE`, `SSL_CERT_FILE`, `REQUESTS_CA_BUNDLE`, `CURL_CA_BUNDLE`, `PIP_CERT`, `NODE_EXTRA_CA_CERTS` and `GRPC_DEFAULT_SSL_ROOTS_FILE_PATH` setting in the checker's process environment, including configured fallback settings. Requests/pip hashed-directory overrides are inspected too; `--system` covers `SSL_CERT_DIR`. Run with the application's environment and filesystem access. The script does not load `.env` or application configuration files; pass any CA paths configured only there explicitly, for example `python scripts/check_ca_trust.py --system --python /path/to/private-ca.pem`. Missing or invalid configured files fail the check. Selecting only `--overrides` with no configured paths also fails instead of reporting that stores were validated.
 
+`--verbose` reports the Python executable/prefix, user home, effective UID/GID where available, and resolved CA paths, including bundles selected from user-installed packages. Compare these with the running application's identity and interpreter. It does not dump environment variables or credentials.
+
 This is an offline inventory check of known certificate fingerprints. It does not modify stores, reject requests at runtime, model native OS revocation, or detect arbitrary reissued certificates sharing the compromised keys. Chromium's policy separately matches public keys. Check mounted or replaced CA files again after deployment, remove affected trust through the owning platform/client configuration, and restart clients that cache SSL contexts. A passing build cannot validate custom files introduced later.
 
 Both Docker build stages refresh system CA certificates and bootstrap pip/certifi before dependency installation. The build fails if known affected CA certificates remain. Node uses the corrected system store through `--use-openssl-ca`. Python gRPC uses that same PEM file through `GRPC_DEFAULT_SSL_ROOTS_FILE_PATH`; updating certifi alone does not replace gRPC's independent wheel bundle. After dependency installation, the image checks gRPC's selected file as well. An explicit gRPC override must be readable and free of known affected CA certificates: gRPC can otherwise fall back to its affected bundled defaults. Upstream gRPC has [merged a bundle update](https://github.com/grpc/grpc/commit/8b32af3bf498c2ba9667410eaa8c836e700e97e6); as checked on 2026-10-21, its [release backport](https://github.com/grpc/grpc/pull/43700) is still open and the latest published grpcio wheel is 1.84.0. Retain the checked override until a released replacement's actual trust behavior has been verified.
 
 Chromium uses a separate trust store. The Docker image installs a managed `CADistrustedCertificates` policy for the eight compromised intermediate public keys, covering their cross-signs without depending on background revocation updates. It adds no trusted certificate and does not disable certificate verification. The policy and public-certificate provenance are documented in [the browser policy note](../docker/chromium-ca-policy.md). Native browser installations and independently managed profiles require their own platform policy or vendor update; this image policy does not configure host browsers.
 
-Rebuild with a fresh base and dependency layers when remediating an existing deployment:
+To replace only Odysseus in an already running Compose stack, build from the corrected checkout with a distinct local image tag. Use the same Compose files and project name as the existing deployment for every command below:
 
 ```sh
+export ODYSSEUS_IMAGE="odysseus-local:ca-$(git rev-parse --short=12 HEAD)"
 docker compose build --pull --no-cache odysseus
-docker compose up -d odysseus
-docker compose exec odysseus python scripts/check_ca_trust.py --system --python --grpc --overrides
+docker compose up -d --no-deps --pull never --no-build odysseus
+docker image inspect --format '{{.Id}}' "$ODYSSEUS_IMAGE"
+docker inspect --format '{{.Image}}' "$(docker compose ps -q odysseus)"
 ```
 
+The two image IDs must match. Keep the selected `ODYSSEUS_IMAGE` in the deployment configuration for subsequent recreations. Compose can prefer the registry image when both `image` and `build` are present; the explicit pull/build flags keep this replacement on the local build. `--no-deps` leaves the existing sidecars running and is intended for an existing stack. For registry deployments, select a verified corrected immutable tag or digest. A merge to `dev` publishes `:dev`; it does not update `:latest`, which is published from `main`.
+
+Check the standard image as its configured app account, using the image's Python interpreter and the same user-bin PATH prefix as the entrypoint:
+
+```sh
+docker compose exec -T --user 0 odysseus sh -ec '
+  gosu_bin=$(command -v gosu)
+  app_user=$(getent passwd "${PUID:-1000}" | cut -d: -f1)
+  test -n "$app_user"
+  exec "$gosu_bin" "$app_user" env PATH="/app/.local/bin:$PATH" \
+    /usr/local/bin/python /app/scripts/check_ca_trust.py \
+    --system --python --grpc --overrides --verbose
+'
+```
+
+`gosu` selects the account's HOME and drops privileges before Python runs, so the check includes its persisted user packages. The entrypoint itself is not rerun. Plain `docker compose exec ... python` uses the image's default root user and can miss `/app/.local` packages. A custom service user, entrypoint, virtual environment or launch command requires matching that deployment's actual user, HOME and Python interpreter instead of copying the standard command unchanged. Docker exec inherits container-creation environment, not variables exported later by the app or entrypoint: reproduce any additional Python/TLS settings with exec's `--env` options, and pass CA paths configured only in application files explicitly. Confirm the verbose identity and selected paths before accepting the result.
+
+For containers started non-root or without the SETUID/SETGID capabilities needed by `gosu`, use `docker compose exec --user UID:GID --env HOME=/actual/app/home` with the deployment's actual numeric IDs, home, PATH and interpreter instead. Do not add capabilities merely to run this check.
+
 SearXNG is a separate HTTPS client and image; updating the Odysseus image does not patch it. Inspect its effective CA path and update or rebuild that image independently. Also inspect persisted `/app/.local` packages, remote Cookbook environments, and externally configured MCP runtimes. Image replacement does not necessarily replace those environments.
 
 For behavioral validation, all twelve [published test chains](https://emudhra.we-have-a-problem.com/chains.zip), including the AAA cross-signs, must fail certificate verification through the effective stores. Confirm that an ordinary known-good HTTPS request still succeeds. In Chromium, confirm the managed policy is loaded at `chrome://policy` and test the incident endpoints through the actual browser path with certificate verification enabled. The PEM checker cannot inspect Chromium's policy or its active verifier. Package versions and a successful image build alone do not prove that a running deployment selects the corrected store.
diff --git a/scripts/check_ca_trust.py b/scripts/check_ca_trust.py
index 7f017fe3d..d34fb53df 100644
--- a/scripts/check_ca_trust.py
+++ b/scripts/check_ca_trust.py
@@ -135,9 +135,16 @@ def main(argv: list[str] | None = None) -> int:
     parser.add_argument("--python", action="store_true", help="check certifi and pip's separate vendored bundle")
     parser.add_argument("--grpc", action="store_true", help="check gRPC's selected default CA file")
     parser.add_argument("--overrides", action="store_true", help="check configured LLM/HTTPX/Requests/pip/Node/gRPC CA overrides")
+    parser.add_argument("--verbose", action="store_true", help="show the runtime identity, Python executable and selected CA paths")
     args = parser.parse_args(argv)
     if not (args.bundles or args.system or args.python or args.grpc or args.overrides):
         parser.error("select --system, --python, --grpc, --overrides, or explicit PEM bundle paths")
+    if args.verbose:
+        print(f"Python executable: {sys.executable}")
+        print(f"Python prefix: {sys.prefix}")
+        print(f"User home: {Path.home()}")
+        if hasattr(os, "geteuid"):
+            print(f"Effective user: uid={os.geteuid()} gid={os.getegid()}")
     try:
         paths = list(args.bundles)
         if args.system:
@@ -154,6 +161,8 @@ def main(argv: list[str] | None = None) -> int:
             raise ValueError("no CA bundle files selected; also select --system, --python, or an explicit path")
         errors = []
         for path in paths:
+            if args.verbose:
+                print(f"CA bundle: {path}")
             try:
                 check_bundle(path)
             except (OSError, ValueError, ssl.SSLError) as exc:
diff --git a/tests/test_ca_trust.py b/tests/test_ca_trust.py
index 24855ea8e..0eb35695f 100644
--- a/tests/test_ca_trust.py
+++ b/tests/test_ca_trust.py
@@ -10,6 +10,7 @@ from pathlib import Path
 import shutil
 import ssl
 import subprocess
+import sys
 import tempfile
 from types import SimpleNamespace
 import unittest
@@ -44,6 +45,43 @@ class CATrustTests(unittest.TestCase):
     def test_unaffected_emsign_root_remains_usable(self):
         checker.check_bundle(self.fixtures / "emsign-g1.pem")
 
+    def test_verbose_python_check_reports_and_rejects_affected_user_bundle(self):
+        # A fresh interpreter must see persisted user packages, independently
+        # of pytest's imported certifi/pip modules and any active test venv.
+        with tempfile.TemporaryDirectory() as tmp:
+            home = Path(tmp)
+            env = dict(os.environ, HOME=str(home), PYTHONUSERBASE=str(home / ".local"))
+            env.pop("PYTHONNOUSERSITE", None)
+            env.pop("PYTHONPATH", None)
+            python = getattr(sys, "_base_executable", sys.executable)
+            site_result = subprocess.run(
+                [python, "-m", "site", "--user-site"], env=env, capture_output=True, text=True,
+            )
+            self.assertEqual(site_result.returncode, 0, site_result.stderr)
+            user_site = Path(site_result.stdout.strip())
+            for package in ("certifi", "pip", "pip/_vendor", "pip/_vendor/certifi"):
+                directory = user_site / package
+                directory.mkdir(parents=True, exist_ok=True)
+                (directory / "__init__.py").write_text(
+                    "from pathlib import Path\ndef where(): return str(Path(__file__).with_name('cacert.pem'))\n"
+                )
+            application_bundle = user_site / "certifi/cacert.pem"
+            pip_bundle = user_site / "pip/_vendor/certifi/cacert.pem"
+            for bundle in (application_bundle, pip_bundle):
+                bundle.write_text(PUBLIC_CERTIFICATES["emsign-g1.pem"])
+            command = [python, str(ROOT / "scripts/check_ca_trust.py"), "--python", "--verbose"]
+            clean = subprocess.run(command, env=env, capture_output=True, text=True)
+            self.assertEqual(clean.returncode, 0, clean.stderr)
+            self.assertIn(str(application_bundle), clean.stdout)
+            self.assertIn(str(pip_bundle), clean.stdout)
+            self.assertIn(str(home), clean.stdout)
+            self.assertIn("Python executable:", clean.stdout)
+            application_bundle.write_text(PUBLIC_CERTIFICATES["emsign-g3.pem"])
+            affected = subprocess.run(command, env=env, capture_output=True, text=True)
+            self.assertEqual(affected.returncode, 1, affected.stderr)
+            self.assertIn(str(application_bundle), affected.stderr)
+            self.assertIn("emSign ECC Root CA - G3", affected.stderr)
+
     def test_compromised_emsign_path_is_rejected(self):
         with self.assertRaisesRegex(ValueError, "emSign ECC Root CA - G3"):
             checker.check_bundle(self.fixtures / "emsign-g3.pem")
diff --git a/tests/test_ci_authoritative_validation.py b/tests/test_ci_authoritative_validation.py
index 6de26817d..cf6994f39 100644
--- a/tests/test_ci_authoritative_validation.py
+++ b/tests/test_ci_authoritative_validation.py
@@ -33,3 +33,16 @@ def test_python_tests_are_authoritative():
 
     assert "python -m pytest -q" in python_tests
     assert "continue-on-error:" not in python_tests
+
+
+def test_ci_checks_system_trust_before_project_installation():
+    python_tests = _indented_block(_WORKFLOW.read_text(), "python-tests", 2)
+    system_check = python_tests.index("python scripts/check_ca_trust.py --system\n")
+    system_update = python_tests.index("sudo apt-get install -y --no-install-recommends ffmpeg bubblewrap ca-certificates")
+    bootstrap = python_tests.index("uv pip install --system --require-hashes")
+    python_check = python_tests.index("python scripts/check_ca_trust.py --python\n")
+    application_install = python_tests.index("uv pip install --system -r requirements.txt")
+
+    assert system_update < system_check < bootstrap < python_check < application_install
+    assert system_check < python_tests.index("npm ci")
+    assert system_check < python_tests.index("npx playwright install")

From 01566b158e627748f70ac402571f2f78241fb6f9 Mon Sep 17 00:00:00 2001
From: RaresKeY <158580472+RaresKeY@users.noreply.github.com>
Date: Thu, 22 Oct 2026 17:08:05 +0100
Subject: [PATCH 42/53] fix(ci): lowercase container image repository names
 (#6802)

---
 .github/workflows/docker-publish.yml    |  7 ++-
 tests/test_docker_publish_image_name.py | 63 +++++++++++++++++++++++++
 2 files changed, 69 insertions(+), 1 deletion(-)
 create mode 100644 tests/test_docker_publish_image_name.py

diff --git a/.github/workflows/docker-publish.yml b/.github/workflows/docker-publish.yml
index 2cb8221ec..6865d5120 100644
--- a/.github/workflows/docker-publish.yml
+++ b/.github/workflows/docker-publish.yml
@@ -29,7 +29,6 @@ permissions:
 
 env:
   REGISTRY: ghcr.io
-  IMAGE_NAME: ${{ github.repository }}
 
 jobs:
   build:
@@ -52,6 +51,9 @@ jobs:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
         with:
           persist-credentials: false
+      - name: Normalize image name
+        shell: bash
+        run: echo "IMAGE_NAME=${GITHUB_REPOSITORY,,}" >> "$GITHUB_ENV"
       - name: Set up Buildx
         uses: docker/setup-buildx-action@37fe631027851001ddb9b187196cc803df7f5f0e  # v4.3.0
       - name: Log in to GHCR
@@ -94,6 +96,9 @@ jobs:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
         with:
           persist-credentials: false
+      - name: Normalize image name
+        shell: bash
+        run: echo "IMAGE_NAME=${GITHUB_REPOSITORY,,}" >> "$GITHUB_ENV"
       - name: Read APP_VERSION + short sha
         id: ver
         run: |
diff --git a/tests/test_docker_publish_image_name.py b/tests/test_docker_publish_image_name.py
new file mode 100644
index 000000000..6b6613c52
--- /dev/null
+++ b/tests/test_docker_publish_image_name.py
@@ -0,0 +1,63 @@
+"""Execute the publication workflow's image-name setup without contacting GHCR."""
+
+import os
+import shutil
+import subprocess
+from pathlib import Path
+
+import pytest
+import yaml
+
+
+WORKFLOW = (
+    Path(__file__).resolve().parents[1]
+    / ".github"
+    / "workflows"
+    / "docker-publish.yml"
+)
+
+
+@pytest.mark.skipif(shutil.which("bash") is None, reason="Docker publication requires Bash")
+@pytest.mark.parametrize("job", ["build", "merge"])
+@pytest.mark.parametrize(
+    ("repository", "expected"),
+    [
+        ("RaresKeY/odysseus-dev", "rareskey/odysseus-dev"),
+        ("ExampleOwner/Example-Repo", "exampleowner/example-repo"),
+        ("odysseus-dev/odysseus", "odysseus-dev/odysseus"),
+    ],
+)
+def test_image_name_is_lowercase_before_docker_steps(tmp_path, job, repository, expected):
+    workflow = yaml.safe_load(WORKFLOW.read_text(encoding="utf-8"))
+    image_name = workflow["env"].get("IMAGE_NAME", "").replace(
+        "${{ github.repository }}", repository
+    )
+    github_env = tmp_path / "github-env"
+    env = {
+        "PATH": os.environ["PATH"],
+        "GITHUB_REPOSITORY": repository,
+        "GITHUB_ENV": str(github_env),
+        "GITHUB_OUTPUT": str(tmp_path / "github-output"),
+        "GITHUB_SHA": "a" * 40,
+    }
+
+    # Run the real setup shell before the job starts using Docker actions.
+    # Checkout, login, builds and registry publication are deliberately excluded.
+    for step in workflow["jobs"][job]["steps"]:
+        if step.get("uses", "").startswith("docker/"):
+            break
+        if "run" not in step:
+            continue
+        subprocess.run(
+            ["bash", "--noprofile", "--norc", "-e", "-o", "pipefail", "-c", step["run"]],
+            cwd=WORKFLOW.parents[2],
+            env=env,
+            check=True,
+            capture_output=True,
+            text=True,
+        )
+        if github_env.exists():
+            env.update(line.split("=", 1) for line in github_env.read_text().splitlines())
+            image_name = env.get("IMAGE_NAME", image_name)
+
+    assert image_name == expected

From b4ae7ebcc43daa6207de0ef614ef336d7707d20f Mon Sep 17 00:00:00 2001
From: Raul Juarez <9117159+rauljua@users.noreply.github.com>
Date: Fri, 23 Oct 2026 12:18:49 -0700
Subject: [PATCH 43/53] feat(agent): expose chat history with existing chat
 scope (#6443)

Co-authored-by: Raul <9117159+raultcj@users.noreply.github.com>
---
 app.py                                        |   4 +-
 integrations/claude/skills/odysseus/SKILL.md  |   8 ++
 .../skills/odysseus/scripts/odysseus_api.py   |   4 +-
 integrations/codex/skills/odysseus/SKILL.md   |   8 ++
 routes/codex_routes.py                        |  35 ++++++
 tests/test_codex_chat_history.py              | 111 ++++++++++++++++++
 6 files changed, 167 insertions(+), 3 deletions(-)
 create mode 100644 tests/test_codex_chat_history.py

diff --git a/app.py b/app.py
index 60441baf1..b0e6f9d55 100644
--- a/app.py
+++ b/app.py
@@ -755,7 +755,8 @@ app.include_router(setup_research_routes(research_handler, session_manager=sessi
 
 # History
 from routes.history.history_routes import setup_history_routes
-app.include_router(setup_history_routes(session_manager, upload_handler=upload_handler))
+history_router = setup_history_routes(session_manager, upload_handler=upload_handler)
+app.include_router(history_router)
 
 # Search
 from routes.search.search_routes import setup_search_routes
@@ -915,6 +916,7 @@ app.include_router(setup_codex_routes(
     memory_router=memory_router,
     calendar_router=calendar_router,
     document_router=document_router,
+    history_router=history_router,
 ))
 app.include_router(setup_claude_routes())
 
diff --git a/integrations/claude/skills/odysseus/SKILL.md b/integrations/claude/skills/odysseus/SKILL.md
index 31b40ee01..c8bd94db3 100644
--- a/integrations/claude/skills/odysseus/SKILL.md
+++ b/integrations/claude/skills/odysseus/SKILL.md
@@ -100,6 +100,14 @@ python3 ~/.claude/skills/odysseus/scripts/odysseus_api.py POST /api/codex/memory
 - `POST /api/codex/documents` — body `{"session_id": "...", "title": "...", "content": "...", "language": "markdown"}`. Requires `documents:write`.
 - `DELETE /api/codex/documents/{doc_id}` — delete a document. Requires `documents:write`.
 
+## Chat history
+
+- `GET /api/codex/chat/{session_id}?offset=0&limit=100` — read a paginated conversation transcript owned by the token owner. Requires the existing `chat` scope.
+
+```bash
+python3 ~/.claude/skills/odysseus/scripts/odysseus_api.py GET /api/codex/chat/SESSION_ID
+```
+
 ## Email draft + send
 
 - Prefer `POST /api/codex/emails/draft-document` for agent-written email replies. It creates an editable Odysseus Document with `language: "email"` and does not touch IMAP/send.
diff --git a/integrations/claude/skills/odysseus/scripts/odysseus_api.py b/integrations/claude/skills/odysseus/scripts/odysseus_api.py
index 8a22eb494..54df59fa1 100755
--- a/integrations/claude/skills/odysseus/scripts/odysseus_api.py
+++ b/integrations/claude/skills/odysseus/scripts/odysseus_api.py
@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
-"""Small Odysseus scoped API helper for Codex terminal sessions."""
+"""Small Odysseus scoped API helper for Claude Code terminal sessions."""
 
 from __future__ import annotations
 
@@ -44,7 +44,7 @@ def _config() -> tuple[str, str] | None:
     if not token:
         missing.append("ODYSSEUS_API_TOKEN")
     if missing:
-        print(f"missing {', '.join(missing)}; create a Codex Agent token in Odysseus Settings", file=sys.stderr)
+        print(f"missing {', '.join(missing)}; create a Claude Agent token in Odysseus Settings", file=sys.stderr)
         return None
     return base_url, token
 
diff --git a/integrations/codex/skills/odysseus/SKILL.md b/integrations/codex/skills/odysseus/SKILL.md
index d4cbdf726..a939cac33 100644
--- a/integrations/codex/skills/odysseus/SKILL.md
+++ b/integrations/codex/skills/odysseus/SKILL.md
@@ -100,6 +100,14 @@ python3 integrations/codex/scripts/odysseus_api.py POST /api/codex/memory '{"tex
 - `POST /api/codex/documents` — body `{"session_id": "...", "title": "...", "content": "...", "language": "markdown"}`. Requires `documents:write`.
 - `DELETE /api/codex/documents/{doc_id}` — delete a document. Requires `documents:write`.
 
+## Chat history
+
+- `GET /api/codex/chat/{session_id}?offset=0&limit=100` — read a paginated conversation transcript owned by the token owner. Requires the existing `chat` scope.
+
+```bash
+python3 integrations/codex/scripts/odysseus_api.py GET /api/codex/chat/SESSION_ID
+```
+
 ## Email draft + send
 
 - Prefer `POST /api/codex/emails/draft-document` for Codex-written email replies. It creates an editable Odysseus Document with `language: "email"` and does not touch IMAP/send.
diff --git a/routes/codex_routes.py b/routes/codex_routes.py
index f42c6b632..542e44d49 100644
--- a/routes/codex_routes.py
+++ b/routes/codex_routes.py
@@ -35,6 +35,7 @@ CALENDAR_READ_SCOPES = {"calendar:read", "calendar:write"}
 CALENDAR_WRITE_SCOPES = {"calendar:write"}
 DOCS_READ_SCOPES = {"documents:read", "documents:write"}
 DOCS_WRITE_SCOPES = {"documents:write"}
+CHAT_READ_SCOPES = {"chat"}
 WRITE_ACTIONS = {"add", "create", "new", "save", "remind", "update", "delete", "toggle_item", "remove", "remove_item"}
 
 
@@ -161,6 +162,7 @@ def setup_codex_routes(
     memory_router: APIRouter | None = None,
     calendar_router: APIRouter | None = None,
     document_router: APIRouter | None = None,
+    history_router: APIRouter | None = None,
 ) -> APIRouter:
     router = APIRouter(prefix="/api/codex", tags=["codex"])
     email_list_endpoint = _find_endpoint(email_router, "GET", "/api/email/list")
@@ -174,6 +176,7 @@ def setup_codex_routes(
     documents_library_endpoint = _find_endpoint(document_router, "GET", "/api/documents/library")
     documents_get_endpoint = _find_endpoint(document_router, "GET", "/api/document/{doc_id}")
     documents_create_endpoint = _find_endpoint(document_router, "POST", "/api/document")
+    chat_history_endpoint = _find_endpoint(history_router, "GET", "/api/history/{session_id}")
 
     @router.get("/capabilities")
     def capabilities(request: Request):
@@ -219,6 +222,11 @@ def setup_codex_routes(
                     "launch": scoped(COOKBOOK_LAUNCH_SCOPES),
                     "actions": ["tasks", "servers", "output", "serve", "stop"],
                 },
+                "chat": {
+                    "read": scoped(CHAT_READ_SCOPES),
+                    "actions": ["read"],
+                    "available": chat_history_endpoint is not None,
+                },
             },
             "safety": {
                 "email_send_requires_confirmation": True,
@@ -226,6 +234,33 @@ def setup_codex_routes(
             },
         }
 
+    @router.get("/chat/{session_id}")
+    async def read_chat(
+        request: Request,
+        session_id: str,
+        offset: int = 0,
+        limit: int = 100,
+    ):
+        _scope_owner(request, CHAT_READ_SCOPES)
+        if chat_history_endpoint is None:
+            raise HTTPException(503, "chat history unavailable")
+        offset, limit = _clamp_pagination(
+            offset,
+            limit,
+            default_limit=100,
+            max_limit=100,
+        )
+        result = await chat_history_endpoint(request, session_id, limit, offset)
+        return {
+            "session_id": session_id,
+            "name": result["name"],
+            "model": result["model"],
+            "messages": result["history"],
+            "total": result["total"],
+            "offset": result["offset"],
+            "limit": result["limit"],
+        }
+
     @router.get("/plugin.zip")
     def plugin_zip(request: Request):
         require_authenticated_request(request)
diff --git a/tests/test_codex_chat_history.py b/tests/test_codex_chat_history.py
new file mode 100644
index 000000000..a169588b2
--- /dev/null
+++ b/tests/test_codex_chat_history.py
@@ -0,0 +1,111 @@
+"""Agent chat history uses the same scope as existing chat and history routes."""
+
+import pytest
+from fastapi import APIRouter, HTTPException
+from starlette.requests import Request
+
+from routes import codex_routes
+
+
+def _endpoint(router, method: str, path: str):
+    for route in router.routes:
+        if route.path == path and method in route.methods:
+            return route.endpoint
+    raise AssertionError(f"{method} {path} route not found")
+
+
+def _request(scopes: list[str]) -> Request:
+    request = Request({
+        "type": "http",
+        "method": "GET",
+        "path": "/api/codex/chat/session-test",
+        "headers": [],
+        "state": {},
+    })
+    request.state.current_user = "api"
+    request.state.api_token = True
+    request.state.api_token_owner = "alice"
+    request.state.api_token_scopes = scopes
+    return request
+
+
+def _history_router(calls: list[tuple]):
+    router = APIRouter()
+
+    @router.get("/api/history/{session_id}")
+    async def history(
+        request: Request,
+        session_id: str,
+        limit: int | None = None,
+        offset: int | None = None,
+    ):
+        calls.append((request, session_id, limit, offset))
+        return {
+            "name": "Model debugging",
+            "model": "org/model",
+            "history": [{"role": "assistant", "content": "second"}],
+            "total": 3,
+            "offset": offset,
+            "limit": limit,
+            "endpoint_url": "http://private-endpoint",
+        }
+
+    return router
+
+
+@pytest.mark.asyncio
+async def test_history_read_uses_existing_paged_handler_without_exposing_endpoint_url():
+    calls = []
+    router = codex_routes.setup_codex_routes(history_router=_history_router(calls))
+    read_chat = _endpoint(router, "GET", "/api/codex/chat/{session_id}")
+    request = _request(["chat"])
+
+    result = await read_chat(request, "session-test", offset=1, limit=1)
+
+    assert calls == [(request, "session-test", 1, 1)]
+    assert result == {
+        "session_id": "session-test",
+        "name": "Model debugging",
+        "model": "org/model",
+        "messages": [{"role": "assistant", "content": "second"}],
+        "total": 3,
+        "offset": 1,
+        "limit": 1,
+    }
+
+
+@pytest.mark.asyncio
+async def test_token_without_chat_scope_cannot_read_history_or_reach_handler():
+    calls = []
+    router = codex_routes.setup_codex_routes(history_router=_history_router(calls))
+    read_chat = _endpoint(router, "GET", "/api/codex/chat/{session_id}")
+
+    with pytest.raises(HTTPException) as exc_info:
+        await read_chat(_request(["todos:read"]), "session-test")
+
+    assert exc_info.value.status_code == 403
+    assert calls == []
+
+
+@pytest.mark.asyncio
+async def test_history_read_uses_existing_page_limit():
+    calls = []
+    router = codex_routes.setup_codex_routes(history_router=_history_router(calls))
+    read_chat = _endpoint(router, "GET", "/api/codex/chat/{session_id}")
+
+    await read_chat(_request(["chat"]), "session-test", limit=1000)
+
+    assert calls[0][2:] == (100, 0)
+
+
+def test_capabilities_report_history_permission_from_chat_scope():
+    router = codex_routes.setup_codex_routes(history_router=_history_router([]))
+    capabilities = _endpoint(router, "GET", "/api/codex/capabilities")
+
+    without_chat = capabilities(_request(["todos:read"]))["tools"]["chat"]
+    reader = capabilities(_request(["chat"]))["tools"]["chat"]
+
+    assert without_chat["read"] is False
+    assert reader["read"] is True
+    assert reader["available"] is True
+    assert reader["actions"] == ["read"]

From 0dbf457c004cd96553d8c96e7ef70d049fd46317 Mon Sep 17 00:00:00 2001
From: Isharak <isharak7m@gmail.com>
Date: Sat, 24 Oct 2026 00:48:54 +0530
Subject: [PATCH 44/53] fix(security): block SSRF via user-supplied model
 endpoint URLs (#6316)

* fix: block SSRF via user-supplied model endpoint URLs

* fix(test): stub DNS in loopback SSRF tests for deterministic results

Replace environment-dependent test_loopback_always_rejected with two
deterministic tests using a stub resolver:
- test_loopback_accepted_by_default (local-first, block_private=False)
- test_loopback_rejected_in_strict_mode (block_private=True)

The old test only passed when localhost resolved to ::1 (hit is_reserved),
not because loopback was actually always rejected.

Co-Authored-By: Santoshkumarpuppala

* fix: guard PATCH base_url against SSRF and add ipv6 loopback coverage

---------

Co-authored-by: isharak7m <192635824+isharak7m@users.noreply.github.com>
---
 routes/model_routes.py            |  34 ++++
 tests/test_model_endpoint_ssrf.py | 296 ++++++++++++++++++++++++++++++
 tests/test_model_routes.py        |   3 +
 3 files changed, 333 insertions(+)
 create mode 100644 tests/test_model_endpoint_ssrf.py

diff --git a/routes/model_routes.py b/routes/model_routes.py
index 3466d4b9b..6aec3b9d9 100644
--- a/routes/model_routes.py
+++ b/routes/model_routes.py
@@ -47,6 +47,7 @@ from src.endpoint_resolver import (
     build_headers,
 )
 from src.auth_helpers import _auth_disabled, effective_user, owner_filter
+from src.url_safety import check_outbound_url
 
 logger = logging.getLogger(__name__)
 
@@ -2163,6 +2164,19 @@ def setup_model_routes(model_discovery):
         # keep those container-local when the frontend marks them as such.
         base_url = _rewrite_loopback_for_docker(base_url, container_local=_truthy(container_local))
 
+        # SSRF hardening: validate the user-supplied URL before any outbound
+        # request. Local-first means loopback/LAN endpoints are allowed by
+        # default; non-HTTP(S) schemes and the cloud metadata range are always
+        # rejected. Set MODELENDPOINT_BLOCK_PRIVATE_IPS=true for full lockdown.
+        # Note: the outbound fetches rely on httpx's default
+        # follow_redirects=False — a redirect target is never dereferenced.
+        ok, reason = check_outbound_url(
+            base_url,
+            block_private=os.getenv("MODELENDPOINT_BLOCK_PRIVATE_IPS", "false").lower() == "true",
+        )
+        if not ok:
+            raise HTTPException(400, f"Rejected endpoint URL: {reason}")
+
         is_featherless = _host_match(base_url, "featherless.ai") or _safe_detect_provider(base_url) == "featherless"
         # Auto-generate name from URL if not provided
         if not name.strip():
@@ -2399,6 +2413,16 @@ def setup_model_routes(model_discovery):
         from src.endpoint_resolver import resolve_url
         base_url = resolve_url(base_url)
         base_url = _rewrite_loopback_for_docker(base_url)
+        # SSRF hardening: validate the user-supplied URL before any outbound
+        # request. Local-first means loopback/LAN endpoints are allowed by
+        # default; non-HTTP(S) schemes and the cloud metadata range are always
+        # rejected. Set MODELENDPOINT_BLOCK_PRIVATE_IPS=true for full lockdown.
+        ok, reason = check_outbound_url(
+            base_url,
+            block_private=os.getenv("MODELENDPOINT_BLOCK_PRIVATE_IPS", "false").lower() == "true",
+        )
+        if not ok:
+            raise HTTPException(400, f"Rejected endpoint URL: {reason}")
         requested_kind = _normalize_endpoint_kind(endpoint_kind)
         is_featherless = _host_match(base_url, "featherless.ai") or _safe_detect_provider(base_url) == "featherless"
         if is_featherless and requested_kind == "auto":
@@ -2889,6 +2913,16 @@ def setup_model_routes(model_discovery):
                             _new_base = _new_base[: -len(_suffix)].rstrip("/")
                     _new_base = _normalize_base(_new_base)
                     if _new_base:
+                        # SSRF hardening: PATCH rewrites the stored base_url, so
+                        # it needs the same guard as POST create/test — no
+                        # bypass through the update path. Follow-up fetches
+                        # rely on httpx's default follow_redirects=False.
+                        ok, reason = check_outbound_url(
+                            _new_base,
+                            block_private=os.getenv("MODELENDPOINT_BLOCK_PRIVATE_IPS", "false").lower() == "true",
+                        )
+                        if not ok:
+                            raise HTTPException(400, f"Rejected endpoint URL: {reason}")
                         ep.base_url = _new_base
             else:
                 ep.is_enabled = not ep.is_enabled
diff --git a/tests/test_model_endpoint_ssrf.py b/tests/test_model_endpoint_ssrf.py
new file mode 100644
index 000000000..fff3c4b96
--- /dev/null
+++ b/tests/test_model_endpoint_ssrf.py
@@ -0,0 +1,296 @@
+"""Regression tests for SSRF hardening on model endpoint routes.
+
+Verifies that POST /model-endpoints/test, POST /model-endpoints, and
+PATCH /model-endpoints/{ep_id} reject user-supplied URLs that resolve to
+link-local (cloud metadata), non-HTTP schemes, or (when
+MODELENDPOINT_BLOCK_PRIVATE_IPS=true) private/loopback addresses — matching
+the existing SSRF guard pattern in embedding_routes.py.
+
+A stub resolver is injected so the loopback tests never touch real DNS.
+"""
+import os
+import sys
+from types import SimpleNamespace
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+
+# ── Resolver stub (same pattern as tests/test_url_safety.py) ────────────────
+def _resolver(mapping):
+    """Create a stub resolver for deterministic DNS in tests."""
+    def resolve(host):
+        if host in mapping:
+            return mapping[host]
+        raise OSError(f"unresolvable: {host}")
+    return resolve
+
+
+LOCALHOST_V4 = _resolver({"localhost": ["127.0.0.1"]})
+LOCALHOST_V6 = _resolver({"localhost": ["::1"]})
+
+
+@pytest.fixture
+def client(monkeypatch):
+    """Build a TestClient with auth disabled and minimal DB stubs."""
+    monkeypatch.setenv("AUTH_ENABLED", "false")
+    monkeypatch.setenv("DATABASE_URL", "sqlite:///:memory:")
+
+    # Stub heavy deps that model_routes imports at module level.
+    # Use monkeypatch so entries are removed after the test.
+    for mod in [
+        "src.tls_overrides",
+        "src.llm_core",
+        "src.settings",
+        "src.constants",
+        "core.log_safety",
+    ]:
+        if mod not in sys.modules:
+            monkeypatch.setitem(sys.modules, mod, MagicMock())
+
+    # Provide real endpoint_resolver so the route logic works
+    if "src.endpoint_resolver" not in sys.modules or isinstance(
+        sys.modules["src.endpoint_resolver"], MagicMock
+    ):
+        er = MagicMock()
+        er.normalize_base = lambda url: url
+        er.resolve_url = lambda url: url
+        er.build_chat_url = lambda base, **kw: base
+        er.build_models_url = lambda base, **kw: base + "/v1/models"
+        er.build_headers = lambda base, **kw: {}
+        monkeypatch.setitem(sys.modules, "src.endpoint_resolver", er)
+
+    # Clear cached model_routes module so it picks up our stubs
+    monkeypatch.delitem(sys.modules, "routes.model_routes", raising=False)
+
+    from fastapi.testclient import TestClient
+    import routes.model_routes as mr
+    from fastapi import FastAPI
+
+    app = FastAPI()
+    router = mr.setup_model_routes(model_discovery=None)
+    app.include_router(router)
+    app.state.auth_enabled = False
+    return TestClient(app, raise_server_exceptions=False)
+
+
+class TestModelEndpointSSRF:
+    """SSRF protection for POST /model-endpoints/test."""
+
+    def test_cloud_metadata_blocked(self, client):
+        """Cloud metadata IP (169.254.169.254) must be rejected."""
+        resp = client.post(
+            "/api/model-endpoints/test",
+            data={"base_url": "http://169.254.169.254/latest/meta-data/"},
+        )
+        assert resp.status_code == 400
+        assert "Rejected" in resp.json()["detail"]
+
+    def test_non_http_scheme_blocked(self, client):
+        """Non-HTTP schemes (file://, ftp://) must be rejected."""
+        resp = client.post(
+            "/api/model-endpoints/test",
+            data={"base_url": "file:///etc/passwd"},
+        )
+        assert resp.status_code == 400
+        assert "Rejected" in resp.json()["detail"]
+
+    def test_loopback_accepted_by_default(self, client):
+        """Local-first: loopback is accepted when block_private=False."""
+        with patch("src.url_safety._default_resolver", LOCALHOST_V4):
+            resp = client.post(
+                "/api/model-endpoints/test",
+                data={"base_url": "http://localhost:11434/v1"},
+            )
+            # Guard passes; probe fails (no server) but that is not SSRF.
+            assert "Rejected endpoint URL" not in str(resp.json())
+
+    def test_loopback_rejected_in_strict_mode(self, client):
+        """Strict mode: loopback is rejected when block_private=True."""
+        os.environ["MODELENDPOINT_BLOCK_PRIVATE_IPS"] = "true"
+        try:
+            with patch("src.url_safety._default_resolver", LOCALHOST_V4):
+                resp = client.post(
+                    "/api/model-endpoints/test",
+                    data={"base_url": "http://localhost:11434/v1"},
+                )
+                assert resp.status_code == 400
+                assert "Rejected" in resp.json()["detail"]
+        finally:
+            os.environ.pop("MODELENDPOINT_BLOCK_PRIVATE_IPS", None)
+
+    def test_strict_mode_blocks_direct_loopback_ip(self, client):
+        """Strict mode rejects 127.0.0.1 passed directly (no DNS needed)."""
+        os.environ["MODELENDPOINT_BLOCK_PRIVATE_IPS"] = "true"
+        try:
+            resp = client.post(
+                "/api/model-endpoints/test",
+                data={"base_url": "http://127.0.0.1:11434/v1"},
+            )
+            assert resp.status_code == 400
+            assert "Rejected" in resp.json()["detail"]
+        finally:
+            os.environ.pop("MODELENDPOINT_BLOCK_PRIVATE_IPS", None)
+
+    def test_ipv6_loopback_literal_accepted_by_default(self, client):
+        """::1 is loopback, not a disallowed 'reserved' address (dfd1f7e7)."""
+        resp = client.post(
+            "/api/model-endpoints/test",
+            data={"base_url": "http://[::1]:11434/v1"},
+        )
+        assert "Rejected endpoint URL" not in str(resp.json())
+
+    def test_ipv6_loopback_localhost_accepted_by_default(self, client):
+        """Dual-stack hosts whose resolver answers ::1 first must work."""
+        with patch("src.url_safety._default_resolver", LOCALHOST_V6):
+            resp = client.post(
+                "/api/model-endpoints/test",
+                data={"base_url": "http://localhost:11434/v1"},
+            )
+            assert "Rejected endpoint URL" not in str(resp.json())
+
+    def test_ipv6_loopback_rejected_in_strict_mode(self, client):
+        """Strict mode still rejects ::1."""
+        os.environ["MODELENDPOINT_BLOCK_PRIVATE_IPS"] = "true"
+        try:
+            resp = client.post(
+                "/api/model-endpoints/test",
+                data={"base_url": "http://[::1]:11434/v1"},
+            )
+            assert resp.status_code == 400
+            assert "Rejected" in resp.json()["detail"]
+        finally:
+            os.environ.pop("MODELENDPOINT_BLOCK_PRIVATE_IPS", None)
+
+
+class TestModelEndpointCreateSSRF:
+    """SSRF protection for POST /model-endpoints."""
+
+    def test_cloud_metadata_blocked(self, client):
+        """Cloud metadata IP must be rejected on endpoint creation."""
+        resp = client.post(
+            "/api/model-endpoints",
+            data={"base_url": "http://169.254.169.254/latest/meta-data/"},
+        )
+        assert resp.status_code == 400
+        assert "Rejected" in resp.json()["detail"]
+
+    def test_non_http_scheme_blocked(self, client):
+        """Non-HTTP schemes must be rejected on endpoint creation."""
+        resp = client.post(
+            "/api/model-endpoints",
+            data={"base_url": "gopher://evil:6379/secret"},
+        )
+        assert resp.status_code == 400
+        assert "Rejected" in resp.json()["detail"]
+
+    def test_loopback_accepted_by_default(self, client):
+        """Local-first: loopback is accepted when block_private=False."""
+        with patch("src.url_safety._default_resolver", LOCALHOST_V4):
+            resp = client.post(
+                "/api/model-endpoints",
+                data={"base_url": "http://localhost:11434/v1"},
+            )
+            # Guard passes; route may 500 on DB/probe but never 400 SSRF.
+            assert resp.status_code != 400
+            body = resp.text if resp.status_code == 500 else str(resp.json())
+            assert "Rejected endpoint URL" not in body
+
+    def test_loopback_rejected_in_strict_mode(self, client):
+        """Strict mode: loopback is rejected when block_private=True."""
+        os.environ["MODELENDPOINT_BLOCK_PRIVATE_IPS"] = "true"
+        try:
+            with patch("src.url_safety._default_resolver", LOCALHOST_V4):
+                resp = client.post(
+                    "/api/model-endpoints",
+                    data={"base_url": "http://localhost:11434/v1"},
+                )
+                assert resp.status_code == 400
+                assert "Rejected" in resp.json()["detail"]
+        finally:
+            os.environ.pop("MODELENDPOINT_BLOCK_PRIVATE_IPS", None)
+
+
+class TestModelEndpointPatchSSRF:
+    """SSRF protection for PATCH /api/model-endpoints/{ep_id} (base_url).
+
+    The update path rewrites the stored base_url, which later fetches probe,
+    list models and serve chat through — it must pass the same guard as the
+    POST routes instead of bypassing it.
+    """
+
+    def _install_fake_endpoint(self, monkeypatch, base_url="http://localhost:9999/v1"):
+        import routes.model_routes as mr
+
+        ep = SimpleNamespace(
+            id="ep1",
+            name="EP",
+            base_url=base_url,
+            api_key=None,
+            is_enabled=True,
+            owner=None,
+            hidden_models=None,
+            cached_models=None,
+            pinned_models=None,
+            model_type="llm",
+            supports_tools=None,
+            endpoint_kind="auto",
+            model_refresh_mode="auto",
+            model_refresh_interval=None,
+            model_refresh_timeout=None,
+            created_at=None,
+            updated_at=None,
+        )
+
+        class _FakeDb:
+            def query(self, _model):
+                return self
+
+            def filter(self, *_args, **_kwargs):
+                return self
+
+            def first(self):
+                return ep
+
+            def commit(self):
+                pass
+
+            def close(self):
+                pass
+
+        monkeypatch.setattr(mr, "SessionLocal", lambda: _FakeDb())
+        monkeypatch.setattr(mr, "require_admin", lambda request: None)
+        monkeypatch.setattr(mr, "_chatgpt_endpoint_visible", lambda ep_, request: True)
+        return ep
+
+    def test_patch_cloud_metadata_blocked(self, client, monkeypatch):
+        """PATCH must reject the cloud metadata URL, not store it."""
+        ep = self._install_fake_endpoint(monkeypatch)
+        resp = client.patch(
+            "/api/model-endpoints/ep1",
+            json={"base_url": "http://169.254.169.254/latest/meta-data"},
+        )
+        assert resp.status_code == 400
+        assert "Rejected endpoint URL" in resp.json()["detail"]
+        assert ep.base_url == "http://localhost:9999/v1"
+
+    def test_patch_non_http_scheme_blocked(self, client, monkeypatch):
+        """PATCH must reject non-HTTP schemes."""
+        ep = self._install_fake_endpoint(monkeypatch)
+        resp = client.patch(
+            "/api/model-endpoints/ep1",
+            json={"base_url": "file:///etc/passwd"},
+        )
+        assert resp.status_code == 400
+        assert "Rejected endpoint URL" in resp.json()["detail"]
+        assert ep.base_url == "http://localhost:9999/v1"
+
+    def test_patch_valid_url_accepted(self, client, monkeypatch):
+        """Control: a legitimate local endpoint URL still updates fine."""
+        ep = self._install_fake_endpoint(monkeypatch)
+        resp = client.patch(
+            "/api/model-endpoints/ep1",
+            json={"base_url": "http://127.0.0.1:11434/v1"},
+        )
+        assert resp.status_code == 200
+        assert ep.base_url == "http://127.0.0.1:11434/v1"
diff --git a/tests/test_model_routes.py b/tests/test_model_routes.py
index 6d1a8dbdb..307dbb5fa 100644
--- a/tests/test_model_routes.py
+++ b/tests/test_model_routes.py
@@ -1281,6 +1281,7 @@ def _patch_create_deps(monkeypatch, db, settings=None):
     monkeypatch.setattr(model_routes, "_save_settings", lambda s: settings.update(s))
     monkeypatch.setattr(endpoint_resolver, "resolve_url", lambda u: u)
     monkeypatch.setattr(auth_helpers, "get_current_user", lambda req: None)
+    monkeypatch.setattr(model_routes, "check_outbound_url", lambda *a, **k: (True, "ok"))
     return settings
 
 
@@ -2000,6 +2001,7 @@ def test_explicit_proxy_test_fetches_models_with_long_timeout(monkeypatch):
 
     monkeypatch.setattr(model_routes, "require_admin", lambda request: None)
     monkeypatch.setattr(model_routes, "_ping_endpoint", lambda *a, **k: (_ for _ in ()).throw(AssertionError("ping should not run when model listing succeeds")))
+    monkeypatch.setattr(model_routes, "check_outbound_url", lambda *a, **k: (True, "ok"))
 
     calls = []
     returned = ["NVIDIA NIM/openai/gpt-oss-120b", "mistral/mistral-small-2603"]
@@ -2038,6 +2040,7 @@ def test_explicit_proxy_add_fetches_and_caches_models_with_long_timeout(monkeypa
     monkeypatch.setattr(model_routes, "_save_settings", lambda settings: None)
     monkeypatch.setattr("src.auth_helpers.get_current_user", lambda request: None)
     monkeypatch.setattr(model_routes, "_ping_endpoint", lambda *a, **k: (_ for _ in ()).throw(AssertionError("ping should not run when model listing succeeds")))
+    monkeypatch.setattr(model_routes, "check_outbound_url", lambda *a, **k: (True, "ok"))
 
     calls = []
     returned = ["NVIDIA NIM/openai/gpt-oss-120b", "mistral/mistral-small-2603"]

From 98a16242c675b13da13248fb06a0d123f67344f5 Mon Sep 17 00:00:00 2001
From: Isharak <isharak7m@gmail.com>
Date: Sat, 24 Oct 2026 00:48:59 +0530
Subject: [PATCH 45/53] fix(security): add SSRF validation to manage_endpoints
 agent tool (#6327)

The manage_endpoints agent tool accepts arbitrary user-supplied base_urls
and writes them to the database without calling check_outbound_url(),
while the HTTP route (POST /api/model-endpoints) enforces full SSRF
hardening. A prompt-injection payload smuggled into a skill, note, fetched
page, or email could instruct the model to register a cloud-metadata or
internal-network endpoint via this tool path.

Add the same check_outbound_url() guard used by the HTTP route to the
agent tool's 'add' action. Also sanitize the error message in the except
block to avoid leaking raw exception text.

Add 8 regression tests covering: cloud metadata, non-HTTP schemes,
loopback (local-first), strict mode, safe URLs, empty URLs, gopher
scheme, and error message sanitization.

Co-authored-by: isharak7m <192635824+isharak7m@users.noreply.github.com>
---
 src/agent_tools/admin_tools.py      |  16 +-
 tests/test_manage_endpoints_ssrf.py | 257 ++++++++++++++++++++++++++++
 2 files changed, 272 insertions(+), 1 deletion(-)
 create mode 100644 tests/test_manage_endpoints_ssrf.py

diff --git a/src/agent_tools/admin_tools.py b/src/agent_tools/admin_tools.py
index 6b1349cff..f0a7662c2 100644
--- a/src/agent_tools/admin_tools.py
+++ b/src/agent_tools/admin_tools.py
@@ -38,11 +38,25 @@ async def do_manage_endpoints(content: str, owner: Optional[str] = None) -> Dict
 
         elif action == "add":
             import uuid as _uuid
+            from src.url_safety import check_outbound_url
             name = args.get("name", "")
             base_url = args.get("base_url", "")
             api_key = args.get("api_key", "")
             if not base_url:
                 return {"error": "base_url is required", "exit_code": 1}
+            # SSRF hardening: validate the URL before storing it. Every entry
+            # point that accepts an external base_url must run this guard.
+            # The HTTP route (POST /api/model-endpoints) gets the same guard
+            # in #6316; this tool bypasses that route entirely, so it needs
+            # its own validation. A prompt-injection payload smuggled into a
+            # skill, note, fetched page, or email could instruct the model to
+            # register a cloud-metadata or internal-network endpoint.
+            ok, reason = check_outbound_url(
+                base_url,
+                block_private=os.getenv("MODELENDPOINT_BLOCK_PRIVATE_IPS", "false").lower() == "true",
+            )
+            if not ok:
+                return {"error": f"Rejected endpoint URL: {reason}", "exit_code": 1}
             eid = str(_uuid.uuid4())[:8]
             from datetime import datetime
             ep = ModelEndpoint(id=eid, name=name or base_url, base_url=base_url,
@@ -75,7 +89,7 @@ async def do_manage_endpoints(content: str, owner: Optional[str] = None) -> Dict
             return {"error": f"Unknown action: {action}", "exit_code": 1}
     except Exception as e:
         logger.error(f"manage_endpoints error: {e}")
-        return {"error": str(e), "exit_code": 1}
+        return {"error": "An internal error occurred while managing endpoints", "exit_code": 1}
     finally:
         db.close()
 
diff --git a/tests/test_manage_endpoints_ssrf.py b/tests/test_manage_endpoints_ssrf.py
new file mode 100644
index 000000000..eac65881a
--- /dev/null
+++ b/tests/test_manage_endpoints_ssrf.py
@@ -0,0 +1,257 @@
+"""Regression tests for SSRF hardening on the manage_endpoints agent tool.
+
+Verifies that the do_manage_endpoints tool function rejects user-supplied URLs
+that resolve to link-local (cloud metadata), non-HTTP schemes, or (when
+MODELENDPOINT_BLOCK_PRIVATE_IPS=true) private/loopback addresses -- applying
+the shared outbound-URL policy in check_outbound_url(). The HTTP route
+(POST /api/model-endpoints) receives the same guard in #6316.
+
+The agent tool path bypasses the HTTP route entirely, so it needs its own
+validation. A prompt-injection payload smuggled into a skill, note, fetched
+page, or email could instruct the model to register a cloud-metadata or
+internal-network endpoint via this tool.
+"""
+import ipaddress
+import json
+import os
+import sys
+import types
+
+import pytest
+
+import src.url_safety as _url_safety
+
+_real_check_outbound_url = _url_safety.check_outbound_url
+
+
+def _fake_resolver(host):
+    """Resolver that returns deterministic IPs without real DNS."""
+    _HOST_MAP = {
+        "169.254.169.254": ["169.254.169.254"],
+        "metadata.google.internal": ["169.254.169.254"],
+        "localhost": ["127.0.0.1"],
+        "127.0.0.1": ["127.0.0.1"],
+        "0.0.0.0": ["0.0.0.0"],
+        "example.com": ["93.184.216.34"],
+        "192.168.1.1": ["192.168.1.1"],
+        "10.0.0.1": ["10.0.0.1"],
+        "api.openai.com": ["104.18.6.192"],
+    }
+    if host in _HOST_MAP:
+        return _HOST_MAP[host]
+    try:
+        ipaddress.ip_address(host)
+        return [host]
+    except ValueError:
+        pass
+    raise OSError(f"Name or service not known: {host}")
+
+
+def _check_with_fake_resolver(url, *, block_private=False, resolver=None):
+    """Call the real check_outbound_url with our fake resolver."""
+    return _real_check_outbound_url(url, block_private=block_private, resolver=_fake_resolver)
+
+
+def _make_content(base_url, *, name="", api_key=""):
+    """Build a JSON content string for the manage_endpoints 'add' action."""
+    return json.dumps({
+        "action": "add",
+        "name": name,
+        "base_url": base_url,
+        "api_key": api_key,
+    })
+
+
+class _FakeQuery:
+    def __init__(self, model):
+        self._model = model
+
+    def filter(self, *args):
+        return self
+
+    def first(self):
+        return None
+
+    def all(self):
+        return []
+
+
+class _FakeDB:
+    def __init__(self):
+        self.added = []
+        self.committed = False
+
+    def query(self, model):
+        return _FakeQuery(model)
+
+    def add(self, obj):
+        self.added.append(obj)
+
+    def commit(self):
+        self.committed = True
+
+    def close(self):
+        pass
+
+
+class _FakeModelEndpoint:
+    def __init__(self, **kwargs):
+        for k, v in kwargs.items():
+            setattr(self, k, v)
+
+
+def _setup_mocks(monkeypatch, db):
+    """Set up faked core.database and patched check_outbound_url."""
+    fake_core_db = types.ModuleType("core.database")
+    fake_core_db.SessionLocal = lambda: db
+    fake_core_db.ModelEndpoint = _FakeModelEndpoint
+    monkeypatch.setitem(sys.modules, "core.database", fake_core_db)
+
+    monkeypatch.setattr(_url_safety, "check_outbound_url", _check_with_fake_resolver)
+
+    if "src.agent_tools.admin_tools" in sys.modules:
+        monkeypatch.delitem(sys.modules, "src.agent_tools.admin_tools", raising=False)
+
+
+def _get_do_manage_endpoints():
+    """Import and return do_manage_endpoints from the reloaded admin_tools."""
+    from src.agent_tools.admin_tools import do_manage_endpoints
+    return do_manage_endpoints
+
+
+@pytest.mark.asyncio
+async def test_cloud_metadata_blocked(monkeypatch):
+    """Cloud metadata IP (169.254.169.254) must be rejected."""
+    db = _FakeDB()
+    _setup_mocks(monkeypatch, db)
+    do_manage_endpoints = _get_do_manage_endpoints()
+    content = _make_content("http://169.254.169.254/latest/meta-data/")
+    result = await do_manage_endpoints(content, owner="admin")
+
+    assert result["exit_code"] == 1
+    assert "Rejected" in result["error"]
+    assert len(db.added) == 0
+
+
+@pytest.mark.asyncio
+async def test_non_http_scheme_blocked(monkeypatch):
+    """Non-HTTP schemes (file://, gopher://) must be rejected."""
+    db = _FakeDB()
+    _setup_mocks(monkeypatch, db)
+    do_manage_endpoints = _get_do_manage_endpoints()
+    content = _make_content("file:///etc/passwd")
+    result = await do_manage_endpoints(content, owner="admin")
+
+    assert result["exit_code"] == 1
+    assert "Rejected" in result["error"]
+    assert len(db.added) == 0
+
+
+@pytest.mark.asyncio
+async def test_loopback_accepted_by_default(monkeypatch):
+    """Loopback addresses are accepted by default (local-first design).
+
+    The agent tool uses check_outbound_url directly, which allows
+    loopback by default -- this is correct for local model endpoints
+    (Ollama, llama.cpp, etc.). Loopback is only blocked in strict mode.
+    """
+    db = _FakeDB()
+    _setup_mocks(monkeypatch, db)
+    do_manage_endpoints = _get_do_manage_endpoints()
+    content = _make_content("http://localhost:11434/v1")
+    result = await do_manage_endpoints(content, owner="admin")
+
+    assert result["exit_code"] == 0
+    assert "Added endpoint" in result["response"]
+    assert len(db.added) == 1
+
+
+@pytest.mark.asyncio
+async def test_strict_mode_blocks_private(monkeypatch):
+    """MODELENDPOINT_BLOCK_PRIVATE_IPS=true blocks private IPs."""
+    db = _FakeDB()
+    _setup_mocks(monkeypatch, db)
+    monkeypatch.setenv("MODELENDPOINT_BLOCK_PRIVATE_IPS", "true")
+    do_manage_endpoints = _get_do_manage_endpoints()
+    content = _make_content("http://192.168.1.1:8080/v1")
+    result = await do_manage_endpoints(content, owner="admin")
+
+    assert result["exit_code"] == 1
+    assert "Rejected" in result["error"]
+    assert len(db.added) == 0
+
+
+@pytest.mark.asyncio
+async def test_safe_url_accepted(monkeypatch):
+    """A safe public URL should be accepted and stored."""
+    db = _FakeDB()
+    _setup_mocks(monkeypatch, db)
+    do_manage_endpoints = _get_do_manage_endpoints()
+    content = _make_content("https://api.openai.com/v1", name="OpenAI")
+    result = await do_manage_endpoints(content, owner="admin")
+
+    assert result["exit_code"] == 0
+    assert "Added endpoint" in result["response"]
+    assert len(db.added) == 1
+    assert db.committed is True
+
+
+@pytest.mark.asyncio
+async def test_empty_url_rejected(monkeypatch):
+    """An empty base_url must be rejected before SSRF check."""
+    db = _FakeDB()
+    _setup_mocks(monkeypatch, db)
+    do_manage_endpoints = _get_do_manage_endpoints()
+    content = _make_content("")
+    result = await do_manage_endpoints(content, owner="admin")
+
+    assert result["exit_code"] == 1
+    assert "base_url is required" in result["error"]
+    assert len(db.added) == 0
+
+
+@pytest.mark.asyncio
+async def test_gopher_scheme_blocked(monkeypatch):
+    """gopher:// scheme must be rejected."""
+    db = _FakeDB()
+    _setup_mocks(monkeypatch, db)
+    do_manage_endpoints = _get_do_manage_endpoints()
+    content = _make_content("gopher://evil:6379/secret")
+    result = await do_manage_endpoints(content, owner="admin")
+
+    assert result["exit_code"] == 1
+    assert "Rejected" in result["error"]
+    assert len(db.added) == 0
+
+
+@pytest.mark.asyncio
+async def test_error_not_leaked(monkeypatch):
+    """Error messages must not leak raw exception text."""
+    db = _FakeDB()
+    _setup_mocks(monkeypatch, db)
+    do_manage_endpoints = _get_do_manage_endpoints()
+    content = _make_content("http://169.254.169.254/latest/meta-data/")
+    result = await do_manage_endpoints(content, owner="admin")
+
+    assert result["exit_code"] == 1
+    assert "Rejected" in result["error"]
+    assert "Traceback" not in result["error"]
+
+
+@pytest.mark.asyncio
+async def test_ipv6_loopback_accepted_by_default(monkeypatch):
+    """::1 must be treated as loopback (accepted local-first), not reserved.
+
+    Proves this branch carries the dfd1f7e7 url_safety fix after rebasing
+    onto current dev: the pre-fix guard checked is_reserved before is_loopback
+    and rejected ::1 even in default local-first mode.
+    """
+    db = _FakeDB()
+    _setup_mocks(monkeypatch, db)
+    do_manage_endpoints = _get_do_manage_endpoints()
+    content = _make_content("http://[::1]:11434/v1")
+    result = await do_manage_endpoints(content, owner="admin")
+
+    assert result["exit_code"] == 0
+    assert "Added endpoint" in result["response"]
+    assert len(db.added) == 1

From f8e043e8ca7cb051785b36dc1e7a669d386fd7fa Mon Sep 17 00:00:00 2001
From: Grzegorz <gpudlowskidxr@gmail.com>
Date: Fri, 23 Oct 2026 21:19:04 +0200
Subject: [PATCH 46/53] fix(approvals): seal approved bash/python and file
 writes in the agent workspace when no workspace is set (#6705)

#6683 made an exact approval seal a launch boundary (and a filesystem root)
in the request's workspace, but only when a workspace is bound. Agent mode
with no folder picked is the default, and there the approval still sealed
nothing, so "Allow" always ended in "Approved action has no sealed
process/job identity" (bash/python) or "Approved filesystem action has no
sealed resource identity" (write_file). In Docker every agent turn carries
the backend runtime context, so bash and write_file always ask for approval
and never ran.

With no workspace, seal the root in the agent workspace, which is where
agent_cwd() already runs bash/python in that case. Inherited (child)
authorities still cannot widen.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
---
 src/tool_approvals.py                         | 14 ++--
 src/tool_execution.py                         |  6 ++
 .../test_exact_approval_ungranted_process.py  | 66 +++++++++++++++++++
 3 files changed, 82 insertions(+), 4 deletions(-)

diff --git a/src/tool_approvals.py b/src/tool_approvals.py
index d68adb82a..5f25cdb26 100644
--- a/src/tool_approvals.py
+++ b/src/tool_approvals.py
@@ -425,9 +425,13 @@ class ToolApprovalStore:
                     # approval exists to admit an ungranted one. Seal its launch
                     # boundary now, in the request's workspace, the same way an
                     # ungranted filesystem action gets its root below (#6635).
+                    # With no workspace bound, bash/python run in the agent
+                    # workspace (agent_cwd), so the launch is sealed there.
                     roots = request_authority.resource_roots
-                    if not roots and workspace:
-                        roots = (FilesystemRoot.seal(workspace, owner=_normalized_owner(owner)),)
+                    if not roots:
+                        from src.tool_execution import default_agent_workspace
+                        roots = (FilesystemRoot.seal(workspace or default_agent_workspace(),
+                                                     owner=_normalized_owner(owner)),)
                     if len(roots) == 1:
                         from dataclasses import replace
                         process_authority = replace(
@@ -455,8 +459,10 @@ class ToolApprovalStore:
         if tool_name in NATIVE_FILESYSTEM_TOOLS and backend_operation is not None and isinstance(backend_operation.resource, NativeBackendResource):
             try:
                 roots = request_authority.resource_roots if request_authority is not None else ()
-                if not roots and workspace and (request_authority is None or not request_authority.inherited):
-                    roots = (FilesystemRoot.seal(workspace, owner=_normalized_owner(owner)),)
+                if not roots and (request_authority is None or not request_authority.inherited):
+                    from src.tool_execution import default_agent_workspace
+                    roots = (FilesystemRoot.seal(workspace or default_agent_workspace(),
+                                                 owner=_normalized_owner(owner)),)
                 resource_operation = resolve_filesystem_operation(
                     ExactOperation.normalize(tool_name, content), roots=roots, workspace=workspace or "",
                     request_id=request_authority.request_id if request_authority is not None else "")
diff --git a/src/tool_execution.py b/src/tool_execution.py
index 599eade99..bde68df30 100644
--- a/src/tool_execution.py
+++ b/src/tool_execution.py
@@ -1221,6 +1221,12 @@ def agent_cwd() -> str:
         if vetted is None:
             raise RuntimeError("active workspace is not a safe real directory")
         return vetted
+    return default_agent_workspace()
+
+
+def default_agent_workspace() -> str:
+    """The agent workspace under the data dir, where subprocesses run when no
+    workspace is bound."""
     resolved = os.path.realpath(_AGENT_WORKDIR)
     if resolved not in _agent_readable_data_subdirs() or vet_workspace(resolved) != resolved:
         raise RuntimeError("agent workspace is not a safe real directory")
diff --git a/tests/test_exact_approval_ungranted_process.py b/tests/test_exact_approval_ungranted_process.py
index fffb5c011..15064178f 100644
--- a/tests/test_exact_approval_ungranted_process.py
+++ b/tests/test_exact_approval_ungranted_process.py
@@ -79,3 +79,69 @@ async def test_inherited_authority_still_cannot_widen_to_ungranted_bash(tmp_path
     assert pending.process_operation is None
     _, result = await _dispatch(child, "bash", "printf approved-run", exact)
     assert result.get("blocked") is True
+
+
+@pytest.fixture
+def agent_workspace():
+    import os
+    from src.constants import AGENT_WORKSPACE_DIR
+    os.makedirs(AGENT_WORKSPACE_DIR, exist_ok=True)
+    return os.path.realpath(AGENT_WORKSPACE_DIR)
+
+
+def test_approval_without_a_workspace_seals_a_launch_in_the_agent_workspace(agent_workspace):
+    # Agent mode with no folder picked is the default. bash already runs in the
+    # agent workspace there (agent_cwd), so that is where its approval seals.
+    authority = _authority("", "get_workspace")
+    assert authority.resource_roots == ()
+
+    pending, _ = _approve(authority, "bash", "pwd")
+
+    bound = pending.process_operation
+    assert bound is not None
+    assert bound.launch is not None
+    assert bound.launch.scope.root.path == agent_workspace
+
+
+async def test_approved_bash_without_a_workspace_runs_in_the_agent_workspace(agent_workspace):
+    authority = _authority("", "get_workspace")
+    _, exact = _approve(authority, "bash", "pwd")
+
+    description, result = await _dispatch(authority, "bash", "pwd", exact)
+
+    assert result.get("failure_kind") != "resource_identity_denied", result
+    assert result.get("exit_code") == 0, result
+    containment = result.get("containment") or {}
+    assert containment.get("workspace", agent_workspace) == agent_workspace, containment
+
+
+async def test_inherited_authority_without_a_workspace_still_cannot_widen(agent_workspace):
+    from dataclasses import replace
+    child = replace(_authority("", "get_workspace"), inherited=True)
+    pending, exact = _approve(child, "bash", "pwd")
+
+    assert pending.process_operation is None
+    _, result = await _dispatch(child, "bash", "pwd", exact)
+    assert result.get("blocked") is True
+
+
+async def test_approved_write_without_a_workspace_lands_in_the_agent_workspace(agent_workspace):
+    # write_file had the same gap: with no workspace the approval sealed no
+    # root, so "approve" ended in "no sealed resource identity".
+    import os
+    target = "approved-write-6635.txt"
+    content = f"{target}\nhello"
+    authority = _authority("", "get_workspace")
+    pending, exact = _approve(authority, "write_file", content)
+    assert pending.resource_operation is not None
+
+    _, result = await _dispatch(authority, "write_file", content, exact)
+
+    assert result.get("failure_kind") != "resource_identity_denied", result
+    written = os.path.join(agent_workspace, target)
+    try:
+        with open(written) as fh:
+            assert fh.read().strip() == "hello"
+    finally:
+        if os.path.exists(written):
+            os.remove(written)

From ed78beee1bd4bb645af6048e6424112b3f651f23 Mon Sep 17 00:00:00 2001
From: RaresKeY <158580472+RaresKeY@users.noreply.github.com>
Date: Sat, 24 Oct 2026 16:26:21 +0100
Subject: [PATCH 47/53] fix(security): refresh client trust and adopt corrected
 upstream SearXNG (#6791)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Select the official immutable SearXNG release with corrected system and certifi stores in all Compose deployments. Retain native offline, actual-entrypoint and Compose/live regression checks while removing the custom trust-repair image and registry publication path. Reuse the canonical CA inventory checker.

Include released Python, certifi, grpcio, uv and Docker CLI trust updates and strict fourteen-chain validation. Keep unreleased CPython verifier and native-helper fixes separate from claims about shipped artifacts.

Part of #6784 and #6790.

Co-authored-by: Léo <leograndcontact@gmail.com>
---
 .github/scripts/validate-searxng-image.sh |  56 ++++++++
 .github/searxng-validation.compose.yml    |  21 +++
 .github/workflows/ci.yml                  |   2 +-
 .github/workflows/searxng-image.yml       |  79 +++++++++++
 Dockerfile                                |  10 +-
 docker-compose.gpu-amd.yml                |   4 +-
 docker-compose.gpu-nvidia.yml             |   4 +-
 docker-compose.yml                        |   4 +-
 docker/searxng/Dockerfile                 |   9 ++
 docker/searxng/Dockerfile.dockerignore    |  10 ++
 docker/searxng/validate_image.py          | 162 ++++++++++++++++++++++
 docs/searxng-trust-image.md               |  39 ++++++
 docs/tls-trust.md                         |  16 ++-
 requirements-bootstrap.txt                |   4 +-
 requirements.txt                          |   4 +-
 tests/fixtures/ca-trust/README.md         |   8 +-
 tests/fixtures/ca-trust/incident.json     |  13 +-
 tests/test_ca_trust.py                    |   6 +-
 tests/test_searxng_ca_validation.py       | 106 ++++++++++++++
 tests/test_searxng_image_pinned.py        |  25 ++--
 tests/test_searxng_validation.py          |  73 ++++++++++
 21 files changed, 622 insertions(+), 33 deletions(-)
 create mode 100644 .github/scripts/validate-searxng-image.sh
 create mode 100644 .github/searxng-validation.compose.yml
 create mode 100644 .github/workflows/searxng-image.yml
 create mode 100644 docker/searxng/Dockerfile
 create mode 100644 docker/searxng/Dockerfile.dockerignore
 create mode 100644 docker/searxng/validate_image.py
 create mode 100644 docs/searxng-trust-image.md
 create mode 100644 tests/test_searxng_ca_validation.py
 create mode 100644 tests/test_searxng_validation.py

diff --git a/.github/scripts/validate-searxng-image.sh b/.github/scripts/validate-searxng-image.sh
new file mode 100644
index 000000000..3edd5ba16
--- /dev/null
+++ b/.github/scripts/validate-searxng-image.sh
@@ -0,0 +1,56 @@
+#!/usr/bin/env bash
+# Exercise an already-built image through the normal Compose startup path.
+set -euo pipefail
+
+searxng_repo=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")/../.." && pwd)
+searxng_image=${1:?usage: validate-searxng-image.sh IMAGE}
+[[ "$searxng_image" =~ ^[a-zA-Z0-9_./:@+-]+$ ]] || {
+  echo "Invalid image reference" >&2
+  exit 2
+}
+searxng_checks=$(mktemp -d "${TMPDIR:-/tmp}/searxng-ci-XXXXXXXX")
+searxng_project=$(basename "$searxng_checks" | tr '[:upper:]' '[:lower:]')
+export SEARXNG_VALIDATION_IMAGE="$searxng_image"
+export SEARXNG_VALIDATION_CHECKS="$searxng_checks"
+export SEARXNG_VALIDATION_VOLUME="${searxng_project}-settings"
+# Never forward an operator's existing secret or load their .env for a CI probe.
+export SEARXNG_SECRET=searxng-ci-validation-only
+searxng_volume_created=0
+searxng_started=0
+searxng_compose=(docker compose --env-file /dev/null --project-name "$searxng_project"
+  -f "$searxng_repo/docker-compose.yml"
+  -f "$searxng_repo/.github/searxng-validation.compose.yml")
+
+searxng_cleanup() {
+  local searxng_exit=$?
+  if [ "$searxng_started" = 1 ]; then
+    "${searxng_compose[@]}" down --remove-orphans >/dev/null 2>&1 || true
+  fi
+  if [ "$searxng_volume_created" = 1 ]; then
+    docker volume rm "$SEARXNG_VALIDATION_VOLUME" >/dev/null 2>&1 || true
+  fi
+  rm -rf -- "$searxng_checks"
+  return "$searxng_exit"
+}
+trap searxng_cleanup EXIT
+
+install -m 0644 "$searxng_repo/scripts/check_ca_trust.py" \
+  "$searxng_repo/docker/searxng/validate_image.py" "$searxng_checks/"
+install -m 0644 "$searxng_repo/tests/fixtures/ca-trust/incident.json" "$searxng_checks/incident.json"
+install -m 0644 "$searxng_repo/config/searxng/settings.yml" "$searxng_checks/settings.yml"
+install -m 0644 "$searxng_repo/scripts/migrate_searxng_settings.py" "$searxng_checks/migrate_searxng_settings.py"
+if docker volume inspect "$SEARXNG_VALIDATION_VOLUME" >/dev/null 2>&1; then
+  echo "Refusing to reuse an existing validation volume" >&2
+  exit 1
+fi
+docker volume create --label "odysseus.searxng-validation=$searxng_project" \
+  "$SEARXNG_VALIDATION_VOLUME" >/dev/null
+searxng_volume_created=1
+searxng_started=1
+if ! "${searxng_compose[@]}" up --detach --no-deps --no-build --pull never \
+  --wait --wait-timeout 150 searxng; then
+  "${searxng_compose[@]}" logs --no-color searxng >&2 || true
+  exit 1
+fi
+"${searxng_compose[@]}" exec -T searxng /usr/local/searxng/.venv/bin/python \
+  /opt/odysseus-checks/validate_image.py --running --live
diff --git a/.github/searxng-validation.compose.yml b/.github/searxng-validation.compose.yml
new file mode 100644
index 000000000..d1e1c575c
--- /dev/null
+++ b/.github/searxng-validation.compose.yml
@@ -0,0 +1,21 @@
+# CI-only isolation; retain the service's entrypoint, healthcheck and capabilities.
+services:
+  searxng:
+    image: ${SEARXNG_VALIDATION_IMAGE:?set the image being validated}
+    ports: !reset []
+    volumes: !override
+      - searxng-validation-data:/etc/searxng
+      - ${SEARXNG_VALIDATION_CHECKS:?}/settings.yml:/tmp/searxng-settings.yml.template:ro
+      - ${SEARXNG_VALIDATION_CHECKS:?}/migrate_searxng_settings.py:/tmp/migrate-searxng-settings.py:ro
+      - ${SEARXNG_VALIDATION_CHECKS:?}:/opt/odysseus-checks:ro
+    networks: !override
+      - default
+    restart: "no"
+
+networks:
+  default: {}
+
+volumes:
+  searxng-validation-data:
+    external: true
+    name: ${SEARXNG_VALIDATION_VOLUME:?}
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 93dcb5e37..229a4d599 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -171,7 +171,7 @@ jobs:
       - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7  # v10.2.0
         if: steps.docs-check.outputs.docs_only != 'true'
         with:
-          version: "0.13.4"
+          version: "0.13.5"
           enable-cache: true
           cache-dependency-glob: requirements.txt
           prune-cache: false
diff --git a/.github/workflows/searxng-image.yml b/.github/workflows/searxng-image.yml
new file mode 100644
index 000000000..844617b10
--- /dev/null
+++ b/.github/workflows/searxng-image.yml
@@ -0,0 +1,79 @@
+name: ci / SearXNG trust
+
+on:
+  pull_request:
+    paths:
+      - 'docker/searxng/**'
+      - 'scripts/check_ca_trust.py'
+      - 'tests/fixtures/ca-trust/**'
+      - 'tests/test_searxng*'
+      - 'docker-compose*.yml'
+      - 'config/searxng/**'
+      - 'scripts/migrate_searxng_settings.py'
+      - '.github/scripts/*searxng*'
+      - '.github/searxng-validation.compose.yml'
+      - '.github/workflows/searxng-image.yml'
+  push:
+    branches: [dev, main]
+    paths:
+      - 'docker/searxng/**'
+      - 'scripts/check_ca_trust.py'
+      - 'tests/fixtures/ca-trust/**'
+      - 'docker-compose*.yml'
+      - 'config/searxng/**'
+      - 'scripts/migrate_searxng_settings.py'
+      - '.github/scripts/*searxng*'
+      - '.github/searxng-validation.compose.yml'
+      - '.github/workflows/searxng-image.yml'
+  workflow_dispatch:
+
+concurrency:
+  group: searxng-image-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+
+jobs:
+  validate:
+    name: SearXNG validate (${{ matrix.arch }})
+    runs-on: ${{ matrix.runner }}
+    timeout-minutes: 25
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - arch: amd64
+            platform: linux/amd64
+            runner: ubuntu-latest
+          - arch: arm64
+            platform: linux/arm64
+            runner: ubuntu-24.04-arm
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - name: Select the immutable upstream image from Compose
+        id: image
+        run: |
+          docker compose --env-file /dev/null -f docker-compose.yml config --format json |
+            python3 -c 'import json, re, sys; image = json.load(sys.stdin)["services"]["searxng"]["image"]; re.fullmatch(r"docker\.io/searxng/searxng:[0-9]{4}\.[^@\s]+@sha256:[0-9a-f]{64}", image) or sys.exit("Invalid SearXNG pin"); print("image=" + image)' >> "$GITHUB_OUTPUT"
+      - name: Pull the upstream image without registry credentials
+        env:
+          SEARXNG_TEST_IMAGE: ${{ steps.image.outputs.image }}
+        run: docker pull "$SEARXNG_TEST_IMAGE"
+      - uses: docker/setup-buildx-action@37fe631027851001ddb9b187196cc803df7f5f0e # v4.3.0
+      - name: Check unmodified upstream trust and actual entrypoint offline
+        uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7.3.0
+        with:
+          context: .
+          file: docker/searxng/Dockerfile
+          target: validation
+          build-args: SEARXNG_IMAGE=${{ steps.image.outputs.image }}
+          network: none
+          platforms: ${{ matrix.platform }}
+          no-cache-filters: validation
+      - name: Validate the selected upstream runtime through Compose and live HTTPS
+        env:
+          SEARXNG_TEST_IMAGE: ${{ steps.image.outputs.image }}
+        run: bash .github/scripts/validate-searxng-image.sh "$SEARXNG_TEST_IMAGE"
diff --git a/Dockerfile b/Dockerfile
index 28653ab7c..936f35b90 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -3,7 +3,7 @@
 # which raises KeyError on Python 3.13+ (PEP 667). Build patched wheels here so
 # the final image / Cookbook never has to compile the broken sdists. See
 # docker/build-realesrgan-wheels.sh for the full rationale.
-FROM python:3.14-slim AS realesrgan-wheels
+FROM python:3.14.9-slim AS realesrgan-wheels
 RUN apt-get update && apt-get install -y --no-install-recommends curl ca-certificates \
     && rm -rf /var/lib/apt/lists/*
 COPY scripts/check_ca_trust.py /usr/local/bin/check-ca-trust.py
@@ -14,7 +14,7 @@ RUN python -m pip install --no-cache-dir --require-hashes --only-binary=:all: --
 COPY docker/build-realesrgan-wheels.sh /usr/local/bin/build-realesrgan-wheels.sh
 RUN bash /usr/local/bin/build-realesrgan-wheels.sh /wheels
 
-FROM python:3.14-slim
+FROM python:3.14.9-slim
 
 # System deps. tmux is required by Cookbook for background downloads/serves.
 # openssh-client is required for Cookbook remote server tests, setup, probes,
@@ -92,7 +92,8 @@ RUN npm install -g agent-browser@0.35.0 --omit=dev --loglevel=error
 # /var/run/docker.sock mount). The Debian `docker.io` package ships
 # dockerd but not the client binary on slim, so grab the static client
 # tarball from download.docker.com instead.
-ARG DOCKER_CLI_VERSION=29.6.2
+# 29.9.2 includes Go 1.26.10's eMudhra intermediate-key distrust.
+ARG DOCKER_CLI_VERSION=29.9.2
 RUN ARCH="$(dpkg --print-architecture)" \
     && case "$ARCH" in \
          amd64) DARCH=x86_64 ;; \
@@ -129,7 +130,8 @@ RUN pip install --no-cache-dir --no-deps /tmp/odysseus-wheels/*.whl \
     && rm -rf /tmp/odysseus-wheels
 
 # Check gRPC's effective defaults after all Python dependencies are installed.
-# Its wheel can retain affected roots even when pip/certifi are current.
+# The application minimum fixes its bundled roots; the checked override also
+# keeps the effective Docker selection consistent with system trust.
 RUN python /usr/local/bin/check-ca-trust.py --system --python --grpc
 
 # Copy app code
diff --git a/docker-compose.gpu-amd.yml b/docker-compose.gpu-amd.yml
index 183b31601..0e2cdbcb8 100644
--- a/docker-compose.gpu-amd.yml
+++ b/docker-compose.gpu-amd.yml
@@ -145,8 +145,8 @@ services:
     # (depends_on: condition: service_healthy), so a broken upstream `latest`
     # tag blocks the whole app from starting. 2026.6.2 crashes on boot with
     # `KeyError: 'default_doi_resolver'`, failing the healthcheck (issue #1414).
-    # Bump this deliberately after verifying a newer tag boots clean.
-    image: docker.io/searxng/searxng:2026.9.25-12f8b6515@sha256:5286edb35782454ab8a102c5eff6b54bff745853191b46aeead95f225aa6dfb6
+    # Update all default/GPU pins together after native startup and trust checks.
+    image: docker.io/searxng/searxng:2026.10.24-ef0ec03da@sha256:7c7cbe509429e82755104b2a95f52085a98633c95d53f44e4e905fa3a59f08c8
     entrypoint:
       - /bin/sh
       - -c
diff --git a/docker-compose.gpu-nvidia.yml b/docker-compose.gpu-nvidia.yml
index 23404b2eb..5d997f28b 100644
--- a/docker-compose.gpu-nvidia.yml
+++ b/docker-compose.gpu-nvidia.yml
@@ -148,8 +148,8 @@ services:
     # (depends_on: condition: service_healthy), so a broken upstream `latest`
     # tag blocks the whole app from starting. 2026.6.2 crashes on boot with
     # `KeyError: 'default_doi_resolver'`, failing the healthcheck (issue #1414).
-    # Bump this deliberately after verifying a newer tag boots clean.
-    image: docker.io/searxng/searxng:2026.9.25-12f8b6515@sha256:5286edb35782454ab8a102c5eff6b54bff745853191b46aeead95f225aa6dfb6
+    # Update all default/GPU pins together after native startup and trust checks.
+    image: docker.io/searxng/searxng:2026.10.24-ef0ec03da@sha256:7c7cbe509429e82755104b2a95f52085a98633c95d53f44e4e905fa3a59f08c8
     entrypoint:
       - /bin/sh
       - -c
diff --git a/docker-compose.yml b/docker-compose.yml
index a7ddf2f04..808471520 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -126,8 +126,8 @@ services:
     # (depends_on: condition: service_healthy), so a broken upstream `latest`
     # tag blocks the whole app from starting. 2026.6.2 crashes on boot with
     # `KeyError: 'default_doi_resolver'`, failing the healthcheck (issue #1414).
-    # Bump this deliberately after verifying a newer tag boots clean.
-    image: docker.io/searxng/searxng:2026.9.25-12f8b6515@sha256:5286edb35782454ab8a102c5eff6b54bff745853191b46aeead95f225aa6dfb6
+    # Update all default/GPU pins together after native startup and trust checks.
+    image: docker.io/searxng/searxng:2026.10.24-ef0ec03da@sha256:7c7cbe509429e82755104b2a95f52085a98633c95d53f44e4e905fa3a59f08c8
     entrypoint:
       - /bin/sh
       - -c
diff --git a/docker/searxng/Dockerfile b/docker/searxng/Dockerfile
new file mode 100644
index 000000000..0b487e66c
--- /dev/null
+++ b/docker/searxng/Dockerfile
@@ -0,0 +1,9 @@
+# Validation only. Deploy the unmodified upstream image selected by Compose.
+ARG SEARXNG_IMAGE
+FROM ${SEARXNG_IMAGE} AS validation
+COPY scripts/check_ca_trust.py docker/searxng/validate_image.py /opt/odysseus-trust/
+COPY tests/fixtures/ca-trust/incident.json /opt/odysseus-trust/incident.json
+RUN /usr/local/searxng/.venv/bin/python /opt/odysseus-trust/validate_image.py
+
+FROM validation AS live-validation
+RUN /usr/local/searxng/.venv/bin/python /opt/odysseus-trust/validate_image.py --live
diff --git a/docker/searxng/Dockerfile.dockerignore b/docker/searxng/Dockerfile.dockerignore
new file mode 100644
index 000000000..3e7e75e3f
--- /dev/null
+++ b/docker/searxng/Dockerfile.dockerignore
@@ -0,0 +1,10 @@
+**
+!scripts/
+!scripts/check_ca_trust.py
+!docker/
+!docker/searxng/
+!docker/searxng/**
+!tests/
+!tests/fixtures/
+!tests/fixtures/ca-trust/
+!tests/fixtures/ca-trust/incident.json
diff --git a/docker/searxng/validate_image.py b/docker/searxng/validate_image.py
new file mode 100644
index 000000000..c768cf010
--- /dev/null
+++ b/docker/searxng/validate_image.py
@@ -0,0 +1,162 @@
+"""Verify incident distrust and startup in the unmodified upstream image."""
+
+import hashlib
+import asyncio
+import json
+import os
+from pathlib import Path
+import re
+import signal
+import ssl
+import subprocess
+import sys
+import tempfile
+import time
+import urllib.request
+
+import certifi
+
+from check_ca_trust import check_bundle
+
+
+def check_chains():
+    incident = json.loads(Path(__file__).with_name("incident.json").read_text())
+    system = Path(os.environ["SSL_CERT_FILE"])
+    capath = os.environ["SSL_CERT_DIR"]
+    stores = [["-CAfile", str(system), "-no-CApath"],
+              ["-CAfile", certifi.where(), "-no-CApath"],
+              ["-no-CAfile", "-CApath", capath]]
+    check_bundle(system)
+    check_bundle(Path(certifi.where()))
+    with tempfile.TemporaryDirectory() as directory:
+        directory = Path(directory)
+        for fingerprint, pem in incident["certificates"].items():
+            if hashlib.sha256(ssl.PEM_cert_to_DER_cert(pem)).hexdigest() != fingerprint:
+                raise ValueError(f"incident fixture fingerprint mismatch: {fingerprint}")
+            (directory / fingerprint).write_text(pem)
+        positive = directory / "affected.pem"
+        positive.write_text("\n".join(incident["certificates"][fp] for fp in incident["roots"]))
+        for hostname, chain in incident["chains"].items():
+            untrusted = directory / "untrusted.pem"
+            untrusted.write_text("\n".join(incident["certificates"][fp] for fp in chain[1:]))
+            base = ["openssl", "verify", "-no-CAstore", "-attime", str(incident["verification_time"]),
+                    "-purpose", "sslserver", "-verify_hostname", hostname,
+                    "-x509_strict", "-partial_chain", "-trusted_first", "-untrusted", str(untrusted)]
+            expectations = [(selection, False) for selection in stores]
+            for selection, expected in expectations + [
+                    (["-CAfile", str(positive), "-no-CApath"], True)]:
+                result = subprocess.run(base + selection + [str(directory / chain[0])],
+                                        capture_output=True, text=True)
+                if (result.returncode == 0) != expected:
+                    raise RuntimeError(f"unexpected chain result: {hostname}: {selection}: {result.stderr}")
+                # Accept issuer lookup, self-signed and explicitly untrusted
+                # certificate errors, rather than tool or fixture failures.
+                if not expected and not re.search(r"error (?:2|18|19|20|21|27) at \d+ depth lookup", result.stderr):
+                    raise RuntimeError(f"not a certificate trust rejection: {hostname}: {result.stderr}")
+    print(f"{len(incident['chains'])}/{len(incident['chains'])} incident chains rejected by system PEM, hashed directory and certifi; affected controls accepted")
+
+
+def check_boot(live=False):
+    with tempfile.TemporaryDirectory() as directory:
+        settings = Path(directory) / "settings.yml"
+        settings.write_text("use_default_settings: true\nserver:\n  secret_key: offline-build-validation-only\n  limiter: false\nsearch:\n  formats: [html, json]\n")
+        cache = Path(directory) / "cache"
+        cache.mkdir()
+        env = dict(os.environ, SEARXNG_SETTINGS_PATH=str(settings),
+                   __SEARXNG_CONFIG_PATH=directory, __SEARXNG_DATA_PATH=str(cache),
+                   GRANIAN_HOST="127.0.0.1", GRANIAN_PORT="18888")
+        # Do not expose a port or issue an outbound search during offline builds.
+        with tempfile.TemporaryFile() as log:
+            process = subprocess.Popen(["/usr/local/searxng/entrypoint.sh"],
+                                       cwd="/usr/local/searxng", env=env, stdout=log,
+                                       stderr=subprocess.STDOUT, start_new_session=True)
+            try:
+                opener = urllib.request.build_opener(urllib.request.ProxyHandler({}))
+                healthy = False
+                for _ in range(60):
+                    if process.poll() is not None:
+                        break
+                    try:
+                        with opener.open("http://127.0.0.1:18888/healthz", timeout=1) as response:
+                            healthy = response.status == 200
+                    except OSError:
+                        pass
+                    if healthy:
+                        break
+                    time.sleep(0.5)
+                if not healthy:
+                    log.seek(0)
+                    raise RuntimeError("SearXNG failed boot smoke: " + log.read().decode(errors="replace")[-6000:])
+                print("SearXNG loopback healthcheck passed")
+                # Its root entrypoint regenerates system trust. Repeat the
+                # behavioral checks after that real startup path completes.
+                check_running(live=live, port=18888)
+            finally:
+                if process.poll() is None:
+                    os.killpg(process.pid, signal.SIGTERM)
+                try:
+                    process.wait(timeout=10)
+                except subprocess.TimeoutExpired:
+                    os.killpg(process.pid, signal.SIGKILL)
+                    process.wait()
+
+
+def check_running(live=False, port=None):
+    """Verify an existing service without repairing it or starting another one."""
+    port = int(os.environ.get("GRANIAN_PORT", "8080")) if port is None else port
+    opener = urllib.request.build_opener(urllib.request.ProxyHandler({}))
+    with opener.open(f"http://127.0.0.1:{port}/healthz", timeout=5) as response:
+        if response.status != 200:
+            raise RuntimeError("SearXNG running-service healthcheck failed")
+    check_chains()
+    for path in Path(os.environ["SSL_CERT_DIR"]).iterdir():
+        if re.fullmatch(r"[0-9a-fA-F]{8}\.[0-9]+", path.name):
+            check_bundle(path)
+    if live:
+        asyncio.run(check_https())
+        with opener.open(f"http://127.0.0.1:{port}/search?q=python+documentation&format=json", timeout=90) as search:
+            payload = json.load(search)
+        results = payload.get("results", [])
+        if not results:
+            raise RuntimeError("live search returned no results")
+        print(f"SearXNG live JSON search passed: {len(results)} results")
+
+
+async def check_https():
+    # Exercise the actual pinned SearXNG client factory with its default CA
+    # selection, rather than a different HTTP library's trust configuration.
+    sys.path.insert(0, "/usr/local/searxng")
+    from curl_cffi.requests.exceptions import RequestException
+    from searx.network.client import new_client
+
+    client = new_client(enable_http=False, verify=True, enable_http2=True,
+                        enable_http3=False, max_connections=2, proxies={},
+                        local_address=None, max_redirects=3)
+    try:
+        response = await client.get("https://pypi.org/simple/certifi/", timeout=30)
+        if response.status_code != 200:
+            raise RuntimeError(f"ordinary HTTPS failed: {response.status_code}")
+        print("SearXNG actual curl client ordinary HTTPS passed with verification enabled")
+        incident = json.loads(Path(__file__).with_name("incident.json").read_text())
+        for hostname in incident["chains"]:
+            try:
+                await client.get(f"https://{hostname}/", timeout=30, allow_redirects=False)
+            except RequestException as exc:
+                # libcurl code 60 is peer certificate verification failure.
+                # DNS failures, timeouts and handshake EOF do not prove distrust.
+                if exc.code != 60:
+                    raise RuntimeError(f"inconclusive incident TLS failure: {hostname}: {exc}") from exc
+            else:
+                raise RuntimeError(f"incident HTTPS unexpectedly accepted: {hostname}")
+        print(f"SearXNG actual curl client rejects {len(incident['chains'])}/{len(incident['chains'])} incident hosts with certificate errors after startup")
+    finally:
+        await client.aclose()
+
+
+if __name__ == "__main__":
+    live = "--live" in sys.argv
+    if "--running" in sys.argv:
+        check_running(live=live)
+    else:
+        check_chains()
+        check_boot(live=live)
diff --git a/docs/searxng-trust-image.md b/docs/searxng-trust-image.md
new file mode 100644
index 000000000..e0f406e82
--- /dev/null
+++ b/docs/searxng-trust-image.md
@@ -0,0 +1,39 @@
+# Upstream SearXNG trust validation
+
+SearXNG owns independent system and Python certificate stores. Updating Odysseus's Python environment does not update this sidecar. The base and both standalone GPU Compose files now select the official `docker.io/searxng/searxng:2026.10.24-ef0ec03da` image at immutable multiarch digest `sha256:7c7cbe509429e82755104b2a95f52085a98633c95d53f44e4e905fa3a59f08c8`. Its system and certifi stores remove the affected eMudhra trust. The [upstream certifi update](https://github.com/searxng/searxng/pull/6881) is included in this release.
+
+Deploy the upstream image directly. The validation Dockerfile adds public fixtures and diagnostics only; no repair layer, custom runtime image or project registry publisher is required. `scripts/check_ca_trust.py` owns the known-certificate inventory for both the application and SearXNG checks.
+
+## Validate a pin update
+
+Run from the repository root on a disposable Docker host. The helper uses a fresh configuration volume, omits published ports and does not load the operator's `.env`. It retains the base Compose settings wrapper, healthcheck and capabilities. Outbound network access and working search engines are required for the live checks.
+
+```sh
+image=$(docker compose --env-file /dev/null -f docker-compose.yml config --format json |
+  python3 -c 'import json, sys; print(json.load(sys.stdin)["services"]["searxng"]["image"])')
+
+# Offline build-step checks, including actual entrypoint and loopback health.
+# Pulling the selected base still requires registry access.
+docker build --network=none --target validation \
+  --build-arg "SEARXNG_IMAGE=$image" -f docker/searxng/Dockerfile .
+
+# Exercise the exact unmodified deployment image after an anonymous pull.
+docker pull "$image"
+bash .github/scripts/validate-searxng-image.sh "$image"
+```
+
+The offline checks require all fourteen incident chains to fail certificate verification through the system PEM bundle, hashed CA directory and certifi. The affected positive-control roots must accept those same chains. Each fixture's DER fingerprint is verified first, and a fixed verification timestamp prevents expiry from hiding a broken mitigation. Checks run again after the real upstream root entrypoint regenerates trust.
+
+The live checks use SearXNG's actual curl client factory. Ordinary verified HTTPS must succeed, all fourteen incident hosts must fail with curl certificate error 60, and a JSON search must return results. DNS failures, timeouts and generic handshake failures are inconclusive and fail validation. The checks inspect the already-running service without changing its trust stores.
+
+The `ci / SearXNG trust` workflow runs these offline and Compose/live checks on native amd64 and arm64 runners. It selects the same immutable image as base Compose, pulls without registry credentials, and has read-only repository permissions. It neither publishes a replacement image nor requires package-write credentials. Update all three deployment pins together; the alignment regression guards the standalone GPU files.
+
+## Rollout and scope
+
+Changing a Compose pin does not replace running containers. After updating the checkout, run `docker compose pull searxng` and `docker compose up -d --no-deps searxng`, then inspect health, retained settings and actual Odysseus search integration. Use the appropriate standalone GPU Compose file when that is the deployment being managed.
+
+Operator-mounted trust, custom engines, persisted packages and independently managed clients need separate effective-client checks. An amd64 result does not establish arm64 behavior. The fixture-based check detects known certificate fingerprints; it does not model every native revocation mechanism or arbitrary reissued certificates sharing a compromised key. See [outbound TLS trust](tls-trust.md) for the application, bootstrap, Chromium and other runtime boundaries.
+
+## Public fixture provenance
+
+The public CA inventory comes from the incident's [roots](https://emudhra.we-have-a-problem.com/roots.json) and [intermediates](https://emudhra.we-have-a-problem.com/impacted-intermediates.json). The additional cross-signed issuer and fourteen chain fixtures come from [chains.zip](https://emudhra.we-have-a-problem.com/chains.zip), SHA-256 `7b949956955fc501a30f4d98d2f513d34c0bbbe92e29a968194c96e097ce2345`. Fixtures contain public certificates only. See [the fixture notes](../tests/fixtures/ca-trust/README.md).
diff --git a/docs/tls-trust.md b/docs/tls-trust.md
index fd5d9776d..71f0fe76e 100644
--- a/docs/tls-trust.md
+++ b/docs/tls-trust.md
@@ -2,7 +2,7 @@
 
 Odysseus uses both Python package CA bundles and system trust. HTTPX uses certifi by default; the guarded web/PDF fetcher and webhook delivery explicitly use Python's system SSL context. A configured `LLM_CA_BUNDLE` adds certificates to system trust for model calls. Upgrading certifi alone cannot repair every outbound HTTPS path.
 
-For the October 2026 eMudhra incident, use certifi 2026.10.19 or newer, pip 26.2.2 or newer, and uv 0.13.4 or newer wherever uv is used. Pip has its own vendored certifi and also loads system roots. Update the operating system's certificate package separately. See the [Python security announcement](https://discuss.python.org/t/109576) and [incident details](https://emudhra.we-have-a-problem.com/).
+For the October 2026 eMudhra incident, use certifi 2026.10.23 or newer, pip 26.2.2 or newer, and uv 0.13.5 or newer wherever uv is used. Pip has its own vendored certifi and also loads system roots. Update the operating system's certificate package separately. See the [Python security announcement](https://discuss.python.org/t/109576) and [incident details](https://emudhra.we-have-a-problem.com/).
 
 Before other pip installs, bootstrap the selected environment with the integrity-pinned wheels:
 
@@ -27,7 +27,9 @@ Explicit PEM bundles can also be passed as positional arguments. The check rejec
 
 This is an offline inventory check of known certificate fingerprints. It does not modify stores, reject requests at runtime, model native OS revocation, or detect arbitrary reissued certificates sharing the compromised keys. Chromium's policy separately matches public keys. Check mounted or replaced CA files again after deployment, remove affected trust through the owning platform/client configuration, and restart clients that cache SSL contexts. A passing build cannot validate custom files introduced later.
 
-Both Docker build stages refresh system CA certificates and bootstrap pip/certifi before dependency installation. The build fails if known affected CA certificates remain. Node uses the corrected system store through `--use-openssl-ca`. Python gRPC uses that same PEM file through `GRPC_DEFAULT_SSL_ROOTS_FILE_PATH`; updating certifi alone does not replace gRPC's independent wheel bundle. After dependency installation, the image checks gRPC's selected file as well. An explicit gRPC override must be readable and free of known affected CA certificates: gRPC can otherwise fall back to its affected bundled defaults. Upstream gRPC has [merged a bundle update](https://github.com/grpc/grpc/commit/8b32af3bf498c2ba9667410eaa8c836e700e97e6); as checked on 2026-10-21, its [release backport](https://github.com/grpc/grpc/pull/43700) is still open and the latest published grpcio wheel is 1.84.0. Retain the checked override until a released replacement's actual trust behavior has been verified.
+Both Docker build stages use Python 3.14.9, refresh system CA certificates and bootstrap pip/certifi before dependency installation. The build fails if known affected CA certificates remain. Node uses the corrected system store through `--use-openssl-ca`. Python gRPC uses that same PEM file through `GRPC_DEFAULT_SSL_ROOTS_FILE_PATH`; updating certifi alone does not replace gRPC's independent wheel bundle. After dependency installation, the image checks gRPC's selected file as well. An explicit gRPC override must be readable and free of known affected CA certificates. [grpcio 1.84.1](https://github.com/grpc/grpc/releases/tag/v1.84.1) includes the upstream root-bundle correction and is the application minimum. Retain the checked override as a consistent image trust selection; older persisted Python environments and explicit client roots still need independent checks.
+
+The image also bundles Docker CLI [29.9.2](https://github.com/moby/moby/releases/tag/docker-v29.9.2), built with Go 1.26.10's distrust of the compromised intermediate keys. Cookbook uses this client for optional Docker operations. Default Compose does not mount the host Docker socket; local daemon access requires the explicit [host-Docker overlay](../docker/host-docker.yml), whose usual Unix-socket connection does not use TLS. The client update is maintenance of a shipped tool, not evidence that these local calls were exposed. It does not update the host daemon or other containers' clients and trust stores; assess those separately.
 
 Chromium uses a separate trust store. The Docker image installs a managed `CADistrustedCertificates` policy for the eight compromised intermediate public keys, covering their cross-signs without depending on background revocation updates. It adds no trusted certificate and does not disable certificate verification. The policy and public-certificate provenance are documented in [the browser policy note](../docker/chromium-ca-policy.md). Native browser installations and independently managed profiles require their own platform policy or vendor update; this image policy does not configure host browsers.
 
@@ -62,4 +64,12 @@ For containers started non-root or without the SETUID/SETGID capabilities needed
 
 SearXNG is a separate HTTPS client and image; updating the Odysseus image does not patch it. Inspect its effective CA path and update or rebuild that image independently. Also inspect persisted `/app/.local` packages, remote Cookbook environments, and externally configured MCP runtimes. Image replacement does not necessarily replace those environments.
 
-For behavioral validation, all twelve [published test chains](https://emudhra.we-have-a-problem.com/chains.zip), including the AAA cross-signs, must fail certificate verification through the effective stores. Confirm that an ordinary known-good HTTPS request still succeeds. In Chromium, confirm the managed policy is loaded at `chrome://policy` and test the incident endpoints through the actual browser path with certificate verification enabled. The PEM checker cannot inspect Chromium's policy or its active verifier. Package versions and a successful image build alone do not prove that a running deployment selects the corrected store.
+For behavioral validation, all fourteen [published test chains](https://emudhra.we-have-a-problem.com/chains.zip), including the AAA cross-signs and two chains without Certificate Transparency entries, must fail certificate verification through the effective stores. Confirm that an ordinary known-good HTTPS request still succeeds. In Chromium, confirm the managed policy is loaded at `chrome://policy` and test the incident endpoints through the actual browser path with certificate verification enabled. The PEM checker cannot inspect Chromium's policy or its active verifier. Package versions and a successful image build alone do not prove that a running deployment selects the corrected store.
+
+## Follow-up releases
+
+The maintained bootstrap selects certifi 2026.10.23 with its verified wheel hash; pip remains 26.2.2. The certifi update removes the C1/C3 roots in addition to the earlier incident changes. CI uses uv 0.13.5, which adds verifier-level rejection of the compromised intermediate keys and updated managed CPython builds. Existing virtual environments do not update automatically. See the [certifi change](https://github.com/certifi/python-certifi/commit/b60466c9f2882d9cf088943c650b0faac06c080c), [uv release](https://github.com/astral-sh/uv/releases/tag/0.13.5), and [Python security releases](https://blog.python.org/2026/10/python-3151-3149-31317/). The pinned bootstrap still replaces the selected versions exactly; preserving newer installed versions and private-mirror support remain separate maintenance.
+
+SearXNG remains an independent trust owner. Use the [upstream-image validation and rollout instructions](searxng-trust-image.md); updating these application packages does not repair an existing sidecar. Host daemons, native browser policy, optional compiled clients and independently managed integrations require their own effective-client checks.
+
+CPython's [intermediate-key verifier block](https://github.com/python/cpython/pull/160042) and its [3.14 backport](https://github.com/python/cpython/pull/160569) merged on October 24. They are distinct from Python 3.14.9's bundled-pip update. No released 3.14 interpreter containing that verifier change was identified when this image pin was selected; retain the corrected effective trust stores and track the subsequent security release. hf-xet's [trust fix](https://github.com/huggingface/xet-core/pull/1038) is also merged but not included in the latest published 1.7.0 release at that check. Agent-browser 0.39.2 and primp 2.0.1 are not established incident fixes for their independent native trust paths. A version bump alone does not establish that the active client uses corrected trust.
diff --git a/requirements-bootstrap.txt b/requirements-bootstrap.txt
index 8b39dc69b..da1d62220 100644
--- a/requirements-bootstrap.txt
+++ b/requirements-bootstrap.txt
@@ -4,5 +4,5 @@
 # Direct universal wheels avoid index resolution through the old trust store.
 pip @ https://files.pythonhosted.org/packages/3f/06/3e4420302363fbb71be3c7f35ce042f54bfca330e3e66b3a2e3c4cca579f/pip-26.2.2-py3-none-any.whl \
     --hash=sha256:fd7f4dfa8190e014013b9f08f3e973f4e4c26ffd179a204895533a7254813a70
-certifi @ https://files.pythonhosted.org/packages/c4/51/29046e48f693c54e5b7412216d447a1d8362c9653148d98c02cdf65fa733/certifi-2026.10.19-py3-none-any.whl \
-    --hash=sha256:42d35340cc5b9ba78e818ddbff0c5b1c2b779de448a340fd1b989f5fa8670e1b
+certifi @ https://files.pythonhosted.org/packages/32/d1/a3652fe2c19134d0d15922177821d863cbd7e842d53a21bbe7e8e3a1b5ac/certifi-2026.10.23-py3-none-any.whl \
+    --hash=sha256:e9b54de76e530bb6cf0ccd036787103acb58fd42ba930ea8bf948ddbaa2f61d1
diff --git a/requirements.txt b/requirements.txt
index 4d794537d..26dcdecb1 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -4,7 +4,7 @@ python-multipart
 python-dotenv
 httpx
 # HTTPS clients using certifi must distrust the compromised eMudhra CA paths.
-certifi>=2026.10.19
+certifi>=2026.10.23
 httpcore>=1.0,<2.0
 pydantic>=2.13.4
 pydantic-settings>=2.14.1
@@ -23,6 +23,8 @@ numpy
 # chromadb-client is the lightweight HTTP client (talks to a standalone
 # ChromaDB service); fastembed runs local ONNX embeddings.
 chromadb-client
+# gRPC vendors independent roots; 1.84.1 removes the incident trust anchors.
+grpcio>=1.84.1
 fastembed
 youtube-transcript-api
 yt-dlp
diff --git a/tests/fixtures/ca-trust/README.md b/tests/fixtures/ca-trust/README.md
index 3feef0f40..1c362d42f 100644
--- a/tests/fixtures/ca-trust/README.md
+++ b/tests/fixtures/ca-trust/README.md
@@ -4,12 +4,14 @@ The public certificates embedded in `tests/test_ca_trust.py` exercise the Octobe
 
 Sources: the [incident root list](https://emudhra.we-have-a-problem.com/roots.json) and the public Mozilla root certificates distributed in Debian's `ca-certificates` package.
 
-`incident.json` contains the four published roots, sixteen [compromised intermediate certificates and cross-signs](https://emudhra.we-have-a-problem.com/impacted-intermediates.json), and the [twelve published server chains](https://emudhra.we-have-a-problem.com/chains.zip), retrieved on 2026-10-21. Certificates are deduplicated by SHA-256 of DER; each chain lists its leaf first. The additional cross-signed `emSign Root TLS CA - G3` issuer comes from those chains and has fingerprint `3094025792039a68af6e553686410bdab7c0d4a36b9084cba64202e35d6ebbdd`. Like the intermediates, it must not be accepted as a custom trust anchor. All data is public certificate material, with no private keys.
+`incident.json` contains the four published roots, sixteen [compromised intermediate certificates and cross-signs](https://emudhra.we-have-a-problem.com/impacted-intermediates.json), and the [fourteen published server chains](https://emudhra.we-have-a-problem.com/chains.zip), retrieved on 2026-10-21 with chains refreshed on 2026-10-23. The refresh adds the two DV G3B hosts without Certificate Transparency entries and preserves the original twelve chains. Certificates are deduplicated by SHA-256 of DER; each chain lists its leaf first. The additional cross-signed `emSign Root TLS CA - G3` issuer comes from those chains and has fingerprint `3094025792039a68af6e553686410bdab7c0d4a36b9084cba64202e35d6ebbdd`. Like the intermediates, it must not be accepted as a custom trust anchor. All data is public certificate material, with no private keys.
 
 Downloaded source SHA-256 values:
 
 - `roots.json`: `119f32cd81a6b5a4e3c4c2df5fe07daa90dc43cafa123a62f0394f1895d92380`
 - `impacted-intermediates.json`: `f67b3abe9b4879f4e91874ed041beccd71257f1db41c588c724ccf12aa90c59e`
-- `chains.zip`: `8a2edc81b6c51e3ad27d45ca1e441ec84c961e2dee0fc547f2a02c0f74315f95`
+- `chains.zip`: `7b949956955fc501a30f4d98d2f513d34c0bbbe92e29a968194c96e097ce2345`
 
-The offline OpenSSL regression verifies server purpose, hostname and strict certificate rules with partial-chain trust, at `2026-10-21T12:00:00Z` (`1792584000`). Fixing the verification date keeps later certificate expiry from masking a broken mitigation. All twelve chains must verify against the affected positive-control roots and fail against the unaffected G1-only store. Adding the compromised DV G3B intermediate restores two paths, which the checker must reject. The regression makes no network requests and skips chain verification if the OpenSSL executable is unavailable; certificate-inventory tests still run using Python's standard library.
+The offline OpenSSL regression verifies server purpose, hostname and strict certificate rules with partial-chain trust, at `2026-10-23T12:00:00Z` (`1792756800`). Fixing the verification date keeps later certificate expiry from masking a broken mitigation. All fourteen chains must verify against the affected positive-control roots and fail against the unaffected G1-only store. Adding the compromised DV G3B intermediate restores four paths, including the two new hosts, which the checker must reject. The regression makes no network requests and skips chain verification if the OpenSSL executable is unavailable; certificate-inventory tests still run using Python's standard library.
+
+The upstream SearXNG image validation uses the same `incident.json` inventory and fixed verification timestamp, checking each stored DER fingerprint before use. See [the image documentation](../../../docs/searxng-trust-image.md) for its validation targets and source provenance.
diff --git a/tests/fixtures/ca-trust/incident.json b/tests/fixtures/ca-trust/incident.json
index 771a341f2..58f572b94 100644
--- a/tests/fixtures/ca-trust/incident.json
+++ b/tests/fixtures/ca-trust/incident.json
@@ -1,5 +1,5 @@
 {
-  "verification_time": 1792584000,
+  "verification_time": 1792756800,
   "roots": {
     "7dd78d5f4f13459a83dff9abbba62edbaf6f2d102bf257fd712f4d9f2746ed8d": "emSign Root TLS CA - G3",
     "f2edaaff3d9b701fb4d14c9f285f8c0bad90fc3bcc1fa07d47f4718edaba34a5": "emSign Root CS CA - G3",
@@ -26,6 +26,7 @@
   },
   "certificates": {
     "0164d7ceae5bb909c272af151ff44b1177ae9b47d9424b94f1d9558c30934d19": "-----BEGIN CERTIFICATE-----\nMIIDaDCCAu6gAwIBAgIPWIsuPCu4zaE+GhIJJUMhMAoGCCqGSM49BAMDMFYxCzAJ\nBgNVBAYTAklOMSUwIwYDVQQKDBxlTXVkaHJhIFRlY2hub2xvZ2llcyBMaW1pdGVk\nMSAwHgYDVQQDDBdlbVNpZ24gUm9vdCBUTFMgQ0EgLSBHMzAeFw0yNTA0MzAxNTM1\nMDlaFw00MDA0MjgxODMwMDBaMEAxCzAJBgNVBAYTAlVTMRQwEgYDVQQKDAtlTXVk\naHJhIEluYzEbMBkGA1UEAwwSRU0gRFYgVExTIENBIC0gRzNDMHYwEAYHKoZIzj0C\nAQYFK4EEACIDYgAEOnp4YsjETTJN3WkDOmeCwO/u/kBV5ooSP6A3G6O9kZRRTuFy\npDPjYw8CvRiAN9nlFJ+bd9uUooHfmHsv6oiLdL3+j9pMEJnubKGVZv4+8OX2sJpV\nbMyLpQVh3xsqRB0Bo4IBljCCAZIwHwYDVR0jBBgwFoAU4TqrIXzx401UrtRyt/2L\nWUIgkFQwHQYDVR0OBBYEFK5+EFw8KZbBqEcnBVnx4D3U5QrzMB0GA1UdJQQWMBQG\nCCsGAQUFBwMBBggrBgEFBQcDAjBdBgNVHSAEVjBUMDkGCysGAQQBg44hAQABMCow\nKAYIKwYBBQUHAgEWHGh0dHA6Ly9yZXBvc2l0b3J5LmVtc2lnbi5jb20wDQYLKwYB\nBAGDjiEBAmQwCAYGZ4EMAQIBMHUGCCsGAQUFBwEBBGkwZzAkBggrBgEFBQcwAYYY\naHR0cDovL29jc3AtYy5lbXNpZ24uY29tMD8GCCsGAQUFBzAChjNodHRwOi8vcmVw\nb3NpdG9yeS5lbXNpZ24uY29tL2NlcnRzL0VNRFZUTFNDQUczQy5wN2MwNwYDVR0f\nBDAwLjAsoCqgKIYmaHR0cDovL2NybC5lbXNpZ24uY29tLz9yb290dGxzY2FnMy5j\ncmwwDgYDVR0PAQH/BAQDAgEGMBIGA1UdEwEB/wQIMAYBAf8CAQAwCgYIKoZIzj0E\nAwMDaAAwZQIxAMEN2HWMocbuWdy1d33pH6JpMvP/V/DIS5PtZbv1Q7TXEbxrcyxg\nyuddOJscYDJJlAIwB4sH1BpbScDzkdD4tJBSwrG/1Mx82vb8YaySehNuu1+1oXNd\nAEKwaJ0mVzScy2+6\n-----END CERTIFICATE-----\n",
+    "0cbfe22b824385823fd3bf4be4d131e8901342933a7feef1cf8b3110b8e44a70": "-----BEGIN CERTIFICATE-----\nMIICQTCCAcigAwIBAgIUG01Z/jOotSvB49K4K27kFjpdnWMwCgYIKoZIzj0EAwIw\nPzELMAkGA1UEBhMCTkwxEzARBgNVBAoMCmVNdWRocmEgQlYxGzAZBgNVBAMMEkVN\nIERWIFRMUyBDQSAtIEczQjAeFw0yNjEwMjIxMjU3MzFaFw0yNzA1MDUxMzAyMzFa\nMDQxMjAwBgNVBAMMKWR2LWczYi1ub2N0LWVtdWRocmEud2UtaGF2ZS1hLXByb2Js\nZW0uY29tMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEI805yWr+RxanILifET+/\nGwHsXo7dp8ghA3OgwR0Mg11Bl6iYyOzldy4iU7kM+3qfDNsUrzxvkUkJZQpYieuC\n+aOBrDCBqTAMBgNVHRMBAf8EAjAAMA4GA1UdDwEB/wQEAwIHgDATBgNVHSUEDDAK\nBggrBgEFBQcDATA0BgNVHREELTArgilkdi1nM2Itbm9jdC1lbXVkaHJhLndlLWhh\ndmUtYS1wcm9ibGVtLmNvbTAdBgNVHQ4EFgQUOlRrLQGIczrmr4H+Oak06aUmJ4Yw\nHwYDVR0jBBgwFoAU4h4v5xwZOQ5VS2LBICRXNSSKJRQwCgYIKoZIzj0EAwIDZwAw\nZAIwf4ekmRgXAxXP2AjpVY2f1bO42GC7Nnc80t4OpaWJeVdXpT+X3dOsLRwlIUm0\nYbMwAjBihTx7oHfaYB3KRnFuhKqlHYmUcOe9Hjxqs6bubZohhrqMQzPocyasDhJL\nUx3HsgQ=\n-----END CERTIFICATE-----\n",
     "21f57f83631a93c98e867050075746b3361e0433c9e0e969462852476784f6f0": "-----BEGIN CERTIFICATE-----\nMIICPzCCAcagAwIBAgIUH0gWfBRnOiSjcduti/cukjDGAjIwCgYIKoZIzj0EAwIw\nPzELMAkGA1UEBhMCTkwxEzARBgNVBAoMCmVNdWRocmEgQlYxGzAZBgNVBAMMEkVN\nIE9WIFRMUyBDQSAtIEczQjAeFw0yNjEwMjAwMjIyNDJaFw0yNzA1MDMwMjI3NDJa\nMDMxMTAvBgNVBAMMKG92LWczYi1hYWEtZW11ZGhyYS53ZS1oYXZlLWEtcHJvYmxl\nbS5jb20wWTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAAQ3EfjVE+6fUm9gr7UoUv6N\nYPttIdILR9OMZnAdTj+RWT1Z4fp7dpC5mat1gbIo4J6EDelcOQQz5/oGeB3gFJKw\no4GrMIGoMAwGA1UdEwEB/wQCMAAwDgYDVR0PAQH/BAQDAgeAMBMGA1UdJQQMMAoG\nCCsGAQUFBwMBMDMGA1UdEQQsMCqCKG92LWczYi1hYWEtZW11ZGhyYS53ZS1oYXZl\nLWEtcHJvYmxlbS5jb20wHQYDVR0OBBYEFKzQPp6gTBOWb0TBxZbkL5zsQn3oMB8G\nA1UdIwQYMBaAFJvYZVGv5+csN60I7mkZ2b83hK4KMAoGCCqGSM49BAMCA2cAMGQC\nMARKrRRBEWY2Ix1d80DGUvC7bWENP1Q9pf6BOGF4+84UiwV5+nAuht/+hdpAanWB\nsQIwJF2dW8tpPN6lTm1kDerzG6yJAJOz4drotaTthMF2+efuv5W2FL7Dr8qZSd1z\n201o\n-----END CERTIFICATE-----\n",
     "3094025792039a68af6e553686410bdab7c0d4a36b9084cba64202e35d6ebbdd": "-----BEGIN CERTIFICATE-----\nMIIDdDCCAvmgAwIBAgIQAJYaPvsTWVdu0EAFtGhKWzAKBggqhkjOPQQDAzBrMQsw\nCQYDVQQGEwJJTjETMBEGA1UECxMKZW1TaWduIFBLSTElMCMGA1UEChMcZU11ZGhy\nYSBUZWNobm9sb2dpZXMgTGltaXRlZDEgMB4GA1UEAxMXZW1TaWduIEVDQyBSb290\nIENBIC0gRzMwHhcNMjQwNzExMTU0MzM2WhcNMzkwNzA5MTgzMDAwWjBWMQswCQYD\nVQQGEwJJTjElMCMGA1UECgwcZU11ZGhyYSBUZWNobm9sb2dpZXMgTGltaXRlZDEg\nMB4GA1UEAwwXZW1TaWduIFJvb3QgVExTIENBIC0gRzMwdjAQBgcqhkjOPQIBBgUr\ngQQAIgNiAARfD9w/q1cWxL6D9bMGH6CQ4u+gAV6GN9s+PwQx9Bl4hC+0iU8QOk8m\nWO/RwXQy10DCSxT8vSIJClHKp+Ao4qJKdYeV0SwZ7LMQziyLfxIUOY6Grja/sQFw\nLKYf8EdDXAyjggF1MIIBcTAfBgNVHSMEGDAWgBR8XQKEE9TMipuBzhccLikenEhj\nQjAdBgNVHQ4EFgQU4TqrIXzx401UrtRyt/2LWUIgkFQwHQYDVR0lBBYwFAYIKwYB\nBQUHAwEGCCsGAQUFBwMCMD0GA1UdIAQ2MDQwMgYEVR0gADAqMCgGCCsGAQUFBwIB\nFhxodHRwOi8vcmVwb3NpdG9yeS5lbXNpZ24uY29tMHgGCCsGAQUFBwEBBGwwajAi\nBggrBgEFBQcwAYYWaHR0cDovL29jc3AuZW1zaWduLmNvbTBEBggrBgEFBQcwAoY4\naHR0cDovL3JlcG9zaXRvcnkuZW1zaWduLmNvbS9jZXJ0cy9lbVNpZ25FQ0NSb290\nQ0FHMy5jcnQwMwYDVR0fBCwwKjAooCagJIYiaHR0cDovL2NybC5lbXNpZ24uY29t\nP1Jvb3RDQUczLmNybDAOBgNVHQ8BAf8EBAMCAQYwEgYDVR0TAQH/BAgwBgEB/wIB\nATAKBggqhkjOPQQDAwNpADBmAjEAt9CIpRGp46QHQYDUBnLKw+vvK0/h9vmilEAg\nTroUl/anH4x2rXHqiCtBTBfgKDegAjEA8WpG1LTZdAIL0FSYqxXeREaeTSxEofM0\n1jJH3jGvCXC79LU9UPJ2o3TU+UIj2gMV\n-----END CERTIFICATE-----\n",
     "346cdd962e97189b59aee5526d1ae8fa714bb1a64094dfa67bef768ee93f36b5": "-----BEGIN CERTIFICATE-----\nMIICODCCAb+gAwIBAgIUbWvtwSNK/Qro223vAqyz323+VBAwCgYIKoZIzj0EAwIw\nQDELMAkGA1UEBhMCVVMxFDASBgNVBAoMC2VNdWRocmEgSW5jMRswGQYDVQQDDBJF\nTSBEViBUTFMgQ0EgLSBHM0MwHhcNMjYxMDIwMDA1OTM2WhcNMjcwNTAzMDEwNDM2\nWjAvMS0wKwYDVQQDDCRkdi1nM2MtZW11ZGhyYS53ZS1oYXZlLWEtcHJvYmxlbS5j\nb20wWTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAAScdBQpNUOOCcag6YEVFccNRSFe\nUIl02iH53vDfoWPJFS005WzqF3CPDclB/kygP2gWF4pg/r5gPYdnI3/6Vdzro4Gn\nMIGkMAwGA1UdEwEB/wQCMAAwDgYDVR0PAQH/BAQDAgeAMBMGA1UdJQQMMAoGCCsG\nAQUFBwMBMC8GA1UdEQQoMCaCJGR2LWczYy1lbXVkaHJhLndlLWhhdmUtYS1wcm9i\nbGVtLmNvbTAdBgNVHQ4EFgQUBj2yGO/TzDOE/u/6QeUvcW8y1iMwHwYDVR0jBBgw\nFoAUrn4QXDwplsGoRycFWfHgPdTlCvMwCgYIKoZIzj0EAwIDZwAwZAIwBQOOQqG9\nccdzM/7XIlXLtota1esALaLmgEN/ZweosBIvk4xabHcERZInWVIwO45NAjBos8Ue\nNwDe1X3ahdK2lkxqBEoBMtUHJN18TnJKs2nK1gmXpMbmY5oKnAQQgCEZPA4=\n-----END CERTIFICATE-----\n",
@@ -34,6 +35,7 @@
     "432ec25f0d28de9006d97bf752f17bbb2cd41f669933fcb072d9a1148d0261f3": "-----BEGIN CERTIFICATE-----\nMIIDaDCCAu6gAwIBAgIQAIAJkopkEHYBrwX6LxnxCTAKBggqhkjOPQQDAzBWMQsw\nCQYDVQQGEwJJTjElMCMGA1UECgwcZU11ZGhyYSBUZWNobm9sb2dpZXMgTGltaXRl\nZDEgMB4GA1UEAwwXZW1TaWduIFJvb3QgVExTIENBIC0gRzMwHhcNMjUwNDMwMTUz\nOTMxWhcNNDAwNDI4MTgzMDAwWjBAMQswCQYDVQQGEwJVUzEUMBIGA1UECgwLZU11\nZGhyYSBJbmMxGzAZBgNVBAMMEkVNIEVWIFRMUyBDQSAtIEczQzB2MBAGByqGSM49\nAgEGBSuBBAAiA2IABC1W6Cmm+4LGSkaX2WCvlR6QZ66R+SbTQwbaSKiq63hptqZ+\nbSdCbgRCqgOzbhmI3/Y2UU7hzwf1uks/8qBmRa59MdWGatMao9JG6wsxd+6Zy3Vm\nxRbOdICKZo+R8MR/yqOCAZUwggGRMB8GA1UdIwQYMBaAFOE6qyF88eNNVK7Ucrf9\ni1lCIJBUMB0GA1UdDgQWBBSmJV6AqU2385Z8G8eR35K87kvrXzAdBgNVHSUEFjAU\nBggrBgEFBQcDAQYIKwYBBQUHAwIwXAYDVR0gBFUwUzA5BgsrBgEEAYOOIQEAATAq\nMCgGCCsGAQUFBwIBFhxodHRwOi8vcmVwb3NpdG9yeS5lbXNpZ24uY29tMA0GCysG\nAQQBg44hAQJ4MAcGBWeBDAEBMHUGCCsGAQUFBwEBBGkwZzAkBggrBgEFBQcwAYYY\naHR0cDovL29jc3AtYy5lbXNpZ24uY29tMD8GCCsGAQUFBzAChjNodHRwOi8vcmVw\nb3NpdG9yeS5lbXNpZ24uY29tL2NlcnRzL0VNRVZUTFNDQUczQy5wN2MwNwYDVR0f\nBDAwLjAsoCqgKIYmaHR0cDovL2NybC5lbXNpZ24uY29tLz9yb290dGxzY2FnMy5j\ncmwwDgYDVR0PAQH/BAQDAgEGMBIGA1UdEwEB/wQIMAYBAf8CAQAwCgYIKoZIzj0E\nAwMDaAAwZQIwBy1wTnzH4lXDTy2PD91ysLjvnlVN3JbJmc1BIMEU8TOLkYVHibMc\n9HeyonikFSfmAjEA6uE3QRxlrZTz/1/lXPTEMUhoauAtycagtlNFp79kjhvNa2/f\nAal1GNxsOutLnr0Y\n-----END CERTIFICATE-----\n",
     "45a883f349aedfd5f3a649b5498ffb121712ba8b448f3f2a91dbc5a766fcddbe": "-----BEGIN CERTIFICATE-----\nMIIDzjCCAragAwIBAgIRAKAk/fS6Zlx4XOSgIEg4WLcwDQYJKoZIhvcNAQELBQAw\nezELMAkGA1UEBhMCR0IxGzAZBgNVBAgMEkdyZWF0ZXIgTWFuY2hlc3RlcjEQMA4G\nA1UEBwwHU2FsZm9yZDEaMBgGA1UECgwRQ29tb2RvIENBIExpbWl0ZWQxITAfBgNV\nBAMMGEFBQSBDZXJ0aWZpY2F0ZSBTZXJ2aWNlczAeFw0yNTA1MTQwMDAwMDBaFw0y\nODEyMzEyMzU5NTlaMD8xCzAJBgNVBAYTAk5MMRMwEQYDVQQKDAplTXVkaHJhIEJW\nMRswGQYDVQQDDBJFTSBEViBUTFMgQ0EgLSBHM0IwdjAQBgcqhkjOPQIBBgUrgQQA\nIgNiAATnntnASpdzxHNeUREdqFrCvV5kqzdLgOEsvCA47B5PDjuBL8mFnh5nr7BO\nL4vJf3SFumWqkR7opORbYtXMA9Vr5nizw4y03JN8okYOI4RTyJKTXSnUT5HhVga2\nPM7atGijggE1MIIBMTAfBgNVHSMEGDAWgBSgEQojPpbxB+zirynvgqV/0DCktDAd\nBgNVHQ4EFgQU4h4v5xwZOQ5VS2LBICRXNSSKJRQwDgYDVR0PAQH/BAQDAgEGMBIG\nA1UdEwEB/wQIMAYBAf8CAQAwHQYDVR0lBBYwFAYIKwYBBQUHAwEGCCsGAQUFBwMC\nMDEGA1UdIAQqMCgwCAYGZ4EMAQIBMA0GCysGAQQBg44hAQABMA0GCysGAQQBg44h\nAQJkMEMGA1UdHwQ8MDowOKA2oDSGMmh0dHA6Ly9jcmwuY29tb2RvY2EuY29tL0FB\nQUNlcnRpZmljYXRlU2VydmljZXMuY3JsMDQGCCsGAQUFBwEBBCgwJjAkBggrBgEF\nBQcwAYYYaHR0cDovL29jc3AuY29tb2RvY2EuY29tMA0GCSqGSIb3DQEBCwUAA4IB\nAQBzQ1IoqpdotM6gFrR4Q3YrKifOLeaj5XXunldpVE/vZn2TxC2y0s8oYiLR5ICE\nwqVXSB7N6BM1Mp+Nif7Jbhb2IswAfSR4Iik8+B0iRmi7lYoNlycCgHjmsjOmZaxM\nQkPmjXAJbG5f4V41OsvJZmS7lI3r0IuvEDVX3GAZ13on6IImSs9ybNpHQ7NCqkMQ\n7wH4uAO1dtpFycgJSdHaCOhHjrox2BTYGLdpUrYwY3EOAjlZ8UGgsxs7mG+xquMl\nbN1LFURwfnkVMP3T/DBIZ/ys2+lNFyxK3FlArrV4/000uTnVB1lO8oGORYdXoT5V\nGUyRCEIDhF5TBUuKF4E3kf1h\n-----END CERTIFICATE-----\n",
     "4b2460a466f95fd40113bcdcca2ceb29b3b093921de45474da7df48874c630b1": "-----BEGIN CERTIFICATE-----\nMIIDWzCCAuGgAwIBAgIPVEt/kiwxriIKSpIpFvbmMAoGCCqGSM49BAMDMFUxCzAJ\nBgNVBAYTAklOMSUwIwYDVQQKDBxlTXVkaHJhIFRlY2hub2xvZ2llcyBMaW1pdGVk\nMR8wHQYDVQQDDBZlbVNpZ24gUm9vdCBDUyBDQSAtIEczMB4XDTI1MDQzMDE2Mzg0\nMFoXDTQwMDQyODE4MzAwMFowPzELMAkGA1UEBhMCVVMxFDASBgNVBAoMC2VNdWRo\ncmEgSW5jMRowGAYDVQQDDBFFTSBPViBDUyBDQSAtIEczQzB2MBAGByqGSM49AgEG\nBSuBBAAiA2IABLnw4GNHAqacpqrdRDz9YsQbm6SyCSRpfXl052kaEm+5avs+NML9\nO8X0gwYfJl3CpYQ2NHMjUQQ2so8E84YjYwZ5gOJQPgJTLWVGI1pxZaJZoe9Jb3Qb\nX97neHII5Lj676OCAYswggGHMB8GA1UdIwQYMBaAFGh0A/iFyo1UUFcdFuDI3kUN\nq80tMB0GA1UdDgQWBBTub3MpjW+/p7Mbw5U09hVWRHhmtzATBgNVHSUEDDAKBggr\nBgEFBQcDAzBeBgNVHSAEVzBVMDkGCysGAQQBg44hAQABMCowKAYIKwYBBQUHAgEW\nHGh0dHA6Ly9yZXBvc2l0b3J5LmVtc2lnbi5jb20wDgYMKwYBBAGDjiEBAoFIMAgG\nBmeBDAEEATB0BggrBgEFBQcBAQRoMGYwJAYIKwYBBQUHMAGGGGh0dHA6Ly9vY3Nw\nLWMuZW1zaWduLmNvbTA+BggrBgEFBQcwAoYyaHR0cDovL3JlcG9zaXRvcnkuZW1z\naWduLmNvbS9jZXJ0cy9FTU9WQ1NDQUczQy5wN2MwNgYDVR0fBC8wLTAroCmgJ4Yl\naHR0cDovL2NybC5lbXNpZ24uY29tLz9yb290Y3NjYWczLmNybDAOBgNVHQ8BAf8E\nBAMCAQYwEgYDVR0TAQH/BAgwBgEB/wIBADAKBggqhkjOPQQDAwNoADBlAjEA8yPg\n8sntOhLwV2QXJ5LEaKSpo/fnE3uOgTadK73fDhyjiqr0Io9GVuQTYqBPbQ2TAjBg\neuApmBS486+iei03lRrp139dPw6k28jjGNvWsAU7A1N86J1zPJVDEyVH+nMAWC0=\n-----END CERTIFICATE-----\n",
+    "5510ecf5764dee8dfe9468ae2d7323da21fcd5530889906540a2f8725c6f74db": "-----BEGIN CERTIFICATE-----\nMIICSTCCAdCgAwIBAgIUO7oRaIOhMWD0jFgvxusAGNi5CI0wCgYIKoZIzj0EAwIw\nPzELMAkGA1UEBhMCTkwxEzARBgNVBAoMCmVNdWRocmEgQlYxGzAZBgNVBAMMEkVN\nIERWIFRMUyBDQSAtIEczQjAeFw0yNjEwMjIxMzE0NDhaFw0yNzA1MDUxMzE5NDha\nMDgxNjA0BgNVBAMMLWR2LWczYi1hYWEtbm9jdC1lbXVkaHJhLndlLWhhdmUtYS1w\ncm9ibGVtLmNvbTBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IABJ0yLMf28vw2E6pO\nc74doinU47pwTYD6xZ60nkrGkqI05DxVKXblos+V5S0+bgDjT2qw1F39EW9EUj8b\nNQmmqv6jgbAwga0wDAYDVR0TAQH/BAIwADAOBgNVHQ8BAf8EBAMCB4AwEwYDVR0l\nBAwwCgYIKwYBBQUHAwEwOAYDVR0RBDEwL4ItZHYtZzNiLWFhYS1ub2N0LWVtdWRo\ncmEud2UtaGF2ZS1hLXByb2JsZW0uY29tMB0GA1UdDgQWBBTruPPaZ1PiEFfpqdLo\n8Ra5Ah5a2jAfBgNVHSMEGDAWgBTiHi/nHBk5DlVLYsEgJFc1JIolFDAKBggqhkjO\nPQQDAgNnADBkAjBUTUTymJylZiZRV/RqMayZdUPJKRDIcn9+sUPpG66AjVgx8M+h\nDGzxxgeroOSxzSwCMBM/r1y7g371RI10nDU16T0WEAO/Udqyyuc8mJ2LCQ+Gxv3c\njU2NXGQLsvosv6T0ww==\n-----END CERTIFICATE-----\n",
     "579480aea166290bd3c643589e795fc0d0e54e86505d180f1dff99efd3199512": "-----BEGIN CERTIFICATE-----\nMIIDzTCCArWgAwIBAgIRANj4aF5PK9nYJAKoWhwetzEwDQYJKoZIhvcNAQELBQAw\nezELMAkGA1UEBhMCR0IxGzAZBgNVBAgMEkdyZWF0ZXIgTWFuY2hlc3RlcjEQMA4G\nA1UEBwwHU2FsZm9yZDEaMBgGA1UECgwRQ29tb2RvIENBIExpbWl0ZWQxITAfBgNV\nBAMMGEFBQSBDZXJ0aWZpY2F0ZSBTZXJ2aWNlczAeFw0yNTA1MTQwMDAwMDBaFw0y\nODEyMzEyMzU5NTlaMD8xCzAJBgNVBAYTAk5MMRMwEQYDVQQKDAplTXVkaHJhIEJW\nMRswGQYDVQQDDBJFTSBFViBUTFMgQ0EgLSBHM0IwdjAQBgcqhkjOPQIBBgUrgQQA\nIgNiAAQl26haZNOX2gsQUunqVG5Ie+/qnJ2daKDF6tz+73Wmm7XW/AH0K/vKbrQL\nzWTAdn42/9Bdl6gTxaoMbJUw55z18IZkaPE4BkIKpchRhAseJSVA55DktlTDhS7W\nSvHoZX2jggE0MIIBMDAfBgNVHSMEGDAWgBSgEQojPpbxB+zirynvgqV/0DCktDAd\nBgNVHQ4EFgQUPtwg2YlGmId7hz/YgUeyXBXYRwYwDgYDVR0PAQH/BAQDAgEGMBIG\nA1UdEwEB/wQIMAYBAf8CAQAwHQYDVR0lBBYwFAYIKwYBBQUHAwEGCCsGAQUFBwMC\nMDAGA1UdIAQpMCcwBwYFZ4EMAQEwDQYLKwYBBAGDjiEBAAEwDQYLKwYBBAGDjiEB\nAngwQwYDVR0fBDwwOjA4oDagNIYyaHR0cDovL2NybC5jb21vZG9jYS5jb20vQUFB\nQ2VydGlmaWNhdGVTZXJ2aWNlcy5jcmwwNAYIKwYBBQUHAQEEKDAmMCQGCCsGAQUF\nBzABhhhodHRwOi8vb2NzcC5jb21vZG9jYS5jb20wDQYJKoZIhvcNAQELBQADggEB\nAJNFuAFW9Gnw/8+kCO4KIlZdnM1Sh2u+8cK0EYAHhXpb5FlGvYkcARigo5oS7VoM\n7FOYlTueV6yICZKNAYawZPJPhNCGK+rp3cQBEz6d0n8OZEYZov9lb3ll8ORgSDuf\nFVIW6Gagg/UnOamLBTOR8eD5V73SCme/B2cHUDw+m5E8cc+0Ujzz3Cn3ex5JrhXk\n2T3s8PoVzEmhTgGboFfcWO1EYhPPrYwdxPYRQIXAXUXhLEOVNL9ASbZJLFI8E1IM\nm7NwxVN2s38jWpaCUaaF0tg7hfiy7oe13rzJfHsdqldJVTTUTPWVx8TC4ju0VLet\nbAlwhwFT6AP8uIVMGUHNw24=\n-----END CERTIFICATE-----\n",
     "59cf0386b56bc2414a0c06241ea9e25e01a9c93bac7a596648747f9d0ded4906": "-----BEGIN CERTIFICATE-----\nMIICQTCCAcegAwIBAgIULuWnWW6kFV6QZxp2ls8r18NCjXkwCgYIKoZIzj0EAwIw\nQDELMAkGA1UEBhMCVVMxFDASBgNVBAoMC2VNdWRocmEgSW5jMRswGQYDVQQDDBJF\nTSBPViBUTFMgQ0EgLSBHM0MwHhcNMjYxMDIwMDIyMjQyWhcNMjcwNTAzMDIyNzQy\nWjAzMTEwLwYDVQQDDChvdi1nM2MtYWFhLWVtdWRocmEud2UtaGF2ZS1hLXByb2Js\nZW0uY29tMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEb7+5g2YHNYwH2eQERrZc\nTmVuf/RmvzsGGMSwXmZke6vn35Ut5HME7UOOU3Muy+BSfjfpo6fjL5KOs3Ndz67d\nOKOBqzCBqDAMBgNVHRMBAf8EAjAAMA4GA1UdDwEB/wQEAwIHgDATBgNVHSUEDDAK\nBggrBgEFBQcDATAzBgNVHREELDAqgihvdi1nM2MtYWFhLWVtdWRocmEud2UtaGF2\nZS1hLXByb2JsZW0uY29tMB0GA1UdDgQWBBQ7oBzq3jpTuvntbIkzMV12Ps3O0TAf\nBgNVHSMEGDAWgBQ06uoM68kK2vnQxeLtm3jJh54bbDAKBggqhkjOPQQDAgNoADBl\nAjEA/Y7AZ4M2MYbN5Od9tREaUfFjZKoOjczfIKPjKNMjtGxTdL9WUXvAT4QDgktn\n/IJdAjAbORTkAXD5hggyG6K7p0MBz3lFZJb2l/LndZlrttJWBLP8QGrc44hrZZtK\nIq0d1dE=\n-----END CERTIFICATE-----\n",
     "5f1ded4dd590af74631290cf073b122a2aac6a1fa479778a0bd43579bd832699": "-----BEGIN CERTIFICATE-----\nMIIDzjCCAragAwIBAgIRAOlCI73pL5FOWrmsq/2sNxAwDQYJKoZIhvcNAQELBQAw\nezELMAkGA1UEBhMCR0IxGzAZBgNVBAgMEkdyZWF0ZXIgTWFuY2hlc3RlcjEQMA4G\nA1UEBwwHU2FsZm9yZDEaMBgGA1UECgwRQ29tb2RvIENBIExpbWl0ZWQxITAfBgNV\nBAMMGEFBQSBDZXJ0aWZpY2F0ZSBTZXJ2aWNlczAeFw0yNTA1MTQwMDAwMDBaFw0y\nODEyMzEyMzU5NTlaMD8xCzAJBgNVBAYTAk5MMRMwEQYDVQQKDAplTXVkaHJhIEJW\nMRswGQYDVQQDDBJFTSBPViBUTFMgQ0EgLSBHM0IwdjAQBgcqhkjOPQIBBgUrgQQA\nIgNiAARziXqg6zz9yosSQC/68KvE4SErr43ud4rJ7i1tuD+sKAxeBWOK56Ks1xwy\nKo42HN659pxDArndjXPRzGyqsswK7k4hbOl53VGKSvS2JuVoTN1lgDftDIVOTMEv\nTPhkbQ2jggE1MIIBMTAfBgNVHSMEGDAWgBSgEQojPpbxB+zirynvgqV/0DCktDAd\nBgNVHQ4EFgQUm9hlUa/n5yw3rQjuaRnZvzeErgowDgYDVR0PAQH/BAQDAgEGMBIG\nA1UdEwEB/wQIMAYBAf8CAQAwHQYDVR0lBBYwFAYIKwYBBQUHAwEGCCsGAQUFBwMC\nMDEGA1UdIAQqMCgwCAYGZ4EMAQICMA0GCysGAQQBg44hAQABMA0GCysGAQQBg44h\nAQJuMEMGA1UdHwQ8MDowOKA2oDSGMmh0dHA6Ly9jcmwuY29tb2RvY2EuY29tL0FB\nQUNlcnRpZmljYXRlU2VydmljZXMuY3JsMDQGCCsGAQUFBwEBBCgwJjAkBggrBgEF\nBQcwAYYYaHR0cDovL29jc3AuY29tb2RvY2EuY29tMA0GCSqGSIb3DQEBCwUAA4IB\nAQALRoOSvkzRa+tN5Rje9W5GiXd/qsicd9N6Gnh0SWC7VyWH+HycIqAnFCMYZznj\nCeGusomFYHE42SHWr85JDIbgzy6y3dO4i9n9w0Bx7yrXWBbDzFS8VgA3+EY4Cg7y\nmtoC3RPOJVtaXXPZ+68X804g1Mj+3vCSHj2lNPVgco0OzSIOJ/KMg1R9MLBkiKzb\nbERAGZHejY0HBhYd76IINZN8z6bBNah2UdFYxsOisLynPQUkol6gRLum024/FzVl\nCCDfnUusrkr+mAfPAvD/Vb8bhpA7jYtepuU+2mIdShj5lLlvAwZphn+ypWycuo2x\n0k9mldz2dqI9nhCiY+TTIOOR\n-----END CERTIFICATE-----\n",
@@ -64,11 +66,20 @@
       "7e02622ab6d745c1edb4b431bb1c551e667305c3dd3eb0c7cc6dfdb523807424",
       "45a883f349aedfd5f3a649b5498ffb121712ba8b448f3f2a91dbc5a766fcddbe"
     ],
+    "dv-g3b-aaa-noct-emudhra.we-have-a-problem.com": [
+      "5510ecf5764dee8dfe9468ae2d7323da21fcd5530889906540a2f8725c6f74db",
+      "45a883f349aedfd5f3a649b5498ffb121712ba8b448f3f2a91dbc5a766fcddbe"
+    ],
     "dv-g3b-emudhra.we-have-a-problem.com": [
       "9dcb21b1841d75313b3c888f4bb9cc01f8f51379a76fbaa241ca492b668839e7",
       "42c4accd12c4f59597925e1a08a7a90102608543809308d50ec427e118ba1493",
       "3094025792039a68af6e553686410bdab7c0d4a36b9084cba64202e35d6ebbdd"
     ],
+    "dv-g3b-noct-emudhra.we-have-a-problem.com": [
+      "0cbfe22b824385823fd3bf4be4d131e8901342933a7feef1cf8b3110b8e44a70",
+      "42c4accd12c4f59597925e1a08a7a90102608543809308d50ec427e118ba1493",
+      "3094025792039a68af6e553686410bdab7c0d4a36b9084cba64202e35d6ebbdd"
+    ],
     "dv-g3c-aaa-emudhra.we-have-a-problem.com": [
       "9200d153c3cac272cc06bf68f9ea163fc24659fc3331e77668236fe00645ae52",
       "62b7f9868263f72f6911fc78ceaf72c1979158b7368bf648683bb2aa39b02e72"
diff --git a/tests/test_ca_trust.py b/tests/test_ca_trust.py
index 0eb35695f..b7dff18fb 100644
--- a/tests/test_ca_trust.py
+++ b/tests/test_ca_trust.py
@@ -132,7 +132,7 @@ class CATrustTests(unittest.TestCase):
             custom = directory / "custom.pem"
             fingerprint = next(iter(INCIDENT["intermediates"]))
             custom.write_text(clean.read_text() + INCIDENT["certificates"][fingerprint])
-            self.assertEqual(len(INCIDENT["chains"]), 12)
+            self.assertEqual(len(INCIDENT["chains"]), 14)
             custom_accepted = []
             for hostname, chain in INCIDENT["chains"].items():
                 leaf, intermediates = directory / "leaf.pem", directory / "chain.pem"
@@ -156,9 +156,11 @@ class CATrustTests(unittest.TestCase):
                     self.assertIn("unable to get local issuer certificate", negative.stderr)
                     if verify(custom).returncode == 0:
                         custom_accepted.append(hostname)
-            self.assertEqual(custom_accepted, [
+            self.assertCountEqual(custom_accepted, [
                 "dv-g3b-aaa-emudhra.we-have-a-problem.com",
+                "dv-g3b-aaa-noct-emudhra.we-have-a-problem.com",
                 "dv-g3b-emudhra.we-have-a-problem.com",
+                "dv-g3b-noct-emudhra.we-have-a-problem.com",
             ])
             checker.check_bundle(clean)
             for bundle in (affected, custom):
diff --git a/tests/test_searxng_ca_validation.py b/tests/test_searxng_ca_validation.py
new file mode 100644
index 000000000..1e13e1571
--- /dev/null
+++ b/tests/test_searxng_ca_validation.py
@@ -0,0 +1,106 @@
+"""A network failure must not be mistaken for rejection of an incident chain."""
+
+import asyncio
+import importlib.util
+import io
+import json
+from pathlib import Path
+import sys
+from types import ModuleType, SimpleNamespace
+from unittest.mock import AsyncMock, patch
+
+import pytest
+
+
+ROOT = Path(__file__).resolve().parents[1]
+INCIDENT = json.loads((ROOT / "tests/fixtures/ca-trust/incident.json").read_text())
+
+
+@pytest.fixture
+def validator():
+    checker = ModuleType("check_ca_trust")
+    checker.check_bundle = lambda path: None
+    spec = importlib.util.spec_from_file_location(
+        "searxng_validation", ROOT / "docker/searxng/validate_image.py"
+    )
+    module = importlib.util.module_from_spec(spec)
+    with patch.dict(sys.modules, {"check_ca_trust": checker}):
+        spec.loader.exec_module(module)
+    module.__file__ = str(ROOT / "tests/fixtures/ca-trust/validate_image.py")
+    return module
+
+
+class RequestFailure(Exception):
+    def __init__(self, code):
+        super().__init__(f"curl error {code}")
+        self.code = code
+
+
+@pytest.mark.parametrize("code", [60, 6, 28, 35, None])
+def test_live_probe_requires_certificate_errors_for_every_host(validator, code):
+    hosts = []
+
+    async def get(url, **kwargs):
+        if url == "https://pypi.org/simple/certifi/":
+            return SimpleNamespace(status_code=200)
+        hosts.append(url.removeprefix("https://").removesuffix("/"))
+        assert kwargs["allow_redirects"] is False
+        if code is not None:
+            raise RequestFailure(code)
+        return SimpleNamespace(status_code=200)
+
+    client = SimpleNamespace(get=get, aclose=AsyncMock())
+    factory = ModuleType("searx.network.client")
+
+    def new_client(**kwargs):
+        assert kwargs["verify"] is True
+        return client
+
+    factory.new_client = new_client
+    errors = ModuleType("curl_cffi.requests.exceptions")
+    errors.RequestException = RequestFailure
+    modules = {"searx.network.client": factory, "curl_cffi.requests.exceptions": errors}
+    with patch.dict(sys.modules, modules), patch.object(sys, "path", list(sys.path)):
+        if code == 60:
+            asyncio.run(validator.check_https())
+            assert set(hosts) == set(INCIDENT["chains"])
+        else:
+            expected = "unexpectedly accepted" if code is None else "inconclusive"
+            with pytest.raises(RuntimeError, match=expected):
+                asyncio.run(validator.check_https())
+    client.aclose.assert_awaited_once()
+
+
+def test_offline_probe_rejects_openssl_execution_failure(validator):
+    result = SimpleNamespace(returncode=1, stderr="openssl: unknown option", stdout="")
+    with patch.dict(validator.os.environ, {"SSL_CERT_FILE": "/unused.pem", "SSL_CERT_DIR": "/unused"}), \
+            patch.object(validator.subprocess, "run", return_value=result):
+        with pytest.raises(RuntimeError, match="not a certificate trust rejection"):
+            validator.check_chains()
+
+
+@pytest.mark.parametrize("results", [[{"title": "ordinary result"}], []])
+def test_running_probe_checks_existing_service_without_repair_or_second_boot(validator, tmp_path, results):
+    certificate = tmp_path / "01234567.0"
+    certificate.write_text("certificate double")
+    (tmp_path / "unrelated").write_text("ignored")
+    health = io.BytesIO(b"OK")
+    health.status = 200
+    search = io.BytesIO(json.dumps({"results": results}).encode())
+    with patch.dict(validator.os.environ, {"SSL_CERT_DIR": str(tmp_path), "GRANIAN_PORT": "8080"}), \
+            patch.object(validator.urllib.request, "build_opener") as opener, \
+            patch.object(validator, "check_chains") as chains, \
+            patch.object(validator, "check_bundle") as bundle, \
+            patch.object(validator, "check_https", new_callable=AsyncMock) as https, \
+            patch.object(validator.subprocess, "Popen") as boot:
+        opener.return_value.open.side_effect = [health, search]
+        if results:
+            validator.check_running(live=True)
+        else:
+            with pytest.raises(RuntimeError, match="no results"):
+                validator.check_running(live=True)
+        assert opener.return_value.open.call_args_list[0].args == ("http://127.0.0.1:8080/healthz",)
+        chains.assert_called_once_with()
+        bundle.assert_called_once_with(certificate)
+        https.assert_awaited_once()
+        boot.assert_not_called()
diff --git a/tests/test_searxng_image_pinned.py b/tests/test_searxng_image_pinned.py
index df9b1b53e..77bafc8e3 100644
--- a/tests/test_searxng_image_pinned.py
+++ b/tests/test_searxng_image_pinned.py
@@ -10,17 +10,22 @@ startup. This guards that the pin stays in place.
 import re
 from pathlib import Path
 
-COMPOSE = Path(__file__).resolve().parent.parent / "docker-compose.yml"
+import yaml
+
+ROOT = Path(__file__).resolve().parent.parent
+COMPOSE = ROOT / "docker-compose.yml"
 
 
 def test_searxng_image_is_pinned_not_latest():
     text = COMPOSE.read_text(encoding="utf-8")
-    m = re.search(r"image:\s*\S*searxng/searxng:(\S+)", text)
-    assert m, "searxng image line not found in docker-compose.yml"
-    tag = m.group(1)
-    assert tag != "latest", (
-        "SearXNG must be pinned, not ':latest' — odysseus startup depends on its "
-        "healthcheck, so a broken upstream latest tag blocks the app (issue #1414)"
-    )
-    # A real version tag (date-based, e.g. 2026.5.31-7159b8aed), not a moving ref.
-    assert re.match(r"\d{4}\.\d", tag), f"expected a versioned tag, got {tag!r}"
+    image = yaml.safe_load(text)["services"]["searxng"]["image"]
+    assert re.fullmatch(
+        r"docker\.io/searxng/searxng:\d{4}\.\d[^\s@]*@sha256:[0-9a-f]{64}", image
+    ), f"SearXNG must use a versioned immutable upstream image: {image!r}"
+
+
+def test_all_standalone_compose_files_select_the_same_searxng_image():
+    expected = yaml.safe_load(COMPOSE.read_text())["services"]["searxng"]["image"]
+    for name in ("docker-compose.gpu-amd.yml", "docker-compose.gpu-nvidia.yml"):
+        actual = yaml.safe_load((ROOT / name).read_text())["services"]["searxng"]["image"]
+        assert actual == expected, f"{name} selects a different SearXNG image"
diff --git a/tests/test_searxng_validation.py b/tests/test_searxng_validation.py
new file mode 100644
index 000000000..021e2846a
--- /dev/null
+++ b/tests/test_searxng_validation.py
@@ -0,0 +1,73 @@
+"""Native checks must validate the selected runtime without registry credentials."""
+
+import json
+import os
+from pathlib import Path
+import subprocess
+
+import pytest
+import yaml
+
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+def test_ci_checks_the_pinned_upstream_image_on_both_native_architectures():
+    workflow = yaml.safe_load((ROOT / ".github/workflows/searxng-image.yml").read_text())
+    events = workflow.get("on", workflow.get(True))
+    assert "pull_request_target" not in events
+    assert workflow["permissions"] == {"contents": "read"}
+    assert set(workflow["jobs"]) == {"validate"}
+    job = workflow["jobs"]["validate"]
+    matrix = job["strategy"]["matrix"]["include"]
+    assert {(row["arch"], row["runner"]) for row in matrix} == {
+        ("amd64", "ubuntu-latest"), ("arm64", "ubuntu-24.04-arm")
+    }
+    steps = job["steps"]
+    assert not any("login-action" in step.get("uses", "") for step in steps)
+    assert all(step.get("with", {}).get("persist-credentials") is False
+               for step in steps if "actions/checkout@" in step.get("uses", ""))
+    offline = next(step for step in steps if "docker/build-push-action@" in step.get("uses", ""))
+    assert offline["with"]["network"] == "none"
+    assert offline["with"]["build-args"] == "SEARXNG_IMAGE=${{ steps.image.outputs.image }}"
+    live = next(step for step in steps if "validate-searxng-image.sh" in step.get("run", ""))
+    assert live["env"]["SEARXNG_TEST_IMAGE"] == "${{ steps.image.outputs.image }}"
+
+
+@pytest.mark.parametrize("failure,expected", [("none", 0), ("exec", 7), ("up", 1), ("existing-volume", 1)])
+def test_compose_probe_owns_only_its_temporary_resources(tmp_path, failure, expected):
+    """Exercise the real helper with a Docker double, including failure cleanup."""
+    binary = tmp_path / "docker"
+    calls = tmp_path / "calls.jsonl"
+    binary.write_text('''#!/usr/bin/env python3
+import json, os, sys
+args = sys.argv[1:]
+with open(os.environ["DOCKER_CALLS"], "a") as log:
+    log.write(json.dumps({"args": args, "volume": os.environ["SEARXNG_VALIDATION_VOLUME"], "secret": os.environ["SEARXNG_SECRET"]}) + "\\n")
+failure = os.environ["DOCKER_FAILURE"]
+if args[:2] == ["volume", "inspect"]:
+    sys.exit(0 if failure == "existing-volume" else 1)
+if "exec" in args and failure == "exec":
+    sys.exit(7)
+if "up" in args and failure == "up":
+    sys.exit(9)
+''')
+    binary.chmod(0o755)
+    result = subprocess.run(["bash", str(ROOT / ".github/scripts/validate-searxng-image.sh"), "localhost/searxng:validated"], env={**os.environ, "PATH": str(tmp_path) + ":" + os.environ["PATH"], "DOCKER_CALLS": str(calls), "DOCKER_FAILURE": failure, "SEARXNG_SECRET": "operator-secret-must-not-propagate"}, capture_output=True, text=True)
+    assert result.returncode == expected, result.stderr
+    entries = [json.loads(line) for line in calls.read_text().splitlines()]
+    assert all(entry["secret"] == "searxng-ci-validation-only" for entry in entries)
+    commands = [entry["args"] for entry in entries]
+    if failure == "existing-volume":
+        assert len(commands) == 1
+        return
+    up = next(command for command in commands if "up" in command)
+    assert up[up.index("--env-file") + 1] == "/dev/null"
+    assert "--no-deps" in up and "--no-build" in up and "--wait" in up
+    assert up[up.index("--pull") + 1] == "never"
+    down = next(command for command in commands if "down" in command)
+    assert "--volumes" not in down
+    assert commands[-1] == ["volume", "rm", entries[-1]["volume"]]
+    if failure != "up":
+        execute = next(command for command in commands if "exec" in command)
+        assert execute[-2:] == ["--running", "--live"]

From a0c93f38ef196aff5c2bdb90ba2c64419254d012 Mon Sep 17 00:00:00 2001
From: Tim F <t.feddersen@qrelation.de>
Date: Sat, 24 Oct 2026 17:44:07 +0200
Subject: [PATCH 48/53] chore: harden and update supporting services (#6788)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* chore: harden and update supporting services

* chore(compose): pin ChromaDB and ntfy images by tag and digest

chromadb/chroma:latest and a bare binwiederhier/ntfy change underneath
an existing install on the next pull, so two hosts on the same commit
can run different sidecar builds. SearXNG is already pinned this way.

Pin chroma 1.5.9 and ntfy v2.32.0 to the multi-arch index digests that
:latest currently resolves to, so nothing changes at runtime today. The
standalone GPU files carry the same references, as
test_gpu_compose_standalone.py requires. Add a test that every sidecar
image has a release tag and a digest.

---------

Co-authored-by: Léo <leograndcontact@gmail.com>
---
 ACKNOWLEDGMENTS.md                 |  4 ++--
 docker-compose.gpu-amd.yml         |  4 ++--
 docker-compose.gpu-nvidia.yml      |  4 ++--
 docker-compose.yml                 |  4 ++--
 tests/test_compose_sidecar_pins.py | 34 ++++++++++++++++++++++++++++++
 5 files changed, 42 insertions(+), 8 deletions(-)
 create mode 100644 tests/test_compose_sidecar_pins.py

diff --git a/ACKNOWLEDGMENTS.md b/ACKNOWLEDGMENTS.md
index 38e184764..294289b7f 100644
--- a/ACKNOWLEDGMENTS.md
+++ b/ACKNOWLEDGMENTS.md
@@ -48,8 +48,8 @@ just composed.
 | Service | Image | Purpose | License |
 |---|---|---|---|
 | [SearXNG](https://github.com/searxng/searxng) | `searxng/searxng:2026.9.25-12f8b6515` (pinned tag; see compose) | Default metasearch backend | AGPL-3.0 |
-| [ChromaDB](https://github.com/chroma-core/chroma) | `chromadb/chroma:latest` | Vector store for memory / RAG | Apache-2.0 |
-| [ntfy](https://github.com/binwiederhier/ntfy) | `binwiederhier/ntfy` | Push notifications (self-hosted reminders) | Apache-2.0 / GPL-2.0 |
+| [ChromaDB](https://github.com/chroma-core/chroma) | `chromadb/chroma:1.5.9` (pinned digest; see compose) | Vector store for memory / RAG | Apache-2.0 |
+| [ntfy](https://github.com/binwiederhier/ntfy) | `binwiederhier/ntfy:v2.32.0` (pinned digest; see compose) | Push notifications (self-hosted reminders) | Apache-2.0 / GPL-2.0 |
 
 ## Bundled front-end libraries
 
diff --git a/docker-compose.gpu-amd.yml b/docker-compose.gpu-amd.yml
index 0e2cdbcb8..5c85014d6 100644
--- a/docker-compose.gpu-amd.yml
+++ b/docker-compose.gpu-amd.yml
@@ -127,7 +127,7 @@ services:
       - ${RENDER_GID:-render}
 
   chromadb:
-    image: docker.io/chromadb/chroma:latest
+    image: docker.io/chromadb/chroma:1.5.9@sha256:1e0b73a187a28757c572acba508c46f48c9e8b0acaf5c20e6d95cdedce1acdf6
     ports:
       - "${CHROMADB_BIND:-127.0.0.1}:8100:8000"
     volumes:
@@ -196,7 +196,7 @@ services:
     restart: unless-stopped
 
   ntfy:
-    image: docker.io/binwiederhier/ntfy
+    image: docker.io/binwiederhier/ntfy:v2.32.0@sha256:59250e1d8be2ee2186c4560322f625faef22ace380331f05b63f8842dbd62602
     command: serve
     ports:
       - "${NTFY_BIND:-127.0.0.1}:8091:80"
diff --git a/docker-compose.gpu-nvidia.yml b/docker-compose.gpu-nvidia.yml
index 5d997f28b..5c628fcfb 100644
--- a/docker-compose.gpu-nvidia.yml
+++ b/docker-compose.gpu-nvidia.yml
@@ -130,7 +130,7 @@ services:
               capabilities: [gpu]
 
   chromadb:
-    image: docker.io/chromadb/chroma:latest
+    image: docker.io/chromadb/chroma:1.5.9@sha256:1e0b73a187a28757c572acba508c46f48c9e8b0acaf5c20e6d95cdedce1acdf6
     ports:
       - "${CHROMADB_BIND:-127.0.0.1}:8100:8000"
     volumes:
@@ -199,7 +199,7 @@ services:
     restart: unless-stopped
 
   ntfy:
-    image: docker.io/binwiederhier/ntfy
+    image: docker.io/binwiederhier/ntfy:v2.32.0@sha256:59250e1d8be2ee2186c4560322f625faef22ace380331f05b63f8842dbd62602
     command: serve
     ports:
       - "${NTFY_BIND:-127.0.0.1}:8091:80"
diff --git a/docker-compose.yml b/docker-compose.yml
index 808471520..2b90227a3 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -108,7 +108,7 @@ services:
     restart: unless-stopped
 
   chromadb:
-    image: docker.io/chromadb/chroma:latest
+    image: docker.io/chromadb/chroma:1.5.9@sha256:1e0b73a187a28757c572acba508c46f48c9e8b0acaf5c20e6d95cdedce1acdf6
     ports:
       - "${CHROMADB_BIND:-127.0.0.1}:8100:8000"
     volumes:
@@ -177,7 +177,7 @@ services:
     restart: unless-stopped
 
   ntfy:
-    image: docker.io/binwiederhier/ntfy
+    image: docker.io/binwiederhier/ntfy:v2.32.0@sha256:59250e1d8be2ee2186c4560322f625faef22ace380331f05b63f8842dbd62602
     command: serve
     ports:
       - "${NTFY_BIND:-127.0.0.1}:8091:80"
diff --git a/tests/test_compose_sidecar_pins.py b/tests/test_compose_sidecar_pins.py
new file mode 100644
index 000000000..6ba9cb901
--- /dev/null
+++ b/tests/test_compose_sidecar_pins.py
@@ -0,0 +1,34 @@
+"""Sidecar images must be pinned to a versioned tag and an immutable digest.
+
+A bare or ``:latest`` reference changes underneath an existing install on the
+next ``docker compose pull``/``up``, so two hosts on the same commit can run
+different ChromaDB or ntfy builds. The ``odysseus`` service is excluded: it is
+the project's own image, selected through ``ODYSSEUS_IMAGE``. The standalone
+GPU files are held equal to these services by test_gpu_compose_standalone.py.
+"""
+
+import re
+from pathlib import Path
+
+import pytest
+import yaml
+
+COMPOSE = Path(__file__).resolve().parents[1] / "docker-compose.yml"
+PINNED = re.compile(r"^[\w.\-/]+:(?P<tag>[\w.\-]+)@sha256:[0-9a-f]{64}$")
+
+
+def _sidecars():
+    services = yaml.safe_load(COMPOSE.read_text(encoding="utf-8"))["services"]
+    return {name: svc["image"] for name, svc in services.items() if name != "odysseus"}
+
+
+def test_expected_sidecars_present():
+    assert {"chromadb", "searxng", "ntfy"} <= set(_sidecars())
+
+
+@pytest.mark.parametrize("name", sorted(_sidecars()))
+def test_sidecar_image_has_version_tag_and_digest(name):
+    image = _sidecars()[name]
+    match = PINNED.match(image)
+    assert match, f"{name}: expected <repo>:<tag>@sha256:<digest>, got {image!r}"
+    assert match.group("tag") != "latest", f"{name}: pin a release tag, not latest"

From 9d0d3720f4ca181d87bef94da826d730acc6d483 Mon Sep 17 00:00:00 2001
From: RaresKeY <158580472+RaresKeY@users.noreply.github.com>
Date: Sun, 25 Oct 2026 12:45:49 +0000
Subject: [PATCH 49/53] fix(deps): require Pillow 13 with compatible FastEmbed
 (#6845)

---
 requirements.txt | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/requirements.txt b/requirements.txt
index 26dcdecb1..415b4b503 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -11,7 +11,8 @@ pydantic-settings>=2.14.1
 SQLAlchemy
 pypdf
 pypdfium2
-Pillow
+# Pillow 13 fixes known image-processing advisories; keep local embeddings compatible.
+Pillow>=13.0.0
 faster-whisper
 pdfplumber
 beautifulsoup4
@@ -25,7 +26,7 @@ numpy
 chromadb-client
 # gRPC vendors independent roots; 1.84.1 removes the incident trust anchors.
 grpcio>=1.84.1
-fastembed
+fastembed>=0.9.1
 youtube-transcript-api
 yt-dlp
 # Markdown rendering for research reports (src/visual_report.py).

From 1000b6582c747b0542ab71606d1de66c02953477 Mon Sep 17 00:00:00 2001
From: Grzegorz <gpudlowskidxr@gmail.com>
Date: Mon, 26 Oct 2026 16:46:52 +0100
Subject: [PATCH 50/53] fix(agent): give file tools the agent workspace as root
 when no workspace is set (#6722)

* fix(agent): give file tools the agent workspace as root when no workspace is set (#6679)

With no workspace bound, bash/python run in data/agent_workspace, but
RequestAuthority sealed no filesystem root, so every native file tool
failed with "requires a sealed resource root", and an approved
write_file failed with "no sealed resource identity". Seal the agent
workspace instead, and resolve relative paths in _resolve_tool_path
against it rather than the server's cwd.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* test: re-seal resource roots when a test swaps the authority owner (#6679)

A no-workspace authority now seals the agent workspace for its owner, so
replace(authority, owner="bob") copied alice's root and was rejected
before the approval-binding check the tests are about.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(agent): only seal a vetted agent workspace as the file-tool root (#6679)

Apply the agent_cwd() check before sealing data/agent_workspace: it must
be a real directory in the readable data subdirs, otherwise no root is
sealed. A symlinked workspace no longer redirects the file tools or the
bash/python launch scope. Tighten the dispatch test assertions to the
exact 'outside the sealed roots' message.

* refactor(agent): vet the no-workspace file root with default_agent_workspace (#6679)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
---
 src/agent_runtime/authority.py                | 20 +++--
 src/tool_execution.py                         |  4 +
 tests/test_agent_state_dir_confinement.py     | 84 ++++++++++++++++++-
 tests/test_browser_resource_identity.py       |  3 +-
 .../test_exact_approval_ungranted_process.py  |  1 -
 tests/test_remote_resource_identity.py        |  3 +-
 tests/test_tool_path_confinement.py           |  9 +-
 7 files changed, 109 insertions(+), 15 deletions(-)

diff --git a/src/agent_runtime/authority.py b/src/agent_runtime/authority.py
index cd5197300..541fac52f 100644
--- a/src/agent_runtime/authority.py
+++ b/src/agent_runtime/authority.py
@@ -7,6 +7,7 @@ from dataclasses import dataclass, replace
 from functools import wraps
 from inspect import signature
 import json
+import os
 from pathlib import Path
 import re
 from uuid import uuid4
@@ -140,11 +141,20 @@ class RequestAuthority:
             raise ValueError("Malformed request authority")
         if self.resource_roots is None:
             roots = ()
-            if self.workspace:
-                try:
-                    roots = (FilesystemRoot.seal(self.workspace, owner=self.owner),)
-                except (OSError, ValueError, RuntimeError):
-                    pass  # An unresolved workspace grants no filesystem root.
+            # With no workspace, bash/python run in the agent workspace
+            # (agent_cwd), so the file tools get that same root (#6679).
+            # Imported here: authority -> execution is a new edge, and
+            # tool_execution imports this module at load time.
+            from src import tool_execution
+            try:
+                root = self.workspace
+                if not root:
+                    # Vetted like agent_cwd(): a symlinked agent workspace
+                    # raises and so grants no root.
+                    root = tool_execution.default_agent_workspace()
+                roots = (FilesystemRoot.seal(root, owner=self.owner),)
+            except (OSError, ValueError, RuntimeError):
+                pass  # An unresolved workspace grants no filesystem root.
             object.__setattr__(self, "resource_roots", roots)
         if (not isinstance(self.resource_roots, tuple)
                 or any(not isinstance(r, FilesystemRoot) or (r.owner and r.owner != self.owner)
diff --git a/src/tool_execution.py b/src/tool_execution.py
index bde68df30..bc489b878 100644
--- a/src/tool_execution.py
+++ b/src/tool_execution.py
@@ -1068,6 +1068,10 @@ def _resolve_tool_path(raw_path: str) -> str:
     if raw_path is None or not str(raw_path).strip():
         raise ValueError("path is required")
     expanded = os.path.expanduser(str(raw_path).strip())
+    # Relative paths resolve where bash/python run (agent_cwd), not against
+    # the server's cwd, which is outside the allowed roots (#6679).
+    if not os.path.isabs(expanded):
+        expanded = os.path.join(_AGENT_WORKDIR, expanded)
     resolved = os.path.realpath(expanded)
 
     if _is_app_state_path(resolved):
diff --git a/tests/test_agent_state_dir_confinement.py b/tests/test_agent_state_dir_confinement.py
index 92d29206d..fc5d7ef14 100644
--- a/tests/test_agent_state_dir_confinement.py
+++ b/tests/test_agent_state_dir_confinement.py
@@ -123,12 +123,88 @@ def test_blocks_listing_the_data_directory_itself():
         _resolve_tool_path(DATA_DIR)
 
 
-def test_blocks_app_state_reached_by_relative_path(monkeypatch):
-    """The data directory is a relative hop from the checkout root, so
+def test_blocks_app_state_reached_by_relative_path(tmp_path, monkeypatch):
+    """The data directory is a relative hop from the agent workspace, so
     confinement cannot depend on the model supplying an absolute path."""
-    monkeypatch.chdir(os.path.dirname(DATA_DIR))
+    current_execution = importlib.import_module("src.tool_execution")
+    data_dir = tmp_path / "data"
+    data_dir.mkdir()
+    workspace = _configure_test_data_tree(monkeypatch, data_dir)["AGENT_WORKSPACE_DIR"]
+    workspace.mkdir()
+    monkeypatch.setattr(current_execution, "_AGENT_WORKDIR", str(workspace))
     with pytest.raises(ValueError, match="application state"):
-        _resolve_tool_path(os.path.join(os.path.basename(DATA_DIR), "sessions.json"))
+        current_execution._resolve_tool_path(os.path.join("..", "sessions.json"))
+
+
+def test_relative_path_resolves_in_agent_workspace_not_server_cwd(tmp_path, monkeypatch):
+    """With no workspace bound, bash runs in the agent workspace, so a
+    relative write_file/read_file path must land there too (#6679), not in
+    the server's cwd, which is outside the allowed roots."""
+    current_execution = importlib.import_module("src.tool_execution")
+    data_dir = tmp_path / "data"
+    data_dir.mkdir()
+    workspace = _configure_test_data_tree(monkeypatch, data_dir)["AGENT_WORKSPACE_DIR"]
+    workspace.mkdir()
+    monkeypatch.setattr(current_execution, "_AGENT_WORKDIR", str(workspace))
+    server_cwd = tmp_path / "checkout"
+    server_cwd.mkdir()
+    monkeypatch.chdir(server_cwd)
+    token = current_execution._active_workspace.set(None)
+    try:
+        assert current_execution._resolve_tool_path("test.txt") == os.path.join(
+            os.path.realpath(workspace), "test.txt"
+        )
+        assert current_execution._resolve_search_root("sub") == os.path.join(
+            os.path.realpath(workspace), "sub"
+        )
+    finally:
+        current_execution._active_workspace.reset(token)
+
+
+def test_request_without_workspace_seals_the_agent_workspace(tmp_path, monkeypatch):
+    """With no workspace, the native file tools get the folder bash/python
+    already run in (#6679) instead of no root at all, and a relative path
+    lands there while app state next to it stays out of reach."""
+    from src.agent_runtime.authority import ExactOperation, OperationGrant, RequestAuthority
+    from src.agent_runtime.resource_binding import resolve_filesystem_operation
+    current_execution = importlib.import_module("src.tool_execution")
+    data_dir = tmp_path / "data"
+    data_dir.mkdir()
+    workspace = _configure_test_data_tree(monkeypatch, data_dir)["AGENT_WORKSPACE_DIR"]
+    workspace.mkdir()
+    (data_dir / "sessions.json").write_text("{}", encoding="utf-8")
+    monkeypatch.setattr(current_execution, "_AGENT_WORKDIR", str(workspace))
+
+    authority = RequestAuthority("request", "alice", "s", "", (OperationGrant("write_file"),))
+    assert [r.path for r in authority.resource_roots] == [os.path.realpath(workspace)]
+
+    bound = resolve_filesystem_operation(
+        ExactOperation.normalize("write_file", "test.txt\nhello"), roots=authority.resource_roots)
+    assert bound.bindings[0].resource.path == os.path.join(os.path.realpath(workspace), "test.txt")
+    with pytest.raises(ValueError, match="outside the sealed roots"):
+        resolve_filesystem_operation(
+            ExactOperation.normalize("read_file", "../sessions.json"), roots=authority.resource_roots)
+
+
+def test_symlinked_agent_workspace_is_not_sealed(tmp_path, monkeypatch):
+    """A symlinked agent workspace must not become the file-tool root:
+    agent_cwd() and create_directories() refuse the same layout."""
+    from src.agent_runtime.authority import OperationGrant, RequestAuthority
+    current_execution = importlib.import_module("src.tool_execution")
+    data_dir = tmp_path / "data"
+    data_dir.mkdir()
+    workspace = _configure_test_data_tree(monkeypatch, data_dir)["AGENT_WORKSPACE_DIR"]
+    elsewhere = tmp_path / "elsewhere"
+    elsewhere.mkdir()
+    (elsewhere / "notes.txt").write_text("private", encoding="utf-8")
+    try:
+        workspace.symlink_to(elsewhere, target_is_directory=True)
+    except OSError:
+        pytest.skip("cannot create symlink")
+    monkeypatch.setattr(current_execution, "_AGENT_WORKDIR", str(workspace))
+
+    authority = RequestAuthority("request", "alice", "s", "", (OperationGrant("read_file"),))
+    assert authority.resource_roots == ()
 
 
 def test_blocks_app_state_reached_through_a_symlink(tmp_path):
diff --git a/tests/test_browser_resource_identity.py b/tests/test_browser_resource_identity.py
index f17452707..e4f11aa37 100644
--- a/tests/test_browser_resource_identity.py
+++ b/tests/test_browser_resource_identity.py
@@ -281,7 +281,8 @@ async def test_browser_approval_application_binding_is_exact(producer, field, va
     original = authority()
     content = '{"action":"session_info"}'
     approval = approval_for(original, "private_browser", content)
-    changed = replace(original, **{field: value}, browser_sessions=(), browser_pages=())
+    # resource_roots=None re-seals the root for the changed owner.
+    changed = replace(original, **{field: value}, browser_sessions=(), browser_pages=(), resource_roots=None)
     _, result = await dispatch(changed, "private_browser", content, approval)
     assert result["exit_code"] == 1 and not approval._claimed
 
diff --git a/tests/test_exact_approval_ungranted_process.py b/tests/test_exact_approval_ungranted_process.py
index 15064178f..af730af7e 100644
--- a/tests/test_exact_approval_ungranted_process.py
+++ b/tests/test_exact_approval_ungranted_process.py
@@ -93,7 +93,6 @@ def test_approval_without_a_workspace_seals_a_launch_in_the_agent_workspace(agen
     # Agent mode with no folder picked is the default. bash already runs in the
     # agent workspace there (agent_cwd), so that is where its approval seals.
     authority = _authority("", "get_workspace")
-    assert authority.resource_roots == ()
 
     pending, _ = _approve(authority, "bash", "pwd")
 
diff --git a/tests/test_remote_resource_identity.py b/tests/test_remote_resource_identity.py
index 885059ad5..a92bc7eb2 100644
--- a/tests/test_remote_resource_identity.py
+++ b/tests/test_remote_resource_identity.py
@@ -117,7 +117,8 @@ async def test_remote_approval_is_bound_to_operation_and_request(manager, change
         content = '{"record":"two"}'
     else:
         authority = replace(authority, **{"request": {"request_id": "other"}, "owner": {"owner": "bob"},
-                                         "session": {"session_id": "other"}}[change])
+                                         "session": {"session_id": "other"}}[change],
+                            resource_roots=None)  # re-seal the root for the changed owner
     _, result = await dispatch(authority, tool, content, exact_approval=exact,
         security_context=ToolRunSecurityContext(external_untrusted_context_seen=True))
     assert result["exit_code"] == 1
diff --git a/tests/test_tool_path_confinement.py b/tests/test_tool_path_confinement.py
index ad172c10a..4d9b2261a 100644
--- a/tests/test_tool_path_confinement.py
+++ b/tests/test_tool_path_confinement.py
@@ -255,7 +255,8 @@ async def test_read_file_dispatch_blocks_etc_shadow(monkeypatch):
         security_context=NO_TOOL_SECURITY_CONTEXT,
     )
     assert result.get("failure_kind") == "resource_identity_denied"
-    assert "sealed resource root" in (result.get("error") or "")
+    assert "outside the sealed roots" in (result.get("error") or "")
+    assert result.get("blocked") is True
     assert result.get("exit_code") == 1
 
 
@@ -285,7 +286,8 @@ async def test_write_file_dispatch_blocks_authorized_keys(monkeypatch):
         security_context=NO_TOOL_SECURITY_CONTEXT,
     )
     assert result.get("failure_kind") == "resource_identity_denied"
-    assert "sealed resource root" in (result.get("error") or "")
+    assert "outside the sealed roots" in (result.get("error") or "")
+    assert result.get("blocked") is True
     assert result.get("exit_code") == 1
 
 
@@ -349,7 +351,8 @@ async def test_write_file_dispatch_blocks_cron(monkeypatch):
         security_context=NO_TOOL_SECURITY_CONTEXT,
     )
     assert result.get("failure_kind") == "resource_identity_denied"
-    assert "sealed resource root" in (result.get("error") or "")
+    assert "outside the sealed roots" in (result.get("error") or "")
+    assert result.get("blocked") is True
     assert result.get("exit_code") == 1
 @pytest.mark.parametrize("filename", ["auth.json", "app.db", "settings.json"])
 def test_application_secrets_are_sensitive_paths(filename):

From be9f575b590ea61f3a686060e7cfc91a8db3c61a Mon Sep 17 00:00:00 2001
From: Afonso Coutinho <afonso@yack.com.br>
Date: Mon, 26 Oct 2026 15:46:57 +0000
Subject: [PATCH 51/53] fix(security): block read-only cookbook tools for
 non-admin owners (#6353)

* fix(security): block read-only cookbook tools for non-admin owners

list_cached_models, list_served_models, tail_serve_output, list_downloads,
search_hf_models, list_serve_presets and list_cookbook_servers were in the
plan-mode read-only allowlist but in neither NON_ADMIN_BLOCKED_TOOLS nor the
dispatcher's _ADMIN_TOOLS. Each implementation calls a require_admin route
over the internal loopback with the process-wide INTERNAL_TOOL_TOKEN and
never checks the owner, so a non-admin user's agent inherited admin reach
through them. list_cached_models is the worst case: a caller-chosen `host`
is forwarded to /api/model/cached, which SSHes to that host with the app
user's keys and walks caller-chosen model_dirs. THREAT_MODEL.md lists model
serving as admin-only, so gate the read side the same way as serve/download.

Adding the names to NON_ADMIN_BLOCKED_TOOLS also hides them from non-admin
tool schemas and caps bearer-token agent runs; _ADMIN_TOOLS blocks them at
dispatch. Regression test covers both lists, schema hiding, and that the
loopback is never reached for a non-admin owner.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TwcwfY2uQMxNRsK3y6xBAp

* fix(cookbook): bind request authority in admin gate regressions

Keep all seven read-only Cookbook tools in the admin prompt inventory. Grant request authority in dispatch tests so the admin gate itself is exercised, and verify administrators still reach each handler. Validation: 359 focused authorization, tool-policy and schema tests passed. Against the running app with real auth accounts, all seven tools reject a non-admin and an admin reaches the authenticated Cookbook HTTP API.

---------

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
Co-authored-by: Afonso Junior <chatgpt@yack.com.br>
---
 src/agent_loop.py                             |   2 +-
 src/tool_execution.py                         |  10 ++
 src/tool_security.py                          |  16 +++
 ...test_cookbook_readonly_tools_admin_gate.py | 136 ++++++++++++++++++
 4 files changed, 163 insertions(+), 1 deletion(-)
 create mode 100644 tests/test_cookbook_readonly_tools_admin_gate.py

diff --git a/src/agent_loop.py b/src/agent_loop.py
index c452c6c22..257cc441d 100644
--- a/src/agent_loop.py
+++ b/src/agent_loop.py
@@ -15204,7 +15204,7 @@ _ADMIN_TOOLS = {
     "manage_documents", "manage_settings", "create_session", "list_sessions",
     "send_to_session", "search_chats", "pipeline", "ask_teacher", "list_models",
     "list_cached_models", "list_downloads", "list_cookbook_servers",
-    "list_serve_presets", "list_served_models",
+    "list_serve_presets", "list_served_models", "tail_serve_output", "search_hf_models",
 }
 
 def _build_base_prompt(
diff --git a/src/tool_execution.py b/src/tool_execution.py
index bc489b878..fd6dcfbbd 100644
--- a/src/tool_execution.py
+++ b/src/tool_execution.py
@@ -1288,6 +1288,16 @@ _ADMIN_TOOLS = {
     "serve_preset",
     "stop_served_model",
     "cancel_download",
+    # Read-only Cookbook tools reach require_admin routes over the internal
+    # loopback without an owner check (see NON_ADMIN_BLOCKED_TOOLS in
+    # src/tool_security.py), so they are admin-only at dispatch as well.
+    "list_served_models",
+    "tail_serve_output",
+    "list_downloads",
+    "search_hf_models",
+    "list_cached_models",
+    "list_serve_presets",
+    "list_cookbook_servers",
 }
 
 
diff --git a/src/tool_security.py b/src/tool_security.py
index f754a6356..418b1a54b 100644
--- a/src/tool_security.py
+++ b/src/tool_security.py
@@ -79,6 +79,22 @@ NON_ADMIN_BLOCKED_TOOLS = BUILTIN_EMAIL_TOOLS | {
     "stop_served_model",
     "cancel_download",
     "adopt_served_model",
+    # Read-only Cookbook inspection tools. They look harmless, but every one
+    # of them calls a require_admin route over the internal loopback with the
+    # process-wide INTERNAL_TOOL_TOKEN and never checks the session owner, so
+    # a non-admin agent would inherit admin reach through them:
+    # list_cached_models forwards a caller-chosen `host` into
+    # /api/model/cached, which SSHes to that host with the app user's keys and
+    # walks caller-chosen `model_dir`s; list_served_models / tail_serve_output
+    # expose serve/download logs and running process command lines. Model
+    # serving is admin-only in THREAT_MODEL.md, so block the read side too.
+    "list_served_models",
+    "tail_serve_output",
+    "list_downloads",
+    "search_hf_models",
+    "list_cached_models",
+    "list_serve_presets",
+    "list_cookbook_servers",
 }
 
 
diff --git a/tests/test_cookbook_readonly_tools_admin_gate.py b/tests/test_cookbook_readonly_tools_admin_gate.py
new file mode 100644
index 000000000..2e683aa6f
--- /dev/null
+++ b/tests/test_cookbook_readonly_tools_admin_gate.py
@@ -0,0 +1,136 @@
+"""Read-only Cookbook tools must be admin-only for the agent.
+
+Regression: `list_cached_models`, `list_served_models`, `tail_serve_output`,
+`list_downloads`, `search_hf_models`, `list_serve_presets` and
+`list_cookbook_servers` sat in the plan-mode read-only allowlist but not in
+NON_ADMIN_BLOCKED_TOOLS or the dispatcher's _ADMIN_TOOLS. Their
+implementations call require_admin routes over the internal loopback with the
+process-wide INTERNAL_TOOL_TOKEN and never look at the owner, so a non-admin
+user's agent could reach admin capability through them. The worst case is
+`list_cached_models`: a caller-chosen `host` is forwarded to
+/api/model/cached, which SSHes to that host with the app user's keys and
+walks caller-chosen `model_dir`s. THREAT_MODEL.md lists model serving as
+admin-only, so the read side has to be gated the same way as serve/download.
+"""
+
+import sys
+import types
+from types import SimpleNamespace
+from unittest.mock import AsyncMock
+
+import pytest
+
+from src.tool_security import (
+    NON_ADMIN_BLOCKED_TOOLS,
+    blocked_tools_for_owner,
+    delegated_credential_blocked_tools,
+)
+from src.tool_execution import _ADMIN_TOOLS
+from src.agent_runtime.authority import OperationGrant, RequestAuthority
+
+READONLY_COOKBOOK_TOOLS = (
+    "list_cached_models",
+    "list_served_models",
+    "tail_serve_output",
+    "list_downloads",
+    "search_hf_models",
+    "list_serve_presets",
+    "list_cookbook_servers",
+)
+
+
+def _install_core_auth_stub(monkeypatch, *, is_admin: bool):
+    """Narrow auth surface: AUTH enabled, configured, owner admin or not."""
+    core_mod = types.ModuleType("core")
+    core_mod.__path__ = []
+    auth_mod = types.ModuleType("core.auth")
+
+    class FakeAuth:
+        is_configured = True
+
+        def is_admin(self, username):
+            return is_admin
+
+    auth_mod.AuthManager = lambda: FakeAuth()
+    core_mod.auth = auth_mod
+    monkeypatch.setitem(sys.modules, "core", core_mod)
+    monkeypatch.setitem(sys.modules, "core.auth", auth_mod)
+    monkeypatch.setattr("src.auth_helpers._auth_disabled", lambda: False)
+    return auth_mod
+
+
+def test_readonly_cookbook_tools_are_in_every_admin_gate():
+    from src.agent_loop import _ADMIN_TOOLS as prompt_admin_tools
+
+    # Spelled out (not imported from a shared tuple in src/) so dropping one
+    # from either set fails here instead of silently reopening the hole.
+    for tool in READONLY_COOKBOOK_TOOLS:
+        assert tool in NON_ADMIN_BLOCKED_TOOLS, tool
+        assert tool in _ADMIN_TOOLS, tool
+        assert tool in prompt_admin_tools, tool
+
+
+def test_readonly_cookbook_tools_hidden_from_non_admin_and_bearer_runs(monkeypatch):
+    _install_core_auth_stub(monkeypatch, is_admin=False)
+    hidden = blocked_tools_for_owner("regular-user")
+    for tool in READONLY_COOKBOOK_TOOLS:
+        assert tool in hidden, tool
+        assert tool in delegated_credential_blocked_tools(), tool
+
+
+def test_admin_owner_keeps_readonly_cookbook_tools(monkeypatch):
+    _install_core_auth_stub(monkeypatch, is_admin=True)
+    assert blocked_tools_for_owner("admin-user") == set()
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("tool_name", READONLY_COOKBOOK_TOOLS)
+async def test_non_admin_agent_cannot_execute_readonly_cookbook_tools(monkeypatch, tool_name):
+    _install_core_auth_stub(monkeypatch, is_admin=False)
+    from src.tool_execution import NO_TOOL_SECURITY_CONTEXT, execute_tool_block
+
+    # The loopback must never be touched: if the gate fails, the tool would
+    # hit a require_admin route with the internal token.
+    import httpx
+
+    def _boom(*args, **kwargs):
+        raise AssertionError(f"{tool_name} reached the internal loopback for a non-admin owner")
+
+    monkeypatch.setattr(httpx, "AsyncClient", _boom)
+    monkeypatch.setattr(httpx, "get", _boom)
+    monkeypatch.setattr(httpx, "post", _boom)
+
+    payload = '{"host": "root@10.0.0.5", "ssh_port": "22", "model_dir": "/root,/etc"}'
+    desc, result = await execute_tool_block(
+        SimpleNamespace(tool_type=tool_name, content=payload),
+        owner="regular-user",
+        security_context=NO_TOOL_SECURITY_CONTEXT,
+        request_authority=RequestAuthority(
+            "cookbook-test", "regular-user", "", "", (OperationGrant(tool_name),)
+        ),
+    )
+    assert desc == f"{tool_name}: BLOCKED"
+    assert result["exit_code"] == 1
+    assert "admin" in result["error"]
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("tool_name", READONLY_COOKBOOK_TOOLS)
+async def test_admin_agent_can_dispatch_readonly_cookbook_tools(monkeypatch, tool_name):
+    from src import tool_implementations
+    from src.tool_execution import NO_TOOL_SECURITY_CONTEXT, execute_tool_block
+
+    _install_core_auth_stub(monkeypatch, is_admin=True)
+    handler = AsyncMock(return_value={"output": "Cookbook result", "exit_code": 0})
+    monkeypatch.setattr(tool_implementations, f"do_{tool_name}", handler)
+    desc, result = await execute_tool_block(
+        SimpleNamespace(tool_type=tool_name, content="{}"),
+        owner="admin-user",
+        security_context=NO_TOOL_SECURITY_CONTEXT,
+        request_authority=RequestAuthority(
+            "cookbook-test", "admin-user", "", "", (OperationGrant(tool_name),)
+        ),
+    )
+    assert desc == tool_name
+    assert result["exit_code"] == 0
+    handler.assert_awaited_once_with("{}", owner="admin-user")

From 4d0610a1eb470460c59b091b34dbe649a8084c49 Mon Sep 17 00:00:00 2001
From: Afonso Coutinho <afonso@yack.com.br>
Date: Mon, 26 Oct 2026 15:47:03 +0000
Subject: [PATCH 52/53] fix(email): guard user-supplied IMAP/SMTP hosts against
 SSRF (#6355)

* fix(email): guard user-supplied IMAP/SMTP hosts against SSRF

POST /api/email/accounts/test opened raw imaplib/smtplib connections to
whatever host:port the request body named, and POST/PUT /api/email/accounts
and PUT /api/email/config persisted arbitrary hosts for the background
pollers to contact. All of these sit behind require_user/require_owner with
no admin gate, so any authenticated user could make the server connect to
loopback, LAN and cloud-metadata targets (169.254.169.254) and read the
first 200 characters of the remote banner back out of the friendly error.
THREAT_MODEL.md lists email as admin-only; the tool layer honours that but
the HTTP routes did not.

Add check_outbound_host() to src/url_safety.py, a bare-host companion to
check_outbound_url() with the same classification (link-local, multicast,
reserved and unspecified always rejected; private/loopback only with
block_private) plus localhost-name handling and an explicit policy for names
that do not resolve. Wire it into the four email routes via
_check_mail_host(): non-admin owners (and everyone when
EMAIL_BLOCK_PRIVATE_IPS=true) also lose private/loopback targets, admins
keep the local-first LAN/Dovecot setups. Unresolvable names pass through
because the connect that follows fails with the same DNS error.

Regression tests cover the helper's policy table and each route: the test
route rejects before any socket opens, save routes reject before touching
the DB, admins keep loopback unless locked down, and an update that fails
validation leaves the stored row untouched.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TwcwfY2uQMxNRsK3y6xBAp

* fix(email): harden IMAP/SMTP SSRF protection against rebinding, TOCTOU, and unvetted hosts

- P0: Implement safe_create_connection() in src/url_safety.py to resolve hostnames once, validate every returned address against SSRF policy, and connect directly to the pinned IP. This eliminates DNS rebinding and TOCTOU while preserving TLS SNI and certificate hostname verification across IMAP, IMAPS, STARTTLS, SMTP, and SMTP_SSL.
- P1: Ensure unresolvable or deferred hostnames cannot become an unrestricted future connection capability by enforcing runtime SSRF validation fail-closed on every connection, while maintaining compatibility with offline configurations.
- P2: Extend SSRF enforcement to the core connection layer (_open_imap_connection, _send_smtp_message, _imap_connect) using ContextVar owner scoping, protecting pre-existing DB rows, restored configs, background pollers, and scheduled operations.
- P3: Allow admin and single-user access to IPv6 loopback (::1, [::1]) for local mail servers (e.g. Dovecot) by checking loopback before is_reserved, while keeping link-local, cloud metadata (169.254.169.254, 100.100.100.200), and non-admin restrictions strictly enforced.
- Add comprehensive regression and adversarial test coverage in tests/test_email_account_host_ssrf.py.

* fix(email): reject unresolved saved hosts without stdlib monkeypatches

Use the existing explicit policy IMAP/SMTP classes and canonical connect_outbound_tcp helper. Remove process-wide stdlib assignments, context-variable plumbing, redundant aliases and resolver-signature retries. Reject unsafe or unresolved hosts before account/config persistence, keep DNS work off the event loop, return fixed client errors, identify Alibaba metadata accurately and reject invalid TCP ports. Validation: 654 relevant email, URL-safety and CodeQL regression tests passed, 3 skipped. Three unrelated browser checks were excluded after environment failures (missing Playwright browser and Chromium timeout). Running-app checks verified rejected create/update/config requests leave stored data unchanged, administrator LAN configuration still works, and metadata/non-admin loopback are blocked.

---------

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
Co-authored-by: PR #6029 Reviewer <reviewer@odysseus-review.local>
Co-authored-by: Afonso Junior <chatgpt@yack.com.br>
---
 routes/email/email_routes.py          |  27 ++
 src/url_safety.py                     |  66 ++++
 tests/test_email_account_host_ssrf.py | 515 ++++++++++++++++++++++++++
 3 files changed, 608 insertions(+)
 create mode 100644 tests/test_email_account_host_ssrf.py

diff --git a/routes/email/email_routes.py b/routes/email/email_routes.py
index 81173f889..b8329eef2 100644
--- a/routes/email/email_routes.py
+++ b/routes/email/email_routes.py
@@ -87,6 +87,17 @@ _SERVER_OWNED_OAUTH_FIELDS = {
 _CACHE_HOOKS: dict = {"invalidate_list": None}
 
 
+def _check_mail_host(host, owner: str, label: str) -> str | None:
+    """Reject unsafe or unresolved mail hosts before saving or testing them."""
+    from src.url_safety import check_outbound_host
+    ok, reason = check_outbound_host(host, block_private=_mail_private_blocked(owner))
+    if ok:
+        return None
+    logger.warning("Rejected %s mail host for owner=%r: %s", label, owner, reason)
+    # Resolver and exception details belong in server logs, never the response.
+    return f"Rejected {label} host: server address is not allowed or does not resolve"
+
+
 def _normalized_mail_host(value) -> str:
     """Normalize a mail hostname for exact provider-bound comparisons."""
     return str(value or "").strip().lower().rstrip(".")
@@ -7139,6 +7150,12 @@ def setup_email_routes():
         if account_id:
             _assert_owns_account(account_id, owner)
 
+        for field, label in (("imap_host", "IMAP"), ("smtp_host", "SMTP")):
+            if data.get(field):
+                host_error = await run_in_threadpool(_check_mail_host, data[field], owner, label)
+                if host_error:
+                    return {"ok": False, "error": host_error}
+
         # Non-reply automation flags stay global. Away/auto-reply settings are
         # account-scoped when an account_id is supplied by the Email Settings UI.
         settings = _load_settings()
@@ -7279,6 +7296,11 @@ def setup_email_routes():
         smtp_port, port_err = _coerce_port(data.get("smtp_port"), 465)
         if port_err:
             return {"ok": False, "error": port_err}
+        for field, label in (("imap_host", "IMAP"), ("smtp_host", "SMTP")):
+            if data.get(field):
+                host_error = await run_in_threadpool(_check_mail_host, data[field], owner, label)
+                if host_error:
+                    return {"ok": False, "error": host_error}
         db = SessionLocal()
         try:
             _lock_email_account_owner_mutation(db, owner)
@@ -7324,6 +7346,11 @@ def setup_email_routes():
         """Update an email account. Passwords only overwrite if non-empty."""
         # Path param account_id — dep validated via Query, re-check the path-param value.
         _assert_owns_account(account_id, owner)
+        for field, label in (("imap_host", "IMAP"), ("smtp_host", "SMTP")):
+            if data.get(field):
+                host_error = await run_in_threadpool(_check_mail_host, data[field], owner, label)
+                if host_error:
+                    return {"ok": False, "error": host_error}
         from core.database import SessionLocal, EmailAccount
         db = SessionLocal()
         try:
diff --git a/src/url_safety.py b/src/url_safety.py
index 74d6334db..a8088f692 100644
--- a/src/url_safety.py
+++ b/src/url_safety.py
@@ -57,6 +57,10 @@ _SHARED_ADDRESS_SPACE_V4 = ipaddress.ip_network("100.64.0.0/10")
 # membership test excludes and which stays rejected as reserved.
 _NAT64_WELL_KNOWN_PREFIX_V6 = ipaddress.ip_network("64:ff9b::/96")
 
+_LOCALHOST_NAMES = frozenset({"localhost", "localhost.localdomain", "ip6-localhost", "ip6-loopback"})
+# Alibaba's metadata endpoint is shared address space, not link-local.
+_METADATA_IPS = {ipaddress.ip_address("100.100.100.200")}
+
 
 def _nat64_well_known_embedded_ipv4(
     ip: ipaddress._BaseAddress,
@@ -92,6 +96,8 @@ def _classify(ip: ipaddress._BaseAddress, *, block_private: bool) -> Optional[st
             if reason:
                 return f"NAT64 translated destination blocked: {reason}"
             return None
+    if ip in _METADATA_IPS:
+        return f"metadata endpoint blocked: {ip}"
     if ip.is_link_local:
         return f"link-local address blocked (SSRF metadata risk): {ip}"
     # IPv6 loopback is also reserved; its policy must match IPv4 loopback.
@@ -161,6 +167,58 @@ def check_outbound_url(
 
 
 
+def check_outbound_host(
+    host: str,
+    *,
+    block_private: bool = False,
+    resolver: Optional[Callable[[str], List[str]]] = None,
+) -> Tuple[bool, str]:
+    """Validate a bare mail hostname/IP, rejecting unresolved destinations.
+
+    Saving an unresolvable hostname is unsafe: another consumer of the stored
+    configuration may later connect after its DNS records change. Live mail
+    connections separately pin their sockets with connect_outbound_tcp.
+    """
+    if not isinstance(host, str):
+        return False, "host must be a string"
+    host = host.strip()
+    if not host:
+        return False, "host is required"
+    if any(ch.isspace() for ch in host) or any(ch in host for ch in "/\\@?#"):
+        return False, "host must be a bare hostname or IP address"
+    literal = host[1:-1] if host.startswith("[") and host.endswith("]") else host
+    try:
+        ip = ipaddress.ip_address(literal.split("%")[0])
+    except ValueError:
+        if ":" in literal:
+            return False, "host must be a bare hostname or IP address"
+    else:
+        reason = _classify(ip, block_private=block_private)
+        return (False, reason) if reason else (True, "ok")
+    name = host.lower().rstrip(".")
+    if name in _LOCALHOST_NAMES or name.endswith(".localhost"):
+        if block_private:
+            return False, f"private/shared/loopback address blocked: {host}"
+        return True, "ok"
+    try:
+        ips = (resolver or _default_resolver)(host)
+        if not ips:
+            return False, "host does not resolve to an IP"
+        saw_ip = False
+        for raw in ips:
+            # Malformed answers fail closed, including mixed valid/invalid ones.
+            ip = ipaddress.ip_address(raw.split("%")[0])
+            saw_ip = True
+            reason = _classify(ip, block_private=block_private)
+            if reason:
+                return False, reason
+    except Exception as exc:
+        return False, f"host does not resolve to valid IP addresses: {exc}"
+    if not saw_ip:
+        return False, "host does not resolve to an IP"
+    return True, "ok"
+
+
 class OutboundAddressBlocked(PermissionError):
     """A non-HTTP outbound host resolves into a disallowed address range."""
 
@@ -183,7 +241,15 @@ def connect_outbound_tcp(
     a rebinding name pass the check with a public answer and then connect to
     metadata/private space. TLS callers keep wrapping the returned socket with
     ``server_hostname=host``, so SNI and certificate checks are unchanged.
+
+    An injected resolver must implement socket.getaddrinfo's argument and
+    result contract. Resolver errors propagate without an unvetted retry.
     """
+    if isinstance(port, bool) or not isinstance(port, (int, str)):
+        raise ValueError("port must be an integer between 1 and 65535")
+    port = int(port)
+    if not 1 <= port <= 65535:
+        raise ValueError("port must be an integer between 1 and 65535")
     resolve = resolver or socket.getaddrinfo
     infos = resolve(host, port, 0, socket.SOCK_STREAM)
     for _family, _type, _proto, _canon, sockaddr in infos:
diff --git a/tests/test_email_account_host_ssrf.py b/tests/test_email_account_host_ssrf.py
new file mode 100644
index 000000000..9522781b5
--- /dev/null
+++ b/tests/test_email_account_host_ssrf.py
@@ -0,0 +1,515 @@
+"""User-supplied IMAP/SMTP hosts must pass the outbound host guard.
+
+Regression: POST /api/email/accounts/test opened raw ``imaplib`` / ``smtplib``
+connections to whatever host:port the caller supplied, and the account save
+routes persisted arbitrary hosts for the background pollers to contact. Both
+are reachable by any authenticated user (``require_user`` / ``require_owner``,
+no admin gate), so a non-admin could port-scan loopback, the LAN and the cloud
+metadata range through the server and read the first 200 chars of the banner
+back out of the error message. THREAT_MODEL.md lists email as admin-only.
+
+Policy (see routes/email_routes.py:_check_mail_host): link-local (metadata),
+multicast, reserved and unspecified targets are always rejected; loopback and
+private ranges are rejected for non-admin owners or when
+EMAIL_BLOCK_PRIVATE_IPS=true, and stay allowed for admins (local-first: a LAN
+Dovecot is a normal setup). Unresolved names are rejected before persistence;
+live connections also validate and pin their own resolved addresses.
+"""
+
+import socket
+import unittest.mock as mock
+
+import pytest
+
+from src.url_safety import check_outbound_host, connect_outbound_tcp, OutboundAddressBlocked
+
+
+# ── helper policy table ──────────────────────────────────────────────────────
+
+@pytest.mark.parametrize("host", [
+    "169.254.169.254",
+    "[::ffff:169.254.169.254]",
+    "::ffff:169.254.169.254",
+    "fe80::1",
+    "0.0.0.0",
+    "224.0.0.1",
+    "100.100.100.200",
+    "[100.100.100.200]",
+])
+def test_always_blocked_addresses(host):
+    ok, reason = check_outbound_host(host)
+    assert ok is False, (host, reason)
+    ok, reason = check_outbound_host(host, block_private=False)
+    assert ok is False
+
+
+@pytest.mark.parametrize("host", [
+    "127.0.0.1",
+    "::1",
+    "[::1]",
+    "10.0.0.5",
+    "192.168.1.10",
+    "100.64.1.1",
+    "localhost",
+    "LOCALHOST.",
+    "mail.localhost",
+    "ip6-localhost",
+])
+def test_private_and_loopback_gated_by_block_private(host):
+    ok, _ = check_outbound_host(host, block_private=True)
+    assert ok is False, host
+    ok, _ = check_outbound_host(host, block_private=False)
+    assert ok is True, host
+
+
+@pytest.mark.parametrize("host", ["host:993", "http://mail.example.com", "user@mail.example.com", "mail.example.com/", "a b", "", "   "])
+def test_non_bare_hosts_rejected(host):
+    ok, _ = check_outbound_host(host, resolver=lambda h: ["93.184.216.34"])
+    assert ok is False, host
+
+
+def test_nonstring_rejected():
+    assert check_outbound_host(None)[0] is False  # type: ignore[arg-type]
+    assert check_outbound_host(123)[0] is False  # type: ignore[arg-type]
+
+
+def test_resolved_name_is_classified():
+    ok, reason = check_outbound_host("metadata.google.internal", resolver=lambda h: ["169.254.169.254"])
+    assert ok is False and "link-local" in reason
+    ok, _ = check_outbound_host("mail.corp", block_private=True, resolver=lambda h: ["10.1.2.3"])
+    assert ok is False
+    ok, _ = check_outbound_host("mail.corp", block_private=False, resolver=lambda h: ["10.1.2.3"])
+    assert ok is True
+    ok, _ = check_outbound_host("imap.example.org", block_private=True, resolver=lambda h: ["93.184.216.34"])
+    assert ok is True
+
+
+def test_unresolved_policy():
+    def _nx(h):
+        raise OSError("Name or service not known")
+    assert check_outbound_host("nope.invalid", resolver=_nx)[0] is False
+    assert check_outbound_host("nope.invalid", resolver=lambda h: [])[0] is False
+
+
+# ── route wiring ─────────────────────────────────────────────────────────────
+
+def _route(router, path, method):
+    for r in router.routes:
+        if r.path == path and method in getattr(r, "methods", set()):
+            return r.endpoint
+    raise AssertionError(f"route not found: {method} {path}")
+
+
+def _make_orm_db():
+    from sqlalchemy import create_engine
+    from sqlalchemy.orm import sessionmaker
+    from core.database import Base
+    engine = create_engine("sqlite:///:memory:", connect_args={"check_same_thread": False})
+    Base.metadata.create_all(engine)
+    Factory = sessionmaker(bind=engine)
+    return Factory
+
+
+def _set_admin(monkeypatch, is_admin: bool):
+    monkeypatch.setattr("src.tool_security.owner_is_admin_or_single_user", lambda owner: is_admin)
+    monkeypatch.delenv("EMAIL_BLOCK_PRIVATE_IPS", raising=False)
+    monkeypatch.delenv("EMAIL_ALLOW_PRIVATE_IPS", raising=False)
+
+
+class _Req:
+    def __init__(self, body):
+        self._body = body
+
+    async def json(self):
+        return self._body
+
+
+@pytest.mark.asyncio
+async def test_test_connection_rejects_loopback_for_non_admin_before_any_socket(monkeypatch):
+    import routes.email_routes as email_routes
+    _set_admin(monkeypatch, False)
+    router = email_routes.setup_email_routes()
+    test_conn = _route(router, "/api/email/accounts/test", "POST")
+
+    body = {
+        "imap_host": "127.0.0.1", "imap_port": 11434, "imap_user": "x", "imap_password": "x",
+        "imap_starttls": False,
+        "smtp_host": "169.254.169.254", "smtp_port": 80, "smtp_security": "none",
+    }
+    with mock.patch("socket.socket") as create_socket:
+        result = await test_conn(req=_Req(body), owner="regular-user")
+
+    assert result["ok"] is False
+    assert ("Rejected IMAP host" in result["imap"]["error"] or "server address is not allowed" in result["imap"]["error"])
+    assert ("Rejected SMTP host" in result["smtp"]["error"] or "server address is not allowed" in result["smtp"]["error"])
+    create_socket.assert_not_called()
+
+
+@pytest.mark.asyncio
+async def test_test_connection_metadata_ip_rejected_even_for_admin(monkeypatch):
+    import routes.email_routes as email_routes
+    _set_admin(monkeypatch, True)
+    router = email_routes.setup_email_routes()
+    test_conn = _route(router, "/api/email/accounts/test", "POST")
+
+    body = {"imap_host": "169.254.169.254", "imap_port": 80, "imap_user": "x", "imap_password": "x", "imap_starttls": True}
+    with mock.patch("socket.socket") as create_socket:
+        result = await test_conn(req=_Req(body), owner="admin")
+    assert result["ok"] is False
+    assert ("link-local" in result["imap"]["error"] or "server address is not allowed" in result["imap"]["error"])
+    create_socket.assert_not_called()
+
+
+@pytest.mark.asyncio
+async def test_test_connection_admin_may_use_loopback(monkeypatch):
+    """Local-first: an admin's Dovecot on localhost keeps working."""
+    import routes.email_routes as email_routes
+    _set_admin(monkeypatch, True)
+    router = email_routes.setup_email_routes()
+    test_conn = _route(router, "/api/email/accounts/test", "POST")
+
+    body = {"imap_host": "127.0.0.1", "imap_port": 31143, "imap_user": "x", "imap_password": "x", "imap_starttls": False}
+    with mock.patch("routes.email_routes._open_imap_connection", return_value=mock.MagicMock()) as imap_open:
+        result = await test_conn(req=_Req(body), owner="admin")
+    assert result["imap"]["ok"] is True
+    imap_open.assert_called_once()
+
+
+@pytest.mark.asyncio
+async def test_create_account_rejects_metadata_host_before_db(monkeypatch):
+    import routes.email_routes as email_routes
+    _set_admin(monkeypatch, True)
+    router = email_routes.setup_email_routes()
+    create = _route(router, "/api/email/accounts", "POST")
+
+    def _no_db():
+        raise AssertionError("DB must not be touched for a rejected host")
+
+    with mock.patch("core.database.SessionLocal", _no_db):
+        result = await create(
+            {"name": "Backup", "imap_host": "169.254.169.254", "imap_user": "u", "imap_password": "p"},
+            owner="admin",
+        )
+    assert result["ok"] is False
+    assert "Rejected IMAP host" in result["error"]
+
+
+@pytest.mark.asyncio
+async def test_create_account_rejects_private_host_for_non_admin(monkeypatch):
+    import routes.email_routes as email_routes
+    _set_admin(monkeypatch, False)
+    router = email_routes.setup_email_routes()
+    create = _route(router, "/api/email/accounts", "POST")
+    with mock.patch("core.database.SessionLocal", _make_orm_db()):
+        result = await create(
+            {"name": "Scan", "imap_host": "93.184.216.34", "smtp_host": "10.0.0.5", "imap_user": "u", "imap_password": "p"},
+            owner="regular-user",
+        )
+    assert result["ok"] is False
+    assert "Rejected SMTP host" in result["error"]
+
+
+@pytest.mark.asyncio
+async def test_create_account_admin_private_host_allowed_unless_locked_down(monkeypatch):
+    import routes.email_routes as email_routes
+    _set_admin(monkeypatch, True)
+    router = email_routes.setup_email_routes()
+    create = _route(router, "/api/email/accounts", "POST")
+    payload = {"name": "LAN", "imap_host": "192.168.1.10", "imap_user": "u", "imap_password": "p"}
+
+    with mock.patch("core.database.SessionLocal", _make_orm_db()):
+        result = await create(dict(payload), owner="admin")
+    assert result["ok"] is True
+
+    monkeypatch.setenv("EMAIL_BLOCK_PRIVATE_IPS", "true")
+    with mock.patch("core.database.SessionLocal", _make_orm_db()):
+        result = await create(dict(payload), owner="admin")
+    assert result["ok"] is False
+    assert "Rejected IMAP host" in result["error"]
+
+
+@pytest.mark.asyncio
+async def test_update_account_rejects_bad_host_and_keeps_row(monkeypatch):
+    import routes.email_routes as email_routes
+    from core.database import EmailAccount
+    _set_admin(monkeypatch, False)
+    Factory = _make_orm_db()
+    db = Factory()
+    db.add(EmailAccount(id="acct-1", owner="regular-user", name="Mine", imap_host="imap.gmail.com", imap_port=993))
+    db.commit()
+    db.close()
+
+    router = email_routes.setup_email_routes()
+    update = _route(router, "/api/email/accounts/{account_id}", "PUT")
+    with mock.patch("core.database.SessionLocal", Factory), \
+         mock.patch("routes.email_routes._assert_owns_account", lambda account_id, owner: None):
+        result = await update("acct-1", {"imap_host": "127.0.0.1", "imap_port": 8000}, owner="regular-user")
+    assert result["ok"] is False
+    assert "Rejected IMAP host" in result["error"]
+
+    db = Factory()
+    try:
+        assert db.get(EmailAccount, "acct-1").imap_host == "imap.gmail.com"
+    finally:
+        db.close()
+
+
+@pytest.mark.asyncio
+async def test_update_config_rejects_bad_host(monkeypatch):
+    import routes.email_routes as email_routes
+    _set_admin(monkeypatch, False)
+    router = email_routes.setup_email_routes()
+    update_cfg = _route(router, "/api/email/config", "PUT")
+
+    def _no_db():
+        raise AssertionError("DB must not be touched for a rejected host")
+
+    with mock.patch("core.database.SessionLocal", _no_db), \
+         mock.patch("routes.email_routes._load_settings", _no_db):
+        result = await update_cfg({"smtp_host": "10.0.0.1", "smtp_port": 6379}, account_id=None, owner="regular-user")
+    assert result["ok"] is False
+    assert "Rejected SMTP host" in result["error"]
+
+
+# ── adversarial runtime & connection-time tests ─────────────────────────────
+
+def test_connect_outbound_tcp_blocks_dns_rebinding():
+    with mock.patch("socket.getaddrinfo", return_value=[(socket.AF_INET, socket.SOCK_STREAM, 6, "", ("169.254.169.254", 993))]):
+        with pytest.raises(OutboundAddressBlocked) as exc_info:
+            connect_outbound_tcp("rebind.example.org", 993, block_private=False)
+        assert "link-local" in str(exc_info.value)
+
+
+def test_connect_outbound_tcp_multiple_ips_fails_closed():
+    mixed_addrs = [
+        (socket.AF_INET, socket.SOCK_STREAM, 6, "", ("93.184.216.34", 993)),
+        (socket.AF_INET, socket.SOCK_STREAM, 6, "", ("10.0.0.1", 993)),
+    ]
+    with mock.patch("socket.getaddrinfo", return_value=mixed_addrs):
+        with pytest.raises(OutboundAddressBlocked) as exc_info:
+            connect_outbound_tcp("dual.example.org", 993, block_private=True)
+        assert "private/shared/loopback" in str(exc_info.value)
+
+
+@pytest.mark.asyncio
+async def test_test_connection_endpoint_dns_rebinding_blocked(monkeypatch):
+    """If DNS changes between save-check and connection, connect-time validation stops it."""
+    import routes.email_routes as email_routes
+    _set_admin(monkeypatch, False)
+    router = email_routes.setup_email_routes()
+    test_conn = _route(router, "/api/email/accounts/test", "POST")
+
+    body = {
+        "imap_host": "rebind.example.org", "imap_port": 993, "imap_user": "u", "imap_password": "p",
+        "imap_starttls": False,
+    }
+    rebinding_addrs = [(socket.AF_INET, socket.SOCK_STREAM, 6, "", ("127.0.0.1", 993))]
+    with mock.patch("socket.getaddrinfo", return_value=rebinding_addrs), \
+         mock.patch("socket.socket") as create_socket:
+        result = await test_conn(req=_Req(body), owner="regular-user")
+
+    assert result["ok"] is False
+    assert ("Rejected IMAP host" in result["imap"]["error"] or "server address is not allowed" in result["imap"]["error"])
+    create_socket.assert_not_called()
+
+
+@pytest.mark.asyncio
+async def test_runtime_imap_connect_blocks_preexisting_db_row(monkeypatch):
+    """A database row with private host (preexisting, restored, or DB-injected) fails closed at runtime."""
+    import routes.email_helpers as email_helpers
+    from core.database import EmailAccount
+    _set_admin(monkeypatch, False)
+    Factory = _make_orm_db()
+    db = Factory()
+    db.add(EmailAccount(id="acct-malicious", owner="regular-user", name="Evil", imap_host="127.0.0.1", imap_port=993, imap_user="u", imap_password="p"))
+    db.commit()
+    db.close()
+
+    with mock.patch("core.database.SessionLocal", Factory):
+        with pytest.raises(OutboundAddressBlocked) as exc_info:
+            email_helpers._imap_connect("acct-malicious", owner="regular-user")
+        assert "private/shared/loopback" in str(exc_info.value)
+
+
+def test_runtime_send_smtp_message_blocks_metadata_host(monkeypatch):
+    """_send_smtp_message fails closed on cloud metadata destination."""
+    import routes.email_helpers as email_helpers
+    _set_admin(monkeypatch, True)
+    cfg = {
+        "smtp_host": "169.254.169.254",
+        "smtp_port": 25,
+        "owner": "admin",
+    }
+    with pytest.raises(OutboundAddressBlocked) as exc_info:
+        email_helpers._send_smtp_message(cfg, "from@example.com", ["to@example.com"], b"data")
+    assert "link-local" in str(exc_info.value)
+
+
+def test_ipv6_loopback_allowed_for_admin_blocked_for_non_admin():
+    mock_sock = mock.MagicMock()
+    with mock.patch("socket.socket", return_value=mock_sock):
+        sock = connect_outbound_tcp("::1", 993, block_private=False)
+        assert sock is mock_sock
+        mock_sock.connect.assert_called_with(("::1", 993, 0, 0))
+
+    with pytest.raises(OutboundAddressBlocked) as exc_info:
+        connect_outbound_tcp("::1", 993, block_private=True)
+    assert "private/shared/loopback" in str(exc_info.value)
+
+
+def test_email_block_private_ips_env_overrides_admin(monkeypatch):
+    import routes.email_helpers as email_helpers
+    _set_admin(monkeypatch, True)
+    monkeypatch.setenv("EMAIL_BLOCK_PRIVATE_IPS", "true")
+    cfg = {
+        "smtp_host": "127.0.0.1",
+        "smtp_port": 25,
+        "owner": "admin",
+    }
+    with pytest.raises(OutboundAddressBlocked) as exc_info:
+        email_helpers._send_smtp_message(cfg, "from@example.com", ["to@example.com"], b"data")
+    assert "private/shared/loopback" in str(exc_info.value)
+
+
+def test_tls_sni_preserved_during_safe_connection():
+    import routes.email_helpers as email_helpers
+    mock_sock = mock.MagicMock()
+    mock_ssl_sock = mock.MagicMock()
+    mock_ctx = mock.MagicMock()
+    mock_ctx.wrap_socket.return_value = mock_ssl_sock
+
+    with mock.patch("routes.email_helpers.connect_outbound_tcp", return_value=mock_sock):
+        imap = email_helpers._PolicyIMAP4_SSL.__new__(email_helpers._PolicyIMAP4_SSL)
+        imap._block_private = False
+        imap.host = "imap.secure.example.com"
+        imap.port = 993
+        imap.ssl_context = mock_ctx
+        res = imap._create_socket(10)
+        mock_ctx.wrap_socket.assert_called_with(mock_sock, server_hostname="imap.secure.example.com")
+        assert res is mock_ssl_sock
+
+    mock_smtp_sock = mock.MagicMock()
+    mock_ctx.wrap_socket.return_value = mock_smtp_sock
+    with mock.patch("routes.email_helpers.connect_outbound_tcp", return_value=mock_sock):
+        smtp = email_helpers._PolicySMTP_SSL.__new__(email_helpers._PolicySMTP_SSL)
+        smtp._block_private = False
+        smtp._host = "smtp.secure.example.com"
+        smtp.context = mock_ctx
+        smtp.source_address = None
+        res = smtp._get_socket("smtp.secure.example.com", 465, 10)
+        mock_ctx.wrap_socket.assert_called_with(mock_sock, server_hostname="smtp.secure.example.com")
+        assert res is mock_smtp_sock
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("route_name", ["create", "update", "config"])
+@pytest.mark.parametrize("field", ["imap_host", "smtp_host"])
+@pytest.mark.parametrize("is_admin", [False, True])
+@pytest.mark.parametrize("answer", ["error", "empty", "garbage", "none"])
+async def test_save_rejects_unresolved_hosts_before_persistence(monkeypatch, route_name, field, is_admin, answer):
+    import routes.email_routes as routes
+    import src.url_safety as safety
+
+    _set_admin(monkeypatch, is_admin)
+    def resolve(host):
+        if answer == "error":
+            raise RuntimeError("resolver-internal-detail")
+        return {"empty": [], "garbage": ["not-an-ip"], "none": None}[answer]
+
+    def no_persistence(*args, **kwargs):
+        raise AssertionError("Rejected mail host reached persistence")
+
+    monkeypatch.setattr(safety, "_default_resolver", resolve)
+    monkeypatch.setattr("core.database.SessionLocal", no_persistence)
+    monkeypatch.setattr(routes, "_load_settings", no_persistence)
+    monkeypatch.setattr(routes, "_save_settings", no_persistence)
+    monkeypatch.setattr(routes, "_assert_owns_account", lambda *a: None)
+    router = routes.setup_email_routes()
+    payload = {"name": "Pending DNS", field: "pending.example.invalid"}
+    owner = "admin" if is_admin else "regular-user"
+    if route_name == "create":
+        result = await _route(router, "/api/email/accounts", "POST")(payload, owner=owner)
+    elif route_name == "update":
+        result = await _route(router, "/api/email/accounts/{account_id}", "PUT")("acct", payload, owner=owner)
+    else:
+        result = await _route(router, "/api/email/config", "PUT")(payload, account_id=None, owner=owner)
+    assert result["ok"] is False
+    assert "does not resolve" in result["error"]
+    assert "resolver-internal-detail" not in result["error"]
+    assert "not-an-ip" not in result["error"]
+
+
+def test_connect_pins_the_first_resolution_without_rebinding_lookup():
+    public = [(socket.AF_INET, socket.SOCK_STREAM, 6, "", ("93.184.216.34", 993))]
+    metadata = [(socket.AF_INET, socket.SOCK_STREAM, 6, "", ("169.254.169.254", 993))]
+    resolver = mock.Mock(side_effect=[public, metadata])
+    with mock.patch("socket.socket") as create_socket:
+        sock = connect_outbound_tcp("rebind.example.org", 993, resolver=resolver, block_private=True)
+    resolver.assert_called_once_with("rebind.example.org", 993, 0, socket.SOCK_STREAM)
+    sock.connect.assert_called_once_with(("93.184.216.34", 993))
+
+
+def test_resolver_type_error_propagates_without_alternate_signature_retry():
+    resolver = mock.Mock(side_effect=TypeError("resolver-internal-bug"))
+    with mock.patch("socket.socket") as create_socket:
+        with pytest.raises(TypeError, match="resolver-internal-bug"):
+            connect_outbound_tcp("mail.example.org", 993, resolver=resolver)
+    resolver.assert_called_once_with("mail.example.org", 993, 0, socket.SOCK_STREAM)
+    create_socket.assert_not_called()
+
+
+@pytest.mark.parametrize("port", [None, 0, -1, 65536, True, 25.5, "not-a-port"])
+def test_invalid_tcp_port_is_rejected_before_resolution(port):
+    resolver = mock.Mock()
+    with pytest.raises(ValueError):
+        connect_outbound_tcp("mail.example.org", port, resolver=resolver)
+    resolver.assert_not_called()
+
+
+def test_empty_resolver_iterator_fails_closed():
+    assert check_outbound_host("empty.example.org", resolver=lambda host: iter(()))[0] is False
+
+
+def test_shared_space_metadata_endpoint_is_identified_correctly():
+    ok, reason = check_outbound_host("100.100.100.200", block_private=False)
+    assert ok is False
+    assert "metadata endpoint blocked" in reason
+    assert "link-local" not in reason
+
+
+def test_importing_mail_helpers_does_not_replace_stdlib_clients():
+    import subprocess
+    import sys
+
+    subprocess.run([sys.executable, "-c", """
+import imaplib, smtplib
+original = (imaplib.IMAP4, imaplib.IMAP4_SSL, smtplib.SMTP, smtplib.SMTP_SSL)
+import routes.email.email_helpers
+assert original == (imaplib.IMAP4, imaplib.IMAP4_SSL, smtplib.SMTP, smtplib.SMTP_SSL)
+"""], check=True, capture_output=True, text=True)
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("route_name", ["create", "update", "config"])
+async def test_save_host_resolution_runs_off_the_event_loop(monkeypatch, route_name):
+    import threading
+    import routes.email_routes as routes
+
+    event_loop_thread = threading.get_ident()
+    def guard(*args):
+        assert threading.get_ident() != event_loop_thread
+        return "Host rejected"
+
+    monkeypatch.setattr(routes, "_check_mail_host", guard)
+    monkeypatch.setattr(routes, "_assert_owns_account", lambda *args: None)
+    router = routes.setup_email_routes()
+    payload = {"name": "Pending DNS", "imap_host": "pending.example.invalid"}
+    if route_name == "create":
+        result = await _route(router, "/api/email/accounts", "POST")(payload, owner="admin")
+    elif route_name == "update":
+        result = await _route(router, "/api/email/accounts/{account_id}", "PUT")("acct", payload, owner="admin")
+    else:
+        result = await _route(router, "/api/email/config", "PUT")(payload, account_id=None, owner="admin")
+    assert result == {"ok": False, "error": "Host rejected"}
+
+

From 39ca749f94987aa02775f5b327e48e0d52beb5e4 Mon Sep 17 00:00:00 2001
From: pewdiepie-archdaemon <pewdiepie-archdaemon@users.noreply.github.com>
Date: Mon, 26 Oct 2026 16:21:22 +0000
Subject: [PATCH 53/53] Refresh configuration reference for the integrated
 review scope

---
 scripts/generate_env_reference.py  | 37 ------------------------------
 website/configuration-reference.md | 33 ++++----------------------
 2 files changed, 4 insertions(+), 66 deletions(-)

diff --git a/scripts/generate_env_reference.py b/scripts/generate_env_reference.py
index 91100656e..ff0fe8974 100644
--- a/scripts/generate_env_reference.py
+++ b/scripts/generate_env_reference.py
@@ -946,43 +946,6 @@ VARIABLE_NOTES: dict[str, tuple[str, str, str]] = {
         "Seconds the outpainting proxy waits for the image backend before giving "
         "up on a single request.",
     ),
-    "ODYSSEUS_JEFF_": ("Agent loop and tool execution", INTERNAL, "Prefix for per-job decision adapter opt-ins; each job is disabled by default."),
-    "ODYSSEUS_JEFF_TIMEOUT": ("Agent loop and tool execution", INTERNAL, "Timeout in seconds for a decision adapter request."),
-    "ODYSSEUS_JEFF_URL": ("Agent loop and tool execution", INTERNAL, "Base URL of the optional decision adapter service."),
-    "ODYSSEUS_PRIVATE_BROWSER_LEGACY": ("Agent loop and tool execution", INTERNAL, "Explicit opt-in to the legacy browser compatibility transport; disabled by default."),
-    "ODYSSEUS_SPEC_BROWSER_FALLBACK": ("Agent loop and tool execution", INTERNAL, "Optional browser routing fallback: mcp, web, or 0 to disable."),
-    "ODYSSEUS_SPEC_DRIVER_TOPK": ("Agent loop and tool execution", INTERNAL, "Number of router-selected tool candidates exposed in a driver round."),
-    "ODYSSEUS_SPEC_MODE": ("Agent loop and tool execution", INTERNAL, "Spec routing mode for explicitly configured models, including strict and driver."),
-    "ODYSSEUS_SPEC_ROUTER_MIN_CONF": ("Agent loop and tool execution", INTERNAL, "Minimum tool-selection confidence accepted from the router."),
-    "ODYSSEUS_SPEC_ROUTER_MODEL": ("Agent loop and tool execution", INTERNAL, "Decision adapter model used for tool routing."),
-    "ODYSSEUS_SPEC_ROUTER_SECOND": ("Agent loop and tool execution", INTERNAL, "Minimum confidence for adding a secondary tool candidate."),
-    "ODYSSEUS_SPEC_ROUTER_TIMEOUT": ("Agent loop and tool execution", INTERNAL, "Time budget in seconds for a router decision."),
-    "ODYSSEUS_SPEC_ROUTER_URL": ("Agent loop and tool execution", INTERNAL, "Base URL of the optional Spec router; an empty URL disables requests."),
-    "ODYSSEUS_SPEC_SUBSET_OF_BASE": ("Agent loop and tool execution", INTERNAL, "Limit Spec tool selections to the existing request inventory by default."),
-    "ODYSSEUS_SPEC_THINK_MIN_P": ("Agent loop and tool execution", INTERNAL, "Minimum router confidence for enabling thinking."),
-    "ODYSSEUS_SPEC_THINK_MODEL": ("Agent loop and tool execution", INTERNAL, "Optional thinking decision adapter model, falling back to the tool router model."),
-    "ODYSSEUS_SPEC_THINK_QUESTION": ("Agent loop and tool execution", INTERNAL, "Thinking classifier question format: binary or kind5."),
-    "ODYSSEUS_SPEC_THINK_ROUTER": ("Agent loop and tool execution", INTERNAL, "Enable router thinking decisions for explicitly configured Spec models."),
-    "ODYSSEUS_SPEC_TOOL_FORMAT": ("Agent loop and tool execution", INTERNAL, "Use names for compact router tool signatures, otherwise include descriptions."),
-    "ODYSSEUS_SPEC_TRIM_PROMPT": ("Agent loop and tool execution", INTERNAL, "Enable prompt trimming for the selected Spec tool menu."),
-    "ODYSSEUS_VISION_MAX_SIDE": ("Upload and media limits", USER, "Maximum pixel side for image attachments sent directly to a vision model."),
-    "ODYSSEUS_VISION_MODELS": ("Model routing and providers", USER, "Comma-separated model-name fragments that explicitly support inline images."),
-    "ODYSSEUS_VISION_PROBE": ("Model routing and providers", USER, "Allow a cached vision-capability probe against local model endpoints."),
-    "ODYSSEUS_SPEC_DIRECT_MODE": (
-        "Agent loop and tool execution", INTERNAL,
-        "Controls how the spec router answers high-confidence direct-answer turns; "
-        "either tool_choice_none (default) or empty_menu.",
-    ),
-    "ODYSSEUS_SPEC_DIRECT_NOTOOLS": (
-        "Agent loop and tool execution", INTERNAL,
-        "Set to 1, true, yes or on to enable the spec router's direct-answer "
-        "no-tools path for high-confidence answer_directly decisions.",
-    ),
-    "ODYSSEUS_SPEC_DIRECT_MIN_P": (
-        "Agent loop and tool execution", INTERNAL,
-        "Minimum confidence probability a spec-router direct-answer decision must "
-        "reach before the no-tools path is taken.",
-    ),
     "ODYSSEUS_GRACEFUL_SHUTDOWN_TIMEOUT": (
         "Deployment and first run", INTERNAL,
         "Seconds the server waits for in-flight requests and background loops to "
diff --git a/website/configuration-reference.md b/website/configuration-reference.md
index 2ee5588a4..86baa197d 100644
--- a/website/configuration-reference.md
+++ b/website/configuration-reference.md
@@ -21,7 +21,7 @@ described as a switch that turns something off, the read rejects `0`, `false`,
 `no` and `off` and treats everything else as on. The `Default` column is the
 value the code falls back to when the variable is unset, quoted from the source.
 
-The source tree reads **149** `ODYSSEUS_*` variables: 90 an operator may want to set, and 59 that are internal - sentinels, fixture switches, capture hooks and development tooling. The internal ones are listed too, in their own section, so this page can be checked against the source mechanically.
+The source tree reads **124** `ODYSSEUS_*` variables: 87 an operator may want to set, and 37 that are internal - sentinels, fixture switches, capture hooks and development tooling. The internal ones are listed too, in their own section, so this page can be checked against the source mechanically.
 
 > This page is generated. Edit `scripts/generate_env_reference.py` and
 > re-run it; `tests/test_env_reference.py` enforces that the committed page
@@ -69,8 +69,6 @@ The source tree reads **149** `ODYSSEUS_*` variables: 90 an operator may want to
 | `ODYSSEUS_MISTRAL_REASONING_EFFORT` | `'high'` | `src/llm_core.py` | Reasoning effort sent to Mistral thinking-capable models. The API accepts high, medium, low and none. |
 | `ODYSSEUS_MLX_IMAGE_VLM_MODEL` | *unset* | `scripts/mlx_image_server.py` | Vision-language model id for the MLX image server script. Required unless `--vlm-model` is passed on the command line. |
 | `ODYSSEUS_QWEN_ROUTE_THINKING` | `'auto'` | `src/agent_loop.py` | Thinking policy for the Qwen routing step. An unrecognized value falls back to `auto`. |
-| `ODYSSEUS_VISION_MODELS` | `''` | `src/chat_helpers.py` | Comma-separated model-name fragments that explicitly support inline images. |
-| `ODYSSEUS_VISION_PROBE` | `'1'` | `src/chat_helpers.py` | Allow a cached vision-capability probe against local model endpoints. |
 
 ### Agent loop and tool execution
 
@@ -93,9 +91,9 @@ The source tree reads **149** `ODYSSEUS_*` variables: 90 an operator may want to
 | `ODYSSEUS_BROWSER_MCP_CACHE` | `os.path.join(base_dir, 'data', 'local', 'playwright-mcp-cache')` | `src/builtin_mcp.py` | Cache directory handed to the browser MCP server, so its npm download survives a container rebuild. |
 | `ODYSSEUS_BROWSER_MCP_CALL_TIMEOUT_S` | `'90'` | `src/mcp_manager.py` | Upper bound in seconds for one browser MCP tool call. A call that exceeds it fails without being retried. |
 | `ODYSSEUS_BROWSER_MCP_REQUIRE_CACHE` | `''` | `src/builtin_mcp.py` | Truthy refuses to start the browser MCP server unless its npm package is already in the npx cache, instead of installing it at startup. |
-| `ODYSSEUS_BROWSER_NAMESPACE` | `'odysseus-ui'` | `src/agent_tools/web_tools.py` (+1 more) | Namespace for the detached agent-browser daemon's pid files, so two runtimes on one machine do not terminate each other's browsers. |
+| `ODYSSEUS_BROWSER_NAMESPACE` | `'odysseus-ui'` | `src/agent_tools/web_tools.py` | Namespace for the detached agent-browser daemon's pid files, so two runtimes on one machine do not terminate each other's browsers. |
 | `ODYSSEUS_BROWSER_NO_SANDBOX` | `'1'` | `src/builtin_mcp.py` | Security-relevant. On by default, adding `--no-sandbox` because the Docker image cannot use the Chromium sandbox. Set 0, false or no to keep it. |
-| `ODYSSEUS_BROWSER_SCREENSHOT_DIR` | *unset* | `src/agent_tools/web_tools.py` (+1 more) | Where private-browser screenshots are written. Falls back to the container path, then the system temp directory. |
+| `ODYSSEUS_BROWSER_SCREENSHOT_DIR` | *unset* | `src/agent_tools/web_tools.py` | Where private-browser screenshots are written. Falls back to the container path, then the system temp directory. |
 
 ### Container and workspace mounts
 
@@ -149,7 +147,6 @@ The source tree reads **149** `ODYSSEUS_*` variables: 90 an operator may want to
 | `ODYSSEUS_MEMORY_IMPORT_MAX_BYTES` | `10 * 1024 * 1024` | `src/upload_limits.py` (+1 more) | Maximum bytes accepted for a memory import file. |
 | `ODYSSEUS_PERSONAL_UPLOAD_MAX_BYTES` | `25 * 1024 * 1024` | `src/upload_limits.py` (+1 more) | Maximum bytes accepted for a personal-documents upload. |
 | `ODYSSEUS_STT_MAX_AUDIO_BYTES` | `25 * 1024 * 1024` | `src/upload_limits.py` | Maximum bytes accepted for an audio file submitted for transcription. |
-| `ODYSSEUS_VISION_MAX_SIDE` | `'1280'` | `src/document_processor.py` | Maximum pixel side for image attachments sent directly to a vision model. |
 
 ### Search
 
@@ -214,28 +211,6 @@ Listed for completeness. Setting one of these on a real install is either a no-o
 |---|---|---|---|
 | `ODYSSEUS_CAPTURE_MODEL_REQUESTS` | `''` | `src/agent_loop.py` | Truthy writes model-request snapshots for local debugging. The marker file `/tmp/odysseus_capture_model_requests` enables the same thing. |
 | `ODYSSEUS_EXPOSE_RAW_BROWSER_MCP` | `''` | `src/agent_loop.py` | Truthy stops hiding the raw Playwright MCP tools from agent prompts when the private-browser tool is available. |
-| `ODYSSEUS_JEFF_` | *unset* | `src/jeff_decision.py` | Prefix for per-job decision adapter opt-ins; each job is disabled by default. |
-| `ODYSSEUS_JEFF_TIMEOUT` | `str(default)` | `src/jeff_decision.py` | Timeout in seconds for a decision adapter request. |
-| `ODYSSEUS_JEFF_URL` | `'http://127.0.0.1:8765'` | `src/jeff_decision.py` | Base URL of the optional decision adapter service. |
-| `ODYSSEUS_PRIVATE_BROWSER_LEGACY` | `'0'` | `src/tool_execution.py` (+1 more) | Explicit opt-in to the legacy browser compatibility transport; disabled by default. |
-| `ODYSSEUS_SPEC_BROWSER_FALLBACK` | `'0'` | `src/spec_router.py` | Optional browser routing fallback: mcp, web, or 0 to disable. |
-| `ODYSSEUS_SPEC_DIRECT_MIN_P` | `'0.9'` | `src/clean_agent_preview.py` | Minimum confidence probability a spec-router direct-answer decision must reach before the no-tools path is taken. |
-| `ODYSSEUS_SPEC_DIRECT_MODE` | `'tool_choice_none'` | `src/clean_agent_preview.py` | Controls how the spec router answers high-confidence direct-answer turns; either tool_choice_none (default) or empty_menu. |
-| `ODYSSEUS_SPEC_DIRECT_NOTOOLS` | `''` | `src/clean_agent_preview.py` | Set to 1, true, yes or on to enable the spec router's direct-answer no-tools path for high-confidence answer_directly decisions. |
-| `ODYSSEUS_SPEC_DRIVER_TOPK` | `'1'` | `src/spec_driver.py` | Number of router-selected tool candidates exposed in a driver round. |
-| `ODYSSEUS_SPEC_MODE` | `'strict'` | `src/agent_loop.py` (+1 more) | Spec routing mode for explicitly configured models, including strict and driver. |
-| `ODYSSEUS_SPEC_ROUTER_MIN_CONF` | `'0.3'` | `src/spec_router.py` | Minimum tool-selection confidence accepted from the router. |
-| `ODYSSEUS_SPEC_ROUTER_MODEL` | `'odysseus-s60'` | `src/spec_router.py` | Decision adapter model used for tool routing. |
-| `ODYSSEUS_SPEC_ROUTER_SECOND` | `'0.25'` | `src/spec_router.py` | Minimum confidence for adding a secondary tool candidate. |
-| `ODYSSEUS_SPEC_ROUTER_TIMEOUT` | `'0.5'` | `src/spec_router.py` | Time budget in seconds for a router decision. |
-| `ODYSSEUS_SPEC_ROUTER_URL` | `''` | `src/spec_router.py` | Base URL of the optional Spec router; an empty URL disables requests. |
-| `ODYSSEUS_SPEC_SUBSET_OF_BASE` | `'1'` | `src/agent_loop.py` | Limit Spec tool selections to the existing request inventory by default. |
-| `ODYSSEUS_SPEC_THINK_MIN_P` | `'0.5'` | `src/spec_router.py` | Minimum router confidence for enabling thinking. |
-| `ODYSSEUS_SPEC_THINK_MODEL` | `os.getenv('ODYSSEUS_SPEC_ROUTER_MODEL', 'odysseus-s60')` | `src/spec_router.py` | Optional thinking decision adapter model, falling back to the tool router model. |
-| `ODYSSEUS_SPEC_THINK_QUESTION` | `'binary'` | `src/spec_router.py` | Thinking classifier question format: binary or kind5. |
-| `ODYSSEUS_SPEC_THINK_ROUTER` | `'0'` | `src/spec_router.py` | Enable router thinking decisions for explicitly configured Spec models. |
-| `ODYSSEUS_SPEC_TOOL_FORMAT` | `''` | `src/spec_router.py` | Use names for compact router tool signatures, otherwise include descriptions. |
-| `ODYSSEUS_SPEC_TRIM_PROMPT` | `'1'` | `src/agent_loop.py` | Enable prompt trimming for the selected Spec tool menu. |
 | `ODYSSEUS_TOOL_CONTRACT_ROOT` | `str(Path(__file__).resolve().parents[1] / 'scripts')` | `src/clean_agent_preview.py` (+1 more) | Directory holding the tool-contract scripts the clean-agent preview loads. The default resolves to the bundled scripts directory relative to the installed/source tree. |
 
 ### Email
@@ -302,7 +277,7 @@ reads three ways, because no single pattern covers the codebase:
   lines, so one read lives inside a string literal.
 
 The three passes are not redundancy. A line-based grep for a direct
-`os.environ.get("ODYSSEUS_...` call finds 119 of the 149 variables on this
+`os.environ.get("ODYSSEUS_...` call finds 94 of the 124 variables on this
 page. What it misses is reads through an env-reader helper, reads whose call
 spans more than one line, reads whose variable name is held in a module
 constant, and reads through a mapping passed in as an argument - which is the