@animalabs/agent-framework 0.22.2 → 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,7 +31,6 @@ import type {
   ChannelsPublishParams,
   ChannelsOpenResult,
   ChannelHistoryRequest,
-  McplContentBlock,
 } from './types.js';
 
 import type { McplServerRegistry } from './server-registry.js';
@@ -38,10 +38,13 @@ import type { FeatureSetManager } from './feature-set-manager.js';
 import type { ToolDefinition, ToolResult, ProcessEvent } from '../types/index.js';
 import { expandCoreTags } from './tags.js';
 import { coalesceRejectionReason, EmptyContentError, validateCoalescedContent } from './push-coalescer.js';
-import { isVisiblyEmptyContent } from './visible-content.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)
@@ -239,88 +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':
-      // Text that isn't a string is no text, as the request sanitizer and
-      // the visible-content check already read it.
-      return { type: 'text', text: typeof block.text === 'string' ? 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 (isFilledString(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 (isFilledString(block.data) && isFilledString(block.mimeType)) {
-        return {
-          type: 'image',
-          source: { type: 'base64', data: block.data, mediaType: block.mimeType },
-        } as ContentBlock;
-      }
-      if (isFilledString(block.uri)) {
-        return {
-          type: 'image',
-          source: { type: 'url', url: block.uri },
-        } as ContentBlock;
-      }
-      return { type: 'text', text: isFilledString(block.data) ? '[Image: no media type]' : '[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 (isFilledString(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 (isFilledString(block.data) && isFilledString(block.mimeType)) {
-        return {
-          type: 'audio',
-          source: { type: 'base64', data: block.data, mediaType: block.mimeType },
-        } as ContentBlock;
-      }
-      return { type: 'text', text: isFilledString(block.data) ? '[Audio: no media type]' : '[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. A type
-      // that isn't a string is no type, and is never converted to one: an
-      // object can throw when it is.
-      const type: unknown = (block as { type?: unknown }).type;
-      return { type: 'text', text: `[unrecognized content block: ${typeof type === 'string' ? type : 'untyped'}]` };
-    }
-  }
-}
-
-/** A string with something in it: the only data, mimeType or uri a block's
- *  source is built from, and the only uri that makes it a reference. Anything
- *  else a sender puts there leaves the block without it, so conversion never
- *  throws and never copies a non-string. */
-function isFilledString(value: unknown): value is string {
-  return typeof value === 'string' && value !== '';
+  /** Host acceptance time (epoch ms), stamped where the message is admitted. */
+  acceptedAt?: number;
+  /** Source envelope frozen at admission (mcpl/inbound-source.ts). */
+  inboundSource?: InboundSource;
 }
 
 // ============================================================================
@@ -336,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: {
@@ -378,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: {
@@ -457,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: [],
@@ -470,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
@@ -499,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. */
@@ -543,6 +594,8 @@ interface ChannelRegistryOptions {
    * `defaultPublishChannel`.
    */
   activeChannelResolver?: (agentName: string) => string | undefined;
+  /** Whether this framework has EventGate and can honor skip_reply self-wakes. */
+  eventGatePresent?: boolean;
 }
 
 // ============================================================================
@@ -576,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;
@@ -680,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,
@@ -696,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;
@@ -1031,8 +1099,8 @@ export class ChannelRegistry {
         }
       }
       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;
       }
@@ -1060,7 +1128,7 @@ export class ChannelRegistry {
       if (this.shouldTriggerInference) {
         // 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, and a text block's non-string text as empty text.
+        // among them, NON_STRING_TEXT_PLACEHOLDER included.
         const textContent = convertedContent
           .filter((b): b is ContentBlock & { type: 'text' } => b.type === 'text')
           .map((b) => b.text)
@@ -1093,6 +1161,7 @@ export class ChannelRegistry {
         metadata: message.metadata,
         ...(message.tags ? { tags: message.tags } : {}),
         triggerInference,
+        acceptedAt: Date.now(),
       };
 
       if (coalesced) {
@@ -1118,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.
@@ -1171,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,
@@ -1197,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,
@@ -1344,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;
   }
@@ -1373,7 +1456,7 @@ export class ChannelRegistry {
    * Get synthesized tool definitions for channel operations.
    */
   getChannelTools(): ToolDefinition[] {
-    return CHANNEL_TOOL_DEFINITIONS;
+    return this.channelTools;
   }
 
   /**
@@ -1434,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 };
@@ -1549,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;
@@ -1598,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);
   }
@@ -1616,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;
@@ -1703,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) {
@@ -1713,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);
   }
 
   /**
@@ -1945,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,
@@ -1954,6 +2035,7 @@ export class ChannelRegistry {
       source,
       timestamp: new Date().toISOString(),
     });
+    this.desiredStates.set(key, { state: desired, source });
   }
 
   // ==========================================================================
@@ -1973,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,
@@ -1988,6 +2064,12 @@ export class ChannelRegistry {
       source,
       timestamp: new Date().toISOString(),
     });
+    this.desiredStates.set(key, {
+      state: 'tuned-out',
+      source,
+      tuneOut: params,
+      wakeCount: 0,
+    });
   }
 
   /**
@@ -2006,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,
@@ -2015,6 +2096,7 @@ export class ChannelRegistry {
       source,
       timestamp: new Date().toISOString(),
     });
+    this.desiredStates.set(key, { state: nextState, source });
     return ended;
   }
 
@@ -2032,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. */
@@ -2069,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);
   }
 
@@ -2116,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);
   }
 
   /**
@@ -2251,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?.({
@@ -2670,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 — ` +
@@ -2845,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,
       };
     }
@@ -2953,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
@@ -3056,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
@@ -3067,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 entry = this.findChannelEntry(channelId);
-    if (!entry) {
-      return fail(channelId, `no registered channel for locus "${channelId}"`);
-    }
-
-    // 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 ${logValue(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 reason = 'turn has no locus (no home/trigger channel; nothing to deliver into)';
+      return fail(null, reason, { status: 'failed', reason, at: Date.now() });
     }
 
-    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 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);
     }
 
-    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 -> ${logValue(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> {
@@ -3220,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,
+    };
   }
 }