From 304d5afa605c9121f23b9c68884d39ec3508f81e Mon Sep 17 00:00:00 2001
From: Cursor Agent <cursoragent@cursor.com>
Date: Mon, 17 Aug 2026 23:17:32 +0000
Subject: [PATCH 01/15] feat(mail): open recognized HWPX text from email
 attachments

List the current email's attachments with the same opaque asset_key as
the Data preview contract so a buyer can read ordered HWPX paragraphs
from mail without treating missing text as empty content.

Co-authored-by: Seongho Bae <seonghobae@users.noreply.github.com>
---
 AGENTS.md                                     |   6 +
 backend/api/emails.py                         |  33 +-
 .../tests/test_email_attachment_preview.py    | 351 ++++++++++++++++++
 .../hwp-hwpx-attachment-recognition.md        |  14 +
 frontend/src/components/EmailDetail.test.tsx  |  68 ++++
 frontend/src/components/EmailDetail.tsx       |   5 +
 .../components/MailAttachmentPreview.test.tsx | 208 +++++++++++
 .../src/components/MailAttachmentPreview.tsx  |  96 +++++
 frontend/src/lib/email-threading.ts           |   8 +
 frontend/tests/e2e/dashboard-flows.spec.ts    |  15 +
 frontend/tests/e2e/helpers.ts                 |  29 +-
 11 files changed, 830 insertions(+), 3 deletions(-)
 create mode 100644 backend/tests/test_email_attachment_preview.py
 create mode 100644 frontend/src/components/MailAttachmentPreview.test.tsx
 create mode 100644 frontend/src/components/MailAttachmentPreview.tsx

diff --git a/AGENTS.md b/AGENTS.md
index 2a45040bd..1a14c29bc 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -446,6 +446,12 @@ in this repo.
   topic components, or label evidence by a bare document, model, topic, rank,
   label, or display value.
 - When reviews find public/private identifier leaks, stale API fixture shapes, or recurring bug patterns, update tests, frontend mocks, E2E mocks, README examples, architecture docs, and explicitly record the anti-pattern in `AGENTS.md` so the same bug pattern does not reappear in copied examples.
+- Mail attachment surfaces must list the current email's files with opaque
+  `asset_key` values and open the signed
+  `/api/data/repository-assets/{asset_key}/preview` contract. Do not expose
+  sequential attachment ids, render missing preview text as empty document
+  content, or send buyers only to the Data repository list as a substitute for
+  opening the HWPX file on the selected mail.
 - Memoized id-to-record Maps must be first-wins (`if (!map.has(key)) map.set(...)`).
   `new Map(items.map((item) => [String(item.id), item]))` is last-wins and
   desynchronizes first-wins label maps from the selected node or edge when
diff --git a/backend/api/emails.py b/backend/api/emails.py
index 2b0a9dbd6..e1ddef19b 100644
--- a/backend/api/emails.py
+++ b/backend/api/emails.py
@@ -3,8 +3,10 @@
 from fastapi import APIRouter, Depends, File, HTTPException, Query, UploadFile
 from sqlalchemy.ext.asyncio import AsyncSession
 from sqlalchemy import func, or_, select
+from sqlalchemy.orm import selectinload
 from db.session import get_db
 from db.models import Email
+from api.data import _opaque_asset_key
 from pydantic import BaseModel, EmailStr, Field, field_validator
 import datetime
 import time
@@ -165,6 +167,22 @@ def _email_list_item(
     )
 
 
+def _mail_attachment_refs(email: Email) -> list["EmailAttachmentRef"]:
+    """Return opaque, display-safe attachment refs for one scoped email."""
+
+    refs: list[EmailAttachmentRef] = []
+    for attachment in getattr(email, "attachments", None) or []:
+        file_name = _safe_email_display_text(getattr(attachment, "filename", None))
+        refs.append(
+            EmailAttachmentRef(
+                asset_key=_opaque_asset_key(email, attachment),
+                file_name=file_name or "email attachment",
+                parser_family=str(getattr(attachment, "parser_key", "") or "") or None,
+            )
+        )
+    return refs
+
+
 def _email_detail_response(email: Email) -> "EmailDetailResponse":
     return EmailDetailResponse(
         id=email.id,
@@ -178,6 +196,7 @@ def _email_detail_response(email: Email) -> "EmailDetailResponse":
         thread_id=canonical_thread_key(email),
         in_reply_to=email.in_reply_to,
         references=email.references,
+        attachments=_mail_attachment_refs(email),
     )
 
 
@@ -197,6 +216,14 @@ class EmailListItem(BaseModel):
     schedule_conflict: bool = False
 
 
+class EmailAttachmentRef(BaseModel):
+    """Opaque mail-attachment handle that opens the read-only preview contract."""
+
+    asset_key: str
+    file_name: str
+    parser_family: str | None = None
+
+
 class EmailDetailResponse(BaseModel):
     id: int
     message_id: str
@@ -211,6 +238,7 @@ class EmailDetailResponse(BaseModel):
     references: str | None = None
     requires_reply: bool = False
     schedule_conflict: bool = False
+    attachments: list[EmailAttachmentRef] = Field(default_factory=list)
 
 
 class UniqueThreadCandidateRequest(BaseModel):
