@animalabs/agent-framework 0.28.0 → 0.30.0

package/src/mcpl/channel-registry.ts

@@ -13,8 +13,10 @@
  * - Build channel context for beforeInference params
  */
 
+import { NOTICE_TAG } from '../notice-tags.js';
 import type { ContentBlock } from '@animalabs/membrane';
-import { convertBlock } from './convert-block.js';
+import { convertBlocks } from './convert-block.js';
+import { cutToFit, markedText, markNoticeOpenings, nameToTypeBack, quotedValue, showsAsItself, suppliedValue } from '../supplied-text.js';
 import type { JsStore } from '@animalabs/chronicle';
 import { isDeepStrictEqual } from 'node:util';
 import { ensureStateRegistered } from '../module-registry.js';
@@ -45,7 +47,7 @@ import { RefusalLines } from './refusal-lines.js';
 import { CapabilityGrant } from './capability-grant.js';
 import type { InboundSource } from './inbound-source.js';
 import { McplRequestError, type McplServerConnection } from './server-connection.js';
-import { readSkipReplyWake } from './skip-reply-wake.js';
+import { readSkipReplyWake, skipReplyNote, type SkipReplyEarlierWake } from './skip-reply-wake.js';
 import { isProseTargetToken } from './prose-grammar.js';
 
 // ============================================================================
