@agent-team-foundation/first-tree-hub 0.14.1 → 0.14.2

package/dist/{client-CzXmweS9-DhUiuQvL.mjs → client-CZ_VnbEc-CBF46cJd.mjs}

@@ -1,10 +1,10 @@
-import { O as withSpan, f as messageAttrs, s as createLogger } from "./observability-BAScT_5S-BcW9HgkG.mjs";
-import { L as extractMentions, N as defaultParticipantMode, S as clientCapabilitiesSchema, b as agentTypeSchema, ct as questionAnswerMessageContentSchema, i as AGENT_STATUSES, lt as questionMessageContentSchema, mt as scanMentionTokens, o as AGENT_VISIBILITY, s as CHAT_ENGAGEMENT_STATUSES } from "./dist-1XGLJMOq.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-LPcARA4K-Dbrptiyz.mjs";
+import { A as FIRST_TREE_HUB_ATTR, O as withSpan, f as messageAttrs, s as createLogger } from "./observability-BAScT_5S-BcW9HgkG.mjs";
+import { L as extractMentions, N as defaultParticipantMode, P as defaultRuntimeConfigPayload, S as clientCapabilitiesSchema, St as stripCode, Z as isReservedAgentName, a as AGENT_TYPES, b as agentTypeSchema, ct as questionAnswerMessageContentSchema, d as MENTION_REGEX, i as AGENT_STATUSES, l as GITHUB_ENTITY_TYPES, lt as questionMessageContentSchema, mt as scanMentionTokens, n as AGENT_NAME_REGEX, nt as messageSourceSchema, o as AGENT_VISIBILITY, s as CHAT_ENGAGEMENT_STATUSES } from "./dist-DmYxT5Kb.mjs";
+import { a as ClientUserMismatchError, c as NotFoundError, d as users, f as uuidv7, o as ConflictError, r as BadRequestError, s as ForbiddenError, t as AgentSendNonMemberError, u as organizations } from "./uuid-DbS_4vFh-iFghv4zA.mjs";
 import { randomUUID } from "node:crypto";
-import { and, desc, eq, inArray, isNotNull, lt, ne, or, sql } from "drizzle-orm";
-import { bigserial, boolean, customType, index, integer, jsonb, pgTable, primaryKey, text, timestamp, unique } from "drizzle-orm/pg-core";
-//#region ../server/dist/client-CzXmweS9.mjs
+import { and, asc, count, desc, eq, gt, gte, inArray, isNotNull, lt, ne, or, sql } from "drizzle-orm";
+import { bigserial, boolean, customType, index, integer, jsonb, pgTable, primaryKey, serial, text, timestamp, unique } from "drizzle-orm/pg-core";
+//#region ../server/dist/client-CZ_VnbEc.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
@@ -69,6 +69,17 @@ const agents = pgTable("agents", {
 	index("idx_agents_client").on(table.clientId),
 	unique("uq_agents_org_name").on(table.organizationId, table.name)
 ]);
+/** Maps external user identities to internal Agents. */
+const adapterAgentMappings = pgTable("adapter_agent_mappings", {
+	id: serial("id").primaryKey(),
+	platform: text("platform").notNull(),
+	externalUserId: text("external_user_id").notNull(),
+	agentId: text("agent_id").notNull().references(() => agents.uuid),
+	boundVia: text("bound_via"),
+	displayName: text("display_name"),
+	metadata: jsonb("metadata").$type().notNull().default({}),
+	createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow()
+}, (table) => [unique("uq_adapter_agent_mapping").on(table.platform, table.externalUserId)]);
 /**
 * Unified membership table. Replaces the two-table split
 * (chat_participants speakers ∪ chat_subscriptions watchers) — both
@@ -130,6 +141,30 @@ const members = pgTable("members", {
 	index("idx_members_user").on(table.userId),
 	index("idx_members_org").on(table.organizationId)
 ]);
+/** Bot credentials for external platform adapters. Credentials are encrypted at application layer (AES-256-GCM). */
+const adapterConfigs = pgTable("adapter_configs", {
+	id: serial("id").primaryKey(),
+	platform: text("platform").notNull(),
+	agentId: text("agent_id").notNull().references(() => agents.uuid),
+	credentials: jsonb("credentials").$type().notNull(),
+	status: text("status").notNull().default("active"),
+	createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+	updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow()
+}, (t) => [unique("uq_adapter_configs_agent_platform").on(t.agentId, t.platform)]);
+/** Messages. Immutable after creation. Each message belongs to exactly one Chat. */
+const messages = pgTable("messages", {
+	id: text("id").primaryKey(),
+	chatId: text("chat_id").notNull().references(() => chats.id),
+	senderId: text("sender_id").notNull(),
+	format: text("format").notNull(),
+	content: jsonb("content").$type().notNull(),
+	metadata: jsonb("metadata").$type().notNull().default({}),
+	replyToInbox: text("reply_to_inbox"),
+	replyToChat: text("reply_to_chat"),
+	inReplyTo: text("in_reply_to"),
+	source: text("source"),
+	createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow()
+}, (table) => [index("idx_messages_chat_time").on(table.chatId, table.createdAt), index("idx_messages_in_reply_to").on(table.inReplyTo)]);
 /**
 * Process-local cache for the per-chat realtime push audience
 * (every row in `chat_membership` for the chat — speakers + watchers,
@@ -193,6 +228,571 @@ async function getCachedAudience(db, chatId) {
 function invalidateChatAudience(chatId) {
 	cache.delete(chatId);
 }
+/** Delivery queue (envelope). One entry per recipient created during message fan-out. Uses SKIP LOCKED for concurrent-safe consumption. */
+const inboxEntries = pgTable("inbox_entries", {
+	id: bigserial("id", { mode: "number" }).primaryKey(),
+	inboxId: text("inbox_id").notNull(),
+	messageId: text("message_id").notNull().references(() => messages.id),
+	chatId: text("chat_id"),
+	status: text("status").notNull().default("pending"),
+	notify: boolean("notify").notNull().default(true),
+	retryCount: integer("retry_count").notNull().default(0),
+	createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+	deliveredAt: timestamp("delivered_at", { withTimezone: true }),
+	ackedAt: timestamp("acked_at", { withTimezone: true })
+}, (table) => [
+	unique("uq_inbox_delivery").on(table.inboxId, table.messageId, table.chatId),
+	index("idx_inbox_pending").on(table.inboxId, table.createdAt),
+	index("idx_inbox_pending_notify").on(table.inboxId, table.createdAt).where(sql`status = 'pending' AND notify = true`),
+	index("idx_inbox_chat_silent").on(table.inboxId, table.chatId, table.notify, table.status)
+]);
+/**
+* Per-agent runtime configuration (Hub-managed; not the local YAML config).
+*
+* One row per agent. `version` increments on every successful UPDATE
+* (optimistic locking via WHERE version = :expected). Sensitive env values
+* inside `payload.env[*]` are AES-256-GCM encrypted at write time and
+* masked when echoed via the Admin API (see Step 2).
+*
+* Integrity is enforced by the service layer per project convention:
+* no FK / CHECK / triggers on this table.
+*/
+const agentConfigs = pgTable("agent_configs", {
+	agentId: text("agent_id").primaryKey(),
+	version: integer("version").notNull().default(1),
+	payload: jsonb("payload").$type().notNull(),
+	updatedBy: text("updated_by").notNull(),
+	updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow()
+});
+function normaliseSource(source) {
+	if (source === null) return null;
+	const parsed = messageSourceSchema.safeParse(source);
+	return parsed.success ? parsed.data : null;
+}
+function normaliseMode(mode) {
+	return mode === "mention_only" ? "mention_only" : "full";
+}
+/**
+* Batch variant — builds all payloads with a single DB lookup per agent plus
+* batched lookups for participant modes and inReplyTo snapshots.
+*/
+async function buildClientMessagePayloadsForInbox(db, inboxId, items) {
+	if (items.length === 0) return [];
+	const agentId = await resolveAgentId(db, {
+		kind: "inboxId",
+		inboxId
+	});
+	const [cfg] = await db.select({ version: agentConfigs.version }).from(agentConfigs).where(eq(agentConfigs.agentId, agentId)).limit(1);
+	const version = cfg?.version ?? 1;
+	const chatIds = [...new Set(items.map((it) => it.entryChatId ?? it.message.chatId).filter((id) => id !== null))];
+	const modeByChat = /* @__PURE__ */ new Map();
+	if (chatIds.length > 0) {
+		const rows = await db.select({
+			chatId: chatMembership.chatId,
+			mode: chatMembership.mode
+		}).from(chatMembership).where(and(eq(chatMembership.agentId, agentId), inArray(chatMembership.chatId, chatIds), eq(chatMembership.accessMode, "speaker")));
+		for (const r of rows) modeByChat.set(r.chatId, normaliseMode(r.mode));
+	}
+	const inReplyToIds = [...new Set(items.map((it) => it.message.inReplyTo).filter((id) => id !== null))];
+	const snapshotById = /* @__PURE__ */ new Map();
+	if (inReplyToIds.length > 0) {
+		const origs = await db.select({
+			id: messages.id,
+			senderId: messages.senderId,
+			chatId: messages.chatId,
+			replyToChat: messages.replyToChat
+		}).from(messages).where(inArray(messages.id, inReplyToIds));
+		for (const o of origs) snapshotById.set(o.id, {
+			senderId: o.senderId,
+			chatId: o.chatId,
+			replyToChat: o.replyToChat
+		});
+	}
+	return items.map(({ entryChatId, message: m, precedingMessages = [] }) => ({
+		id: m.id,
+		chatId: m.chatId,
+		senderId: m.senderId,
+		format: m.format,
+		content: m.content,
+		metadata: m.metadata,
+		replyToInbox: m.replyToInbox,
+		replyToChat: m.replyToChat,
+		inReplyTo: m.inReplyTo,
+		source: normaliseSource(m.source),
+		createdAt: m.createdAt,
+		configVersion: version,
+		recipientMode: modeByChat.get(entryChatId ?? m.chatId) ?? "full",
+		inReplyToSnapshot: m.inReplyTo ? snapshotById.get(m.inReplyTo) ?? null : null,
+		precedingMessages
+	}));
+}
+async function resolveAgentId(db, source) {
+	if (source.kind === "agentId") return source.agentId;
+	const [agent] = await db.select({ uuid: agents.uuid }).from(agents).where(eq(agents.inboxId, source.inboxId)).limit(1);
+	if (!agent) throw new Error(`No agent owns inbox "${source.inboxId}"`);
+	return agent.uuid;
+}
+const DEFAULT_INBOX_TIMEOUT_SECONDS = 300;
+const DEFAULT_MAX_RETRY_COUNT = 3;
+const PRECEDING_CONTEXT_WINDOW_SECONDS = 1440 * 60;
+/**
+* Backfill the most recent `PRECEDING_CONTEXT_MAX_ENTRIES` messages of `chatId`
+* as silent (notify=false) inbox rows for every new participant. Called from
+* `addParticipant()` inside the participant-insert transaction so a freshly
+* added member already has prior chat history available the first time they
+* are woken (mentioned / `chat send`-ed).
+*
+* Invariants the implementation upholds:
+*
+*   - **`notify=false` everywhere**: adding a participant is not itself a
+*     wake event. The new participant only runs the LLM when an actual
+*     trigger lands later; the backfill rows then piggy-back as preceding
+*     context (see `collectPrecedingContext`).
+*   - **Old members are not woken**: only inbox rows for the brand-new
+*     participants are written.
+*   - **Transaction-scoped**: writes go through the caller's `tx`, so a
+*     rollback of `addParticipant` rolls the backfill back too.
+*   - **Quiet on chats with no prior history**: a chat with zero messages
+*     produces zero backfill rows; no error, no INSERT.
+*   - **Idempotent**: collides cleanly on the
+*     `(inbox_id, message_id, chat_id)` unique key via
+*     `ON CONFLICT DO NOTHING`. This matters when a watcher → speaker
+*     promotion already had inbox rows for some of these messages.
+*
+* Pure data write — no PG NOTIFY, no participant-mode logic, no watcher
+* recompute. Callers stay responsible for those.
+*
+* **Caller responsibility — bulk batching**: writes a single
+* `INSERT VALUES (...)` of `newParticipants.length * PRECEDING_CONTEXT_MAX_ENTRIES`
+* tuples. v1's only caller (`addParticipant`) always passes 1 participant
+* (≤ 50 rows). Future bulk-add paths (sub-chat / spawn / etc.) should split
+* input into chunks (suggested: ≤ 512 rows per call) before passing here.
+*
+* See proposals/hub-chat-message-v1-design §四 改造 2.
+*/
+async function backfillSilentContextForNewParticipants(tx, chatId, newParticipants) {
+	if (newParticipants.length === 0) return;
+	const recent = await tx.select({ id: messages.id }).from(messages).where(eq(messages.chatId, chatId)).orderBy(desc(messages.createdAt)).limit(50);
+	if (recent.length === 0) return;
+	const rows = [];
+	for (const p of newParticipants) for (const m of recent) rows.push({
+		inboxId: p.inboxId,
+		messageId: m.id,
+		chatId,
+		notify: false
+	});
+	await tx.insert(inboxEntries).values(rows).onConflictDoNothing();
+}
+async function pollInbox(db, inboxId, limit) {
+	return withSpan("inbox.deliver", {
+		"inbox.id": inboxId,
+		"inbox.poll.limit": limit
+	}, () => pollInboxInner(db, inboxId, limit));
+}
+async function pollInboxInner(db, inboxId, limit) {
+	return db.transaction(async (tx) => {
+		const targetIds = tx.select({ id: inboxEntries.id }).from(inboxEntries).where(and(eq(inboxEntries.inboxId, inboxId), eq(inboxEntries.status, "pending"), eq(inboxEntries.notify, true))).orderBy(asc(inboxEntries.createdAt)).limit(limit).for("update", { skipLocked: true });
+		return bundleDeliveryWithSilentContext(tx, inboxId, await tx.update(inboxEntries).set({
+			status: "delivered",
+			deliveredAt: /* @__PURE__ */ new Date()
+		}).where(inArray(inboxEntries.id, targetIds)).returning());
+	});
+}
+/**
+* Shared payload assembler for already-claimed `inbox_entries` rows.
+*
+* Both the HTTP poll path (`pollInbox`) and the WS push path
+* (`claimAndBuildForPush`) call this with rows they have just `UPDATE`d to
+* `status='delivered'`. Keeping the silent-context bundling in one place is
+* the only way to keep the two paths from drifting (proposal
+* hub-inbox-ws-data-plane §3.2 risk #1).
+*
+* Steps:
+*   1. Sort by `createdAt` ASC (PG `RETURNING` does not guarantee order).
+*   2. For each trigger, collect silent context & bulk-ack stale silent rows.
+*   3. Fetch the trigger messages.
+*   4. Build wire payloads via the single dispatcher.
+*
+* Returns `[]` if `claimed` is empty.
+*/
+async function bundleDeliveryWithSilentContext(tx, inboxId, claimed) {
+	if (claimed.length === 0) return [];
+	claimed.sort((a, b) => a.createdAt.getTime() - b.createdAt.getTime());
+	const precedingByEntryId = await collectPrecedingContext(tx, inboxId, claimed);
+	const messageIds = claimed.map((e) => e.messageId);
+	const msgs = await tx.select().from(messages).where(inArray(messages.id, messageIds));
+	const msgMap = new Map(msgs.map((m) => [m.id, m]));
+	const payloads = await buildClientMessagePayloadsForInbox(tx, inboxId, claimed.map((entry) => {
+		const msg = msgMap.get(entry.messageId);
+		if (!msg) throw new Error(`Unexpected: message ${entry.messageId} not found`);
+		return {
+			entryChatId: entry.chatId,
+			precedingMessages: precedingByEntryId.get(entry.id) ?? [],
+			message: {
+				id: msg.id,
+				chatId: msg.chatId,
+				senderId: msg.senderId,
+				format: msg.format,
+				content: msg.content,
+				metadata: msg.metadata,
+				replyToInbox: msg.replyToInbox,
+				replyToChat: msg.replyToChat,
+				inReplyTo: msg.inReplyTo,
+				source: msg.source,
+				createdAt: msg.createdAt.toISOString()
+			}
+		};
+	}));
+	return claimed.map((entry, idx) => {
+		const payload = payloads[idx];
+		if (!payload) throw new Error(`Unexpected: payload for entry ${entry.id} not built`);
+		return {
+			id: entry.id,
+			inboxId: entry.inboxId,
+			messageId: entry.messageId,
+			chatId: entry.chatId,
+			status: entry.status,
+			retryCount: entry.retryCount,
+			createdAt: entry.createdAt.toISOString(),
+			deliveredAt: entry.deliveredAt?.toISOString() ?? null,
+			ackedAt: entry.ackedAt?.toISOString() ?? null,
+			message: payload
+		};
+	});
+}
+/**
+* Realistic upper bound on rows a single NOTIFY references. The unique
+* constraint `(inbox_id, message_id, chat_id)` caps a `(inbox, message)`
+* pair at one row per chatId; the only way to exceed 1 today is the replyTo
+* cross-chat path (`message.ts` writes a second row keyed by the original's
+* `replyToChat`). 8 leaves headroom for any future fan-out variant without
+* requiring a schema change here.
+*/
+const PUSH_CLAIM_BATCH_LIMIT = 8;
+/**
+* WS-push path: atomically claim every pending entry the just-fired
+* `NOTIFY (inboxId:messageId)` references and assemble their wire payloads.
+*
+* Returns `[]` if no row matches — benign race with HTTP poll or another
+* server instance that already claimed the entry. NOTIFY is fire-and-forget
+* (proposal §3.2).
+*
+* Why an array, not a single row: `sendMessage` can write **two** rows for
+* the same `(inbox, messageId)` pair when the recipient is both a chat
+* participant and the `replyToInbox` of an earlier message — the unique key
+* is `(inbox_id, message_id, chat_id)`, so the rows differ by chatId. The
+* old `LIMIT 1` shape would only push the first; the second sat `pending`
+* until reconnect. Aligning with `pollInboxInner`'s `LIMIT N` shape closes
+* that gap and keeps push/poll behaviour interchangeable.
+*/
+async function claimAndBuildForPush(db, inboxId, messageId) {
+	return withSpan("inbox.deliver.push", {
+		"inbox.id": inboxId,
+		"message.id": messageId
+	}, () => db.transaction(async (tx) => {
+		const targetIds = tx.select({ id: inboxEntries.id }).from(inboxEntries).where(and(eq(inboxEntries.inboxId, inboxId), eq(inboxEntries.messageId, messageId), eq(inboxEntries.status, "pending"), eq(inboxEntries.notify, true))).orderBy(asc(inboxEntries.createdAt)).limit(PUSH_CLAIM_BATCH_LIMIT).for("update", { skipLocked: true });
+		return bundleDeliveryWithSilentContext(tx, inboxId, await tx.update(inboxEntries).set({
+			status: "delivered",
+			deliveredAt: /* @__PURE__ */ new Date()
+		}).where(inArray(inboxEntries.id, targetIds)).returning());
+	}));
+}
+/**
+* WS-push backlog path: on agent rebind (or once an in-flight slot frees up
+* after an ack), drain up to `limit` pending `notify=true` entries oldest-
+* first and assemble wire payloads. Identical claim shape to the HTTP poll
+* path — they are intentionally interchangeable so a hot-path bug fixed in
+* one shows up in the other (proposal §3.3 / §3.5).
+*/
+async function claimBacklogForPush(db, inboxId, limit) {
+	return withSpan("inbox.deliver.backlog", {
+		"inbox.id": inboxId,
+		"inbox.backlog.limit": limit
+	}, () => pollInboxInner(db, inboxId, limit));
+}
+/**
+* Per claimed trigger: SELECT silent (notify=false) pending rows in the same
+* chat that occurred between the previous trigger in this batch (or beginning
+* of time) and this trigger, capped by `PRECEDING_CONTEXT_MAX_ENTRIES` and
+* `PRECEDING_CONTEXT_WINDOW_SECONDS`. Returned messages are oldest-first.
+*
+* Side effect: bulk-ack ALL silent pending rows in each chat with
+* createdAt < latest_trigger.createdAt — including ones that fell outside
+* the window/cap. Otherwise stale silent rows would accumulate and re-load
+* on every poll.
+*/
+async function collectPrecedingContext(tx, inboxId, triggers) {
+	const result = /* @__PURE__ */ new Map();
+	const byChat = /* @__PURE__ */ new Map();
+	for (const t of triggers) {
+		if (t.chatId === null) continue;
+		const list = byChat.get(t.chatId) ?? [];
+		list.push(t);
+		byChat.set(t.chatId, list);
+	}
+	for (const [chatId, chatTriggers] of byChat) {
+		chatTriggers.sort((a, b) => a.createdAt.getTime() - b.createdAt.getTime());
+		let prevCreatedAt = null;
+		for (const trigger of chatTriggers) {
+			const preceding = (await tx.select({
+				messageId: messages.id,
+				senderId: messages.senderId,
+				format: messages.format,
+				content: messages.content,
+				metadata: messages.metadata,
+				createdAt: messages.createdAt
+			}).from(inboxEntries).innerJoin(messages, eq(messages.id, inboxEntries.messageId)).where(and(eq(inboxEntries.inboxId, inboxId), eq(inboxEntries.chatId, chatId), eq(inboxEntries.status, "pending"), eq(inboxEntries.notify, false), lt(inboxEntries.createdAt, trigger.createdAt), prevCreatedAt === null ? void 0 : gt(inboxEntries.createdAt, prevCreatedAt), sql`${inboxEntries.createdAt} > NOW() - make_interval(secs => ${PRECEDING_CONTEXT_WINDOW_SECONDS})`)).orderBy(desc(messages.createdAt)).limit(50).for("update", {
+				of: inboxEntries,
+				skipLocked: true
+			})).map((r) => ({
+				id: r.messageId,
+				senderId: r.senderId,
+				format: r.format,
+				content: r.content,
+				metadata: r.metadata ?? {},
+				createdAt: r.createdAt.toISOString()
+			})).reverse();
+			result.set(trigger.id, preceding);
+			prevCreatedAt = trigger.createdAt;
+		}
+		const latestTrigger = chatTriggers[chatTriggers.length - 1];
+		if (latestTrigger) await tx.update(inboxEntries).set({
+			status: "acked",
+			ackedAt: /* @__PURE__ */ new Date()
+		}).where(and(eq(inboxEntries.inboxId, inboxId), eq(inboxEntries.chatId, chatId), eq(inboxEntries.status, "pending"), eq(inboxEntries.notify, false), lt(inboxEntries.createdAt, latestTrigger.createdAt)));
+	}
+	return result;
+}
+async function ackEntry(db, entryId, inboxId) {
+	return withSpan("inbox.ack", {
+		[FIRST_TREE_HUB_ATTR.INBOX_ENTRY_ID]: String(entryId),
+		"inbox.id": inboxId
+	}, async () => {
+		const [entry] = await db.update(inboxEntries).set({
+			status: "acked",
+			ackedAt: /* @__PURE__ */ new Date()
+		}).where(and(eq(inboxEntries.id, entryId), eq(inboxEntries.inboxId, inboxId), eq(inboxEntries.status, "delivered"))).returning();
+		if (!entry) throw new NotFoundError("Inbox entry not found or not in delivered status");
+		return entry;
+	});
+}
+/**
+* Ack a delivered entry from the WS data plane, scoped to the inboxes the
+* connected socket has bound. Returns the acked row on success, `null` if no
+* row matches — a benign outcome the caller should ignore (the entry may
+* have already been acked, timed out, or never belonged to this socket).
+*
+* Distinct from {@link ackEntry} so the WS path can ack without trusting an
+* `inboxId` from the wire — only entries whose `inboxId` is in `inboxIds`
+* are eligible. Empty `inboxIds` short-circuits to `null`.
+*/
+async function ackEntryByIdForBoundAgents(db, entryId, inboxIds) {
+	if (inboxIds.length === 0) return null;
+	return withSpan("inbox.ack.ws", { [FIRST_TREE_HUB_ATTR.INBOX_ENTRY_ID]: String(entryId) }, async () => {
+		const [entry] = await db.update(inboxEntries).set({
+			status: "acked",
+			ackedAt: /* @__PURE__ */ new Date()
+		}).where(and(eq(inboxEntries.id, entryId), inArray(inboxEntries.inboxId, inboxIds), eq(inboxEntries.status, "delivered"))).returning();
+		return entry ?? null;
+	});
+}
+async function renewEntry(db, entryId, inboxId) {
+	const [entry] = await db.update(inboxEntries).set({ deliveredAt: /* @__PURE__ */ new Date() }).where(and(eq(inboxEntries.id, entryId), eq(inboxEntries.inboxId, inboxId), eq(inboxEntries.status, "delivered"))).returning();
+	if (!entry) throw new NotFoundError("Inbox entry not found or not in delivered status");
+	return entry;
+}
+async function resetTimedOutEntries(db, timeoutSeconds = DEFAULT_INBOX_TIMEOUT_SECONDS, maxRetries = DEFAULT_MAX_RETRY_COUNT) {
+	const reset = await db.update(inboxEntries).set({
+		status: "pending",
+		retryCount: sql`${inboxEntries.retryCount} + 1`
+	}).where(and(eq(inboxEntries.status, "delivered"), sql`${inboxEntries.deliveredAt} < NOW() - make_interval(secs => ${timeoutSeconds})`, lt(inboxEntries.retryCount, maxRetries))).returning({ id: inboxEntries.id });
+	const failed = await db.update(inboxEntries).set({ status: "failed" }).where(and(eq(inboxEntries.status, "delivered"), sql`${inboxEntries.deliveredAt} < NOW() - make_interval(secs => ${timeoutSeconds})`, gte(inboxEntries.retryCount, maxRetries))).returning({ id: inboxEntries.id });
+	return {
+		reset: reset.length,
+		failed: failed.length
+	};
+}
+/** Default age (30 days) past which silent rows that no notify-true delivery
+*  ever picked up are physically deleted. */
+const SILENT_ROW_GC_MAX_AGE_SECONDS = 720 * 60 * 60;
+/**
+* Garbage-collect silent inbox rows so the table doesn't grow forever in
+* chats where a `mention_only` agent is never @mentioned.
+*
+* Two cleanup paths:
+*
+*   1. `notify=false AND status='acked'` of any age — these are fully
+*      consumed (either bundled into a previous trigger or aged out via the
+*      bulk-ack in `collectPrecedingContext`); keep them only as long as
+*      the corresponding message rows we link to. The unique constraint
+*      `(inbox_id, message_id, chat_id)` means leaving them around blocks
+*      legitimate retries with the same key.
+*
+*   2. `notify=false AND status='pending' AND createdAt < NOW() - maxAge` —
+*      stale silent rows that no trigger ever caught up with. After 30
+*      days they're useless as preceding context (the @mention almost
+*      certainly already happened or the chat went dormant).
+*
+* Returns the number of rows deleted in each bucket so the background task
+* can log meaningful counts.
+*/
+async function pruneStaleSilentEntries(db, maxAgeSeconds = SILENT_ROW_GC_MAX_AGE_SECONDS) {
+	const ackedDeleted = await db.delete(inboxEntries).where(and(eq(inboxEntries.notify, false), eq(inboxEntries.status, "acked"))).returning({ id: inboxEntries.id });
+	const stalePendingDeleted = await db.delete(inboxEntries).where(and(eq(inboxEntries.notify, false), eq(inboxEntries.status, "pending"), sql`${inboxEntries.createdAt} < NOW() - make_interval(secs => ${maxAgeSeconds})`)).returning({ id: inboxEntries.id });
+	return {
+		ackedDeleted: ackedDeleted.length,
+		stalePendingDeleted: stalePendingDeleted.length
+	};
+}
+/** Per-session state snapshot. One row per (agent, chat) pair, upserted on each session:state message. */
+const agentChatSessions = pgTable("agent_chat_sessions", {
+	agentId: text("agent_id").notNull().references(() => agents.uuid, { onDelete: "cascade" }),
+	chatId: text("chat_id").notNull().references(() => chats.id, { onDelete: "cascade" }),
+	state: text("state").notNull(),
+	updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow()
+}, (table) => [primaryKey({ columns: [table.agentId, table.chatId] })]);
+/**
+* Per-(chat, agent) user state — independent from membership structure.
+*
+* This is the third layer of the chat data model: while `chats` owns
+* the entity and `chat_membership` owns the structural relation
+* (who can speak, who watches), this table owns the user's private
+* state about a chat. The reason it lives apart: structural changes
+* (speaker ↔ watcher, manager rebind, recompute) must never overwrite
+* user-private state — physical separation makes that an invariant
+* rather than a service-layer discipline.
+*
+* Columns evolve incrementally as new per-user state is needed.
+* Currently:
+*   - `last_read_at`, `unread_mention_count` — seeded by PR-A from
+*     the legacy `chat_participants` / `chat_subscriptions` columns.
+*   - `engagement_status` — added in 0040; per-(chat, user) view
+*     state (active / archived / deleted). Auto-revives archived →
+*     active on new message; deleted is sticky (only the user can
+*     restore from the chat detail page).
+*
+* Future fields slated for this table: pinned, mute_until, draft,
+* custom_title, last_seen_at — each as a separate change.
+*
+* Rows are lazy-upserted on first user write (markRead / mention
+* counter bump / engagement transition). Reads use COALESCE for
+* defaults so callers see `'active'` etc. even when no row exists.
+* Service-layer integrity (no FK / CHECK / trigger).
+*
+* See proposals/chat-data-model-restructure.20260512.md §8.6.
+*/
+const chatUserState = pgTable("chat_user_state", {
+	chatId: text("chat_id").notNull(),
+	agentId: text("agent_id").notNull(),
+	lastReadAt: timestamp("last_read_at", { withTimezone: true }),
+	unreadMentionCount: integer("unread_mention_count").notNull().default(0),
+	engagementStatus: text("engagement_status").notNull().default("active")
+}, (table) => [
+	primaryKey({ columns: [table.chatId, table.agentId] }),
+	index("idx_user_state_agent").on(table.agentId),
+	index("idx_user_state_unread").on(table.agentId).where(sql`unread_mention_count > 0`)
+]);
+/** Agent presence and runtime state. Tracked via WebSocket connections; stale entries are cleaned up using server_instances heartbeat. */
+const agentPresence = pgTable("agent_presence", {
+	agentId: text("agent_id").primaryKey().references(() => agents.uuid, { onDelete: "cascade" }),
+	status: text("status").notNull().default("offline"),
+	instanceId: text("instance_id"),
+	connectedAt: timestamp("connected_at", { withTimezone: true }),
+	lastSeenAt: timestamp("last_seen_at", { withTimezone: true }).notNull().defaultNow(),
+	clientId: text("client_id").references(() => clients.id, { onDelete: "set null" }),
+	runtimeType: text("runtime_type"),
+	runtimeVersion: text("runtime_version"),
+	runtimeState: text("runtime_state"),
+	activeSessions: integer("active_sessions"),
+	totalSessions: integer("total_sessions"),
+	runtimeUpdatedAt: timestamp("runtime_updated_at", { withTimezone: true })
+});
+/**
+* Shared access-control primitives. Most route-level gating now lives in
+* `scope/require-*.ts` — this module is reduced to two helpers that need
+* SQL building blocks reused across routes and tests:
+*
+*   - `agentVisibilityCondition` — WHERE clause for "agents visible to a
+*     member" (org-visible OR managerId = the caller's member). Composed
+*     into list queries that already select from `agents`.
+*   - `listAgentsManagedByUser` — cross-org list of agents personally
+*     managed by a user; powers the CLI `agent list --remote` view.
+*
+* Visibility is the same for all roles — admin sees the same set as a
+* regular member. Admin privilege is expressed through manageability
+* (`requireAgentAccess(..., "manage")`), not visibility.
+*/
+/**
+* SQL WHERE conditions for agents visible to a member.
+*   target org + not deleted + (organization-visible OR managerId = caller's member)
+*/
+function agentVisibilityCondition(orgId, memberId) {
+	return and(eq(agents.organizationId, orgId), ne(agents.status, AGENT_STATUSES.DELETED), or(eq(agents.visibility, AGENT_VISIBILITY.ORGANIZATION), eq(agents.managerId, memberId)));
+}
+/**
+* Cross-org listing helper for "agents I personally manage". Used by the
+* CLI `agent list --remote` view — JOINs `agents → members.id` and filters
+* by `members.user_id`.
+*/
+async function listAgentsManagedByUser(db, userId) {
+	return db.select({
+		uuid: agents.uuid,
+		name: agents.name,
+		displayName: agents.displayName,
+		type: agents.type,
+		organizationId: agents.organizationId,
+		inboxId: agents.inboxId,
+		visibility: agents.visibility,
+		runtimeProvider: agents.runtimeProvider,
+		clientId: agents.clientId
+	}).from(agents).innerJoin(members, eq(agents.managerId, members.id)).where(and(eq(members.userId, userId), eq(members.status, "active"), ne(agents.status, AGENT_STATUSES.DELETED)));
+}
+/**
+* Resolve the UUID of the "default" organization. Internal use only —
+* webhooks, fallbacks, etc. The HTTP API layer no longer falls back to
+* the JWT default org.
+*/
+async function resolveDefaultOrgId(db) {
+	const [org] = await db.select({ id: organizations.id }).from(organizations).where(eq(organizations.name, "default")).limit(1);
+	if (!org) throw new Error("Default organization not found. Ensure the server has started and ensureDefaultOrganization() ran.");
+	return org.id;
+}
+async function getOrganization(db, id) {
+	const [org] = await db.select().from(organizations).where(eq(organizations.id, id)).limit(1);
+	if (!org) throw new NotFoundError(`Organization "${id}" not found`);
+	return org;
+}
+async function updateOrganization(db, id, data) {
+	const updates = { updatedAt: /* @__PURE__ */ new Date() };
+	if (data.name !== void 0) updates.name = data.name;
+	if (data.displayName !== void 0) updates.displayName = data.displayName;
+	if (data.maxAgents !== void 0) updates.maxAgents = data.maxAgents;
+	if (data.maxMessagesPerMinute !== void 0) updates.maxMessagesPerMinute = data.maxMessagesPerMinute;
+	if (data.features !== void 0) updates.features = data.features;
+	try {
+		const [org] = await db.update(organizations).set(updates).where(eq(organizations.id, id)).returning();
+		if (!org) throw new NotFoundError(`Organization "${id}" not found`);
+		return org;
+	} catch (err) {
+		if ((err?.code ?? err?.cause?.code ?? "") === "23505") throw new ConflictError(`Organization name "${data.name}" is already taken`);
+		throw err;
+	}
+}
+/**
+* Ensure the default organization exists. Called on server startup.
+* Uses a fixed UUID for the default org to ensure idempotency.
+*/
+async function ensureDefaultOrganization(db) {
+	const [existing] = await db.select({ id: organizations.id }).from(organizations).where(eq(organizations.name, "default")).limit(1);
+	if (existing) return existing;
+	const id = uuidv7();
+	const [org] = await db.insert(organizations).values({
+		id,
+		name: "default",
+		displayName: "Default Organization"
+	}).onConflictDoNothing().returning();
+	return org ?? existing;
+}
 /**
 * Single source of truth for writing speaker rows into `chat_membership`.
 *
@@ -563,586 +1163,615 @@ function ensureCanJoin(membership) {
 	if (membership === "participant") throw new ConflictError("Already a participant in this chat");
 	if (membership === null) throw new ForbiddenError("Not a watcher of this chat — open the chat from your workspace before joining");
 }
-async function createChat(db, creatorId, data) {
-	const chatId = randomUUID();
-	const allParticipantIds = new Set([creatorId, ...data.participantIds]);
-	const existingAgents = await db.select({
-		id: agents.uuid,
-		organizationId: agents.organizationId,
-		type: agents.type
-	}).from(agents).where(inArray(agents.uuid, [...allParticipantIds]));
-	if (existingAgents.length !== allParticipantIds.size) {
-		const found = new Set(existingAgents.map((a) => a.id));
-		throw new BadRequestError(`Agents not found: ${[...allParticipantIds].filter((id) => !found.has(id)).join(", ")}`);
-	}
-	const creator = existingAgents.find((a) => a.id === creatorId);
-	if (!creator) throw new Error("Unexpected: creator not in existingAgents");
-	const orgId = creator.organizationId;
-	const crossOrg = existingAgents.filter((a) => a.organizationId !== orgId);
-	if (crossOrg.length > 0) throw new BadRequestError(`Cross-organization chat not allowed: ${crossOrg.map((a) => a.id).join(", ")}`);
-	return db.transaction(async (tx) => {
-		const [chat] = await tx.insert(chats).values({
-			id: chatId,
-			organizationId: orgId,
-			type: data.type,
-			topic: data.topic ?? null,
-			metadata: data.metadata ?? {}
-		}).returning();
-		await addChatParticipants(tx, chatId, [...allParticipantIds].map((agentId) => ({
-			agentId,
-			role: agentId === creatorId ? "owner" : "member"
-		})));
-		await recomputeChatWatchers(tx, 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,
-			participants
-		};
-	});
+/**
+* Names beginning with `__` are reserved for Hub-internal pseudo agents.
+* User-facing creation must not be able to squat on them, otherwise
+* internal traffic could be routed through a real account.
+*/
+const RESERVED_AGENT_NAME_PREFIX = "__";
+/**
+* Derive the relative URL clients should use to fetch a manager-uploaded
+* avatar image. Returns `null` when no image is set. Embeds the upload
+* timestamp as `?v=<epoch>` so a fresh upload busts any browser cache
+* that may have memoised the previous version.
+*
+* Auth: the image route is intentionally public read — the URL leaks no
+* more than the agent's UUID, which is already required to address it.
+* Keeping it unauthenticated lets `<img src>` render without bespoke
+* fetch-and-blob plumbing.
+*/
+function agentAvatarImageUrl(uuid, updatedAt) {
+	if (!updatedAt) return null;
+	return `/api/v1/agents/${uuid}/avatar?v=${updatedAt.getTime()}`;
 }
