@botcord/daemon 0.2.4 → 0.2.6

package/src/gateway/dispatcher.ts

@@ -1,10 +1,19 @@
+import { randomUUID } from "node:crypto";
+
 import type { GatewayLogger } from "./log.js";
 import { resolveRoute } from "./router.js";
 import { sessionKey, type SessionStore } from "./session-store.js";
+import {
+  truncateTextField,
+  type DeliveryStatus,
+  type TranscriptBlockSummary,
+  type TranscriptWriter,
+} from "./transcript.js";
 import type {
   ChannelAdapter,
   GatewayConfig,
   GatewayInboundEnvelope,
+  GatewayInboundMessage,
   GatewayOutboundMessage,
   GatewayRoute,
   GatewaySessionEntry,
@@ -20,6 +29,24 @@ import type {
 
 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;
+
 /** Factory signature for building a runtime adapter at turn dispatch time. */
 export type RuntimeFactory = (
   runtimeId: string,
@@ -65,20 +92,80 @@ export interface DispatcherOptions {
    * and suppressed so observer failures never break the turn.
    */
   onOutbound?: OutboundObserver;
+  /**
+   * Optional attention gate (PR3, design §4.2). Resolved AFTER `onInbound`
+   * runs and BEFORE the runtime turn enqueues, so working memory / activity
+   * tracking still observe the message even when the gate skips the wake.
+   *
+   * Return `true` to wake the runtime, `false` to skip the turn. Errors are
+   * logged and treated as `true` (fail-open) so a buggy gate cannot silence
+   * the agent.
+   */
+  attentionGate?: (
+    message: GatewayInboundMessage,
+  ) => Promise<boolean> | boolean;
+  /**
+   * Resolve the hub URL the inbound message's agent is registered against.
+   * Threaded into `RuntimeRunOptions.hubUrl` so spawned CLI subprocesses
+   * target the correct hub. If unset, runtimes leave `BOTCORD_HUB`
+   * unspecified and fall back to whatever the bundled CLI defaults to.
+   */
+  resolveHubUrl?: (accountId: string) => string | undefined;
+  /**
+   * Optional NDJSON transcript writer. When provided, dispatcher emits one
+   * inbound record + one path record + (for dispatched turns) one terminal
+   * record per `handle()` call. A noop writer is used by default so existing
+   * call sites keep working unchanged. See `docs/transcript-logging.md`.
+   */
+  transcript?: TranscriptWriter;
 }
 
+/**
+ * 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 {
+  constructor(public readonly supersededBy: string) {
+    super("turn superseded");
+    this.name = "TurnSupersededError";
+  }
+}
+
+const NOOP_TRANSCRIPT: TranscriptWriter = {
+  enabled: false,
+  rootDir: "",
+  write: () => {},
+};
+
 interface TurnSlot {
+  turnId: string;
   controller: AbortController;
   timedOut: boolean;
   snapshot: TurnStatusSnapshot;
   done: Promise<void>;
+  dispatchedAt: number;
+  /** Streamed block summaries flushed into the terminal `outbound` record. */
+  blocks: TranscriptBlockSummary[];
+}
+
+/**
+ * One entry buffered for serial-mode coalescing. Each successful `runSerial`
+ * call pushes one entry; the worker drains the entire buffer on the next
+ * turn boundary and merges them into a single dispatch.
+ */
+interface BufferedSerialEntry {
+  route: GatewayRoute;
+  msg: GatewayInboundEnvelope["message"];
+  channel: ChannelAdapter;
+  /** Per-arrival turnId; preserved through merge so transcript can record dropped/dispatched correctly. */
+  turnId: string;
 }
 
 interface QueueState {
   /** The currently executing turn on this queue key, if any. */
   current: TurnSlot | null;
-  /** Tail of the serial-mode queue — chained via promises; replaced each append. */
-  tail: Promise<void>;
   /**
    * Generation counter bumped every time a cancel-previous turn arrives.
    * Any in-flight cancel-previous arrival captures the value at entry; if a
@@ -88,6 +175,15 @@ interface QueueState {
    * `current === null` after an abort and run concurrently.
    */
   cancelGen: number;
+  /**
+   * Serial-mode coalescing buffer. Messages pushed here while a turn is in
+   * flight are drained — and merged into a single user turn — on the next
+   * iteration of the worker loop. First message in an idle queue triggers a
+   * turn immediately; subsequent arrivals fold into the next batch.
+   */
+  serialBuffer: BufferedSerialEntry[];
+  /** True when the serial-drain worker is actively running (or about to). */
+  serialWorkerActive: boolean;
 }
 
 /**
@@ -112,6 +208,11 @@ export class Dispatcher {
   private readonly onOutbound?: OutboundObserver;
   private readonly composeUserTurn?: UserTurnBuilder;
   private readonly managedRoutes?: Map<string, GatewayRoute>;
+  private readonly attentionGate?: (
+    message: GatewayInboundMessage,
+  ) => Promise<boolean> | boolean;
+  private readonly resolveHubUrl?: (accountId: string) => string | undefined;
+  private readonly transcript: TranscriptWriter;
   private readonly queues: Map<string, QueueState> = new Map();
 
   constructor(opts: DispatcherOptions) {
@@ -126,21 +227,32 @@ 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: GatewayInboundEnvelope): Promise<void> {
     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") {
@@ -149,33 +261,52 @@ export class Dispatcher {
       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: string | undefined;
+    if (mode === "cancel-previous" && this.composeUserTurn) {
       try {
         const composed = this.composeUserTurn(msg);
         if (typeof composed === "string" && composed.length > 0) {
           text = composed;
         }
       } 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) {
@@ -189,19 +320,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);
     }
   }
 
@@ -236,8 +406,9 @@ export class Dispatcher {
     if (!q) {
       q = {
         current: null,
-        tail: Promise.resolve(),
         cancelGen: 0,
+        serialBuffer: [],
+        serialWorkerActive: false,
       };
       this.queues.set(key, q);
     }
@@ -250,6 +421,7 @@ export class Dispatcher {
     text: string,
     msg: GatewayInboundEnvelope["message"],
     channel: ChannelAdapter,
+    turnId: string,
   ): Promise<void> {
     const q = this.getQueue(queueKey);
     // Bump the generation on every arrival. Older arrivals still awaiting
@@ -260,7 +432,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);
     }
@@ -269,23 +453,217 @@ 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, []);
   }
 
+  /**
+   * 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.
+   */
   private async runSerial(
     queueKey: string,
     route: GatewayRoute,
-    text: string,
+    _text: string,
     msg: GatewayInboundEnvelope["message"],
     channel: ChannelAdapter,
+    turnId: string,
   ): Promise<void> {
     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;
+    }
+  }
+
+  /**
+   * 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).
+   */
+  private mergeSerialBuffer(
+    entries: BufferedSerialEntry[],
+    queueKey: string,
+  ): {
+    route: GatewayRoute;
+    text: string;
+    msg: GatewayInboundEnvelope["message"];
+    channel: ChannelAdapter;
+    turnId: string;
+  } | null {
+    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: Array<Record<string, unknown>> = [];
+    for (const e of entries) {
+      const raw = e.msg.raw as Record<string, unknown> | null | undefined;
+      const batch = raw && Array.isArray((raw as { batch?: unknown }).batch)
+        ? ((raw as { batch: Array<Record<string, unknown>> }).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 as string).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 as string).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 as Record<string, unknown> | null | undefined) ?? {};
+    const mergedRaw = { ...latestRaw, batch: items };
+    const anyMentioned = entries.some((e) => e.msg.mentioned === true);
+    const mergedMsg: GatewayInboundEnvelope["message"] = {
+      ...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.
+   */
+  private recomposeUserTurn(msg: GatewayInboundEnvelope["message"]): string {
+    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;
   }
 
   private async runTurn(
@@ -294,6 +672,8 @@ export class Dispatcher {
     text: string,
     msg: GatewayInboundEnvelope["message"],
     channel: ChannelAdapter,
+    turnId: string,
+    mergedFromTurnIds: string[],
   ): Promise<void> {
     const q = this.getQueue(queueKey);
     const controller = new AbortController();
@@ -312,9 +692,35 @@ export class Dispatcher {
     const done = new Promise<void>((res) => {
       resolveDone = res;
     });
-    const slot: TurnSlot = { controller, timedOut: false, snapshot, done };
+    const slot: TurnSlot = {
+      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: import("./transcript.js").DispatchedTranscriptRecord = {
+        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;
@@ -342,8 +748,18 @@ export class Dispatcher {
     const traceId = msg.trace?.id;
     const canStream =
       streamable && typeof traceId === "string" && typeof channel.streamBlock === "function";
+    const recordBlock = (block: StreamBlock): void => {
+      const summary: TranscriptBlockSummary = { type: block.kind };
+      const raw = block.raw as { text?: unknown; name?: unknown } | null | undefined;
+      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: StreamBlock) => {
+          recordBlock(block);
           // Fire-and-forget: stream errors must not break the turn.
           channel
             .streamBlock!({
@@ -390,11 +806,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) {
         threw = err;
@@ -409,39 +827,99 @@ 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;
       }
 
@@ -500,7 +978,51 @@ export class Dispatcher {
       }
 
       const replyText = (result.text || "").trim();
-      if (!replyText) return;
+      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
@@ -509,7 +1031,7 @@ export class Dispatcher {
         return;
       }
 
-      await this.sendReply(channel, {
+      const sendResult = await this.sendReply(channel, {
         channel: msg.channel,
         accountId: msg.accountId,
         conversationId: msg.conversation.id,
@@ -518,6 +1040,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).
       // Only then do cancel-previous arrivals stop finding this slot — which
@@ -532,16 +1066,17 @@ export class Dispatcher {
   private async sendReply(
     channel: ChannelAdapter,
     outbound: GatewayOutboundMessage,
-  ): Promise<void> {
+  ): Promise<{ ok: true } | { ok: false; error: string }> {
     try {
       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 {
@@ -553,14 +1088,102 @@ export class Dispatcher {
         });
       }
     }
+    return { ok: true };
+  }
+
+  private emitInbound(turnId: string, msg: GatewayInboundEnvelope["message"]): void {
+    if (!this.transcript.enabled) return;
+    const rawText = typeof msg.text === "string" ? msg.text : "";
+    const tField = truncateTextField(rawText);
+    const raw = msg.raw as Record<string, unknown> | null | undefined;
+    const batch =
+      raw && typeof raw === "object" && Array.isArray((raw as { batch?: unknown }).batch)
+        ? (raw as { batch: unknown[] }).batch.length
+        : undefined;
+    const rec: import("./transcript.js").InboundTranscriptRecord = {
+      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);
+  }
+
+  private emitOutbound(args: {
+    turnId: string;
+    msg: GatewayInboundEnvelope["message"];
+    runtime: string;
+    runtimeSessionId: string | null;
+    startedAt: number;
+    costUsd?: number;
+    finalText: { text: string; truncated: boolean };
+    deliveryStatus: DeliveryStatus;
+    deliveryReason: string | null;
+    blocks: TranscriptBlockSummary[];
+  }): void {
+    if (!this.transcript.enabled) return;
+    const rec: import("./transcript.js").OutboundTranscriptRecord = {
+      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(): string {
+  return new Date().toISOString();
+}
+
 function buildQueueKey(msg: GatewayInboundEnvelope["message"]): string {
   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: GatewayInboundEnvelope["message"]): boolean {
+  if (msg.conversation.id.startsWith(OWNER_CHAT_ROOM_PREFIX)) return true;
+  const raw = msg.raw;
+  if (raw && typeof raw === "object") {
+    const sourceType = (raw as { source_type?: unknown }).source_type;
+    if (sourceType === "dashboard_user_chat") return true;
+  }
+  return false;
+}
+
 function resolveQueueMode(
   route: GatewayRoute,
   kind: "direct" | "group",