@@ -564,11 +566,11 @@ const CHANNEL_TOOL_DEFINITIONS: ToolDefinition[] = [
   },
   {
     name: 'channel_publish',
-    description: "Publish a message to a channel. If channelId is omitted, publishes to your conversation's channel if you are bound to one; otherwise to the channel of the most recent incoming message this host received on any channel, whether or not you've been shown it. Reactions, reaction removals, deletions and edits don't set it, though an edit of a message you hadn't been shown can count as that message. A message pushed to you rather than posted on a channel never sets it. A subagent has neither default, so it must name a channel.",
+    description: "Publish a message to a channel. If channelId is omitted, publishes where your plain speech goes this turn: your conversation's channel if you are bound to one; otherwise the channel of the message that woke this turn, or one you opened during it; otherwise, while a focus holds, the channel it keeps. Where none of those names a channel, nothing is posted, unless this host is set to use the channel of the latest incoming message instead. A turn with no channel of its own, such as a heartbeat's, has no default, so it names one. A subagent has no default, so it must name a channel.",
     inputSchema: {
       type: 'object' as const,
       properties: {
-        channelId: { type: 'string', description: "ID of the channel to publish to (defaults to your conversation's channel if you are bound to one; otherwise the channel of the most recent incoming message this host received on any channel, whether or not you've been shown it, other than a reaction, reaction removal, deletion or edit, though an edit of a message you hadn't been shown can count; a message pushed to you rather than posted on a channel never sets it; required of a subagent)" },
+        channelId: { type: 'string', description: "ID of the channel to publish to (defaults to where your plain speech goes this turn, as the tool's description says; required of a subagent)" },
         content: { type: 'string', description: 'Text content to publish' },
         text: { type: 'string', description: 'Alias for content' },
       },
@@ -643,19 +645,21 @@ 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`) as the
- *  connection gives it, its strings redacted (redactedData). */
+/** Bound connector values for notices, logs and an outcome's reason, on one
+ *  line with their notice openings marked (suppliedValue). A PublishOutcome
+ *  keeps the connector's structured data (`detail`) as the connection gives
+ *  it, its strings redacted (redactedData). */
 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]';
+    return `[${NOTICE_TAG.unserializableConnectorValue}]`;
   }
   const limit = 2000;
-  const suffix = '… [truncated]';
-  return text.length > limit ? text.slice(0, limit - suffix.length) + suffix : text;
+  const suffix = `… [${NOTICE_TAG.truncated}]`;
+  const shown = suppliedValue(text);
+  return shown.length > limit ? cutToFit(shown, limit - suffix.length) + suffix : shown;
 }
 
 /**
@@ -688,6 +692,9 @@ export function sameChannel(a: ChannelRef | null | undefined, b: ChannelRef | nu
   return a.serverId === b.serverId && a.channelId === b.channelId;
 }
 
+export const NO_CHANNEL_EXAMPLE = '#<channel>';
+export const NO_PERSON_EXAMPLE = '@<person>';
+
 /**
  * A channel's server-qualified name, `serverId:channelId`. A name given as a
  * string (a tool's channelId, a `>>` target, a host's call) may take this
@@ -699,12 +706,32 @@ export function qualifiedChannelName(ref: ChannelRef): string {
   return `${ref.serverId}:${ref.channelId}`;
 }
 
+function markedHistory(history: readonly unknown[]): unknown[] {
+  return history.map((item) => {
+    if (item === null || typeof item !== 'object' || Array.isArray(item) || !('content' in item)) return item;
+    const { content } = item as { content: unknown };
+    if (Array.isArray(content)) return { ...item, content: markNoticeOpenings(content.map(withEmbeddedTextMarked) as object[]) };
+    return typeof content === 'string' ? { ...item, content: markedText(content) } : item;
+  });
+}
+
+function withEmbeddedTextMarked(block: unknown): unknown {
+  if (block === null || typeof block !== 'object' || (block as { type?: unknown }).type !== 'resource') return block;
+  const { resource } = block as { resource?: unknown };
+  if (resource === null || typeof resource !== 'object' || typeof (resource as { text?: unknown }).text !== 'string') return block;
+  return { ...block, resource: { ...resource, text: markedText((resource as { text: string }).text) } };
+}
+
 /** A channel told apart by its id and its server, for one no string picks
- *  alone: `"b:room" on server "a"`. No input takes it for a name. */
+ *  alone or whose name wouldn't show as itself: `"b:room" on server "a"`,
+ *  each a JSON literal a channel tool's channelId and serverId take back
+ *  (quotedValue). No input takes the whole form for a name. */
 function channelOnServer(ref: ChannelRef): string {
-  return `${JSON.stringify(ref.channelId)} on server ${JSON.stringify(ref.serverId)}`;
+  return `${quotedValue(ref.channelId)} on server ${quotedValue(ref.serverId)}`;
 }
 
+const CHANNEL_ON_SERVER_AT_END = /("(?:[^"\\]|\\.)*") on server ("(?:[^"\\]|\\.)*")$/;
+
 /**
  * What one channels/publish attempt established (ChannelRegistry.publish).
  * - `delivered`: the connector returned `delivered: true`. A historical
@@ -965,8 +992,35 @@ interface ChannelRegistryOptions {
   ) => Promise<ChannelIncomingMessageResult & { firstView?: true }>;
   /** Chronicle store used for durable desired channel lifecycle state. */
   store?: JsStore;
-  /** Callback to determine whether an incoming message should trigger inference. */
+  /**
+   * The server-level veto on waking for an incoming message (a per-server
+   * `McplServerConfig.shouldTriggerInference`). The wake gate is NOT wired
+   * here: it runs in the framework's admission stage, after the hold
+   * decision, so a held message never forms a gate batch (issue #232 gap 3).
+   */
   shouldTriggerInference?: (content: string, metadata: Record<string, unknown>) => boolean;
+  /**
+   * Whether the most recent delivered inbound message is a fallback speech
+   * locus for turns that have none of their own (`speech.locus:
+   * 'latest-inbound'`). Off by default: incoming traffic never moves the
+   * locus (architecture channel, 2026-10-06).
+   */
+  latestInboundLocus?: boolean;
+  /**
+   * A channel is being closed by tool: an all-except hold whose exception
+   * this is ends through the cancel flow (release the backlog, record the
+   * end) before the lifecycle state flips to closed. A
+   * tuned-out channel's close is refused before this (its cancel ends it).
+   * Returns what it ended, in a sentence the close's answer adds when the
+   * close itself isn't recorded.
+   */
+  onToolClose?: (serverId: string, channelId: string) => string | undefined;
+  /**
+   * The channel unprefixed speech lands in while an all-except hold is
+   * active (its exception), else null. Consulted after a fork's home and
+   * the turn's own delivery, before the legacy fallback.
+   */
+  focusChannelResolver?: () => ChannelRef | null;
   /**
    * Called when a text-only turn's speech was not delivered to its
    * conversational locus (`failed`), or may not have been (`unknown`), for
@@ -1016,7 +1070,7 @@ interface ChannelRegistryOptions {
   /**
    * Resolve a conversation fork's HOME channel from its agent name. Conversation
    * forks are spawned bound to a single channel (the framework tracks this in
-   * `conversationAgentHomes` / `ConversationRouter.channelForAgent`); their
+   * the agent registry's `homeChannel` / `ConversationRouter.channelForAgent`); their
    * plain-text speech must route THERE. The process-global `defaultPublishChannel`
    * tracks only the most recent inbound message across ALL channels (reaction,
    * reaction-removal, edit and deletion markers aside, apart from an edit the
@@ -1089,6 +1143,14 @@ export type ChannelToolOrigin =
      *  name one of them answers to by its id means that channel
      *  (ChannelRegistry.ownChannelNamed). */
     own?: readonly ChannelRef[];
+    /** For a skip_reply whose self-wake the framework armed: the heartbeat's
+     *  wake due before it, when there is one, which its confirmation names
+     *  (skipReplyNote). */
+    earlierWake?: SkipReplyEarlierWake;
+    /** Made inside one of the agent's turns (the framework's callingTurnOf):
+     *  a channel_publish naming no channel arrives with that turn's default
+     *  already applied, so it takes no other. */
+    inTurn?: boolean;
   };
 
 /** The machine decision sources a module-origin channel_close may record.
@@ -1123,6 +1185,9 @@ export class ChannelRegistry {
     op?: 'start' | 'stop',
   ) => void;
   private shouldTriggerInference?: (content: string, metadata: Record<string, unknown>) => boolean;
+  private readonly latestInboundLocus: boolean;
+  private onToolClose?: (serverId: string, channelId: string) => string | undefined;
+  private focusChannelResolver?: () => ChannelRef | null;
   private onRouteFailure?: ChannelRegistryOptions['onRouteFailure'];
   private onChannelAutoOpened?: (info: {
     conversationId?: string;
@@ -1551,6 +1616,9 @@ export class ChannelRegistry {
     this.emitTraceFn = emitTraceFn;
     this.sendTypingFn = options?.sendTypingFn;
     this.shouldTriggerInference = options?.shouldTriggerInference;
+    this.latestInboundLocus = options?.latestInboundLocus === true;
+    this.onToolClose = options?.onToolClose;
+    this.focusChannelResolver = options?.focusChannelResolver;
     this.onRouteFailure = options?.onRouteFailure;
     this.onChannelAutoOpened = options?.onChannelAutoOpened;
     this.homeChannelResolver = options?.homeChannelResolver;
@@ -1792,9 +1860,6 @@ export class ChannelRegistry {
     // The batch came on the transport open now: a close after this point
     // (transportClosed) leaves its traffic nothing to confirm.
     const closesAtArrival = this.transportCloses.get(serverId) ?? 0;
-    // And came from a server registered now: one removed since (removeServer)
-    // gives no message the agent replies to (markAccepted).
-    const removalsAtArrival = this.serverRemovals.get(serverId) ?? 0;
 
     for (const message of params.messages) {
       if (!message || typeof message.channelId !== 'string' || !message.channelId
@@ -1894,34 +1959,25 @@ export class ChannelRegistry {
         }
       }
       if (message.tags) message.tags = expandCoreTags(message.tags);
-      const convertedContent: ContentBlock[] = message.content.map((block) => convertBlock(block, 'attachment on channel message', serverId));
+      const convertedContent: ContentBlock[] = convertBlocks(message.content, 'attachment on channel message', serverId);
       if (!emptyAllowed && isVisiblyEmptyConversion(message.content, convertedContent)) {
         rejectEmpty();
         continue;
       }
 
-      // Track default publish channel (most recent ACCEPTED incoming) —
-      // deliberately after §14.5 validation: a rejected message from an
-      // unregistered channel must not retarget outbound speech (the locus is
-      // exactly the authority a self-attested channel would be stealing).
-      // A coalesced item is "accepted" only once the coalescer admits it, so
-      // for those this runs after the hook (below).
+      // A server sending channels/incoming is evidence that the transport
+      // is open. This repairs transient status only; durable desired state
+      // still changes exclusively through lifecycle operations. Nothing else
+      // is decided here: whether this message is delivered, wakes anyone or
+      // counts as the latest inbound is the framework's admission decision,
+      // taken once the hold is known (see `noteDelivered`; issue #232 root
+      // cause A). A coalesced item is "accepted" only once the coalescer
+      // admits it, so for those this runs after the hook (below).
       const incomingEntry = this.channels.get(incomingKey)!;
-      const markAccepted = (firstView = false) => {
-        // Non-conversational markers (a reaction added or removed, an edit, a
-        // deletion, and a chat:system notice such as a join or the weather)
-        // are ABOUT a message or the place, not one the agent replies to: they
-        // must not retarget the default publish locus or become
-        // `context.incoming`'s reply anchor. An edit the coalescer delivered
-        // as the agent's first view counts as the message it replaced.
-        // A message the coalescer admits after its server was removed sets no
-        // default: the removal cleared that server's message, and a server
-        // that's gone mustn't displace a live one's default.
-        if (!isMarkerTagged(message.tags, firstView) && (this.serverRemovals.get(serverId) ?? 0) === removalsAtArrival) {
-          this.defaultPublishChannel = { serverId, channelId: message.channelId };
-          this.defaultPublishMessageId = message.messageId;
-          this.defaultPublishThreadId = message.threadId;
-        }
+      // `firstView` is the coalescer's mark that an edit was the agent's first
+      // view of its message; the registry no longer records the publish locus
+      // here (admission does, through noteDelivered, with the same marker rule).
+      const markAccepted = (_firstView = false) => {
         // Where the host directs this server's lifecycle, traffic shows the
         // transport open only for a channel still decided open or tuned out,
         // and, but for one exception, only for a confirmed target: after a
@@ -1956,7 +2012,7 @@ export class ChannelRegistry {
       };
       if (!coalesced) markAccepted();
 
-      // Determine whether to trigger inference
+      // The server-level veto only; the wake gate runs at admission.
       let triggerInference = true;
       if (this.shouldTriggerInference) {
         // The text the agent's context gets, as the push lane's filter reads
@@ -2258,16 +2314,58 @@ export class ChannelRegistry {
   // Accessors
   // ==========================================================================
 
+  /**
+   * The most recent DELIVERED inbound message (channel, message, thread).
+   * Recorded by the framework after admission, so a held message never
+   * becomes "the latest inbound" (issue #232 gap 2), and never for a marker
+   * (a reaction, reaction removal, edit or deletion, apart from an edit the
+   * coalescer delivered as the agent's first view: isMarkerTagged). Read as
+   * the `incoming` reference in the channel context and, under
+   * `speech.locus: 'latest-inbound'`, as the fallback speech locus. The
+   * channel is on the server the message came from. A message whose server
+   * no longer registers its channel sets nothing, as one the coalescer admits
+   * after its server was removed: the removal cleared that server's message,
+   * and a server that's gone mustn't displace a live one's anchor. That's
+   * read at admission, where main's guard compared the server's removal
+   * count at arrival and at acceptance (markAccepted): a message that
+   * arrived before its server's removal and is admitted once the server
+   * registers the channel again sets the anchor here, as a message delivered
+   * on a live channel, where main's would set nothing.
+   */
+  noteDelivered(channel: ChannelRef, messageId: string, threadId?: string, tags?: unknown, firstView = false): void {
+    // A marker is ABOUT a message, not one the agent replies to: it leaves
+    // the anchor where it was (#157), and so does a chat:system notice (a
+    // join, the weather), which is about the place (isMarkerTagged). An edit
+    // the coalescer delivered as the agent's first view of its message counts
+    // as that message.
+    if (isMarkerTagged(tags, firstView)) return;
+    if (!this.entryAt(channel)) return;
+    this.defaultPublishChannel = { serverId: channel.serverId, channelId: channel.channelId };
+    this.defaultPublishMessageId = messageId;
+    this.defaultPublishThreadId = threadId;
+  }
+
   /**
    * Get the default publish channel ID: the channel of the most recent
-   * incoming message that isn't a reaction, reaction removal, edit or
-   * deletion marker, apart from an edit the coalescer delivers on acceptance
-   * as the agent's first view.
+   * delivered incoming message that isn't a reaction, reaction removal, edit
+   * or deletion marker, apart from an edit the coalescer delivers on
+   * acceptance as the agent's first view.
    */
   getDefaultPublishChannel(): ChannelRef | null {
     return this.defaultPublishChannel;
   }
 
+  /**
+   * Public form of the tool-input channel resolution (resolveToolChannelEntry):
+   * optional server, the calling turn's own channels (`own`), ambiguity is an
+   * error.
+   */
+  resolveChannel(channelId: string, serverId?: string, own?: readonly ChannelRef[]): ChannelRef | { error: string } {
+    const resolved = this.resolveToolChannelEntry(channelId, serverId, own);
+    if (!resolved.entry) return { error: resolved.error ?? `Channel not found: ${channelId}` };
+    return { serverId: resolved.entry.serverId, channelId: resolved.entry.descriptor.id };
+  }
+
   /**
    * RFC-006 §3.2: is `channelId` registered BY `serverId` through a server
    * declaration (channels/register, channels/changed) or an authorized open?
@@ -2386,7 +2484,10 @@ export class ChannelRegistry {
         return this.handleToolJournal(input as { content?: string });
 
       case 'skip_reply':
-        return this.handleToolSkipReply(input as { reason?: string; wake_in_seconds?: unknown });
+        return this.handleToolSkipReply(
+          input as { reason?: string; wake_in_seconds?: unknown },
+          origin?.kind === 'agent' ? origin.earlierWake : undefined,
+        );
 
       default:
         // Not every agent is given every channel tool, so the refusal points
@@ -2405,7 +2506,7 @@ export class ChannelRegistry {
 
   /**
    * The message the agent is replying to, with its channel: the most recent
-   * inbound message that isn't a reaction, reaction removal, edit or deletion
+   * delivered inbound message (noteDelivered) that isn't a reaction, reaction removal, edit or deletion
    * marker, apart from an edit the coalescer delivers on acceptance as the
    * agent's first view. Left process-global: per-channel inbound tracking
    * (the right messageId for a fork's own channel) is a separate concern from
@@ -2422,9 +2523,13 @@ export class ChannelRegistry {
     if (agentName !== undefined && this.activeChannelResolver?.(agentName) === null && !this.homeChannelResolver?.(agentName)) {
       return undefined;
     }
-    const fallback = agentName !== undefined ? this.globalFallbackFor(agentName) : this.defaultPublishChannel;
-    if (!fallback || !this.defaultPublishMessageId) return undefined;
-    return { channel: fallback, messageId: this.defaultPublishMessageId, threadId: this.defaultPublishThreadId };
+    // The latest delivered inbound itself, not the speech fallback
+    // (globalFallbackFor), which under `speech.locus: 'delivery'` is the
+    // all-except hold's excepted channel while one is open, and none
+    // otherwise.
+    const anchor = agentName !== undefined && this.takesGlobalFallback?.(agentName) === false ? null : this.defaultPublishChannel;
+    if (!anchor || !this.defaultPublishMessageId) return undefined;
+    return { channel: anchor, messageId: this.defaultPublishMessageId, threadId: this.defaultPublishThreadId };
   }
 
   /**
@@ -2442,23 +2547,27 @@ export class ChannelRegistry {
     // declared it inbound-only, since speech isn't posted there): a conversation
     // fork's 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
+    // (a no-trigger turn's, but not a heartbeat's, whose turn takes none).
+    // Without this, a fork
     // was advertised the global locus but published somewhere else; and a trunk
     // agent was told the wrong channel under concurrency.
     // Each lookup is keyed on whether a name was given, not its truthiness:
     // '' is a name an ephemeral run can have, and resolveLocus reads it too.
     const home = agentName !== undefined ? this.homeChannelResolver?.(agentName) : undefined;
     const active = agentName !== undefined ? this.activeChannelResolver?.(agentName) : undefined;
-    // An ephemeral run takes no global fallback (takesGlobalFallback): neither
-    // the latest inbound message's channel as its outgoing one, nor that
-    // message as the one it is replying to.
-    const fallback = agentName !== undefined ? this.globalFallbackFor(agentName) : this.defaultPublishChannel;
+    // An ephemeral run takes no global fallback (takesGlobalFallback): not the
+    // all-except hold's channel, not the latest inbound message's channel as
+    // its outgoing one, nor that message as the one it is replying to.
+    const fallback = agentName !== undefined ? this.globalFallbackFor(agentName) : this.sharedFallback();
     // A turn that deliberately has no channel (null) takes no fallback.
     const outgoing = home ?? (active !== undefined ? active : fallback);
 
     const context: ChannelContext = {};
 
-    // Incoming: the message the agent is replying to (incomingFor).
+    // Incoming: the message the agent is replying to (incomingFor). The
+    // anchor is independent of the speech rule: under `speech.locus:
+    // 'delivery'` the latest inbound is no fallback for where prose lands,
+    // but it is still the message the agent is replying to.
     const incoming = this.incomingFor(agentName);
     if (incoming && incoming.channel.serverId === serverId) {
       context.incoming = {
@@ -3921,12 +4030,20 @@ export class ChannelRegistry {
    * name, only where no registered channel takes that name, as a channel
    * tool reads it or a `>>` target does (by label or raw id too), so the
    * name can't send anything to another channel; else by its id and server.
+   * A name that wouldn't show as itself (showsAsItself: one holding a line
+   * break, a notice opening, a quote, a backslash or a lone surrogate, or
+   * whitespace at its edges) is shown by its id and its server too, which
+   * the channel tools take exactly and the prose resolver doesn't, so no name
+   * shown can be another channel's.
    */
   nameShown(ref: ChannelRef): string {
     const entry = this.entryAt(ref);
-    if (entry) return this.nameFor(entry) ?? channelOnServer(ref);
+    if (entry) {
+      const name = this.nameFor(entry);
+      return name !== undefined && showsAsItself(name) ? name : channelOnServer(ref);
+    }
     for (const name of [ref.channelId, qualifiedChannelName(ref)]) {
-      if (this.entriesNamed(name).length === 0 && !('channelId' in this.resolveProseTarget(name))) return name;
+      if (showsAsItself(name) && this.entriesNamed(name).length === 0 && !('channelId' in this.resolveProseTarget(name))) return name;
     }
     return channelOnServer(ref);
   }
@@ -3951,8 +4068,8 @@ export class ChannelRegistry {
   /**
    * How a tuned-out channel's tune-out ends, for the texts that tell an agent
    * channel_open doesn't change it: a tune_out cancel, by the name that
-   * picks the channel (nameFor), or, where no name picks it alone, its own
-   * end, since tune_out takes a name.
+   * picks the channel (nameFor), or, where no name picks it alone, by its id
+   * and server, since tune_out takes a serverId.
    * For channel_close, which refuses a tuned-out channel too, it adds that
    * the close comes after that.
    */
@@ -3965,12 +4082,15 @@ export class ChannelRegistry {
 
   private tuneOutEndText(entry: ChannelEntry, tool?: string): string {
     const close = tool === 'channel_close';
-    return this.nameFor(entry) !== undefined
-      ? `Call tune_out with channelId ${this.quotedShown(refOf(entry))} and mode "cancel" for it to resume normal ` +
-        `attention; cancelling delivers the diverted backlog${close ? ', and channel_close closes it after that.' : '.'}`
-      : 'No channelId names it alone, so tune_out can\'t cancel it: its tune-out ends by itself when its duration ' +
-        'runs out, or at the first wake past its wake budget, and its backlog is delivered then.' +
-        (close ? ' Once it has ended, channel_close can close it.' : '');
+    // A name is written as a literal tune_out's channelId takes back
+    // (quotedValue, main's #852); one no name picks alone, by its id and
+    // server, since this branch's tune_out takes a serverId.
+    const name = this.nameFor(entry);
+    const names = name !== undefined
+      ? `channelId ${quotedValue(name)}`
+      : `channelId ${quotedValue(entry.descriptor.id)}, serverId ${JSON.stringify(entry.serverId)}`;
+    return `Call tune_out with ${names} and mode "cancel" for it to resume normal ` +
+      `attention; cancelling delivers the diverted backlog${close ? ', and channel_close closes it after that.' : '.'}`;
   }
 
   /**
@@ -3979,7 +4099,7 @@ export class ChannelRegistry {
    */
   quotedShown(ref: ChannelRef): string {
     const shown = this.nameShown(ref);
-    return shown === channelOnServer(ref) ? shown : JSON.stringify(shown);
+    return shown === channelOnServer(ref) ? shown : quotedValue(shown);
   }
 
   /**
@@ -4017,7 +4137,7 @@ export class ChannelRegistry {
     const nothing = opts.nothing ?? 'nothing ran';
     const names = entries.map((e) => this.nameFor(e));
     if (names.every((n) => n !== undefined)) {
-      const listed = names.map((n) => JSON.stringify(n)).join(', ');
+      const listed = names.map((n) => quotedValue(n!)).join(', ');
       const servers = [...new Set(entries.map((e) => JSON.stringify(e.serverId)))];
       // One server's two channels can answer to one name too, as `s`'s
       // `s:room` and `room` both do to `s:room`; its server picks neither.
@@ -4038,8 +4158,8 @@ export class ChannelRegistry {
       const own = names[i];
       if (own === undefined && !opts.takesServerId) return `- ${where}: no channelId reaches it alone.`;
       return own !== undefined
-        ? `- ${where}: call again with channelId ${JSON.stringify(own)}.`
-        : `- ${where}: call again with channelId ${JSON.stringify(e.descriptor.id)} and serverId ${JSON.stringify(e.serverId)}.`;
+        ? `- ${where}: call again with channelId ${quotedValue(own)}.`
+        : `- ${where}: call again with channelId ${quotedValue(e.descriptor.id)} and serverId ${JSON.stringify(e.serverId)}.`;
     });
     const count = entries.length === 2 ? 'either of two channels' : `any of ${entries.length} channels`;
     return `Channel ${JSON.stringify(name)} could mean ${count}, so ${nothing}:\n${lines.join('\n')}`;
@@ -4078,7 +4198,7 @@ export class ChannelRegistry {
       // so the text says whose.
       if (!alone) return 'channel_list shows the channels and their servers.';
       const one = named[0]!;
-      const names = `${JSON.stringify(channelId)} alone names channel ${JSON.stringify(one.descriptor.id)} on server `
+      const names = `${JSON.stringify(channelId)} alone names channel ${quotedValue(one.descriptor.id)} on server `
         + JSON.stringify(one.serverId);
       return takesServerId ? `${names}: for that one, call again with serverId left out.` : `${names}.`;
     }
@@ -4090,7 +4210,7 @@ export class ChannelRegistry {
       const places = elsewhere.map((e) => {
         const at = `on server ${JSON.stringify(e.serverId)}`;
         const name = this.nameFor(e);
-        return name === undefined ? `${at} (no channelId reaches it alone)` : `${at} as ${JSON.stringify(name)}`;
+        return name === undefined ? `${at} (no channelId reaches it alone)` : `${at} as ${quotedValue(name)}`;
       });
       return `It's ${places.length === 1 ? places[0] : `${places.slice(0, -1).join(', ')} and ${places.at(-1)}`}.`;
     }
@@ -4394,17 +4514,19 @@ export class ChannelRegistry {
     spec: string,
     opts?: { forSpeech?: boolean; own?: readonly ChannelRef[] },
   ): PublishDestination | { error: string; candidates?: string[]; refusedChannelId?: string } {
-    const own = this.ownChannelNamed(spec.trim(), opts?.own);
+    const name = spec.trim();
+    if (name === NO_CHANNEL_EXAMPLE || name === NO_PERSON_EXAMPLE) return { error: `${name} is the example's placeholder: write the name it stands for in its place` };
+    const own = this.ownChannelNamed(name, opts?.own);
     let resolved: PublishDestination | { error: string; candidates?: string[] };
     if (own === undefined) {
-      resolved = this.resolveTargetByName(spec);
+      resolved = this.resolveTargetByName(name);
     } else if ('neither' in own) {
-      resolved = { error: `"${spec.trim()}" is the id of this turn's channels on more than one server`, candidates: this.ownCandidates(own.neither).map((c) => c.text) };
+      resolved = { error: `"${name}" is the id of this turn's channels on more than one server`, candidates: this.ownCandidates(own.neither).map((c) => c.prose) };
     } else {
       const entry = this.entryAt(own.channel);
       resolved = entry
         ? { channelId: entry.descriptor.id, serverId: entry.serverId, label: entry.descriptor.label }
-        : { error: `${this.ownChannelGoneText(spec.trim(), own.channel)}, and nothing can be sent there until that server registers it again` };
+        : { error: `${this.ownChannelGoneText(name, own.channel)}, and nothing can be sent there until that server registers it again` };
     }
     if (!opts?.forSpeech || 'error' in resolved) return resolved;
     const entry = this.entryAt(resolved);
@@ -4463,7 +4585,7 @@ export class ChannelRegistry {
     if (!mine) return undefined;
     if ('neither' in mine) {
       const done = tool === 'publish' ? 'was posted' : tool === 'deliver' ? 'was delivered' : 'ran';
-      return { error: this.ownNeitherRefusal(name, mine.neither, done) };
+      return { error: this.ownNeitherRefusal(name, mine.neither, done, false) };
     }
     return this.entryAt(mine.channel) ? { channel: mine.channel } : { error: this.ownChannelGoneRefusal(name, mine.channel, tool) };
   }
@@ -4482,32 +4604,73 @@ export class ChannelRegistry {
   /**
    * The turn's channels a name means neither of (ownChannelNamed), each by a
    * string that reaches it outside the turn's rule: its server-qualified
-   * name, where that picks it alone, since its id is the name refused. One
-   * no string picks alone, and one its server no longer registers, is named
-   * by its id and server, saying so; `reaches` says which a name reaches.
+   * name, where that picks it alone, since its id is the name refused. `text`
+   * is that name, which a refusal writes as JSON; `prose`, which a `>>`
+   * target reads, is that name where it shows as itself, else its id and
+   * server. One no string picks alone, and one its server no longer
+   * registers, are named by id and server in both, saying so. `reaches` says
+   * which a name reaches.
    */
-  private ownCandidates(channels: readonly ChannelRef[]): Array<{ text: string; reaches: boolean }> {
+  private ownCandidates(channels: readonly ChannelRef[]): Array<{ text: string; prose: string; reaches: boolean; byServer: boolean }> {
     return channels.map((c) => {
       const entry = this.entryAt(c);
-      if (!entry) return { text: `${channelOnServer(c)} (its server no longer registers it)`, reaches: false };
+      if (!entry) {
+        const text = `${channelOnServer(c)} (its server no longer registers it)`;
+        return { text, prose: text, reaches: false, byServer: false };
+      }
       const qualified = qualifiedChannelName(c);
       const picked = this.entriesNamed(qualified);
-      return picked.length === 1 && picked[0] === entry
-        ? { text: qualified, reaches: true }
-        : { text: `${channelOnServer(c)} (no channelId reaches it alone)`, reaches: false };
+      if (picked.length !== 1 || picked[0] !== entry) {
+        const text = `${channelOnServer(c)} (no channelId reaches it alone)`;
+        return { text, prose: text, reaches: false, byServer: true };
+      }
+      return { text: qualified, prose: showsAsItself(qualified) ? qualified : channelOnServer(c), reaches: true, byServer: false };
     });
   }
 
+  /**
+   * What a refusal listing these candidates says of each one that is a
+   * channel shown by its id and server: the channelId channel_publish reaches
+   * it by, or that no channelId reaches it alone. That is its server-qualified
+   * name where that picks it alone, since a bare id is what a turn's own
+   * channels answer to first, whether or not their server still registers
+   * them (ownChannelNamed), and else its id where that picks it alone and
+   * isn't empty (channel_publish refuses an empty one). It leaves out a channel no
+   * longer registered and a candidate that already says no channelId reaches
+   * it alone, and is empty when nothing is left.
+   */
+  publishRouteFor(candidates: readonly string[]): string {
+    const parts = new Set<string>();
+    for (const candidate of candidates) {
+      const shown = CHANNEL_ON_SERVER_AT_END.exec(candidate);
+      if (!shown) continue;
+      const ref: ChannelRef = { channelId: JSON.parse(shown[1]!) as string, serverId: JSON.parse(shown[2]!) as string };
+      const entry = this.entryAt(ref);
+      if (!entry) continue;
+      const name = [qualifiedChannelName(ref), ref.channelId].find((n) => {
+        const named = n === '' ? [] : this.entriesNamed(n);
+        return named.length === 1 && named[0] === entry;
+      });
+      parts.add(name !== undefined
+        ? `channel_publish reaches ${channelOnServer(ref)} with channelId ${quotedValue(name)}`
+        : `no channelId reaches ${channelOnServer(ref)} alone`);
+    }
+    return parts.size ? ` For a channel shown by its id and server: ${[...parts].join('; ')}.` : '';
+  }
+
   /** A tool's refusal of a name the turn's channels on more than one server
    *  answer to by their id (ownChannelNamed's neither). */
-  private ownNeitherRefusal(name: string, channels: readonly ChannelRef[], done: string): string {
+  private ownNeitherRefusal(name: string, channels: readonly ChannelRef[], done: string, takesServer = true): string {
     const candidates = this.ownCandidates(channels);
-    const named = candidates.filter((c) => c.reaches).map((c) => JSON.stringify(c.text));
+    const named = candidates.filter((c) => c.reaches).map((c) => quotedValue(c.text));
     const pick = named.length === candidates.length ? ' Call again with channelId set to one of them.'
       : named.length === 1 ? ` Call again with channelId ${named[0]}.`
         : named.length > 1 ? ` Call again with channelId set to one of ${named.join(', ')}.` : '';
-    const listed = candidates.map((c) => (c.reaches ? JSON.stringify(c.text) : c.text)).join(', ');
-    return `"${name}" is the id of this turn's channels on more than one server (${listed}), so nothing ${done}.${pick}`;
+    const listed = candidates.map((c) => (c.reaches ? quotedValue(c.text) : c.text)).join(', ');
+    const byServer = takesServer && candidates.some((c) => c.byServer)
+      ? ' For a channel shown by its id and server, call again with that channelId and that serverId.'
+      : '';
+    return `"${name}" is the id of this turn's channels on more than one server (${listed}), so nothing ${done}.${pick}${byServer}`;
   }
 
   private resolveTargetByName(
@@ -4521,7 +4684,7 @@ export class ChannelRegistry {
     // A candidate is named by the token that picks it alone (nameFor), so
     // two servers' channels with one id or one label can be told apart, or,
     // where no string picks it alone, by its id and its server.
-    const token = (e: ChannelEntry): string => this.nameFor(e) ?? channelOnServer(refOf(e));
+    const token = (e: ChannelEntry): string => this.nameShown(refOf(e));
     // A DM is shown by its label, the person, where that label, given as a
     // target, picks that DM. It doesn't where another channel answers to that
     // label too, as two servers' DMs with one person do (a label is matched
@@ -4537,7 +4700,7 @@ export class ChannelRegistry {
     };
     const dmShown = (list: ChannelEntry[]): string[] => list.map((e) => {
       const label = e.descriptor.label ?? e.descriptor.id;
-      return labelPicks(e, label) ? label : token(e);
+      return showsAsItself(label) && labelPicks(e, label) ? label : token(e);
     });
 
     // A channel id, or its server-qualified name (entriesNamed).
@@ -4655,7 +4818,7 @@ export class ChannelRegistry {
     if (byName.length > 1) {
       return {
         error: `"${trimmed}" matches several channels`,
-        candidates: byName.map((e) => `${e.descriptor.label} = ${token(e)}`),
+        candidates: byName.map((e) => `${nameToTypeBack(e.descriptor.label ?? '')} = ${token(e)}`),
       };
     }
 
@@ -4664,7 +4827,7 @@ export class ChannelRegistry {
     const near = entries
       .filter((e) => norm(e.descriptor.label ?? '').includes(norm(trimmed)))
       .slice(0, 5)
-      .map((e) => `${e.descriptor.label} = ${token(e)}`);
+      .map((e) => `${nameToTypeBack(e.descriptor.label ?? '')} = ${token(e)}`);
     return { error: `no channel matches "${trimmed}"`, ...(near.length ? { candidates: near } : {}) };
   }
 
@@ -4701,7 +4864,7 @@ export class ChannelRegistry {
       qualifiedChannelName(ref),
     ];
     for (const c of candidates) {
-      if (!isProseTargetToken(c) || c === '#') continue;
+      if (!isProseTargetToken(c) || c === '#' || !showsAsItself(c)) continue;
       const r = this.resolveProseTarget(c, { forSpeech: true });
       if ('channelId' in r && sameChannel(r, ref)) return c;
     }
@@ -4990,7 +5153,7 @@ export class ChannelRegistry {
           channelId: input.channelId,
           serverId: entry.serverId,
           status: alreadyDesiredOpen ? 'reconciled' : 'opened',
-          ...(result.history ? { history: result.history } : {}),
+          ...(result.history ? { history: markedHistory(result.history) } : {}),
           ...(result.historyTruncated ? { historyTruncated: true } : {}),
         },
       };
@@ -5070,12 +5233,13 @@ export class ChannelRegistry {
       // Closed already, perhaps only by default: the agent's close is still
       // its decision, and is recorded as one (setDesiredState), so a later
       // registration's lift of a default leaves the channel closed.
+      const ended = this.onToolClose?.(entry.serverId, input.channelId);
       try {
         this.setDesiredState(entry.serverId, input.channelId, 'closed', closeSource);
       } catch (err) {
         return {
           success: false,
-          error: `Channel ${shown} is already closed, but recording the decision to close it failed: ${(err as Error).message}`,
+          error: `Channel ${shown} is already closed, but recording the decision to close it failed: ${(err as Error).message}${ended ? ` ${ended}` : ''}`,
           isError: true,
         };
       }
@@ -5118,12 +5282,18 @@ export class ChannelRegistry {
       const refusal = this.tunedOutRefusal('channel_close', entry);
       return isModuleOrigin ? { ...refusal, isError: false } : refusal;
     }
+    // A hold around this channel — the all-except scope it is the excepted
+    // channel of — ends through the cancel flow: backlog released, end
+    // recorded, never by overwriting state (#232 gap 9).
+    const ended = this.onToolClose?.(entry.serverId, input.channelId);
 
-    // A decision the log refused changed nothing, and the answer says so.
+    // A decision the log refused changed nothing for the channel, and the
+    // answer says so, and what the hook ended all the same.
     try {
       this.setDesiredState(entry.serverId, input.channelId, 'closed', closeSource);
     } catch (err) {
-      return { success: false, error: this.lifecycleFailureText('close', entry, unrecordedDecision(err)), isError: true };
+      const text = this.lifecycleFailureText('close', entry, unrecordedDecision(err));
+      return { success: false, error: ended ? `${text} ${ended}` : text, isError: true };
     }
     // This channel's typing, not every channel with its id (stopTyping's
     // fan-out of a bare name).
@@ -5479,13 +5649,14 @@ 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?: unknown }): ToolResult {
+  private handleToolSkipReply(input: { reason?: string; wake_in_seconds?: unknown }, earlierWake?: SkipReplyEarlierWake): ToolResult {
     // The self-wake itself is armed by the framework (which owns the
     // 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.
+    // nothing armed. The framework, which also owns the heartbeat, says
+    // which of its wakes is due before the self-wake (`earlierWake`).
     const wake = readSkipReplyWake(input);
     const selfWake = wake.kind === 'wake' ? wake.seconds : undefined;
     return {
@@ -5501,9 +5672,7 @@ export class ChannelRegistry {
       // on Fable: ~60% of skip_reply result bytes were verbatim input echo).
       data: {
         skipped: true,
-        note: selfWake !== undefined
-          ? `Turn ended; nothing sent. Self-wake in ~${selfWake}s unless something wakes you first.`
-          : 'Turn ended; nothing sent.',
+        note: skipReplyNote(selfWake, selfWake !== undefined ? earlierWake : undefined),
       },
     };
   }
@@ -5601,9 +5770,29 @@ export class ChannelRegistry {
     return active !== undefined ? active : this.globalFallbackFor(conversationId);
   }
 
-  /** The process-global fallback channel for this conversation, or null when it takes none (takesGlobalFallback). */
+  /**
+   * The process-global fallback for this conversation, or null when it takes
+   * none (takesGlobalFallback): an ephemeral run's prose is its caller's
+   * result, so neither the all-except hold's channel nor the latest inbound
+   * message's is ever its destination.
+   */
   private globalFallbackFor(conversationId: string): ChannelRef | null {
-    return this.takesGlobalFallback?.(conversationId) === false ? null : this.defaultPublishChannel;
+    return this.takesGlobalFallback?.(conversationId) === false ? null : this.sharedFallback();
+  }
+
+  /**
+   * What every conversation that takes the global fallback falls back to when
+   * neither a home channel nor its own delivery names one: the all-except
+   * hold's channel while one is open, else the latest delivered inbound
+   * channel under the legacy locus rule, else none — the prose stays private
+   * (architecture channel §3 carve-out, 2026-10-06).
+   */
+  private sharedFallback(): ChannelRef | null {
+    return this.focusChannelResolver?.() ?? this.fallbackLocus();
+  }
+
+  private fallbackLocus(): ChannelRef | null {
+    return this.latestInboundLocus ? this.defaultPublishChannel : null;
   }
 
   /**
@@ -6055,17 +6244,20 @@ export class ChannelRegistry {
     if (input.channelId === '' && tool === 'channel_publish') {
       return { success: false, error: `Nothing was posted: channelId is empty. ${findIds}`, isError: true };
     }
-    // Resolve channelId: default to the channel of the most recent incoming
-    // message that isn't a reaction, reaction removal, edit or deletion
-    // marker, apart from an edit the coalescer delivers on acceptance as the
-    // agent's first view. An ephemeral run never takes that default
+    // Resolve channelId: a call made inside the agent's turn (inTurn) has
+    // the turn's default applied already, where its plain speech goes, and
+    // takes none here. Any other defaults to what the caller falls back to:
+    // the all-except hold's channel, else the latest delivered inbound
+    // channel under the legacy locus rule (a marker — reaction, edit,
+    // deletion — is never that channel), which an ephemeral run never takes
     // (takesGlobalFallback), so it names one.
     // A channel named by a string means what it means to every channel tool
     // (entriesNamed): one channel, by its id or its server-qualified name,
     // and a name two servers' channels answer to is refused with them as
     // candidates, never sent to the first.
     const caller = origin?.kind === 'agent' ? origin.agentName : undefined;
-    const fallback = caller !== undefined ? this.globalFallbackFor(caller) : this.defaultPublishChannel;
+    const inTurn = origin?.kind === 'agent' && origin.inTurn === true;
+    const fallback = caller === undefined ? this.sharedFallback() : inTurn ? null : this.globalFallbackFor(caller);
     if (!(input.channelId ?? fallback)) {
       return {
         success: false,
@@ -6074,7 +6266,10 @@ export class ChannelRegistry {
           : caller !== undefined && this.takesGlobalFallback?.(caller) === false
             ? 'Nothing was posted: name the channel with channelId. A subagent has no default channel, since its plain '
               + 'speech is returned to whoever called it, so channel_publish sends only to a channel it names.'
-            : `Nothing was posted: channel_publish needs a \`channelId\`, and there's no channel to default to yet. ${findIds}`,
+            : caller !== undefined && inTurn && this.activeChannelResolver?.(caller) === null
+              ? `Nothing was posted: name the channel with channelId. This turn has no channel of its own, so its plain speech `
+                + `goes to none and channel_publish sends only to a channel it names. ${findIds}`
+              : `Nothing was posted: channel_publish needs a \`channelId\`, and there's no channel to default to yet. ${findIds}`,
         isError: true,
       };
     }
@@ -6096,7 +6291,7 @@ export class ChannelRegistry {
       entry = this.entryAt(serverGiven ? { serverId: input.serverId!, channelId: fallback!.channelId } : fallback!);
     } else if (own && 'neither' in own) {
       if (seen) seen.refusal = 'shared-id';
-      return { success: false, error: this.ownNeitherRefusal(input.channelId, own.neither, 'was posted'), isError: true };
+      return { success: false, error: this.ownNeitherRefusal(input.channelId, own.neither, 'was posted', false), isError: true };
     } else if (own) {
       entry = this.entryAt(own.channel);
       if (!entry) {
@@ -6127,7 +6322,7 @@ export class ChannelRegistry {
         // channel with its id isn't where its message came from.
         error: input.channelId === undefined
           ? serverGiven
-            ? `Server "${input.serverId}" has no channel "${fallback!.channelId}", the id of the channel this call would default to, so nothing was posted.`
+            ? `Server "${input.serverId}" has no channel ${quotedValue(fallback!.channelId)}, the id of the channel this call would default to, so nothing was posted.`
             : `The channel this would default to, ${this.quotedShown(fallback!)}, isn't registered now, so nothing was posted.`
           // This tool's schema has no serverId, so one given here is a host's
           // ref (publishForAgent), or one an agent added unasked, and the