@@ -645,7 +673,9 @@ async def get_email(
 ):
     # Ensure auth context validates the request payload and scopes access
     result = await db.execute(
-        select(Email).where(
+        select(Email)
+        .options(selectinload(Email.attachments))
+        .where(
             Email.id == email_id,
             *Email.owner_filters(auth_context.user_id, auth_context.organization_id),
         )
@@ -668,6 +698,7 @@ async def get_email_thread(
     lookup_values = thread_lookup_values(thread_id)
     result = await db.execute(
         select(Email)
+        .options(selectinload(Email.attachments))
         .where(
             *Email.owner_filters(auth_context.user_id, auth_context.organization_id),
             or_(
diff --git a/backend/tests/test_email_attachment_preview.py b/backend/tests/test_email_attachment_preview.py
new file mode 100644
index 000000000..0a64a967d
--- /dev/null
+++ b/backend/tests/test_email_attachment_preview.py
@@ -0,0 +1,351 @@
+"""Mail-detail attachments must open the existing read-only HWPX preview.
+
+#1404 already exposes recognized ordered paragraphs at
+``/api/data/repository-assets/{asset_key}/preview``. These tests require the
+core mail attachment experience to list the current email's files with that
+same opaque ``asset_key`` so a buyer can open HWPX text without going through
+the Data repository list. Preview recognition semantics stay unchanged.
+"""
+
+from __future__ import annotations
+
+import datetime
+
+import pytest
+import pytest_asyncio
+from httpx import ASGITransport, AsyncClient
+
+from db.models import Attachment, Email
+from main import app
+
+
+pytestmark = pytest.mark.usefixtures("dev_auth_dependency_overrides")
+
+
+class _EmailDetailMockSession:
+    """Return one email row for mail-detail attachment listing tests."""
+
+    def __init__(self, items: list[Email]):
+        self.items = items
+
+    async def execute(self, query, params=None):
+        class _MockResult:
+            def __init__(self, rows):
+                self.rows = rows
+
+            def scalars(self):
+                return self
+
+            def all(self):
+                return self.rows
+
+            def scalar_one_or_none(self):
+                return self.rows[0] if self.rows else None
+
+        return _MockResult(self.items)
+
+
+def _hwpx_mail_email() -> Email:
+    """Build one scoped email that already has a recognized HWPX attachment."""
+
+    email = Email(
+        id=41,
+        user_id="testuser",
+        organization_id="org-acme",
+        message_id="<mail-hwpx@example.com>",
+        thread_id="thread-mail-hwpx",
+        sender="partner@example.com",
+        reply_to="partner@example.com",
+        recipients="user@example.com",
+        subject="HWPX decision record",
+        date=datetime.datetime.now(datetime.timezone.utc),
+        body="Please review the attached HWPX decision record.",
+    )
+    email.attachments = [
+        Attachment(
+            id=99,
+            email_id=41,
+            filename="<script>alert(1)</script>decision.hwpx",
+            content="Quarterly decision record\n\nApprove the next action.",
+            content_type="application/hwp+zip",
+            parse_status="hwpx_xml_package_parsed",
+            parse_content_type="application/hwp+zip",
+            parser_key="hwpx",
+        )
+    ]
+    return email
+
+
+@pytest.fixture
+def mail_hwpx_email() -> Email:
+    """Provide the recognized HWPX mail fixture to route tests."""
+
+    return _hwpx_mail_email()
+
+
+@pytest.fixture
+def db_session(mail_hwpx_email: Email) -> _EmailDetailMockSession:
+    """Bind the mail-detail mock session to the recognized HWPX email."""
+
+    return _EmailDetailMockSession([mail_hwpx_email])
+
+
+@pytest.fixture(autouse=True)
+def override_get_db(db_session: _EmailDetailMockSession):
+    """Install the mail-detail mock database for this module."""
+
+    from db.session import get_db
+
+    app.dependency_overrides[get_db] = lambda: db_session
+    yield
+    app.dependency_overrides.pop(get_db, None)
+
+
+@pytest_asyncio.fixture
+async def client():
+    """Return a signed-session test client scoped to the fixture owner."""
+
+    async with AsyncClient(
+        transport=ASGITransport(app=app),
+        headers={
+            "X-User-Id": "testuser",
+            "X-Organization-Id": "org-acme",
+        },
+        base_url="http://test",
+    ) as async_client:
+        yield async_client
+
+
+@pytest.mark.asyncio
+async def test_email_detail_lists_opaque_hwpx_attachment_refs(
+    client: AsyncClient,
+    mail_hwpx_email: Email,
+) -> None:
+    """Mail detail exposes the current email's HWPX file without sequential ids."""
+
+    import api.data as data_api
+
+    response = await client.get(f"/api/emails/{mail_hwpx_email.id}")
+
+    assert response.status_code == 200, response.text
+    payload = response.json()
+    attachments = payload["attachments"]
+    assert len(attachments) == 1
+    attachment = attachments[0]
+    expected_key = data_api._opaque_asset_key(
+        mail_hwpx_email,
+        mail_hwpx_email.attachments[0],
+    )
+    assert attachment["asset_key"] == expected_key
+    assert attachment["asset_key"].startswith("asset_")
+    assert attachment["file_name"] == "decision.hwpx"
+    assert attachment["parser_family"] == "hwpx"
+    assert "id" not in attachment
+    assert "email_id" not in attachment
+    assert "content" not in attachment
+    assert "<script" not in attachment["file_name"].lower()
+    assert "alert(1)" not in attachment["file_name"]
+
+
+@pytest.mark.asyncio
+async def test_email_thread_lists_the_same_opaque_attachment_refs(
+    client: AsyncClient,
+    mail_hwpx_email: Email,
+) -> None:
+    """Thread messages keep the same opaque attachment keys as mail detail."""
+
+    import api.data as data_api
+
+    response = await client.get(
+        f"/api/emails/thread/{mail_hwpx_email.thread_id}"
+    )
+
+    assert response.status_code == 200, response.text
+    items = response.json()["thread"]
+    assert len(items) == 1
+    attachment = items[0]["attachments"][0]
+    assert attachment["asset_key"] == data_api._opaque_asset_key(
+        mail_hwpx_email,
+        mail_hwpx_email.attachments[0],
+    )
+    assert attachment["file_name"] == "decision.hwpx"
+    assert "id" not in attachment
+
+
+@pytest.mark.asyncio
+async def test_email_detail_without_attachments_returns_empty_list(
+    client: AsyncClient,
+) -> None:
+    """Missing attachments stay an empty list, never implied empty document text."""
+
+    from db.session import get_db
+
+    bare_email = Email(
+        id=42,
+        user_id="testuser",
+        organization_id="org-acme",
+        message_id="<mail-no-attach@example.com>",
+        thread_id="thread-mail-empty",
+        sender="partner@example.com",
+        recipients="user@example.com",
+        subject="No attachments",
+        date=datetime.datetime.now(datetime.timezone.utc),
+        body="There is no attached file.",
+    )
+    app.dependency_overrides[get_db] = lambda: _EmailDetailMockSession([bare_email])
+
+    response = await client.get(f"/api/emails/{bare_email.id}")
+
+    assert response.status_code == 200, response.text
+    assert response.json()["attachments"] == []
+
+
+@pytest.mark.asyncio
+@pytest.mark.postgres
+async def test_email_detail_preview_postgres_smoke_lists_opaque_hwpx_key() -> None:
+    """Mail detail returns the same opaque key the scoped preview can open."""
+
+    import uuid
+
+    import asyncpg
+    from sqlalchemy import text
+    from sqlalchemy.exc import OperationalError
+    from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine
+
+    from core.config import settings
+    from db.models import Base
+    from db.session import get_db
+
+    database_url = getattr(settings, "DATABASE_URL", None)
+    if not database_url:
+        pytest.skip("PostgreSQL smoke path unavailable: DATABASE_URL is not set")
+
+    user_id = f"mail_preview_user_{uuid.uuid4().hex[:12]}"
+    organization_id = f"mail_preview_org_{uuid.uuid4().hex[:12]}"
+    message_id = f"<mail-preview-{uuid.uuid4().hex}@example.com>"
+    engine = create_async_engine(database_url, echo=False)
+    try:
+        async with engine.begin() as conn:
+            await conn.execute(text("SELECT 1"))
+            await conn.execute(text("CREATE EXTENSION IF NOT EXISTS vector"))
+            await conn.run_sync(Base.metadata.create_all)
+            inserted = await conn.execute(
+                text(
+                    """
+                    INSERT INTO email_records (
+                        user_id, organization_id, message_id, thread_id,
+                        fingerprint, sender, recipients, subject, "date", body
+                    )
+                    VALUES (
+                        :user_id, :organization_id, :message_id, :thread_id,
+                        :fingerprint, :sender, :recipients, :subject, now(), :body
+                    )
+                    RETURNING id
+                    """
+                ),
+                {
+                    "user_id": user_id,
+                    "organization_id": organization_id,
+                    "message_id": message_id,
+                    "thread_id": "thread-mail-preview-hwpx",
+                    "fingerprint": f"sha256:{message_id}",
+                    "sender": "partner@example.com",
+                    "recipients": "owner@example.com",
+                    "subject": "Mail HWPX preview smoke",
+                    "body": "source email body",
+                },
+            )
+            email_id = inserted.scalar_one()
+            await conn.execute(
+                text(
+                    """
+                    INSERT INTO email_attachments (
+                        email_id, filename, content,
+                        content_type, parse_status, parse_content_type,
+                        parser_key, parse_error_code
+                    )
+                    VALUES (
+                        CAST(:email_id AS INTEGER), 'decision.hwpx',
+                        :content, 'application/hwp+zip',
+                        'hwpx_xml_package_parsed', 'application/hwp+zip',
+                        'hwpx', NULL
+                    )
+                    """
+                ),
+                {
+                    "email_id": email_id,
+                    "content": (
+                        "Quarterly decision record\n\nApprove the next action."
+                    ),
+                },
+            )
+    except (
+        ConnectionRefusedError,
+        OSError,
+        OperationalError,
+        asyncpg.CannotConnectNowError,
+        asyncpg.InvalidAuthorizationSpecificationError,
+        asyncpg.InvalidCatalogNameError,
+        asyncpg.InvalidPasswordError,
+    ):
+        await engine.dispose()
+        pytest.skip("PostgreSQL smoke path unavailable")
+    except Exception:
+        await engine.dispose()
+        raise
+
+    session_factory = async_sessionmaker(engine, expire_on_commit=False)
+
+    async def override_real_db():
+        async with session_factory() as session:
+            yield session
+
+    import api.data as data_api
+
+    expected_key = data_api._opaque_asset_key(
+        Email(
+            user_id=user_id,
+            organization_id=organization_id,
+            message_id=message_id,
+        ),
+        Attachment(filename="decision.hwpx"),
+    )
+    previous_override = app.dependency_overrides.get(get_db)
+    app.dependency_overrides[get_db] = override_real_db
+    try:
+        async with AsyncClient(
+            transport=ASGITransport(app=app),
+            headers={
+                "X-User-Id": user_id,
+                "X-Organization-Id": organization_id,
+            },
+            base_url="http://test",
+        ) as real_client:
+            detail = await real_client.get(f"/api/emails/{email_id}")
+            preview = await real_client.get(
+                f"/api/data/repository-assets/{expected_key}/preview"
+            )
+            hidden = await real_client.get(
+                "/api/data/repository-assets/asset_missing_mail_preview/preview"
+            )
+    finally:
+        if previous_override is None:
+            app.dependency_overrides.pop(get_db, None)
+        else:
+            app.dependency_overrides[get_db] = previous_override
+        await engine.dispose()
+
+    assert detail.status_code == 200, detail.text
+    attachments = detail.json()["attachments"]
+    assert len(attachments) == 1
+    assert attachments[0]["asset_key"] == expected_key
+    assert attachments[0]["file_name"] == "decision.hwpx"
+    assert "id" not in attachments[0]
+    assert preview.status_code == 200, preview.text
+    assert preview.json()["preview_state"] == "recognized"
+    assert preview.json()["paragraph_texts"] == [
+        "Quarterly decision record",
+        "Approve the next action.",
+    ]
+    assert hidden.status_code == 404
+    assert hidden.json()["detail"]["error_code"] == "repository_asset_not_found"
diff --git a/docs/doctoring/hwp-hwpx-attachment-recognition.md b/docs/doctoring/hwp-hwpx-attachment-recognition.md
index 32adf2c8d..30cf39a2e 100644
--- a/docs/doctoring/hwp-hwpx-attachment-recognition.md
+++ b/docs/doctoring/hwp-hwpx-attachment-recognition.md
@@ -176,6 +176,7 @@ traceability, not a substitute for current-head gates.
 | Deferred HWPX worker selection and local execution | `backend/services/newsdom_worker.py` | `test_hwpx_worker.py` | Active stacked PR #1373 |
 | Parsed attachment text + graph provenance | shared content-graph landing path | HWPX worker + recognizer tests | Active stacked PR #1373 |
 | Buyer-visible recognized HWPX paragraph preview | `backend/services/repository_asset_preview.py`, Data attachment view | `test_repository_asset_preview.py`, `RepositoryAssetPreviewPanel.test.tsx` | Active stacked preview PR |
+| Mail-detail HWPX preview via the same read-only contract | `backend/api/emails.py`, `MailAttachmentPreview` | `test_email_attachment_preview.py`, `MailAttachmentPreview.test.tsx` | Active stacked mail preview PR |
 | Binary HWP conversion | future sandboxed converter | none yet | Planned / out of this slice |
 | HWPX tables, images, layout fidelity | future bounded recognizers | none yet | Planned / out of this slice |
 | Protected-`develop` shipped HWP/HWPX recognition | protected branch | integrated release gates | Not yet shipped |
@@ -207,6 +208,19 @@ recognizer: KS X 6101/OWPML section and paragraph order is already persisted,
 and the UI only reads that order (Korean Agency for Technology and Standards,
 2024; Hancom Tech, 2025b, 2025c).
 
+## Buyer-visible mail attachment preview — stacked on PR #1404
+
+Recognized HWPX text that is only reachable from Data is not the core mail
+attachment experience. This slice lists the current email's attachments with
+the same opaque `asset_key` and opens the existing read-only preview contract.
+It does not reconstruct tables or images, convert binary HWP, call a model or
+NewsDOM, or change #1353/#1373/#1404 recognition or preview semantics.
+
+Pending HWPX still means wait or choose another file. Failed or unavailable
+preview still means choose another file. Missing text is never presented as
+empty document content. Unknown and cross-workspace resources remain one
+indistinguishable 404.
+
 ## Out of scope
 
 This slice does not reconstruct HWPX tables, images, charts, layout, styles, or
diff --git a/frontend/src/components/EmailDetail.test.tsx b/frontend/src/components/EmailDetail.test.tsx
index db2b617b6..77dcc9cb6 100644
--- a/frontend/src/components/EmailDetail.test.tsx
+++ b/frontend/src/components/EmailDetail.test.tsx
@@ -1278,6 +1278,74 @@ describe("EmailDetail", () => {
     )).toBe(true);
   });
 
+  it("lets a buyer open recognized HWPX paragraph text from a mail attachment", async () => {
+    const email = {
+      id: 44,
+      message_id: "<mail-hwpx@example.com>",
+      thread_id: null,
+      sender: "partner@example.com",
+      recipients: "user@example.com",
+      subject: "HWPX from inbox",
+      date: "2026-08-17T09:00:00Z",
+      body: "Please read the attached decision record.",
+      attachments: [
+        {
+          asset_key: "asset_mail_hwpx_recognized",
+          file_name: "decision.hwpx",
+          parser_family: "hwpx",
+        },
+      ],
+    };
+
+    const fetchMock = vi.fn((input: RequestInfo | URL) => {
+      const url = String(input);
+      if (url.endsWith("/api/emails/44")) return Promise.resolve(jsonResponse(email));
+      if (url.endsWith("/api/llm/summarize")) {
+        return Promise.resolve(jsonResponse({ summary: "첨부 결정문을 확인해야 합니다.", action_items: [] }));
+      }
+      if (url.endsWith("/api/data/repository-assets/asset_mail_hwpx_recognized/preview")) {
+        return Promise.resolve(jsonResponse({
+          asset_key: "asset_mail_hwpx_recognized",
+          asset_type: "email_attachment",
+          preview_state: "recognized",
+          parser_family: "hwpx",
+          paragraph_texts: ["Quarterly decision record", "Approve the next action."],
+          preview_text: "Quarterly decision record\n\nApprove the next action.",
+          next_action: "read_recognized_text",
+          error_code: null,
+          provider_write_executed: false,
+        }));
+      }
+      throw new Error(`Unexpected fetch: ${url}`);
+    });
+    vi.stubGlobal("fetch", fetchMock);
+
+    container = document.createElement("div");
+    document.body.appendChild(container);
+    root = createRoot(container);
+
+    await act(async () => {
+      root?.render(<EmailDetail emailId={44} />);
+    });
+    await flushAsyncWork();
+
+    const openButton = Array.from(container.querySelectorAll<HTMLButtonElement>("button")).find(
+      (button) => button.textContent?.includes("decision.hwpx"),
+    );
+    expect(openButton).not.toBeUndefined();
+
+    await act(async () => {
+      openButton?.click();
+    });
+    await flushAsyncWork();
+
+    expect(container.textContent).toContain("Quarterly decision record");
+    expect(container.textContent).toContain("Approve the next action.");
+    expect(container.textContent).toContain("인식된 본문");
+    expect(container.textContent).not.toContain("본문이 없습니다");
+    expect(container.textContent).not.toContain("asset_mail_hwpx_recognized");
+  });
+
   it("handles send message failure", async () => {
     const email: TestEmail = {
       id: 22,
diff --git a/frontend/src/components/EmailDetail.tsx b/frontend/src/components/EmailDetail.tsx
index e634a896c..92b563b6e 100644
--- a/frontend/src/components/EmailDetail.tsx
+++ b/frontend/src/components/EmailDetail.tsx
@@ -16,8 +16,10 @@ import {
   buildReplyPayload,
   formatEmailDate,
   getConversationMessages,
+  type MailAttachmentRef,
   type ThreadEmailData,
 } from "@/lib/email-threading";
+import { MailAttachmentPreview } from "@/components/MailAttachmentPreview";
 import { toMailBodyText, toMailDisplayText } from "@/lib/mail-text";
 import { toConfidencePercent } from "@/lib/confidence";
 import {
@@ -29,6 +31,7 @@ import {
 type EmailData = ThreadEmailData & {
   requires_reply?: boolean;
   schedule_conflict?: boolean;
+  attachments?: MailAttachmentRef[];
 };
 interface LlmData {
   summary: string;
@@ -652,6 +655,8 @@ export const EmailDetail = memo(function EmailDetail({ emailId, actionCommand =
       <ScrollArea className="flex-1">
         <div className="flex flex-col gap-6 bg-background/50 p-6 pb-[calc(7rem+env(safe-area-inset-bottom))] lg:pb-6">
 
+          <MailAttachmentPreview attachments={email.attachments ?? []} />
+
           <DecisionPointCard
             title="맥락 종합"
             icon={<span aria-hidden="true">✦</span>}
diff --git a/frontend/src/components/MailAttachmentPreview.test.tsx b/frontend/src/components/MailAttachmentPreview.test.tsx
new file mode 100644
index 000000000..72d5aded6
--- /dev/null
+++ b/frontend/src/components/MailAttachmentPreview.test.tsx
@@ -0,0 +1,208 @@
+/* @vitest-environment jsdom */
+import React, { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { MailAttachmentPreview } from "./MailAttachmentPreview";
+import type { MailAttachmentRef } from "@/lib/email-threading";
+
+function jsonResponse(body: unknown, status = 200) {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "Content-Type": "application/json" },
+  });
+}
+
+async function flushAsyncWork() {
+  for (let index = 0; index < 5; index += 1) {
+    await act(async () => {
+      await Promise.resolve();
+      await new Promise((resolve) => setTimeout(resolve, 0));
+    });
+  }
+}
+
+const recognizedAttachment: MailAttachmentRef = {
+  asset_key: "asset_mail_hwpx_recognized",
+  file_name: "decision.hwpx",
+  parser_family: "hwpx",
+};
+
+describe("MailAttachmentPreview", () => {
+  let root: Root | null = null;
+  let container: HTMLDivElement | null = null;
+
+  afterEach(() => {
+    if (root) act(() => root?.unmount());
+    root = null;
+    container?.remove();
+    container = null;
+    vi.unstubAllGlobals();
+  });
+
+  function renderPreview(attachments: MailAttachmentRef[]) {
+    container = document.createElement("div");
+    document.body.appendChild(container);
+    root = createRoot(container);
+    act(() => {
+      root?.render(<MailAttachmentPreview attachments={attachments} />);
+    });
+  }
+
+  it("opens recognized HWPX ordered paragraphs from the selected mail attachment", async () => {
+    const fetchMock = vi.fn((input: RequestInfo | URL) => {
+      const url = String(input);
+      if (url.endsWith("/api/data/repository-assets/asset_mail_hwpx_recognized/preview")) {
+        return Promise.resolve(jsonResponse({
+          asset_key: "asset_mail_hwpx_recognized",
+          asset_type: "email_attachment",
+          preview_state: "recognized",
+          parser_family: "hwpx",
+          paragraph_texts: ["Quarterly decision record", "Approve the next action."],
+          preview_text: "Quarterly decision record\n\nApprove the next action.",
+          next_action: "read_recognized_text",
+          error_code: null,
+          provider_write_executed: false,
+        }));
+      }
+      throw new Error(`Unexpected fetch: ${url}`);
+    });
+    vi.stubGlobal("fetch", fetchMock);
+
+    renderPreview([recognizedAttachment]);
+
+    const openButton = Array.from(container?.querySelectorAll("button") ?? []).find(
+      (button) => button.textContent?.includes("decision.hwpx"),
+    );
+    expect(openButton).toBeDefined();
+    expect(container?.textContent).toContain("첨부에서 파일을 선택하면 인식된 본문을 읽습니다");
+
+    await act(async () => {
+      openButton?.click();
+    });
+    await flushAsyncWork();
+
+    expect(fetchMock.mock.calls.map(([input]) => String(input))).toContain(
+      "/api/data/repository-assets/asset_mail_hwpx_recognized/preview",
+    );
+    const panel = container?.querySelector('[aria-label="선택한 자산 본문 미리보기"]');
+    expect(panel?.textContent).toContain("Quarterly decision record");
+    expect(panel?.textContent).toContain("Approve the next action.");
+    expect(panel?.textContent).toContain("인식된 본문");
+    expect(container?.textContent).not.toContain("본문이 없습니다");
+    expect(container?.textContent).not.toContain("asset_mail_hwpx_recognized");
+    expect(container?.textContent).not.toContain("99");
+  });
+
+  it("tells the buyer to wait when mail HWPX recognition is still pending", async () => {
+    vi.stubGlobal("fetch", vi.fn((input: RequestInfo | URL) => {
+      const url = String(input);
+      if (url.endsWith("/api/data/repository-assets/asset_mail_hwpx_pending/preview")) {
+        return Promise.resolve(jsonResponse({
+          asset_key: "asset_mail_hwpx_pending",
+          asset_type: "email_attachment",
+          preview_state: "pending",
+          parser_family: "hwpx",
+          paragraph_texts: [],
+          preview_text: null,
+          next_action: "wait_for_recognition",
+          error_code: "hwpx_recognition_pending",
+          provider_write_executed: false,
+        }));
+      }
+      throw new Error(`Unexpected fetch: ${url}`);
+    }));
+
+    renderPreview([{
+      asset_key: "asset_mail_hwpx_pending",
+      file_name: "pending.hwpx",
+      parser_family: "hwpx",
+    }]);
+
+    await act(async () => {
+      Array.from(container?.querySelectorAll("button") ?? []).find(
+        (button) => button.textContent?.includes("pending.hwpx"),
+      )?.click();
+    });
+    await flushAsyncWork();
+
+    const panel = container?.querySelector('[aria-label="선택한 자산 본문 미리보기"]');
+    expect(panel?.textContent).toContain("인식이 끝날 때까지 기다리거나 다른 파일을 선택하세요");
+    expect(panel?.querySelector("[data-preview-paragraphs]")).toBeNull();
+    expect(container?.textContent).not.toContain("본문이 없습니다");
+  });
+
+  it("tells the buyer to choose another file when mail HWPX preview failed", async () => {
+    vi.stubGlobal("fetch", vi.fn((input: RequestInfo | URL) => {
+      const url = String(input);
+      if (url.endsWith("/api/data/repository-assets/asset_mail_hwpx_failed/preview")) {
+        return Promise.resolve(jsonResponse({
+          asset_key: "asset_mail_hwpx_failed",
+          asset_type: "email_attachment",
+          preview_state: "failed",
+          parser_family: "hwpx",
+          paragraph_texts: [],
+          preview_text: null,
+          next_action: "choose_another_file",
+          error_code: "hwpx_recognition_failed",
+          provider_write_executed: false,
+        }));
+      }
+      throw new Error(`Unexpected fetch: ${url}`);
+    }));
+
+    renderPreview([{
+      asset_key: "asset_mail_hwpx_failed",
+      file_name: "failed.hwpx",
+      parser_family: "hwpx",
+    }]);
+
+    await act(async () => {
+      Array.from(container?.querySelectorAll("button") ?? []).find(
+        (button) => button.textContent?.includes("failed.hwpx"),
+      )?.click();
+    });
+    await flushAsyncWork();
+
+    const panel = container?.querySelector('[aria-label="선택한 자산 본문 미리보기"]');
+    expect(panel?.textContent).toContain("이 파일의 본문을 읽을 수 없습니다. 다른 파일을 선택하세요");
+    expect(panel?.querySelector("[data-preview-paragraphs]")).toBeNull();
+  });
+
+  it("fails closed on unmatched preview 404 without leaking existence", async () => {
+    vi.stubGlobal("fetch", vi.fn((input: RequestInfo | URL) => {
+      const url = String(input);
+      if (url.endsWith("/api/data/repository-assets/asset_missing_mail_preview/preview")) {
+        return Promise.resolve(jsonResponse({
+          detail: { error_code: "repository_asset_not_found" },
+        }, 404));
+      }
+      throw new Error(`Unexpected fetch: ${url}`);
+    }));
+
+    renderPreview([{
+      asset_key: "asset_missing_mail_preview",
+      file_name: "missing.hwpx",
+      parser_family: "hwpx",
+    }]);
+
+    await act(async () => {
+      Array.from(container?.querySelectorAll("button") ?? []).find(
+        (button) => button.textContent?.includes("missing.hwpx"),
+      )?.click();
+    });
+    await flushAsyncWork();
+
+    const panel = container?.querySelector('[aria-label="선택한 자산 본문 미리보기"]');
+    expect(panel?.textContent).toContain("미리보기를 열 수 없습니다. 다른 파일을 선택하세요");
+    expect(panel?.querySelector("[data-preview-paragraphs]")).toBeNull();
+    expect(container?.textContent).not.toContain("repository_asset_not_found");
+    expect(container?.textContent).not.toContain("본문이 없습니다");
+  });
+
+  it("renders nothing when the selected mail has no attachments", () => {
+    renderPreview([]);
+    expect(container?.querySelector('[aria-label="메일 첨부 파일"]')).toBeNull();
+    expect(container?.textContent).toBe("");
+  });
+});
diff --git a/frontend/src/components/MailAttachmentPreview.tsx b/frontend/src/components/MailAttachmentPreview.tsx
new file mode 100644
index 000000000..c8402f7d4
--- /dev/null
+++ b/frontend/src/components/MailAttachmentPreview.tsx
@@ -0,0 +1,96 @@
+import React, { useState } from 'react';
+import { apiClient } from '@/lib/api-client';
+import type { MailAttachmentRef } from '@/lib/email-threading';
+import { toMailDisplayText } from '@/lib/mail-text';
+import { RepositoryAssetPreviewPanel } from '@/components/data-layout/RepositoryAssetPreviewPanel';
+import type { RepositoryAssetPreview, RepositoryAssetPreviewNextAction } from '@/components/data-layout/types';
+import { getApiErrorStatus } from '@/components/data-layout/utils';
+
+type MailAttachmentPreviewProps = {
+  attachments: MailAttachmentRef[];
+};
+
+function unavailablePreview(assetKey: string): RepositoryAssetPreview {
+  return {
+    asset_key: assetKey,
+    asset_type: 'email_attachment',
+    preview_state: 'unavailable',
+    parser_family: null,
+    paragraph_texts: [],
+    preview_text: null,
+    next_action: 'choose_another_file' satisfies RepositoryAssetPreviewNextAction,
+    error_code: 'repository_asset_not_found',
+    provider_write_executed: false,
+  };
+}
+
+/** Open one mail attachment through the existing read-only repository preview. */
+export function MailAttachmentPreview({ attachments }: MailAttachmentPreviewProps) {
+  const [selectedAssetKey, setSelectedAssetKey] = useState<string | null>(null);
+  const [previewByKey, setPreviewByKey] = useState<Record<string, RepositoryAssetPreview>>({});
+
+  if (attachments.length === 0) {
+    return null;
+  }
+
+  const selectedAttachment = attachments.find((attachment) => attachment.asset_key === selectedAssetKey) ?? null;
+  const selectedPreview = selectedAttachment
+    ? previewByKey[selectedAttachment.asset_key] ?? null
+    : null;
+
+  const openAttachment = async (attachment: MailAttachmentRef) => {
+    setSelectedAssetKey(attachment.asset_key);
+    try {
+      const preview = await apiClient.get<RepositoryAssetPreview>(
+        `/api/data/repository-assets/${encodeURIComponent(attachment.asset_key)}/preview`,
+      );
+      setPreviewByKey((current) => ({ ...current, [attachment.asset_key]: preview }));
+    } catch (error: unknown) {
+      setPreviewByKey((current) => {
+        const existing = current[attachment.asset_key];
+        if (existing?.preview_state === 'recognized') {
+          return current;
+        }
+        return { ...current, [attachment.asset_key]: unavailablePreview(attachment.asset_key) };
+      });
+      void getApiErrorStatus(error);
+    }
+  };
+
+  return (
+    <section aria-label="메일 첨부 파일" className="space-y-3 rounded-2xl border border-border bg-card p-4 shadow-sm">
+      <div>
+        <h3 className="text-sm font-bold text-foreground">첨부 파일</h3>
+        <p className="mt-1 text-xs text-muted-foreground">
+          첨부에서 파일을 선택하면 인식된 본문을 읽습니다. 인식이 끝나지 않았으면 기다리거나 다른 파일을 선택하세요.
+        </p>
+      </div>
+      <ul className="grid gap-2">
+        {attachments.map((attachment) => {
+          const selected = selectedAssetKey === attachment.asset_key;
+          return (
+            <li key={attachment.asset_key}>
+              <button
+                type="button"
+                aria-pressed={selected}
+                aria-label={`${toMailDisplayText(attachment.file_name, '첨부 파일')} 인식된 본문 열기`}
+                onClick={() => void openAttachment(attachment)}
+                className={`w-full rounded-xl border px-3 py-2 text-left text-sm font-semibold focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring/40 ${
+                  selected ? 'border-primary bg-primary/5 text-foreground' : 'border-border bg-background text-foreground hover:border-primary/40'
+                }`}
+              >
+                {toMailDisplayText(attachment.file_name, '첨부 파일')}
+              </button>
+            </li>
+          );
+        })}
+      </ul>
+      {selectedAttachment ? (
+        <RepositoryAssetPreviewPanel
+          currentDetailText={selectedAttachment.file_name}
+          preview={selectedPreview}
+        />
+      ) : null}
+    </section>
+  );
+}
diff --git a/frontend/src/lib/email-threading.ts b/frontend/src/lib/email-threading.ts
index c9172cb9b..b6f11c86b 100644
--- a/frontend/src/lib/email-threading.ts
+++ b/frontend/src/lib/email-threading.ts
@@ -1,3 +1,10 @@
+/** Opaque mail-attachment handle that opens the read-only preview contract. */
+export interface MailAttachmentRef {
+  asset_key: string;
+  file_name: string;
+  parser_family: string | null;
+}
+
 export interface ThreadEmailData {
   id: number;
   subject: string | null;
@@ -9,6 +16,7 @@ export interface ThreadEmailData {
   message_id?: string | null;
   in_reply_to?: string | null;
   references?: string | null;
+  attachments?: MailAttachmentRef[];
 }
 
 export interface ReplyPayload {
diff --git a/frontend/tests/e2e/dashboard-flows.spec.ts b/frontend/tests/e2e/dashboard-flows.spec.ts
index f913d54c8..b8bc053ba 100644
--- a/frontend/tests/e2e/dashboard-flows.spec.ts
+++ b/frontend/tests/e2e/dashboard-flows.spec.ts
@@ -25,6 +25,21 @@ test('connects inbox selection to summary, execution, reply, calendar, and graph
   await expect(page.getByText('개발 모드에서 답장을 시뮬레이션했습니다. 실제 메일은 전송되지 않았습니다.')).toBeVisible();
 });
 
+test('opens recognized HWPX paragraph text from the selected mail attachment', async ({ page }, testInfo) => {
+  test.skip(testInfo.project.name !== 'desktop', 'Desktop mail attachment preview is covered by the desktop shell project.');
+  await mockDashboardApi(page);
+
+  await page.goto('/');
+  await page.getByRole('button', { name: '메일함 바로가기' }).first().click();
+  await page.getByRole('button', { name: /김지현 PM/ }).click();
+
+  await expect(page.getByRole('region', { name: '메일 첨부 파일' })).toBeVisible();
+  await page.getByRole('button', { name: 'decision.hwpx 인식된 본문 열기' }).click();
+  await expect(page.getByText('Quarterly decision record')).toBeVisible();
+  await expect(page.getByText('Approve the next action.')).toBeVisible();
+  await expect(page.getByText('본문이 없습니다')).toHaveCount(0);
+});
+
 test('submits branded inbox search against the search API', async ({ page }, testInfo) => {
   test.skip(testInfo.project.name !== 'desktop', 'Desktop search box is covered by the desktop shell project.');
   await mockDashboardApi(page);
diff --git a/frontend/tests/e2e/helpers.ts b/frontend/tests/e2e/helpers.ts
index 57549f932..ae897f912 100644
--- a/frontend/tests/e2e/helpers.ts
+++ b/frontend/tests/e2e/helpers.ts
@@ -24,6 +24,12 @@ const sibling = {
   body: '파트너 미팅 전까지 일정 확인이 필요합니다.',
 };
 
+const mailHwpxAttachment = {
+  asset_key: 'asset_mail_hwpx_recognized',
+  file_name: 'decision.hwpx',
+  parser_family: 'hwpx',
+};
+
 const sentEmail = {
   ...email,
   id: 31,
@@ -980,12 +986,17 @@ export async function mockDashboardApi(page: Page, onApiRequest?: (path: string,
     }
 
     if (path === '/api/emails/7') {
-      await fulfillJson(route, email);
+      await fulfillJson(route, { ...email, attachments: [mailHwpxAttachment] });
       return;
     }
 
     if (path === '/api/emails/thread/thread-q2') {
-      await fulfillJson(route, { thread: [email, sibling] });
+      await fulfillJson(route, {
+        thread: [
+          { ...email, attachments: [mailHwpxAttachment] },
+          { ...sibling, attachments: [] },
+        ],
+      });
       return;
     }
 
@@ -1326,6 +1337,20 @@ export async function mockDashboardApi(page: Page, onApiRequest?: (path: string,
         });
         return;
       }
+      if (assetKey === 'asset_mail_hwpx_recognized') {
+        await fulfillJson(route, {
+          asset_key: 'asset_mail_hwpx_recognized',
+          asset_type: 'email_attachment',
+          preview_state: 'recognized',
+          parser_family: 'hwpx',
+          paragraph_texts: ['Quarterly decision record', 'Approve the next action.'],
+          preview_text: 'Quarterly decision record\n\nApprove the next action.',
+          next_action: 'read_recognized_text',
+          error_code: null,
+          provider_write_executed: false,
+        });
+        return;
+      }
       if (assetKey === 'asset_repository_ready') {
         await fulfillJson(route, {
           asset_key: 'asset_repository_ready',

From b83a0da03b46a447f9710b5f91d245f5b1783dfa Mon Sep 17 00:00:00 2001
From: Cursor Agent <cursoragent@cursor.com>
Date: Tue, 18 Aug 2026 00:03:00 +0000
Subject: [PATCH 02/15] fix(mail): reuse live #1404 pending preview refresh
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Wire the inherited 다시 확인 control to re-fetch the same opaque mail
attachment preview so the stacked parent refresh stays reachable.

Co-authored-by: Seongho Bae <seonghobae@users.noreply.github.com>
---
 frontend/src/components/MailAttachmentPreview.tsx | 1 +
 1 file changed, 1 insertion(+)

diff --git a/frontend/src/components/MailAttachmentPreview.tsx b/frontend/src/components/MailAttachmentPreview.tsx
index c8402f7d4..e408294dc 100644
--- a/frontend/src/components/MailAttachmentPreview.tsx
+++ b/frontend/src/components/MailAttachmentPreview.tsx
@@ -89,6 +89,7 @@ export function MailAttachmentPreview({ attachments }: MailAttachmentPreviewProp
         <RepositoryAssetPreviewPanel
           currentDetailText={selectedAttachment.file_name}
           preview={selectedPreview}
+          onRefreshPreview={() => void openAttachment(selectedAttachment)}
         />
       ) : null}
     </section>

From 6878fc45c0b0861fa8433bfa7fa0de4417dd5e1f Mon Sep 17 00:00:00 2001
From: Seongho Bae <me@seonghobae.me>
Date: Sun, 6 Sep 2026 09:57:25 +0900
Subject: [PATCH 03/15] fix(docs): restore canonical AGENTS ownership

---
 AGENTS.md | 14 --------------
 1 file changed, 14 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 1a14c29bc..9104dd1f4 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -446,12 +446,6 @@ in this repo.
   topic components, or label evidence by a bare document, model, topic, rank,
   label, or display value.
 - When reviews find public/private identifier leaks, stale API fixture shapes, or recurring bug patterns, update tests, frontend mocks, E2E mocks, README examples, architecture docs, and explicitly record the anti-pattern in `AGENTS.md` so the same bug pattern does not reappear in copied examples.
-- Mail attachment surfaces must list the current email's files with opaque
-  `asset_key` values and open the signed
-  `/api/data/repository-assets/{asset_key}/preview` contract. Do not expose
-  sequential attachment ids, render missing preview text as empty document
-  content, or send buyers only to the Data repository list as a substitute for
-  opening the HWPX file on the selected mail.
 - Memoized id-to-record Maps must be first-wins (`if (!map.has(key)) map.set(...)`).
   `new Map(items.map((item) => [String(item.id), item]))` is last-wins and
   desynchronizes first-wins label maps from the selected node or edge when
@@ -599,14 +593,6 @@ in this repo.
   vector counts, unsupported embedding model names, static quality totals, or
   provider-write success claims; Data mocks and E2E fixtures must preserve the
   bearer-session call and omit public identity headers.
-- Repository-asset preview is read-only and scoped. Unknown keys and
-  cross-workspace access both return 404 `repository_asset_not_found` so
-  existence cannot leak. Recognized HWPX text comes from stored ordered
-  paragraphs; pending or failed recognition must keep the current asset detail
-  and show an explicit next action. Do not treat missing preview text as empty
-  content, and do not fetch preview indiscriminately in E2E helpers — mock
-  known assets such as `roadmap.md` and `blank-notes.md`, then fail unmatched
-  preview routes closed.
 - Project workspace lists, milestones, task links, and decision logs must be
   source-backed by signed `/api/webdav/folders` and `/api/tasks` data or
   explicitly labeled pending. Do not reintroduce static project names, inert

From 55f489a298ce727c4d09f59ff61a1d3e5726aad1 Mon Sep 17 00:00:00 2001
From: Seongho Bae <me@seonghobae.me>
Date: Sun, 6 Sep 2026 10:03:53 +0900
Subject: [PATCH 04/15] docs(mail): restore mail preview traceability

---
 docs/doctoring/hwp-hwpx-attachment-recognition.md | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/docs/doctoring/hwp-hwpx-attachment-recognition.md b/docs/doctoring/hwp-hwpx-attachment-recognition.md
index 7a64d71e0..3f8b04b27 100644
--- a/docs/doctoring/hwp-hwpx-attachment-recognition.md
+++ b/docs/doctoring/hwp-hwpx-attachment-recognition.md
@@ -188,6 +188,7 @@ traceability, not a substitute for current-head gates.
 | Deferred HWPX worker selection and local execution | `backend/services/newsdom_worker.py` | `test_hwpx_worker.py` | Active stacked PR #1373 |
 | Parsed attachment text + graph provenance | shared content-graph landing path | HWPX worker + recognizer tests | Active stacked PR #1373 |
 | Buyer-visible recognized HWPX paragraph preview | `backend/services/repository_asset_preview.py`, Data attachment view | `test_repository_asset_preview.py`, `RepositoryAssetPreviewPanel.test.tsx` | Active stacked preview PR |
+| Mail-detail HWPX preview via the same read-only contract | `backend/api/emails.py`, `MailAttachmentPreview` | `test_email_attachment_preview.py`, `MailAttachmentPreview.test.tsx` | Active stacked mail preview PR |
 | Binary HWP conversion | future sandboxed converter | none yet | Planned / out of this slice |
 | HWPX tables, images, layout fidelity | future bounded recognizers | none yet | Planned / out of this slice |
 | Protected-`develop` shipped HWP/HWPX recognition | protected branch | integrated release gates | Not yet shipped |
@@ -219,6 +220,19 @@ recognizer: KS X 6101/OWPML section and paragraph order is already persisted,
 and the UI only reads that order (Korean Agency for Technology and Standards,
 2024; Hancom Tech, 2025b, 2025c).
 
+## Buyer-visible mail attachment preview — stacked on PR #1404
+
+Recognized HWPX text that is only reachable from Data is not the core mail
+attachment experience. This slice lists the current email's attachments with
+the same opaque `asset_key` and opens the existing read-only preview contract.
+It does not reconstruct tables or images, convert binary HWP, call a model or
+NewsDOM, or change #1353/#1373/#1404 recognition or preview semantics.
+
+Pending HWPX still means wait or choose another file. Failed or unavailable
+preview still means choose another file. Missing text is never presented as
+empty document content. Unknown and cross-workspace resources remain one
+indistinguishable 404.
+
 ## Out of scope
 
 This slice does not reconstruct HWPX tables, images, charts, layout, styles, or

From 0edb98fb810b8a2fbfec7cb6fb0a199df26a6463 Mon Sep 17 00:00:00 2001
From: Seongho Bae <me@seonghobae.me>
Date: Sun, 6 Sep 2026 10:04:33 +0900
Subject: [PATCH 05/15] merge(mail): restore preview E2E fixture delta

---
 frontend/tests/e2e/helpers.ts | 29 +++++++++++++++++++++++++++--
 1 file changed, 27 insertions(+), 2 deletions(-)

diff --git a/frontend/tests/e2e/helpers.ts b/frontend/tests/e2e/helpers.ts
index 57549f932..ae897f912 100644
--- a/frontend/tests/e2e/helpers.ts
+++ b/frontend/tests/e2e/helpers.ts
@@ -24,6 +24,12 @@ const sibling = {
   body: '파트너 미팅 전까지 일정 확인이 필요합니다.',
 };
 
+const mailHwpxAttachment = {
+  asset_key: 'asset_mail_hwpx_recognized',
+  file_name: 'decision.hwpx',
+  parser_family: 'hwpx',
+};
+
 const sentEmail = {
   ...email,
   id: 31,
@@ -980,12 +986,17 @@ export async function mockDashboardApi(page: Page, onApiRequest?: (path: string,
     }
 
     if (path === '/api/emails/7') {
-      await fulfillJson(route, email);
+      await fulfillJson(route, { ...email, attachments: [mailHwpxAttachment] });
       return;
     }
 
     if (path === '/api/emails/thread/thread-q2') {
-      await fulfillJson(route, { thread: [email, sibling] });
+      await fulfillJson(route, {
+        thread: [
+          { ...email, attachments: [mailHwpxAttachment] },
+          { ...sibling, attachments: [] },
+        ],
+      });
       return;
     }
 
@@ -1326,6 +1337,20 @@ export async function mockDashboardApi(page: Page, onApiRequest?: (path: string,
         });
         return;
       }
+      if (assetKey === 'asset_mail_hwpx_recognized') {
+        await fulfillJson(route, {
+          asset_key: 'asset_mail_hwpx_recognized',
+          asset_type: 'email_attachment',
+          preview_state: 'recognized',
+          parser_family: 'hwpx',
+          paragraph_texts: ['Quarterly decision record', 'Approve the next action.'],
+          preview_text: 'Quarterly decision record\n\nApprove the next action.',
+          next_action: 'read_recognized_text',
+          error_code: null,
+          provider_write_executed: false,
+        });
+        return;
+      }
       if (assetKey === 'asset_repository_ready') {
         await fulfillJson(route, {
           asset_key: 'asset_repository_ready',

From cc7d2cefd41aff24bac1a1a94d3a0205984816c1 Mon Sep 17 00:00:00 2001
From: Seongho Bae <me@seonghobae.me>
Date: Sun, 6 Sep 2026 21:44:35 +0900
Subject: [PATCH 06/15] fix(mail): preserve current preview parent tree

---
 backend/api/data.py                           |  63 ++++----
 .../tests/test_repository_asset_preview.py    |  10 ++
 ..._asset_preview_scope_streaming_contract.py | 153 ++++++++++++++++++
 3 files changed, 192 insertions(+), 34 deletions(-)
 create mode 100644 backend/tests/test_repository_asset_preview_scope_streaming_contract.py

diff --git a/backend/api/data.py b/backend/api/data.py
index 81c52d3a1..bee59aca4 100644
--- a/backend/api/data.py
+++ b/backend/api/data.py
@@ -73,8 +73,7 @@
     "knowledge_graph_edges.edge_kind, content_segments.segment_path"
 )
 SEMANTIC_RELATION_SOURCE_BACKING_EVIDENCE_SOURCE = (
-    "sender_relationships.source_message_id, "
-    "sender_relationships.source_thread_id"
+    "sender_relationships.source_message_id, sender_relationships.source_thread_id"
 )
 WEB_DAV_ERROR_STATUS_CODES = {
     "no_webdav_account": 422,
@@ -1801,9 +1800,7 @@ def _diligence_close_decision_summary(
     snapshot: DataEvidenceSnapshotResponse,
 ) -> DataDiligenceCloseDecisionSummary:
     proof_plan = snapshot.diligence_close_proof_plan
-    blocked = [
-        item for item in proof_plan if item.close_gate_status == "blocked"
-    ]
+    blocked = [item for item in proof_plan if item.close_gate_status == "blocked"]
     ready = [item for item in proof_plan if item.close_gate_status == "ready"]
     required_artifacts = sorted(
         {item.required_proof_artifact for item in proof_plan}
@@ -1983,9 +1980,7 @@ def _diligence_close_traceability_map(
         risk_key = proof.proof_key.removeprefix("proof_")
         risk = risk_by_key[risk_key]
         manifest = manifest_by_file[proof.required_proof_artifact]
-        artifact_review = artifact_review_by_artifact[
-            proof.required_proof_artifact
-        ]
+        artifact_review = artifact_review_by_artifact[proof.required_proof_artifact]
         owner_handoff = owner_handoff_by_owner[proof.owner_area]
         source_field = manifest.source_field
         data_room_artifact = proof.required_proof_artifact
@@ -2337,8 +2332,6 @@ def _materialized_document_target_path(document: Document) -> str:
     return f"/Naruon/Data/{filename}"
 
 
-# Document statuses whose stored content is not yet materializable parsed text
-# (it may be a base64 binary payload awaiting a recognition/conversion worker).
 _NON_MATERIALIZABLE_DOCUMENT_STATUSES = frozenset(
     {
         PDF_DOM_RECOGNITION_PENDING_STATUS,
@@ -2502,6 +2495,22 @@ def _email_scope_filter(auth_context: AuthContext) -> EmailScopeFilter:
     return (Email.user_id == auth_context.user_id, organization_filter)
 
 
+def _document_scope_filter(
+    auth_context: AuthContext,
+) -> tuple[ColumnElement[bool], ColumnElement[bool]]:
+    """Return signed workspace and nullable-organization document predicates."""
+
+    organization_filter = (
+        Document.organization_id == auth_context.organization_id
+        if auth_context.organization_id is not None
+        else Document.organization_id.is_(None)
+    )
+    return (
+        Document.workspace_id == auth_context.workspace_id,
+        organization_filter,
+    )
+
+
 async def _scoped_rows(db: AsyncSession, statement):
     result = await db.execute(statement)
     return list(result.scalars().all())
@@ -2520,7 +2529,7 @@ async def _get_workspace_document(
     result = await db.execute(
         select(Document).where(
             Document.document_id == document_id,
-            Document.workspace_id == auth_context.workspace_id,
+            *_document_scope_filter(auth_context),
         )
     )
     document = result.scalar_one_or_none()
@@ -2534,12 +2543,12 @@ async def _find_workspace_document(
     auth_context: AuthContext,
     document_id: str,
 ) -> Document | None:
-    """Return a workspace-scoped document, or None without leaking other workspaces."""
+    """Return a signed-tenant document without leaking other workspace/org rows."""
 
     result = await db.execute(
         select(Document).where(
             Document.document_id == document_id,
-            Document.workspace_id == auth_context.workspace_id,
+            *_document_scope_filter(auth_context),
         )
     )
     return result.scalar_one_or_none()
@@ -3392,14 +3401,12 @@ async def create_document_pdf_dom_recognition_intent(
 )
 async def upload_document_for_pdf_dom_recognition(
     file: UploadFile = File(...),
-    # Declared as multipart form data (not a query parameter) so a client
-    # sending document_name alongside the file is honored.
     document_name: str | None = Form(None),
     auth_context: AuthContext = Depends(get_auth_context),
     db: AsyncSession = Depends(get_db),
 ) -> DataDocumentActionResponse:
-    """Binary upload variant: accept a PDF, stash it pending, and defer the
-    heavy NewsDOM recognition to the worker."""
+    """Accept a bounded PDF upload and defer heavy DOM recognition to the worker."""
+
     raw = await file.read(_MAX_PDF_DOM_UPLOAD_BYTES + 1)
     if len(raw) > _MAX_PDF_DOM_UPLOAD_BYTES:
         raise HTTPException(status_code=413, detail="PDF upload is too large.")
@@ -3432,10 +3439,8 @@ async def upload_document_for_pdf_dom_recognition(
 
 
 def decode_pending_pdf_document_bytes(document: Document) -> bytes:
-    """Decode the base64 PDF payload stashed by the binary upload variant.
+    """Decode the base64 PDF payload stashed by the binary upload variant."""
 
-    Used by the recognition worker before calling the NewsDOM sidecar.
-    """
     try:
         payload = base64.b64decode(
             (document.document_content or "").encode("ascii"), validate=True
@@ -3461,11 +3466,6 @@ async def create_document_webdav_materialization_intent(
 ) -> DataDocumentWebdavMaterializationResponse:
     document = await _get_workspace_document(db, auth_context, document_id)
     if document.document_status in _NON_MATERIALIZABLE_DOCUMENT_STATUSES:
-        # A document whose recognition/conversion is still pending holds a
-        # non-text payload (e.g. the base64 PDF stashed for the NewsDOM worker).
-        # Materializing it as Markdown would write that raw payload to the
-        # customer's WebDAV target. Refuse until recognition has landed real
-        # parsed text.
         raise HTTPException(
             status_code=409,
             detail=(
@@ -3510,9 +3510,6 @@ async def _get_email_stats(
     db: AsyncSession,
     email_scope: EmailScopeFilter,
 ) -> EmailQualityStats:
-    # ⚡ Bolt Optimization: Batching scalar counts using CASE
-    # Impact: Reduces 7 sequential database queries down to 2, drastically cutting
-    # latency from network roundtrips when fetching quality surface metrics.
     email_stats_result = await db.execute(
         select(
             func.count(Email.id),
@@ -4032,13 +4029,13 @@ async def get_repository_asset_preview(
         return _preview_response(build_document_preview(asset_key, document))
 
     email_scope = _email_scope_filter(auth_context)
-    candidate_result = await db.execute(
+    candidate_result = await db.stream(
         select(Attachment.id, Attachment.filename, Email)
         .join(Email)
         .where(*email_scope)
         .execution_options(yield_per=500)
     )
-    for attachment_id, filename, email in candidate_result:
+    async for attachment_id, filename, email in candidate_result:
         if _opaque_asset_key_for_filename(email, filename) != asset_key:
             continue
         if not _email_matches_preview_scope(email, auth_context):
@@ -4081,7 +4078,7 @@ async def get_data_quality_surface(
     documents = await _scoped_rows(
         db,
         select(Document)
-        .where(Document.workspace_id == auth_context.workspace_id)
+        .where(*_document_scope_filter(auth_context))
         .order_by(Document.created_at.desc(), Document.document_id.asc())
         .limit(8),
     )
@@ -4127,9 +4124,7 @@ async def get_data_quality_surface(
     edged_email_count = knowledge_graph_stats.edged_email_count
     knowledge_graph_edge_count = knowledge_graph_stats.edge_count
     semantic_relation_count = semantic_relation_stats.total_count
-    semantic_relation_source_backed_count = (
-        semantic_relation_stats.source_backed_count
-    )
+    semantic_relation_source_backed_count = semantic_relation_stats.source_backed_count
     parsed_attachment_count = attachment_parse_stats.parsed_count
     unparsed_attachment_count = attachment_parse_stats.unparsed_count
 
diff --git a/backend/tests/test_repository_asset_preview.py b/backend/tests/test_repository_asset_preview.py
index 98c8bcfec..ec595acb2 100644
--- a/backend/tests/test_repository_asset_preview.py
+++ b/backend/tests/test_repository_asset_preview.py
@@ -59,6 +59,13 @@ def all(self):
     def __iter__(self):
         return iter(self.all())
 
+    def __aiter__(self):
+        async def _rows():
+            for row in self.all():
+                yield row
+
+        return _rows()
+
     def scalar_one_or_none(self):
         if isinstance(self.obj, list):
             return self.obj[0] if self.obj else None
@@ -120,6 +127,9 @@ async def execute(self, query):
             ]
         )
 
+    async def stream(self, query):
+        return await self.execute(query)
+
 
 def _base64url_encode(data: bytes) -> str:
     """Encode JWT segments without padding."""
diff --git a/backend/tests/test_repository_asset_preview_scope_streaming_contract.py b/backend/tests/test_repository_asset_preview_scope_streaming_contract.py
new file mode 100644
index 000000000..4f28358c4
--- /dev/null
+++ b/backend/tests/test_repository_asset_preview_scope_streaming_contract.py
@@ -0,0 +1,153 @@
+"""Regression contracts for repository-asset preview isolation and streaming.
+
+These tests deliberately exercise the query boundary rather than a permissive
+mock of ``AsyncSession.execute``. Document reads and mutations must include the
+signed organization scope, and a ``yield_per`` attachment scan must use the
+asynchronous streaming API.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import pytest
+from fastapi import HTTPException
+
+from api import data as data_api
+from api.auth import AuthContext
+
+
+class _ScalarResult:
+    """Minimal scalar result used to capture document lookup statements."""
+
+    def __init__(self, value: object | None) -> None:
+        self._value = value
+
+    def scalar_one_or_none(self) -> object | None:
+        return self._value
+
+
+class _CaptureDocumentSession:
+    """Capture the exact SQL statement used for a workspace-document lookup."""
+
+    def __init__(self) -> None:
+        self.statement: Any | None = None
+
+    async def execute(self, statement: Any) -> _ScalarResult:
+        self.statement = statement
+        return _ScalarResult(None)
+
+
+class _EmptyAsyncRows:
+    """Asynchronous row iterator for an attachment scan with no matching row."""
+
+    def __aiter__(self):
+        async def _rows():
+            if False:  # pragma: no cover - keeps this an async generator.
+                yield None
+
+        return _rows()
+
+
+class _StreamingOnlyPreviewSession:
+    """Reject attachment candidate scans sent through ``execute``."""
+
+    def __init__(self) -> None:
+        self.streamed_statements: list[Any] = []
+
+    async def execute(self, statement: Any) -> _ScalarResult:
+        rendered = str(statement).lower()
+        if "workspace_documents" in rendered:
+            return _ScalarResult(None)
+        if "email_attachments" in rendered:
+            raise AssertionError(
+                "yield_per attachment candidates must use AsyncSession.stream"
+            )
+        return _ScalarResult(None)
+
+    async def stream(self, statement: Any) -> _EmptyAsyncRows:
+        self.streamed_statements.append(statement)
+        return _EmptyAsyncRows()
+
+
+def _auth_context(*, organization_id: str | None) -> AuthContext:
+    return AuthContext(
+        user_id="member-a",
+        role="member",
+        organization_id=organization_id,
+        group_ids=("group-data",),
+        workspace_id="workspace-shared",
+    )
+
+
+def _assert_document_statement_scope(
+    statement: Any,
+    organization_id: str | None,
+) -> None:
+    sql = str(statement).lower()
+    assert "workspace_documents.workspace_id" in sql
+    assert "workspace_documents.organization_id" in sql
+    if organization_id is None:
+        assert "workspace_documents.organization_id is null" in sql
+    else:
+        params = statement.compile().params
+        assert organization_id in params.values()
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("organization_id", ["org-acme", None])
+async def test_document_preview_lookup_carries_signed_organization_scope(
+    organization_id: str | None,
+) -> None:
+    """Workspace id alone is not a tenant boundary for preview reads."""
+
+    session = _CaptureDocumentSession()
+
+    await data_api._find_workspace_document(
+        session,  # type: ignore[arg-type]
+        _auth_context(organization_id=organization_id),
+        "doc-shared",
+    )
+
+    assert session.statement is not None
+    _assert_document_statement_scope(session.statement, organization_id)
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("organization_id", ["org-acme", None])
+async def test_document_mutation_lookup_carries_signed_organization_scope(
+    organization_id: str | None,
+) -> None:
+    """Status-changing document actions must use the same tenant boundary."""
+
+    session = _CaptureDocumentSession()
+
+    with pytest.raises(HTTPException) as exc_info:
+        await data_api._get_workspace_document(
+            session,  # type: ignore[arg-type]
+            _auth_context(organization_id=organization_id),
+            "doc-shared",
+        )
+
+    assert exc_info.value.status_code == 404
+    assert session.statement is not None
+    _assert_document_statement_scope(session.statement, organization_id)
+
+
+@pytest.mark.asyncio
+async def test_attachment_preview_streams_yield_per_candidates() -> None:
+    """A yield-per candidate scan must not go through AsyncSession.execute."""
+
+    session = _StreamingOnlyPreviewSession()
+
+    with pytest.raises(HTTPException) as exc_info:
+        await data_api.get_repository_asset_preview(
+            "asset_missing_preview_key",
+            _auth_context(organization_id="org-acme"),
+            session,  # type: ignore[arg-type]
+        )
+
+    assert exc_info.value.status_code == 404
+    assert len(session.streamed_statements) == 1
+    execution_options = session.streamed_statements[0].get_execution_options()
+    assert execution_options.get("yield_per") == 500

From 63fd00a9382c47f8e530a8c47b43f2988f80f9f7 Mon Sep 17 00:00:00 2001
From: Seongho Bae <me@seonghobae.me>
Date: Sun, 6 Sep 2026 21:45:42 +0900
Subject: [PATCH 07/15] test(mail): forbid attachment-body loads in detail and
 thread

---
 .../tests/test_email_attachment_preview.py    | 30 +++++++++++++++++--
 1 file changed, 28 insertions(+), 2 deletions(-)

diff --git a/backend/tests/test_email_attachment_preview.py b/backend/tests/test_email_attachment_preview.py
index 0a64a967d..9b1110c0f 100644
--- a/backend/tests/test_email_attachment_preview.py
+++ b/backend/tests/test_email_attachment_preview.py
@@ -203,12 +203,12 @@ async def test_email_detail_without_attachments_returns_empty_list(
 @pytest.mark.asyncio
 @pytest.mark.postgres
 async def test_email_detail_preview_postgres_smoke_lists_opaque_hwpx_key() -> None:
-    """Mail detail returns the same opaque key the scoped preview can open."""
+    """Mail detail returns the same opaque key without loading attachment bodies."""
 
     import uuid
 
     import asyncpg
-    from sqlalchemy import text
+    from sqlalchemy import event, text
     from sqlalchemy.exc import OperationalError
     from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine
 
@@ -312,6 +312,15 @@ async def override_real_db():
     )
     previous_override = app.dependency_overrides.get(get_db)
     app.dependency_overrides[get_db] = override_real_db
+    attachment_selects: list[str] = []
+
+    def capture_attachment_select(
+        conn, cursor, statement: str, parameters, context, executemany
+    ) -> None:
+        if "from email_attachments" in statement.lower().replace('"', ""):
+            attachment_selects.append(statement)
+
+    event.listen(engine.sync_engine, "before_cursor_execute", capture_attachment_select)
     try:
         async with AsyncClient(
             transport=ASGITransport(app=app),
@@ -322,6 +331,13 @@ async def override_real_db():
             base_url="http://test",
         ) as real_client:
             detail = await real_client.get(f"/api/emails/{email_id}")
+            detail_attachment_selects = tuple(attachment_selects)
+            attachment_selects.clear()
+            thread = await real_client.get(
+                "/api/emails/thread/thread-mail-preview-hwpx"
+            )
+            thread_attachment_selects = tuple(attachment_selects)
+            attachment_selects.clear()
             preview = await real_client.get(
                 f"/api/data/repository-assets/{expected_key}/preview"
             )
@@ -329,6 +345,9 @@ async def override_real_db():
                 "/api/data/repository-assets/asset_missing_mail_preview/preview"
             )
     finally:
+        event.remove(
+            engine.sync_engine, "before_cursor_execute", capture_attachment_select
+        )
         if previous_override is None:
             app.dependency_overrides.pop(get_db, None)
         else:
@@ -341,6 +360,13 @@ async def override_real_db():
     assert attachments[0]["asset_key"] == expected_key
     assert attachments[0]["file_name"] == "decision.hwpx"
     assert "id" not in attachments[0]
+    assert thread.status_code == 200, thread.text
+    assert len(thread.json()["thread"]) == 1
+    assert detail_attachment_selects
+    assert thread_attachment_selects
+    for statement in (*detail_attachment_selects, *thread_attachment_selects):
+        normalized_statement = statement.lower().replace('"', "")
+        assert "email_attachments.content" not in normalized_statement
     assert preview.status_code == 200, preview.text
     assert preview.json()["preview_state"] == "recognized"
     assert preview.json()["paragraph_texts"] == [

From 6d3bcc5afe0e6e0ccea9c03e03f2e7496f81947a Mon Sep 17 00:00:00 2001
From: Seongho Bae <me@seonghobae.me>
Date: Sun, 6 Sep 2026 21:47:58 +0900
Subject: [PATCH 08/15] fix(mail): load attachment metadata without bodies

---
 backend/api/emails.py | 16 +++++++++++++---
 1 file changed, 13 insertions(+), 3 deletions(-)

diff --git a/backend/api/emails.py b/backend/api/emails.py
index e1ddef19b..048cf448b 100644
--- a/backend/api/emails.py
+++ b/backend/api/emails.py
@@ -5,7 +5,7 @@
 from sqlalchemy import func, or_, select
 from sqlalchemy.orm import selectinload
 from db.session import get_db
-from db.models import Email
+from db.models import Attachment, Email
 from api.data import _opaque_asset_key
 from pydantic import BaseModel, EmailStr, Field, field_validator
 import datetime
@@ -167,6 +167,16 @@ def _email_list_item(
     )
 
 
+def _mail_attachment_load_option():
+    """Load only metadata required to render mail attachment references."""
+
+    return selectinload(Email.attachments).load_only(
+        Attachment.filename,
+        Attachment.parser_key,
+        raiseload=True,
+    )
+
+
 def _mail_attachment_refs(email: Email) -> list["EmailAttachmentRef"]:
     """Return opaque, display-safe attachment refs for one scoped email."""
 
@@ -674,7 +684,7 @@ async def get_email(
     # Ensure auth context validates the request payload and scopes access
     result = await db.execute(
         select(Email)
-        .options(selectinload(Email.attachments))
+        .options(_mail_attachment_load_option())
         .where(
             Email.id == email_id,
             *Email.owner_filters(auth_context.user_id, auth_context.organization_id),
@@ -698,7 +708,7 @@ async def get_email_thread(
     lookup_values = thread_lookup_values(thread_id)
     result = await db.execute(
         select(Email)
-        .options(selectinload(Email.attachments))
+        .options(_mail_attachment_load_option())
         .where(
             *Email.owner_filters(auth_context.user_id, auth_context.organization_id),
             or_(

From 7615754fb9a49b3378db6d73f5093e9f53660e19 Mon Sep 17 00:00:00 2001
From: Seongho Bae <me@seonghobae.me>
Date: Sun, 6 Sep 2026 21:49:44 +0900
Subject: [PATCH 09/15] test(mail): clean PostgreSQL preview smoke rows

---
 backend/tests/test_email_attachment_preview.py | 11 ++++++++++-
 1 file changed, 10 insertions(+), 1 deletion(-)

diff --git a/backend/tests/test_email_attachment_preview.py b/backend/tests/test_email_attachment_preview.py
index 9b1110c0f..ea9c1fa45 100644
--- a/backend/tests/test_email_attachment_preview.py
+++ b/backend/tests/test_email_attachment_preview.py
@@ -315,7 +315,7 @@ async def override_real_db():
     attachment_selects: list[str] = []
 
     def capture_attachment_select(
-        conn, cursor, statement: str, parameters, context, executemany
+        _conn, _cursor, statement: str, _parameters, _context, _executemany
     ) -> None:
         if "from email_attachments" in statement.lower().replace('"', ""):
             attachment_selects.append(statement)
@@ -352,6 +352,15 @@ def capture_attachment_select(
             app.dependency_overrides.pop(get_db, None)
         else:
             app.dependency_overrides[get_db] = previous_override
+        async with engine.begin() as cleanup_conn:
+            await cleanup_conn.execute(
+                text("DELETE FROM email_attachments WHERE email_id = :email_id"),
+                {"email_id": email_id},
+            )
+            await cleanup_conn.execute(
+                text("DELETE FROM email_records WHERE id = :email_id"),
+                {"email_id": email_id},
+            )
         await engine.dispose()
 
     assert detail.status_code == 200, detail.text

From bc24bf682ff6998610db39c90dc644cfeb8baad5 Mon Sep 17 00:00:00 2001
From: Seongho Bae <me@seonghobae.me>
Date: Sun, 6 Sep 2026 21:52:37 +0900
Subject: [PATCH 10/15] test(mail): keep latest attachment preview response

---
 .../components/MailAttachmentPreview.test.tsx | 66 ++++++++++++++++++-
 1 file changed, 65 insertions(+), 1 deletion(-)

diff --git a/frontend/src/components/MailAttachmentPreview.test.tsx b/frontend/src/components/MailAttachmentPreview.test.tsx
index 72d5aded6..babcf2852 100644
--- a/frontend/src/components/MailAttachmentPreview.test.tsx
+++ b/frontend/src/components/MailAttachmentPreview.test.tsx
@@ -200,9 +200,73 @@ describe("MailAttachmentPreview", () => {
     expect(container?.textContent).not.toContain("본문이 없습니다");
   });
 
+  it("keeps the latest recognized preview when an older pending response arrives late", async () => {
+    let resolveFirst!: (response: Response) => void;
+    let resolveSecond!: (response: Response) => void;
+    const firstResponse = new Promise<Response>((resolve) => {
+      resolveFirst = resolve;
+    });
+    const secondResponse = new Promise<Response>((resolve) => {
+      resolveSecond = resolve;
+    });
+    const fetchMock = vi
+      .fn()
+      .mockReturnValueOnce(firstResponse)
+      .mockReturnValueOnce(secondResponse);
+    vi.stubGlobal("fetch", fetchMock);
+
+    renderPreview([recognizedAttachment]);
+    const openButton = Array.from(container?.querySelectorAll("button") ?? []).find(
+      (button) => button.textContent?.includes("decision.hwpx"),
+    );
+    expect(openButton).toBeDefined();
+
+    await act(async () => {
+      openButton?.click();
+    });
+    await act(async () => {
+      openButton?.click();
+    });
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+
+    await act(async () => {
+      resolveSecond(jsonResponse({
+        asset_key: "asset_mail_hwpx_recognized",
+        asset_type: "email_attachment",
+        preview_state: "recognized",
+        parser_family: "hwpx",
+        paragraph_texts: ["Latest recognized paragraph"],
+        preview_text: "Latest recognized paragraph",
+        next_action: "read_recognized_text",
+        error_code: null,
+        provider_write_executed: false,
+      }));
+    });
+    await flushAsyncWork();
+    expect(container?.textContent).toContain("Latest recognized paragraph");
+
+    await act(async () => {
+      resolveFirst(jsonResponse({
+        asset_key: "asset_mail_hwpx_recognized",
+        asset_type: "email_attachment",
+        preview_state: "pending",
+        parser_family: "hwpx",
+        paragraph_texts: [],
+        preview_text: null,
+        next_action: "wait_for_recognition",
+        error_code: "hwpx_recognition_pending",
+        provider_write_executed: false,
+      }));
+    });
+    await flushAsyncWork();
+
+    expect(container?.textContent).toContain("Latest recognized paragraph");
+    expect(container?.textContent).not.toContain("인식이 끝날 때까지 기다리거나 다른 파일을 선택하세요");
+  });
+
   it("renders nothing when the selected mail has no attachments", () => {
     renderPreview([]);
     expect(container?.querySelector('[aria-label="메일 첨부 파일"]')).toBeNull();
     expect(container?.textContent).toBe("");
   });
-});
+});
\ No newline at end of file

From 298bbba1fd8f3b4dcb9cdc7ac50bb6f2dd3e472e Mon Sep 17 00:00:00 2001
From: Seongho Bae <me@seonghobae.me>
Date: Sun, 6 Sep 2026 21:54:32 +0900
Subject: [PATCH 11/15] fix(mail): ignore stale attachment preview responses

---
 .../src/components/MailAttachmentPreview.tsx  | 26 ++++++++++++++-----
 1 file changed, 19 insertions(+), 7 deletions(-)

diff --git a/frontend/src/components/MailAttachmentPreview.tsx b/frontend/src/components/MailAttachmentPreview.tsx
index e408294dc..8c7a815a2 100644
--- a/frontend/src/components/MailAttachmentPreview.tsx
+++ b/frontend/src/components/MailAttachmentPreview.tsx
@@ -1,4 +1,4 @@
-import React, { useState } from 'react';
+import React, { useRef, useState } from 'react';
 import { apiClient } from '@/lib/api-client';
 import type { MailAttachmentRef } from '@/lib/email-threading';
 import { toMailDisplayText } from '@/lib/mail-text';
@@ -28,6 +28,7 @@ function unavailablePreview(assetKey: string): RepositoryAssetPreview {
 export function MailAttachmentPreview({ attachments }: MailAttachmentPreviewProps) {
   const [selectedAssetKey, setSelectedAssetKey] = useState<string | null>(null);
   const [previewByKey, setPreviewByKey] = useState<Record<string, RepositoryAssetPreview>>({});
+  const requestSequenceByAsset = useRef<Record<string, number>>({});
 
   if (attachments.length === 0) {
     return null;
@@ -39,19 +40,30 @@ export function MailAttachmentPreview({ attachments }: MailAttachmentPreviewProp
     : null;
 
   const openAttachment = async (attachment: MailAttachmentRef) => {
-    setSelectedAssetKey(attachment.asset_key);
+    const assetKey = attachment.asset_key;
+    const requestSequence = (requestSequenceByAsset.current[assetKey] ?? 0) + 1;
+    requestSequenceByAsset.current[assetKey] = requestSequence;
+    const isLatestRequest = () => requestSequenceByAsset.current[assetKey] === requestSequence;
+
+    setSelectedAssetKey(assetKey);
     try {
       const preview = await apiClient.get<RepositoryAssetPreview>(
-        `/api/data/repository-assets/${encodeURIComponent(attachment.asset_key)}/preview`,
+        `/api/data/repository-assets/${encodeURIComponent(assetKey)}/preview`,
       );
-      setPreviewByKey((current) => ({ ...current, [attachment.asset_key]: preview }));
+      if (!isLatestRequest()) {
+        return;
+      }
+      setPreviewByKey((current) => ({ ...current, [assetKey]: preview }));
     } catch (error: unknown) {
+      if (!isLatestRequest()) {
+        return;
+      }
       setPreviewByKey((current) => {
-        const existing = current[attachment.asset_key];
+        const existing = current[assetKey];
         if (existing?.preview_state === 'recognized') {
           return current;
         }
-        return { ...current, [attachment.asset_key]: unavailablePreview(attachment.asset_key) };
+        return { ...current, [assetKey]: unavailablePreview(assetKey) };
       });
       void getApiErrorStatus(error);
     }
@@ -94,4 +106,4 @@ export function MailAttachmentPreview({ attachments }: MailAttachmentPreviewProp
       ) : null}
     </section>
   );
-}
+}
\ No newline at end of file

From b0ba575ac6927b6b92fa8edf5b823e82ad268400 Mon Sep 17 00:00:00 2001
From: Seongho Bae <me@seonghobae.me>
Date: Sun, 6 Sep 2026 21:55:08 +0900
Subject: [PATCH 12/15] chore(mail): preserve preview source newline

---
 frontend/src/components/MailAttachmentPreview.tsx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/frontend/src/components/MailAttachmentPreview.tsx b/frontend/src/components/MailAttachmentPreview.tsx
index 8c7a815a2..c88d90cc8 100644
--- a/frontend/src/components/MailAttachmentPreview.tsx
+++ b/frontend/src/components/MailAttachmentPreview.tsx
@@ -106,4 +106,4 @@ export function MailAttachmentPreview({ attachments }: MailAttachmentPreviewProp
       ) : null}
     </section>
   );
-}
\ No newline at end of file
+}

From c5fde35c937a6eb5a5d63d6ee3b28bce3c6c9183 Mon Sep 17 00:00:00 2001
From: Seongho Bae <me@seonghobae.me>
Date: Sun, 6 Sep 2026 21:56:01 +0900
Subject: [PATCH 13/15] chore(mail): preserve preview test newline

---
 frontend/src/components/MailAttachmentPreview.test.tsx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/frontend/src/components/MailAttachmentPreview.test.tsx b/frontend/src/components/MailAttachmentPreview.test.tsx
index babcf2852..385ca5cad 100644
--- a/frontend/src/components/MailAttachmentPreview.test.tsx
+++ b/frontend/src/components/MailAttachmentPreview.test.tsx
@@ -269,4 +269,4 @@ describe("MailAttachmentPreview", () => {
     expect(container?.querySelector('[aria-label="메일 첨부 파일"]')).toBeNull();
     expect(container?.textContent).toBe("");
   });
-});
\ No newline at end of file
+});

From 501d019e1ae0efde3b5df333047fda4fdd88b971 Mon Sep 17 00:00:00 2001
From: Seongho Bae <me@seonghobae.me>
Date: Sun, 6 Sep 2026 21:59:33 +0900
Subject: [PATCH 14/15] test(mail): exercise real signed attachment session

---
 .../test_email_attachment_preview_auth.py     | 145 ++++++++++++++++++
 1 file changed, 145 insertions(+)
 create mode 100644 backend/tests/test_email_attachment_preview_auth.py

diff --git a/backend/tests/test_email_attachment_preview_auth.py b/backend/tests/test_email_attachment_preview_auth.py
new file mode 100644
index 000000000..c2560649a
--- /dev/null
+++ b/backend/tests/test_email_attachment_preview_auth.py
@@ -0,0 +1,145 @@
+"""Signed-session coverage for mail attachment metadata endpoints."""
+
+from __future__ import annotations
+
+import datetime
+import time
+
+import jwt
+import pytest
+import pytest_asyncio
+from httpx import ASGITransport, AsyncClient
+
+from api.auth import SESSION_AUDIENCE, SESSION_ISSUER
+from core.config import settings
+from db.models import Attachment, Email
+from db.session import get_db
+from main import app
+
+
+class _SignedMailMockSession:
+    """Return one tenant-scoped email while authentication stays production-real."""
+
+    def __init__(self, email: Email):
+        self.email = email
+
+    async def execute(self, query, params=None):
+        class _MockResult:
+            def __init__(self, email: Email):
+                self.email = email
+
+            def scalar_one_or_none(self):
+                return self.email
+
+            def scalars(self):
+                return self
+
+            def all(self):
+                return [self.email]
+
+        return _MockResult(self.email)
+
+
+def _signed_mail_email() -> Email:
+    email = Email(
+        id=51,
+        user_id="signed-mail-user",
+        organization_id="org-signed-mail",
+        message_id="<signed-mail-preview@example.com>",
+        thread_id="thread-signed-mail-preview",
+        sender="partner@example.com",
+        recipients="owner@example.com",
+        subject="Signed HWPX preview",
+        date=datetime.datetime.now(datetime.timezone.utc),
+        body="Open the recognized attachment.",
+    )
+    email.attachments = [
+        Attachment(
+            id=151,
+            email_id=51,
+            filename="decision.hwpx",
+            parser_key="hwpx",
+        )
+    ]
+    return email
+
+
+def _signed_session_token() -> str:
+    configured_secret = settings.AUTH_SESSION_HMAC_SECRET
+    assert configured_secret is not None
+    now = int(time.time())
+    return jwt.encode(
+        {
+            "ver": 1,
+            "iss": SESSION_ISSUER,
+            "aud": SESSION_AUDIENCE,
+            "iat": now,
+            "exp": now + 600,
+            "sub": "signed-mail-user",
+            "role": "member",
+            "org": "org-signed-mail",
+            "groups": [],
+            "workspace": "workspace-org-signed-mail",
+        },
+        configured_secret.get_secret_value(),
+        algorithm="HS256",
+    )
+
+
+@pytest.fixture(autouse=True)
+def override_mail_db():
+    email = _signed_mail_email()
+    app.dependency_overrides[get_db] = lambda: _SignedMailMockSession(email)
+    yield
+    app.dependency_overrides.pop(get_db, None)
+
+
+@pytest_asyncio.fixture
+async def client():
+    async with AsyncClient(
+        transport=ASGITransport(app=app),
+        base_url="http://test",
+    ) as async_client:
+        yield async_client
+
+
+@pytest.mark.asyncio
+async def test_email_attachment_detail_uses_real_signed_bearer_session(
+    client: AsyncClient,
+) -> None:
+    """A valid HMAC bearer session authorizes attachment metadata without identity headers."""
+
+    response = await client.get(
+        "/api/emails/51",
+        headers={"Authorization": f"Bearer {_signed_session_token()}"},
+    )
+
+    assert response.status_code == 200, response.text
+    payload = response.json()
+    assert payload["id"] == 51
+    assert payload["attachments"] == [
+        {
+            "asset_key": payload["attachments"][0]["asset_key"],
+            "file_name": "decision.hwpx",
+            "parser_family": "hwpx",
+        }
+    ]
+    assert payload["attachments"][0]["asset_key"].startswith("asset_")
+
+
+@pytest.mark.asyncio
+async def test_email_attachment_detail_rejects_public_identity_headers_without_session(
+    client: AsyncClient,
+) -> None:
+    """Public identity headers cannot substitute for the signed bearer session."""
+
+    response = await client.get(
+        "/api/emails/51",
+        headers={
+            "X-User-Id": "signed-mail-user",
+            "X-Organization-Id": "org-signed-mail",
+        },
+    )
+
+    assert response.status_code == 401
+    assert response.json()["detail"] == "Authentication required"

From edd3134a197fe819df366b469a2a4a1c5b27b4f7 Mon Sep 17 00:00:00 2001
From: Seongho Bae <me@seonghobae.me>
Date: Sun, 6 Sep 2026 21:59:56 +0900
Subject: [PATCH 15/15] test(mail): verify cookie-backed attachment preview
 path

---
 .../tests/e2e/mail-attachment-session.spec.ts | 50 +++++++++++++++++++
 1 file changed, 50 insertions(+)
 create mode 100644 frontend/tests/e2e/mail-attachment-session.spec.ts

diff --git a/frontend/tests/e2e/mail-attachment-session.spec.ts b/frontend/tests/e2e/mail-attachment-session.spec.ts
new file mode 100644
index 000000000..9d7c1f3ec
--- /dev/null
+++ b/frontend/tests/e2e/mail-attachment-session.spec.ts
@@ -0,0 +1,50 @@
+import { expect, test } from '@playwright/test';
+
+import { mockDashboardApi } from './helpers';
+
+const PUBLIC_IDENTITY_HEADERS = [
+  'x-user-id',
+  'x-organization-id',
+  'x-group-id',
+  'x-group-ids',
+  'x-user-role',
+  'x-dev-auth-token',
+];
+
+function expectCookieSession(headers: Record<string, string>, token: string) {
+  expect(headers.authorization).toBeUndefined();
+  expect(headers.cookie ?? '').toContain(`naruon_session=${token}`);
+  for (const headerName of PUBLIC_IDENTITY_HEADERS) {
+    expect(headers[headerName]).toBeUndefined();
+  }
+}
+
+test('opens a mail HWPX preview through the cookie-backed signed API path', async ({ page }, testInfo) => {
+  test.skip(testInfo.project.name !== 'desktop', 'The mail detail interaction is owned by the desktop shell project.');
+  const sessionToken = 'signed-mail-attachment.preview.token';
+  await page.addInitScript((token) => {
+    document.cookie = `naruon_session=${token}; Path=/; SameSite=Lax`;
+  }, sessionToken);
+  await mockDashboardApi(page);
+
+  const detailRequest = page.waitForRequest((request) => {
+    const url = new URL(request.url());
+    return url.pathname === '/api/emails/7' && request.method() === 'GET';
+  });
+
+  await page.goto('/');
+  await page.getByRole('button', { name: '메일함 바로가기' }).first().click();
+  await page.getByRole('button', { name: /김지현 PM/ }).click();
+  expectCookieSession((await detailRequest).headers(), sessionToken);
+
+  const previewRequest = page.waitForRequest((request) => {
+    const url = new URL(request.url());
+    return url.pathname === '/api/data/repository-assets/asset_mail_hwpx_recognized/preview'
+      && request.method() === 'GET';
+  });
+  await page.getByRole('button', { name: 'decision.hwpx 인식된 본문 열기' }).click();
+  expectCookieSession((await previewRequest).headers(), sessionToken);
+
+  await expect(page.getByText('Quarterly decision record')).toBeVisible();
+  await expect(page.getByText('Approve the next action.')).toBeVisible();
+});