@agent-team-foundation/first-tree-hub 0.12.7 → 0.12.8

package/dist/{client-h5l7mi0m-OEX7MOBg.mjs → client-bR8nwHaV-OxnjyKOk.mjs}

@@ -1,10 +1,10 @@
 import { O as withSpan, f as messageAttrs, s as createLogger } from "./observability-BAScT_5S-BcW9HgkG.mjs";
-import { $ as questionMessageContentSchema, M as extractMentions, O as defaultParticipantMode, Q as questionAnswerMessageContentSchema, _ as clientCapabilitiesSchema, a as AGENT_VISIBILITY, h as agentTypeSchema, i as AGENT_STATUSES, it as scanMentionTokens } from "./dist-CTkhS6p5.mjs";
+import { N as extractMentions, a as AGENT_VISIBILITY, et as questionAnswerMessageContentSchema, g as agentTypeSchema, i as AGENT_STATUSES, k as defaultParticipantMode, o as CHAT_ENGAGEMENT_STATUSES, ot as scanMentionTokens, tt as questionMessageContentSchema, v as clientCapabilitiesSchema } from "./dist-CnjqakXS.mjs";
 import { a as ConflictError, i as ClientUserMismatchError, l as organizations, n as BadRequestError, o as ForbiddenError, s as NotFoundError, u as users } from "./errors-CF5evtJt-B0NTIVPt.mjs";
 import { randomUUID } from "node:crypto";
 import { and, desc, eq, inArray, isNotNull, lt, ne, or, sql } from "drizzle-orm";
 import { bigserial, boolean, index, integer, jsonb, pgTable, primaryKey, text, timestamp, unique } from "drizzle-orm/pg-core";
