@botcord/daemon 0.2.4 → 0.2.6

package/dist/gateway/dispatcher.js

@@ -1,6 +1,42 @@
+import { randomUUID } from "node:crypto";
 import { resolveRoute } from "./router.js";
 import { sessionKey } from "./session-store.js";
+import { truncateTextField, } from "./transcript.js";
 const DEFAULT_TURN_TIMEOUT_MS = 10 * 60 * 1000;
+/**
+ * Owner-chat room prefix. Reply-text gating: only rooms with this prefix get
+ * `result.text` forwarded to the channel; in every other room the runtime's
+ * plain text output is discarded — agents must use the `botcord_send` tool
+ * (or `botcord send` CLI via Bash) to actually deliver replies.
+ */
+const OWNER_CHAT_ROOM_PREFIX = "rm_oc_";
+/** Maximum number of buffered serial entries per queue. Excess entries drop oldest. */
+const MAX_BATCH_BUFFER_ENTRIES = 40;
+/**
+ * Soft cap on the total characters across raw.batch members in a merged
+ * turn. When exceeded, oldest entries are dropped (with a warn log) so the
+ * runtime prompt stays bounded even if the channel-side batch was huge.
+ */
+const MAX_BATCH_BUFFER_CHARS = 16000;
+/**
+ * Reason carried on `AbortController.abort()` when a cancel-previous wave
+ * is taking over the slot. Distinguishing this from a timeout abort lets
+ * `runTurn`'s finalize know NOT to write a `turn_error` — the supersede
+ * path already wrote a `dropped` record for the old turnId before the abort.
+ */
+class TurnSupersededError extends Error {
+    supersededBy;
+    constructor(supersededBy) {
+        super("turn superseded");
+        this.supersededBy = supersededBy;
+        this.name = "TurnSupersededError";
+    }
+}
+const NOOP_TRANSCRIPT = {
+    enabled: false,
+    rootDir: "",
+    write: () => { },
+};
 /**
  * Gateway dispatcher: consumes `GatewayInboundEnvelope` and drives a runtime
  * turn per message, respecting queue mode, trust level, streaming, and
@@ -23,6 +59,9 @@ export class Dispatcher {
     onOutbound;
     composeUserTurn;
     managedRoutes;
+    attentionGate;
+    resolveHubUrl;
+    transcript;
     queues = new Map();
     constructor(opts) {
         this.config = opts.config;
@@ -36,18 +75,28 @@ export class Dispatcher {
         this.onOutbound = opts.onOutbound;
         this.composeUserTurn = opts.composeUserTurn;
         this.managedRoutes = opts.managedRoutes;
+        this.attentionGate = opts.attentionGate;
+        this.resolveHubUrl = opts.resolveHubUrl;
+        this.transcript = opts.transcript ?? NOOP_TRANSCRIPT;
     }
     /** Consume one inbound envelope, ack it once ownership is decided, then run its turn. */
     async handle(envelope) {
         const msg = envelope.message;
-        // Skip rule: empty/whitespace text.
-        const rawText = typeof msg.text === "string" ? msg.text.trim() : "";
-        if (!rawText) {
-            this.log.debug("dispatcher skip: empty text", { messageId: msg.id });
+        // ---- Pre-skip branches: NEVER write a transcript record (design §3.2).
+        // Order matters: unknown channel → own echo → empty text. Each ack's the
+        // envelope (when applicable) and returns silently with only a debug/warn
+        // line in the daemon log.
+        // Pre-skip: unknown channel — configuration error, not a conversation event.
+        const channel = this.channels.get(msg.channel);
+        if (!channel) {
+            this.log.warn("dispatcher: unknown channel for outbound reply", {
+                channel: msg.channel,
+                messageId: msg.id,
+            });
             await this.safeAck(envelope);
             return;
         }
-        // Skip rule: echo from the agent itself (own agent output looped back).
+        // Pre-skip: echo from the agent itself (own agent output looped back).
         // Owner/human messages in dashboard rooms share the agent's id as sender.id
         // but carry sender.kind === "user", so we only skip when kind === "agent".
         if (msg.sender.id === msg.accountId && msg.sender.kind === "agent") {
@@ -55,12 +104,28 @@ export class Dispatcher {
             await this.safeAck(envelope);
             return;
         }
-        // Compose the final user-turn text. The composer can enrich the raw
-        // message with sender label, room header, NO_REPLY hint, etc. — anything
-        // that should land in the runtime transcript. Failures fall back to the
-        // raw trimmed text so a buggy composer cannot drop turns.
+        // Pre-skip: empty/whitespace text.
+        const rawText = typeof msg.text === "string" ? msg.text.trim() : "";
+        if (!rawText) {
+            this.log.debug("dispatcher skip: empty text", { messageId: msg.id });
+            await this.safeAck(envelope);
+            return;
+        }
+        // From here on, the inbound is a real conversation event — generate a
+        // turnId and write the inbound transcript record.
+        const turnId = randomUUID();
+        const managed = this.managedRoutes ? Array.from(this.managedRoutes.values()) : undefined;
+        const route = resolveRoute(msg, this.config, managed);
+        const mode = resolveQueueMode(route, msg.conversation.kind);
+        const queueKey = buildQueueKey(msg);
+        // Compose the final user-turn text only for cancel-previous mode, where
+        // the dispatcher consumes the pre-composed text directly. Serial mode
+        // re-runs the composer at drain time on the merged message (so it sees
+        // the full coalesced batch instead of any single arrival), so calling
+        // the composer here would just be redundant work.
         let text = rawText;
-        if (this.composeUserTurn) {
+        let composeFailedError;
+        if (mode === "cancel-previous" && this.composeUserTurn) {
             try {
                 const composed = this.composeUserTurn(msg);
                 if (typeof composed === "string" && composed.length > 0) {
@@ -68,18 +133,18 @@ export class Dispatcher {
                 }
             }
             catch (err) {
+                composeFailedError = err instanceof Error ? err.message : String(err);
                 this.log.warn("dispatcher: composeUserTurn threw — using raw text", {
                     messageId: msg.id,
-                    error: err instanceof Error ? err.message : String(err),
+                    error: composeFailedError,
                 });
             }
         }
-        const managed = this.managedRoutes ? Array.from(this.managedRoutes.values()) : undefined;
-        const route = resolveRoute(msg, this.config, managed);
-        const mode = resolveQueueMode(route, msg.conversation.kind);
-        const queueKey = buildQueueKey(msg);
         // Ack immediately: once the dispatcher has a route + queue key, ownership is decided.
         await this.safeAck(envelope);
+        // Inbound transcript record — always before observers / gates so we have a
+        // grounded turnId for any downstream attention_skipped / dropped / etc.
+        this.emitInbound(turnId, msg);
         // Notify the optional observer (activity tracking, metrics, etc.) as soon
         // as the dispatcher owns the message. Errors must not abort the turn.
         if (this.onInbound) {
@@ -93,19 +158,58 @@ export class Dispatcher {
                 });
             }
         }
-        const channel = this.channels.get(msg.channel);
-        if (!channel) {
-            this.log.warn("dispatcher: unknown channel for outbound reply", {
-                channel: msg.channel,
-                messageId: msg.id,
+        // Attention gate (PR3, design §4.2). Inserted AFTER `onInbound` so the
+        // working-memory append + activity tracking still see the message — only
+        // the runtime turn is suppressed. Errors are treated as wake (fail-open)
+        // so a buggy gate cannot silence the agent.
+        if (this.attentionGate) {
+            let wake = true;
+            try {
+                const result = this.attentionGate(msg);
+                wake = result instanceof Promise ? await result : result;
+            }
+            catch (err) {
+                this.log.warn("dispatcher: attentionGate threw — waking", {
+                    messageId: msg.id,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+                wake = true;
+            }
+            if (!wake) {
+                this.log.debug("dispatcher skip turn: attention policy", {
+                    messageId: msg.id,
+                    accountId: msg.accountId,
+                    conversationId: msg.conversation.id,
+                });
+                this.transcript.write({
+                    ts: nowIso(),
+                    kind: "attention_skipped",
+                    turnId,
+                    agentId: msg.accountId,
+                    roomId: msg.conversation.id,
+                    topicId: msg.conversation.threadId ?? null,
+                    reason: "attention_gate_false",
+                });
+                return;
+            }
+        }
+        if (composeFailedError) {
+            this.transcript.write({
+                ts: nowIso(),
+                kind: "compose_failed",
+                turnId,
+                agentId: msg.accountId,
+                roomId: msg.conversation.id,
+                topicId: msg.conversation.threadId ?? null,
+                error: composeFailedError,
+                fallback: "raw_text",
             });
-            return;
         }
         if (mode === "cancel-previous") {
-            await this.runCancelPrevious(queueKey, route, text, msg, channel);
+            await this.runCancelPrevious(queueKey, route, text, msg, channel, turnId);
         }
         else {
-            await this.runSerial(queueKey, route, text, msg, channel);
+            await this.runSerial(queueKey, route, text, msg, channel, turnId);
         }
     }
     /** Snapshot of currently running turns keyed by queue key. */
@@ -139,14 +243,15 @@ export class Dispatcher {
         if (!q) {
             q = {
                 current: null,
-                tail: Promise.resolve(),
                 cancelGen: 0,
+                serialBuffer: [],
+                serialWorkerActive: false,
             };
             this.queues.set(key, q);
         }
         return q;
     }
-    async runCancelPrevious(queueKey, route, text, msg, channel) {
+    async runCancelPrevious(queueKey, route, text, msg, channel, turnId) {
         const q = this.getQueue(queueKey);
         // Bump the generation on every arrival. Older arrivals still awaiting
         // the prior turn's teardown will observe `myGen !== q.cancelGen` when
@@ -156,7 +261,19 @@ export class Dispatcher {
         const prev = q.current;
         if (prev) {
             this.log.info("dispatcher: cancelling previous turn", { queueKey });
-            prev.controller.abort();
+            // Record the supersede BEFORE aborting so the prev turn's finalize sees
+            // the abort reason (TurnSupersededError) and skips writing turn_error.
+            this.transcript.write({
+                ts: nowIso(),
+                kind: "dropped",
+                turnId: prev.turnId,
+                agentId: msg.accountId,
+                roomId: msg.conversation.id,
+                topicId: msg.conversation.threadId ?? null,
+                reason: "queue_cancel_previous",
+                supersededBy: turnId,
+            });
+            prev.controller.abort(new TurnSupersededError(turnId));
             // Wait for it to finish cleanup (it won't reply, won't persist).
             await prev.done.catch(() => undefined);
         }
@@ -165,18 +282,194 @@ export class Dispatcher {
         // drop out silently — the newest turn is the only one that should run.
         if (myGen !== q.cancelGen) {
             this.log.info("dispatcher: cancel-previous superseded", { queueKey });
+            // We didn't run the turn; emit dropped so the caller's inbound has a
+            // matching path record. supersededBy is unknown at this layer (newer
+            // arrival owns its own bump) — leave null.
+            this.transcript.write({
+                ts: nowIso(),
+                kind: "dropped",
+                turnId,
+                agentId: msg.accountId,
+                roomId: msg.conversation.id,
+                topicId: msg.conversation.threadId ?? null,
+                reason: "queue_cancel_previous",
+                supersededBy: null,
+            });
             return;
         }
-        await this.runTurn(queueKey, route, text, msg, channel);
+        await this.runTurn(queueKey, route, text, msg, channel, turnId, []);
     }
-    async runSerial(queueKey, route, text, msg, channel) {
+    /**
+     * Serial mode with coalesce-on-drain semantics:
+     *
+     *   1. First arrival on an idle queue boots the worker, which dispatches a
+     *      single-message turn immediately (no batching delay).
+     *   2. Arrivals during an in-flight turn append to `serialBuffer`; when the
+     *      worker finishes the current turn it drains the entire buffer and
+     *      merges all pending entries into ONE next turn (folded into a single
+     *      `raw.batch` so the composer renders them as multi-block input).
+     *   3. Buffer caps: at most `MAX_BATCH_BUFFER_ENTRIES` entries are retained
+     *      (drop oldest) and merged turns are further trimmed to fit
+     *      `MAX_BATCH_BUFFER_CHARS` of total raw text.
+     *
+     * Note: the pre-composed `text` from `handle()` is intentionally discarded
+     * here — at drain time the worker re-invokes `composeUserTurn` on the
+     * merged message so the runtime sees a single coherent prompt covering all
+     * coalesced messages.
+     */
+    async runSerial(queueKey, route, _text, msg, channel, turnId) {
         const q = this.getQueue(queueKey);
-        const prev = q.tail;
-        const next = prev.then(() => this.runTurn(queueKey, route, text, msg, channel));
-        q.tail = next.catch(() => undefined);
-        return next;
+        q.serialBuffer.push({ route, msg, channel, turnId });
+        while (q.serialBuffer.length > MAX_BATCH_BUFFER_ENTRIES) {
+            const dropped = q.serialBuffer.shift();
+            this.log.warn("dispatcher: serial buffer overflow — dropped oldest entry", {
+                queueKey,
+                droppedMessageId: dropped.msg.id,
+                bufferCap: MAX_BATCH_BUFFER_ENTRIES,
+            });
+            this.transcript.write({
+                ts: nowIso(),
+                kind: "dropped",
+                turnId: dropped.turnId,
+                agentId: dropped.msg.accountId,
+                roomId: dropped.msg.conversation.id,
+                topicId: dropped.msg.conversation.threadId ?? null,
+                reason: "queue_overflow",
+                supersededBy: null,
+            });
+        }
+        if (q.serialWorkerActive)
+            return;
+        q.serialWorkerActive = true;
+        try {
+            while (q.serialBuffer.length > 0) {
+                const drained = q.serialBuffer.splice(0, q.serialBuffer.length);
+                const merged = this.mergeSerialBuffer(drained, queueKey);
+                if (!merged)
+                    continue;
+                // Drained entries other than the winner get a `batch_merged` dropped
+                // record now (winner is always the last entry — see mergeSerialBuffer).
+                if (drained.length > 1) {
+                    for (let i = 0; i < drained.length - 1; i++) {
+                        const lost = drained[i];
+                        this.transcript.write({
+                            ts: nowIso(),
+                            kind: "dropped",
+                            turnId: lost.turnId,
+                            agentId: lost.msg.accountId,
+                            roomId: lost.msg.conversation.id,
+                            topicId: lost.msg.conversation.threadId ?? null,
+                            reason: "batch_merged",
+                            supersededBy: merged.turnId,
+                        });
+                    }
+                }
+                const mergedFromTurnIds = drained.length > 1 ? drained.slice(0, -1).map((e) => e.turnId) : [];
+                await this.runTurn(queueKey, merged.route, merged.text, merged.msg, merged.channel, merged.turnId, mergedFromTurnIds);
+            }
+        }
+        finally {
+            q.serialWorkerActive = false;
+        }
     }
-    async runTurn(queueKey, route, text, msg, channel) {
+    /**
+     * Merge buffered serial entries into a single dispatchable unit. With one
+     * entry the call is a near no-op (just recompose). With ≥2 entries this
+     * flattens any per-entry `raw.batch` (the BotCord channel already groups
+     * one inbox-poll's worth of same-room/topic messages into a `raw.batch`),
+     * applies the `MAX_BATCH_BUFFER_CHARS` cap by dropping oldest individual
+     * messages, and then synthesizes a merged inbound message anchored on the
+     * latest entry's metadata (mentioned = OR across all entries).
+     */
+    mergeSerialBuffer(entries, queueKey) {
+        if (entries.length === 0)
+            return null;
+        if (entries.length === 1) {
+            const only = entries[0];
+            return {
+                route: only.route,
+                text: this.recomposeUserTurn(only.msg),
+                msg: only.msg,
+                channel: only.channel,
+                turnId: only.turnId,
+            };
+        }
+        // Flatten: each entry's raw may already be a BatchedInboxRaw with
+        // `.batch`; otherwise it's a single InboxMessage we treat as a 1-element
+        // batch. Insertion order preserves chronology.
+        const items = [];
+        for (const e of entries) {
+            const raw = e.msg.raw;
+            const batch = raw && Array.isArray(raw.batch)
+                ? (raw.batch)
+                : null;
+            if (batch) {
+                for (const m of batch)
+                    items.push(m);
+            }
+            else if (raw) {
+                items.push(raw);
+            }
+        }
+        // Char-cap: drop oldest until we fit. Reserve at least one item so we
+        // never produce an empty merged batch.
+        let totalChars = items.reduce((acc, m) => acc + (typeof m?.text === "string" ? m.text.length : 0), 0);
+        let droppedCount = 0;
+        while (totalChars > MAX_BATCH_BUFFER_CHARS && items.length > 1) {
+            const removed = items.shift();
+            totalChars -= typeof removed?.text === "string" ? removed.text.length : 0;
+            droppedCount += 1;
+        }
+        if (droppedCount > 0) {
+            this.log.warn("dispatcher: merged batch exceeded char cap — dropped oldest", {
+                queueKey,
+                droppedCount,
+                remaining: items.length,
+                totalChars,
+                charCap: MAX_BATCH_BUFFER_CHARS,
+            });
+        }
+        const latest = entries[entries.length - 1];
+        const latestRaw = latest.msg.raw ?? {};
+        const mergedRaw = { ...latestRaw, batch: items };
+        const anyMentioned = entries.some((e) => e.msg.mentioned === true);
+        const mergedMsg = {
+            ...latest.msg,
+            mentioned: anyMentioned,
+            raw: mergedRaw,
+        };
+        return {
+            route: latest.route,
+            text: this.recomposeUserTurn(mergedMsg),
+            msg: mergedMsg,
+            channel: latest.channel,
+            turnId: latest.turnId,
+        };
+    }
+    /**
+     * Re-run the user-turn composer at drain time. Mirrors the logic in
+     * `handle()` but operates on the (possibly merged) message. Falls back to
+     * raw trimmed text on composer failure so a buggy composer never drops a
+     * turn.
+     */
+    recomposeUserTurn(msg) {
+        const rawText = typeof msg.text === "string" ? msg.text.trim() : "";
+        if (!this.composeUserTurn)
+            return rawText;
+        try {
+            const composed = this.composeUserTurn(msg);
+            if (typeof composed === "string" && composed.length > 0)
+                return composed;
+        }
+        catch (err) {
+            this.log.warn("dispatcher: composeUserTurn (drain) threw — using raw text", {
+                messageId: msg.id,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+        return rawText;
+    }
+    async runTurn(queueKey, route, text, msg, channel, turnId, mergedFromTurnIds) {
         const q = this.getQueue(queueKey);
         const controller = new AbortController();
         const startedAt = Date.now();
@@ -193,8 +486,35 @@ export class Dispatcher {
         const done = new Promise((res) => {
             resolveDone = res;
         });
-        const slot = { controller, timedOut: false, snapshot, done };
+        const slot = {
+            turnId,
+            controller,
+            timedOut: false,
+            snapshot,
+            done,
+            dispatchedAt: startedAt,
+            blocks: [],
+        };
         q.current = slot;
+        // Dispatched record — marks "this turn entered runtime".
+        {
+            const composedField = truncateTextField(text);
+            const dispatched = {
+                ts: nowIso(),
+                kind: "dispatched",
+                turnId,
+                agentId: msg.accountId,
+                roomId: msg.conversation.id,
+                topicId: msg.conversation.threadId ?? null,
+                composedText: composedField.text,
+                runtime: route.runtime,
+            };
+            if (mergedFromTurnIds.length > 0)
+                dispatched.mergedFromTurnIds = mergedFromTurnIds;
+            if (composedField.truncated)
+                dispatched.truncated = { composedText: true };
+            this.transcript.write(dispatched);
+        }
         // Hard-cap turn with a timeout.
         const timer = setTimeout(() => {
             slot.timedOut = true;
@@ -220,8 +540,20 @@ export class Dispatcher {
         const streamable = msg.trace?.streamable === true;
         const traceId = msg.trace?.id;
         const canStream = streamable && typeof traceId === "string" && typeof channel.streamBlock === "function";
+        const recordBlock = (block) => {
+            const summary = { type: block.kind };
+            const raw = block.raw;
+            if (raw && typeof raw === "object") {
+                if (typeof raw.text === "string")
+                    summary.chars = raw.text.length;
+                if (typeof raw.name === "string")
+                    summary.name = raw.name;
+            }
+            slot.blocks.push(summary);
+        };
         const onBlock = canStream
             ? (block) => {
+                recordBlock(block);
                 // Fire-and-forget: stream errors must not break the turn.
                 channel
                     .streamBlock({
@@ -267,11 +599,13 @@ export class Dispatcher {
                     sessionId,
                     cwd: route.cwd,
                     accountId: msg.accountId,
+                    hubUrl: this.resolveHubUrl?.(msg.accountId),
                     extraArgs: route.extraArgs,
                     signal: controller.signal,
                     trustLevel,
                     systemContext,
                     onBlock,
+                    gateway: route.gateway,
                 });
             }
             catch (err) {
@@ -287,37 +621,98 @@ export class Dispatcher {
             // until after the reply lets the new arrival trip our abort signal, and
             // this check then drops us silently. Timed-out turns still fall through
             // to send their error reply.
+            //
+            // Note on transcript: the supersede path already wrote the `dropped`
+            // record from `runCancelPrevious` BEFORE aborting, so we MUST NOT also
+            // emit a `turn_error` here — that would violate the "exactly one
+            // terminal record per turnId" invariant.
             if (controller.signal.aborted && !slot.timedOut) {
                 return;
             }
+            // Reply gating: only owner-chat rooms accept the runtime's plain text
+            // output as a delivered message. Every other room expects the agent to
+            // call the `botcord_send` tool (or `botcord send` CLI via Bash)
+            // explicitly; runtime text in those rooms is logged and dropped,
+            // including timeout / error notifications.
+            //
+            // Owner-chat is identified by either the `rm_oc_` room prefix OR
+            // `source_type === "dashboard_user_chat"` on the raw envelope — the
+            // same dual check used by `sender-classify.ts:classifyActivitySender`,
+            // so the dispatcher's reply gating stays in lock-step with the
+            // composer's owner-bypass.
+            //
+            // Side effect: `onOutbound` (loop-risk tracking) only fires when a
+            // reply actually leaves the dispatcher. In non-owner-chat rooms the
+            // expectation is that the agent's `botcord_send` tool calls do their
+            // own loop-risk accounting downstream.
+            const isOwnerChat = isOwnerChatRoom(msg);
             if (slot.timedOut) {
-                await this.sendReply(channel, {
-                    channel: msg.channel,
-                    accountId: msg.accountId,
-                    conversationId: msg.conversation.id,
-                    threadId: msg.conversation.threadId ?? null,
-                    text: `⚠️ Runtime timeout after ${Math.round(this.turnTimeoutMs / 60000)} minute(s); aborted`,
-                    replyTo: msg.id,
-                    traceId: msg.trace?.id ?? null,
+                this.transcript.write({
+                    ts: nowIso(),
+                    kind: "turn_error",
+                    turnId,
+                    agentId: msg.accountId,
+                    roomId: msg.conversation.id,
+                    topicId: msg.conversation.threadId ?? null,
+                    phase: "timeout",
+                    error: `runtime timeout after ${this.turnTimeoutMs}ms`,
+                    durationMs: Date.now() - slot.dispatchedAt,
                 });
+                if (isOwnerChat) {
+                    await this.sendReply(channel, {
+                        channel: msg.channel,
+                        accountId: msg.accountId,
+                        conversationId: msg.conversation.id,
+                        threadId: msg.conversation.threadId ?? null,
+                        text: `⚠️ Runtime timeout after ${Math.round(this.turnTimeoutMs / 60000)} minute(s); aborted`,
+                        replyTo: msg.id,
+                        traceId: msg.trace?.id ?? null,
+                    });
+                }
+                else {
+                    this.log.warn("dispatcher: timeout in non-owner-chat room — error reply suppressed", {
+                        queueKey,
+                        conversationId: msg.conversation.id,
+                        timeoutMs: this.turnTimeoutMs,
+                    });
+                }
                 return;
             }
             if (threw) {
+                const errMsg = threw instanceof Error ? threw.message : String(threw);
                 this.log.error("dispatcher: runtime threw", {
                     queueKey,
                     runtime: route.runtime,
-                    error: threw instanceof Error ? threw.message : String(threw),
+                    error: errMsg,
                 });
-                const shortMsg = threw instanceof Error ? threw.message : String(threw);
-                await this.sendReply(channel, {
-                    channel: msg.channel,
-                    accountId: msg.accountId,
-                    conversationId: msg.conversation.id,
-                    threadId: msg.conversation.threadId ?? null,
-                    text: `⚠️ Runtime error: ${truncate(shortMsg, 500)}`,
-                    replyTo: msg.id,
-                    traceId: msg.trace?.id ?? null,
+                this.transcript.write({
+                    ts: nowIso(),
+                    kind: "turn_error",
+                    turnId,
+                    agentId: msg.accountId,
+                    roomId: msg.conversation.id,
+                    topicId: msg.conversation.threadId ?? null,
+                    phase: "runtime",
+                    error: errMsg,
+                    durationMs: Date.now() - slot.dispatchedAt,
                 });
+                if (isOwnerChat) {
+                    await this.sendReply(channel, {
+                        channel: msg.channel,
+                        accountId: msg.accountId,
+                        conversationId: msg.conversation.id,
+                        threadId: msg.conversation.threadId ?? null,
+                        text: `⚠️ Runtime error: ${truncate(errMsg, 500)}`,
+                        replyTo: msg.id,
+                        traceId: msg.trace?.id ?? null,
+                    });
+                }
+                else {
+                    this.log.warn("dispatcher: runtime error in non-owner-chat room — error reply suppressed", {
+                        queueKey,
+                        conversationId: msg.conversation.id,
+                    });
+                }
                 return;
             }
             if (!result)
@@ -377,15 +772,53 @@ export class Dispatcher {
                 }
             }
             const replyText = (result.text || "").trim();
-            if (!replyText)
+            const finalTextField = truncateTextField(result.text || "");
+            if (!replyText) {
+                this.emitOutbound({
+                    turnId,
+                    msg,
+                    runtime: route.runtime,
+                    runtimeSessionId: result.newSessionId || null,
+                    startedAt: slot.dispatchedAt,
+                    costUsd: result.costUsd,
+                    finalText: finalTextField,
+                    deliveryStatus: "empty_text",
+                    deliveryReason: null,
+                    blocks: slot.blocks,
+                });
                 return;
+            }
+            if (!isOwnerChat) {
+                // Non-owner-chat rooms: result.text never goes out. The agent is
+                // expected to have used the `botcord_send` tool / `botcord send` CLI
+                // already; whatever it left in the runtime's final assistant text is
+                // discarded so it doesn't leak into the room.
+                this.log.debug("dispatcher: non-owner-chat — discarding result.text (agent must use botcord_send)", {
+                    queueKey,
+                    conversationId: msg.conversation.id,
+                    replyTextLen: replyText.length,
+                });
+                this.emitOutbound({
+                    turnId,
+                    msg,
+                    runtime: route.runtime,
+                    runtimeSessionId: result.newSessionId || null,
+                    startedAt: slot.dispatchedAt,
+                    costUsd: result.costUsd,
+                    finalText: finalTextField,
+                    deliveryStatus: "gated_non_owner_chat",
+                    deliveryReason: null,
+                    blocks: slot.blocks,
+                });
+                return;
+            }
             // One last abort check immediately before the send. Narrows the window
             // in which a cancel-previous arriving during session-store.set could
             // still slip a stale reply past us.
             if (controller.signal.aborted && !slot.timedOut) {
                 return;
             }
-            await this.sendReply(channel, {
+            const sendResult = await this.sendReply(channel, {
                 channel: msg.channel,
                 accountId: msg.accountId,
                 conversationId: msg.conversation.id,
@@ -394,6 +827,18 @@ export class Dispatcher {
                 replyTo: msg.id,
                 traceId: msg.trace?.id ?? null,
             });
+            this.emitOutbound({
+                turnId,
+                msg,
+                runtime: route.runtime,
+                runtimeSessionId: result.newSessionId || null,
+                startedAt: slot.dispatchedAt,
+                costUsd: result.costUsd,
+                finalText: finalTextField,
+                deliveryStatus: sendResult.ok ? "delivered" : "send_failed",
+                deliveryReason: sendResult.ok ? null : sendResult.error,
+                blocks: slot.blocks,
+            });
         }
         finally {
             // Clear slot ownership AFTER the reply has been sent (or skipped).
@@ -411,12 +856,13 @@ export class Dispatcher {
             await channel.send({ message: outbound, log: this.log });
         }
         catch (err) {
+            const error = err instanceof Error ? err.message : String(err);
             this.log.warn("dispatcher: channel.send failed", {
                 channel: outbound.channel,
                 conversationId: outbound.conversationId,
-                error: err instanceof Error ? err.message : String(err),
+                error,
             });
-            return;
+            return { ok: false, error };
         }
         if (this.onOutbound) {
             try {
@@ -429,12 +875,93 @@ export class Dispatcher {
                 });
             }
         }
+        return { ok: true };
     }
+    emitInbound(turnId, msg) {
+        if (!this.transcript.enabled)
+            return;
+        const rawText = typeof msg.text === "string" ? msg.text : "";
+        const tField = truncateTextField(rawText);
+        const raw = msg.raw;
+        const batch = raw && typeof raw === "object" && Array.isArray(raw.batch)
+            ? raw.batch.length
+            : undefined;
+        const rec = {
+            ts: nowIso(),
+            kind: "inbound",
+            turnId,
+            agentId: msg.accountId,
+            roomId: msg.conversation.id,
+            topicId: msg.conversation.threadId ?? null,
+            messageId: msg.id,
+            sender: { id: msg.sender.id, kind: msg.sender.kind, ...(msg.sender.name ? { name: msg.sender.name } : {}) },
+            text: tField.text,
+        };
+        if (batch !== undefined && batch > 1)
+            rec.rawBatchEntries = batch;
+        if (msg.trace?.id) {
+            rec.trace = { id: msg.trace.id, ...(msg.trace.streamable ? { streamable: true } : {}) };
+        }
+        if (tField.truncated)
+            rec.truncated = { text: true };
+        this.transcript.write(rec);
+    }
+    emitOutbound(args) {
+        if (!this.transcript.enabled)
+            return;
+        const rec = {
+            ts: nowIso(),
+            kind: "outbound",
+            turnId: args.turnId,
+            agentId: args.msg.accountId,
+            roomId: args.msg.conversation.id,
+            topicId: args.msg.conversation.threadId ?? null,
+            runtime: args.runtime,
+            runtimeSessionId: args.runtimeSessionId,
+            durationMs: Date.now() - args.startedAt,
+            finalText: args.finalText.text,
+            deliveryStatus: args.deliveryStatus,
+            deliveryReason: args.deliveryReason,
+        };
+        if (typeof args.costUsd === "number")
+            rec.costUsd = args.costUsd;
+        if (args.blocks.length > 0)
+            rec.blocks = args.blocks;
+        if (args.finalText.truncated)
+            rec.truncated = { finalText: true };
+        this.transcript.write(rec);
+    }
+}
+function nowIso() {
+    return new Date().toISOString();
 }
 function buildQueueKey(msg) {
     const thread = msg.conversation.threadId ?? "";
     return `${msg.channel}:${msg.accountId}:${msg.conversation.id}:${thread}`;
 }
+/**
+ * Owner-chat predicate used by the dispatcher's reply gating. Matches the
+ * dual check in `sender-classify.ts:classifyActivitySender` so the
+ * dispatcher's gate stays consistent with the composer's owner-bypass:
+ *
+ *   1. `rm_oc_*` room id, OR
+ *   2. `source_type === "dashboard_user_chat"` on the raw envelope.
+ *
+ * The latter exists because the dashboard's user-chat surface can route
+ * messages through non-`rm_oc_` rooms in some flows; treating them as
+ * owner-trust here keeps the agent's plain reply text reachable.
+ */
+function isOwnerChatRoom(msg) {
+    if (msg.conversation.id.startsWith(OWNER_CHAT_ROOM_PREFIX))
+        return true;
+    const raw = msg.raw;
+    if (raw && typeof raw === "object") {
+        const sourceType = raw.source_type;
+        if (sourceType === "dashboard_user_chat")
+            return true;
+    }
+    return false;
+}
 function resolveQueueMode(route, kind) {
     if (route.queueMode)
         return route.queueMode;