@animalabs/agent-framework 0.22.1 → 0.22.3

package/src/mcpl/channel-registry.ts

@@ -14,8 +14,9 @@
  */
 
 import type { ContentBlock } from '@animalabs/membrane';
-import { INLINE_WITHHELD_TEXT, isInlineContradiction, referenceStubOrNull } from './references.js';
+import { convertBlock } from './convert-block.js';
 import type { JsStore } from '@animalabs/chronicle';
+import { ensureStateRegistered } from '../module-registry.js';
 
 import type {
   ChannelDescriptor,
@@ -30,16 +31,20 @@ import type {
   ChannelsPublishParams,
   ChannelsOpenResult,
   ChannelHistoryRequest,
-  McplContentBlock,
 } from './types.js';
 
 import type { McplServerRegistry } from './server-registry.js';
 import type { FeatureSetManager } from './feature-set-manager.js';
 import type { ToolDefinition, ToolResult, ProcessEvent } from '../types/index.js';
 import { expandCoreTags } from './tags.js';
-import { EmptyContentError, validateCoalescedContent } from './push-coalescer.js';
-import { isVisiblyEmptyContent } from './visible-content.js';
+import { coalesceRejectionReason, EmptyContentError, validateCoalescedContent } from './push-coalescer.js';
+import { isVisiblyEmptyConversion } from './visible-content.js';
+import { logDetail, logValue } from './log-value.js';
+import { RefusalLines } from './refusal-lines.js';
 import { CapabilityGrant } from './capability-grant.js';
+import type { InboundSource } from './inbound-source.js';
+import { McplRequestError } from './server-connection.js';
+import { readSkipReplyWake } from './skip-reply-wake.js';
 
 // ============================================================================
 // Typing indicator interval (Discord typing lasts ~10s, so 7s keeps it alive)
@@ -237,74 +242,10 @@ interface McplChannelIncomingEvent {
   tags?: string[];
   triggerInference?: boolean;
   targetAgents?: string[];
-}
-
-// ============================================================================
-// Content Conversion: McplContentBlock → membrane ContentBlock
-// ============================================================================
-
-/**
- * Convert a single MCPL wire-format content block to a membrane ContentBlock.
- */
-function convertBlock(block: McplContentBlock): ContentBlock {
-  switch (block.type) {
-    case 'text':
-      return { type: 'text', text: block.text };
-
-    case 'image':
-      if (isInlineContradiction(block)) {
-        // RFC-005 vector 2: inline data claiming bulk disposition — fail
-        // closed, withhold the data (checked BEFORE the data branch).
-        return { type: 'text', text: INLINE_WITHHELD_TEXT };
-      }
-      if (block.uri && block.disposition) {
-        // RFC-005 uri-form media with a disposition claim: stub, do not
-        // hand the URI to the provider or inline it.
-        return { type: 'text', text: referenceStubOrNull(block, 'attachment on channel message') ?? '[reference]' };
-      }
-      if (block.data && block.mimeType) {
-        return {
-          type: 'image',
-          source: { type: 'base64', data: block.data, mediaType: block.mimeType },
-        } as ContentBlock;
-      }
-      if (block.uri) {
-        return {
-          type: 'image',
-          source: { type: 'url', url: block.uri },
-        } as ContentBlock;
-      }
-      return { type: 'text', text: '[Image: no data]' };
-
-    case 'audio':
-      if (isInlineContradiction(block)) {
-        // RFC-005 vector 2: inline data claiming bulk disposition — fail
-        // closed, withhold the data (checked BEFORE the data branch).
-        return { type: 'text', text: INLINE_WITHHELD_TEXT };
-      }
-      if (block.uri && block.disposition) {
-        // RFC-005 uri-form media with a disposition claim: stub, do not
-        // hand the URI to the provider or inline it.
-        return { type: 'text', text: referenceStubOrNull(block, 'attachment on channel message') ?? '[reference]' };
-      }
-      if (block.data && block.mimeType) {
-        return {
-          type: 'audio',
-          source: { type: 'base64', data: block.data, mediaType: block.mimeType },
-        } as ContentBlock;
-      }
-      return { type: 'text', text: '[Audio: no data]' };
-
-    case 'resource':
-      // RFC-005: reference blocks become bounded stubs — never raw URIs
-      // (a signed URL is a bearer credential that looks like a location).
-      return { type: 'text', text: referenceStubOrNull(block, 'attachment on channel message') ?? '[reference]' };
-
-    default:
-      // Unknown wire block types previously fell off the exhaustive switch
-      // and propagated `undefined` into ContentBlock[]. Fail visibly.
-      return { type: 'text', text: `[unrecognized content block: ${(block as { type?: string }).type ?? 'untyped'}]` };
-  }
+  /** Host acceptance time (epoch ms), stamped where the message is admitted. */
+  acceptedAt?: number;
+  /** Source envelope frozen at admission (mcpl/inbound-source.ts). */
+  inboundSource?: InboundSource;
 }
 
 // ============================================================================
@@ -320,9 +261,8 @@ const CHANNEL_TOOL_DEFINITIONS: ToolDefinition[] = [
   {
     name: 'channel_open',
     description:
-      'Open a channel to start receiving its ordinary ongoing traffic. The MCPL ' +
-      'integration performs its own subscribe/join/attach operation. Optionally request ' +
-      'history preceding the message that invited you into the channel.',
+      'Open a channel. What an open channel delivers to you depends on its MCPL server. ' +
+      'Optionally request history preceding the message that invited you into the channel.',
     inputSchema: {
       type: 'object' as const,
       properties: {
@@ -362,7 +302,9 @@ const CHANNEL_TOOL_DEFINITIONS: ToolDefinition[] = [
   },
   {
     name: 'channel_close',
-    description: 'Close a channel to stop receiving messages',
+    description:
+      'Close a channel. Messages that address you still reach you; what else stops reaching you ' +
+      'depends on its server.',
     inputSchema: {
       type: 'object' as const,
       properties: {
@@ -441,8 +383,9 @@ const CHANNEL_TOOL_DEFINITIONS: ToolDefinition[] = [
           type: 'number',
           description:
             'Optional self-wake: if nothing else wakes you first, you wake again after this ' +
-            'many seconds (1 = go again almost immediately; clamped to 1–3600). Any other ' +
-            'wake before then cancels it. Omit to stay idle until the next external wake.',
+            'many seconds, from 1 to 3600; a larger number waits 3600 (1 = go again almost ' +
+            'immediately). Any other wake before then cancels it. Omit to stay idle until the ' +
+            'next external wake.',
         },
       },
       required: [],
@@ -454,7 +397,125 @@ const CHANNEL_TOOL_DEFINITIONS: ToolDefinition[] = [
 // Constructor Options
 // ============================================================================
 
+/** Bound connector values for notices, logs and an outcome's reason. A
+ *  PublishOutcome keeps the connector's structured data (`detail`) whole. */
+export function connectorText(value: unknown): string {
+  let text: string;
+  try {
+    text = typeof value === 'string' ? value : JSON.stringify(value) ?? String(value);
+  } catch {
+    return '[unserializable connector value]';
+  }
+  const limit = 2000;
+  const suffix = '… [truncated]';
+  return text.length > limit ? text.slice(0, limit - suffix.length) + suffix : text;
+}
+
+/** Where a publish was resolved to go — named by the registry, never by
+ *  the caller's spelling. */
+export interface PublishDestination {
+  serverId: string;
+  channelId: string;
+  /** The channel's registered label when the attempt was made. */
+  label?: string;
+}
+
+/**
+ * What one channels/publish attempt established (ChannelRegistry.publish).
+ * - `delivered`: the connector returned `delivered: true`. A historical
+ *   receipt (confirmed at `at`, to `destination`, message `messageId` when
+ *   the connector named one), not a claim the message still exists.
+ * - `failed`: nothing was posted: the request never left the host
+ *   (unresolvable or shared channel id, missing grant, failed open, closed
+ *   connection), or the connector answered `delivered: false` and named no
+ *   message.
+ * - `unknown`: the request was dispatched and no valid receipt came back (an
+ *   error response, a timeout, a lost connection, or a missing, malformed or
+ *   contradictory receipt, such as `delivered: false` beside a message id).
+ *   It may or may not have been posted.
+ */
+export interface PublishOutcome {
+  status: 'delivered' | 'failed' | 'unknown';
+  /** Absent only when no destination could be resolved. */
+  destination?: PublishDestination;
+  messageId?: string;
+  /** Why it failed, or why its outcome is unknown — for a connector error,
+   *  its message, bounded (which may say what was already posted). */
+  reason?: string;
+  /** The connector error's structured `data`, verbatim, when it sent one. */
+  detail?: unknown;
+  /** When the outcome was established (epoch ms). */
+  at: number;
+}
+
+/**
+ * What a channels/publish request that threw establishes. Only a request
+ * that never left the host proves nothing was posted. An error response may
+ * follow a partial post (a multi-part send whose later part failed), so it
+ * is unknown, with the connector's own words, bounded, and its data kept for
+ * the resident to judge. The publish executor and channel_publish both read
+ * a failed request this way.
+ */
+function publishErrorOutcome(err: unknown, destination: PublishDestination, at: number): PublishOutcome {
+  const message = connectorText(err instanceof Error ? err.message : String(err));
+  const notSent = err instanceof McplRequestError && err.outcome === 'not-sent';
+  const detail = err instanceof McplRequestError ? err.data : undefined;
+  return {
+    status: notSent ? 'failed' : 'unknown',
+    destination,
+    reason: notSent ? message : `${message} (delivery uncertain)`,
+    ...(detail !== undefined ? { detail } : {}),
+    at,
+  };
+}
+
+/**
+ * What a channels/publish answer establishes. A final publish is a request,
+ * so success requires an explicit receipt; a missing or malformed one leaves
+ * delivery uncertain (anima-research/agent-framework#163's rule).
+ * `delivered: false` proves nothing went out only when the receipt names no
+ * message at all: a message id beside it, valid or malformed, contradicts it,
+ * since something may have been posted. The publish executor and
+ * channel_publish both read an answer this way.
+ */
+function publishReceiptOutcome(result: unknown, destination: PublishDestination, at: number): PublishOutcome {
+  const receipt = (result ?? {}) as { delivered?: unknown; messageId?: unknown };
+  const messageId = typeof receipt.messageId === 'string' && receipt.messageId ? receipt.messageId : undefined;
+  if (receipt.delivered === true) {
+    return { status: 'delivered', destination, ...(messageId ? { messageId } : {}), at };
+  }
+  if (receipt.delivered === false) {
+    if (receipt.messageId === undefined || receipt.messageId === null) {
+      return { status: 'failed', destination, reason: `server "${destination.serverId}" reported delivered:false`, at };
+    }
+    return {
+      status: 'unknown',
+      destination,
+      ...(messageId ? { messageId } : {}),
+      reason: messageId
+        ? `server "${destination.serverId}" reported delivered:false but named posted message ${connectorText(messageId)} (delivery uncertain)`
+        : `server "${destination.serverId}" reported delivered:false beside a malformed message id ` +
+          `${connectorText(receipt.messageId)} (contradictory receipt; delivery uncertain)`,
+      at,
+    };
+  }
+  return {
+    status: 'unknown',
+    destination,
+    ...(messageId ? { messageId } : {}),
+    reason: `server "${destination.serverId}" returned no valid delivery receipt (delivery uncertain)`,
+    at,
+  };
+}
+
 interface ChannelRegistryOptions {
+  /**
+   * An ordinary (uncoalesced) `channels/incoming` message has just been
+   * admitted, before it is queued or acknowledged: return its source
+   * envelope, frozen now (mcpl/inbound-source.ts). The framework observes the
+   * acceptance here; coalesced work is stamped and observed by its own path.
+   */
+  acceptInbound?: (event: McplChannelIncomingEvent) => InboundSource | undefined;
   /**
    * RFC-006: an admitted `channels/incoming` message carrying `coalesce`, with
    * the event the ordinary path would have queued. The handler decides
@@ -483,15 +544,21 @@ interface ChannelRegistryOptions {
     channelId: string | null;
     reason: string;
     textLen: number;
+    /** `failed`: nothing was posted; `unknown`: the request was dispatched
+     *  and no valid receipt came back, so it may or may not have been. */
+    outcome?: 'failed' | 'unknown';
+    /** Bounded display of the connector's structured error data, when present. */
+    detail?: string;
   }) => void;
   /**
    * Called when channels were opened WITHOUT the agent asking (subscription
    * policy admitting a newly discovered channel, or delivery into a closed
    * locus). The host wires this to drop a durable notice into the agent's
-   * window — the agent must always learn that new traffic will start
-   * flowing, and that `channel_close` opts out (their decision outranks
-   * policy). Fires ONCE per channel ever: the desired-state decision is
-   * durable, so reboots do not re-announce. Must not trigger inference.
+   * window — the agent must always learn that the channel opened, and that
+   * `channel_close` opts out (their decision outranks policy). What an open
+   * channel delivers is the server's to say (#406). Fires ONCE per channel
+   * ever: the desired-state decision is durable, so reboots do not
+   * re-announce. Must not trigger inference.
    */
   onChannelAutoOpened?: (info: {
     /** Agent whose action caused the open (delivery); absent for policy opens. */
@@ -512,19 +579,23 @@ interface ChannelRegistryOptions {
    */
   homeChannelResolver?: (agentName: string) => string | undefined;
   /**
-   * Resolve the channel that triggered an agent's CURRENT inference turn, by
-   * agent name. This is the fix for single-TRUNK agents (the only mode
+   * Resolve an agent's channel for its CURRENT inference turn, by agent name:
+   * the turn's locus once it has one, else the channel that triggered the
+   * turn. This is the fix for single-TRUNK agents (the only mode
    * connectome-host runs — it never exposes conversation forks). A trunk agent
    * has no fork home, so without this its plain-text speech falls back to the
    * process-global `defaultPublishChannel`, which tracks the most-recent inbound
    * across ALL channels and misroutes a reply to whichever channel last spoke
-   * under concurrency (item-3 redux). The framework tracks the triggering
-   * channel of the live turn per-agent and exposes it here; resolves to
-   * undefined for a heartbeat / no-trigger turn, which correctly keeps the
-   * global fallback. Consulted AFTER `homeChannelResolver` (a fork's home always
-   * wins), BEFORE `defaultPublishChannel`.
+   * under concurrency (item-3 redux). The framework keeps both on the live
+   * turn's routing state and exposes them here. For a heartbeat / no-trigger
+   * turn it resolves to undefined until the turn's locus is resolved, so that
+   * resolution takes the global fallback, which the turn then keeps.
+   * Consulted AFTER `homeChannelResolver` (a fork's home always wins), BEFORE
+   * `defaultPublishChannel`.
    */
   activeChannelResolver?: (agentName: string) => string | undefined;
+  /** Whether this framework has EventGate and can honor skip_reply self-wakes. */
+  eventGatePresent?: boolean;
 }
 
 // ============================================================================
@@ -558,12 +629,7 @@ export class ChannelRegistry {
     op?: 'start' | 'stop',
   ) => void;
   private shouldTriggerInference?: (content: string, metadata: Record<string, unknown>) => boolean;
-  private onRouteFailure?: (info: {
-    conversationId: string;
-    channelId: string | null;
-    reason: string;
-    textLen: number;
-  }) => void;
+  private onRouteFailure?: ChannelRegistryOptions['onRouteFailure'];
   private onChannelAutoOpened?: (info: {
     conversationId?: string;
     serverId: string;
@@ -577,6 +643,10 @@ export class ChannelRegistry {
   /** Registered channels, keyed by `{serverId}:{channelId}`. */
   private channels = new Map<string, ChannelEntry>();
 
+  /** Holds back repeats of the line for a message refused because its
+   *  channel isn't registered (RefusalLines). */
+  private unknownChannelLines = new RefusalLines();
+
   /**
    * Most-recently-known label per channelId, replayed from
    * `CHANNEL_LABEL_HISTORY_LOG_ID` (last sighting wins) and kept current by
@@ -658,6 +728,8 @@ export class ChannelRegistry {
   private legacyPolicies = new Map<string, 'auto' | 'manual' | string[]>();
   private migratedLegacyPolicies = new Set<string>();
   private handleCoalescedIncoming?: ChannelRegistryOptions['handleCoalescedIncoming'];
+  private acceptInbound?: ChannelRegistryOptions['acceptInbound'];
+  private channelTools: ToolDefinition[];
 
   constructor(
     serverRegistry: McplServerRegistry,
@@ -674,6 +746,24 @@ export class ChannelRegistry {
     },
   ) {
     this.handleCoalescedIncoming = options?.handleCoalescedIncoming;
+    this.acceptInbound = options?.acceptInbound;
+    this.channelTools = CHANNEL_TOOL_DEFINITIONS.map((tool) => {
+      if (tool.name !== 'skip_reply' || options?.eventGatePresent === true) return tool;
+      const schema = tool.inputSchema as {
+        type: 'object';
+        properties: NonNullable<ToolDefinition['inputSchema']['properties']>;
+        required?: string[];
+      };
+      const { wake_in_seconds: _wake, ...properties } = schema.properties;
+      return {
+        ...tool,
+        description: tool.description.replace(
+          ' To end this turn but come back on your own shortly, set wake_in_seconds.',
+          '',
+        ),
+        inputSchema: { ...schema, properties },
+      };
+    });
     this.serverRegistry = serverRegistry;
     this.featureSetManager = featureSetManager;
     this.pushEventFn = pushEventFn;
@@ -848,6 +938,45 @@ export class ChannelRegistry {
     });
   }
 
+  /**
+   * A coalesced message the host refused. Until now the host said nothing, so
+   * a dropped message (agent-framework#266: every Discord message with a
+   * screenshot) left no trace where operators look. The sender gets the
+   * per-message result this lane gives: `coalesce_invalid` for a malformed
+   * item, or the thrown error's message for anything else. `answered` is the
+   * code that result stands for (-32602 for `coalesce_invalid`), and the
+   * reason follows it (coalesceRejectionReason): `coalesce-failed` when the
+   * host itself failed, `coalesce-invalid` when the sender's item was
+   * refused, with the failing `field` and the error's message as `detail`.
+   * The line prints the ids the sender sent, whatever their type; the trace
+   * carries them when they are strings.
+   */
+  private traceCoalesceRejection(
+    serverId: string,
+    message: { channelId?: unknown; messageId?: unknown } | null | undefined,
+    error: { field?: unknown; message: string },
+    answered: number,
+  ): void {
+    const reason = coalesceRejectionReason(answered);
+    const field = typeof error.field === 'string' && error.field ? error.field : undefined;
+    const channelId = typeof message?.channelId === 'string' ? message.channelId : '';
+    const messageId = typeof message?.messageId === 'string' && message.messageId ? message.messageId : undefined;
+    console.error(
+      `[channel-incoming-rejected] server=${serverId} channel=${logValue(message?.channelId ?? '')} ` +
+      `messageId=${logValue(message?.messageId ?? '')} ` +
+      `reason=${reason}${field ? ` field=${logValue(field)}` : ''}: ${logDetail(error.message)}`,
+    );
+    this.emitTraceFn({
+      type: 'mcpl:channel-incoming-rejected',
+      serverId,
+      channelId,
+      ...(messageId ? { messageId } : {}),
+      reason,
+      ...(field ? { field } : {}),
+      detail: error.message,
+    });
+  }
+
   /**
    * Handle `channels/incoming` from a server.
    *
@@ -864,10 +993,20 @@ export class ChannelRegistry {
     for (const message of params.messages) {
       if (!message || typeof message.channelId !== 'string' || !message.channelId
         || typeof message.messageId !== 'string' || !message.messageId) {
+        // The same gate as admission below: with no coalescer wired, a
+        // message carrying `coalesce` is handled uncoalesced, and refused as
+        // any uncoalesced message without an identity is.
+        const coalescedItem = message?.coalesce !== undefined && !!this.handleCoalescedIncoming;
+        if (coalescedItem) {
+          this.traceCoalesceRejection(serverId, message, {
+            field: typeof message.channelId !== 'string' || !message.channelId ? 'channelId' : 'messageId',
+            message: 'a coalesced message needs a channelId and a messageId',
+          }, -32602);
+        }
         results.push({
           messageId: typeof message?.messageId === 'string' ? message.messageId : '',
           accepted: false,
-          reason: message?.coalesce !== undefined ? 'coalesce_invalid' : 'invalid channel/message identity',
+          reason: coalescedItem ? 'coalesce_invalid' : 'invalid channel/message identity',
         });
         continue;
       }
@@ -899,11 +1038,24 @@ export class ChannelRegistry {
       // routable entry rather than an open self-attested one.
       const incomingKey = `${serverId}:${message.channelId}`;
       if (!this.channels.has(incomingKey)) {
+        // Loud, coalesced or not, like every other refusal of a message, but
+        // at most once a minute per channel (RefusalLines): a server that
+        // never registered a busy channel would otherwise print a line for
+        // every message in it. Every refusal is traced.
+        const held = this.unknownChannelLines.admit(serverId, message.channelId);
+        if (held !== null) {
+          console.error(
+            `[channel-incoming-rejected] server=${serverId} channel=${logValue(message.channelId)} ` +
+            `messageId=${logValue(message.messageId)} reason=unknown-channel ` +
+            `(not registered, §14.5${held ? `; ${held} more since the last line` : ''})`,
+          );
+        }
         this.emitTraceFn({
           type: 'mcpl:channel-incoming-rejected',
           serverId,
           channelId: message.channelId,
-          reason: 'unknown channel — not registered (§14.5)',
+          messageId: message.messageId,
+          reason: 'unknown-channel',
         });
         results.push({
           messageId: message.messageId,
@@ -921,7 +1073,7 @@ export class ChannelRegistry {
       // shows the model nothing would wake it with no visible cause.
       const emptyAllowed = coalesced && (message.coalesce as { retract?: unknown } | null)?.retract === true;
       const rejectEmpty = () => {
-        console.error(`[channel-incoming-rejected] server=${serverId} channel=${message.channelId} messageId=${message.messageId} reason=empty-content`);
+        console.error(`[channel-incoming-rejected] server=${serverId} channel=${logValue(message.channelId)} messageId=${logValue(message.messageId)} reason=empty-content`);
         this.emitTraceFn({
           type: 'mcpl:channel-incoming-rejected',
           serverId,
@@ -935,16 +1087,20 @@ export class ChannelRegistry {
         // RFC-006 §13: malformed content on a coalesced item is that item's
         // failure, not the batch's — check the shape before converting.
         try {
-          validateCoalescedContent(message.content, undefined, { allowEmpty: emptyAllowed });
+          validateCoalescedContent(message.content, { allowEmpty: emptyAllowed });
         } catch (error) {
           if (error instanceof EmptyContentError) rejectEmpty();
-          else results.push({ messageId: message.messageId, accepted: false, reason: 'coalesce_invalid' });
+          else {
+            // Answered coalesce_invalid whatever the error's code: -32602.
+            this.traceCoalesceRejection(serverId, message, error as Error & { field?: string }, -32602);
+            results.push({ messageId: message.messageId, accepted: false, reason: 'coalesce_invalid' });
+          }
           continue;
         }
       }
       if (message.tags) message.tags = expandCoreTags(message.tags);
-      const convertedContent: ContentBlock[] = message.content.map(convertBlock);
-      if (!emptyAllowed && isVisiblyEmptyContent(convertedContent)) {
+      const convertedContent: ContentBlock[] = message.content.map((block) => convertBlock(block, 'attachment on channel message', serverId));
+      if (!emptyAllowed && isVisiblyEmptyConversion(message.content, convertedContent)) {
         rejectEmpty();
         continue;
       }
@@ -970,8 +1126,11 @@ export class ChannelRegistry {
       // Determine whether to trigger inference
       let triggerInference = true;
       if (this.shouldTriggerInference) {
-        const textContent = message.content
-          .filter((b): b is { type: 'text'; text: string } => b.type === 'text')
+        // The text the agent's context gets, as the push lane's filter reads
+        // it: the converted text blocks, a placeholder or reference stub
+        // among them, NON_STRING_TEXT_PLACEHOLDER included.
+        const textContent = convertedContent
+          .filter((b): b is ContentBlock & { type: 'text' } => b.type === 'text')
           .map((b) => b.text)
           .join('\n');
         triggerInference = this.shouldTriggerInference(
@@ -1002,6 +1161,7 @@ export class ChannelRegistry {
         metadata: message.metadata,
         ...(message.tags ? { tags: message.tags } : {}),
         triggerInference,
+        acceptedAt: Date.now(),
       };
 
       if (coalesced) {
@@ -1014,7 +1174,10 @@ export class ChannelRegistry {
           if (result.accepted) markAccepted();
           results.push(result);
         } catch (error) {
-          const err = error as Error & { code?: number };
+          const err = error as Error & { code?: number; field?: string };
+          // -32602 is answered coalesce_invalid; anything else as its message,
+          // a plain Error standing for an internal error (-32603).
+          this.traceCoalesceRejection(serverId, message, err, typeof err.code === 'number' ? err.code : -32603);
           results.push({
             messageId: message.messageId,
             accepted: false,
@@ -1024,6 +1187,12 @@ export class ChannelRegistry {
         continue;
       }
 
+      // The source envelope is frozen here, at admission, before the message
+      // is queued or acknowledged: a rename or rebind while it waits in the
+      // queue cannot change where it says it came from.
+      const inboundSource = this.acceptInbound?.(event);
+      if (inboundSource) event.inboundSource = inboundSource;
+
       // Push to the processing queue
       // Cast through unknown because McplChannelIncomingEvent matches the
       // CustomEvent `${string}:${string}` type pattern but lacks an index signature.
@@ -1077,20 +1246,34 @@ export class ChannelRegistry {
         (existing.descriptor.metadata as { lazyRegistered?: boolean } | undefined)?.lazyRegistered &&
         label && existing.descriptor.label === channelId
       ) {
-        existing.descriptor.label = label;
-        if (extraMetadata) {
-          existing.descriptor.metadata = { ...existing.descriptor.metadata, ...extraMetadata };
-        }
+        const metadata = extraMetadata
+          ? { ...existing.descriptor.metadata, ...extraMetadata }
+          : existing.descriptor.metadata;
         // The channel now has a real label, not just the bare id — durable.
-        this.appendLabelSighting(
-          existing.descriptor.id,
-          existing.descriptor.label,
-          extractDmMeta(existing.descriptor.metadata),
-        );
+        // Recorded before the live descriptor takes it, since this branch's
+        // guard reads the descriptor: an append that throws leaves the
+        // placeholder, so the next push tries again.
+        this.appendLabelSighting(existing.descriptor.id, label, extractDmMeta(metadata));
+        existing.descriptor.label = label;
+        existing.descriptor.metadata = metadata;
       }
       return;
     }
 
+    // Only persist a REAL label durably. Falling back to the bare
+    // channelId as a placeholder (no server-supplied label at all — e.g. a
+    // Discord DM push missing both channelName and an author name,
+    // framework.ts's derivePushEventChannel) must never overwrite a real
+    // label already on file from a previous boot: after a restart the live
+    // `channels` map starts empty, so THIS is the very branch a
+    // label-less post-restart event takes — recording the placeholder here
+    // would clobber the good label initializeLabelHistoryStore() just
+    // replayed, defeating the entire point of the durable log. The live
+    // descriptor below still carries the placeholder for in-process
+    // routing; only the durable write is skipped when there's no real
+    // label to record. A real label is recorded before the entry exists:
+    // an append that throws registers nothing, so the next push tries again.
+    if (label) this.appendLabelSighting(channelId, label, extractDmMeta(extraMetadata));
     const key = `${serverId}:${channelId}`;
     this.channels.set(key, {
       serverId,
@@ -1103,19 +1286,6 @@ export class ChannelRegistry {
       },
       open: false,
     });
-    // Only persist a REAL label durably. Falling back to the bare
-    // channelId as a placeholder (no server-supplied label at all — e.g. a
-    // Discord DM push missing both channelName and an author name,
-    // framework.ts's derivePushEventChannel) must never overwrite a real
-    // label already on file from a previous boot: after a restart the live
-    // `channels` map starts empty, so THIS is the very branch a
-    // label-less post-restart event takes — recording the placeholder here
-    // would clobber the good label initializeLabelHistoryStore() just
-    // replayed, defeating the entire point of the durable log. The live
-    // descriptor above still carries the placeholder for in-process
-    // routing; only the durable write is skipped when there's no real
-    // label to record.
-    if (label) this.appendLabelSighting(channelId, label, extractDmMeta(extraMetadata));
     this.emitTraceFn({
       type: 'mcpl:channel-lazy-registered',
       serverId,
@@ -1250,6 +1420,13 @@ export class ChannelRegistry {
     return this.findChannelEntry(channelId)?.descriptor;
   }
 
+  /** The registered label of `channelId` on exactly `serverId` (no
+   *  cross-server first match), or undefined when it has none. */
+  getChannelLabel(serverId: string, channelId: string): string | undefined {
+    const label = this.channels.get(`${serverId}:${channelId}`)?.descriptor.label;
+    return typeof label === 'string' && label.length > 0 ? label : undefined;
+  }
+
   isChannelOpen(channelId: string): boolean {
     return this.findChannelEntry(channelId)?.open === true;
   }
@@ -1279,7 +1456,7 @@ export class ChannelRegistry {
    * Get synthesized tool definitions for channel operations.
    */
   getChannelTools(): ToolDefinition[] {
-    return CHANNEL_TOOL_DEFINITIONS;
+    return this.channelTools;
   }
 
   /**
@@ -1340,7 +1517,7 @@ export class ChannelRegistry {
         return this.handleToolJournal(input as { content?: string });
 
       case 'skip_reply':
-        return this.handleToolSkipReply(input as { reason?: string; wake_in_seconds?: number });
+        return this.handleToolSkipReply(input as { reason?: string; wake_in_seconds?: unknown });
 
       default:
         return { success: false, error: `Unknown channel tool: ${toolName}`, isError: true };
@@ -1361,8 +1538,9 @@ export class ChannelRegistry {
 
     // Resolve the outbound locus the SAME way routeSpeech does, so the agent is
     // told the channel its speech will actually land in: a conversation fork's
-    // home channel, else this turn's triggering channel (single trunk agent —
-    // item-3 redux), else the global default (heartbeats). Without this, a fork
+    // home channel, else this turn's channel (single trunk agent — item-3
+    // redux: its locus, else its triggering channel), else the global default
+    // (heartbeats). Without this, a fork
     // was advertised the global locus but published somewhere else; and a trunk
     // agent was told the wrong channel under concurrency.
     const home = agentName ? this.homeChannelResolver?.(agentName) : undefined;
@@ -1454,13 +1632,7 @@ export class ChannelRegistry {
   private initializeLifecycleStore(): void {
     if (!this.store) return;
 
-    try {
-      this.store.registerState({ id: CHANNEL_LIFECYCLE_LOG_ID, strategy: 'append_log' });
-    } catch (error) {
-      if (!(error instanceof Error) || !error.message.includes('State already exists')) {
-        throw error;
-      }
-    }
+    ensureStateRegistered(this.store, { id: CHANNEL_LIFECYCLE_LOG_ID, strategy: 'append_log' });
 
     const raw = this.store.getStateJson(CHANNEL_LIFECYCLE_LOG_ID);
     if (!Array.isArray(raw)) return;
@@ -1503,6 +1675,15 @@ export class ChannelRegistry {
     }
   }
 
+  /**
+   * Each writer appends its record here before it changes memory for it, so
+   * an append that throws, as on a full disk, fails the operation with that
+   * change unmade, and memory and the log still agree. A retry then records
+   * the change rather than finding it in memory already, where
+   * setDesiredState's same-state return would record nothing, and a restart
+   * replays what memory held. appendLabelSighting keeps the same order for
+   * the label history.
+   */
   private appendLifecycleEvent(event: ChannelLifecycleEvent): void {
     this.store?.appendToStateJson(CHANNEL_LIFECYCLE_LOG_ID, event);
   }
@@ -1521,13 +1702,7 @@ export class ChannelRegistry {
   private initializeLabelHistoryStore(): void {
     if (!this.store) return;
 
-    try {
-      this.store.registerState({ id: CHANNEL_LABEL_HISTORY_LOG_ID, strategy: 'append_log' });
-    } catch (error) {
-      if (!(error instanceof Error) || !error.message.includes('State already exists')) {
-        throw error;
-      }
-    }
+    ensureStateRegistered(this.store, { id: CHANNEL_LABEL_HISTORY_LOG_ID, strategy: 'append_log' });
 
     const raw = this.store.getStateJson(CHANNEL_LABEL_HISTORY_LOG_ID);
     if (!Array.isArray(raw)) return;
@@ -1608,6 +1783,16 @@ export class ChannelRegistry {
     const recipientNameUnchanged = recipientName === undefined || recipientName === this.dmRecipientNames.get(channelId);
     const isDmUnchanged = isDm === undefined || this.dmClassified.get(channelId) === true;
     if (labelUnchanged && recipientIdUnchanged && recipientNameUnchanged && isDmUnchanged) return;
+    // The log first, as for lifecycle events: an append that throws leaves
+    // the history in memory as it was, so the next sighting records it.
+    this.store?.appendToStateJson(CHANNEL_LABEL_HISTORY_LOG_ID, {
+      channelId,
+      label,
+      ts: Date.now(),
+      ...(recipientId ? { recipientId } : {}),
+      ...(recipientName ? { recipientName } : {}),
+      ...(isDm ? { isDm } : {}),
+    } satisfies ChannelLabelSightingEvent);
     this.labelHistory.set(channelId, label);
     let seen = this.allLabelsSeen.get(channelId);
     if (!seen) {
@@ -1618,14 +1803,6 @@ export class ChannelRegistry {
     if (recipientId) this.dmRecipientIds.set(channelId, recipientId);
     if (recipientName) this.dmRecipientNames.set(channelId, recipientName);
     if (isDm) this.dmClassified.set(channelId, true);
-    this.store?.appendToStateJson(CHANNEL_LABEL_HISTORY_LOG_ID, {
-      channelId,
-      label,
-      ts: Date.now(),
-      ...(recipientId ? { recipientId } : {}),
-      ...(recipientName ? { recipientName } : {}),
-      ...(isDm ? { isDm } : {}),
-    } satisfies ChannelLabelSightingEvent);
   }
 
   /**
@@ -1850,7 +2027,6 @@ export class ChannelRegistry {
   ): void {
     const key = this.lifecycleKey(serverId, channelId);
     if (this.desiredStates.get(key)?.state === desired) return;
-    this.desiredStates.set(key, { state: desired, source });
     this.appendLifecycleEvent({
       kind: 'desired-state',
       serverId,
@@ -1859,6 +2035,7 @@ export class ChannelRegistry {
       source,
       timestamp: new Date().toISOString(),
     });
+    this.desiredStates.set(key, { state: desired, source });
   }
 
   // ==========================================================================
@@ -1878,12 +2055,6 @@ export class ChannelRegistry {
     source: string,
   ): void {
     const key = this.lifecycleKey(serverId, channelId);
-    this.desiredStates.set(key, {
-      state: 'tuned-out',
-      source,
-      tuneOut: params,
-      wakeCount: 0,
-    });
     this.appendLifecycleEvent({
       kind: 'desired-state',
       serverId,
@@ -1893,6 +2064,12 @@ export class ChannelRegistry {
       source,
       timestamp: new Date().toISOString(),
     });
+    this.desiredStates.set(key, {
+      state: 'tuned-out',
+      source,
+      tuneOut: params,
+      wakeCount: 0,
+    });
   }
 
   /**
@@ -1911,7 +2088,6 @@ export class ChannelRegistry {
     const current = this.desiredStates.get(key);
     if (current?.state !== 'tuned-out' || !current.tuneOut) return null;
     const ended = { params: current.tuneOut, wakeCount: current.wakeCount ?? 0 };
-    this.desiredStates.set(key, { state: nextState, source });
     this.appendLifecycleEvent({
       kind: 'desired-state',
       serverId,
@@ -1920,6 +2096,7 @@ export class ChannelRegistry {
       source,
       timestamp: new Date().toISOString(),
     });
+    this.desiredStates.set(key, { state: nextState, source });
     return ended;
   }
 
@@ -1937,16 +2114,17 @@ export class ChannelRegistry {
     const key = this.lifecycleKey(serverId, channelId);
     const current = this.desiredStates.get(key);
     if (current?.state !== 'tuned-out' || !current.tuneOut) return null;
-    current.wakeCount = (current.wakeCount ?? 0) + 1;
+    const wakeCount = (current.wakeCount ?? 0) + 1;
     this.appendLifecycleEvent({
       kind: 'tune-out-wake',
       serverId,
       channelId,
       epochId: current.tuneOut.epochId,
-      wakeCount: current.wakeCount,
+      wakeCount,
       timestamp: new Date().toISOString(),
     });
-    return { params: current.tuneOut, wakeCount: current.wakeCount };
+    current.wakeCount = wakeCount;
+    return { params: current.tuneOut, wakeCount };
   }
 
   /** Active tune-out params + wake count for a channel, or null. */
@@ -1974,17 +2152,13 @@ export class ChannelRegistry {
    */
   readCoordinatorState(stateId: string): unknown {
     if (!this.store) return null;
-    try {
-      this.store.registerState({ id: stateId, strategy: 'snapshot' });
-    } catch { /* already registered */ }
+    ensureStateRegistered(this.store, { id: stateId, strategy: 'snapshot' });
     return this.store.getStateJson(stateId);
   }
 
   writeCoordinatorState(stateId: string, value: unknown): void {
     if (!this.store) return;
-    try {
-      this.store.registerState({ id: stateId, strategy: 'snapshot' });
-    } catch { /* already registered */ }
+    ensureStateRegistered(this.store, { id: stateId, strategy: 'snapshot' });
     this.store.setStateJson(stateId, value);
   }
 
@@ -2021,13 +2195,13 @@ export class ChannelRegistry {
       this.setDesiredState(serverId, channel.id, desired, 'legacy-recipe-migration');
     }
 
-    this.migratedLegacyPolicies.add(serverId);
     this.appendLifecycleEvent({
       kind: 'legacy-policy-migrated',
       serverId,
       source: Array.isArray(policy) ? 'allow-list' : policy,
       timestamp: new Date().toISOString(),
     });
+    this.migratedLegacyPolicies.add(serverId);
   }
 
   /**
@@ -2156,9 +2330,9 @@ export class ChannelRegistry {
       }
     }
 
-    // Announce policy admissions to the agent — nothing may start flowing
-    // traffic into their window without them being told, and told how to
-    // opt out (channel_close; their decision outranks policy).
+    // Announce policy admissions to the agent — no channel may open without
+    // them being told, and told how to opt out (channel_close; their
+    // decision outranks policy).
     if (policyOpened.length > 0) {
       try {
         this.onChannelAutoOpened?.({
@@ -2575,11 +2749,13 @@ export class ChannelRegistry {
     // A tuned-out channel is transport-open but attention-diverted; a plain
     // open would silently discard the epoch (and its pending backlog dump).
     // Cancelling is the tune-out coordinator's flow, reached via its own
-    // tool — refuse with the pointer rather than eat the state.
+    // tool — refuse with the pointer rather than eat the state. As an error
+    // result, the agent reads the pointer itself; `data` names the refusal
+    // for an in-process caller.
     if (this.getDesiredState(entry.serverId, input.channelId) === 'tuned-out') {
       return {
         success: false,
-        isError: false,
+        isError: true,
         error:
           `Channel ${input.channelId} is tuned out. Cancel the tune-out ` +
           `(tune_out with mode: 'cancel') to resume normal attention — ` +
@@ -2750,7 +2926,7 @@ export class ChannelRegistry {
     if (entry.open || this.getDesiredState(entry.serverId, input.channelId) === 'open') {
       return {
         success: false,
-        error: `Channel is already open: ${input.channelId}. Use channel_close to leave it.`,
+        error: `Channel is already open: ${input.channelId}. Use channel_close to close it.`,
         isError: true,
       };
     }
@@ -2858,14 +3034,15 @@ export class ChannelRegistry {
    * tool, so any trailing prose this turn is NOT posted. Replaces the old
    * overloaded use of `think` for staying silent.
    */
-  private handleToolSkipReply(input: { reason?: string; wake_in_seconds?: number }): ToolResult {
+  private handleToolSkipReply(input: { reason?: string; wake_in_seconds?: unknown }): ToolResult {
     // The self-wake itself is armed by the framework (which owns the
-    // EventGate) BEFORE this dispatch; when the gate is absent the framework
-    // strips the field so this confirmation stays truthful.
-    const wakeSecs = Number(input.wake_in_seconds);
-    const selfWake = Number.isFinite(wakeSecs) && wakeSecs > 0
-      ? Math.max(1, Math.min(3600, Math.floor(wakeSecs)))
-      : undefined;
+    // EventGate) BEFORE its dispatch reaches this handler, from the same
+    // reading, and the framework refuses a wake the host can't set before
+    // dispatching. A caller of this registry's handleChannelToolCall
+    // (AgentFramework.channels) goes past both, so its note names a wake
+    // nothing armed.
+    const wake = readSkipReplyWake(input);
+    const selfWake = wake.kind === 'wake' ? wake.seconds : undefined;
     return {
       success: true,
       // The note says "ended the turn" — make it TRUE. Without endTurn the
@@ -2961,7 +3138,179 @@ export class ChannelRegistry {
     return home ?? this.activeChannelResolver?.(conversationId) ?? this.defaultPublishChannel ?? null;
   }
 
-  async routeSpeech(
+  /**
+   * Resolve a publish target to exactly one registered channel: `serverId`
+   * plus `channelId` when the caller has the server, otherwise a channel id
+   * registered by exactly one server. A shared id is refused, never resolved
+   * to whichever server registered it first.
+   */
+  resolveDestination(
+    target: { serverId?: string; channelId: string },
+  ): { destination: PublishDestination } | { error: string } {
+    const entry = this.findExactEntry(target);
+    if ('error' in entry) return entry;
+    return {
+      destination: {
+        serverId: entry.entry.serverId,
+        channelId: entry.entry.descriptor.id,
+        ...(entry.entry.descriptor.label ? { label: entry.entry.descriptor.label } : {}),
+      },
+    };
+  }
+
+  private findExactEntry(
+    target: { serverId?: string; channelId: string },
+  ): { entry: ChannelEntry } | { error: string } {
+    // A supplied selector is checked, never read as omission: an empty or
+    // non-string serverId would otherwise widen to "any server".
+    if (typeof target.channelId !== 'string' || !target.channelId) {
+      return { error: 'the destination names no channel id' };
+    }
+    if (target.serverId !== undefined && (typeof target.serverId !== 'string' || !target.serverId)) {
+      return { error: 'serverId must name a server (omit it to resolve the channel id alone)' };
+    }
+    const matches = [...this.channels.values()].filter(
+      (e) => e.descriptor.id === target.channelId && (!target.serverId || e.serverId === target.serverId),
+    );
+    if (matches.length === 0) {
+      return {
+        error: target.serverId
+          ? `no registered channel "${target.channelId}" on server "${target.serverId}"`
+          : `no registered channel "${target.channelId}"`,
+      };
+    }
+    if (matches.length > 1) {
+      return {
+        error: `channel id "${target.channelId}" is registered by more than one MCPL server; the destination must name its server`,
+      };
+    }
+    return { entry: matches[0]! };
+  }
+
+  /**
+   * Publish `text` to one registered channel and report what the attempt
+   * established (PublishOutcome). The delivery executor behind plain speech
+   * (deliverSpeech / routeSpeech) and resident resends of held drafts.
+   * channel_publish (and publishForAgent, which shares its handler) resolves
+   * and sends on its own path, and reads its answer through the same
+   * publishReceiptOutcome and publishErrorOutcome.
+   *
+   * Resolution is exact (resolveDestination): `serverId` plus `channelId`
+   * when the caller has the server, otherwise the channel id must be
+   * registered by exactly one server (a shared id is refused, never routed
+   * through whichever server came first). An omitted `serverId` means "not
+   * in use"; a supplied one must be a non-empty server id, and an empty or
+   * non-string selector is refused rather than read as omission. It is not
+   * possible to send into a closed channel: a closed but registered
+   * destination is opened first (`openSource` names why), once its server
+   * and that server's channels.publish grant are known to take the send, so
+   * a refused send opens nothing; and a failed open sends nothing.
+   *
+   * Only the connector's `delivered: true` confirms a post. `failed` means
+   * nothing was posted: the attempt stopped before the request was written,
+   * or the connector answered `delivered: false` and named no message (no
+   * `messageId`, or null). Everything else is `unknown`: once the request
+   * has been handed to the transport, an error response, a timeout, a lost
+   * connection, or a missing, malformed or contradictory receipt (such as
+   * `delivered: false` beside a message id, valid or not) means the post may
+   * or may not exist, and the caller must not treat it as safe to retry
+   * blindly.
+   */
+  async publish(
+    conversationId: string,
+    text: string,
+    target: {
+      serverId?: string;
+      channelId: string;
+      /** Set by speech routing (deliverSpeech): opening a closed channel
+       *  for this publish is logged under `[routeSpeech]`, with speech
+       *  routing's other lines. */
+      routed?: boolean;
+    },
+    openSource: 'opened-by-delivery' | 'opened-by-reply' = 'opened-by-delivery',
+  ): Promise<PublishOutcome> {
+    const at = (): number => Date.now();
+    const found = this.findExactEntry(target);
+    if ('error' in found) return { status: 'failed', reason: found.error, at: at() };
+    const entry = found.entry;
+    const destination: PublishDestination = {
+      serverId: entry.serverId,
+      channelId: entry.descriptor.id,
+      ...(entry.descriptor.label ? { label: entry.descriptor.label } : {}),
+    };
+
+    // A send that would be refused is refused before anything opens: a
+    // closed channel opens only for words that can go out.
+    const server = this.serverRegistry.getServer(entry.serverId);
+    if (!server) {
+      return { status: 'failed', destination, reason: `server "${entry.serverId}" not found`, at: at() };
+    }
+    // §14.1: channels/publish requires channels.publish in the grant. The
+    // host not sending is the enforcement.
+    if (!CapabilityGrant.of(server).has('channels.publish')) {
+      return {
+        status: 'failed',
+        destination,
+        reason: `channels.publish not in "${entry.serverId}"'s effective grant (§14.1)`,
+        at: at(),
+      };
+    }
+
+    if (!entry.open) {
+      try {
+        await this.openChannelNow(entry, openSource);
+        if (target.routed) {
+          console.error(
+            `[routeSpeech] ${conversationId}: locus ${logValue(entry.descriptor.id)} was closed — opened by delivery (speech implies engagement)`,
+          );
+        }
+        this.emitTraceFn({
+          type: 'mcpl:channel-opened-by-send',
+          serverId: entry.serverId,
+          channelId: entry.descriptor.id,
+        });
+        if (openSource === 'opened-by-delivery') {
+          try {
+            this.onChannelAutoOpened?.({
+              conversationId,
+              serverId: entry.serverId,
+              source: 'opened-by-delivery',
+              channels: [{ channelId: entry.descriptor.id, label: entry.descriptor.label }],
+            });
+          } catch (err) {
+            console.error('onChannelAutoOpened (delivery) failed:', err);
+          }
+        }
+      } catch (err) {
+        return {
+          status: 'failed',
+          destination,
+          reason: `channel is closed and open failed: ${connectorText(err instanceof Error ? err.message : String(err))}`,
+          at: at(),
+        };
+      }
+    }
+
+    let result: unknown;
+    try {
+      result = await server.sendChannelsPublish({
+        conversationId,
+        channelId: entry.descriptor.id,
+        content: [{ type: 'text', text }],
+      });
+    } catch (err) {
+      return publishErrorOutcome(err, destination, at());
+    }
+    return publishReceiptOutcome(result, destination, at());
+  }
+
+  /**
+   * Plain speech for one turn segment: publish `text` to the turn's frozen
+   * locus and report the PublishOutcome. A failure (or an uncertain outcome)
+   * is surfaced as a trace and through onRouteFailure, so the agent learns
+   * its words did not (or may not have) reached anyone.
+   */
+  async deliverSpeech(
     conversationId: string,
     text: string,
     /** The turn's FROZEN locus, snapshotted once by the caller (resolveLocus
@@ -2972,118 +3321,82 @@ export class ChannelRegistry {
      *  PR #32, and the 2026-07-22 Sol DM misroute). Explicit `null` means
      *  "this turn is pinned to no locus": fail loudly rather than guess. */
     locusChannelId: string | null,
-  ): Promise<{ delivered: boolean; channelId: string; messageId?: string } | null> {
-    // Surface a routing failure: emit a trace AND notify the host (which drops
-    // a `[discord-send-failed]` marker into chronicle) so the agent learns her
-    // reply never reached the human, instead of it vanishing silently.
-    const fail = (channelId: string | null, reason: string): null => {
-      console.error(`[routeSpeech] ${conversationId}: ${reason} — speech NOT routed (${text.length} chars stay in chronicle)`);
+    /** `heldOnFailure`: the caller holds a `failed` delivery's words as a
+     *  draft with its own notice, so no failure marker is written for it.
+     *  An `unknown` outcome still gets its marker. */
+    opts?: { heldOnFailure?: boolean },
+  ): Promise<PublishOutcome> {
+    const fail = (channelId: string | null, reason: string, outcome: PublishOutcome): PublishOutcome => {
+      const status = outcome.status === 'unknown' ? 'unknown' : 'failed';
+      const detail = outcome.detail !== undefined ? connectorText(outcome.detail) : undefined;
+      const detailText = detail !== undefined ? `; connector detail: ${detail}` : '';
+      console.error(`[routeSpeech] ${conversationId}: ${reason}${detailText} — speech ${status === 'unknown' ? 'delivery NOT confirmed' : 'NOT routed'} (${text.length} chars stay in chronicle)`);
       this.emitTraceFn({
         type: 'mcpl:speech-route-failed',
         conversationId,
         channelId: channelId ?? '',
         reason,
         textLen: text.length,
+        outcome: status,
+        ...(detail !== undefined ? { detail } : {}),
       });
-      this.onRouteFailure?.({ conversationId, channelId, reason, textLen: text.length });
-      return null;
+      if (status === 'unknown' || !opts?.heldOnFailure) {
+        this.onRouteFailure?.({ conversationId, channelId, reason, textLen: text.length, outcome: status, ...(detail !== undefined ? { detail } : {}) });
+      }
+      return outcome;
     };
 
     // Runtime backstop for JS callers the compiler can't see: an omitted
     // locus is a routing bug at the call site, never something to paper over
     // with a live re-resolution.
     if (locusChannelId === undefined) {
-      return fail(null, 'caller passed no locus (routing bug: every speech path must snapshot the turn locus)');
+      const reason = 'caller passed no locus (routing bug: every speech path must snapshot the turn locus)';
+      return fail(null, reason, { status: 'failed', reason, at: Date.now() });
     }
-    const channelId = locusChannelId;
-    if (!channelId) {
+    if (!locusChannelId) {
       // The turn froze with no locus (no home, no triggering channel, no
       // global inbound ever seen) — the agent was told its prose stays in
       // the archive; honor that.
-      return fail(null, 'turn has no locus (no home/trigger channel; nothing to deliver into)');
+      const reason = 'turn has no locus (no home/trigger channel; nothing to deliver into)';
+      return fail(null, reason, { status: 'failed', reason, at: Date.now() });
     }
 
-    const entry = this.findChannelEntry(channelId);
-    if (!entry) {
-      return fail(channelId, `no registered channel for locus "${channelId}"`);
+    const outcome = await this.publish(conversationId, text, { channelId: locusChannelId, routed: true });
+    const channelId = outcome.destination?.channelId ?? locusChannelId;
+    if (outcome.status !== 'delivered') {
+      return fail(channelId, outcome.reason ?? 'delivery not confirmed', outcome);
     }
 
-    // INVARIANT: it is not possible to send into a closed channel. Speech
-    // routed into a closed-but-registered locus (the canonical case: a DM
-    // that woke the agent — DMs register closed) OPENS the channel first,
-    // so typing indicators, reaction machinery, and inbound forwarding come
-    // alive with the reply. If the open fails, the speech does NOT go out:
-    // a half-alive delivery is worse than a loud marker.
-    if (!entry.open) {
-      try {
-        await this.openChannelNow(entry, 'opened-by-delivery');
-        console.error(
-          `[routeSpeech] ${conversationId}: locus ${channelId} was closed — opened by delivery (speech implies engagement)`,
-        );
-        this.emitTraceFn({
-          type: 'mcpl:channel-opened-by-send',
-          serverId: entry.serverId,
-          channelId,
-        });
-        try {
-          this.onChannelAutoOpened?.({
-            conversationId,
-            serverId: entry.serverId,
-            source: 'opened-by-delivery',
-            channels: [{ channelId, label: entry.descriptor.label }],
-          });
-        } catch (err) {
-          console.error('onChannelAutoOpened (delivery) failed:', err);
-        }
-      } catch (err) {
-        return fail(channelId, `locus channel is closed and open failed: ${(err as Error).message}`);
-      }
-    }
-
-    const server = this.serverRegistry.getServer(entry.serverId);
-    if (!server) {
-      return fail(channelId, `server "${entry.serverId}" not found`);
-    }
-    // §14.1: channels/publish requires channels.publish in the grant. The
-    // host not sending is the enforcement — a send to an ungranted server
-    // would have it act on authority it was never told it has.
-    if (!CapabilityGrant.of(server).has('channels.publish')) {
-      return fail(channelId, `channels.publish not in "${entry.serverId}"'s effective grant (§14.1)`);
-    }
-
-    const publishParams: ChannelsPublishParams = {
-      conversationId,
-      channelId,
-      content: [{ type: 'text', text }],
-    };
-    const result = await server.sendChannelsPublish(publishParams);
-    const delivered = (result as { delivered?: boolean } | undefined)?.delivered ?? true;
-    // Surface the posted message's id (ChannelsPublishResult.messageId) so
-    // trace consumers can act on the just-posted message — e.g. a TTS-relay
-    // tap editing it down to the words actually voiced on interruption.
-    // Previously this was silently dropped here.
-    const messageId = (result as { messageId?: string } | undefined)?.messageId;
-
-    // The server accepted the publish RPC but reported the message was not
-    // actually delivered (e.g. missing Send Messages permission). Previously
-    // this returned `{ delivered: true }`, masking the failure. Surface it.
-    if (delivered === false) {
-      return fail(channelId, `server "${entry.serverId}" reported delivered:false for "${channelId}"`);
-    }
-
-    console.error(`[routeSpeech] ${conversationId}: routed ${text.length} chars -> ${channelId} (server=${entry.serverId}, delivered=${delivered})`);
+    console.error(`[routeSpeech] ${conversationId}: routed ${text.length} chars -> ${logValue(channelId)} (server=${outcome.destination!.serverId}, delivered=true)`);
     this.emitTraceFn({
       type: 'mcpl:speech-routed',
       conversationId,
-      serverId: entry.serverId,
+      serverId: outcome.destination!.serverId,
       channelId,
-      delivered,
+      delivered: true,
       textLen: text.length,
       text,
-      ...(messageId !== undefined ? { messageId } : {}),
+      // Surface the posted message's id (ChannelsPublishResult.messageId) so
+      // trace consumers can act on the just-posted message — e.g. a TTS-relay
+      // tap editing it down to the words actually voiced on interruption.
+      ...(outcome.messageId !== undefined ? { messageId: outcome.messageId } : {}),
     });
+    return outcome;
+  }
 
-    return { delivered, channelId, ...(messageId !== undefined ? { messageId } : {}) };
+  /** deliverSpeech, reduced to the confirmed delivery (null when there was none). */
+  async routeSpeech(
+    conversationId: string,
+    text: string,
+    locusChannelId: string | null,
+  ): Promise<{ delivered: boolean; channelId: string; messageId?: string } | null> {
+    const outcome = await this.deliverSpeech(conversationId, text, locusChannelId);
+    if (outcome.status !== 'delivered') return null;
+    return {
+      delivered: true,
+      channelId: outcome.destination!.channelId,
+      ...(outcome.messageId !== undefined ? { messageId: outcome.messageId } : {}),
+    };
   }
 
   private async handleToolPublish(input: { channelId?: string; content?: string; text?: string }): Promise<ToolResult> {
@@ -3125,31 +3438,44 @@ export class ChannelRegistry {
       };
     }
 
-    try {
-      if (!CapabilityGrant.of(server).has('channels.publish')) {
-        return {
-          success: false,
-          error: `channels.publish not in "${server.id}"'s effective grant (§14.1)`,
-          isError: true,
-        };
-      }
-      const publishParams: ChannelsPublishParams = {
-        conversationId: '', // Framework will fill this when wired
-        channelId,
-        content: [{ type: 'text', text: messageText }],
-      };
-
-      const result = await server.sendChannelsPublish(publishParams);
-      return {
-        success: true,
-        data: result ?? { delivered: true },
-      };
-    } catch (err) {
+    if (!CapabilityGrant.of(server).has('channels.publish')) {
       return {
         success: false,
-        error: `Failed to publish to channel: ${(err as Error).message}`,
+        error: `channels.publish not in "${server.id}"'s effective grant (§14.1)`,
         isError: true,
       };
     }
+    const publishParams: ChannelsPublishParams = {
+      conversationId: '', // Framework will fill this when wired
+      channelId,
+      content: [{ type: 'text', text: messageText }],
+    };
+    const destination: PublishDestination = {
+      serverId: entry.serverId,
+      channelId: entry.descriptor.id,
+      ...(entry.descriptor.label ? { label: entry.descriptor.label } : {}),
+    };
+
+    // The answer counts by the same rule as plain speech's: only the
+    // connector's delivered:true confirms a post.
+    let result: unknown;
+    let outcome: PublishOutcome;
+    try {
+      result = await server.sendChannelsPublish(publishParams);
+      outcome = publishReceiptOutcome(result, destination, Date.now());
+    } catch (err) {
+      outcome = publishErrorOutcome(err, destination, Date.now());
+    }
+    if (outcome.status === 'delivered') return { success: true, data: result };
+    // The connector's data may say what a multi-part send already posted.
+    const detail = outcome.status === 'unknown' && outcome.detail !== undefined ? ` Connector detail: ${connectorText(outcome.detail)}` : '';
+    return {
+      success: false,
+      error: (outcome.status === 'failed'
+        ? `Publish to ${channelId} failed: ${outcome.reason}. Nothing was posted.`
+        : `Publish to ${channelId} wasn't confirmed: ${outcome.reason}. ` +
+          'It may or may not have been posted, so sending it again could post it twice.') + detail,
+      isError: true,
+    };
   }
 }