-//#region ../server/dist/client-h5l7mi0m.mjs
+//#region ../server/dist/client-bR8nwHaV.mjs
 /**
 * Client connections. A client is a single SDK process (AgentRuntime) that may
 * host multiple agents. From the unified-user-token milestone on, a client is
@@ -58,6 +58,39 @@ const agents = pgTable("agents", {
 	index("idx_agents_client").on(table.clientId),
 	unique("uq_agents_org_name").on(table.organizationId, table.name)
 ]);
+/**
+* Unified membership table. Replaces the two-table split
+* (chat_participants speakers ∪ chat_subscriptions watchers) — both
+* collapse into a single row keyed by (chat_id, agent_id) with two
+* orthogonal columns:
+*
+*   - `role` ∈ owner / member  (creator-vs-member, governs admin actions)
+*   - `access_mode` ∈ speaker / watcher  (fan-out + mention candidacy)
+*
+* `(owner, speaker)`, `(member, speaker)`, `(member, watcher)` are the
+* legal combinations. `(owner, watcher)` is structurally possible but
+* never produced by v1 paths — the creator is always a speaker.
+*
+* Service-layer integrity (no FK / CHECK / trigger), matching the
+* messages / inbox_entries / notifications convention. Chat hard-delete
+* paths must explicitly DELETE rows here (service-level cascade) — the
+* old DB-level `ON DELETE CASCADE` is intentionally not preserved.
+*
+* See proposals/chat-data-model-restructure.20260512.md §8.
+*/
+const chatMembership = pgTable("chat_membership", {
+	chatId: text("chat_id").notNull(),
+	agentId: text("agent_id").notNull(),
+	role: text("role").notNull().default("member"),
+	accessMode: text("access_mode").notNull(),
+	mode: text("mode").notNull().default("full"),
+	source: text("source").notNull().default("manual"),
+	joinedAt: timestamp("joined_at", { withTimezone: true }).notNull().defaultNow()
+}, (table) => [
+	primaryKey({ columns: [table.chatId, table.agentId] }),
+	index("idx_membership_agent").on(table.agentId),
+	index("idx_membership_chat_role").on(table.chatId, table.accessMode)
+]);
 /** Communication container. All messages between agents flow within a Chat. */
 const chats = pgTable("chats", {
 	id: text("id").primaryKey(),
@@ -72,39 +105,6 @@ const chats = pgTable("chats", {
 	createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
 	updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow()
 }, (table) => [index("idx_chats_org_last_message").on(table.organizationId, desc(table.lastMessageAt))]);
-/** Speaking participants of a chat (M:N). Watchers live in chat_subscriptions. */
-const chatParticipants = pgTable("chat_participants", {
-	chatId: text("chat_id").notNull().references(() => chats.id, { onDelete: "cascade" }),
-	agentId: text("agent_id").notNull().references(() => agents.uuid),
-	role: text("role").notNull().default("member"),
-	mode: text("mode").notNull().default("full"),
-	lastReadAt: timestamp("last_read_at", { withTimezone: true }),
-	unreadMentionCount: integer("unread_mention_count").notNull().default(0),
-	joinedAt: timestamp("joined_at", { withTimezone: true }).notNull().defaultNow()
-}, (table) => [primaryKey({ columns: [table.chatId, table.agentId] }), index("idx_participants_agent").on(table.agentId)]);
-/**
-* Non-speaking observers ("watchers"). Used by the chat-first workspace so a
-* user can supervise chats their managed agents participate in without
-* accidentally being part of fan-out.
-*
-* Invariants:
-*   1. (chat_id, agent_id) is mutually exclusive with chat_participants.
-*   2. Rows here NEVER produce inbox_entries (fan-out exclusivity).
-*   3. Mention candidate resolution NEVER includes these rows.
-*   4. State transitions (join/leave) carry last_read_at + counter; lifecycle
-*      recomputes default to NULL/0 and MUST NOT run on the join/leave path.
-*
-* See docs/chat-first-workspace-product-design.md "Data Model" + "State
-* Transitions" for the full contract.
-*/
-const chatSubscriptions = pgTable("chat_subscriptions", {
-	chatId: text("chat_id").notNull().references(() => chats.id, { onDelete: "cascade" }),
-	agentId: text("agent_id").notNull().references(() => agents.uuid),
-	kind: text("kind").notNull().default("watching"),
-	lastReadAt: timestamp("last_read_at", { withTimezone: true }),
-	unreadMentionCount: integer("unread_mention_count").notNull().default(0),
-	createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow()
-}, (table) => [primaryKey({ columns: [table.chatId, table.agentId] }), index("idx_chat_subscriptions_agent").on(table.agentId)]);
 /** Organization membership. Links a user to an org with a role and a 1:1 human agent. */
 const members = pgTable("members", {
 	id: text("id").primaryKey(),
@@ -121,10 +121,10 @@ const members = pgTable("members", {
 ]);
 /**
 * Process-local cache for the per-chat realtime push audience
-* (`chat_participants ∪ chat_subscriptions`, keyed by human agent
-* uuid). Sits in front of the admin WS dispatch so a chat with N
-* messages/sec doesn't issue N audience-resolution queries; one query
-* + cache hit per chat per TTL window.
+* (every row in `chat_membership` for the chat — speakers + watchers,
+* keyed by human agent uuid). Sits in front of the admin WS dispatch
+* so a chat with N messages/sec doesn't issue N audience-resolution
+* queries; one query + cache hit per chat per TTL window.
 *
 * The cache exposes both a populator (`getCachedAudience`) and an
 * invalidator (`invalidateChatAudience`). Participant-mutation paths
@@ -156,9 +156,7 @@ async function getCachedAudience(db, chatId) {
 	if (cached && cached.expiresAt > now) return cached.audience;
 	try {
 		const rows = await db.execute(sql`
-      SELECT agent_id FROM chat_participants WHERE chat_id = ${chatId}
-      UNION
-      SELECT agent_id FROM chat_subscriptions WHERE chat_id = ${chatId}
+      SELECT agent_id FROM chat_membership WHERE chat_id = ${chatId}
     `);
 		const audience = new Set(rows.map((r) => r.agent_id));
 		cache.set(chatId, {
@@ -185,20 +183,25 @@ function invalidateChatAudience(chatId) {
 	cache.delete(chatId);
 }
 /**
-* Single source of truth for writing `chat_participants`.
+* Single source of truth for writing speaker rows into `chat_membership`.
+*
+* **This is the ONLY place in the codebase that may INSERT speaker rows
+* (access_mode = 'speaker') into `chat_membership`.** Do not call
+* `tx.insert(chatMembership)` with `accessMode: 'speaker'` from anywhere
+* else. The original bug (docs/chat-participant-mode-fix-design.md §1.1)
+* was caused by mode-derivation logic scattered across ten insert sites,
+* several of which violated `group + non-human ⇒ mention_only`.
+* Re-introducing a second writer reopens that hole — please don't.
 *
-* **This is the ONLY place in the codebase that may `INSERT` into the
-* `chat_participants` table.** Do not call `tx.insert(chatParticipants)`
-* or `db.insert(chatParticipants)` from anywhere else. The original bug
-* (docs/chat-participant-mode-fix-design.md §1.1) was caused by ten
-* scattered insert sites each re-deriving the `mode` rule, several of
-* which violated `group + non-human ⇒ mention_only`. Re-introducing a
-* second writer reopens that hole — please don't.
+* Watcher rows (access_mode = 'watcher') are written from
+* `services/watcher.ts::recomputeChatWatchers` via raw SQL; they don't
+* go through this service because the mode rule is `full` by construction
+* for watchers (they receive but don't fan out).
 *
-* Test fixtures under `src/__tests__/` that deliberately seed
-* pathological rows (e.g. cross-org pollution tests) may bypass this
-* rule; they are setting up "what bad data looks like" rather than
-* exercising the production write path.
+* Test fixtures under `src/__tests__/` that deliberately seed pathological
+* rows (e.g. cross-org pollution tests) may bypass this rule; they are
+* setting up "what bad data looks like" rather than exercising the
+* production write path.
 *
 * All callers that need to add a participant — `createChat`, `addParticipant`,
 * `ensureParticipant`, `joinChat`, `createMeChat`, `addMeChatParticipants`,
@@ -211,13 +214,20 @@ function invalidateChatAudience(chatId) {
 *
 * `changeChatType` complements it on the type-flip path: when a `direct`
 * chat is being upgraded to `group` by the very next participant insert, the
-* existing non-human rows must be re-graded to `mention_only`. Callers that
-* trigger an upgrade are expected to invoke `changeChatType` BEFORE
+* existing non-human speakers must be re-graded to `mention_only`. Callers
+* that trigger an upgrade are expected to invoke `changeChatType` BEFORE
 * `addChatParticipants`, inside the same transaction, so the new row picks
 * up the post-upgrade `chats.type` and existing rows get re-graded together.
+*
+* Read state (`last_read_at` / `unread_mention_count`) is no longer carried
+* here: per the chat-data-model-restructure (proposal §8), it lives in a
+* structurally separate `chat_user_state` table whose rows survive
+* access_mode transitions untouched. A watcher → speaker promotion just
+* UPDATEs `chat_membership.access_mode`; the `chat_user_state` row (if any)
+* is unaffected — no state-carry transaction needed.
 */
 /**
-* Insert participant rows whose `mode` is derived from `(chats.type, agents.type)`.
+* Insert speaker rows whose `mode` is derived from `(chats.type, agents.type)`.
 *
 * Reads:
 *   - `chats.type` for the target chat (NotFoundError on missing)
@@ -225,16 +235,16 @@ function invalidateChatAudience(chatId) {
 *
 * Mode derivation:
 *   - for each row, `peerAgentTypes` is the type of every OTHER participant
-*     being inserted in the same call PLUS every EXISTING participant of
+*     being inserted in the same call PLUS every EXISTING speaker of
 *     the chat. This matters only for `direct` chats; the helper ignores
 *     it for `group` / `thread`.
 *
 * Writes one INSERT (multi-row) per call.
 *
 * No watcher / audience-cache side effects — the caller owns those, since
-* different entrypoints have different surrounding work (state-carry, watcher
-* recompute, audience invalidation). Keeping this module side-effect-free
-* makes it testable from any tx context.
+* different entrypoints have different surrounding work (watcher recompute,
+* audience invalidation). Keeping this module side-effect-free makes it
+* testable from any tx context.
 */
 async function addChatParticipants(tx, chatId, participants, options = {}) {
 	if (participants.length === 0) return;
@@ -266,35 +276,51 @@ async function addChatParticipants(tx, chatId, participants, options = {}) {
 			chatId,
 			agentId: spec.agentId,
 			role: spec.role ?? "member",
+			accessMode: "speaker",
 			mode: defaultParticipantMode(chatType, agentType, peerTypesForRow),
-			lastReadAt: spec.carriedReadState?.lastReadAt ?? null,
-			unreadMentionCount: spec.carriedReadState?.unreadMentionCount ?? 0
+			source: "manual"
 		};
 	});
-	const insert = tx.insert(chatParticipants).values(rows);
-	if (options.onConflictDoNothing) await insert.onConflictDoNothing({ target: [chatParticipants.chatId, chatParticipants.agentId] });
+	const insert = tx.insert(chatMembership).values(rows);
+	if (options.upgradeWatcherToSpeaker) await insert.onConflictDoUpdate({
+		target: [chatMembership.chatId, chatMembership.agentId],
+		set: {
+			accessMode: "speaker",
+			mode: sqlExcluded("mode"),
+			source: "manual"
+		}
+	});
+	else if (options.onConflictDoNothing) await insert.onConflictDoNothing({ target: [chatMembership.chatId, chatMembership.agentId] });
 	else await insert;
 }
+/**
+* Drizzle helper: reference `excluded.<col>` in an UPSERT's UPDATE clause.
+* Returned as untyped SQL because Drizzle's type system doesn't model the
+* `excluded` pseudo-row, and we only use it for two simple text columns
+* here. Centralised so callers don't have to import `sql` just for this.
+*/
+function sqlExcluded(column) {
+	return sql.raw(`excluded.${column}`);
+}
 async function loadExistingAgentTypes(tx, chatId, excludeAgentIds) {
 	return (await tx.select({
 		type: agents.type,
-		agentId: chatParticipants.agentId
-	}).from(chatParticipants).innerJoin(agents, eq(chatParticipants.agentId, agents.uuid)).where(eq(chatParticipants.chatId, chatId))).filter((r) => !excludeAgentIds.has(r.agentId)).map((r) => r.type);
+		agentId: chatMembership.agentId
+	}).from(chatMembership).innerJoin(agents, eq(chatMembership.agentId, agents.uuid)).where(and(eq(chatMembership.chatId, chatId), eq(chatMembership.accessMode, "speaker")))).filter((r) => !excludeAgentIds.has(r.agentId)).map((r) => r.type);
 }
 /**
 * Upgrade `chats.type` from `direct` → `group` AND re-grade every existing
-* non-human participant to `mention_only`. Idempotent: if `chat.type` is
+* non-human speaker to `mention_only`. Idempotent: if `chat.type` is
 * already `group` (or any non-`direct` value), no-op.
 *
-* Callers that are about to insert a 3rd participant on a `direct` chat
+* Callers that are about to insert a 3rd speaker on a `direct` chat
 * invoke this BEFORE `addChatParticipants` so the new row picks up the
 * post-upgrade `chats.type` and the existing rows are re-graded in the
 * same transaction.
 *
-* Note: this is the replacement for `services/chat.ts`'s
-* `maybeUpgradeDirectToGroup` (the one in `services/watcher.ts` is
-* removed). Keep the rename: `changeChatType` is more precise about the
-* primary mutation; `maybe…ToGroup` overstated the conditional gate.
+* Re-grade is gated on `access_mode = 'speaker'` — watcher rows already
+* have `mode = 'full'` by construction (recompute writes that literal)
+* and don't participate in fan-out, so they need no touching.
 */
 async function changeChatType(tx, chatId, newType) {
 	const [chat] = await tx.select({ type: chats.type }).from(chats).where(eq(chats.id, chatId)).limit(1);
@@ -305,9 +331,9 @@ async function changeChatType(tx, chatId, newType) {
 		type: newType,
 		updatedAt: /* @__PURE__ */ new Date()
 	}).where(eq(chats.id, chatId));
