@micha.bigler/ui-core-micha 2.18.0 → 2.20.0

package/tests/messagingDirectMessageLauncher.test.jsx

@@ -55,6 +55,47 @@ describe('DirectMessageLauncher', () => {
     await waitFor(() => expect(screen.queryByRole('dialog')).toBeNull());
   });
 
+  it('uses the selected candidate scope over the launcher scope', () => {
+    const api = { createDirectConversation: vi.fn().mockResolvedValue({ id: 41, kind: 'direct' }) };
+    renderLauncher({
+      api,
+      candidates: [
+        { id: 2, display_name: 'Alex', scope: 'scope-a' },
+        { id: 3, display_name: 'Sam', scope: 'scope-b' },
+      ],
+      scope: 'scope-prop',
+    });
+    openPicker();
+    fireEvent.click(screen.getByText('Sam'));
+    fireEvent.click(screen.getByRole('button', { name: 'MessagingDirect.START' }));
+    expect(api.createDirectConversation).toHaveBeenCalledWith({ target_user_id: 3, scope: 'scope-b' });
+  });
+
+  it('falls back to the launcher scope when the selected candidate has none', () => {
+    const api = { createDirectConversation: vi.fn().mockResolvedValue({ id: 41, kind: 'direct' }) };
+    renderLauncher({
+      api,
+      candidates: [
+        { id: 2, display_name: 'Alex' },
+        { id: 3, display_name: 'Sam', scope: 'scope-b' },
+      ],
+      scope: 'scope-prop',
+    });
+    openPicker();
+    fireEvent.click(screen.getByText('Alex'));
+    fireEvent.click(screen.getByRole('button', { name: 'MessagingDirect.START' }));
+    expect(api.createDirectConversation).toHaveBeenCalledWith({ target_user_id: 2, scope: 'scope-prop' });
+  });
+
+  it('omits scope when neither the candidate nor launcher provides one', () => {
+    const api = { createDirectConversation: vi.fn().mockResolvedValue({ id: 41, kind: 'direct' }) };
+    renderLauncher({ api });
+    openPicker();
+    fireEvent.click(screen.getByText('Alex'));
+    fireEvent.click(screen.getByRole('button', { name: 'MessagingDirect.START' }));
+    expect(Object.keys(api.createDirectConversation.mock.calls[0][0])).toEqual(['target_user_id']);
+  });
+
   it('surfaces a policy rejection without closing the picker', async () => {
     const api = { createDirectConversation: vi.fn().mockRejectedValue({ response: { data: { detail: 'Direct messages are restricted.' } } }) };
     renderLauncher({ api });

package/tests/messagingThreadReceipts.test.jsx

@@ -0,0 +1,170 @@
+// @vitest-environment jsdom
+import fs from 'node:fs';
+import path from 'node:path';
+import React from 'react';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react';
+
+vi.mock('react-i18next', () => ({ useTranslation: () => ({ t: (key, options) => options?.count !== undefined ? `${key}:${options.count}` : key, i18n: { language: 'en' } }) }));
+
+const realtimeSubscribers = new Map();
+vi.mock('../src/notifications/realtime', () => ({
+  useRealtime: () => ({
+    subscribe: (envelope, handler) => { realtimeSubscribers.set(envelope, handler); return () => realtimeSubscribers.delete(envelope); },
+    onReconnect: () => () => {},
+  }),
+}));
+function dispatchMessagingFrame(frame) { realtimeSubscribers.get('messaging')?.(frame); }
+
+import { ConversationList } from '../src/messaging/ConversationList';
+import { Thread } from '../src/messaging/Thread';
+import { applyFrame, MessagingProvider } from '../src/messaging/MessagingProvider';
+
+// Server-shaped serialize_message output (django_core_micha/messaging/
+// serializers.py:80-95): reply_count/last_reply_at always present;
+// thread_last_read_at is REST-only and never on a frame — copied from the
+// real _message_response/_message_page_response wiring in views.py, not
+// hand-invented.
+function serverRoot(overrides = {}) {
+  return { id: 'root-1', conversation_id: 'conv-1', body: 'Root', sender_id: 'user-1', kind: 'chat', reply_count: 1, last_reply_at: '2026-08-01T09:00:00Z', thread_last_read_at: null, ...overrides };
+}
+function serverReply(overrides = {}) {
+  return { id: 'reply-1', conversation_id: 'conv-1', body: 'Reply', sender_id: 'user-2', kind: 'chat', reply_to_id: 'root-1', reply_count: 0, last_reply_at: null, created_at: '2026-08-01T10:00:00Z', ...overrides };
+}
+function baseApi(overrides = {}) {
+  return {
+    listConversations: vi.fn().mockResolvedValue({ results: [] }), listMessages: vi.fn().mockResolvedValue({ results: [] }),
+    getUnreadCount: vi.fn().mockResolvedValue({ unread_count: 0, by_conversation: {} }),
+    markConversationRead: vi.fn().mockResolvedValue({}), markThreadRead: vi.fn(),
+    ...overrides,
+  };
+}
+
+afterEach(() => { cleanup(); realtimeSubscribers.clear(); });
+
+describe('the merge trap — thread_last_read_at must survive frames that never carry it', () => {
+  function cache() { return { conversations: {}, messages: {}, threads: {}, polls: {}, reactions: {}, receipts: {}, unread: { unread_count: 0, by_conversation: {} }, cursors: { conversations: null, messages: {}, threads: {} } }; }
+
+  it('a server-shaped message frame does not wipe a previously-fetched thread_last_read_at on an unrelated root', () => {
+    const state = { ...cache(), messages: { 'root-1': serverRoot({ thread_last_read_at: '2026-08-01T08:00:00Z' }) } };
+    // A brand-new, unrelated root message frame — server-shaped, no
+    // thread_last_read_at key, exactly as serialize_message emits it.
+    const next = applyFrame(state, { envelope: 'messaging', type: 'message', event_id: 'evt-1', conversation_id: 'conv-1', message: serverRoot({ id: 'root-2', thread_last_read_at: undefined, reply_to_id: undefined }) }, 'conv-1');
+    expect(next.messages['root-1'].thread_last_read_at).toBe('2026-08-01T08:00:00Z');
+  });
+
+  it('a server-shaped message_edited frame does not wipe the edited root\'s own thread_last_read_at', () => {
+    const state = { ...cache(), messages: { 'root-1': serverRoot({ thread_last_read_at: '2026-08-01T08:00:00Z', body: 'Before' }) } };
+    const edited = serverRoot({ body: 'After', thread_last_read_at: undefined });
+    delete edited.thread_last_read_at;
+    const next = applyFrame(state, { envelope: 'messaging', type: 'message_edited', event_id: 'evt-2', conversation_id: 'conv-1', message_id: 'root-1', message: edited }, null);
+    expect(next.messages['root-1'].thread_last_read_at).toBe('2026-08-01T08:00:00Z');
+    expect(next.messages['root-1'].body).toBe('After');
+  });
+
+  it('a reply frame bumping a cached root\'s reply_count/last_reply_at does not wipe that root\'s thread_last_read_at — the WO\'s highest-risk path', () => {
+    // The receipt is deliberately NEWER than the incoming reply, so
+    // hasUnreadReplies-style logic would already read "read" before this
+    // frame — if the bump wiped thread_last_read_at to null/undefined instead
+    // of preserving it, that derived read-state would flip, which this
+    // assertion catches directly (unlike a marker-visibility assertion,
+    // which can't distinguish "correctly still read" from "field wiped to
+    // null" — both render no marker).
+    const state = { ...cache(), messages: { 'root-1': serverRoot({ reply_count: 1, last_reply_at: '2026-08-01T08:00:00Z', thread_last_read_at: '2026-08-01T09:00:00Z' }) } };
+    const next = applyFrame(state, { envelope: 'messaging', type: 'message', event_id: 'evt-4', conversation_id: 'conv-1', message: serverReply({ id: 'reply-2', created_at: '2026-08-01T10:00:00Z' }) }, 'conv-1');
+    expect(next.messages['root-1'].reply_count).toBe(2);
+    expect(next.messages['root-1'].last_reply_at).toBe('2026-08-01T10:00:00Z');
+    expect(next.messages['root-1'].thread_last_read_at).toBe('2026-08-01T09:00:00Z');
+  });
+});
+
+describe('unread-reply marker logic', () => {
+  it('shows when last_reply_at is newer than the receipt', async () => {
+    const api = baseApi({ listMessages: vi.fn().mockResolvedValue({ results: [serverRoot({ last_reply_at: '2026-08-01T10:00:00Z', thread_last_read_at: '2026-08-01T09:00:00Z' })] }) });
+    render(<MessagingProvider api={api} activeConversationId="conv-1"><Thread conversationId="conv-1" /></MessagingProvider>);
+    await screen.findByText('Root');
+    expect(screen.getByLabelText(/MessagingThread.UNREAD_REPLIES/)).toBeTruthy();
+  });
+
+  it('hides when the receipt is equal to or newer than last_reply_at', async () => {
+    const api = baseApi({ listMessages: vi.fn().mockResolvedValue({ results: [serverRoot({ last_reply_at: '2026-08-01T09:00:00Z', thread_last_read_at: '2026-08-01T10:00:00Z' })] }) });
+    render(<MessagingProvider api={api} activeConversationId="conv-1"><Thread conversationId="conv-1" /></MessagingProvider>);
+    await screen.findByText('Root');
+    expect(screen.queryByLabelText(/MessagingThread.UNREAD_REPLIES/)).toBeNull();
+  });
+
+  it('shows when the receipt is null and reply_count > 0', async () => {
+    const api = baseApi({ listMessages: vi.fn().mockResolvedValue({ results: [serverRoot({ thread_last_read_at: null, reply_count: 2, last_reply_at: '2026-08-01T09:00:00Z' })] }) });
+    render(<MessagingProvider api={api} activeConversationId="conv-1"><Thread conversationId="conv-1" /></MessagingProvider>);
+    await screen.findByText('Root');
+    expect(screen.getByLabelText(/MessagingThread.UNREAD_REPLIES/)).toBeTruthy();
+  });
+
+  it('renders no toggle and no marker at all when reply_count is 0', async () => {
+    const api = baseApi({ listMessages: vi.fn().mockResolvedValue({ results: [serverRoot({ reply_count: 0, last_reply_at: null, thread_last_read_at: null })] }) });
+    render(<MessagingProvider api={api} activeConversationId="conv-1"><Thread conversationId="conv-1" /></MessagingProvider>);
+    await screen.findByText('Root');
+    expect(screen.queryByText(/MessagingThread\.SHOW_REPLIES/)).toBeNull();
+    expect(screen.queryByLabelText(/MessagingThread.UNREAD_REPLIES/)).toBeNull();
+  });
+});
+
+describe('opening a thread marks it read from the REST response', () => {
+  it('issues the REST read call and updates the cached receipt from last_read_at', async () => {
+    const api = baseApi({
+      listMessages: vi.fn().mockResolvedValue({ results: [serverRoot({ thread_last_read_at: null, reply_count: 1, last_reply_at: '2026-08-01T09:00:00Z' })] }),
+      listThread: vi.fn().mockResolvedValue({ results: [] }),
+      markThreadRead: vi.fn().mockResolvedValue({ last_read_at: '2026-08-01T12:00:00Z' }),
+    });
+    render(<MessagingProvider api={api} activeConversationId="conv-1"><Thread conversationId="conv-1" /></MessagingProvider>);
+    await screen.findByText('Root');
+    expect(screen.getByLabelText(/MessagingThread.UNREAD_REPLIES/)).toBeTruthy();
+    fireEvent.click(screen.getByText(/MessagingThread\.SHOW_REPLIES/));
+    await waitFor(() => expect(api.markThreadRead).toHaveBeenCalledWith('root-1', undefined));
+    await waitFor(() => expect(screen.queryByLabelText(/MessagingThread.UNREAD_REPLIES/)).toBeNull());
+  });
+});
+
+describe('live root update on an incoming reply', () => {
+  it('raises reply_count/last_reply_at on the cached root and the marker appears without a refetch when the sender is not the viewer', async () => {
+    const api = baseApi({ listMessages: vi.fn().mockResolvedValue({ results: [serverRoot({ reply_count: 1, last_reply_at: '2026-08-01T08:00:00Z', thread_last_read_at: '2026-08-01T08:30:00Z' })] }) });
+    render(<MessagingProvider api={api} activeConversationId="conv-1"><Thread conversationId="conv-1" /></MessagingProvider>);
+    await screen.findByText(/MessagingThread\.SHOW_REPLIES:1/);
+    expect(screen.queryByLabelText(/MessagingThread.UNREAD_REPLIES/)).toBeNull();
+    // A new reply from someone else — server-shaped message frame with
+    // reply_to_id naming the cached root.
+    dispatchMessagingFrame({ envelope: 'messaging', type: 'message', event_id: 'evt-3', conversation_id: 'conv-1', message: serverReply() });
+    await waitFor(() => expect(screen.getByText(/MessagingThread\.SHOW_REPLIES:2/)).toBeTruthy());
+    expect(screen.getByLabelText(/MessagingThread.UNREAD_REPLIES/)).toBeTruthy();
+  });
+});
+
+describe('managed-conversation identity (row 42)', () => {
+  it('renders two managed conversations with different external_key as distinguishable via a host resolver', async () => {
+    const api = baseApi({
+      listConversations: vi.fn().mockResolvedValue({ results: [
+        { id: 'c1', kind: 'managed', external_key: 'all' },
+        { id: 'c2', kind: 'managed', external_key: 'team' },
+      ] }),
+    });
+    render(<MessagingProvider api={api}><ConversationList resolveManagedLabel={(conversation) => conversation.external_key === 'all' ? 'Everyone' : 'My team'} /></MessagingProvider>);
+    await screen.findByText('Everyone');
+    expect(screen.getByText('My team')).toBeTruthy();
+  });
+
+  it('falls back to the existing title behavior when no resolver is supplied', async () => {
+    const api = baseApi({ listConversations: vi.fn().mockResolvedValue({ results: [{ id: 'c1', kind: 'managed', external_key: 'all', title: 'Fallback title' }] }) });
+    render(<MessagingProvider api={api}><ConversationList /></MessagingProvider>);
+    await screen.findByText('Fallback title');
+  });
+
+  it('no jg-specific vocabulary (event_all, event_team) appears anywhere in src/', () => {
+    const root = path.resolve(import.meta.dirname, '..', 'src');
+    const files = fs.readdirSync(root, { recursive: true }).filter((file) => typeof file === 'string' && /\.(jsx?|tsx?)$/.test(file));
+    const offenders = files.filter((file) => {
+      const contents = fs.readFileSync(path.join(root, file), 'utf8');
+      return /event_all|event_team/.test(contents);
+    });
+    expect(offenders).toEqual([]);
+  });
+});

package/tests/messagingUnreadLifecycle.test.jsx

@@ -45,7 +45,10 @@ describe('messaging unread lifecycle', () => {
   it('marks a reply thread read when it expands', async () => {
     const api = makeApi({ listMessages: vi.fn().mockResolvedValue({ results: [{ id: 40, conversation_id: 12, body: 'Root', reply_count: 1 }] }) });
     render(<MessagingProvider api={api} activeConversationId={12}><Thread conversationId={12} /></MessagingProvider>);
-    fireEvent.click(await screen.findByRole('button', { name: 'MessagingThread.SHOW_REPLIES' }));
+    // No thread_last_read_at in this fixture — the unread-reply marker
+    // (MSG-3d) correctly treats a null receipt with replies as unread, which
+    // changes the button's accessible name to include the marker text.
+    fireEvent.click(await screen.findByRole('button', { name: /MessagingThread\.SHOW_REPLIES/ }));
     await waitFor(() => expect(api.markThreadRead).toHaveBeenCalledWith(40, undefined));
   });
 

package/work-orders/DX-1.md

@@ -1,6 +1,9 @@
 # DX-1 — minimal Vite dev harness for ucm components
 
-Status: planned · Tier 1 (dev-only tooling; **adds devDependencies → approval-gated**) · Target repo: `ui-core-micha` (main)
+Status: done · **Tier 2** (dev-only tooling; **adds devDependencies → approval-gated**) · Target repo: `ui-core-micha` (main)
+*Reclassified 2026-08-01: labelled Tier 1 at authoring, but it adds dependencies in a shared-core
+repo — two binding Tier-2 surfaces per AGENTS.md's Tiering gate. A named independent `reviewer` did
+run (one P2 on the provider's own WebSocket), so only the label was wrong.*
 
 ---
 

package/work-orders/MSG-3d.md

@@ -0,0 +1,268 @@
+# MSG-3d — the last two blocked rows: unread-reply marker and managed-conversation identity
+
+Status: planned · Tier 2 · Target repo: `ui-core-micha` (main)
+**Binding spec:** `django-core-micha/docs/design/messaging-platform.md` — §"Thread reply state and
+managed-conversation identity" and §Realtime's consumer obligation. Extends the landed MSG-3c
+(published ucm 2.18.0), same convention as `MSG-2b` / `MSG-3b` / `MSG-3c`.
+
+---
+
+## Part A — Envelope (Expertenchat, 2026-08-01)
+
+### Goal
+
+Deliver checklist rows **27** and **42** — the last two entries still marked BLOCKED in
+`docs/messaging-deviations.md`. dcm 2.38.0 (MSG-2d) shipped the contract they were waiting for, on the
+same day MSG-3c closed. After this WO the deviation doc has **zero** BLOCKED entries.
+
+### Verified deliverable against dcm 2.38.0
+
+Checked in `django-core-micha` before this WO was written (`serializers.py`):
+
+| Row | Was blocked on | Present in 2.38.0 |
+|---|---|---|
+| 27 | no readable thread reply state | `reply_count` + `last_reply_at` on `serialize_message` (viewer-independent), `thread_last_read_at` added REST-only |
+| 42 | `external_key` not serialized | `external_key` on `serialize_conversation_core` |
+
+### Expected outcome
+
+**Row 27 — unread-reply marker on the thread toggle.** Render the marker when
+`last_reply_at > thread_last_read_at`; a `null` receipt with at least one reply counts as unread; no
+replies means no toggle and no marker. `reply_count` gives the toggle its count without expanding the
+thread. Opening a thread marks it read and updates the receipt **from the REST response** to
+`POST messages/{root_id}/thread/read/` — not from a frame, which cannot carry it.
+
+**Live root update on an incoming reply.** A new reply arrives as a `message` frame carrying *the
+reply's* projection — its own `reply_count` is 0 and `last_reply_at` null. Nothing in the frame updates
+the **root's** counters, so without explicit handling the marker only appears after the next refetch.
+jg updates the root live (`Thread.jsx:1488-1537`: increments `reply_count` and marks the thread unread
+when the sender is someone else), so parity requires the same here: on a `message` frame whose
+`reply_to_id` names a cached root, increment that root's `reply_count` and advance its `last_reply_at`.
+This was a gap in the first draft of this envelope, surfaced by review — do not leave it to discovery.
+
+**Row 42 — distinguish managed conversations.** Surface `external_key` so a host can tell one managed
+conversation from another. **ucm must not know what the values mean.** `event_all` and `event_team` are
+jg's vocabulary, not the platform's; baking them in would put app-specific code in a consumer-agnostic
+package and break the first non-jg adopter. Expose the value and let the host supply label and icon,
+mirroring the existing `groupLaunchers` host-supplied pattern.
+
+**Deviation doc.** Rows 27 and 42 move from BLOCKED to delivered. The doc then contains no BLOCKED
+entries at all — confirm MSG-3c's version-pin conformance check still passes on an empty set rather
+than erroring or vacuously "passing" for the wrong reason.
+
+### The trap this WO walks into — read before writing any merge code
+
+`thread_last_read_at` is **viewer-specific and REST-only**. `reply_count` and `last_reply_at` ride
+`serialize_message`, which is embedded verbatim into the `message` and `message_edited` frames. So every
+such frame carries a message projection **with** the reply fields and **without** the receipt.
+
+That is precisely the defect shape MSG-3c just fixed three times (`poll_updated`'s `voted_option_ids`,
+the `reaction` frame's `reacted` flags, `toggleReaction`'s REST confirm): a viewer-independent
+projection replacing a cached object and silently wiping viewer-specific state. This WO introduces a
+**fourth field of that shape**, arriving immediately after those fixes. Merge field-wise, preserve
+`thread_last_read_at`, never replace the message object wholesale — the contract obligation is now
+written into design §Realtime. It has a mandatory test below.
+
+### Non-goals / do-not-touch
+
+Any dcm change. Any app-specific vocabulary in ucm (see row 42). App-side code, the jg migration
+(MSG-5), search, typing, client→server WS. The component boundaries from MSG-3 — the marker belongs to
+whichever component owns the thread toggle, not to a regrown `Thread`; the ~400 LOC soft trigger and
+one-harness-entry-per-component rule stay in force. Do not re-open rows already delivered or already
+recorded as deliberate deviations.
+
+### Required tests to WRITE
+
+- **The merge trap (load-bearing):** a `message` and a `message_edited` frame — **server-shaped, copied
+  from real `serialize_message` output**, therefore without `thread_last_read_at` — must leave a
+  previously-fetched receipt intact. Assert the cached value after the merge, not just that no error
+  was thrown.
+- **Marker logic:** shown when `last_reply_at > thread_last_read_at`; hidden when the receipt is equal
+  or newer; shown when the receipt is `null` and `reply_count > 0`; absent entirely when
+  `reply_count == 0`.
+- **Read on open:** expanding a thread issues the REST read call and updates the receipt from its
+  response.
+- **Live root update:** a server-shaped `message` frame carrying a `reply_to_id` for a cached root
+  raises that root's `reply_count` and advances `last_reply_at`, and the marker appears without a
+  refetch when the sender is not the viewer.
+- **Row 42:** two managed conversations with different `external_key` values are distinguishable through
+  whatever the host supplies, and **no jg-specific string appears anywhere in `src/`** — assert that
+  directly, it is the constraint most likely to be quietly violated.
+- **Deviation doc / conformance:** zero BLOCKED entries and the version-pin check still meaningful.
+- Existing ucm suites stay green.
+
+**Fixture rule, non-negotiable:** every payload in these tests is copied from actual dcm serializer
+output. Two separate defects in this workstream (`reply_to` vs `reply_to_id`, `last_message.body` vs
+`.excerpt`) survived only because hand-written client-shaped fixtures agreed with the client's mistake.
+
+### Risks
+
+- **The merge trap**, above — the single most likely way this WO ships a regression, and the reason its
+  first test is mandatory rather than nice-to-have.
+- **jg vocabulary leaking into ucm** on row 42; it has its own assertion.
+- Small WO, low complexity — the risk is complacency, not difficulty.
+
+### Reviews
+
+**Tier 2, not Tier 1 — corrected on review.** The row count is small but the change lands in
+`MessagingProvider`'s frame-merge code, which is exactly where MSG-3c's Tier-2 pass found three shipped
+bugs, and this WO's own risk section calls its merge trap the most likely way it ships a regression.
+That is review-sensitive work by AGENTS.md's definition; size does not lower the tier.
+
+Independent `reviewer` plus **`ui_reviewer`** at WO end: the marker is a visual
+affordance and the harness exists to look at it. The `ui_reviewer` must also confirm the deviation doc
+reaches zero BLOCKED entries honestly — by delivery, not by deletion.
+
+### Preconditions
+
+dcm 2.38.0 published (met — verified in source, not assumed). Approval Gate #1 = operator go on this
+envelope.
+
+### Release
+
+One version bump + npm publish at WO end. **This closes the post-audit remediation**: with rows 27 and
+42 delivered, every row of the MSG-3b checklist is either implemented or a recorded deliberate
+deviation, and MSG-5 becomes unblocked.
+
+### Execution directive
+
+Implement through `codex exec` in the background — invoked **directly via Bash** (never the
+`debugger`/`*_coder` Agent wrappers) with **both** flags `--skip-git-repo-check` and
+`--dangerously-bypass-approvals-and-sandbox`, prompt passed as a positional argument from a file;
+fall back to direct Claude implementation only on Codex quota / rate-limit / non-zero exit. Codex has
+been out of workspace credits recently — verify before assuming the fallback, and if the fallback is
+used, the orchestrator becomes author and the independent review is mandatory, not routine.
+
+### Mini-handover (pastable)
+
+Orchestrator: implement `work-orders/MSG-3d.md` in `ui-core-micha` (main). `git pull` first, read the WO
++ `django-core-micha/docs/design/messaging-platform.md` (§"Thread reply state and managed-conversation
+identity", §Realtime's consumer obligation), then follow `orchestrate-codex` (Codex-first, own
+independent review, `ui_reviewer` at WO end, one publish at WO end).
+
+---
+
+## Part B — Implementation map (Orchestrator)
+
+**Single chunk** (the envelope's own framing: small WO, low complexity — Tier 2 for review rigor, not
+for decomposition). **Target repo working directory:** `C:\Users\biglmi\Documents\webapps\ui-core-micha`
+(repo root).
+
+**Verified against dcm 2.38.0 while scoping (do not re-derive):**
+- `serialize_message` (`django-core-micha/src/django_core_micha/messaging/serializers.py:80-95`) ALWAYS
+  includes `reply_count`/`last_reply_at` — annotated-queryset fast path when present
+  (`_with_reply_count`, `views.py:39-47`, used by `ConversationMessagesView`/`ThreadView`), a live
+  aggregate fallback otherwise (`_reply_stats`, `serializers.py:68-77`). Every `message`/`message_edited`
+  frame (built from `serialize_message` via `realtime.py`'s `publish_messaging_event`) therefore always
+  carries fresh, viewer-independent reply stats for that specific message.
+- `thread_last_read_at` is added **only** by `_message_response`/`_message_page_response`
+  (`views.py:50-74`) — REST-only, viewer-specific, from `MessageThreadReceipt`. `_with_reply_count`'s
+  list responses (`GET conversations/{id}/messages/`, `GET messages/{root_id}/thread/`) already attach
+  it per-row via one bulk query (not N+1) — so a normal `listMessages`/`listThread` load already gives
+  roots both their reply stats AND the viewer's own receipt in one response; no extra call needed on
+  mount.
+- `POST messages/{root_id}/thread/read/` (`views.py:342-347`, already wired as `markThreadRead` in
+  `api.js:41`) returns `{"last_read_at": ...}` — **note the field name differs from the cached message's
+  own `thread_last_read_at` key** — the provider action must map `last_read_at` from this response onto
+  the root message's `thread_last_read_at` cache field, they are not the same key name.
+- `serialize_conversation_core` (`serializers.py:107-115` area) now includes `external_key` (`null`
+  where the kind doesn't use one).
+
+**The merge trap — investigated, resolved by existing infrastructure, still needs its mandatory test:**
+`mergeById`/`reconcileMessage` (`MessagingProvider.jsx:45-79`) already do a **field-wise** merge
+(`{...previous, ...incoming}`), and neither the `message` nor `message_edited` `applyFrame` branches
+explicitly re-derive or strip `thread_last_read_at` the way the `reaction`/`poll_updated` branches used
+to explicitly recompute their own fields — so an incoming frame lacking `thread_last_read_at` (it always
+will) does NOT overwrite a previously-cached value through the current code path. This is a genuine
+finding from investigation, not an assumption: **do not skip the mandatory merge-trap test on the
+strength of this finding** — the WO requires it regardless, and any code added by this WO (the live
+root-update below in particular) must preserve this property rather than accidentally break it by
+constructing a replacement object that omits the key.
+
+**Row 27 implementation:**
+1. `MessagingProvider.jsx`'s `markReplyThreadRead` (currently `:262`,
+   `const markReplyThreadRead = useCallback((rootId, readAt) => api.markThreadRead(rootId, readAt),
+   [api]);`) fires the REST call and **discards the response** — nothing ever updates the cache, so the
+   receipt is never actually stored client-side today. Fix: on success, patch the root message's
+   `thread_last_read_at` from the response's `last_read_at` (field-name mapping per above).
+2. A marker component/affordance on the thread-toggle button (`Thread.jsx`'s existing
+   `toggleReplies`/reply-count button, around where `message.reply_count` is already read at `:93-96`
+   for the reply-count label) — show it when `message.last_reply_at > message.thread_last_read_at`, OR
+   when `message.thread_last_read_at` is `null`/absent and `message.reply_count > 0`. No marker at all
+   when `reply_count === 0` (matches the existing "no toggle button at all when there are no replies"
+   behavior — don't add a marker to a control that doesn't render). This belongs in `Thread.jsx` (or a
+   small collaborator it owns) — not a new top-level component, per the non-goals' "marker belongs to
+   whichever component owns the thread toggle."
+3. **Live root update on an incoming reply** — in `applyFrame`'s `message` case
+   (`MessagingProvider.jsx:126-143`): after the existing reply message itself is merged via
+   `reconcileMessage`, additionally check `message.reply_to_id` (server field name — reuse the pattern
+   already established, this is NOT the client-shaped `reply_to` used only by locally-built optimistic
+   rows) against `state.messages` for a cached root. If found, bump that root's `reply_count` by one and
+   set `last_reply_at` to the incoming message's `created_at`, via a **field-wise merge that explicitly
+   preserves the root's existing `thread_last_read_at`** (the exact discipline the merge-trap section
+   above is about — do this by spreading the previous root object and only overriding
+   `reply_count`/`last_reply_at`, never by constructing a fresh object from the frame's data). Apply this
+   unconditionally (regardless of who sent the reply) — `reply_count`/`last_reply_at` are
+   viewer-independent facts; do not add sender-based suppression logic that isn't explicitly required
+   (the required tests only ask for the "sender is not the viewer" case, the common path — don't invent
+   untested self-send special-casing beyond that).
+
+**Row 42 implementation:** `external_key` needs no new plumbing to reach the cache — `mergeById`/REST
+responses pass every field through transparently already. What's missing is a way for a host to render
+it. Add an optional host-supplied resolver prop to `ConversationList.jsx` (mirrors the existing
+`groupLaunchers`/`broadcastLauncher` host-supplied-data pattern already in this file) — e.g.
+`resolveManagedLabel(conversation)` — called instead of the existing `titleOf()` fallback specifically
+when `conversation.kind === 'managed'` and the prop is supplied; falls back to the existing `titleOf()`
+behavior otherwise (unset prop, or non-managed kind). **ucm must not hardcode or reference `event_all`/
+`event_team` or any other jg-specific vocabulary anywhere in `src/`** — the resolver receives the raw
+`conversation` object (including `external_key`) and the host owns all interpretation.
+
+**Deviation doc + conformance test:** move rows 27 and 42 from `BLOCKED` to their delivered outcome in
+`docs/messaging-deviations.md` (describe what was actually built, not a generic note, matching the
+established style from MSG-3c's rewrite). This leaves **zero** `BLOCKED` entries — verify
+`tests/messagingContractConformance.test.js`'s version-pin check (added in MSG-3c) still passes
+meaningfully against an empty set (i.e. `unpinnedBlockedLines()` naturally returns `[]` when there are no
+`**BLOCKED**` lines at all — confirm this is actually true of the regex-based approach, not just assumed
+because the test happens to pass; the WO's own text calls out the "passing vacuously for the wrong
+reason" risk explicitly).
+
+**Required tests to WRITE (all named explicitly in the WO's own "Required tests" section — treat that
+section as the checklist, not this paraphrase):**
+- The merge-trap test (load-bearing, per the WO: server-shaped `message` and `message_edited` frames,
+  copied from real `serialize_message` shape, must leave a previously-fetched
+  `thread_last_read_at` intact).
+- Marker visibility logic (shown/hidden/null-receipt/no-replies cases, all four named in the WO).
+- Read-on-open (expanding a thread issues the REST call and updates the receipt from its response).
+- Live root update (server-shaped `message` frame with `reply_to_id` raises the cached root's
+  `reply_count`/`last_reply_at`; marker appears without a refetch for the "sender is not the viewer"
+  case).
+- Row 42: two managed conversations with different `external_key` render distinguishable labels via a
+  host resolver; **a direct assertion that no jg-specific string (`event_all`, `event_team`) appears
+  anywhere in `src/`** — grep-based, mirroring the style of the existing contract-conformance test.
+- Deviation-doc/conformance: zero `BLOCKED` entries; the version-pin check's own logic still behaves
+  correctly against that empty set (not just "the real file happens to pass").
+- Existing ucm suites stay green.
+
+**Fixture rule (WO's own words, binding):** every payload in these tests is copied from actual dcm
+serializer output — this workstream has twice shipped a bug that survived only because a hand-written
+client-shaped fixture agreed with the client's own mistake (`reply_to` vs `reply_to_id`,
+`last_message.body` vs `.excerpt`). Do not hand-invent a payload shape without checking it against the
+serializer citations above first.
+
+**Invariants / do-not-break:** don't touch chunks/rows already delivered; keep the ~400 LOC soft trigger
+in mind for `Thread.jsx`/`ConversationList.jsx`/`MessagingProvider.jsx`; no new top-level component for
+the marker (lives in `Thread.jsx` or a small collaborator it owns); no new DX-1 harness entry needed
+unless a genuinely new independently-mountable component is added (it shouldn't be, per the above).
+
+**Progress contract / preamble:** `PLAN:`/`PROGRESS:`/`RESULT:` lines, no git operations, write-and-run-
+only-the-new-tests, leave the diff uncommitted for the orchestrator's review. Codex has been out of
+workspace credits recently across the last several WOs in this workstream — verify liveness before
+assuming success; if Codex fails (credits, quota, non-zero exit), the orchestrator implements directly
+per the fallback rule, which makes the orchestrator the author and independent review mandatory
+(not routine) — this has been true for every chunk of MSG-3c and should be expected here too.
+
+**Mini-handover:** repo `C:\Users\biglmi\Documents\webapps\ui-core-micha`, branch `main`, WO
+`work-orders/MSG-3d.md` (Part B above, single chunk). Follow `orchestrate-codex`. After the independent
+review and commit, run the WO-end `ui_reviewer` pass (per the WO's "Reviews" section — confirm the
+deviation doc reaches zero BLOCKED entries honestly, by delivery not deletion, and look at the marker
+as a rendered visual affordance via the DX-1 harness), then one version bump + npm publish.