-async function getChat(db, chatId) {
-	const [chat] = await db.select().from(chats).where(eq(chats.id, chatId)).limit(1);
-	if (!chat) throw new NotFoundError(`Chat "${chatId}" not found`);
-	return chat;
+/**
+* True iff `clients.metadata.capabilities` is a non-empty object — i.e. the
+* client has reported at least one runtime probe result. Used to distinguish
+* "we don't know what's installed yet" (empty / never reported) from
+* "client explicitly reports this provider is missing".
+*/
+function clientCapabilitiesReported(metadata) {
+	if (!metadata || typeof metadata !== "object") return false;
+	const caps = metadata.capabilities;
+	if (!caps || typeof caps !== "object") return false;
+	return Object.keys(caps).length > 0;
 }
-async function getChatDetail(db, chatId) {
-	const chat = await getChat(db, chatId);
-	const participants = await db.select().from(chatMembership).where(and(eq(chatMembership.chatId, chatId), eq(chatMembership.accessMode, "speaker")));
-	return {
-		...chat,
-		participants
-	};
+/**
+* Inspect a `clients.metadata.capabilities` blob (jsonb) for a specific
+* runtime provider entry. Capabilities live under the `metadata.capabilities`
+* subkey (Option C); the column is unstructured at the DB layer, so we
+* defensively narrow before key access.
+*
+* "Supports" requires the entry's SDK to be **available** — `state: "ok"` or
+* `state: "unauthenticated"`. A `missing` or `error` entry is *reported* but
+* not usable, so we explicitly reject those rather than treating mere key
+* presence as support. Auth state is left to the user to fix at runtime
+* (the re-bind dialog surfaces an `unauthenticated` hint).
+*/
+function clientSupportsRuntimeProvider(metadata, provider) {
+	if (!metadata || typeof metadata !== "object") return false;
+	const caps = metadata.capabilities;
+	if (!caps || typeof caps !== "object") return false;
+	const entry = caps[provider];
+	if (!entry || typeof entry !== "object") return false;
+	return entry.available === true;
 }
-async function listChats(db, agentId, limit, cursor) {
-	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
-	};
-	const where = cursor ? and(inArray(chats.id, chatIds), lt(chats.updatedAt, new Date(cursor))) : inArray(chats.id, chatIds);
-	const rows = await db.select().from(chats).where(where).orderBy(desc(chats.updatedAt)).limit(limit + 1);
-	const hasMore = rows.length > limit;
-	const items = hasMore ? rows.slice(0, limit) : rows;
-	const last = items[items.length - 1];
-	return {
-		items,
-		nextCursor: hasMore && last ? last.updatedAt.toISOString() : null
-	};
+/** Default visibility per agent type. */
+function defaultVisibility(type) {
+	switch (type) {
+		case "human":
+		case "autonomous_agent": return AGENT_VISIBILITY.ORGANIZATION;
+		case "personal_assistant": return AGENT_VISIBILITY.PRIVATE;
+		default: return AGENT_VISIBILITY.PRIVATE;
+	}
 }
 /**
-* List participants of a chat with their agent names — used by the client
-* runtime to resolve `@<name>` mentions against the authoritative participant
-* set (see proposals/hub-agent-messaging-reply-and-mentions §4).
+* Resolve + validate the client that will own the new agent.
+*
+* Rule (unified-user-token, post-first-bind relaxation):
+*   - Human agents represent the member themselves and have no runtime; a
+*     missing `clientId` is required and the column stays NULL.
+*   - Non-human agents MAY omit `clientId` at creation; the row stays NULL
+*     and is claimed on the first WS bind (see `api/agent/ws-client.ts`).
+*   - When a non-human agent IS created with a `clientId`, the pinned client
+*     must already be owned by the manager's user (Rule R-RUN).
 */
-async function listChatParticipantsWithNames(db, chatId) {
-	return await db.select({
-		agentId: chatMembership.agentId,
-		role: chatMembership.role,
-		mode: chatMembership.mode,
-		joinedAt: chatMembership.joinedAt,
-		name: agents.name,
-		displayName: agents.displayName,
-		type: agents.type
-	}).from(chatMembership).innerJoin(agents, eq(chatMembership.agentId, agents.uuid)).where(and(eq(chatMembership.chatId, chatId), eq(chatMembership.accessMode, "speaker")));
+/**
+* Check that a client's reported capabilities show the given runtime provider
+* as **available** (SDK installed, regardless of auth state).
+*
+* Tri-state semantics by `clients.metadata.capabilities` shape:
+*   - empty / absent — client hasn't probed yet (newly registered or pre-P2
+*     install). Treat as "unknown" and allow; the in-band repair path
+*     (RUNTIME_PROVIDER_MISMATCH on bind) catches actual incompatibility.
+*   - reported, entry shows `state: ok | unauthenticated` (i.e. `available:
+*     true`) — allow.
+*   - reported, entry missing OR `state: missing | error` — block unless
+*     `force` is set. We deliberately do NOT treat mere key presence as
+*     support: probeCapabilities() always emits an entry per built-in
+*     provider, including `{ state: "missing" }` for absent SDKs.
+*
+* Skipped entirely for human agents (no clientId) and when `force` is set
+* (e.g. operator overrides for an offline client).
+*/
+async function ensureClientSupportsRuntimeProvider(db, clientId, runtimeProvider, options = {}) {
+	if (clientId === null) return;
+	if (options.force) return;
+	const [client] = await db.select({ metadata: clients.metadata }).from(clients).where(eq(clients.id, clientId)).limit(1);
+	if (!client) return;
+	if (!clientCapabilitiesReported(client.metadata)) return;
+	if (!clientSupportsRuntimeProvider(client.metadata, runtimeProvider)) throw new BadRequestError(`Client "${clientId}" does not have runtime provider "${runtimeProvider}" available. Install the matching SDK on that machine and re-run capability detection, or retry with \`force: true\` if the client is offline / capabilities are stale.`);
 }
-async function assertParticipant(db, chatId, agentId) {
-	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");
+async function resolveAgentClient(db, data) {
+	if (data.type === "human") {
+		if (data.clientId) throw new BadRequestError("Human agents cannot be pinned to a client");
+		return null;
+	}
+	if (!data.clientId) return null;
+	const [manager] = await db.select({ userId: members.userId }).from(members).where(eq(members.id, data.managerId)).limit(1);
+	if (!manager) throw new BadRequestError(`Manager "${data.managerId}" not found`);
+	const [client] = await db.select({
+		id: clients.id,
+		userId: clients.userId
+	}).from(clients).where(eq(clients.id, data.clientId)).limit(1);
+	if (!client) throw new BadRequestError(`Client "${data.clientId}" not found`);
+	if (!client.userId) throw new BadRequestError(`Client "${data.clientId}" has not been claimed by a user yet. Have the operator run \`first-tree-hub connect <token>\` on that machine before pinning an agent to it.`);
+	if (client.userId !== manager.userId) throw new ForbiddenError(`Client "${data.clientId}" is not owned by the manager's user — pick a client belonging to that user.`);
+	return client.id;
 }
 /**
-* Non-throwing membership check. Used by routing logic that needs to fall
-* back to a different chat when the candidate target isn't a member of the
-* caller's current chat (see `sendToAgent`'s current-chat routing branch).
+* Validate a `delegateMention` write at the service layer. Two checks:
+*   1. Target uuid must resolve to an existing agent — dangling references
+*      would silently break webhook delegation at runtime.
+*   2. Target must belong to the same organization as the source agent —
+*      cross-org delegate links are rejected here at the source so the
+*      database never accumulates dirty rows. The webhook router has a
+*      defense-in-depth check that filters them at fan-out time, but this
+*      keeps the data clean and gives the admin UI an immediate 422 instead
+*      of a silent runtime drop.
+*
+* `null` clears the field — handled by the caller; we are only invoked when
+* the caller wrote a non-null uuid.
 */
-async function isParticipant(db, chatId, agentId) {
-	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);
+async function validateDelegateMentionTarget(db, targetUuid, sourceOrgId) {
+	const [target] = await db.select({
+		uuid: agents.uuid,
+		organizationId: agents.organizationId
+	}).from(agents).where(eq(agents.uuid, targetUuid)).limit(1);
+	if (!target) throw new BadRequestError(`delegateMention target "${targetUuid}" not found`);
+	if (target.organizationId !== sourceOrgId) throw new BadRequestError("delegateMention target must belong to the same organization as the agent");
 }
-/** 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({ 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: 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);
+/**
+* Service-layer guard: `delegateMention` is only available for `human` agents.
+* Mirrors the Web UI in `identity-section.tsx`, which only renders the
+* delegate-mention selector when `agent.type === "human"`. Without this
+* server-side check, CLI / Admin API / internal scripts could write
+* delegateMention onto non-human rows, silently re-enabling the
+* autonomous-agent-self-mention path that resolveAudience would then fan
+* out. Called from `createAgent` / `updateAgent` before
+* `validateDelegateMentionTarget` so a wrong source type fails fast without
+* the target lookup round-trip.
+*/
+function assertDelegateMentionAllowed(sourceType) {
+	if (sourceType !== AGENT_TYPES.HUMAN) throw new BadRequestError("delegateMention can only be set on human agents");
 }
-async function addParticipant(db, chatId, requesterId, data) {
-	const chat = await getChat(db, chatId);
-	await assertParticipant(db, chatId, requesterId);
-	const [targetAgent] = await db.select({
-		id: agents.uuid,
-		organizationId: agents.organizationId
-	}).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({ 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: 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);
+/**
+* Pick the first admin member in the org for internal system agents. Throws
+* if the org has no admin — the caller should surface the error so an admin
+* is created before the system tries to register more agents.
+*/
+async function resolveFallbackManagerId(db, orgId) {
+	const [row] = await db.select({ id: members.id }).from(members).where(and(eq(members.organizationId, orgId), eq(members.role, "admin"))).orderBy(members.createdAt).limit(1);
+	if (!row) throw new BadRequestError(`Cannot create agent in organization "${orgId}" — no admin member exists. Create an admin member first (see \`first-tree-hub onboard\`).`);
+	return row.id;
+}
+async function createAgent(db, data, options = {}) {
+	const uuid = uuidv7();
+	const name = data.name ?? null;
+	const runtimeProvider = data.runtimeProvider ?? "claude-code";
+	if (name?.startsWith(RESERVED_AGENT_NAME_PREFIX)) throw new BadRequestError(`Agent name "${name}" is reserved — names starting with "${RESERVED_AGENT_NAME_PREFIX}" are Hub-internal`);
+	if (name && isReservedAgentName(name)) throw new BadRequestError(`Agent name "${name}" is reserved — pick a different one.`);
+	const inboxId = `inbox_${uuid}`;
+	let orgId;
+	let managerId;
+	if (data.managerId && data.organizationId) {
+		orgId = data.organizationId;
+		managerId = data.managerId;
+	} else if (data.managerId) {
+		const [manager] = await db.select({
+			id: members.id,
+			organizationId: members.organizationId
+		}).from(members).where(eq(members.id, data.managerId)).limit(1);
+		if (!manager) throw new BadRequestError(`Manager "${data.managerId}" not found`);
+		orgId = manager.organizationId;
+		managerId = manager.id;
+	} else {
+		orgId = data.organizationId ?? await resolveDefaultOrgId(db);
+		managerId = await resolveFallbackManagerId(db, orgId);
+	}
+	const clientId = await resolveAgentClient(db, {
+		clientId: data.clientId,
+		managerId,
+		type: data.type
 	});
-	invalidateChatAudience(chatId);
-	return db.select().from(chatMembership).where(and(eq(chatMembership.chatId, chatId), eq(chatMembership.accessMode, "speaker")));
+	await ensureClientSupportsRuntimeProvider(db, clientId, runtimeProvider, { force: options.force });
+	if (data.delegateMention) {
+		assertDelegateMentionAllowed(data.type);
+		await validateDelegateMentionTarget(db, data.delegateMention, orgId);
+	}
+	const [org] = await db.select({ maxAgents: organizations.maxAgents }).from(organizations).where(eq(organizations.id, orgId)).limit(1);
+	if (org && org.maxAgents > 0) {
+		if (((await db.select({ value: count() }).from(agents).where(and(eq(agents.organizationId, orgId), ne(agents.status, AGENT_STATUSES.DELETED))))[0]?.value ?? 0) >= org.maxAgents) throw new ForbiddenError(`Organization "${orgId}" has reached its agent limit (${org.maxAgents}). Upgrade your plan or delete unused agents.`);
+	}
+	const resolvedDisplayName = data.displayName?.trim() || name || "Unnamed Agent";
+	try {
+		return await db.transaction(async (tx) => {
+			const [row] = await tx.insert(agents).values({
+				uuid,
+				name,
+				organizationId: orgId,
+				type: data.type,
+				displayName: resolvedDisplayName,
+				delegateMention: data.delegateMention ?? null,
+				inboxId,
+				source: data.source ?? null,
+				visibility: data.visibility ?? defaultVisibility(data.type),
+				metadata: data.metadata ?? {},
+				managerId,
+				clientId,
+				runtimeProvider
+			}).returning();
+			if (!row) throw new Error("Unexpected: INSERT RETURNING produced no row");
+			const initialPayload = defaultRuntimeConfigPayload(runtimeProvider);
+			if (data.gitRepos && data.gitRepos.length > 0) initialPayload.gitRepos = data.gitRepos;
+			await tx.insert(agentConfigs).values({
+				agentId: row.uuid,
+				version: 1,
+				payload: initialPayload,
+				updatedBy: "system"
+			}).onConflictDoNothing();
+			return row;
+		});
+	} catch (err) {
+		if ((err?.code ?? err?.cause?.code ?? "") === "23505" && name) throw new ConflictError(`Agent name "${name}" already exists in organization "${orgId}"`);
+		throw err;
+	}
 }
-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(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(chatMembership).where(and(eq(chatMembership.chatId, chatId), eq(chatMembership.accessMode, "speaker")));
+async function checkAgentNameAvailability(db, orgId, name) {
+	if (!AGENT_NAME_REGEX.test(name)) return {
+		available: false,
+		reason: "invalid"
+	};
+	if (isReservedAgentName(name) || name.startsWith(RESERVED_AGENT_NAME_PREFIX)) return {
+		available: false,
+		reason: "reserved"
+	};
+	const [existing] = await db.select({ uuid: agents.uuid }).from(agents).where(and(eq(agents.organizationId, orgId), eq(agents.name, name), ne(agents.status, AGENT_STATUSES.DELETED))).limit(1);
+	return existing ? {
+		available: false,
+		reason: "taken"
+	} : { available: true };
+}
+async function getAgent(db, uuid) {
+	const [agent] = await db.select().from(agents).where(and(eq(agents.uuid, uuid), ne(agents.status, AGENT_STATUSES.DELETED))).limit(1);
+	if (!agent) throw new NotFoundError(`Agent "${uuid}" not found`);
+	return agent;
 }
 /**
-* List chats visible to a member, grouped by agent.
-* A member sees chats where:
-*   1. Their human agent is a participant, OR
-*   2. Any agent they manage (managerId = memberId) is a participant (supervision)
+* Admin-only variant: return every non-deleted agent in the org, ignoring
+* the visibility filter. Used by the `/admin` "All Agents" view so a team
+* admin can see and act on private agents owned by other members. The
+* route layer is responsible for gating this to admin callers — the
+* service does not enforce role by itself, but it does enforce org scope
+* and the not-deleted predicate.
 */
-async function listChatsForMember(db, memberId, humanAgentId) {
-	const managedAgents = await db.select({
+async function listAgentsForAdmin(db, scope, limit, cursor) {
+	const conditions = [eq(agents.organizationId, scope.organizationId), ne(agents.status, AGENT_STATUSES.DELETED)];
+	if (cursor) conditions.push(lt(agents.createdAt, new Date(cursor)));
+	const where = and(...conditions);
+	const rows = await db.select({
 		uuid: agents.uuid,
 		name: agents.name,
+		organizationId: agents.organizationId,
 		type: agents.type,
-		displayName: agents.displayName
-	}).from(agents).where(eq(agents.managerId, memberId));
-	const agentMap = /* @__PURE__ */ new Map();
-	for (const a of managedAgents) agentMap.set(a.uuid, a);
-	if (!agentMap.has(humanAgentId)) {
-		const [ha] = await db.select({
-			uuid: agents.uuid,
-			name: agents.name,
-			type: agents.type,
-			displayName: agents.displayName
-		}).from(agents).where(eq(agents.uuid, humanAgentId)).limit(1);
-		if (ha) agentMap.set(ha.uuid, ha);
+		displayName: agents.displayName,
+		delegateMention: agents.delegateMention,
+		inboxId: agents.inboxId,
+		status: agents.status,
+		visibility: agents.visibility,
+		metadata: agents.metadata,
+		managerId: agents.managerId,
+		clientId: agents.clientId,
+		runtimeProvider: agents.runtimeProvider,
+		avatarColorToken: agents.avatarColorToken,
+		avatarImageUpdatedAt: agents.avatarImageUpdatedAt,
+		createdAt: agents.createdAt,
+		updatedAt: agents.updatedAt,
+		presenceStatus: agentPresence.status,
+		runtimeType: agentPresence.runtimeType,
+		runtimeState: agentPresence.runtimeState,
+		activeSessions: agentPresence.activeSessions
+	}).from(agents).leftJoin(agentPresence, eq(agents.uuid, agentPresence.agentId)).where(where).orderBy(desc(agents.createdAt)).limit(limit + 1);
+	const hasMore = rows.length > limit;
+	const items = hasMore ? rows.slice(0, limit) : rows;
+	const last = items[items.length - 1];
+	return {
+		items,
+		nextCursor: hasMore && last ? last.createdAt.toISOString() : null
+	};
+}
+/**
+* List agents visible to a specific member.
+* Uses agentVisibilityCondition from access-control (same rules for all roles).
+*/
+async function listAgentsForMember(db, scope, limit, cursor, type) {
+	const conditions = [agentVisibilityCondition(scope.organizationId, scope.memberId)];
+	if (cursor) conditions.push(lt(agents.createdAt, new Date(cursor)));
+	if (type) conditions.push(eq(agents.type, type));
+	const where = and(...conditions);
+	const rows = await db.select({
+		uuid: agents.uuid,
+		name: agents.name,
+		organizationId: agents.organizationId,
+		type: agents.type,
+		displayName: agents.displayName,
+		delegateMention: agents.delegateMention,
+		inboxId: agents.inboxId,
+		status: agents.status,
+		visibility: agents.visibility,
+		metadata: agents.metadata,
+		managerId: agents.managerId,
+		clientId: agents.clientId,
+		runtimeProvider: agents.runtimeProvider,
+		avatarColorToken: agents.avatarColorToken,
+		avatarImageUpdatedAt: agents.avatarImageUpdatedAt,
+		createdAt: agents.createdAt,
+		updatedAt: agents.updatedAt,
+		presenceStatus: agentPresence.status,
+		runtimeType: agentPresence.runtimeType,
+		runtimeState: agentPresence.runtimeState,
+		activeSessions: agentPresence.activeSessions
+	}).from(agents).leftJoin(agentPresence, eq(agents.uuid, agentPresence.agentId)).where(where).orderBy(desc(agents.createdAt)).limit(limit + 1);
+	const hasMore = rows.length > limit;
+	const items = hasMore ? rows.slice(0, limit) : rows;
+	const last = items[items.length - 1];
+	return {
+		items,
+		nextCursor: hasMore && last ? last.createdAt.toISOString() : null
+	};
+}
+async function updateAgent(db, uuid, data) {
+	const agent = await getAgent(db, uuid);
+	if (data.clientId !== void 0) {
+		if (data.clientId === null) throw new BadRequestError("clientId cannot be cleared — once bound, an agent stays bound to its client");
+		if (agent.clientId !== null && agent.clientId !== data.clientId) throw new BadRequestError("clientId is immutable through this entry — cross-client moves go through rebindAgent (PATCH /agents/:uuid/rebind), which runs owner / org / capability checks atomically.");
 	}
-	const agentIds = [...agentMap.keys()];
-	if (agentIds.length === 0) return [];
-	const participations = await db.select({
-		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();
-	for (const p of participations) {
-		const list = agentChatMap.get(p.agentId) ?? [];
-		list.push(p.chatId);
-		agentChatMap.set(p.agentId, list);
+	const updates = { updatedAt: /* @__PURE__ */ new Date() };
+	if (data.type !== void 0) {
+		if (data.type !== AGENT_TYPES.HUMAN && agent.delegateMention !== null && data.delegateMention !== null) throw new BadRequestError("Cannot change type away from `human` while delegateMention is set — clear delegateMention in the same patch.");
+		updates.type = data.type;
 	}
-	const chatRows = await db.select({
-		id: chats.id,
-		type: chats.type,
-		topic: chats.topic,
-		metadata: chats.metadata,
-		createdAt: chats.createdAt,
-		updatedAt: chats.updatedAt,
-		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));
-	const result = [];
-	for (const [agentId, agentChatIds] of agentChatMap) {
-		const agentInfo = agentMap.get(agentId);
-		if (!agentInfo) continue;
-		const agentChats = agentChatIds.map((chatId) => {
-			const chat = chatMap.get(chatId);
-			if (!chat) return null;
-			const isSupervisionOnly = agentId !== humanAgentId && !humanParticipantChatIds.has(chatId);
-			return {
-				id: chat.id,
-				type: chat.type,
-				topic: chat.topic,
-				participantCount: chat.participantCount,
-				isSupervisionOnly,
-				createdAt: chat.createdAt.toISOString(),
-				updatedAt: chat.updatedAt.toISOString()
-			};
-		}).filter((c) => c !== null);
-		if (agentChats.length > 0) result.push({
-			agent: agentInfo,
-			chats: agentChats
+	if (data.displayName !== void 0) updates.displayName = data.displayName;
+	if (data.delegateMention !== void 0) {
+		if (data.delegateMention !== null) {
+			assertDelegateMentionAllowed(data.type ?? agent.type);
+			await validateDelegateMentionTarget(db, data.delegateMention, agent.organizationId);
+		}
+		updates.delegateMention = data.delegateMention;
+	}
+	if (data.visibility !== void 0) updates.visibility = data.visibility;
+	if (data.metadata !== void 0) updates.metadata = data.metadata;
+	if (data.avatarColorToken !== void 0) updates.avatarColorToken = data.avatarColorToken;
+	if (data.managerId !== void 0) {
+		if (data.managerId === null) throw new BadRequestError("managerId cannot be cleared — every agent must have a manager");
+		const [manager] = await db.select({
+			id: members.id,
+			organizationId: members.organizationId
+		}).from(members).where(eq(members.id, data.managerId)).limit(1);
+		if (!manager) throw new BadRequestError(`Manager "${data.managerId}" not found`);
+		if (manager.organizationId !== agent.organizationId) throw new BadRequestError("Manager must belong to the same organization as the agent");
+		updates.managerId = data.managerId;
+	}
+	if (data.clientId !== void 0 && data.clientId !== null && agent.clientId === null) {
+		const resolvedClientId = await resolveAgentClient(db, {
+			clientId: data.clientId,
+			managerId: updates.managerId ?? agent.managerId,
+			type: agent.type
 		});
+		if (resolvedClientId !== null) updates.clientId = resolvedClientId;
 	}
-	return result;
+	const [updated] = await db.update(agents).set(updates).where(eq(agents.uuid, agent.uuid)).returning();
+	if (!updated) throw new Error("Unexpected: UPDATE RETURNING produced no row");
+	if (data.managerId !== void 0 && data.managerId !== agent.managerId) await recomputeWatchersForAgent(db, agent.uuid);
+	return updated;
 }
 /**
-* Manager joins a chat. Adds their human agent as a participant.
-* Requires the member to have supervision rights (manages at least one existing participant).
+* Atomically re-bind an agent to a new client and/or runtime provider.
+*
+* Validations: agent must exist and not be human; new client must belong to
+* the same owner (manager.userId) and same organization; client must report
+* the requested runtime provider in its capabilities (skipped under `force`).
+*
+* Intended caller: PATCH /agents/:uuid/rebind. The Web "Re-bind"
+* dialog routes both same-client runtime-only switches and cross-client
+* moves through this single entry.
+*
+* NOTE: active sessions on the previous client are not auto-suspended in P1.
+* P3 will wire in cross-service coordination (inbox + presence + session)
+* so the destination client can resume cleanly.
 */
-async function joinChat(db, chatId, memberId, humanAgentId) {
-	const chat = await getChat(db, chatId);
-	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) => {
-		if (wouldUpgradeToGroup(participantAgentIds.length, 1)) await changeChatType(tx, chatId, "group");
-		await addChatParticipants(tx, chatId, [{
-			agentId: humanAgentId,
-			role: "member"
-		}], {
-			assertHuman: true,
-			upgradeWatcherToSpeaker: true
-		});
-		await recomputeChatWatchers(tx, chatId);
+async function rebindAgent(db, uuid, data) {
+	const agent = await getAgent(db, uuid);
+	if (agent.type === "human") throw new BadRequestError("Human agents have no runtime — they cannot be re-bound to a client.");
+	const newClientId = await resolveAgentClient(db, {
+		clientId: data.clientId,
+		managerId: agent.managerId,
+		type: agent.type
 	});
-	invalidateChatAudience(chatId);
-	return db.select().from(chatMembership).where(and(eq(chatMembership.chatId, chatId), eq(chatMembership.accessMode, "speaker")));
+	if (newClientId === null) throw new BadRequestError("Rebind requires a non-null clientId.");
+	await ensureClientSupportsRuntimeProvider(db, newClientId, data.runtimeProvider, { force: data.force });
+	const [updated] = await db.update(agents).set({
+		clientId: newClientId,
+		runtimeProvider: data.runtimeProvider,
+		updatedAt: /* @__PURE__ */ new Date()
+	}).where(eq(agents.uuid, uuid)).returning();
+	if (!updated) throw new Error("Unexpected: UPDATE RETURNING produced no row");
+	return updated;
 }
 /**
-* Manager leaves a chat. Removes their human agent from participants.
-* Only allowed if the human agent is a participant.
-*
-* Delegates the participant→watcher transition to `leaveAsParticipant`
-* so admin-side and `/me/chats/:id/leave` share one canonical path. The
-* earlier "recompute then UPDATE-back state" variant violated the design
-* rule that recompute is only for set rebuild — never on a transition
-* path (review #228 issue #2). The returned participant list is fetched
-* after the tx commits, matching the admin route's existing contract.
+* Reactivate a suspended agent.
 */
-async function leaveChat(db, chatId, humanAgentId) {
-	await leaveAsParticipant(db, chatId, humanAgentId);
-	invalidateChatAudience(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({
+async function reactivateAgent(db, uuid) {
+	const [existing] = await db.select({
 		uuid: agents.uuid,
-		organizationId: agents.organizationId,
-		type: agents.type
-	}).from(agents).where(inArray(agents.uuid, [agentAId, agentBId]));
-	const agentA = ends.find((a) => a.uuid === agentAId);
-	if (!agentA) throw new NotFoundError(`Agent "${agentAId}" not found`);
-	const agentB = ends.find((a) => a.uuid === 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 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];
-	}
-	const chatId = randomUUID();
-	return db.transaction(async (tx) => {
-		const [chat] = await tx.insert(chats).values({
-			id: chatId,
-			organizationId: orgId,
-			type: "direct"
-		}).returning();
-		await addChatParticipants(tx, chatId, [{
-			agentId: agentAId,
-			role: "member"
-		}, {
-			agentId: agentBId,
-			role: "member"
-		}]);
-		await recomputeChatWatchers(tx, chatId);
-		if (!chat) throw new Error("Unexpected: INSERT RETURNING produced no row");
-		return chat;
-	});
+		status: agents.status
+	}).from(agents).where(eq(agents.uuid, uuid)).limit(1);
+	if (!existing || existing.status === AGENT_STATUSES.DELETED) throw new NotFoundError(`Agent "${uuid}" not found`);
+	if (existing.status !== AGENT_STATUSES.SUSPENDED) throw new BadRequestError("Only suspended agents can be reactivated.");
+	const [agent] = await db.update(agents).set({
+		status: AGENT_STATUSES.ACTIVE,
+		updatedAt: /* @__PURE__ */ new Date()
+	}).where(eq(agents.uuid, uuid)).returning();
+	if (!agent) throw new Error("Unexpected: UPDATE RETURNING produced no row");
+	return agent;
 }
-/** Agent presence and runtime state. Tracked via WebSocket connections; stale entries are cleaned up using server_instances heartbeat. */
-const agentPresence = pgTable("agent_presence", {
-	agentId: text("agent_id").primaryKey().references(() => agents.uuid, { onDelete: "cascade" }),
-	status: text("status").notNull().default("offline"),
-	instanceId: text("instance_id"),
-	connectedAt: timestamp("connected_at", { withTimezone: true }),
-	lastSeenAt: timestamp("last_seen_at", { withTimezone: true }).notNull().defaultNow(),
-	clientId: text("client_id").references(() => clients.id, { onDelete: "set null" }),
-	runtimeType: text("runtime_type"),
-	runtimeVersion: text("runtime_version"),
-	runtimeState: text("runtime_state"),
-	activeSessions: integer("active_sessions"),
-	totalSessions: integer("total_sessions"),
-	runtimeUpdatedAt: timestamp("runtime_updated_at", { withTimezone: true })
-});
 /**
-* Shared access-control primitives. Most route-level gating now lives in
-* `scope/require-*.ts` — this module is reduced to two helpers that need
-* SQL building blocks reused across routes and tests:
-*
-*   - `agentVisibilityCondition` — WHERE clause for "agents visible to a
-*     member" (org-visible OR managerId = the caller's member). Composed
-*     into list queries that already select from `agents`.
-*   - `listAgentsManagedByUser` — cross-org list of agents personally
-*     managed by a user; powers the CLI `agent list --remote` view.
-*
-* Visibility is the same for all roles — admin sees the same set as a
-* regular member. Admin privilege is expressed through manageability
-* (`requireAgentAccess(..., "manage")`), not visibility.
+* Suspend an agent. Once suspended, Rule R-RUN refuses every runtime bind
+* and every agent-selector-authorised HTTP call.
 */
+async function suspendAgent(db, uuid) {
+	const [agent] = await db.update(agents).set({
+		status: AGENT_STATUSES.SUSPENDED,
+		updatedAt: /* @__PURE__ */ new Date()
+	}).where(and(eq(agents.uuid, uuid), ne(agents.status, AGENT_STATUSES.DELETED))).returning();
+	if (!agent) throw new NotFoundError(`Agent "${uuid}" not found`);
+	return agent;
+}
 /**
-* SQL WHERE conditions for agents visible to a member.
-*   target org + not deleted + (organization-visible OR managerId = caller's member)
+* Delete an agent. Only allowed when status is "suspended". Sets name to NULL
+* so the name becomes reusable.
 */
-function agentVisibilityCondition(orgId, memberId) {
-	return and(eq(agents.organizationId, orgId), ne(agents.status, AGENT_STATUSES.DELETED), or(eq(agents.visibility, AGENT_VISIBILITY.ORGANIZATION), eq(agents.managerId, memberId)));
+async function deleteAgent(db, uuid) {
+	const [existing] = await db.select({
+		uuid: agents.uuid,
+		status: agents.status
+	}).from(agents).where(eq(agents.uuid, uuid)).limit(1);
+	if (!existing || existing.status === AGENT_STATUSES.DELETED) throw new NotFoundError(`Agent "${uuid}" not found`);
+	if (existing.status !== AGENT_STATUSES.SUSPENDED) throw new BadRequestError("Only suspended agents can be deleted. Suspend the agent first.");
+	const [agent] = await db.update(agents).set({
+		status: AGENT_STATUSES.DELETED,
+		name: null,
+		updatedAt: /* @__PURE__ */ new Date()
+	}).where(eq(agents.uuid, uuid)).returning();
+	await db.delete(adapterConfigs).where(eq(adapterConfigs.agentId, uuid));
+	await db.delete(adapterAgentMappings).where(eq(adapterAgentMappings.agentId, uuid));
+	if (!agent) throw new Error("Unexpected: UPDATE RETURNING produced no row");
+	return agent;
 }
 /**
-* Cross-org listing helper for "agents I personally manage". Used by the
-* CLI `agent list --remote` view — JOINs `agents → members.id` and filters
-* by `members.user_id`.
+* Supported avatar-image MIME types. The web client always uploads WEBP after
+* its own resize step; we accept PNG/JPEG too so a caller using the raw HTTP
+* API (curl, scripts) doesn't have to re-encode. Anything else is rejected at
+* the boundary — we never store an unknown content type.
 */
-async function listAgentsManagedByUser(db, userId) {
-	return db.select({
-		uuid: agents.uuid,
-		name: agents.name,
-		displayName: agents.displayName,
-		type: agents.type,
-		organizationId: agents.organizationId,
-		inboxId: agents.inboxId,
-		visibility: agents.visibility,
-		runtimeProvider: agents.runtimeProvider,
-		clientId: agents.clientId
-	}).from(agents).innerJoin(members, eq(agents.managerId, members.id)).where(and(eq(members.userId, userId), eq(members.status, "active"), ne(agents.status, AGENT_STATUSES.DELETED)));
+const SUPPORTED_AVATAR_IMAGE_MIMES = [
+	"image/webp",
+	"image/png",
+	"image/jpeg"
+];
+/** Hard server-side ceiling for the stored bytea blob. Client pre-resizes to ~50KB. */
+const MAX_AVATAR_IMAGE_BYTES = 512 * 1024;
+function isSupportedAvatarMime(mime) {
+	return SUPPORTED_AVATAR_IMAGE_MIMES.find((m) => m === mime) !== void 0;
 }
-/** Messages. Immutable after creation. Each message belongs to exactly one Chat. */
-const messages = pgTable("messages", {
-	id: text("id").primaryKey(),
-	chatId: text("chat_id").notNull().references(() => chats.id),
-	senderId: text("sender_id").notNull(),
-	format: text("format").notNull(),
-	content: jsonb("content").$type().notNull(),
-	metadata: jsonb("metadata").$type().notNull().default({}),
-	replyToInbox: text("reply_to_inbox"),
-	replyToChat: text("reply_to_chat"),
-	inReplyTo: text("in_reply_to"),
-	source: text("source"),
-	createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow()
-}, (table) => [index("idx_messages_chat_time").on(table.chatId, table.createdAt), index("idx_messages_in_reply_to").on(table.inReplyTo)]);
-/** Delivery queue (envelope). One entry per recipient created during message fan-out. Uses SKIP LOCKED for concurrent-safe consumption. */
-const inboxEntries = pgTable("inbox_entries", {
-	id: bigserial("id", { mode: "number" }).primaryKey(),
-	inboxId: text("inbox_id").notNull(),
-	messageId: text("message_id").notNull().references(() => messages.id),
-	chatId: text("chat_id"),
-	status: text("status").notNull().default("pending"),
-	notify: boolean("notify").notNull().default(true),
-	retryCount: integer("retry_count").notNull().default(0),
-	createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
-	deliveredAt: timestamp("delivered_at", { withTimezone: true }),
-	ackedAt: timestamp("acked_at", { withTimezone: true })
-}, (table) => [
-	unique("uq_inbox_delivery").on(table.inboxId, table.messageId, table.chatId),
-	index("idx_inbox_pending").on(table.inboxId, table.createdAt),
-	index("idx_inbox_pending_notify").on(table.inboxId, table.createdAt).where(sql`status = 'pending' AND notify = true`),
-	index("idx_inbox_chat_silent").on(table.inboxId, table.chatId, table.notify, table.status)
-]);
-/** Server instance heartbeat. Used to detect crashed instances and clean up associated agent_presence records. */
-const serverInstances = pgTable("server_instances", {
-	instanceId: text("instance_id").primaryKey(),
-	lastHeartbeat: timestamp("last_heartbeat", { withTimezone: true }).notNull().defaultNow()
-});
-/** Common field reset when agent goes offline or is unbound. */
-function runtimeFieldsReset(now) {
+/**
+* Fetch the avatar image blob for an agent. Returns `null` when no image
+* is set (the column is NULL). The data + mime pair is always coherent
+* (set/cleared together by the service writes below).
+*/
+async function getAgentAvatarImage(db, uuid) {
+	const [row] = await db.select({
+		data: agents.avatarImageData,
+		mime: agents.avatarImageMime,
+		updatedAt: agents.avatarImageUpdatedAt
+	}).from(agents).where(and(eq(agents.uuid, uuid), ne(agents.status, AGENT_STATUSES.DELETED))).limit(1);
+	if (!row || !row.data || !row.mime || !row.updatedAt) return null;
 	return {
-		runtimeState: null,
-		activeSessions: null,
-		totalSessions: null,
-		runtimeUpdatedAt: now,
-		lastSeenAt: now
+		data: row.data,
+		mime: row.mime,
+		updatedAt: row.updatedAt
 	};
 }
-async function setOffline(db, agentId) {
+/** Replace (or set) an agent's avatar image. Validates mime + size. */
+async function setAgentAvatarImage(db, uuid, data, mime) {
+	if (!isSupportedAvatarMime(mime)) throw new BadRequestError(`Unsupported avatar image type "${mime}". Use PNG, JPEG, or WEBP.`);
+	if (data.length === 0) throw new BadRequestError("Avatar image payload is empty.");
+	if (data.length > 524288) throw new BadRequestError(`Avatar image is too large (${data.length} bytes; max ${MAX_AVATAR_IMAGE_BYTES}).`);
 	const now = /* @__PURE__ */ new Date();
-	await db.update(agentPresence).set({
-		status: "offline",
-		instanceId: null,
-		...runtimeFieldsReset(now)
-	}).where(eq(agentPresence.agentId, agentId));
+	if ((await db.update(agents).set({
+		avatarImageData: data,
+		avatarImageMime: mime,
+		avatarImageUpdatedAt: now,
+		updatedAt: now
+	}).where(and(eq(agents.uuid, uuid), ne(agents.status, AGENT_STATUSES.DELETED))).returning({ uuid: agents.uuid })).length === 0) throw new NotFoundError(`Agent "${uuid}" not found`);
+	return now;
 }
-async function getPresence(db, agentId) {
-	const [row] = await db.select().from(agentPresence).where(eq(agentPresence.agentId, agentId)).limit(1);
-	return row ?? null;
+/** Clear an agent's avatar image (falls back to color + initial). */
+async function clearAgentAvatarImage(db, uuid) {
+	if ((await db.update(agents).set({
+		avatarImageData: null,
+		avatarImageMime: null,
+		avatarImageUpdatedAt: null,
+		updatedAt: /* @__PURE__ */ new Date()
+	}).where(and(eq(agents.uuid, uuid), ne(agents.status, AGENT_STATUSES.DELETED))).returning({ uuid: agents.uuid })).length === 0) throw new NotFoundError(`Agent "${uuid}" not found`);
 }
-async function getOnlineCount(db) {
-	const [result] = await db.select({ count: sql`count(*)::int` }).from(agentPresence).where(eq(agentPresence.status, "online"));
-	return result?.count ?? 0;
+/**
+* Server-side lifecycle tracker for `format=question` messages.
+*
+* Written when an agent emits a question through `sendMessage`; status
+* flips to `answered` when the user posts an answer, or to `superseded`
+* when the chat session is archived or its client is claimed away.
+*
+* Per the team's "integrity in service layer" convention, NO foreign-key
+* constraints — referential integrity is enforced by the question
+* service itself (chat-id / agent-id / message-id are validated at
+* write time and the lifecycle hooks supersede orphaned rows).
+*/
+const pendingQuestions = pgTable("pending_questions", {
+	id: text("id").primaryKey(),
+	agentId: text("agent_id").notNull(),
+	chatId: text("chat_id").notNull(),
+	messageId: text("message_id").notNull(),
+	status: text("status").notNull().default("pending"),
+	createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+	answeredAt: timestamp("answered_at", { withTimezone: true }),
+	supersededAt: timestamp("superseded_at", { withTimezone: true }),
+	supersededReason: text("superseded_reason")
+}, (table) => [index("idx_pending_questions_agent_status").on(table.agentId, table.status), index("idx_pending_questions_chat_status").on(table.chatId, table.status)]);
+/**
+* Upsert session state + refresh presence aggregates + NOTIFY.
+*
+* `agent_chat_sessions.(agent_id, chat_id)` is a single-row "current session
+* state" cache, not a session history log. A new runtime session starting on
+* the same (agent, chat) pair MUST overwrite whatever ended before — including
+* an `evicted` row left by a previous terminate. The previous "revival
+* defense" conflated two concerns: "this runtime session ended" (which is
+* what `evicted` actually means) and "this chat is permanently archived for
+* this agent" (a chat-level decision that should live on `chats`, not here).
+* See proposals/hub-agent-messaging-reply-and-mentions §M2-session-lifecycle.
+*
+* Presence row contract: this function tolerates a missing `agent_presence`
+* row by using `INSERT ... ON CONFLICT DO UPDATE`. The predictive-write path
+* (sendMessage on first message) may target an agent whose client has never
+* bound, so a prior `update agent_presence ... where agentId` would silently
+* drop the activeSessions/totalSessions refresh. See PR #198 review §2.
+*/
+async function upsertSessionState(db, agentId, chatId, state, organizationId, notifier, options) {
+	const now = /* @__PURE__ */ new Date();
+	let wrote = false;
+	await db.transaction(async (tx) => {
+		await tx.insert(agentChatSessions).values({
+			agentId,
+			chatId,
+			state,
+			updatedAt: now
+		}).onConflictDoUpdate({
+			target: [agentChatSessions.agentId, agentChatSessions.chatId],
+			set: {
+				state,
+				updatedAt: now
+			},
+			setWhere: ne(agentChatSessions.state, state)
+		});
+		const [counts] = await tx.select({
+			active: sql`count(*) FILTER (WHERE ${agentChatSessions.state} = 'active')::int`,
+			total: sql`count(*) FILTER (WHERE ${agentChatSessions.state} != 'evicted')::int`
+		}).from(agentChatSessions).where(eq(agentChatSessions.agentId, agentId));
+		const activeSessions = counts?.active ?? 0;
+		const totalSessions = counts?.total ?? 0;
+		const presenceSet = options?.touchPresenceLastSeen ?? true ? {
+			activeSessions,
+			totalSessions,
+			lastSeenAt: now
+		} : {
+			activeSessions,
+			totalSessions
+		};
+		await tx.insert(agentPresence).values({
+			agentId,
+			activeSessions,
+			totalSessions
+		}).onConflictDoUpdate({
+			target: [agentPresence.agentId],
+			set: presenceSet
+		});
+		wrote = true;
+	});
+	if (wrote && notifier) notifier.notifySessionStateChange(agentId, chatId, state, organizationId).catch(() => {});
 }
-async function bindAgent(db, agentId, data) {
+async function resetActivity(db, agentId) {
 	const now = /* @__PURE__ */ new Date();
-	await db.insert(agentPresence).values({
-		agentId,
-		status: "online",
-		instanceId: data.instanceId,
-		clientId: data.clientId,
-		runtimeType: data.runtimeType,
-		runtimeVersion: data.runtimeVersion ?? null,
-		runtimeState: "idle",
-		connectedAt: now,
-		lastSeenAt: now,
-		runtimeUpdatedAt: now
-	}).onConflictDoUpdate({
-		target: agentPresence.agentId,
-		set: {
-			status: "online",
-			instanceId: data.instanceId,
-			clientId: data.clientId,
-			runtimeType: data.runtimeType,
-			runtimeVersion: data.runtimeVersion ?? null,
-			runtimeState: "idle",
-			activeSessions: null,
-			totalSessions: null,
-			connectedAt: now,
-			lastSeenAt: now,
-			runtimeUpdatedAt: now
-		}
-	});
-}
-async function unbindAgent(db, agentId) {
-	const now = /* @__PURE__ */ new Date();
-	await db.update(agentPresence).set({
-		status: "offline",
-		clientId: null,
-		...runtimeFieldsReset(now)
-	}).where(eq(agentPresence.agentId, agentId));
-}
-/** Set runtime state directly from client-reported value.
-*
-* When an org-scoped notifier is provided, emit a PG NOTIFY on the
-* `runtime_state_changes` channel so the pulse aggregator (and any future
-* admin-side consumers) can observe the transition. Fire-and-forget to match
-* notifier semantics elsewhere in this module. */
-async function setRuntimeState(db, agentId, runtimeState, options) {
-	const now = /* @__PURE__ */ new Date();
-	await db.update(agentPresence).set({
-		runtimeState,
-		runtimeUpdatedAt: now,
-		lastSeenAt: now
-	}).where(eq(agentPresence.agentId, agentId));
-	if (options?.notifier && options.organizationId) options.notifier.notifyRuntimeStateChange(agentId, runtimeState, options.organizationId).catch(() => {});
-}
-/** Touch agent last_seen_at on heartbeat (per-agent liveness). */
-async function touchAgent(db, agentId) {
-	await db.update(agentPresence).set({ lastSeenAt: /* @__PURE__ */ new Date() }).where(eq(agentPresence.agentId, agentId));
-}
-async function heartbeatInstance(db, instanceId) {
-	await db.insert(serverInstances).values({
-		instanceId,
-		lastHeartbeat: /* @__PURE__ */ new Date()
-	}).onConflictDoUpdate({
-		target: serverInstances.instanceId,
-		set: { lastHeartbeat: /* @__PURE__ */ new Date() }
-	});
-}
-/**
-* M1: Mark agents as offline whose last_seen_at is older than staleSeconds.
-* Unlike cleanupStalePresence (which checks instance liveness), this checks
-* per-agent heartbeat liveness — detecting agents that stopped heartbeating
-* while the client process may still be alive.
-*
-* Returns the list of agent IDs that were marked stale (for notification in Step 6).
-*/
-async function markStaleAgents(db, staleSeconds = 60) {
-	return (await db.execute(sql`
-    UPDATE agent_presence SET
-      status = 'offline',
-      client_id = NULL,
-      runtime_state = NULL,
-      active_sessions = NULL,
-      total_sessions = NULL,
-      runtime_updated_at = NOW()
-    WHERE status = 'online'
-    AND last_seen_at < NOW() - make_interval(secs => ${staleSeconds})
-    RETURNING agent_id
-  `)).map((r) => r.agent_id);
-}
-async function cleanupStalePresence(db, staleSeconds = 60) {
-	return (await db.execute(sql`
-    UPDATE agent_presence SET status = 'offline', instance_id = NULL,
-      runtime_state = NULL,
-      active_sessions = NULL, total_sessions = NULL,
-      runtime_updated_at = NOW()
-    WHERE instance_id IN (
-      SELECT instance_id FROM server_instances
-      WHERE last_heartbeat < NOW() - make_interval(secs => ${staleSeconds})
-    )
-    AND status = 'online'
-    RETURNING agent_id
-  `)).length;
-}
-/** Per-session state snapshot. One row per (agent, chat) pair, upserted on each session:state message. */
-const agentChatSessions = pgTable("agent_chat_sessions", {
-	agentId: text("agent_id").notNull().references(() => agents.uuid, { onDelete: "cascade" }),
-	chatId: text("chat_id").notNull().references(() => chats.id, { onDelete: "cascade" }),
-	state: text("state").notNull(),
-	updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow()
-}, (table) => [primaryKey({ columns: [table.agentId, table.chatId] })]);
-/**
-* Upsert session state + refresh presence aggregates + NOTIFY.
-*
-* `agent_chat_sessions.(agent_id, chat_id)` is a single-row "current session
-* state" cache, not a session history log. A new runtime session starting on
-* the same (agent, chat) pair MUST overwrite whatever ended before — including
-* an `evicted` row left by a previous terminate. The previous "revival
-* defense" conflated two concerns: "this runtime session ended" (which is
-* what `evicted` actually means) and "this chat is permanently archived for
-* this agent" (a chat-level decision that should live on `chats`, not here).
-* See proposals/hub-agent-messaging-reply-and-mentions §M2-session-lifecycle.
-*
-* Presence row contract: this function tolerates a missing `agent_presence`
-* row by using `INSERT ... ON CONFLICT DO UPDATE`. The predictive-write path
-* (sendMessage on first message) may target an agent whose client has never
-* bound, so a prior `update agent_presence ... where agentId` would silently
-* drop the activeSessions/totalSessions refresh. See PR #198 review §2.
-*/
-async function upsertSessionState(db, agentId, chatId, state, organizationId, notifier, options) {
-	const now = /* @__PURE__ */ new Date();
-	let wrote = false;
-	await db.transaction(async (tx) => {
-		await tx.insert(agentChatSessions).values({
-			agentId,
-			chatId,
-			state,
-			updatedAt: now
-		}).onConflictDoUpdate({
-			target: [agentChatSessions.agentId, agentChatSessions.chatId],
-			set: {
-				state,
-				updatedAt: now
-			},
-			setWhere: ne(agentChatSessions.state, state)
-		});
-		const [counts] = await tx.select({
-			active: sql`count(*) FILTER (WHERE ${agentChatSessions.state} = 'active')::int`,
-			total: sql`count(*) FILTER (WHERE ${agentChatSessions.state} != 'evicted')::int`
-		}).from(agentChatSessions).where(eq(agentChatSessions.agentId, agentId));
-		const activeSessions = counts?.active ?? 0;
-		const totalSessions = counts?.total ?? 0;
-		const presenceSet = options?.touchPresenceLastSeen ?? true ? {
-			activeSessions,
-			totalSessions,
-			lastSeenAt: now
-		} : {
-			activeSessions,
-			totalSessions
-		};
-		await tx.insert(agentPresence).values({
-			agentId,
-			activeSessions,
-			totalSessions
-		}).onConflictDoUpdate({
-			target: [agentPresence.agentId],
-			set: presenceSet
-		});
-		wrote = true;
-	});
-	if (wrote && notifier) notifier.notifySessionStateChange(agentId, chatId, state, organizationId).catch(() => {});
-}
-async function resetActivity(db, agentId) {
-	const now = /* @__PURE__ */ new Date();
-	await db.update(agentPresence).set({
+	await db.update(agentPresence).set({
 		runtimeState: "idle",
 		runtimeUpdatedAt: now
 	}).where(eq(agentPresence.agentId, agentId));
@@ -1225,7 +1854,7 @@ async function listAgentsWithRuntime(db, scope) {
 *   - Mention candidate set is `chat_membership` speakers only;
 *     watchers are not direct `@`-mention targets.
 */
-const { ACTIVE, ARCHIVED } = CHAT_ENGAGEMENT_STATUSES;
+const { ACTIVE: ACTIVE$1, ARCHIVED: ARCHIVED$1 } = CHAT_ENGAGEMENT_STATUSES;
 let dispatcher = null;
 function registerChatMessageDispatcher(fn) {
 	dispatcher = fn;
@@ -1260,9 +1889,9 @@ async function applyAfterFanOut(tx, input) {
 	}).where(eq(chats.id, chatId));
 	await tx.execute(sql`
     UPDATE chat_user_state
-       SET engagement_status = ${ACTIVE}
+       SET engagement_status = ${ACTIVE$1}
      WHERE chat_id = ${chatId}
-       AND engagement_status = ${ARCHIVED}
+       AND engagement_status = ${ARCHIVED$1}
   `);
 	if (mentionedAgentIds.length === 0) return;
 	const mentionedList = sql.join(mentionedAgentIds.map((id) => sql`${id}`), sql`, `);
@@ -1291,791 +1920,1991 @@ async function applyAfterFanOut(tx, input) {
     DO UPDATE SET unread_mention_count = chat_user_state.unread_mention_count + 1
   `);
 }
-/**
-* Server-side lifecycle tracker for `format=question` messages.
-*
-* Written when an agent emits a question through `sendMessage`; status
-* flips to `answered` when the user posts an answer, or to `superseded`
-* when the chat session is archived or its client is claimed away.
-*
-* Per the team's "integrity in service layer" convention, NO foreign-key
-* constraints — referential integrity is enforced by the question
-* service itself (chat-id / agent-id / message-id are validated at
-* write time and the lifecycle hooks supersede orphaned rows).
-*/
-const pendingQuestions = pgTable("pending_questions", {
-	id: text("id").primaryKey(),
-	agentId: text("agent_id").notNull(),
-	chatId: text("chat_id").notNull(),
-	messageId: text("message_id").notNull(),
-	status: text("status").notNull().default("pending"),
-	createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
-	answeredAt: timestamp("answered_at", { withTimezone: true }),
-	supersededAt: timestamp("superseded_at", { withTimezone: true }),
-	supersededReason: text("superseded_reason")
-}, (table) => [index("idx_pending_questions_agent_status").on(table.agentId, table.status), index("idx_pending_questions_chat_status").on(table.chatId, table.status)]);
-const INBOX_CHANNEL = "inbox_notifications";
-const CONFIG_CHANNEL = "config_changes";
-const SESSION_STATE_CHANNEL = "session_state_changes";
-const SESSION_EVENT_CHANNEL = "session_event_changes";
-const RUNTIME_STATE_CHANNEL = "runtime_state_changes";
-/**
-* Chat-first workspace cross-process kick. Carries `<chatId>:<messageId>`.
-* Lets admin WS sockets translate every chat message (speaker AND watcher
-* audience) into a `chat:message` frame, without being coupled to the
-* inbox NOTIFY path that only reaches speakers.
-*/
-const CHAT_MESSAGE_CHANNEL = "chat_message_events";
-/**
-* Generic admin-broadcast envelope channel. Producers (e.g. notification.ts)
-* emit a JSON-stringified `AdminBroadcastPayload`; every server instance
-* LISTENs and hands the envelope to its local admin-socket fanout. Keeps
-* cross-instance and single-instance code paths identical from the admin WS
-* route's perspective.
-*/
-const ADMIN_BROADCAST_CHANNEL = "admin_broadcast_envelopes";
-function createNotifier(listenClient) {
-	const subscriptions = /* @__PURE__ */ new Map();
-	const configChangeHandlers = [];
-	const sessionStateChangeHandlers = [];
-	const sessionEventHandlers = [];
-	const runtimeStateChangeHandlers = [];
-	const chatMessageHandlers = [];
-	const adminBroadcastHandlers = [];
-	let unlistenInboxFn = null;
-	let unlistenConfigFn = null;
-	let unlistenSessionStateFn = null;
-	let unlistenSessionEventFn = null;
-	let unlistenRuntimeStateFn = null;
-	let unlistenChatMessageFn = null;
-	let unlistenAdminBroadcastFn = null;
-	function handleNotification(payload) {
-		const sepIdx = payload.indexOf(":");
-		if (sepIdx === -1) return;
-		const inboxId = payload.slice(0, sepIdx);
-		const messageId = payload.slice(sepIdx + 1);
-		const sockets = subscriptions.get(inboxId);
-		if (!sockets) return;
-		const doorbellFrame = JSON.stringify({
-			type: "new_message",
-			inboxId,
-			messageId
-		});
-		for (const [ws, pushHandler] of sockets) {
-			if (ws.readyState !== ws.OPEN) continue;
-			if (pushHandler) Promise.resolve(pushHandler(messageId)).catch(() => {});
-			else ws.send(doorbellFrame);
-		}
-	}
-	return {
-		subscribe(inboxId, ws, pushHandler) {
-			let map = subscriptions.get(inboxId);
-			if (!map) {
-				map = /* @__PURE__ */ new Map();
-				subscriptions.set(inboxId, map);
-			}
-			map.set(ws, pushHandler ?? null);
-		},
-		unsubscribe(inboxId, ws) {
-			const map = subscriptions.get(inboxId);
-			if (map) {
-				map.delete(ws);
-				if (map.size === 0) subscriptions.delete(inboxId);
-			}
-		},
-		async notify(inboxId, messageId) {
-			try {
-				await listenClient`SELECT pg_notify(${INBOX_CHANNEL}, ${`${inboxId}:${messageId}`})`;
-			} catch {}
-		},
-		async notifyConfigChange(configType) {
-			try {
-				await listenClient`SELECT pg_notify(${CONFIG_CHANNEL}, ${configType})`;
-			} catch {}
-		},
-		async notifySessionStateChange(agentId, chatId, state, organizationId) {
-			try {
-				await listenClient`SELECT pg_notify(${SESSION_STATE_CHANNEL}, ${`${agentId}:${chatId}:${state}:${organizationId}`})`;
-			} catch {}
-		},
-		async notifySessionEvent(agentId, chatId, kind, organizationId) {
-			try {
-				await listenClient`SELECT pg_notify(${SESSION_EVENT_CHANNEL}, ${`${agentId}:${chatId}:${kind}:${organizationId}`})`;
-			} catch {}
-		},
-		async notifyRuntimeStateChange(agentId, state, organizationId) {
-			try {
-				await listenClient`SELECT pg_notify(${RUNTIME_STATE_CHANNEL}, ${`${agentId}:${state}:${organizationId}`})`;
-			} catch {}
-		},
-		async notifyChatMessage(chatId, messageId) {
-			try {
-				await listenClient`SELECT pg_notify(${CHAT_MESSAGE_CHANNEL}, ${`${chatId}:${messageId}`})`;
-			} catch {}
-		},
-		async notifyAdminBroadcast(payload) {
-			let encoded;
-			try {
-				encoded = JSON.stringify(payload);
-			} catch {
-				return;
-			}
-			if (encoded.length > 7500) {
-				console.error(`[notifier] admin broadcast payload too large (${encoded.length} bytes); refusing to NOTIFY`);
-				return;
-			}
-			try {
-				await listenClient`SELECT pg_notify(${ADMIN_BROADCAST_CHANNEL}, ${encoded})`;
-			} catch {}
-		},
-		async pushFrameToInbox(inboxId, frame) {
-			const map = subscriptions.get(inboxId);
-			if (!map) return 0;
-			let queued = 0;
-			const pending = [];
-			for (const ws of map.keys()) {
-				if (ws.readyState !== ws.OPEN) continue;
-				pending.push(new Promise((resolve) => {
-					ws.send(frame, (err) => {
-						if (!err) queued += 1;
-						resolve();
-					});
-				}));
+const log$1 = createLogger("message");
+async function sendMessage(db, chatId, senderId, data, options = {}) {
+	return withSpan("inbox.enqueue", messageAttrs({
+		chatId,
+		senderAgentId: senderId,
+		source: data.source ?? void 0
+	}), () => sendMessageInner(db, chatId, senderId, data, options));
+}
+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: chatMembership.agentId,
+				inboxId: agents.inboxId,
+				mode: chatMembership.mode,
+				name: agents.name
+			}).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,
+				organizationId: agents.organizationId,
+				type: agents.type
+			}).from(agents).where(eq(agents.uuid, senderId)).limit(1)
+		]);
+		const chatType = chatRow?.type ?? null;
+		if (!senderRow) throw new NotFoundError(`Sender agent "${senderId}" not found`);
+		let effectiveContent = data.content;
+		if (senderRow.type !== "human" && typeof effectiveContent === "string") {
+			const unwrapped = maybeUnwrapDoubleEncoded(effectiveContent);
+			if (unwrapped !== null) {
+				log$1.warn({
+					metric: "double_encoded_content_unwrapped_total",
+					chatId,
+					senderId
+				}, "agent sent JSON-encoded string content — unwrapping to restore markdown rendering");
+				effectiveContent = unwrapped;
 			}
-			await Promise.all(pending);
-			return queued;
-		},
-		onConfigChange(handler) {
-			configChangeHandlers.push(handler);
-		},
-		onSessionStateChange(handler) {
-			sessionStateChangeHandlers.push(handler);
-		},
-		onSessionEvent(handler) {
-			sessionEventHandlers.push(handler);
-		},
-		onRuntimeStateChange(handler) {
-			runtimeStateChangeHandlers.push(handler);
-		},
-		onChatMessage(handler) {
-			chatMessageHandlers.push(handler);
-		},
-		onAdminBroadcast(handler) {
-			adminBroadcastHandlers.push(handler);
-		},
-		async start() {
-			unlistenInboxFn = (await listenClient.listen(INBOX_CHANNEL, (payload) => {
-				if (payload) handleNotification(payload);
-			})).unlisten;
-			unlistenConfigFn = (await listenClient.listen(CONFIG_CHANNEL, (payload) => {
-				if (payload) for (const handler of configChangeHandlers) handler(payload);
-			})).unlisten;
-			unlistenSessionStateFn = (await listenClient.listen(SESSION_STATE_CHANNEL, (payload) => {
-				if (payload) {
-					const firstSep = payload.indexOf(":");
-					const secondSep = payload.indexOf(":", firstSep + 1);
-					const thirdSep = payload.indexOf(":", secondSep + 1);
-					if (firstSep > 0 && secondSep > firstSep && thirdSep > secondSep) {
-						const agentId = payload.slice(0, firstSep);
-						const chatId = payload.slice(firstSep + 1, secondSep);
-						const state = payload.slice(secondSep + 1, thirdSep);
-						const organizationId = payload.slice(thirdSep + 1);
-						for (const handler of sessionStateChangeHandlers) handler({
-							agentId,
-							chatId,
-							state,
-							organizationId
-						});
-					}
-				}
-			})).unlisten;
-			unlistenSessionEventFn = (await listenClient.listen(SESSION_EVENT_CHANNEL, (payload) => {
-				if (payload) {
-					const firstSep = payload.indexOf(":");
-					const secondSep = payload.indexOf(":", firstSep + 1);
-					const thirdSep = payload.indexOf(":", secondSep + 1);
-					if (firstSep > 0 && secondSep > firstSep && thirdSep > secondSep) {
-						const agentId = payload.slice(0, firstSep);
-						const chatId = payload.slice(firstSep + 1, secondSep);
-						const kind = payload.slice(secondSep + 1, thirdSep);
-						const organizationId = payload.slice(thirdSep + 1);
-						for (const handler of sessionEventHandlers) try {
-							handler({
-								agentId,
-								chatId,
-								kind,
-								organizationId
-							});
-						} catch {}
-					}
-				}
-			})).unlisten;
-			unlistenRuntimeStateFn = (await listenClient.listen(RUNTIME_STATE_CHANNEL, (payload) => {
-				if (payload) {
-					const firstSep = payload.indexOf(":");
-					const secondSep = payload.indexOf(":", firstSep + 1);
-					if (firstSep > 0 && secondSep > firstSep) {
-						const agentId = payload.slice(0, firstSep);
-						const state = payload.slice(firstSep + 1, secondSep);
-						const organizationId = payload.slice(secondSep + 1);
-						for (const handler of runtimeStateChangeHandlers) handler({
-							agentId,
-							state,
-							organizationId
-						});
-					}
-				}
-			})).unlisten;
-			unlistenChatMessageFn = (await listenClient.listen(CHAT_MESSAGE_CHANNEL, (payload) => {
-				if (!payload) return;
-				const sep = payload.indexOf(":");
-				if (sep <= 0) return;
-				const chatId = payload.slice(0, sep);
-				const messageId = payload.slice(sep + 1);
-				for (const handler of chatMessageHandlers) try {
-					handler({
-						chatId,
-						messageId
-					});
-				} catch {}
-			})).unlisten;
-			unlistenAdminBroadcastFn = (await listenClient.listen(ADMIN_BROADCAST_CHANNEL, (payload) => {
-				if (!payload) return;
-				let parsed;
-				try {
-					parsed = JSON.parse(payload);
-				} catch {
-					return;
+		}
+		if (data.replyToInbox !== void 0 && data.replyToInbox !== null) {
+			if (senderRow.inboxId !== data.replyToInbox) throw new BadRequestError("replyToInbox must reference the sender's own inbox");
+		}
+		const incomingMeta = data.metadata ?? {};
+		const explicitMentionsRaw = incomingMeta.mentions;
+		const explicitMentions = Array.isArray(explicitMentionsRaw) ? explicitMentionsRaw.filter((m) => typeof m === "string") : [];
+		const contentText = typeof effectiveContent === "string" ? effectiveContent : "";
+		const resolved = contentText ? extractMentions(contentText, participants) : [];
+		const mergedMentions = [...new Set([...explicitMentions, ...resolved])];
+		const metadataToStore = mergedMentions.length > 0 ? {
+			...incomingMeta,
+			mentions: mergedMentions
+		} : incomingMeta;
+		const dmAutoProjection = chatType === "direct" ? [...new Set([...mergedMentions, ...participants.filter((p) => p.agentId !== senderId).map((p) => p.agentId)])] : mergedMentions;
+		const isAgentFinalText = data.purpose === "agent-final-text";
+		if (options.enforceGroupMention && chatType === "group" && !isAgentFinalText) {
+			if (mergedMentions.filter((id) => id !== senderId).length === 0) throw new BadRequestError("Sending to a group chat requires an explicit @mention. Use `first-tree-hub chat send <name>` to message a single agent, or @<name> in the content to address one or more group members.");
+		}
+		if (options.enforceGroupMention && !isAgentFinalText && typeof effectiveContent === "string") {
+			const rawTokens = scanMentionTokens(effectiveContent);
+			if (rawTokens.length > 0) {
+				const speakerNames = new Set(participants.map((p) => p.name).filter((n) => typeof n === "string" && n.length > 0).map((n) => n.toLowerCase()));
+				const unresolved = rawTokens.filter((t) => !speakerNames.has(t));
+				if (unresolved.length > 0) {
+					const sample = unresolved[0];
+					throw new BadRequestError(`Cannot @-mention "${sample}" — they are not a participant of this chat. Use \`first-tree-hub chat send --direct ${sample} "..."\` to message them in a side conversation, or ask a human in this chat to add them as a participant first.`);
 				}
-				if (typeof parsed !== "object" || parsed === null) return;
-				const envelope = parsed;
-				for (const handler of adminBroadcastHandlers) try {
-					handler(envelope);
-				} catch {}
-			})).unlisten;
-		},
-		async stop() {
-			if (unlistenInboxFn) {
-				await unlistenInboxFn();
-				unlistenInboxFn = null;
-			}
-			if (unlistenConfigFn) {
-				await unlistenConfigFn();
-				unlistenConfigFn = null;
-			}
-			if (unlistenSessionStateFn) {
-				await unlistenSessionStateFn();
-				unlistenSessionStateFn = null;
-			}
-			if (unlistenSessionEventFn) {
-				await unlistenSessionEventFn();
-				unlistenSessionEventFn = null;
-			}
-			if (unlistenRuntimeStateFn) {
-				await unlistenRuntimeStateFn();
-				unlistenRuntimeStateFn = null;
 			}
-			if (unlistenChatMessageFn) {
-				await unlistenChatMessageFn();
-				unlistenChatMessageFn = null;
+		}
+		let outboundContent = effectiveContent;
+		if (options.normalizeMentionsInContent && typeof outboundContent === "string") {
+			const present = new Set(scanMentionTokens(outboundContent));
+			const missingNames = [];
+			for (const id of mergedMentions) {
+				if (id === senderId) continue;
+				const p = participants.find((q) => q.agentId === id);
+				if (!p?.name) continue;
+				if (present.has(p.name.toLowerCase())) continue;
+				missingNames.push(p.name);
 			}
-			if (unlistenAdminBroadcastFn) {
-				await unlistenAdminBroadcastFn();
-				unlistenAdminBroadcastFn = null;
+			if (missingNames.length > 0) {
+				const prefix = missingNames.map((n) => `@${n}`).join(" ");
+				outboundContent = outboundContent.length > 0 ? `${prefix} ${outboundContent}` : prefix;
 			}
 		}
-	};
+		if (data.format === "question") await assertSenderMayEmitQuestion(tx, senderId);
+		const isSilentSend = typeof outboundContent === "string" && outboundContent.replace(/^(@\S+\s*)+/, "").trim().length === 0;
+		if (isSilentSend) log$1.info({
+			chatId,
+			senderId,
+			source: data.source ?? null
+		}, "silent send: empty content after mention strip — no fan-out wake-up");
+		const projectionMentions = isSilentSend ? [] : dmAutoProjection;
+		const messageId = randomUUID();
+		const [msg] = await tx.insert(messages).values({
+			id: messageId,
+			chatId,
+			senderId,
+			format: data.format,
+			content: outboundContent,
+			metadata: metadataToStore,
+			replyToInbox: data.replyToInbox ?? null,
+			replyToChat: data.replyToChat ?? null,
+			inReplyTo: data.inReplyTo ?? null,
+			source: data.source ?? null
+		}).returning();
+		if (data.format === "question" && msg) await recordPendingQuestionFromMessage(tx, {
+			agentId: senderId,
+			chatId,
+			messageId: msg.id,
+			content: outboundContent
+		});
+		const mentionSet = new Set(mergedMentions);
+		const fanout = participants.filter((p) => p.agentId !== senderId).map((p) => ({
+			agentId: p.agentId,
+			inboxId: p.inboxId,
+			notify: !isSilentSend && !isAgentFinalText && (p.mode !== "mention_only" || mentionSet.has(p.agentId))
+		}));
+		if (fanout.length > 0) await tx.insert(inboxEntries).values(fanout.map((f) => ({
+			inboxId: f.inboxId,
+			messageId,
+			chatId,
+			notify: f.notify
+		})));
+		const notified = fanout.filter((f) => f.notify);
+		const recipients = notified.map((f) => f.inboxId);
+		const recipientAgentIds = notified.map((f) => f.agentId);
+		if (data.inReplyTo) {
+			const [original] = await tx.select({
+				replyToInbox: messages.replyToInbox,
+				replyToChat: messages.replyToChat
+			}).from(messages).where(eq(messages.id, data.inReplyTo)).limit(1);
+			if (original?.replyToInbox && original?.replyToChat) {
+				const replyNotify = !isSilentSend;
+				await tx.insert(inboxEntries).values({
+					inboxId: original.replyToInbox,
+					messageId,
+					chatId: original.replyToChat,
+					notify: replyNotify
+				}).onConflictDoNothing();
+				if (replyNotify && !recipients.includes(original.replyToInbox)) recipients.push(original.replyToInbox);
+			}
+		}
+		await tx.update(chats).set({ updatedAt: /* @__PURE__ */ new Date() }).where(eq(chats.id, chatId));
+		if (!msg) throw new Error("Unexpected: INSERT RETURNING produced no row");
+		const previewText = typeof outboundContent === "string" ? outboundContent.trim() : "";
+		await applyAfterFanOut(tx, {
+			chatId,
+			messageId: msg.id,
+			senderId,
+			mentionedAgentIds: projectionMentions,
+			contentPreview: previewText,
+			messageCreatedAt: msg.createdAt
+		});
+		return {
+			message: msg,
+			recipients,
+			recipientAgentIds,
+			organizationId: senderRow.organizationId
+		};
+	});
+	const settled = await Promise.allSettled(txResult.recipientAgentIds.map((agentId) => upsertSessionState(db, agentId, chatId, "active", txResult.organizationId, void 0, { touchPresenceLastSeen: false })));
+	for (let i = 0; i < settled.length; i++) {
+		const r = settled[i];
+		if (r?.status === "rejected") log$1.error({
+			err: r.reason,
+			chatId,
+			agentId: txResult.recipientAgentIds[i]
+		}, "predictive session activation failed");
+	}
+	fireChatMessageKick(chatId, txResult.message.id);
+	observeLoopPattern(db, chatId).catch((err) => {
+		log$1.error({
+			err,
+			chatId
+		}, "loop pattern observation failed");
+	});
+	return {
+		message: txResult.message,
+		recipients: txResult.recipients
+	};
+}
+/**
+* Detect agent-sent content that was JSON.stringify-ed once before reaching
+* the CLI / API. The bad shape is an outer `"..."` wrapper + interior `\n` /
+* `\"` escape sequences, which the UI renders as a quoted literal instead of
+* markdown (issue #389). Returns the unwrapped inner string on a confident
+* match, or `null` to leave the content alone.
+*
+* Match conditions (all required) — kept strict so legitimate human content
+* that happens to look like a quoted phrase is never touched. The caller is
+* additionally responsible for restricting this to non-human senders.
+*
+*   - first and last char are `"`
+*   - body contains at least one typical JSON escape sequence
+*     (`\n`, `\r`, `\t`, `\"`, or `\\`)
+*   - `JSON.parse` succeeds
+*   - the parse result is a `string` (excludes `{...}`, `[...]`, numbers)
+*/
+function maybeUnwrapDoubleEncoded(content) {
+	if (content.length < 4) return null;
+	if (content.charCodeAt(0) !== 34) return null;
+	if (content.charCodeAt(content.length - 1) !== 34) return null;
+	if (!/\\[nrt"\\]/.test(content)) return null;
+	try {
+		const parsed = JSON.parse(content);
+		return typeof parsed === "string" ? parsed : null;
+	} catch {
+		return null;
+	}
+}
+function stripMentionPrefix(content) {
+	return content.replace(/^(@\S+\s*)+/, "").trim();
+}
+const defaultLoopObserver = (data) => {
+	log$1.warn({
+		metric: "loop_pattern_observed_total",
+		...data
+	}, "loop pattern observed (not blocked) — prompt discipline may be drifting");
+};
+/**
+* Pure observation: detect short, fast, two-agent ping-pong reply chains and
+* surface them via a structured log line. Does NOT modify the `notify` flag
+* or otherwise interfere with delivery — loop *prevention* lives client-side
+* (prompt + silent-turn protocol in `result-sink`). Six conjunctive
+* conditions (see design `agent-reply-loop-prevention-design.md` §3.4) so
+* normal multi-agent collaboration is never flagged:
+*
+*   C1 — every message is `format=text`
+*   C2 — no human sender in the window (any human reply resets the chain)
+*   C3 — exactly two senders, perfectly alternating
+*   C4 — strict `inReplyTo` chain across the whole window
+*   C5 — every message body (after stripping leading `@<name>` tokens) is
+*        ≤ `LOOP_OBSERVATION_SHORT_CHARS` characters
+*   C6 — the whole window spans ≤ `LOOP_OBSERVATION_TIME_WINDOW_MS` ms
+*
+* Exported for direct test coverage of the detection logic; the `sendMessage`
+* call site uses the default observer.
+*/
+async function observeLoopPattern(db, chatId, observer = defaultLoopObserver) {
+	const window = await db.select({
+		id: messages.id,
+		senderId: messages.senderId,
+		content: messages.content,
+		inReplyTo: messages.inReplyTo,
+		createdAt: messages.createdAt,
+		format: messages.format,
+		senderType: agents.type
+	}).from(messages).innerJoin(agents, eq(messages.senderId, agents.uuid)).where(eq(messages.chatId, chatId)).orderBy(desc(messages.createdAt)).limit(4);
+	if (window.length < 4) return;
+	if (window.some((m) => m.format !== "text")) return;
+	if (window.some((m) => m.senderType === "human")) return;
+	if (new Set(window.map((m) => m.senderId)).size !== 2) return;
+	for (let i = 0; i < window.length - 1; i++) if (window[i]?.senderId === window[i + 1]?.senderId) return;
+	for (let i = 0; i < window.length - 1; i++) if (window[i]?.inReplyTo !== window[i + 1]?.id) return;
+	const lens = [];
+	for (const m of window) {
+		const text = typeof m.content === "string" ? m.content : null;
+		if (text === null) return;
+		const len = stripMentionPrefix(text).length;
+		if (len > 10) return;
+		lens.push(len);
+	}
+	const newest = window[0];
+	const oldest = window[window.length - 1];
+	if (!newest || !oldest) return;
+	const spanMs = newest.createdAt.getTime() - oldest.createdAt.getTime();
+	if (spanMs > 3e4) return;
+	observer({
+		chatId,
+		recentMessageIds: window.map((m) => m.id),
+		windowSpanMs: spanMs,
+		contentLengths: lens
+	});
+}
+async function sendToAgent(db, senderUuid, targetName, data) {
+	const [sender] = await db.select({
+		uuid: agents.uuid,
+		organizationId: agents.organizationId
+	}).from(agents).where(eq(agents.uuid, senderUuid)).limit(1);
+	if (!sender) throw new NotFoundError(`Agent "${senderUuid}" not found`);
+	const [target] = await db.select({ uuid: agents.uuid }).from(agents).where(and(eq(agents.organizationId, sender.organizationId), eq(agents.name, targetName), ne(agents.status, "deleted"))).limit(1);
+	if (!target) throw new NotFoundError(`Agent "${targetName}" not found${/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(targetName) ? " — `first-tree-hub chat send` expects an agent NAME, not a uuid. Run `first-tree-hub agent list` to see available names." : ""}`);
+	const incomingMeta = data.metadata ?? {};
+	const existingMentionsRaw = incomingMeta.mentions;
+	const existingMentions = Array.isArray(existingMentionsRaw) ? existingMentionsRaw.filter((m) => typeof m === "string") : [];
+	const mergedMentions = existingMentions.includes(target.uuid) ? existingMentions : [...existingMentions, target.uuid];
+	const metadata = {
+		...incomingMeta,
+		mentions: mergedMentions
+	};
+	if (data.replyToChat) {
+		const [targetIsMember, senderIsMember] = await Promise.all([isParticipant(db, data.replyToChat, target.uuid), isParticipant(db, data.replyToChat, senderUuid)]);
+		if (targetIsMember && senderIsMember) return sendMessage(db, data.replyToChat, senderUuid, {
+			format: data.format,
+			content: data.content,
+			metadata,
+			replyToInbox: void 0,
+			replyToChat: void 0,
+			source: data.source
+		}, { normalizeMentionsInContent: true });
+	}
+	if (!data.direct) throw new AgentSendNonMemberError(`Agent "${targetName}" is not a member of your current chat. Either open or reuse a side-conversation explicitly with \`first-tree-hub chat send --direct ${targetName} "..."\`, or ask a human in this chat to add ${targetName} as a participant.`);
+	return sendMessage(db, (await findOrCreateDirectChat(db, senderUuid, target.uuid)).id, senderUuid, {
+		format: data.format,
+		content: data.content,
+		metadata,
+		replyToInbox: data.replyToInbox,
+		replyToChat: data.replyToChat,
+		source: data.source
+	}, { normalizeMentionsInContent: true });
+}
+async function editMessage(db, chatId, messageId, senderId, data) {
+	const [msg] = await db.select().from(messages).where(eq(messages.id, messageId)).limit(1);
+	if (!msg) throw new NotFoundError(`Message "${messageId}" not found`);
+	if (msg.chatId !== chatId) throw new NotFoundError(`Message "${messageId}" not found in this chat`);
+	if (msg.senderId !== senderId) throw new ForbiddenError("Only the sender can edit a message");
+	const setClause = {};
+	if (data.format !== void 0) setClause.format = data.format;
+	if (data.content !== void 0) setClause.content = data.content;
+	const meta = msg.metadata ?? {};
+	meta.editedAt = (/* @__PURE__ */ new Date()).toISOString();
+	setClause.metadata = meta;
+	const [updated] = await db.update(messages).set(setClause).where(eq(messages.id, messageId)).returning();
+	if (!updated) throw new Error("Unexpected: UPDATE RETURNING produced no row");
+	return updated;
+}
+async function listMessages(db, chatId, limit, cursor) {
+	const where = cursor ? and(eq(messages.chatId, chatId), lt(messages.createdAt, new Date(cursor))) : eq(messages.chatId, chatId);
+	const rows = await db.select().from(messages).where(where).orderBy(desc(messages.createdAt)).limit(limit + 1);
+	const hasMore = rows.length > limit;
+	const items = hasMore ? rows.slice(0, limit) : rows;
+	const last = items[items.length - 1];
+	return {
+		items,
+		nextCursor: hasMore && last ? last.createdAt.toISOString() : null
+	};
+}
+const INBOX_CHANNEL = "inbox_notifications";
+const CONFIG_CHANNEL = "config_changes";
+const SESSION_STATE_CHANNEL = "session_state_changes";
+const SESSION_EVENT_CHANNEL = "session_event_changes";
+const RUNTIME_STATE_CHANNEL = "runtime_state_changes";
+/**
+* Chat-first workspace cross-process kick. Carries `<chatId>:<messageId>`.
+* Lets admin WS sockets translate every chat message (speaker AND watcher
+* audience) into a `chat:message` frame, without being coupled to the
+* inbox NOTIFY path that only reaches speakers.
+*/
+const CHAT_MESSAGE_CHANNEL = "chat_message_events";
+/**
+* Generic admin-broadcast envelope channel. Producers (e.g. notification.ts)
+* emit a JSON-stringified `AdminBroadcastPayload`; every server instance
+* LISTENs and hands the envelope to its local admin-socket fanout. Keeps
+* cross-instance and single-instance code paths identical from the admin WS
+* route's perspective.
+*/
+const ADMIN_BROADCAST_CHANNEL = "admin_broadcast_envelopes";
+function createNotifier(listenClient) {
+	const subscriptions = /* @__PURE__ */ new Map();
+	const configChangeHandlers = [];
+	const sessionStateChangeHandlers = [];
+	const sessionEventHandlers = [];
+	const runtimeStateChangeHandlers = [];
+	const chatMessageHandlers = [];
+	const adminBroadcastHandlers = [];
+	let unlistenInboxFn = null;
+	let unlistenConfigFn = null;
+	let unlistenSessionStateFn = null;
+	let unlistenSessionEventFn = null;
+	let unlistenRuntimeStateFn = null;
+	let unlistenChatMessageFn = null;
+	let unlistenAdminBroadcastFn = null;
+	function handleNotification(payload) {
+		const sepIdx = payload.indexOf(":");
+		if (sepIdx === -1) return;
+		const inboxId = payload.slice(0, sepIdx);
+		const messageId = payload.slice(sepIdx + 1);
+		const sockets = subscriptions.get(inboxId);
+		if (!sockets) return;
+		const doorbellFrame = JSON.stringify({
+			type: "new_message",
+			inboxId,
+			messageId
+		});
+		for (const [ws, pushHandler] of sockets) {
+			if (ws.readyState !== ws.OPEN) continue;
+			if (pushHandler) Promise.resolve(pushHandler(messageId)).catch(() => {});
+			else ws.send(doorbellFrame);
+		}
+	}
+	return {
+		subscribe(inboxId, ws, pushHandler) {
+			let map = subscriptions.get(inboxId);
+			if (!map) {
+				map = /* @__PURE__ */ new Map();
+				subscriptions.set(inboxId, map);
+			}
+			map.set(ws, pushHandler ?? null);
+		},
+		unsubscribe(inboxId, ws) {
+			const map = subscriptions.get(inboxId);
+			if (map) {
+				map.delete(ws);
+				if (map.size === 0) subscriptions.delete(inboxId);
+			}
+		},
+		async notify(inboxId, messageId) {
+			try {
+				await listenClient`SELECT pg_notify(${INBOX_CHANNEL}, ${`${inboxId}:${messageId}`})`;
+			} catch {}
+		},
+		async notifyConfigChange(configType) {
+			try {
+				await listenClient`SELECT pg_notify(${CONFIG_CHANNEL}, ${configType})`;
+			} catch {}
+		},
+		async notifySessionStateChange(agentId, chatId, state, organizationId) {
+			try {
+				await listenClient`SELECT pg_notify(${SESSION_STATE_CHANNEL}, ${`${agentId}:${chatId}:${state}:${organizationId}`})`;
+			} catch {}
+		},
+		async notifySessionEvent(agentId, chatId, kind, organizationId) {
+			try {
+				await listenClient`SELECT pg_notify(${SESSION_EVENT_CHANNEL}, ${`${agentId}:${chatId}:${kind}:${organizationId}`})`;
+			} catch {}
+		},
+		async notifyRuntimeStateChange(agentId, state, organizationId) {
+			try {
+				await listenClient`SELECT pg_notify(${RUNTIME_STATE_CHANNEL}, ${`${agentId}:${state}:${organizationId}`})`;
+			} catch {}
+		},
+		async notifyChatMessage(chatId, messageId) {
+			try {
+				await listenClient`SELECT pg_notify(${CHAT_MESSAGE_CHANNEL}, ${`${chatId}:${messageId}`})`;
+			} catch {}
+		},
+		async notifyAdminBroadcast(payload) {
+			let encoded;
+			try {
+				encoded = JSON.stringify(payload);
+			} catch {
+				return;
+			}
+			if (encoded.length > 7500) {
+				console.error(`[notifier] admin broadcast payload too large (${encoded.length} bytes); refusing to NOTIFY`);
+				return;
+			}
+			try {
+				await listenClient`SELECT pg_notify(${ADMIN_BROADCAST_CHANNEL}, ${encoded})`;
+			} catch {}
+		},
+		async pushFrameToInbox(inboxId, frame) {
+			const map = subscriptions.get(inboxId);
+			if (!map) return 0;
+			let queued = 0;
+			const pending = [];
+			for (const ws of map.keys()) {
+				if (ws.readyState !== ws.OPEN) continue;
+				pending.push(new Promise((resolve) => {
+					ws.send(frame, (err) => {
+						if (!err) queued += 1;
+						resolve();
+					});
+				}));
+			}
+			await Promise.all(pending);
+			return queued;
+		},
+		onConfigChange(handler) {
+			configChangeHandlers.push(handler);
+		},
+		onSessionStateChange(handler) {
+			sessionStateChangeHandlers.push(handler);
+		},
+		onSessionEvent(handler) {
+			sessionEventHandlers.push(handler);
+		},
+		onRuntimeStateChange(handler) {
+			runtimeStateChangeHandlers.push(handler);
+		},
+		onChatMessage(handler) {
+			chatMessageHandlers.push(handler);
+		},
+		onAdminBroadcast(handler) {
+			adminBroadcastHandlers.push(handler);
+		},
+		async start() {
+			unlistenInboxFn = (await listenClient.listen(INBOX_CHANNEL, (payload) => {
+				if (payload) handleNotification(payload);
+			})).unlisten;
+			unlistenConfigFn = (await listenClient.listen(CONFIG_CHANNEL, (payload) => {
+				if (payload) for (const handler of configChangeHandlers) handler(payload);
+			})).unlisten;
+			unlistenSessionStateFn = (await listenClient.listen(SESSION_STATE_CHANNEL, (payload) => {
+				if (payload) {
+					const firstSep = payload.indexOf(":");
+					const secondSep = payload.indexOf(":", firstSep + 1);
+					const thirdSep = payload.indexOf(":", secondSep + 1);
+					if (firstSep > 0 && secondSep > firstSep && thirdSep > secondSep) {
+						const agentId = payload.slice(0, firstSep);
+						const chatId = payload.slice(firstSep + 1, secondSep);
+						const state = payload.slice(secondSep + 1, thirdSep);
+						const organizationId = payload.slice(thirdSep + 1);
+						for (const handler of sessionStateChangeHandlers) handler({
+							agentId,
+							chatId,
+							state,
+							organizationId
+						});
+					}
+				}
+			})).unlisten;
+			unlistenSessionEventFn = (await listenClient.listen(SESSION_EVENT_CHANNEL, (payload) => {
+				if (payload) {
+					const firstSep = payload.indexOf(":");
+					const secondSep = payload.indexOf(":", firstSep + 1);
+					const thirdSep = payload.indexOf(":", secondSep + 1);
+					if (firstSep > 0 && secondSep > firstSep && thirdSep > secondSep) {
+						const agentId = payload.slice(0, firstSep);
+						const chatId = payload.slice(firstSep + 1, secondSep);
+						const kind = payload.slice(secondSep + 1, thirdSep);
+						const organizationId = payload.slice(thirdSep + 1);
+						for (const handler of sessionEventHandlers) try {
+							handler({
+								agentId,
+								chatId,
+								kind,
+								organizationId
+							});
+						} catch {}
+					}
+				}
+			})).unlisten;
+			unlistenRuntimeStateFn = (await listenClient.listen(RUNTIME_STATE_CHANNEL, (payload) => {
+				if (payload) {
+					const firstSep = payload.indexOf(":");
+					const secondSep = payload.indexOf(":", firstSep + 1);
+					if (firstSep > 0 && secondSep > firstSep) {
+						const agentId = payload.slice(0, firstSep);
+						const state = payload.slice(firstSep + 1, secondSep);
+						const organizationId = payload.slice(secondSep + 1);
+						for (const handler of runtimeStateChangeHandlers) handler({
+							agentId,
+							state,
+							organizationId
+						});
+					}
+				}
+			})).unlisten;
+			unlistenChatMessageFn = (await listenClient.listen(CHAT_MESSAGE_CHANNEL, (payload) => {
+				if (!payload) return;
+				const sep = payload.indexOf(":");
+				if (sep <= 0) return;
+				const chatId = payload.slice(0, sep);
+				const messageId = payload.slice(sep + 1);
+				for (const handler of chatMessageHandlers) try {
+					handler({
+						chatId,
+						messageId
+					});
+				} catch {}
+			})).unlisten;
+			unlistenAdminBroadcastFn = (await listenClient.listen(ADMIN_BROADCAST_CHANNEL, (payload) => {
+				if (!payload) return;
+				let parsed;
+				try {
+					parsed = JSON.parse(payload);
+				} catch {
+					return;
+				}
+				if (typeof parsed !== "object" || parsed === null) return;
+				const envelope = parsed;
+				for (const handler of adminBroadcastHandlers) try {
+					handler(envelope);
+				} catch {}
+			})).unlisten;
+		},
+		async stop() {
+			if (unlistenInboxFn) {
+				await unlistenInboxFn();
+				unlistenInboxFn = null;
+			}
+			if (unlistenConfigFn) {
+				await unlistenConfigFn();
+				unlistenConfigFn = null;
+			}
+			if (unlistenSessionStateFn) {
+				await unlistenSessionStateFn();
+				unlistenSessionStateFn = null;
+			}
+			if (unlistenSessionEventFn) {
+				await unlistenSessionEventFn();
+				unlistenSessionEventFn = null;
+			}
+			if (unlistenRuntimeStateFn) {
+				await unlistenRuntimeStateFn();
+				unlistenRuntimeStateFn = null;
+			}
+			if (unlistenChatMessageFn) {
+				await unlistenChatMessageFn();
+				unlistenChatMessageFn = null;
+			}
+			if (unlistenAdminBroadcastFn) {
+				await unlistenAdminBroadcastFn();
+				unlistenAdminBroadcastFn = null;
+			}
+		}
+	};
+}
+/** Fire-and-forget: notify all recipients that a new message is available. */
+function notifyRecipients(notifier, recipients, messageId) {
+	for (const inboxId of recipients) notifier.notify(inboxId, messageId).catch(() => {});
+}
+const log = createLogger("questions");
+/**
+* Insert a `pending_questions` row inside the same transaction that wrote a
+* `format=question` message. Caller is `sendMessage` after the message INSERT
+* returns, so a rollback drops both rows together. No-op (returns silently)
+* if the message content is not a valid `QuestionMessageContent` — the caller
+* will already have rejected such input upstream, but we defend in depth so a
+* malformed write never leaves a dangling pending row.
+*/
+async function recordPendingQuestionFromMessage(tx, args) {
+	const parsed = questionMessageContentSchema.safeParse(args.content);
+	if (!parsed.success) throw new BadRequestError("Invalid question message content", { "question.parse_error": parsed.error.message.slice(0, 200) });
+	const { correlationId } = parsed.data;
+	await tx.insert(pendingQuestions).values({
+		id: correlationId,
+		agentId: args.agentId,
+		chatId: args.chatId,
+		messageId: args.messageId,
+		status: "pending"
+	});
+}
+/**
+* Defensive write-side check: codex-runtime agents must never emit
+* `format=question` (Codex SDK 0.125 has no ask-user surface, so any such
+* message would be a runtime regression). Looks up the sender's
+* `runtime_provider` and rejects if it is `codex`. Throws `ForbiddenError`
+* (HTTP 403) so the bug surfaces loudly to the offending writer.
+*
+* Returns the runtime provider for telemetry / further checks (e.g. the
+* caller can attach it to the active span).
+*/
+async function assertSenderMayEmitQuestion(tx, senderAgentId) {
+	const [row] = await tx.select({ runtimeProvider: agents.runtimeProvider }).from(agents).where(eq(agents.uuid, senderAgentId)).limit(1);
+	if (!row) throw new NotFoundError(`Sender agent "${senderAgentId}" not found`);
+	if (row.runtimeProvider === "codex") {
+		log.error({
+			agentId: senderAgentId,
+			runtimeProvider: row.runtimeProvider
+		}, "rejected format=question emit from codex-runtime agent");
+		throw new ForbiddenError("Codex runtime cannot emit ask-user questions", {
+			"question.codex_emit_attempt": true,
+			"agent.id": senderAgentId
+		});
+	}
+	return row.runtimeProvider;
+}
+/**
+* User-side answer submission. Atomically:
+*   1. Lock the `pending_questions` row by correlationId.
+*   2. Refuse if status !== "pending" (409 if already-answered, 410-shaped
+*      400 if superseded — both surface as ConflictError so the caller knows
+*      the question is no longer answerable).
+*   3. Validate that the answer keys match the original `questions[]`.
+*   4. Flip status to `answered` INSIDE the lock-tx, before releasing the
+*      row lock. This is the linearisation point: the second concurrent
+*      submitter (waiting on the same row lock) will, on its turn, see
+*      status=answered and exit with ConflictError BEFORE it can write a
+*      second `format=question_answer` message.
+*   5. Send the `format=question_answer` message OUTSIDE the lock-tx
+*      (sendMessage opens its own transaction; nesting wasn't supported by
+*      the existing call site). At this point we hold an exclusive logical
+*      claim — only one submitter ever reaches this step per correlationId.
+*
+* `submitterAgentId` is the human agent on whose behalf the answer is
+* written (it must be a participant of the question's chat). Returns the
+* created `question_answer` message id so the route can include it in the
+* 201 response.
+*
+* Failure semantics: if step 5 (sendMessage) fails after status was flipped,
+* we revert the row to `pending` so the user can retry. This is best-effort —
+* the revert UPDATE is guarded by `status='answered'` to avoid clobbering a
+* supersede that might race in. If the revert itself fails, the row is
+* stranded as `answered` with no answer message; an operator would need to
+* intervene, but a sendMessage failure (local DB tx) is already
+* extraordinarily rare.
+*/
+async function submitAnswer(db, notifier, args) {
+	const questionRow = await db.transaction(async (tx) => {
+		const [row] = await tx.select({
+			id: pendingQuestions.id,
+			status: pendingQuestions.status,
+			chatId: pendingQuestions.chatId,
+			agentId: pendingQuestions.agentId,
+			messageId: pendingQuestions.messageId
+		}).from(pendingQuestions).where(eq(pendingQuestions.id, args.correlationId)).for("update").limit(1);
+		if (!row) throw new NotFoundError(`Question "${args.correlationId}" not found`);
+		if (row.chatId !== args.chatId) throw new NotFoundError(`Question "${args.correlationId}" not found in this chat`);
+		if (row.status !== "pending") throw new ConflictError(`Question "${args.correlationId}" is no longer pending`, { "question.status": row.status });
+		const [msg] = await tx.select({ content: messages.content }).from(messages).where(eq(messages.id, row.messageId)).limit(1);
+		if (!msg) throw new NotFoundError(`Question message "${row.messageId}" not found`);
+		const parsedQuestion = questionMessageContentSchema.safeParse(msg.content);
+		if (!parsedQuestion.success) throw new BadRequestError("Stored question content is malformed", { "question.parse_error": parsedQuestion.error.message.slice(0, 200) });
+		const expectedKeys = new Set(parsedQuestion.data.questions.map((q) => q.question));
+		for (const key of Object.keys(args.answers)) if (!expectedKeys.has(key)) throw new BadRequestError(`Answer key "${key}" does not match any question`, { "question.id": args.correlationId });
+		for (const key of expectedKeys) if (!(key in args.answers)) throw new BadRequestError(`Answer missing for question "${key}"`, { "question.id": args.correlationId });
+		await tx.update(pendingQuestions).set({
+			status: "answered",
+			answeredAt: /* @__PURE__ */ new Date()
+		}).where(eq(pendingQuestions.id, args.correlationId));
+		return row;
+	});
+	const answerContent = {
+		correlationId: args.correlationId,
+		answers: args.answers
+	};
+	questionAnswerMessageContentSchema.parse(answerContent);
+	let result;
+	try {
+		result = await sendMessage(db, args.chatId, args.submitterAgentId, {
+			format: "question_answer",
+			content: answerContent,
+			inReplyTo: questionRow.messageId,
+			source: "hub_ui"
+		});
+	} catch (err) {
+		log.error({
+			correlationId: args.correlationId,
+			chatId: args.chatId,
+			err: err instanceof Error ? err.message : String(err)
+		}, "sendMessage failed after status flip; reverting pending_questions row to 'pending'");
+		try {
+			await db.update(pendingQuestions).set({
+				status: "pending",
+				answeredAt: null
+			}).where(and(eq(pendingQuestions.id, args.correlationId), eq(pendingQuestions.status, "answered")));
+		} catch (revertErr) {
+			log.error({
+				correlationId: args.correlationId,
+				chatId: args.chatId,
+				revertErr: revertErr instanceof Error ? revertErr.message : String(revertErr)
+			}, "revert UPDATE also failed; row may be stranded as 'answered' without an answer message");
+		}
+		throw err;
+	}
+	if (notifier) notifyRecipients(notifier, result.recipients, result.message.id);
+	return {
+		messageId: result.message.id,
+		recipients: result.recipients
+	};
+}
+/**
+* Mark every pending row whose chat is `chatId` as superseded. Used when a
+* chat session is archived — the agent runtime that emitted the question
+* may already be gone, so leaving the row pending would block forever.
+*/
+async function markSupersededByChat(tx, chatId, reason = "chat_archived") {
+	return (await tx.update(pendingQuestions).set({
+		status: "superseded",
+		supersededAt: /* @__PURE__ */ new Date(),
+		supersededReason: reason
+	}).where(and(eq(pendingQuestions.chatId, chatId), eq(pendingQuestions.status, "pending"))).returning({ id: pendingQuestions.id })).length;
+}
+/**
+* Mark every pending row owned by any of `agentIds` as superseded. Used when
+* the client carrying these agents is claimed by a new user — the previous
+* owner's runtime is detached and cannot deliver an answer back.
+*/
+async function markSupersededByAgents(tx, agentIds, reason = "client_claimed") {
+	if (agentIds.length === 0) return 0;
+	return (await tx.update(pendingQuestions).set({
+		status: "superseded",
+		supersededAt: /* @__PURE__ */ new Date(),
+		supersededReason: reason
+	}).where(and(inArray(pendingQuestions.agentId, agentIds), eq(pendingQuestions.status, "pending"))).returning({ id: pendingQuestions.id })).length;
+}
+/** Extract a plain-text summary from a message's JSONB content field.
+*  Used as the auto-title fallback in chat list rendering — see
+*  `me-chat.ts:resolveChatTitle` and `admin/chats.ts:getChat`.
+*
+*  - `@<name>` mention tokens are stripped before truncation: in the
+*    chat-first model they're routing/audience metadata, not part of
+*    the user's intent. Leaving them in produces noisy titles like
+*    "@hub-agent-01 帮我重构这个文件" or "你好 @hub-agent-02 看看".
+*  - Whitespace runs (including those left behind by mention removal)
+*    collapse to single spaces.
+*  - If the cleaned text is empty (e.g., a message that's only
+*    `@hub-agent-01`), returns null so the caller falls through to
+*    the participant-join fallback.
+*  - Slicing is code-point-aware (`Array.from + join`) so emoji /
+*    surrogate pairs aren't split into garbled half-characters. */
+function extractSummary(content, maxLen = 50) {
+	let text = "";
+	if (typeof content === "object" && content !== null && "text" in content) text = String(content.text ?? "");
+	else if (typeof content === "string") text = content;
+	if (!text) return null;
+	const cleaned = stripCode(text).replace(MENTION_REGEX, "").replace(/\s+/g, " ").trim();
+	if (!cleaned) return null;
+	return Array.from(cleaned).slice(0, maxLen).join("");
+}
+/** List sessions for a specific agent, with optional state filters. */
+async function listAgentSessions(db, agentId, filters) {
+	const conditions = [eq(agentChatSessions.agentId, agentId)];
+	if (filters?.state) conditions.push(eq(agentChatSessions.state, filters.state));
+	else conditions.push(ne(agentChatSessions.state, "evicted"));
+	const rows = await db.select({
+		agentId: agentChatSessions.agentId,
+		chatId: agentChatSessions.chatId,
+		state: agentChatSessions.state,
+		updatedAt: agentChatSessions.updatedAt,
+		chatCreatedAt: chats.createdAt,
+		chatTopic: chats.topic
+	}).from(agentChatSessions).innerJoin(chats, eq(agentChatSessions.chatId, chats.id)).where(and(...conditions)).orderBy(desc(agentChatSessions.updatedAt));
+	const [presence] = await db.select({ runtimeState: agentPresence.runtimeState }).from(agentPresence).where(eq(agentPresence.agentId, agentId)).limit(1);
+	const agentRuntimeState = presence?.runtimeState ?? null;
+	if (filters?.runtimeState && agentRuntimeState !== filters.runtimeState) return [];
+	const chatIds = rows.map((r) => r.chatId);
+	const messageCounts = chatIds.length > 0 ? await db.select({
+		chatId: inboxEntries.chatId,
+		count: sql`count(*)::int`
+	}).from(inboxEntries).where(and(eq(inboxEntries.inboxId, sql`(SELECT inbox_id FROM agents WHERE uuid = ${agentId})`), inArray(inboxEntries.chatId, chatIds))).groupBy(inboxEntries.chatId) : [];
+	const countMap = new Map(messageCounts.map((r) => [r.chatId, r.count]));
+	const firstMessages = chatIds.length > 0 ? await db.selectDistinctOn([messages.chatId], {
+		chatId: messages.chatId,
+		content: messages.content
+	}).from(messages).where(inArray(messages.chatId, chatIds)).orderBy(messages.chatId, messages.createdAt) : [];
+	const summaryMap = /* @__PURE__ */ new Map();
+	for (const row of firstMessages) {
+		const summary = extractSummary(row.content);
+		if (summary) summaryMap.set(row.chatId, summary);
+	}
+	return rows.map((r) => ({
+		agentId: r.agentId,
+		chatId: r.chatId,
+		state: r.state,
+		runtimeState: agentRuntimeState,
+		startedAt: r.chatCreatedAt.toISOString(),
+		lastActivityAt: r.updatedAt.toISOString(),
+		messageCount: countMap.get(r.chatId) ?? 0,
+		summary: summaryMap.get(r.chatId) ?? null,
+		topic: r.chatTopic ?? null
+	}));
+}
+/** Get a single session's detail. */
+async function getSession(db, agentId, chatId) {
+	const [row] = await db.select({
+		agentId: agentChatSessions.agentId,
+		chatId: agentChatSessions.chatId,
+		state: agentChatSessions.state,
+		updatedAt: agentChatSessions.updatedAt,
+		chatCreatedAt: chats.createdAt,
+		chatTopic: chats.topic
+	}).from(agentChatSessions).innerJoin(chats, eq(agentChatSessions.chatId, chats.id)).where(and(eq(agentChatSessions.agentId, agentId), eq(agentChatSessions.chatId, chatId))).limit(1);
+	if (!row) throw new NotFoundError(`Session (${agentId}, ${chatId}) not found`);
+	const [presence] = await db.select({ runtimeState: agentPresence.runtimeState }).from(agentPresence).where(eq(agentPresence.agentId, agentId)).limit(1);
+	const [countRow] = await db.select({ count: sql`count(*)::int` }).from(inboxEntries).where(and(eq(inboxEntries.inboxId, sql`(SELECT inbox_id FROM agents WHERE uuid = ${agentId})`), eq(inboxEntries.chatId, chatId)));
+	const firstMsg = (await db.execute(sql`SELECT content FROM messages WHERE chat_id = ${chatId} ORDER BY created_at ASC LIMIT 1`))[0];
+	const summary = firstMsg ? extractSummary(firstMsg.content) : null;
+	return {
+		agentId: row.agentId,
+		chatId: row.chatId,
+		state: row.state,
+		runtimeState: presence?.runtimeState ?? null,
+		startedAt: row.chatCreatedAt.toISOString(),
+		lastActivityAt: row.updatedAt.toISOString(),
+		messageCount: countRow?.count ?? 0,
+		summary,
+		topic: row.chatTopic ?? null
+	};
+}
+/** List all sessions across all agents, with pagination. Scoped to organization. */
+async function listAllSessions(db, limit, cursor, filters) {
+	const conditions = [];
+	if (filters?.state) conditions.push(eq(agentChatSessions.state, filters.state));
+	else conditions.push(ne(agentChatSessions.state, "evicted"));
+	if (filters?.agentId) conditions.push(eq(agentChatSessions.agentId, filters.agentId));
+	if (filters?.organizationId) conditions.push(eq(agents.organizationId, filters.organizationId));
+	if (cursor) conditions.push(sql`${agentChatSessions.updatedAt} < ${new Date(cursor)}`);
+	const rows = await db.select({
+		agentId: agentChatSessions.agentId,
+		chatId: agentChatSessions.chatId,
+		state: agentChatSessions.state,
+		updatedAt: agentChatSessions.updatedAt,
+		chatCreatedAt: chats.createdAt,
+		chatTopic: chats.topic
+	}).from(agentChatSessions).innerJoin(chats, eq(agentChatSessions.chatId, chats.id)).innerJoin(agents, eq(agentChatSessions.agentId, agents.uuid)).where(conditions.length > 0 ? and(...conditions) : void 0).orderBy(desc(agentChatSessions.updatedAt)).limit(limit + 1);
+	const hasMore = rows.length > limit;
+	const items = hasMore ? rows.slice(0, limit) : rows;
+	const agentIds = [...new Set(items.map((r) => r.agentId))];
+	const presenceRows = agentIds.length > 0 ? await db.select({
+		agentId: agentPresence.agentId,
+		runtimeState: agentPresence.runtimeState
+	}).from(agentPresence).where(inArray(agentPresence.agentId, agentIds)) : [];
+	const runtimeMap = new Map(presenceRows.map((r) => [r.agentId, r.runtimeState]));
+	const chatIds = [...new Set(items.map((r) => r.chatId))];
+	const firstMessages = chatIds.length > 0 ? await db.selectDistinctOn([messages.chatId], {
+		chatId: messages.chatId,
+		content: messages.content
+	}).from(messages).where(inArray(messages.chatId, chatIds)).orderBy(messages.chatId, messages.createdAt) : [];
+	const summaryMap = /* @__PURE__ */ new Map();
+	for (const row of firstMessages) {
+		const summary = extractSummary(row.content);
+		if (summary) summaryMap.set(row.chatId, summary);
+	}
+	const last = items[items.length - 1];
+	const nextCursor = hasMore && last ? last.updatedAt.toISOString() : null;
+	return {
+		items: items.map((r) => ({
+			agentId: r.agentId,
+			chatId: r.chatId,
+			state: r.state,
+			runtimeState: runtimeMap.get(r.agentId) ?? null,
+			startedAt: r.chatCreatedAt.toISOString(),
+			lastActivityAt: r.updatedAt.toISOString(),
+			messageCount: 0,
+			summary: summaryMap.get(r.chatId) ?? null,
+			topic: r.chatTopic ?? null
+		})),
+		nextCursor
+	};
+}
+/** Commit `active → suspended`. No-op on suspended/evicted. Throws if row is missing. */
+async function suspendSession(db, agentId, chatId, organizationId, notifier) {
+	return transitionSessionState(db, agentId, chatId, "suspended", ["active"], organizationId, notifier);
+}
+/** Commit `suspended → evicted` (terminal — listings hide it, revival defense blocks resurrection). */
+async function archiveSession(db, agentId, chatId, organizationId, notifier) {
+	return transitionSessionState(db, agentId, chatId, "evicted", ["suspended"], organizationId, notifier);
+}
+async function transitionSessionState(db, agentId, chatId, target, from, organizationId, notifier) {
+	const now = /* @__PURE__ */ new Date();
+	let finalState = null;
+	let transitioned = false;
+	await db.transaction(async (tx) => {
+		const [existing] = await tx.select({ state: agentChatSessions.state }).from(agentChatSessions).where(and(eq(agentChatSessions.agentId, agentId), eq(agentChatSessions.chatId, chatId))).for("update");
+		if (!existing) return;
+		const current = existing.state;
+		finalState = current;
+		if (!from.includes(current)) return;
+		await tx.update(agentChatSessions).set({
+			state: target,
+			updatedAt: now
+		}).where(and(eq(agentChatSessions.agentId, agentId), eq(agentChatSessions.chatId, chatId)));
+		const [counts] = await tx.select({
+			active: sql`count(*) FILTER (WHERE ${agentChatSessions.state} = 'active')::int`,
+			total: sql`count(*) FILTER (WHERE ${agentChatSessions.state} != 'evicted')::int`
+		}).from(agentChatSessions).where(eq(agentChatSessions.agentId, agentId));
+		await tx.update(agentPresence).set({
+			activeSessions: counts?.active ?? 0,
+			totalSessions: counts?.total ?? 0,
+			lastSeenAt: now
+		}).where(eq(agentPresence.agentId, agentId));
+		if (target === "evicted") await markSupersededByChat(tx, chatId, "chat_archived");
+		finalState = target;
+		transitioned = true;
+	});
+	if (finalState === null) throw new NotFoundError(`Session (${agentId}, ${chatId}) not found`);
+	if (transitioned && notifier) notifier.notifySessionStateChange(agentId, chatId, target, organizationId).catch(() => {});
+	return {
+		state: finalState,
+		transitioned
+	};
+}
+/**
+* Filter sessions to only those where the given agent is also a participant in the chat.
+* Used when a non-manager views sessions of an org-visible agent — they should only see
+* sessions for chats they participate in.
+*/
+async function filterSessionsByParticipant(db, sessions, participantAgentId) {
+	if (sessions.length === 0) return [];
+	const chatIds = sessions.map((s) => s.chatId);
+	const participantRows = await db.select({ chatId: chatMembership.chatId }).from(chatMembership).where(and(inArray(chatMembership.chatId, chatIds), eq(chatMembership.agentId, participantAgentId), eq(chatMembership.accessMode, "speaker")));
+	const allowedChatIds = new Set(participantRows.map((r) => r.chatId));
+	return sessions.filter((s) => allowedChatIds.has(s.chatId));
+}
+/**
+* Member-facing chat service backing `/me/chats*` endpoints (chat-first
+* workspace).
+*
+* Responsibilities:
+*   - Cursor-paginated conversation list (single-stream JOIN over the
+*     unified `chat_membership` + `chat_user_state` tables).
+*   - Create a new chat (no dedupe, runs `recomputeChatWatchers` after).
+*   - Add participants (idempotent, UPSERT into `chat_membership`,
+*     runs `recomputeChatWatchers` after).
+*   - Mark-read (UPSERT into `chat_user_state`).
+*   - Join → watcher to speaker (delegates to `watcher.ts`).
+*   - Leave → speaker to watcher or detach (delegates to `watcher.ts`).
+*
+* See proposals/chat-data-model-restructure.20260512.md §8 (schema)
+* and §11.1 (per-route mapping).
+*/
+function encodeCursor(lastMessageAt, chatId) {
+	const payload = `${lastMessageAt ? lastMessageAt.toISOString() : ""}|${chatId}`;
+	return Buffer.from(payload, "utf8").toString("base64url");
+}
+function decodeCursor(cursor) {
+	try {
+		const decoded = Buffer.from(cursor, "base64url").toString("utf8");
+		const sep = decoded.indexOf("|");
+		if (sep < 0) return null;
+		const tsPart = decoded.slice(0, sep);
+		const chatId = decoded.slice(sep + 1);
+		if (!chatId) return null;
+		const lastMessageAt = tsPart.length > 0 ? new Date(tsPart) : null;
+		if (lastMessageAt && Number.isNaN(lastMessageAt.getTime())) return null;
+		return {
+			lastMessageAt,
+			chatId
+		};
+	} catch {
+		return null;
+	}
+}
+const { ACTIVE, ARCHIVED, DELETED } = CHAT_ENGAGEMENT_STATUSES;
+/**
+* SQL predicate for each engagement view tab. `deleted` is never a valid view
+* value — deleted rows are reachable only through `GET /chats/:chatId` + the
+* Restore banner on the chat detail page.
+*/
+const ENGAGEMENT_VIEW_PREDICATE = {
+	active: sql`COALESCE(cus.engagement_status, ${ACTIVE}) = ${ACTIVE}`,
+	archived: sql`COALESCE(cus.engagement_status, ${ACTIVE}) = ${ARCHIVED}`,
+	all: sql`COALESCE(cus.engagement_status, ${ACTIVE}) IN (${ACTIVE}, ${ARCHIVED})`
+};
+/**
+* Write the caller's engagement state for this chat. UPSERT into
+* `chat_user_state` — the row may not yet exist (the user might not have
+* marked-read or been @-mentioned), so an INSERT with the engagement value
+* is the first write; subsequent transitions are UPDATEs.
+*
+* Idempotent. Mirrors the UPSERT shape used by `markMeChatRead`.
+*/
+async function setChatEngagement(db, chatId, agentId, status) {
+	await db.insert(chatUserState).values({
+		chatId,
+		agentId,
+		unreadMentionCount: 0,
+		engagementStatus: status
+	}).onConflictDoUpdate({
+		target: [chatUserState.chatId, chatUserState.agentId],
+		set: { engagementStatus: status }
+	});
+}
+/**
+* Read the caller's engagement state. Returns `'active'` when no
+* `chat_user_state` row exists yet (lazy-materialised; matches the SQL
+* `COALESCE(..., 'active')` used elsewhere).
+*/
+async function getCallerEngagement(db, chatId, agentId) {
+	const [row] = await db.select({ engagementStatus: chatUserState.engagementStatus }).from(chatUserState).where(and(eq(chatUserState.chatId, chatId), eq(chatUserState.agentId, agentId))).limit(1);
+	return row?.engagementStatus ?? ACTIVE;
+}
+const KNOWN_NON_MANUAL_PREDICATE = sql`(
+     (c.metadata->>'source' = 'github' AND c.metadata->>'entityType' IN (${sql.join(GITHUB_ENTITY_TYPES.map((t) => sql`${t}`), sql.raw(", "))}))
+  OR c.metadata->>'source' = 'feishu'
+)`;
+const chatSourceSqlExpression = sql`CASE
+    ${sql.join(GITHUB_ENTITY_TYPES.map((t) => sql`WHEN c.metadata->>'source' = 'github' AND c.metadata->>'entityType' = ${t} THEN ${`github_${t}`}`), sql.raw("\n    "))}
+    WHEN c.metadata->>'source' = 'feishu' THEN 'feishu'
+    ELSE 'manual'
+  END`;
+function sourceFilterSql(source) {
+	switch (source) {
+		case "manual": return sql`(${KNOWN_NON_MANUAL_PREDICATE}) IS NOT TRUE`;
+		case "github_issue": return sql`(c.metadata->>'source' = 'github' AND c.metadata->>'entityType' = 'issue')`;
+		case "github_pull_request": return sql`(c.metadata->>'source' = 'github' AND c.metadata->>'entityType' = 'pull_request')`;
+		case "github_discussion": return sql`(c.metadata->>'source' = 'github' AND c.metadata->>'entityType' = 'discussion')`;
+		case "github_commit": return sql`(c.metadata->>'source' = 'github' AND c.metadata->>'entityType' = 'commit')`;
+		case "feishu": return sql`(c.metadata->>'source' = 'feishu')`;
+	}
+}
+/**
+* GET /me/chats — cursor-paginated conversation list.
+*
+* SQL strategy:
+*   - Single-stream query: `chats JOIN chat_membership LEFT JOIN
+*     chat_user_state`. The membership row carries access_mode
+*     (speaker → "participant" / watcher → "watching"); the user
+*     state row supplies the unread counter (COALESCE → 0 when
+*     row is missing).
+*   - Filter `parent_chat_id IS NULL` (nested chats not surfaced in v1).
+*   - Filter `c.organization_id = ?` to defend against historical
+*     cross-org pollution rows that may still reference the caller
+*     (see fix/cross-org-direct-chat-pollution).
+*   - Sort `(last_message_at DESC NULLS LAST, chat_id DESC)`.
+*   - Cursor narrows the result to rows STRICTLY before the cursor.
+*   - Followed by a participants-list lookup for the page only.
+*/
+async function listMeChats(db, humanAgentId, organizationId, query) {
+	const limit = query.limit;
+	const cursor = query.cursor ? decodeCursor(query.cursor) : null;
+	if (query.cursor && !cursor) throw new BadRequestError("Invalid cursor");
+	const filterUnreadOnly = query.filter === "unread";
+	const filterWatchingOnly = query.filter === "watching";
+	const engagementPredicate = ENGAGEMENT_VIEW_PREDICATE[query.engagement];
+	const sourcePredicate = query.source ? sourceFilterSql(query.source) : sql`TRUE`;
+	const cursorTsIso = cursor?.lastMessageAt ? cursor.lastMessageAt.toISOString() : null;
+	const cursorPredicate = !cursor ? sql`TRUE` : cursor.lastMessageAt === null ? sql`(c.last_message_at IS NULL AND c.id < ${cursor.chatId})` : sql`(c.last_message_at IS NULL
+             OR c.last_message_at < ${cursorTsIso}::timestamptz
+             OR (c.last_message_at = ${cursorTsIso}::timestamptz AND c.id < ${cursor.chatId}))`;
+	const rawRows = await db.execute(sql`
+    SELECT
+      c.id                  AS chat_id,
+      c.type                AS type,
+      c.topic               AS topic,
+      c.parent_chat_id      AS parent_chat_id,
+      c.last_message_at     AS last_message_at,
+      c.last_message_preview AS last_message_preview,
+      (SELECT count(*) FROM chat_membership
+        WHERE chat_id = c.id AND access_mode = 'speaker') AS participant_count,
+      cm.access_mode AS access_mode,
+      COALESCE(cus.unread_mention_count, 0) AS unread_mention_count,
+      COALESCE(cus.engagement_status, ${ACTIVE}) AS engagement_status
+      FROM chats c
+      JOIN chat_membership cm
+        ON cm.chat_id = c.id AND cm.agent_id = ${humanAgentId}
+      LEFT JOIN chat_user_state cus
+        ON cus.chat_id = c.id AND cus.agent_id = ${humanAgentId}
+     WHERE c.parent_chat_id IS NULL
+       /* Scope to the caller's org. Without this, cross-org dirty
+          chats whose chat_membership still references the caller's
+          human agent (historical pollution — see
+          fix/cross-org-direct-chat-pollution) would leak into the
+          list and 404 on click via requireChatAccess. */
+       AND c.organization_id = ${organizationId}
+       AND (${!filterUnreadOnly}::bool OR COALESCE(cus.unread_mention_count, 0) > 0)
+       AND (${!filterWatchingOnly}::bool OR cm.access_mode = 'watcher')
+       AND ${engagementPredicate}
+       AND ${sourcePredicate}
+       AND ${cursorPredicate}
+     ORDER BY c.last_message_at DESC NULLS LAST, c.id DESC
+     LIMIT ${limit + 1}
+  `);
+	const toDate = (v) => {
+		if (v === null) return null;
+		return v instanceof Date ? v : new Date(v);
+	};
+	const hasMore = rawRows.length > limit;
+	const pageRaw = hasMore ? rawRows.slice(0, limit) : rawRows;
+	const last = pageRaw[pageRaw.length - 1];
+	const nextCursor = hasMore && last ? encodeCursor(toDate(last.last_message_at), last.chat_id) : null;
+	if (pageRaw.length === 0) return {
+		rows: [],
+		nextCursor: null
+	};
+	const chatIds = pageRaw.map((r) => r.chat_id);
+	const participantRows = await db.select({
+		chatId: chatMembership.chatId,
+		agentId: chatMembership.agentId,
+		displayName: agents.displayName,
+		type: agents.type,
+		avatarColorToken: agents.avatarColorToken,
+		avatarImageUpdatedAt: agents.avatarImageUpdatedAt,
+		sessionState: agentChatSessions.state
+	}).from(chatMembership).innerJoin(agents, eq(chatMembership.agentId, agents.uuid)).leftJoin(agentChatSessions, and(eq(agentChatSessions.agentId, chatMembership.agentId), eq(agentChatSessions.chatId, chatMembership.chatId))).where(and(inArray(chatMembership.chatId, chatIds), eq(chatMembership.accessMode, "speaker")));
+	const participantsByChat = /* @__PURE__ */ new Map();
+	const engagedByChat = /* @__PURE__ */ new Map();
+	for (const p of participantRows) {
+		const list = participantsByChat.get(p.chatId) ?? [];
+		list.push({
+			agentId: p.agentId,
+			displayName: p.displayName,
+			type: p.type,
+			avatarColorToken: p.avatarColorToken,
+			avatarImageUrl: agentAvatarImageUrl(p.agentId, p.avatarImageUpdatedAt)
+		});
+		participantsByChat.set(p.chatId, list);
+		if (p.sessionState === "active") {
+			const engaged = engagedByChat.get(p.chatId) ?? [];
+			engaged.push(p.agentId);
+			engagedByChat.set(p.chatId, engaged);
+		}
+	}
+	const liveActivityByChat = await deriveLiveActivity(db, chatIds);
+	const firstMessageRows = chatIds.length > 0 ? await db.selectDistinctOn([messages.chatId], {
+		chatId: messages.chatId,
+		content: messages.content
+	}).from(messages).where(inArray(messages.chatId, chatIds)).orderBy(messages.chatId, messages.createdAt) : [];
+	const firstMessageSummary = /* @__PURE__ */ new Map();
+	for (const row of firstMessageRows) {
+		const s = extractSummary(row.content);
+		if (s) firstMessageSummary.set(row.chatId, s);
+	}
+	return {
+		rows: pageRaw.map((r) => {
+			const participants = participantsByChat.get(r.chat_id) ?? [];
+			const title = resolveChatTitle(r.topic, firstMessageSummary.get(r.chat_id) ?? null, participants, humanAgentId);
+			const isSpeaker = r.access_mode === "speaker";
+			return {
+				chatId: r.chat_id,
+				type: r.type,
+				membershipKind: isSpeaker ? "participant" : "watching",
+				title,
+				topic: r.topic,
+				participants,
+				participantCount: Number(r.participant_count),
+				lastMessageAt: toDate(r.last_message_at)?.toISOString() ?? null,
+				lastMessagePreview: r.last_message_preview,
+				unreadMentionCount: r.unread_mention_count,
+				canReply: isSpeaker,
+				engagementStatus: r.engagement_status,
+				engagedAgentIds: engagedByChat.get(r.chat_id) ?? [],
+				liveActivity: liveActivityByChat.get(r.chat_id) ?? null
+			};
+		}),
+		nextCursor
+	};
+}
+/**
+* Per-chat live activity, derived from the most recent `session_events` row.
+*
+* Returns a chatId → LiveActivity map; chats with no activity (or where the
+* latest event is terminal / stale) are absent from the map (caller treats
+* absence as null).
+*/
+async function deriveLiveActivity(db, chatIds) {
+	if (chatIds.length === 0) return /* @__PURE__ */ new Map();
+	const chatIdInClause = sql.join(chatIds.map((id) => sql`${id}`), sql`, `);
+	const rows = (await db.execute(sql`
+    SELECT acs.agent_id        AS agent_id,
+           acs.chat_id         AS chat_id,
+           e.kind              AS kind,
+           e.payload           AS payload,
+           e.created_at        AS created_at
+      FROM agent_chat_sessions acs
+      CROSS JOIN LATERAL (
+        SELECT kind, payload, created_at, seq
+          FROM session_events se
+         WHERE se.agent_id = acs.agent_id
+           AND se.chat_id  = acs.chat_id
+         ORDER BY se.seq DESC
+         LIMIT 1
+      ) e
+     WHERE acs.chat_id IN (${chatIdInClause})
+       AND acs.state <> 'evicted'
+  `)).map((r) => ({
+		agent_id: r.agent_id,
+		chat_id: r.chat_id,
+		kind: r.kind,
+		payload: r.payload,
+		created_at: r.created_at
+	}));
+	const now = Date.now();
+	const byChat = /* @__PURE__ */ new Map();
+	for (const row of rows) {
+		const activity = toLiveActivity(row);
+		if (!activity) continue;
+		const createdAtMs = new Date(row.created_at).getTime();
+		if (now - createdAtMs > 6e4) continue;
+		const existing = byChat.get(row.chat_id);
+		if (!existing || createdAtMs > existing.createdAtMs) byChat.set(row.chat_id, {
+			activity,
+			createdAtMs
+		});
+	}
+	const out = /* @__PURE__ */ new Map();
+	for (const [chatId, { activity }] of byChat) out.set(chatId, activity);
+	return out;
+}
+/**
+* Translate a `session_events` row into a `LiveActivity`, or null when the
+* kind is terminal (`turn_end` / `error`) or unrecognised. Pure & exported
+* for unit testing.
+*/
+function toLiveActivity(row) {
+	const startedAt = new Date(row.created_at).toISOString();
+	switch (row.kind) {
+		case "tool_call": {
+			const payload = row.payload ?? {};
+			const label = typeof payload.name === "string" && payload.name.length > 0 ? payload.name : "Tool";
+			return {
+				agentId: row.agent_id,
+				kind: "tool_call",
+				label,
+				startedAt
+			};
+		}
+		case "thinking": return {
+			agentId: row.agent_id,
+			kind: "thinking",
+			label: "Thinking",
+			startedAt
+		};
+		case "assistant_text": return {
+			agentId: row.agent_id,
+			kind: "assistant_text",
+			label: "Writing",
+			startedAt
+		};
+		default: return null;
+	}
+}
+/**
+* Title resolution priority:
+*
+*   1. `chat.topic` (manual, set via `PATCH /chats/:chatId`)
+*   2. First message summary (auto, ≤ 50 chars from `extractSummary`)
+*   3. Participant join (fallback when chat has no messages yet)
+*/
+function resolveChatTitle(topic, firstMessageSummary, participants, selfAgentId) {
+	if (topic && topic.length > 0) return topic;
+	if (firstMessageSummary && firstMessageSummary.length > 0) return firstMessageSummary;
+	const others = participants.filter((p) => p.agentId !== selfAgentId);
+	if (others.length === 0) return "Empty chat";
+	if (others.length <= 3) return others.map((p) => p.displayName).join(", ");
+	return `${others[0]?.displayName}, ${others[1]?.displayName} +${others.length - 2}`;
+}
+async function createMeChat(db, humanAgentId, organizationId, body) {
+	const distinctIds = [...new Set(body.participantIds)].filter((id) => id !== humanAgentId);
+	if (distinctIds.length === 0) throw new BadRequestError("At least one non-self participant required");
+	const allIds = [humanAgentId, ...distinctIds];
+	const found = await db.select({
+		uuid: agents.uuid,
+		organizationId: agents.organizationId,
+		type: agents.type,
+		visibility: agents.visibility,
+		managerId: agents.managerId
+	}).from(agents).where(inArray(agents.uuid, allIds));
+	if (found.length !== allIds.length) {
+		const foundSet = new Set(found.map((a) => a.uuid));
+		throw new BadRequestError(`Agents not found: ${allIds.filter((id) => !foundSet.has(id)).join(", ")}`);
+	}
+	const crossOrg = found.filter((a) => a.organizationId !== organizationId);
+	if (crossOrg.length > 0) throw new BadRequestError(`Cross-organization chat not allowed: ${crossOrg.map((a) => a.uuid).join(", ")}`);
+	const caller = found.find((a) => a.uuid === humanAgentId);
+	if (!caller) throw new BadRequestError("Caller agent not found in the chat's organization");
+	const privateNotOwned = found.filter((a) => a.uuid !== humanAgentId && a.visibility === AGENT_VISIBILITY.PRIVATE && a.managerId !== caller.managerId);
+	if (privateNotOwned.length > 0) throw new ForbiddenError(`Only the owner can add a private agent to a chat: ${privateNotOwned.map((a) => a.uuid).join(", ")}`);
+	const chatType = distinctIds.length === 1 ? "direct" : "group";
+	const chatId = randomUUID();
+	const topic = body.topic ?? null;
+	await db.transaction(async (tx) => {
+		await tx.insert(chats).values({
+			id: chatId,
+			organizationId,
+			type: chatType,
+			topic
+		});
+		await addChatParticipants(tx, chatId, allIds.map((agentId) => ({
+			agentId,
+			role: agentId === humanAgentId ? "owner" : "member"
+		})));
+		await recomputeChatWatchers(tx, chatId);
+	});
+	invalidateChatAudience(chatId);
+	return { chatId };
+}
+async function addMeChatParticipants(db, chatId, callerHumanAgentId, callerOrganizationId, body) {
+	const distinct = [...new Set(body.participantIds)];
+	if (distinct.length === 0) throw new BadRequestError("At least one participant required");
+	const [chat] = await db.select({
+		id: chats.id,
+		organizationId: chats.organizationId,
+		type: chats.type
+	}).from(chats).where(eq(chats.id, chatId)).limit(1);
+	if (!chat) throw new NotFoundError(`Chat "${chatId}" not found`);
+	if (chat.organizationId !== callerOrganizationId) throw new NotFoundError(`Chat "${chatId}" not found`);
+	const [callerRow] = await db.select({ ownerMemberId: agents.managerId }).from(chatMembership).innerJoin(agents, eq(agents.uuid, chatMembership.agentId)).where(and(eq(chatMembership.chatId, chatId), eq(chatMembership.agentId, callerHumanAgentId), eq(chatMembership.accessMode, "speaker"))).limit(1);
+	if (!callerRow) throw new NotFoundError(`Chat "${chatId}" not found`);
+	const callerMemberId = callerRow.ownerMemberId;
+	const found = await db.select({
+		uuid: agents.uuid,
+		organizationId: agents.organizationId,
+		type: agents.type,
+		visibility: agents.visibility,
+		managerId: agents.managerId
+	}).from(agents).where(inArray(agents.uuid, distinct));
+	if (found.length !== distinct.length) {
+		const foundSet = new Set(found.map((a) => a.uuid));
+		throw new BadRequestError(`Agents not found: ${distinct.filter((id) => !foundSet.has(id)).join(", ")}`);
+	}
+	const crossOrg = found.filter((a) => a.organizationId !== chat.organizationId);
+	if (crossOrg.length > 0) throw new BadRequestError(`Cross-organization participant rejected: ${crossOrg.map((a) => a.uuid).join(", ")}`);
+	const privateNotOwned = found.filter((a) => a.visibility === AGENT_VISIBILITY.PRIVATE && a.managerId !== callerMemberId);
+	if (privateNotOwned.length > 0) throw new ForbiddenError(`Only the owner can add a private agent to a chat: ${privateNotOwned.map((a) => a.uuid).join(", ")}`);
+	await db.transaction(async (tx) => {
+		const existingSpeakers = await tx.select({ agentId: chatMembership.agentId }).from(chatMembership).where(and(eq(chatMembership.chatId, chatId), eq(chatMembership.accessMode, "speaker")));
+		const existingSpeakerSet = new Set(existingSpeakers.map((e) => e.agentId));
+		const toUpsert = distinct.filter((id) => !existingSpeakerSet.has(id));
+		if (toUpsert.length === 0) {
+			await recomputeChatWatchers(tx, chatId);
+			return;
+		}
+		if (existingSpeakers.length + toUpsert.length >= 3 && chat.type === "direct") await changeChatType(tx, chatId, "group");
+		await addChatParticipants(tx, chatId, toUpsert.map((agentId) => ({
+			agentId,
+			role: "member"
+		})), { upgradeWatcherToSpeaker: true });
+		await recomputeChatWatchers(tx, chatId);
+	});
+	invalidateChatAudience(chatId);
+}
+async function markMeChatRead(db, chatId, humanAgentId) {
+	const now = /* @__PURE__ */ new Date();
+	await db.insert(chatUserState).values({
+		chatId,
+		agentId: humanAgentId,
+		lastReadAt: now,
+		unreadMentionCount: 0
+	}).onConflictDoUpdate({
+		target: [chatUserState.chatId, chatUserState.agentId],
+		set: {
+			lastReadAt: now,
+			unreadMentionCount: 0
+		}
+	});
+	return {
+		chatId,
+		lastReadAt: now.toISOString(),
+		unreadMentionCount: 0
+	};
+}
+/**
+* Bump `unread_mention_count` to at least 1 so the chat shows up as unread
+* in the conversation list (and is matched by `?filter=unread`). Idempotent:
+* if the row already has a positive count, it stays as-is. `last_read_at`
+* is intentionally untouched — this is a UI affordance, not a "rewind the
+* read cursor" operation.
+*
+* Contract note — semantic overload: the column is named `unread_mention_count`
+* but is co-opted here as a generic "manual unread" flag. Every existing
+* consumer (conversation list bold styling, `?filter=unread`, source-counts,
+* the bell badge) only checks `> 0`, so the exact value carries no meaning
+* for callers. If a future feature ever renders the literal mention count
+* (e.g. a "N mentions" pill), it must NOT read this column directly — it
+* needs a separate mention-only counter, otherwise a manually-marked-unread
+* chat would show a fictitious "1 mention".
+*/
+async function markMeChatUnread(db, chatId, humanAgentId) {
+	await db.insert(chatUserState).values({
+		chatId,
+		agentId: humanAgentId,
+		unreadMentionCount: 1
+	}).onConflictDoUpdate({
+		target: [chatUserState.chatId, chatUserState.agentId],
+		set: { unreadMentionCount: sql`GREATEST(${chatUserState.unreadMentionCount}, 1)` }
+	});
+	const [row] = await db.select({ unreadMentionCount: chatUserState.unreadMentionCount }).from(chatUserState).where(and(eq(chatUserState.chatId, chatId), eq(chatUserState.agentId, humanAgentId))).limit(1);
+	return {
+		chatId,
+		unreadMentionCount: row?.unreadMentionCount ?? 1
+	};
+}
+async function joinMeChat(db, chatId, humanAgentId) {
+	ensureCanJoin(await resolveChatMembership(db, chatId, humanAgentId));
+	await joinAsParticipant(db, chatId, humanAgentId);
+	invalidateChatAudience(chatId);
+}
+async function leaveMeChat(db, chatId, humanAgentId) {
+	const result = await leaveAsParticipant(db, chatId, humanAgentId);
+	invalidateChatAudience(chatId);
+	return result;
+}
+/**
+* Used by future bell-badge / list-pill counts. The partial index
+* `idx_user_state_unread WHERE unread_mention_count > 0` bounds the
+* driving scan; we then join `chat_membership` + `chats` so the badge
+* stays consistent with `listMeChats`.
+*
+* Why the joins (not just a single-table count): per §11.4 a user's
+* `chat_user_state` row is **preserved on detach** so read state
+* survives a leave/rejoin cycle. Without the membership join, any
+* preserved row with `unread_mention_count > 0` would keep
+* contributing to the badge even though the chat no longer appears in
+* the list. The `chats` join applies the same org-scoping +
+* `parent_chat_id IS NULL` filter as `listMeChats` so the two counts
+* cannot drift in the cross-org pollution or nested-chat cases either.
+*
+* Engagement parity: deleted chats are excluded from `listMeChats`
+* (any `engagement` view), so the badge must exclude them too — otherwise
+* the user sees an unread red dot for a chat they've removed from view.
+*/
+/**
+* Per-source aggregate for the conversation-list tag bar.
+*
+* Returns one row per source the caller has at least one chat for, plus an
+* always-present `manual` entry (zero counts when there are no manual chats —
+* the workspace UI uses `manual` as its default tab and must render it even
+* when empty).
+*
+* Filtering matches `listMeChats` for the corresponding tab so the badges
+* cannot drift from the list: same membership join, same `parent_chat_id IS
+* NULL` and `organization_id` scopes, same engagement view, same
+* `chat_user_state.unread_mention_count` source.
+*/
+async function listMeChatSourceCounts(db, humanAgentId, organizationId, query) {
+	const engagementPredicate = ENGAGEMENT_VIEW_PREDICATE[query.engagement];
+	const rows = await db.execute(sql`
+    SELECT
+      ${chatSourceSqlExpression} AS source,
+      count(*)::int AS chat_count,
+      count(*) FILTER (WHERE COALESCE(cus.unread_mention_count, 0) > 0)::int AS unread_chat_count
+      FROM chats c
+      JOIN chat_membership cm
+        ON cm.chat_id = c.id AND cm.agent_id = ${humanAgentId}
+      LEFT JOIN chat_user_state cus
+        ON cus.chat_id = c.id AND cus.agent_id = ${humanAgentId}
+     WHERE c.parent_chat_id IS NULL
+       AND c.organization_id = ${organizationId}
+       AND ${engagementPredicate}
+     GROUP BY 1
+  `);
+	const counts = {};
+	for (const row of rows) counts[row.source] = {
+		chatCount: Number(row.chat_count),
+		unreadChatCount: Number(row.unread_chat_count)
+	};
+	if (!counts.manual) counts.manual = {
+		chatCount: 0,
+		unreadChatCount: 0
+	};
+	return { counts };
+}
+async function createChat(db, creatorId, data) {
+	const chatId = randomUUID();
+	const allParticipantIds = new Set([creatorId, ...data.participantIds]);
+	const existingAgents = await db.select({
+		id: agents.uuid,
+		organizationId: agents.organizationId,
+		type: agents.type,
+		visibility: agents.visibility,
+		managerId: agents.managerId
+	}).from(agents).where(inArray(agents.uuid, [...allParticipantIds]));
+	if (existingAgents.length !== allParticipantIds.size) {
+		const found = new Set(existingAgents.map((a) => a.id));
+		throw new BadRequestError(`Agents not found: ${[...allParticipantIds].filter((id) => !found.has(id)).join(", ")}`);
+	}
+	const creator = existingAgents.find((a) => a.id === creatorId);
+	if (!creator) throw new Error("Unexpected: creator not in existingAgents");
+	const orgId = creator.organizationId;
+	const crossOrg = existingAgents.filter((a) => a.organizationId !== orgId);
+	if (crossOrg.length > 0) throw new BadRequestError(`Cross-organization chat not allowed: ${crossOrg.map((a) => a.id).join(", ")}`);
+	const privateNotOwned = existingAgents.filter((a) => a.id !== creatorId && a.visibility === AGENT_VISIBILITY.PRIVATE && a.managerId !== creator.managerId);
+	if (privateNotOwned.length > 0) throw new ForbiddenError(`Only the owner can add a private agent to a chat: ${privateNotOwned.map((a) => a.id).join(", ")}`);
+	return db.transaction(async (tx) => {
+		const [chat] = await tx.insert(chats).values({
+			id: chatId,
+			organizationId: orgId,
+			type: data.type,
+			topic: data.topic ?? null,
+			metadata: data.metadata ?? {}
+		}).returning();
+		await addChatParticipants(tx, chatId, [...allParticipantIds].map((agentId) => ({
+			agentId,
+			role: agentId === creatorId ? "owner" : "member"
+		})));
+		await recomputeChatWatchers(tx, 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,
+			participants
+		};
+	});
+}
+async function getChat(db, chatId) {
+	const [chat] = await db.select().from(chats).where(eq(chats.id, chatId)).limit(1);
+	if (!chat) throw new NotFoundError(`Chat "${chatId}" not found`);
+	return chat;
+}
+/**
+* Read a chat row + speaker participants + server-resolved display
+* metadata (`title`, `firstMessagePreview`) so the agent route can return
+* a payload that matches the wire `chatDetailSchema` contract.
+*
+* `selfAgentId` only affects the participant-join fallback in
+* `resolveChatTitle` (e.g. `"alice, bob"` excluding self when topic + first
+* message are both empty). Callers that don't have a self agent (admin
+* paths) can pass `null` — the fallback degrades to "all displayNames".
+*/
+async function getChatDetail(db, chatId, selfAgentId = null) {
+	const chat = await getChat(db, chatId);
+	const participantRows = await db.select({
+		agentId: chatMembership.agentId,
+		role: chatMembership.role,
+		mode: chatMembership.mode,
+		joinedAt: chatMembership.joinedAt,
+		name: agents.name,
+		displayName: agents.displayName,
+		type: agents.type
+	}).from(chatMembership).innerJoin(agents, eq(chatMembership.agentId, agents.uuid)).where(and(eq(chatMembership.chatId, chatId), eq(chatMembership.accessMode, "speaker")));
+	const [firstMessageRow] = await db.select({ content: messages.content }).from(messages).where(eq(messages.chatId, chatId)).orderBy(messages.createdAt, messages.id).limit(1);
+	const firstMessagePreview = firstMessageRow ? extractSummary(firstMessageRow.content) : null;
+	const title = resolveChatTitle(chat.topic, firstMessagePreview, participantRows, selfAgentId ?? "");
+	const participants = participantRows.map((p) => ({
+		chatId,
+		agentId: p.agentId,
+		role: p.role,
+		mode: p.mode,
+		joinedAt: p.joinedAt,
+		name: p.name,
+		displayName: p.displayName,
+		type: p.type
+	}));
+	return {
+		...chat,
+		participants,
+		title,
+		firstMessagePreview
+	};
+}
+async function listChats(db, agentId, limit, cursor) {
+	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
+	};
+	const where = cursor ? and(inArray(chats.id, chatIds), lt(chats.updatedAt, new Date(cursor))) : inArray(chats.id, chatIds);
+	const rows = await db.select().from(chats).where(where).orderBy(desc(chats.updatedAt)).limit(limit + 1);
+	const hasMore = rows.length > limit;
+	const items = hasMore ? rows.slice(0, limit) : rows;
+	const last = items[items.length - 1];
+	return {
+		items,
+		nextCursor: hasMore && last ? last.updatedAt.toISOString() : null
+	};
+}
+/**
+* List participants of a chat with their agent names — used by the client
+* runtime to resolve `@<name>` mentions against the authoritative participant
+* set (see proposals/hub-agent-messaging-reply-and-mentions §4).
+*/
+async function listChatParticipantsWithNames(db, chatId) {
+	return await db.select({
+		agentId: chatMembership.agentId,
+		role: chatMembership.role,
+		mode: chatMembership.mode,
+		joinedAt: chatMembership.joinedAt,
+		name: agents.name,
+		displayName: agents.displayName,
+		type: agents.type
+	}).from(chatMembership).innerJoin(agents, eq(chatMembership.agentId, agents.uuid)).where(and(eq(chatMembership.chatId, chatId), eq(chatMembership.accessMode, "speaker")));
 }
-/** Fire-and-forget: notify all recipients that a new message is available. */
-function notifyRecipients(notifier, recipients, messageId) {
-	for (const inboxId of recipients) notifier.notify(inboxId, messageId).catch(() => {});
+async function assertParticipant(db, chatId, agentId) {
+	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");
 }
-const log$1 = createLogger("questions");
 /**
-* Insert a `pending_questions` row inside the same transaction that wrote a
-* `format=question` message. Caller is `sendMessage` after the message INSERT
-* returns, so a rollback drops both rows together. No-op (returns silently)
-* if the message content is not a valid `QuestionMessageContent` — the caller
-* will already have rejected such input upstream, but we defend in depth so a
-* malformed write never leaves a dangling pending row.
+* Non-throwing membership check. Used by routing logic that needs to fall
+* back to a different chat when the candidate target isn't a member of the
+* caller's current chat (see `sendToAgent`'s current-chat routing branch).
 */
-async function recordPendingQuestionFromMessage(tx, args) {
-	const parsed = questionMessageContentSchema.safeParse(args.content);
-	if (!parsed.success) throw new BadRequestError("Invalid question message content", { "question.parse_error": parsed.error.message.slice(0, 200) });
-	const { correlationId } = parsed.data;
-	await tx.insert(pendingQuestions).values({
-		id: correlationId,
-		agentId: args.agentId,
-		chatId: args.chatId,
-		messageId: args.messageId,
-		status: "pending"
+async function isParticipant(db, chatId, agentId) {
+	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 speaker of a chat. Silently adds them if not already. */
+async function ensureParticipant(db, chatId, agentId) {
+	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: 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);
+}
+async function addParticipant(db, chatId, requesterId, data) {
+	const chat = await getChat(db, chatId);
+	await assertParticipant(db, chatId, requesterId);
+	const [targetAgent] = await db.select({
+		id: agents.uuid,
+		organizationId: agents.organizationId,
+		inboxId: agents.inboxId,
+		visibility: agents.visibility,
+		managerId: agents.managerId
+	}).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");
+	if (targetAgent.visibility === AGENT_VISIBILITY.PRIVATE && targetAgent.id !== requesterId) {
+		const [requester] = await db.select({ managerId: agents.managerId }).from(agents).where(eq(agents.uuid, requesterId)).limit(1);
+		if (!requester) throw new NotFoundError(`Agent "${requesterId}" not found`);
+		if (requester.managerId !== targetAgent.managerId) throw new ForbiddenError(`Only the owner can add a private agent to a chat: ${targetAgent.id}`);
+	}
+	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: 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);
+		await backfillSilentContextForNewParticipants(tx, chatId, [{ inboxId: targetAgent.inboxId }]);
 	});
+	invalidateChatAudience(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(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(chatMembership).where(and(eq(chatMembership.chatId, chatId), eq(chatMembership.accessMode, "speaker")));
 }
 /**
-* Defensive write-side check: codex-runtime agents must never emit
-* `format=question` (Codex SDK 0.125 has no ask-user surface, so any such
-* message would be a runtime regression). Looks up the sender's
-* `runtime_provider` and rejects if it is `codex`. Throws `ForbiddenError`
-* (HTTP 403) so the bug surfaces loudly to the offending writer.
-*
-* Returns the runtime provider for telemetry / further checks (e.g. the
-* caller can attach it to the active span).
+* List chats visible to a member, grouped by agent.
+* A member sees chats where:
+*   1. Their human agent is a participant, OR
+*   2. Any agent they manage (managerId = memberId) is a participant (supervision)
 */
-async function assertSenderMayEmitQuestion(tx, senderAgentId) {
-	const [row] = await tx.select({ runtimeProvider: agents.runtimeProvider }).from(agents).where(eq(agents.uuid, senderAgentId)).limit(1);
-	if (!row) throw new NotFoundError(`Sender agent "${senderAgentId}" not found`);
-	if (row.runtimeProvider === "codex") {
-		log$1.error({
-			agentId: senderAgentId,
-			runtimeProvider: row.runtimeProvider
-		}, "rejected format=question emit from codex-runtime agent");
-		throw new ForbiddenError("Codex runtime cannot emit ask-user questions", {
-			"question.codex_emit_attempt": true,
-			"agent.id": senderAgentId
+async function listChatsForMember(db, memberId, humanAgentId) {
+	const managedAgents = await db.select({
+		uuid: agents.uuid,
+		name: agents.name,
+		type: agents.type,
+		displayName: agents.displayName
+	}).from(agents).where(eq(agents.managerId, memberId));
+	const agentMap = /* @__PURE__ */ new Map();
+	for (const a of managedAgents) agentMap.set(a.uuid, a);
+	if (!agentMap.has(humanAgentId)) {
+		const [ha] = await db.select({
+			uuid: agents.uuid,
+			name: agents.name,
+			type: agents.type,
+			displayName: agents.displayName
+		}).from(agents).where(eq(agents.uuid, humanAgentId)).limit(1);
+		if (ha) agentMap.set(ha.uuid, ha);
+	}
+	const agentIds = [...agentMap.keys()];
+	if (agentIds.length === 0) return [];
+	const participations = await db.select({
+		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();
+	for (const p of participations) {
+		const list = agentChatMap.get(p.agentId) ?? [];
+		list.push(p.chatId);
+		agentChatMap.set(p.agentId, list);
+	}
+	const chatRows = await db.select({
+		id: chats.id,
+		type: chats.type,
+		topic: chats.topic,
+		metadata: chats.metadata,
+		createdAt: chats.createdAt,
+		updatedAt: chats.updatedAt,
+		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));
+	const result = [];
+	for (const [agentId, agentChatIds] of agentChatMap) {
+		const agentInfo = agentMap.get(agentId);
+		if (!agentInfo) continue;
+		const agentChats = agentChatIds.map((chatId) => {
+			const chat = chatMap.get(chatId);
+			if (!chat) return null;
+			const isSupervisionOnly = agentId !== humanAgentId && !humanParticipantChatIds.has(chatId);
+			return {
+				id: chat.id,
+				type: chat.type,
+				topic: chat.topic,
+				participantCount: chat.participantCount,
+				isSupervisionOnly,
+				createdAt: chat.createdAt.toISOString(),
+				updatedAt: chat.updatedAt.toISOString()
+			};
+		}).filter((c) => c !== null);
+		if (agentChats.length > 0) result.push({
+			agent: agentInfo,
+			chats: agentChats
 		});
 	}
-	return row.runtimeProvider;
+	return result;
 }
 /**
-* User-side answer submission. Atomically:
-*   1. Lock the `pending_questions` row by correlationId.
-*   2. Refuse if status !== "pending" (409 if already-answered, 410-shaped
-*      400 if superseded — both surface as ConflictError so the caller knows
-*      the question is no longer answerable).
-*   3. Validate that the answer keys match the original `questions[]`.
-*   4. Flip status to `answered` INSIDE the lock-tx, before releasing the
-*      row lock. This is the linearisation point: the second concurrent
-*      submitter (waiting on the same row lock) will, on its turn, see
-*      status=answered and exit with ConflictError BEFORE it can write a
-*      second `format=question_answer` message.
-*   5. Send the `format=question_answer` message OUTSIDE the lock-tx
-*      (sendMessage opens its own transaction; nesting wasn't supported by
-*      the existing call site). At this point we hold an exclusive logical
-*      claim — only one submitter ever reaches this step per correlationId.
-*
-* `submitterAgentId` is the human agent on whose behalf the answer is
-* written (it must be a participant of the question's chat). Returns the
-* created `question_answer` message id so the route can include it in the
-* 201 response.
-*
-* Failure semantics: if step 5 (sendMessage) fails after status was flipped,
-* we revert the row to `pending` so the user can retry. This is best-effort —
-* the revert UPDATE is guarded by `status='answered'` to avoid clobbering a
-* supersede that might race in. If the revert itself fails, the row is
-* stranded as `answered` with no answer message; an operator would need to
-* intervene, but a sendMessage failure (local DB tx) is already
-* extraordinarily rare.
+* Manager joins a chat. Adds their human agent as a participant.
+* Requires the member to have supervision rights (manages at least one existing participant).
 */
-async function submitAnswer(db, notifier, args) {
-	const questionRow = await db.transaction(async (tx) => {
-		const [row] = await tx.select({
-			id: pendingQuestions.id,
-			status: pendingQuestions.status,
-			chatId: pendingQuestions.chatId,
-			agentId: pendingQuestions.agentId,
-			messageId: pendingQuestions.messageId
-		}).from(pendingQuestions).where(eq(pendingQuestions.id, args.correlationId)).for("update").limit(1);
-		if (!row) throw new NotFoundError(`Question "${args.correlationId}" not found`);
-		if (row.chatId !== args.chatId) throw new NotFoundError(`Question "${args.correlationId}" not found in this chat`);
-		if (row.status !== "pending") throw new ConflictError(`Question "${args.correlationId}" is no longer pending`, { "question.status": row.status });
-		const [msg] = await tx.select({ content: messages.content }).from(messages).where(eq(messages.id, row.messageId)).limit(1);
-		if (!msg) throw new NotFoundError(`Question message "${row.messageId}" not found`);
-		const parsedQuestion = questionMessageContentSchema.safeParse(msg.content);
-		if (!parsedQuestion.success) throw new BadRequestError("Stored question content is malformed", { "question.parse_error": parsedQuestion.error.message.slice(0, 200) });
-		const expectedKeys = new Set(parsedQuestion.data.questions.map((q) => q.question));
-		for (const key of Object.keys(args.answers)) if (!expectedKeys.has(key)) throw new BadRequestError(`Answer key "${key}" does not match any question`, { "question.id": args.correlationId });
-		for (const key of expectedKeys) if (!(key in args.answers)) throw new BadRequestError(`Answer missing for question "${key}"`, { "question.id": args.correlationId });
-		await tx.update(pendingQuestions).set({
-			status: "answered",
-			answeredAt: /* @__PURE__ */ new Date()
-		}).where(eq(pendingQuestions.id, args.correlationId));
-		return row;
-	});
-	const answerContent = {
-		correlationId: args.correlationId,
-		answers: args.answers
-	};
-	questionAnswerMessageContentSchema.parse(answerContent);
-	let result;
-	try {
-		result = await sendMessage(db, args.chatId, args.submitterAgentId, {
-			format: "question_answer",
-			content: answerContent,
-			inReplyTo: questionRow.messageId,
-			source: "hub_ui"
-		});
-	} catch (err) {
-		log$1.error({
-			correlationId: args.correlationId,
-			chatId: args.chatId,
-			err: err instanceof Error ? err.message : String(err)
-		}, "sendMessage failed after status flip; reverting pending_questions row to 'pending'");
-		try {
-			await db.update(pendingQuestions).set({
-				status: "pending",
-				answeredAt: null
-			}).where(and(eq(pendingQuestions.id, args.correlationId), eq(pendingQuestions.status, "answered")));
-		} catch (revertErr) {
-			log$1.error({
-				correlationId: args.correlationId,
-				chatId: args.chatId,
-				revertErr: revertErr instanceof Error ? revertErr.message : String(revertErr)
-			}, "revert UPDATE also failed; row may be stranded as 'answered' without an answer message");
-		}
-		throw err;
+async function joinChat(db, chatId, memberId, humanAgentId) {
+	const chat = await getChat(db, chatId);
+	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) => {
+		if (wouldUpgradeToGroup(participantAgentIds.length, 1)) await changeChatType(tx, chatId, "group");
+		await addChatParticipants(tx, chatId, [{
+			agentId: humanAgentId,
+			role: "member"
+		}], {
+			assertHuman: true,
+			upgradeWatcherToSpeaker: true
+		});
+		await recomputeChatWatchers(tx, chatId);
+	});
+	invalidateChatAudience(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.
+* Only allowed if the human agent is a participant.
+*
+* Delegates the participant→watcher transition to `leaveAsParticipant`
+* so admin-side and `/me/chats/:id/leave` share one canonical path. The
+* earlier "recompute then UPDATE-back state" variant violated the design
+* rule that recompute is only for set rebuild — never on a transition
+* path (review #228 issue #2). The returned participant list is fetched
+* after the tx commits, matching the admin route's existing contract.
+*/
+async function leaveChat(db, chatId, humanAgentId) {
+	await leaveAsParticipant(db, chatId, humanAgentId);
+	invalidateChatAudience(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({
+		uuid: agents.uuid,
+		organizationId: agents.organizationId,
+		type: agents.type,
+		visibility: agents.visibility,
+		managerId: agents.managerId
+	}).from(agents).where(inArray(agents.uuid, [agentAId, agentBId]));
+	const agentA = ends.find((a) => a.uuid === agentAId);
+	if (!agentA) throw new NotFoundError(`Agent "${agentAId}" not found`);
+	const agentB = ends.find((a) => a.uuid === 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 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];
 	}
-	if (notifier) notifyRecipients(notifier, result.recipients, result.message.id);
+	if ((agentA.visibility === AGENT_VISIBILITY.PRIVATE || agentB.visibility === AGENT_VISIBILITY.PRIVATE) && agentA.managerId !== agentB.managerId) throw new ForbiddenError(`Cannot open a direct chat with a private agent across owners: "${agentAId}" ↔ "${agentBId}"`);
+	const chatId = randomUUID();
+	return db.transaction(async (tx) => {
+		const [chat] = await tx.insert(chats).values({
+			id: chatId,
+			organizationId: orgId,
+			type: "direct"
+		}).returning();
+		await addChatParticipants(tx, chatId, [{
+			agentId: agentAId,
+			role: "member"
+		}, {
+			agentId: agentBId,
+			role: "member"
+		}]);
+		await recomputeChatWatchers(tx, chatId);
+		if (!chat) throw new Error("Unexpected: INSERT RETURNING produced no row");
+		return chat;
+	});
+}
+/** Server instance heartbeat. Used to detect crashed instances and clean up associated agent_presence records. */
+const serverInstances = pgTable("server_instances", {
+	instanceId: text("instance_id").primaryKey(),
+	lastHeartbeat: timestamp("last_heartbeat", { withTimezone: true }).notNull().defaultNow()
+});
+/** Common field reset when agent goes offline or is unbound. */
+function runtimeFieldsReset(now) {
 	return {
-		messageId: result.message.id,
-		recipients: result.recipients
+		runtimeState: null,
+		activeSessions: null,
+		totalSessions: null,
+		runtimeUpdatedAt: now,
+		lastSeenAt: now
 	};
 }
-/**
-* Mark every pending row whose chat is `chatId` as superseded. Used when a
-* chat session is archived — the agent runtime that emitted the question
-* may already be gone, so leaving the row pending would block forever.
-*/
-async function markSupersededByChat(tx, chatId, reason = "chat_archived") {
-	return (await tx.update(pendingQuestions).set({
-		status: "superseded",
-		supersededAt: /* @__PURE__ */ new Date(),
-		supersededReason: reason
-	}).where(and(eq(pendingQuestions.chatId, chatId), eq(pendingQuestions.status, "pending"))).returning({ id: pendingQuestions.id })).length;
+async function setOffline(db, agentId) {
+	const now = /* @__PURE__ */ new Date();
+	await db.update(agentPresence).set({
+		status: "offline",
+		instanceId: null,
+		...runtimeFieldsReset(now)
+	}).where(eq(agentPresence.agentId, agentId));
 }
-/**
-* Mark every pending row owned by any of `agentIds` as superseded. Used when
-* the client carrying these agents is claimed by a new user — the previous
-* owner's runtime is detached and cannot deliver an answer back.
-*/
-async function markSupersededByAgents(tx, agentIds, reason = "client_claimed") {
-	if (agentIds.length === 0) return 0;
-	return (await tx.update(pendingQuestions).set({
-		status: "superseded",
-		supersededAt: /* @__PURE__ */ new Date(),
-		supersededReason: reason
-	}).where(and(inArray(pendingQuestions.agentId, agentIds), eq(pendingQuestions.status, "pending"))).returning({ id: pendingQuestions.id })).length;
+async function getPresence(db, agentId) {
+	const [row] = await db.select().from(agentPresence).where(eq(agentPresence.agentId, agentId)).limit(1);
+	return row ?? null;
 }
-const log = createLogger("message");
-async function sendMessage(db, chatId, senderId, data, options = {}) {
-	return withSpan("inbox.enqueue", messageAttrs({
-		chatId,
-		senderAgentId: senderId,
-		source: data.source ?? void 0
-	}), () => sendMessageInner(db, chatId, senderId, data, options));
+async function getOnlineCount(db) {
+	const [result] = await db.select({ count: sql`count(*)::int` }).from(agentPresence).where(eq(agentPresence.status, "online"));
+	return result?.count ?? 0;
 }
-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: chatMembership.agentId,
-				inboxId: agents.inboxId,
-				mode: chatMembership.mode,
-				name: agents.name
-			}).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,
-				organizationId: agents.organizationId,
-				type: agents.type
-			}).from(agents).where(eq(agents.uuid, senderId)).limit(1)
-		]);
-		const chatType = chatRow?.type ?? null;
-		if (!senderRow) throw new NotFoundError(`Sender agent "${senderId}" not found`);
-		let effectiveContent = data.content;
-		if (senderRow.type !== "human" && typeof effectiveContent === "string") {
-			const unwrapped = maybeUnwrapDoubleEncoded(effectiveContent);
-			if (unwrapped !== null) {
-				log.warn({
-					metric: "double_encoded_content_unwrapped_total",
-					chatId,
-					senderId
-				}, "agent sent JSON-encoded string content — unwrapping to restore markdown rendering");
-				effectiveContent = unwrapped;
-			}
-		}
-		if (data.replyToInbox !== void 0 && data.replyToInbox !== null) {
-			if (senderRow.inboxId !== data.replyToInbox) throw new BadRequestError("replyToInbox must reference the sender's own inbox");
-		}
-		const incomingMeta = data.metadata ?? {};
-		const explicitMentionsRaw = incomingMeta.mentions;
-		const explicitMentions = Array.isArray(explicitMentionsRaw) ? explicitMentionsRaw.filter((m) => typeof m === "string") : [];
-		const contentText = typeof effectiveContent === "string" ? effectiveContent : "";
-		const resolved = contentText ? extractMentions(contentText, participants) : [];
-		const mergedMentions = [...new Set([...explicitMentions, ...resolved])];
-		const metadataToStore = mergedMentions.length > 0 ? {
-			...incomingMeta,
-			mentions: mergedMentions
-		} : incomingMeta;
-		const dmAutoProjection = chatType === "direct" ? [...new Set([...mergedMentions, ...participants.filter((p) => p.agentId !== senderId).map((p) => p.agentId)])] : mergedMentions;
-		if (options.enforceGroupMention && chatType === "group") {
-			if (mergedMentions.filter((id) => id !== senderId).length === 0) throw new BadRequestError("Sending to a group chat requires an explicit @mention. Use `first-tree-hub chat send <name>` to message a single agent, or @<name> in the content to address one or more group members.");
-		}
-		let outboundContent = effectiveContent;
-		if (options.normalizeMentionsInContent && typeof outboundContent === "string") {
-			const present = new Set(scanMentionTokens(outboundContent));
-			const missingNames = [];
-			for (const id of mergedMentions) {
-				if (id === senderId) continue;
-				const p = participants.find((q) => q.agentId === id);
-				if (!p?.name) continue;
-				if (present.has(p.name.toLowerCase())) continue;
-				missingNames.push(p.name);
-			}
-			if (missingNames.length > 0) {
-				const prefix = missingNames.map((n) => `@${n}`).join(" ");
-				outboundContent = outboundContent.length > 0 ? `${prefix} ${outboundContent}` : prefix;
-			}
-		}
-		if (data.format === "question") await assertSenderMayEmitQuestion(tx, senderId);
-		const isSilentSend = typeof outboundContent === "string" && outboundContent.replace(/^(@\S+\s*)+/, "").trim().length === 0;
-		if (isSilentSend) log.info({
-			chatId,
-			senderId,
-			source: data.source ?? null
-		}, "silent send: empty content after mention strip — no fan-out wake-up");
-		const projectionMentions = isSilentSend ? [] : dmAutoProjection;
-		const messageId = randomUUID();
-		const [msg] = await tx.insert(messages).values({
-			id: messageId,
-			chatId,
-			senderId,
-			format: data.format,
-			content: outboundContent,
-			metadata: metadataToStore,
-			replyToInbox: data.replyToInbox ?? null,
-			replyToChat: data.replyToChat ?? null,
-			inReplyTo: data.inReplyTo ?? null,
-			source: data.source ?? null
-		}).returning();
-		if (data.format === "question" && msg) await recordPendingQuestionFromMessage(tx, {
-			agentId: senderId,
-			chatId,
-			messageId: msg.id,
-			content: outboundContent
-		});
-		const mentionSet = new Set(mergedMentions);
-		const fanout = participants.filter((p) => p.agentId !== senderId).map((p) => ({
-			agentId: p.agentId,
-			inboxId: p.inboxId,
-			notify: !isSilentSend && (p.mode !== "mention_only" || mentionSet.has(p.agentId))
-		}));
-		if (fanout.length > 0) await tx.insert(inboxEntries).values(fanout.map((f) => ({
-			inboxId: f.inboxId,
-			messageId,
-			chatId,
-			notify: f.notify
-		})));
-		const notified = fanout.filter((f) => f.notify);
-		const recipients = notified.map((f) => f.inboxId);
-		const recipientAgentIds = notified.map((f) => f.agentId);
-		if (data.inReplyTo) {
-			const [original] = await tx.select({
-				replyToInbox: messages.replyToInbox,
-				replyToChat: messages.replyToChat
-			}).from(messages).where(eq(messages.id, data.inReplyTo)).limit(1);
-			if (original?.replyToInbox && original?.replyToChat) {
-				await tx.insert(inboxEntries).values({
-					inboxId: original.replyToInbox,
-					messageId,
-					chatId: original.replyToChat,
-					notify: !isSilentSend
-				}).onConflictDoNothing();
-				if (!isSilentSend && !recipients.includes(original.replyToInbox)) recipients.push(original.replyToInbox);
-			}
+async function bindAgent(db, agentId, data) {
+	const now = /* @__PURE__ */ new Date();
+	await db.insert(agentPresence).values({
+		agentId,
+		status: "online",
+		instanceId: data.instanceId,
+		clientId: data.clientId,
+		runtimeType: data.runtimeType,
+		runtimeVersion: data.runtimeVersion ?? null,
+		runtimeState: "idle",
+		connectedAt: now,
+		lastSeenAt: now,
+		runtimeUpdatedAt: now
+	}).onConflictDoUpdate({
+		target: agentPresence.agentId,
+		set: {
+			status: "online",
+			instanceId: data.instanceId,
+			clientId: data.clientId,
+			runtimeType: data.runtimeType,
+			runtimeVersion: data.runtimeVersion ?? null,
+			runtimeState: "idle",
+			activeSessions: null,
+			totalSessions: null,
+			connectedAt: now,
+			lastSeenAt: now,
+			runtimeUpdatedAt: now
 		}
-		await tx.update(chats).set({ updatedAt: /* @__PURE__ */ new Date() }).where(eq(chats.id, chatId));
-		if (!msg) throw new Error("Unexpected: INSERT RETURNING produced no row");
-		const previewText = typeof outboundContent === "string" ? outboundContent.trim() : "";
-		await applyAfterFanOut(tx, {
-			chatId,
-			messageId: msg.id,
-			senderId,
-			mentionedAgentIds: projectionMentions,
-			contentPreview: previewText,
-			messageCreatedAt: msg.createdAt
-		});
-		return {
-			message: msg,
-			recipients,
-			recipientAgentIds,
-			organizationId: senderRow.organizationId
-		};
-	});
-	const settled = await Promise.allSettled(txResult.recipientAgentIds.map((agentId) => upsertSessionState(db, agentId, chatId, "active", txResult.organizationId, void 0, { touchPresenceLastSeen: false })));
-	for (let i = 0; i < settled.length; i++) {
-		const r = settled[i];
-		if (r?.status === "rejected") log.error({
-			err: r.reason,
-			chatId,
-			agentId: txResult.recipientAgentIds[i]
-		}, "predictive session activation failed");
-	}
-	fireChatMessageKick(chatId, txResult.message.id);
-	observeLoopPattern(db, chatId).catch((err) => {
-		log.error({
-			err,
-			chatId
-		}, "loop pattern observation failed");
 	});
-	return {
-		message: txResult.message,
-		recipients: txResult.recipients
-	};
 }
-/**
-* Detect agent-sent content that was JSON.stringify-ed once before reaching
-* the CLI / API. The bad shape is an outer `"..."` wrapper + interior `\n` /
-* `\"` escape sequences, which the UI renders as a quoted literal instead of
-* markdown (issue #389). Returns the unwrapped inner string on a confident
-* match, or `null` to leave the content alone.
-*
-* Match conditions (all required) — kept strict so legitimate human content
-* that happens to look like a quoted phrase is never touched. The caller is
-* additionally responsible for restricting this to non-human senders.
+async function unbindAgent(db, agentId) {
+	const now = /* @__PURE__ */ new Date();
+	await db.update(agentPresence).set({
+		status: "offline",
+		clientId: null,
+		...runtimeFieldsReset(now)
+	}).where(eq(agentPresence.agentId, agentId));
+}
+/** Set runtime state directly from client-reported value.
 *
-*   - first and last char are `"`
-*   - body contains at least one typical JSON escape sequence
-*     (`\n`, `\r`, `\t`, `\"`, or `\\`)
-*   - `JSON.parse` succeeds
-*   - the parse result is a `string` (excludes `{...}`, `[...]`, numbers)
-*/
-function maybeUnwrapDoubleEncoded(content) {
-	if (content.length < 4) return null;
-	if (content.charCodeAt(0) !== 34) return null;
-	if (content.charCodeAt(content.length - 1) !== 34) return null;
-	if (!/\\[nrt"\\]/.test(content)) return null;
-	try {
-		const parsed = JSON.parse(content);
-		return typeof parsed === "string" ? parsed : null;
-	} catch {
-		return null;
-	}
+* When an org-scoped notifier is provided, emit a PG NOTIFY on the
+* `runtime_state_changes` channel so the pulse aggregator (and any future
+* admin-side consumers) can observe the transition. Fire-and-forget to match
+* notifier semantics elsewhere in this module. */
+async function setRuntimeState(db, agentId, runtimeState, options) {
+	const now = /* @__PURE__ */ new Date();
+	await db.update(agentPresence).set({
+		runtimeState,
+		runtimeUpdatedAt: now,
+		lastSeenAt: now
+	}).where(eq(agentPresence.agentId, agentId));
+	if (options?.notifier && options.organizationId) options.notifier.notifyRuntimeStateChange(agentId, runtimeState, options.organizationId).catch(() => {});
 }
-function stripMentionPrefix(content) {
-	return content.replace(/^(@\S+\s*)+/, "").trim();
+/** Touch agent last_seen_at on heartbeat (per-agent liveness). */
+async function touchAgent(db, agentId) {
+	await db.update(agentPresence).set({ lastSeenAt: /* @__PURE__ */ new Date() }).where(eq(agentPresence.agentId, agentId));
+}
+async function heartbeatInstance(db, instanceId) {
+	await db.insert(serverInstances).values({
+		instanceId,
+		lastHeartbeat: /* @__PURE__ */ new Date()
+	}).onConflictDoUpdate({
+		target: serverInstances.instanceId,
+		set: { lastHeartbeat: /* @__PURE__ */ new Date() }
+	});
 }
-const defaultLoopObserver = (data) => {
-	log.warn({
-		metric: "loop_pattern_observed_total",
-		...data
-	}, "loop pattern observed (not blocked) — prompt discipline may be drifting");
-};
 /**
-* Pure observation: detect short, fast, two-agent ping-pong reply chains and
-* surface them via a structured log line. Does NOT modify the `notify` flag
-* or otherwise interfere with delivery — loop *prevention* lives client-side
-* (prompt + silent-turn protocol in `result-sink`). Six conjunctive
-* conditions (see design `agent-reply-loop-prevention-design.md` §3.4) so
-* normal multi-agent collaboration is never flagged:
-*
-*   C1 — every message is `format=text`
-*   C2 — no human sender in the window (any human reply resets the chain)
-*   C3 — exactly two senders, perfectly alternating
-*   C4 — strict `inReplyTo` chain across the whole window
-*   C5 — every message body (after stripping leading `@<name>` tokens) is
-*        ≤ `LOOP_OBSERVATION_SHORT_CHARS` characters
-*   C6 — the whole window spans ≤ `LOOP_OBSERVATION_TIME_WINDOW_MS` ms
+* M1: Mark agents as offline whose last_seen_at is older than staleSeconds.
+* Unlike cleanupStalePresence (which checks instance liveness), this checks
+* per-agent heartbeat liveness — detecting agents that stopped heartbeating
+* while the client process may still be alive.
 *
-* Exported for direct test coverage of the detection logic; the `sendMessage`
-* call site uses the default observer.
+* Returns the list of agent IDs that were marked stale (for notification in Step 6).
 */
-async function observeLoopPattern(db, chatId, observer = defaultLoopObserver) {
-	const window = await db.select({
-		id: messages.id,
-		senderId: messages.senderId,
-		content: messages.content,
-		inReplyTo: messages.inReplyTo,
-		createdAt: messages.createdAt,
-		format: messages.format,
-		senderType: agents.type
-	}).from(messages).innerJoin(agents, eq(messages.senderId, agents.uuid)).where(eq(messages.chatId, chatId)).orderBy(desc(messages.createdAt)).limit(4);
-	if (window.length < 4) return;
-	if (window.some((m) => m.format !== "text")) return;
-	if (window.some((m) => m.senderType === "human")) return;
-	if (new Set(window.map((m) => m.senderId)).size !== 2) return;
-	for (let i = 0; i < window.length - 1; i++) if (window[i]?.senderId === window[i + 1]?.senderId) return;
-	for (let i = 0; i < window.length - 1; i++) if (window[i]?.inReplyTo !== window[i + 1]?.id) return;
-	const lens = [];
-	for (const m of window) {
-		const text = typeof m.content === "string" ? m.content : null;
-		if (text === null) return;
-		const len = stripMentionPrefix(text).length;
-		if (len > 10) return;
-		lens.push(len);
-	}
-	const newest = window[0];
-	const oldest = window[window.length - 1];
-	if (!newest || !oldest) return;
-	const spanMs = newest.createdAt.getTime() - oldest.createdAt.getTime();
-	if (spanMs > 3e4) return;
-	observer({
-		chatId,
-		recentMessageIds: window.map((m) => m.id),
-		windowSpanMs: spanMs,
-		contentLengths: lens
-	});
-}
-async function sendToAgent(db, senderUuid, targetName, data) {
-	const [sender] = await db.select({
-		uuid: agents.uuid,
-		organizationId: agents.organizationId
-	}).from(agents).where(eq(agents.uuid, senderUuid)).limit(1);
-	if (!sender) throw new NotFoundError(`Agent "${senderUuid}" not found`);
-	const [target] = await db.select({ uuid: agents.uuid }).from(agents).where(and(eq(agents.organizationId, sender.organizationId), eq(agents.name, targetName), ne(agents.status, "deleted"))).limit(1);
-	if (!target) throw new NotFoundError(`Agent "${targetName}" not found${/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(targetName) ? " — `first-tree-hub chat send` expects an agent NAME, not a uuid. Run `first-tree-hub agent list` to see available names." : ""}`);
-	const incomingMeta = data.metadata ?? {};
-	const existingMentionsRaw = incomingMeta.mentions;
-	const existingMentions = Array.isArray(existingMentionsRaw) ? existingMentionsRaw.filter((m) => typeof m === "string") : [];
-	const mergedMentions = existingMentions.includes(target.uuid) ? existingMentions : [...existingMentions, target.uuid];
-	const metadata = {
-		...incomingMeta,
-		mentions: mergedMentions
-	};
-	if (data.replyToChat) {
-		const [targetIsMember, senderIsMember] = await Promise.all([isParticipant(db, data.replyToChat, target.uuid), isParticipant(db, data.replyToChat, senderUuid)]);
-		if (targetIsMember && senderIsMember) return sendMessage(db, data.replyToChat, senderUuid, {
-			format: data.format,
-			content: data.content,
-			metadata,
-			replyToInbox: void 0,
-			replyToChat: void 0,
-			source: data.source
-		}, { normalizeMentionsInContent: true });
-	}
-	return sendMessage(db, (await findOrCreateDirectChat(db, senderUuid, target.uuid)).id, senderUuid, {
-		format: data.format,
-		content: data.content,
-		metadata,
-		replyToInbox: data.replyToInbox,
-		replyToChat: data.replyToChat,
-		source: data.source
-	}, { normalizeMentionsInContent: true });
-}
-async function editMessage(db, chatId, messageId, senderId, data) {
-	const [msg] = await db.select().from(messages).where(eq(messages.id, messageId)).limit(1);
-	if (!msg) throw new NotFoundError(`Message "${messageId}" not found`);
-	if (msg.chatId !== chatId) throw new NotFoundError(`Message "${messageId}" not found in this chat`);
-	if (msg.senderId !== senderId) throw new ForbiddenError("Only the sender can edit a message");
-	const setClause = {};
-	if (data.format !== void 0) setClause.format = data.format;
-	if (data.content !== void 0) setClause.content = data.content;
-	const meta = msg.metadata ?? {};
-	meta.editedAt = (/* @__PURE__ */ new Date()).toISOString();
-	setClause.metadata = meta;
-	const [updated] = await db.update(messages).set(setClause).where(eq(messages.id, messageId)).returning();
-	if (!updated) throw new Error("Unexpected: UPDATE RETURNING produced no row");
-	return updated;
+async function markStaleAgents(db, staleSeconds = 60) {
+	return (await db.execute(sql`
+    UPDATE agent_presence SET
+      status = 'offline',
+      client_id = NULL,
+      runtime_state = NULL,
+      active_sessions = NULL,
+      total_sessions = NULL,
+      runtime_updated_at = NOW()
+    WHERE status = 'online'
+    AND last_seen_at < NOW() - make_interval(secs => ${staleSeconds})
+    RETURNING agent_id
+  `)).map((r) => r.agent_id);
 }
-async function listMessages(db, chatId, limit, cursor) {
-	const where = cursor ? and(eq(messages.chatId, chatId), lt(messages.createdAt, new Date(cursor))) : eq(messages.chatId, chatId);
-	const rows = await db.select().from(messages).where(where).orderBy(desc(messages.createdAt)).limit(limit + 1);
-	const hasMore = rows.length > limit;
-	const items = hasMore ? rows.slice(0, limit) : rows;
-	const last = items[items.length - 1];
-	return {
-		items,
-		nextCursor: hasMore && last ? last.createdAt.toISOString() : null
-	};
+async function cleanupStalePresence(db, staleSeconds = 60) {
+	return (await db.execute(sql`
+    UPDATE agent_presence SET status = 'offline', instance_id = NULL,
+      runtime_state = NULL,
+      active_sessions = NULL, total_sessions = NULL,
+      runtime_updated_at = NOW()
+    WHERE instance_id IN (
+      SELECT instance_id FROM server_instances
+      WHERE last_heartbeat < NOW() - make_interval(secs => ${staleSeconds})
+    )
+    AND status = 'online'
+    RETURNING agent_id
+  `)).length;
 }
 /**
 * Assert the caller can act on this client. Throws 404 for both "not found"
@@ -2381,4 +4210,4 @@ async function cleanupStaleClients(db, staleSeconds = 60) {
 	return result.length;
 }
 //#endregion
-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 };
+export { getSession as $, suspendSession as $t, createAgent as A, pollInbox as At, extractSummary as B, resetTimedOutEntries as Bt, claimAndBuildForPush as C, markMeChatRead as Ct, cleanupStalePresence as D, messages as Dt, cleanupStaleClients as E, members as Et, deriveAuthState as F, registerChatMessageDispatcher as Ft, getAgentAvatarImage as G, sendToAgent as Gt, findOrCreateDirectChat as H, resolveDefaultOrgId as Ht, disconnectClient as I, registerClient as It, getChatDetail as J, setChatEngagement as Jt, getCachedAudience as K, serverInstances as Kt, editMessage as L, removeParticipant as Lt, createMeChat as M, reactivateAgent as Mt, createNotifier as N, rebindAgent as Nt, clearAgentAvatarImage as O, notifyRecipients as Ot, deleteAgent as P, recomputeWatchersForMember as Pt, getPresence as Q, suspendAgent as Qt, ensureDefaultOrganization as R, renewEntry as Rt, checkAgentNameAvailability as S, listMyPinnedAgents as St, claimClient as T, markStaleAgents as Tt, getActivityOverview as U, retireClient as Ut, filterSessionsByParticipant as V, resolveChatTitle as Vt, getAgent as W, sendMessage as Wt, getOnlineCount as X, setRuntimeState as Xt, getClient as Y, setOffline as Yt, getOrganization as Z, submitAnswer as Zt, assertParticipant as _, listClients as _t, adapterAgentMappings as a, upsertSessionState as an, leaveChat as at, chatUserState as b, listMeChats as bt, addMeChatParticipants as c, listAgentSessions as ct, agentChatSessions as d, listAgentsManagedByUser as dt, touchAgent as en, heartbeatClient as et, agentConfigs as f, listAgentsWithRuntime as ft, assertClientOwner as g, listChatsForMember as gt, archiveSession as h, listChats as ht, ackEntryByIdForBoundAgents as i, updateOrganization as in, joinMeChat as it, createChat as j, pruneStaleSilentEntries as jt, clients as k, pendingQuestions as kt, addParticipant as l, listAgentsForAdmin as lt, agents as m, listChatParticipantsWithNames as mt, SUPPORTED_AVATAR_IMAGE_MIMES as n, updateAgent as nn, inboxEntries as nt, adapterConfigs as o, leaveMeChat as ot, agentPresence as p, listAllSessions as pt, getCallerEngagement as q, setAgentAvatarImage as qt, ackEntry as r, updateClientCapabilities as rn, joinChat as rt, addChatParticipants as s, listActiveAgentsPinnedToClient as st, MAX_AVATAR_IMAGE_BYTES as t, unbindAgent as tn, heartbeatInstance as tt, agentAvatarImageUrl as u, listAgentsForMember as ut, bindAgent as v, listClientsForOrgAdmin as vt, claimBacklogForPush as w, markMeChatUnread as wt, chats as x, listMessages as xt, chatMembership as y, listMeChatSourceCounts as yt, ensureParticipant as z, resetActivity as zt };