-	const ids = (await tx.select({ agentId: chatParticipants.agentId }).from(chatParticipants).innerJoin(agents, eq(chatParticipants.agentId, agents.uuid)).where(and(eq(chatParticipants.chatId, chatId), ne(agents.type, "human")))).map((r) => r.agentId);
+	const ids = (await tx.select({ agentId: chatMembership.agentId }).from(chatMembership).innerJoin(agents, eq(chatMembership.agentId, agents.uuid)).where(and(eq(chatMembership.chatId, chatId), eq(chatMembership.accessMode, "speaker"), ne(agents.type, "human")))).map((r) => r.agentId);
 	if (ids.length === 0) return;
-	await tx.update(chatParticipants).set({ mode: "mention_only" }).where(and(eq(chatParticipants.chatId, chatId), inArray(chatParticipants.agentId, ids)));
+	await tx.update(chatMembership).set({ mode: "mention_only" }).where(and(eq(chatMembership.chatId, chatId), inArray(chatMembership.agentId, ids), eq(chatMembership.accessMode, "speaker")));
 }
 /**
 * Heuristic for whether an insert about to happen would push the chat past
@@ -315,182 +341,187 @@ async function changeChatType(tx, chatId, newType) {
 * to call `changeChatType` before `addChatParticipants` without re-deriving
 * the rule locally.
 */
-function wouldUpgradeToGroup(currentParticipantCount, newParticipantCount) {
-	return currentParticipantCount + newParticipantCount >= 3;
+function wouldUpgradeToGroup(currentSpeakerCount, newSpeakerCount) {
+	return currentSpeakerCount + newSpeakerCount >= 3;
 }
 /**
-* Chat-first workspace — watcher subscription helpers.
+* Chat-first workspace — membership lifecycle helpers.
 *
-* Watchers (rows in `chat_subscriptions`) are non-speaking observers. A
-* member who manages an agent that participates in a chat — but whose own
-* human agent is not a speaker there — sees the chat in their workspace
-* via a watcher row.
+* After the chat data model restructure (see
+* proposals/chat-data-model-restructure.20260512.md §8), "watcher" is
+* just an `access_mode` value on `chat_membership`, not a separate
+* table. Speaker ↔ watcher transitions are a single-table UPDATE;
+* read state lives in `chat_user_state` and is structurally isolated
+* from access_mode changes — there is no state-carry path anymore.
 *
 * Two distinct kinds of operation live here:
 *
-*   1. Set rebuilds (`recompute*`). Idempotent set-based recomputations
-*      driven by lifecycle events (chat created, participant added/removed,
-*      member status flipped, etc.). These DEFAULT new rows to NULL/0 read
-*      state.
+*   1. Set rebuilds (`recompute*`). Idempotent set-based
+*      recomputations driven by lifecycle events (chat created,
+*      participant added/removed, member status flipped, agent
+*      rebind, etc.). Strict invariant: ONLY INSERT or DELETE rows
+*      where access_mode = 'watcher'. NEVER UPDATE any row with
+*      access_mode = 'speaker' — the user's own join/leave decision
+*      must not be overwritten by ops paths.
 *
-*   2. State-carry transitions (`joinAsParticipant`, `leaveAsParticipant`).
-*      Move a single (chat, agent) pair between `chat_participants` and
-*      `chat_subscriptions` while preserving `last_read_at` and
-*      `unread_mention_count`. NEVER call recompute on this path or you'll
-*      lose read state.
+*   2. Speaker ↔ watcher transitions (`joinAsParticipant`,
+*      `leaveAsParticipant`). Single-table UPDATE on
+*      `chat_membership.access_mode`; `chat_user_state` rows for
+*      the (chat, agent) pair are not touched. Per §11.4 default,
+*      a fully-detached user keeps their `chat_user_state` row
+*      (read state remembered for re-add).
 *
-* See docs/chat-first-workspace-product-design.md "State Transitions" and
-* "Risk Constraints".
+* File name preserved across the refactor for diff readability; may
+* be renamed in a follow-up. Public function names preserved too —
+* `recomputeChatWatchers` still describes what it does (recomputes
+* the watcher rows), so the rename to `recomputeChatMembership`
+* would obscure rather than clarify.
 */
 /**
 * Recompute watcher rows for ONE chat. For every active member who:
 *   - manages a non-human agent that speaks in the chat, AND
 *   - whose own human agent is NOT a speaker in the chat
-* an `(chat_id, member.agent_id)` watcher row is upserted (NULL read state).
+* a `(chat_id, member.agent_id)` watcher row is upserted.
 *
-* Watchers whose anchoring condition no longer holds (manager left, the
-* managed agent was removed from the chat, the manager joined as a speaker
-* themselves) are deleted.
+* Strict invariant: only writes rows with access_mode = 'watcher';
+* never updates or deletes any access_mode = 'speaker' row. The
+* ON CONFLICT DO NOTHING clause guarantees that if a (chat, agent)
+* row already exists as a speaker (the manager joined as a real
+* participant themselves), we leave it alone.
+*
+* Watchers whose anchoring condition no longer holds (manager left,
+* the managed agent was removed from the chat, the manager joined as
+* a speaker themselves) are deleted — also gated on access_mode =
+* 'watcher'.
 *
 * Idempotent: safe to call multiple times for the same chat.
 */
 async function recomputeChatWatchers(db, chatId) {
 	await db.execute(sql`
-    INSERT INTO chat_subscriptions
-      (chat_id, agent_id, kind, last_read_at, unread_mention_count, created_at)
-    SELECT DISTINCT cp.chat_id, m.agent_id, 'watching', NULL::timestamp with time zone, 0, now()
-      FROM chat_participants cp
-      JOIN agents  a ON a.uuid = cp.agent_id
+    INSERT INTO chat_membership
+      (chat_id, agent_id, role, access_mode, mode, source, joined_at)
+    SELECT DISTINCT cm.chat_id, m.agent_id, 'member', 'watcher', 'full', 'auto_manager', now()
+      FROM chat_membership cm
+      JOIN agents  a ON a.uuid = cm.agent_id
       JOIN members m ON m.id   = a.manager_id
-     WHERE cp.chat_id = ${chatId}
-       AND m.status   = 'active'
-       AND a.type    <> 'human'
+     WHERE cm.chat_id = ${chatId}
+       AND cm.access_mode = 'speaker'
+       AND m.status = 'active'
+       AND a.type   <> 'human'
        AND NOT EXISTS (
-         SELECT 1 FROM chat_participants cp2
-          WHERE cp2.chat_id  = cp.chat_id
-            AND cp2.agent_id = m.agent_id
+         SELECT 1 FROM chat_membership cm2
+          WHERE cm2.chat_id  = cm.chat_id
+            AND cm2.agent_id = m.agent_id
        )
     ON CONFLICT (chat_id, agent_id) DO NOTHING
   `);
 	await db.execute(sql`
-    DELETE FROM chat_subscriptions cs
-     WHERE cs.chat_id = ${chatId}
+    DELETE FROM chat_membership cm
+     WHERE cm.chat_id = ${chatId}
+       AND cm.access_mode = 'watcher'
        AND NOT EXISTS (
          SELECT 1
-           FROM chat_participants cp
-           JOIN agents  a ON a.uuid = cp.agent_id
+           FROM chat_membership speakers
+           JOIN agents  a ON a.uuid = speakers.agent_id
            JOIN members m ON m.id   = a.manager_id
-          WHERE cp.chat_id = cs.chat_id
-            AND m.agent_id = cs.agent_id
-            AND m.status   = 'active'
-            AND a.type    <> 'human'
-            AND NOT EXISTS (
-              SELECT 1 FROM chat_participants cp2
-               WHERE cp2.chat_id  = cp.chat_id
-                 AND cp2.agent_id = m.agent_id
-            )
+          WHERE speakers.chat_id     = cm.chat_id
+            AND speakers.access_mode = 'speaker'
+            AND m.agent_id           = cm.agent_id
+            AND m.status             = 'active'
+            AND a.type              <> 'human'
        )
   `);
 }
 /**
-* Recompute watcher rows touching ONE agent across all chats it speaks in.
-* Used after `rebindAgent` (manager change) so the new manager picks up
-* watcher rows and the old manager's are dropped.
+* Recompute watcher rows touching ONE agent across all chats it
+* speaks in. Used after `rebindAgent` (manager change) so the new
+* manager picks up watcher rows and the old manager's are dropped.
 */
 async function recomputeWatchersForAgent(db, agentId) {
-	const chatRows = await db.select({ chatId: chatParticipants.chatId }).from(chatParticipants).where(eq(chatParticipants.agentId, agentId));
+	const chatRows = await db.select({ chatId: chatMembership.chatId }).from(chatMembership).where(and(eq(chatMembership.agentId, agentId), eq(chatMembership.accessMode, "speaker")));
 	for (const { chatId } of chatRows) await recomputeChatWatchers(db, chatId);
 }
 /**
-* Recompute watcher rows touching ONE member across all chats. Triggered
-* when the member's status flips active ↔ left.
+* Recompute watcher rows touching ONE member across all chats.
+* Triggered when the member's status flips active ↔ left.
 */
 async function recomputeWatchersForMember(db, memberId) {
-	const rows = await db.selectDistinct({ chatId: chatParticipants.chatId }).from(chatParticipants).innerJoin(agents, eq(chatParticipants.agentId, agents.uuid)).where(and(eq(agents.managerId, memberId), ne(agents.type, "human")));
+	const rows = await db.selectDistinct({ chatId: chatMembership.chatId }).from(chatMembership).innerJoin(agents, eq(chatMembership.agentId, agents.uuid)).where(and(eq(chatMembership.accessMode, "speaker"), eq(agents.managerId, memberId), ne(agents.type, "human")));
 	for (const { chatId } of rows) await recomputeChatWatchers(db, chatId);
 }
 /**
-* Watcher → speaking participant. State-carry transaction.
+* Watcher → speaker (or fresh speaker insert).
 *
-*   1. DELETE the watcher row (returning read state).
-*   2. If a participant row already exists, no-op (idempotent).
-*   3. Otherwise, run the direct → group upgrade rule against the *current*
-*      participant set, then INSERT the participant row carrying read state.
+*   1. SELECT the existing chat_membership row for the (chat, agent) pair.
+*   2. If already a speaker → no-op (idempotent).
+*   3. If a watcher row → run the direct→group upgrade rule, then
+*      UPDATE access_mode to 'speaker'.
+*   4. If no row → run the direct→group upgrade rule, then INSERT a
+*      fresh speaker row.
 *
-* If `requireWatcherOrVisible` is true, refuse when the user has neither a
-* watcher row nor admin-derived visibility — used to keep the public
-* `/me/chats/:chatId/join` endpoint honest. Pre-check happens in the
-* route layer where we have the full member scope.
+* Caller is expected to have verified the user is authorised to join
+* (admin override OR an existing watcher row); this helper does not
+* gate on visibility.
 */
 async function joinAsParticipant(db, chatId, humanAgentId) {
 	return db.transaction(async (tx) => {
-		const [carriedRow] = await tx.delete(chatSubscriptions).where(and(eq(chatSubscriptions.chatId, chatId), eq(chatSubscriptions.agentId, humanAgentId))).returning({
-			lastReadAt: chatSubscriptions.lastReadAt,
-			unreadMentionCount: chatSubscriptions.unreadMentionCount
-		});
-		const [existing] = await tx.select({ chatId: chatParticipants.chatId }).from(chatParticipants).where(and(eq(chatParticipants.chatId, chatId), eq(chatParticipants.agentId, humanAgentId))).limit(1);
-		if (existing) return {
+		const [existing] = await tx.select({ accessMode: chatMembership.accessMode }).from(chatMembership).where(and(eq(chatMembership.chatId, chatId), eq(chatMembership.agentId, humanAgentId))).limit(1);
+		if (existing?.accessMode === "speaker") return {
 			chatId,
 			inserted: false,
-			carried: carriedRow ?? null
+			carried: null
 		};
-		if (wouldUpgradeToGroup((await tx.select({ agentId: chatParticipants.agentId }).from(chatParticipants).where(eq(chatParticipants.chatId, chatId))).length, 1)) await changeChatType(tx, chatId, "group");
+		if (wouldUpgradeToGroup((await tx.select({ agentId: chatMembership.agentId }).from(chatMembership).where(and(eq(chatMembership.chatId, chatId), eq(chatMembership.accessMode, "speaker")))).length, 1)) await changeChatType(tx, chatId, "group");
 		await addChatParticipants(tx, chatId, [{
 			agentId: humanAgentId,
-			role: "member",
-			carriedReadState: carriedRow ? {
-				lastReadAt: carriedRow.lastReadAt,
-				unreadMentionCount: carriedRow.unreadMentionCount
-			} : void 0
-		}], { assertHuman: true });
+			role: "member"
+		}], {
+			assertHuman: true,
+			upgradeWatcherToSpeaker: true
+		});
 		return {
 			chatId,
-			inserted: true,
-			carried: carriedRow ?? null
+			inserted: !existing,
+			carried: null
 		};
 	});
 }
 /**
-* Speaking participant → watcher (or fully detach).
-*
-*   1. DELETE the participant row (returning read state).
-*   2. Test "still visible": is the user still the manager of an agent that
-*      remains a participant in this chat? If yes, INSERT a watcher row
-*      carrying read state. If no, drop entirely.
+* Speaker → watcher (or fully detach).
 *
-* Caller must validate that the user actually has a participant row to
-* leave (returns `NotFoundError` if not).
+*   1. SELECT the existing speaker row; 404 if not present.
+*   2. Test "still visible": does the user still manage a non-human
+*      agent that remains a speaker in this chat?
+*      - If yes → UPDATE access_mode to 'watcher'.
+*      - If no  → DELETE the chat_membership row entirely.
+*   3. `chat_user_state` row (if any) is preserved either way per
+*      §11.4 default — read state is remembered for re-add.
 */
 async function leaveAsParticipant(db, chatId, humanAgentId) {
 	return db.transaction(async (tx) => {
-		const [carried] = await tx.delete(chatParticipants).where(and(eq(chatParticipants.chatId, chatId), eq(chatParticipants.agentId, humanAgentId))).returning({
-			lastReadAt: chatParticipants.lastReadAt,
-			unreadMentionCount: chatParticipants.unreadMentionCount
-		});
-		if (!carried) throw new NotFoundError("Not a participant of this chat");
-		const [stillVisibleRow] = await tx.execute(sql`
+		const [existing] = await tx.select({ accessMode: chatMembership.accessMode }).from(chatMembership).where(and(eq(chatMembership.chatId, chatId), eq(chatMembership.agentId, humanAgentId))).limit(1);
+		if (!existing || existing.accessMode !== "speaker") throw new NotFoundError("Not a participant of this chat");
+		const result = await tx.execute(sql`
       SELECT EXISTS (
         SELECT 1
-          FROM chat_participants cp
-          JOIN agents  a ON a.uuid = cp.agent_id
+          FROM chat_membership cm
+          JOIN agents  a ON a.uuid = cm.agent_id
           JOIN members m ON m.id   = a.manager_id
-         WHERE cp.chat_id = ${chatId}
+         WHERE cm.chat_id = ${chatId}
+           AND cm.access_mode = 'speaker'
            AND m.agent_id = ${humanAgentId}
            AND m.status   = 'active'
            AND a.type    <> 'human'
       ) AS visible
     `);
-		if (!Boolean(stillVisibleRow?.visible)) return {
-			chatId,
-			membershipKind: null
-		};
-		await tx.insert(chatSubscriptions).values({
-			chatId,
-			agentId: humanAgentId,
-			kind: "watching",
-			lastReadAt: carried.lastReadAt,
-			unreadMentionCount: carried.unreadMentionCount
-		}).onConflictDoNothing();
+		if (!Boolean(result[0]?.visible)) {
+			await tx.delete(chatMembership).where(and(eq(chatMembership.chatId, chatId), eq(chatMembership.agentId, humanAgentId)));
+			return {
+				chatId,
+				membershipKind: null
+			};
+		}
+		await tx.update(chatMembership).set({ accessMode: "watcher" }).where(and(eq(chatMembership.chatId, chatId), eq(chatMembership.agentId, humanAgentId)));
 		return {
 			chatId,
 			membershipKind: "watching"
@@ -498,24 +529,24 @@ async function leaveAsParticipant(db, chatId, humanAgentId) {
 	});
 }
 /**
-* Resolve the membership row of the human agent for the given chat. Returns
-* one of: 'participant', 'watching', or null.
+* Resolve the membership row of the human agent for the given chat.
+* Returns one of: 'participant' (speaker), 'watching' (watcher),
+* or null (no row).
 *
-* Used by `/me/chats/:chatId/join` to refuse a join when the user has
-* neither a watcher row nor a participant row, and isn't otherwise
-* authorised (admin in the chat's org).
+* Used by `/me/chats/:chatId/join` to refuse a join when the user
+* has neither a watcher row nor a participant row, and isn't
+* otherwise authorised (admin in the chat's org).
 */
 async function resolveChatMembership(db, chatId, humanAgentId) {
-	const [participant] = await db.select({ chatId: chatParticipants.chatId }).from(chatParticipants).where(and(eq(chatParticipants.chatId, chatId), eq(chatParticipants.agentId, humanAgentId))).limit(1);
-	if (participant) return "participant";
-	const [sub] = await db.select({ chatId: chatSubscriptions.chatId }).from(chatSubscriptions).where(and(eq(chatSubscriptions.chatId, chatId), eq(chatSubscriptions.agentId, humanAgentId))).limit(1);
-	if (sub) return "watching";
-	return null;
+	const [row] = await db.select({ accessMode: chatMembership.accessMode }).from(chatMembership).where(and(eq(chatMembership.chatId, chatId), eq(chatMembership.agentId, humanAgentId))).limit(1);
+	if (!row) return null;
+	return row.accessMode === "speaker" ? "participant" : "watching";
 }
 /**
-* Used by `/me/chats/:chatId/join`. Throw 409 if already a speaker (no work
-* to do) and 403 if no watcher row and no admin override. Admin override is
-* resolved at the route layer; this helper only reports the watcher state.
+* Used by `/me/chats/:chatId/join`. Throw 409 if already a speaker
+* (no work to do) and 403 if no row at all (admin override is
+* resolved at the route layer; this helper only reports the membership
+* state).
 */
 function ensureCanJoin(membership) {
 	if (membership === "participant") throw new ConflictError("Already a participant in this chat");
@@ -551,7 +582,7 @@ async function createChat(db, creatorId, data) {
 			role: agentId === creatorId ? "owner" : "member"
 		})));
 		await recomputeChatWatchers(tx, chatId);
-		const participants = await tx.select().from(chatParticipants).where(eq(chatParticipants.chatId, chatId));
+		const participants = await tx.select().from(chatMembership).where(and(eq(chatMembership.chatId, chatId), eq(chatMembership.accessMode, "speaker")));
 		if (!chat) throw new Error("Unexpected: INSERT RETURNING produced no row");
 		return {
 			...chat,
@@ -566,14 +597,14 @@ async function getChat(db, chatId) {
 }
 async function getChatDetail(db, chatId) {
 	const chat = await getChat(db, chatId);
-	const participants = await db.select().from(chatParticipants).where(eq(chatParticipants.chatId, chatId));
+	const participants = await db.select().from(chatMembership).where(and(eq(chatMembership.chatId, chatId), eq(chatMembership.accessMode, "speaker")));
 	return {
 		...chat,
 		participants
 	};
 }
 async function listChats(db, agentId, limit, cursor) {
-	const chatIds = (await db.select({ chatId: chatParticipants.chatId }).from(chatParticipants).where(eq(chatParticipants.agentId, agentId))).map((r) => r.chatId);
+	const chatIds = (await db.select({ chatId: chatMembership.chatId }).from(chatMembership).where(and(eq(chatMembership.agentId, agentId), eq(chatMembership.accessMode, "speaker")))).map((r) => r.chatId);
 	if (chatIds.length === 0) return {
 		items: [],
 		nextCursor: null
@@ -595,17 +626,17 @@ async function listChats(db, agentId, limit, cursor) {
 */
 async function listChatParticipantsWithNames(db, chatId) {
 	return await db.select({
-		agentId: chatParticipants.agentId,
-		role: chatParticipants.role,
-		mode: chatParticipants.mode,
-		joinedAt: chatParticipants.joinedAt,
+		agentId: chatMembership.agentId,
+		role: chatMembership.role,
+		mode: chatMembership.mode,
+		joinedAt: chatMembership.joinedAt,
 		name: agents.name,
 		displayName: agents.displayName,
 		type: agents.type
-	}).from(chatParticipants).innerJoin(agents, eq(chatParticipants.agentId, agents.uuid)).where(eq(chatParticipants.chatId, chatId));
+	}).from(chatMembership).innerJoin(agents, eq(chatMembership.agentId, agents.uuid)).where(and(eq(chatMembership.chatId, chatId), eq(chatMembership.accessMode, "speaker")));
 }
 async function assertParticipant(db, chatId, agentId) {
-	const [row] = await db.select({ chatId: chatParticipants.chatId }).from(chatParticipants).where(and(eq(chatParticipants.chatId, chatId), eq(chatParticipants.agentId, agentId))).limit(1);
+	const [row] = await db.select({ chatId: chatMembership.chatId }).from(chatMembership).where(and(eq(chatMembership.chatId, chatId), eq(chatMembership.agentId, agentId), eq(chatMembership.accessMode, "speaker"))).limit(1);
 	if (!row) throw new ForbiddenError("Not a participant of this chat");
 }
 /**
@@ -614,17 +645,16 @@ async function assertParticipant(db, chatId, agentId) {
 * caller's current chat (see `sendToAgent`'s current-chat routing branch).
 */
 async function isParticipant(db, chatId, agentId) {
-	const [row] = await db.select({ chatId: chatParticipants.chatId }).from(chatParticipants).where(and(eq(chatParticipants.chatId, chatId), eq(chatParticipants.agentId, agentId))).limit(1);
+	const [row] = await db.select({ chatId: chatMembership.chatId }).from(chatMembership).where(and(eq(chatMembership.chatId, chatId), eq(chatMembership.agentId, agentId), eq(chatMembership.accessMode, "speaker"))).limit(1);
 	return Boolean(row);
 }
-/** Ensure an agent is a participant of a chat. Silently adds them if not already. */
+/** Ensure an agent is a speaker of a chat. Silently adds them if not already. */
 async function ensureParticipant(db, chatId, agentId) {
-	const [existing] = await db.select({ agentId: chatParticipants.agentId }).from(chatParticipants).where(and(eq(chatParticipants.chatId, chatId), eq(chatParticipants.agentId, agentId))).limit(1);
-	if (existing) return;
+	const [existing] = await db.select({ accessMode: chatMembership.accessMode }).from(chatMembership).where(and(eq(chatMembership.chatId, chatId), eq(chatMembership.agentId, agentId))).limit(1);
+	if (existing?.accessMode === "speaker") return;
 	await db.transaction(async (tx) => {
-		if (wouldUpgradeToGroup((await tx.select({ agentId: chatParticipants.agentId }).from(chatParticipants).where(eq(chatParticipants.chatId, chatId))).length, 1)) await changeChatType(tx, chatId, "group");
-		await tx.delete(chatSubscriptions).where(and(eq(chatSubscriptions.chatId, chatId), eq(chatSubscriptions.agentId, agentId)));
-		await addChatParticipants(tx, chatId, [{ agentId }], { onConflictDoNothing: true });
+		if (wouldUpgradeToGroup((await tx.select({ agentId: chatMembership.agentId }).from(chatMembership).where(and(eq(chatMembership.chatId, chatId), eq(chatMembership.accessMode, "speaker")))).length, 1)) await changeChatType(tx, chatId, "group");
+		await addChatParticipants(tx, chatId, [{ agentId }], { upgradeWatcherToSpeaker: true });
 		await recomputeChatWatchers(tx, chatId);
 	});
 	invalidateChatAudience(chatId);
@@ -638,25 +668,24 @@ async function addParticipant(db, chatId, requesterId, data) {
 	}).from(agents).where(eq(agents.uuid, data.agentId)).limit(1);
 	if (!targetAgent) throw new NotFoundError(`Agent "${data.agentId}" not found`);
 	if (targetAgent.organizationId !== chat.organizationId) throw new BadRequestError("Cannot add agent from different organization");
-	const [existing] = await db.select({ chatId: chatParticipants.chatId }).from(chatParticipants).where(and(eq(chatParticipants.chatId, chatId), eq(chatParticipants.agentId, data.agentId))).limit(1);
-	if (existing) throw new ConflictError(`Agent "${data.agentId}" is already a participant`);
+	const [existing] = await db.select({ accessMode: chatMembership.accessMode }).from(chatMembership).where(and(eq(chatMembership.chatId, chatId), eq(chatMembership.agentId, data.agentId))).limit(1);
+	if (existing?.accessMode === "speaker") throw new ConflictError(`Agent "${data.agentId}" is already a participant`);
 	await db.transaction(async (tx) => {
-		if (wouldUpgradeToGroup((await tx.select({ agentId: chatParticipants.agentId }).from(chatParticipants).where(eq(chatParticipants.chatId, chatId))).length, 1)) await changeChatType(tx, chatId, "group");
-		await tx.delete(chatSubscriptions).where(and(eq(chatSubscriptions.chatId, chatId), eq(chatSubscriptions.agentId, data.agentId)));
-		await addChatParticipants(tx, chatId, [{ agentId: data.agentId }]);
+		if (wouldUpgradeToGroup((await tx.select({ agentId: chatMembership.agentId }).from(chatMembership).where(and(eq(chatMembership.chatId, chatId), eq(chatMembership.accessMode, "speaker")))).length, 1)) await changeChatType(tx, chatId, "group");
+		await addChatParticipants(tx, chatId, [{ agentId: data.agentId }], { upgradeWatcherToSpeaker: true });
 		await recomputeChatWatchers(tx, chatId);
 	});
 	invalidateChatAudience(chatId);
-	return db.select().from(chatParticipants).where(eq(chatParticipants.chatId, chatId));
+	return db.select().from(chatMembership).where(and(eq(chatMembership.chatId, chatId), eq(chatMembership.accessMode, "speaker")));
 }
 async function removeParticipant(db, chatId, requesterId, targetAgentId) {
 	await assertParticipant(db, chatId, requesterId);
 	if (requesterId === targetAgentId) throw new BadRequestError("Cannot remove yourself from a chat");
-	const [removed] = await db.delete(chatParticipants).where(and(eq(chatParticipants.chatId, chatId), eq(chatParticipants.agentId, targetAgentId))).returning();
+	const [removed] = await db.delete(chatMembership).where(and(eq(chatMembership.chatId, chatId), eq(chatMembership.agentId, targetAgentId), eq(chatMembership.accessMode, "speaker"))).returning();
 	if (!removed) throw new NotFoundError(`Agent "${targetAgentId}" is not a participant of this chat`);
 	await recomputeChatWatchers(db, chatId);
 	invalidateChatAudience(chatId);
-	return db.select().from(chatParticipants).where(eq(chatParticipants.chatId, chatId));
+	return db.select().from(chatMembership).where(and(eq(chatMembership.chatId, chatId), eq(chatMembership.accessMode, "speaker")));
 }
 /**
 * List chats visible to a member, grouped by agent.
@@ -685,11 +714,11 @@ async function listChatsForMember(db, memberId, humanAgentId) {
 	const agentIds = [...agentMap.keys()];
 	if (agentIds.length === 0) return [];
 	const participations = await db.select({
-		chatId: chatParticipants.chatId,
-		agentId: chatParticipants.agentId,
-		role: chatParticipants.role,
-		mode: chatParticipants.mode
-	}).from(chatParticipants).where(inArray(chatParticipants.agentId, agentIds));
+		chatId: chatMembership.chatId,
+		agentId: chatMembership.agentId,
+		role: chatMembership.role,
+		mode: chatMembership.mode
+	}).from(chatMembership).where(and(inArray(chatMembership.agentId, agentIds), eq(chatMembership.accessMode, "speaker")));
 	if (participations.length === 0) return [];
 	const chatIds = [...new Set(participations.map((p) => p.chatId))];
 	const agentChatMap = /* @__PURE__ */ new Map();
@@ -705,7 +734,7 @@ async function listChatsForMember(db, memberId, humanAgentId) {
 		metadata: chats.metadata,
 		createdAt: chats.createdAt,
 		updatedAt: chats.updatedAt,
-		participantCount: sql`(SELECT count(*)::int FROM chat_participants WHERE chat_id = ${chats.id})`
+		participantCount: sql`(SELECT count(*)::int FROM chat_membership WHERE chat_id = ${chats.id} AND access_mode = 'speaker')`
 	}).from(chats).where(inArray(chats.id, chatIds)).orderBy(desc(chats.updatedAt));
 	const chatMap = new Map(chatRows.map((c) => [c.id, c]));
 	const humanParticipantChatIds = new Set(participations.filter((p) => p.agentId === humanAgentId).map((p) => p.chatId));
@@ -740,30 +769,25 @@ async function listChatsForMember(db, memberId, humanAgentId) {
 */
 async function joinChat(db, chatId, memberId, humanAgentId) {
 	const chat = await getChat(db, chatId);
-	const participantAgentIds = (await db.select().from(chatParticipants).where(eq(chatParticipants.chatId, chatId))).map((p) => p.agentId);
+	const participantAgentIds = (await db.select().from(chatMembership).where(and(eq(chatMembership.chatId, chatId), eq(chatMembership.accessMode, "speaker")))).map((p) => p.agentId);
 	if (participantAgentIds.length === 0) throw new NotFoundError("Chat has no participants");
 	if (participantAgentIds.includes(humanAgentId)) throw new ConflictError("Already a participant in this chat");
 	if ((await db.select({ uuid: agents.uuid }).from(agents).where(and(inArray(agents.uuid, participantAgentIds), eq(agents.managerId, memberId)))).length === 0) throw new ForbiddenError("You can only join chats where you manage at least one participant");
 	const [humanAgent] = await db.select({ organizationId: agents.organizationId }).from(agents).where(eq(agents.uuid, humanAgentId)).limit(1);
 	if (!humanAgent || humanAgent.organizationId !== chat.organizationId) throw new BadRequestError("Agent does not belong to the same organization as the chat");
 	await db.transaction(async (tx) => {
-		const [carriedRow] = await tx.delete(chatSubscriptions).where(and(eq(chatSubscriptions.chatId, chatId), eq(chatSubscriptions.agentId, humanAgentId))).returning({
-			lastReadAt: chatSubscriptions.lastReadAt,
-			unreadMentionCount: chatSubscriptions.unreadMentionCount
-		});
 		if (wouldUpgradeToGroup(participantAgentIds.length, 1)) await changeChatType(tx, chatId, "group");
 		await addChatParticipants(tx, chatId, [{
 			agentId: humanAgentId,
-			role: "member",
-			carriedReadState: carriedRow ? {
-				lastReadAt: carriedRow.lastReadAt,
-				unreadMentionCount: carriedRow.unreadMentionCount
-			} : void 0
-		}], { assertHuman: true });
+			role: "member"
+		}], {
+			assertHuman: true,
+			upgradeWatcherToSpeaker: true
+		});
 		await recomputeChatWatchers(tx, chatId);
 	});
 	invalidateChatAudience(chatId);
-	return db.select().from(chatParticipants).where(eq(chatParticipants.chatId, chatId));
+	return db.select().from(chatMembership).where(and(eq(chatMembership.chatId, chatId), eq(chatMembership.accessMode, "speaker")));
 }
 /**
 * Manager leaves a chat. Removes their human agent from participants.
@@ -779,7 +803,7 @@ async function joinChat(db, chatId, memberId, humanAgentId) {
 async function leaveChat(db, chatId, humanAgentId) {
 	await leaveAsParticipant(db, chatId, humanAgentId);
 	invalidateChatAudience(chatId);
-	return db.select().from(chatParticipants).where(eq(chatParticipants.chatId, chatId));
+	return db.select().from(chatMembership).where(and(eq(chatMembership.chatId, chatId), eq(chatMembership.accessMode, "speaker")));
 }
 async function findOrCreateDirectChat(db, agentAId, agentBId) {
 	const ends = await db.select({
@@ -793,10 +817,7 @@ async function findOrCreateDirectChat(db, agentAId, agentBId) {
 	if (!agentB) throw new NotFoundError(`Agent "${agentBId}" not found`);
 	if (agentA.organizationId !== agentB.organizationId) throw new BadRequestError(`Cannot create direct chat across organizations: agent "${agentAId}" (org "${agentA.organizationId}") vs agent "${agentBId}" (org "${agentB.organizationId}")`);
 	const orgId = agentA.organizationId;
-	const aChats = await db.select({ chatId: chatParticipants.chatId }).from(chatParticipants).where(eq(chatParticipants.agentId, agentAId));
-	const bChats = await db.select({ chatId: chatParticipants.chatId }).from(chatParticipants).where(eq(chatParticipants.agentId, agentBId));
-	const bChatIds = new Set(bChats.map((r) => r.chatId));
-	const commonChatIds = aChats.map((r) => r.chatId).filter((id) => bChatIds.has(id));
+	const commonChatIds = (await db.select({ chatId: chatMembership.chatId }).from(chatMembership).where(and(inArray(chatMembership.agentId, [agentAId, agentBId]), eq(chatMembership.accessMode, "speaker"))).groupBy(chatMembership.chatId).having(sql`COUNT(DISTINCT ${chatMembership.agentId}) = 2`)).map((r) => r.chatId);
 	if (commonChatIds.length > 0) {
 		const directChats = await db.select().from(chats).where(and(inArray(chats.id, commonChatIds), eq(chats.type, "direct"), eq(chats.organizationId, orgId))).orderBy(chats.createdAt, chats.id).limit(1);
 		if (directChats.length > 0 && directChats[0]) return directChats[0];
@@ -1165,17 +1186,21 @@ async function listAgentsWithRuntime(db, scope) {
 *
 * The single sanctioned extension point on the message hot path. Called
 * from `services/message.ts` AFTER existing fan-out completes, inside the
-* same transaction. Three responsibilities:
-*
-*   1. Mention propagation: increment `unread_mention_count` for mentioned
-*      speaking participants AND for watcher rows whose managed agent was
-*      mentioned. Sender row is excluded.
+* same transaction. Four responsibilities:
 *
-*   2. Chats projection: roll forward `chats.last_message_at`,
+*   1. Chats projection: roll forward `chats.last_message_at`,
 *      `chats.last_message_preview`. Powers the conversation list cursor +
 *      sort + preview.
 *
-*   3. Realtime kick: fire-and-forget `pg_notify('chat_message_events', …)`
+*   2. Engagement auto-revive: flip `chat_user_state.engagement_status`
+*      from `archived` → `active` for everyone watching this chat. `deleted`
+*      rows are sticky and intentionally untouched.
+*
+*   3. Mention propagation: increment `unread_mention_count` for mentioned
+*      speaking participants AND for watcher rows whose managed agent was
+*      mentioned. Sender row is excluded.
+*
+*   4. Realtime kick: fire-and-forget `pg_notify('chat_message_events', …)`
 *      so admin WS sockets can translate it into a `chat:message` frame.
 *      Failure is swallowed — durable persistence is the correctness path.
 *
@@ -1183,11 +1208,13 @@ async function listAgentsWithRuntime(db, scope) {
 * "Risk Constraints"):
 *   - This module appends ONLY. Never edits existing fan-out / inbox /
 *     mention-extraction code.
-*   - Watchers (chat_subscriptions) are NEVER added to inbox_entries here.
-*     Their counters are bumped purely as a per-user red-dot signal.
-*   - Mention candidate set is `chat_participants` only; watchers are not
-*     direct `@`-mention targets.
+*   - Watcher rows (chat_membership with access_mode='watcher') are
+*     NEVER added to inbox_entries here. Their counters in
+*     chat_user_state are bumped purely as a per-user red-dot signal.
+*   - Mention candidate set is `chat_membership` speakers only;
+*     watchers are not direct `@`-mention targets.
 */
+const { ACTIVE, ARCHIVED } = CHAT_ENGAGEMENT_STATUSES;
 let dispatcher = null;
 function registerChatMessageDispatcher(fn) {
 	dispatcher = fn;
@@ -1220,27 +1247,38 @@ async function applyAfterFanOut(tx, input) {
 		lastMessageAt: ts,
 		lastMessagePreview: previewClipped
 	}).where(eq(chats.id, chatId));
+	await tx.execute(sql`
+    UPDATE chat_user_state
+       SET engagement_status = ${ACTIVE}
+     WHERE chat_id = ${chatId}
+       AND engagement_status = ${ARCHIVED}
+  `);
 	if (mentionedAgentIds.length === 0) return;
-	await tx.update(chatParticipants).set({ unreadMentionCount: sql`${chatParticipants.unreadMentionCount} + 1` }).where(and(eq(chatParticipants.chatId, chatId), inArray(chatParticipants.agentId, mentionedAgentIds), ne(chatParticipants.agentId, senderId)));
-	const managerHumanAgentIds = (await tx.execute(sql`
-    SELECT DISTINCT m.agent_id AS human_agent_id
-      FROM agents a
-      JOIN members m ON m.id = a.manager_id
-     WHERE a.uuid IN ${makeUuidList(mentionedAgentIds)}
-       AND a.type <> 'human'
-       AND m.status = 'active'
-  `)).map((r) => r.human_agent_id);
-	if (managerHumanAgentIds.length === 0) return;
-	await tx.update(chatSubscriptions).set({ unreadMentionCount: sql`${chatSubscriptions.unreadMentionCount} + 1` }).where(and(eq(chatSubscriptions.chatId, chatId), inArray(chatSubscriptions.agentId, managerHumanAgentIds)));
-}
-/**
-* Build a parenthesised, comma-separated list of bound parameters: `(?, ?, ?)`.
-* Used in raw SQL where drizzle's `inArray` can't be directly applied (e.g.
-* inside a hand-rolled SELECT). Always called with a non-empty list — the
-* caller short-circuits the empty case.
-*/
-function makeUuidList(ids) {
-	return sql`(${sql.join(ids.map((id) => sql`${id}`), sql`, `)})`;
+	const mentionedList = sql.join(mentionedAgentIds.map((id) => sql`${id}`), sql`, `);
+	await tx.execute(sql`
+    INSERT INTO chat_user_state (chat_id, agent_id, unread_mention_count)
+    SELECT chat_id, agent_id, 1
+      FROM (
+        SELECT cm.chat_id, cm.agent_id
+          FROM chat_membership cm
+         WHERE cm.chat_id     = ${chatId}
+           AND cm.access_mode = 'speaker'
+           AND cm.agent_id    IN (${mentionedList})
+           AND cm.agent_id   <> ${senderId}
+        UNION
+        SELECT cm.chat_id, cm.agent_id
+          FROM chat_membership cm
+          JOIN members m  ON m.agent_id    = cm.agent_id
+          JOIN agents  a  ON a.manager_id  = m.id
+         WHERE cm.chat_id     = ${chatId}
+           AND cm.access_mode = 'watcher'
+           AND a.uuid         IN (${mentionedList})
+           AND a.type        <> 'human'
+           AND m.status       = 'active'
+      ) targets
+    ON CONFLICT (chat_id, agent_id)
+    DO UPDATE SET unread_mention_count = chat_user_state.unread_mention_count + 1
+  `);
 }
 /**
 * Server-side lifecycle tracker for `format=question` messages.
@@ -1636,11 +1674,11 @@ async function sendMessageInner(db, chatId, senderId, data, options) {
 	const txResult = await db.transaction(async (tx) => {
 		const [participants, [chatRow], [senderRow]] = await Promise.all([
 			tx.select({
-				agentId: chatParticipants.agentId,
+				agentId: chatMembership.agentId,
 				inboxId: agents.inboxId,
-				mode: chatParticipants.mode,
+				mode: chatMembership.mode,
 				name: agents.name
-			}).from(chatParticipants).innerJoin(agents, eq(chatParticipants.agentId, agents.uuid)).where(eq(chatParticipants.chatId, chatId)),
+			}).from(chatMembership).innerJoin(agents, eq(chatMembership.agentId, agents.uuid)).where(and(eq(chatMembership.chatId, chatId), eq(chatMembership.accessMode, "speaker"))),
 			tx.select({ type: chats.type }).from(chats).where(eq(chats.id, chatId)).limit(1),
 			tx.select({
 				inboxId: agents.inboxId,
@@ -2129,4 +2167,4 @@ async function cleanupStaleClients(db, staleSeconds = 60) {
 	return result.length;
 }
 //#endregion
-export { messages as $, getOnlineCount as A, listActiveAgentsPinnedToClient as B, ensureCanJoin as C, getCachedAudience as D, getActivityOverview as E, invalidateChatAudience as F, listChatsForMember as G, listAgentsWithRuntime as H, joinAsParticipant as I, listMessages as J, listClients as K, joinChat as L, heartbeatClient as M, heartbeatInstance as N, getChatDetail as O, inboxEntries as P, members as Q, leaveAsParticipant as R, editMessage as S, findOrCreateDirectChat as T, listChatParticipantsWithNames as U, listAgentsManagedByUser as V, listChats as W, markStaleAgents as X, listMyPinnedAgents as Y, markSupersededByChat as Z, clients as _, touchAgent as _t, agentVisibilityCondition as a, registerChatMessageDispatcher as at, deriveAuthState as b, upsertSessionState as bt, assertParticipant as c, resetActivity as ct, chatParticipants as d, sendMessage as dt, notifyRecipients as et, chatSubscriptions as f, sendToAgent as ft, cleanupStalePresence as g, submitAnswer as gt, cleanupStaleClients as h, setRuntimeState as ht, agentPresence as i, recomputeWatchersForMember as it, getPresence as j, getClient as k, bindAgent as l, resolveChatMembership as lt, claimClient as m, setOffline as mt, addParticipant as n, recomputeChatWatchers as nt, agents as o, registerClient as ot, chats as p, serverInstances as pt, listClientsForOrgAdmin as q, agentChatSessions as r, recomputeWatchersForAgent as rt, assertClientOwner as s, removeParticipant as st, addChatParticipants as t, pendingQuestions as tt, changeChatType as u, retireClient as ut, createChat as v, unbindAgent as vt, ensureParticipant as w, disconnectClient as x, createNotifier as y, updateClientCapabilities as yt, leaveChat as z };
+export { notifyRecipients as $, getPresence as A, listAgentsManagedByUser as B, ensureParticipant as C, getChatDetail as D, getCachedAudience as E, joinAsParticipant as F, listClients as G, listChatParticipantsWithNames as H, joinChat as I, listMyPinnedAgents as J, listClientsForOrgAdmin as K, leaveAsParticipant as L, heartbeatInstance as M, inboxEntries as N, getClient as O, invalidateChatAudience as P, messages as Q, leaveChat as R, ensureCanJoin as S, getActivityOverview as T, listChats as U, listAgentsWithRuntime as V, listChatsForMember as W, markSupersededByChat as X, markStaleAgents as Y, members as Z, createChat as _, unbindAgent as _t, agentVisibilityCondition as a, registerClient as at, disconnectClient as b, assertParticipant as c, resolveChatMembership as ct, chatMembership as d, sendToAgent as dt, pendingQuestions as et, chats as f, serverInstances as ft, clients as g, touchAgent as gt, cleanupStalePresence as h, submitAnswer as ht, agentPresence as i, registerChatMessageDispatcher as it, heartbeatClient as j, getOnlineCount as k, bindAgent as l, retireClient as lt, cleanupStaleClients as m, setRuntimeState as mt, addParticipant as n, recomputeWatchersForAgent as nt, agents as o, removeParticipant as ot, claimClient as p, setOffline as pt, listMessages as q, agentChatSessions as r, recomputeWatchersForMember as rt, assertClientOwner as s, resetActivity as st, addChatParticipants as t, recomputeChatWatchers as tt, changeChatType as u, sendMessage as ut, createNotifier as v, updateClientCapabilities as vt, findOrCreateDirectChat as w, editMessage as x, deriveAuthState as y, upsertSessionState as yt, listActiveAgentsPinnedToClient as z };