@animalabs/agent-framework 0.32.0 → 0.34.0

package/dist/src/mcpl/channel-registry.js

@@ -21,11 +21,13 @@ import { expandCoreTags, isMarkerTagged } from './tags.js';
 import { coalesceRejectionReason, EmptyContentError, validateCoalescedContent } from './push-coalescer.js';
 import { isVisiblyEmptyConversion } from './visible-content.js';
 import { logDetail, logValue } from './log-value.js';
+import { jsonKind } from '../jsonrpc-envelope.js';
 import { RefusalLines } from './refusal-lines.js';
 import { CapabilityGrant } from './capability-grant.js';
 import { McplRequestError } from './server-connection.js';
 import { readSkipReplyWake, skipReplyNote } from './skip-reply-wake.js';
 import { isProseTargetToken } from './prose-grammar.js';
+import { persistentReaderName, tuneOutHeldWords, tuneOutNoReaderAnswer, tuneOutReachWords } from '../tune-out/tools.js';
 // ============================================================================
 // Typing indicator interval (Discord typing lasts ~10s, so 7s keeps it alive)
 // ============================================================================
@@ -146,8 +148,8 @@ function desiredStateRecord(item) {
 }
 /**
  * The desired state `store`'s lifecycle log records for `channelId` on
- * `serverId`, for a reader with no registry yet, as a serving boot's
- * deferred-write flush is, before initializeMcpl: the last decision wins, as
+ * `serverId`, for a reader with no registry yet, as the boot's import of an
+ * earlier release's queued writes is, before initializeMcpl: the last decision wins, as
  * the registry's replay reads it (getDesiredState answers once there is a
  * registry). undefined when no decision names it.
  */
@@ -478,6 +480,32 @@ function withEmbeddedTextMarked(block) {
 function channelOnServer(ref) {
     return `${quotedValue(ref.channelId)} on server ${quotedValue(ref.serverId)}`;
 }
+/** A channel_close's lead where its channel's server no longer registers it. */
+function noLongerRegistered(ref) {
+    return `Server ${quotedValue(ref.serverId)} no longer registers channel ${quotedValue(ref.channelId)}, so no close was recorded or sent.`;
+}
+/** What a channel_close's bare name reached besides the channel it closed
+ *  (ChannelRegistry.focusNamedBare): each by its id and server, which the
+ *  bare name leaves out, and the channelId and serverId a call closes it
+ *  with: its own id, which needn't be the name the call gave (a focus on
+ *  `b:room` beside server b's `room`), so naming the server alone, the
+ *  name kept, is no channel there. */
+function notClosedText(refs) {
+    const names = refs.map(channelOnServer);
+    const call = (ref) => `channelId ${quotedValue(ref.channelId)} and serverId ${quotedValue(ref.serverId)}`;
+    return refs.length === 1
+        ? `Channel ${names[0]} was not closed: to close it, call again with ${call(refs[0])}.`
+        : `Channels ${names.slice(0, -1).join(', ')} and ${names.at(-1)} were not closed: to close one, call again with ` +
+            `${refs.slice(0, -1).map(call).join(', with ')}, or with ${call(refs.at(-1))}.`;
+}
+/** A tool result with a sentence added: a success's after its note (or as
+ *  its note), a failure's after its error. */
+function withSentence(result, sentence) {
+    if (!result.success)
+        return { ...result, error: result.error ? `${result.error} ${sentence}` : sentence };
+    const data = (result.data ?? {});
+    return { ...result, data: { ...data, note: typeof data.note === 'string' ? `${data.note} ${sentence}` : sentence } };
+}
 const CHANNEL_ON_SERVER_AT_END = /("(?:[^"\\]|\\.)*") on server ("(?:[^"\\]|\\.)*")$/;
 /**
  * A failed request's words, bounded, for a reason that a caller composes.
@@ -680,12 +708,17 @@ export class ChannelRegistry {
     latestInboundLocus;
     onToolClose;
     focusChannelResolver;
+    tuneOutReaderFn;
     onRouteFailure;
     onChannelAutoOpened;
     homeChannelResolver;
     activeChannelResolver;
+    channellessTurn;
     takesGlobalFallback;
     serverConnecting;
+    unpromptedChannel;
+    unpromptedChannelWarned = false;
+    takesUnpromptedChannel;
     store;
     /**
      * Registered channels, keyed by their server and id (destinationKey): a
@@ -861,6 +894,10 @@ export class ChannelRegistry {
             return new ChannelLifecycleError(unreachableClause(serverId, reach), 'unreachable', reach);
         return new ChannelLifecycleError(`this host isn't permitted to open or close the "${serverId}" server's channels`, 'not-permitted');
     }
+    publishingServer(serverId) {
+        const server = this.serverRegistry.getServer(serverId);
+        return server && CapabilityGrant.of(server).has('channels.publish') ? server : undefined;
+    }
     /**
      * Why a send to this server's channels is refused before anything goes
      * out, as one clause with what works from there, for a caller that found
@@ -934,17 +971,17 @@ export class ChannelRegistry {
                 (reach === 'gone' ? ' If you need the server back, ask whoever runs this host.' : '') +
                 (failure === undefined ? ` ${withStop(lifecycleClause(err))}` : '');
         }
-        // A tune-out sends the channel's messages to the subconscious, and
+        // A tune-out holds the channel's messages for its reader, if any, and
         // channel_open refuses a tuned-out channel.
         if (action === 'open' ? now !== 'open' : now !== 'closed') {
             if (action === 'open' && now === 'tuned-out') {
-                return `Channel ${channel} was tuned out meanwhile: its messages go to the subconscious, and channel_open doesn't ` +
+                return `Channel ${channel} was tuned out meanwhile: its messages ${this.tuneOutHeld()}, and channel_open doesn't ` +
                     `change that. ${this.tuneOutEndText(current)}`;
             }
             // channel_close refuses a tuned-out channel too, so calling it again
             // isn't the way: the tune-out's cancel is, and it delivers the backlog.
             if (action === 'close' && now === 'tuned-out') {
-                return `Channel ${channel} was tuned out meanwhile: its messages go to the subconscious, and channel_close doesn't ` +
+                return `Channel ${channel} was tuned out meanwhile: its messages ${this.tuneOutHeld()}, and channel_close doesn't ` +
                     `change that. ${this.tuneOutEndText(current, 'channel_close')}`;
             }
             // The later decision's own work settles the transport, and its call
@@ -1034,6 +1071,16 @@ export class ChannelRegistry {
         this.handleCoalescedIncoming = options?.handleCoalescedIncoming;
         this.acceptInbound = options?.acceptInbound;
         this.channelTools = CHANNEL_TOOL_DEFINITIONS.map((tool) => {
+            if (tool.name === 'channel_publish') {
+                if (options?.unpromptedChannel === undefined || options.eventGatePresent !== true)
+                    return tool;
+                return {
+                    ...tool,
+                    description: tool.description
+                        .replace('otherwise, while a focus holds, the channel it keeps.', 'otherwise, while a focus holds, the channel it keeps; otherwise, on a turn your own skip_reply wake or the end of your sleep started (or a turn continuing one, when your plain speech isn\'t routed), the channel this host names for such turns.')
+                        .replace('A turn with no channel of its own, such as', 'A turn with no channel by design, such as'),
+                };
+            }
             if (tool.name !== 'skip_reply' || options?.eventGatePresent === true)
                 return tool;
             const schema = tool.inputSchema;
@@ -1053,11 +1100,15 @@ export class ChannelRegistry {
         this.latestInboundLocus = options?.latestInboundLocus === true;
         this.onToolClose = options?.onToolClose;
         this.focusChannelResolver = options?.focusChannelResolver;
+        this.tuneOutReaderFn = options?.tuneOutReader;
         this.onRouteFailure = options?.onRouteFailure;
         this.onChannelAutoOpened = options?.onChannelAutoOpened;
         this.homeChannelResolver = options?.homeChannelResolver;
         this.activeChannelResolver = options?.activeChannelResolver;
+        this.channellessTurn = options?.channellessTurn;
         this.takesGlobalFallback = options?.takesGlobalFallback;
+        this.unpromptedChannel = options?.unpromptedChannel;
+        this.takesUnpromptedChannel = options?.takesUnpromptedChannel;
         this.serverConnecting = options?.serverConnecting;
         this.store = options?.store;
         this.initializeLifecycleStore();
@@ -1686,8 +1737,10 @@ export class ChannelRegistry {
         }
     }
     /** The explicit 'stop' for a channel whose typing ended, while its
-     *  server still registers it. */
+     *  server still registers it and holds the grant its start needed. */
     sendTypingStop(ref) {
+        if (!this.typingGranted(ref))
+            return;
         if (this.sendTypingFn && this.entryAt(ref)) {
             this.sendTypingFn(ref.serverId, ref.channelId, this.typingMetadata.get(destinationKey(ref)), 'stop');
         }
@@ -1796,6 +1849,30 @@ export class ChannelRegistry {
     getChannelTools() {
         return this.channelTools;
     }
+    /**
+     * The refusal of a channel tool's call that gives a parameter its schema
+     * declares a string as something else, before anything changes; absent and
+     * `null` pass, as each tool reads them. A number written past 2^53 has
+     * usually lost its last digits by the time the call is parsed.
+     */
+    nonStringRefusal(toolName, input) {
+        if (input === null || typeof input !== 'object')
+            return undefined;
+        const properties = this.channelTools.find((tool) => tool.name === toolName)?.inputSchema.properties ?? {};
+        for (const [field, value] of Object.entries(input)) {
+            if (properties[field]?.type !== 'string')
+                continue;
+            if (value === undefined || value === null || typeof value === 'string')
+                continue;
+            return {
+                success: false,
+                error: `Nothing changed: ${toolName}'s ${field} must be a string, and this call gave ${jsonKind(value)}. Give it in quotes`
+                    + (typeof value === 'number' ? ': a number can lose its last digits as the call is read.' : '.'),
+                isError: true,
+            };
+        }
+        return undefined;
+    }
     /**
      * Handle a call to one of the synthesized channel tools.
      *
@@ -1812,6 +1889,9 @@ export class ChannelRegistry {
     /** Filled with a channel_publish's outcome once its request is
      *  attempted, so the caller learns where it was delivered. */
     seen) {
+        const refused = this.nonStringRefusal(toolName, input);
+        if (refused)
+            return refused;
         switch (toolName) {
             case 'channel_list':
                 return this.handleToolList();
@@ -1858,7 +1938,9 @@ export class ChannelRegistry {
      * its home.
      */
     incomingFor(agentName) {
-        if (agentName !== undefined && this.activeChannelResolver?.(agentName) === null && !this.homeChannelResolver?.(agentName)) {
+        const channelless = agentName === undefined ? false
+            : this.channellessTurn ? this.channellessTurn(agentName) : this.activeChannelResolver?.(agentName) === null;
+        if (channelless && !this.homeChannelResolver?.(agentName)) {
             return undefined;
         }
         // The latest delivered inbound itself, not the speech fallback
@@ -1885,7 +1967,9 @@ 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
-        // (a no-trigger turn's, but not a heartbeat's, whose turn takes none).
+        // (a no-trigger turn's, but not a heartbeat's, whose turn takes none), with
+        // the configured unprompted channel in it where the turn takes it: the
+        // channel channel_publish naming none publishes to, in every prose mode.
         // Without this, a fork
         // was advertised the global locus but published somewhere else; and a trunk
         // agent was told the wrong channel under concurrency.
@@ -1896,9 +1980,11 @@ export class ChannelRegistry {
         // 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();
+        const fallback = () => agentName !== undefined
+            ? this.globalFallbackFor(agentName, () => this.configuredUnprompted(agentName))
+            : this.sharedFallback();
         // A turn that deliberately has no channel (null) takes no fallback.
-        const outgoing = home ?? (active !== undefined ? active : fallback);
+        const outgoing = home ?? (active !== undefined ? active : fallback());
         const context = {};
         // Incoming: the message the agent is replying to (incomingFor). The
         // anchor is independent of the speech rule: under `speech.locus:
@@ -2466,7 +2552,7 @@ export class ChannelRegistry {
     }
     /**
      * Make a tuned-out channel's transport match its tune-out, which keeps it
-     * open so its traffic reaches the subconscious (TuneOutParams). The
+     * open so its traffic reaches its reader, or is held (TuneOutParams). The
      * tune-out is recorded first (enterTuneOut), and this writes no decision,
      * so the tune-out stands whatever becomes of the open. Lifecycle work
      * queued for the channel goes first, until none is left, since each
@@ -2478,8 +2564,8 @@ export class ChannelRegistry {
      * tune-out as open), and the answer waits for the work queued after it
      * too, such as a registration that came back, and comes from the state
      * that work leaves. Returns nothing where the transport is open, or, for
-     * tune_out's answer, why the channel's messages don't or may not reach the
-     * subconscious yet and when they will, or that the tune-out isn't in
+     * tune_out's answer, why the channel's messages don't or may not reach its
+     * reader yet, or be received, and when they will, or that the tune-out isn't in
      * effect any more. A call while this tune-out's open is in flight, as a
      * repeated tune_out makes, gets that open's answer rather than send
      * another.
@@ -2545,8 +2631,9 @@ export class ChannelRegistry {
         // that took effect would have its traffic diverted. `again` where calling
         // tune_out again tries the open now: the channel is registered here and
         // its server up.
-        const notYet = (later, why, again = false) => withStop(`The tune-out is recorded, but its messages may not reach the subconscious until this host opens the channel, ` +
-            `which it does ${later}${again ? ', or now if you call tune_out again' : ''}; ${why}`);
+        // Where no reader runs, each answer is that alone (tuneOutNoReaderAnswer).
+        const notYet = (later, why, again = false) => tuneOutNoReaderAnswer(this.tuneOutReaderNow()) ?? withStop(`The tune-out is recorded, but its messages ${this.tuneOutReach('may not reach')} until this host opens the ` +
+            `channel, which it does ${later}${again ? ', or now if you call tune_out again' : ''}; ${why}`);
         const nextRegistration = `when the "${serverId}" server next registers this channel, if this host may open and ` +
             'close its channels then';
         // The work queued for the channel as it stands: its tail, waited for,
@@ -2580,16 +2667,16 @@ export class ChannelRegistry {
             // established.
             const reach = this.serverReach(serverId);
             if (reach !== 'up') {
-                return withStop(`The tune-out is recorded, but its messages don't reach the subconscious until the "${serverId}" server is ` +
-                    `connected and the channel is open; it can't be opened now: ${unreachableClause(serverId, reach)}` +
+                return tuneOutNoReaderAnswer(this.tuneOutReaderNow()) ?? withStop(`The tune-out is recorded, but its messages ${this.tuneOutReach("don't reach")} until the "${serverId}" server ` +
+                    `is connected and the channel is open; it can't be opened now: ${unreachableClause(serverId, reach)}` +
                     (reach === 'gone' ? unreachableRemedy(reach) : ''));
             }
             const transportOpen = this.tuneOutReadsOpen(entry);
             if (!this.directsLifecycle(serverId)) {
                 return transportOpen ? undefined
-                    : `The tune-out is recorded, but ${this.lifecycleRefusal(serverId).message}, so its messages reach the ` +
-                        'subconscious only as that server sends them, and calling tune_out again won\'t change that. If you need ' +
-                        'this host to open it, ask whoever runs this host.';
+                    : tuneOutNoReaderAnswer(this.tuneOutReaderNow()) ?? `The tune-out is recorded, but ${this.lifecycleRefusal(serverId).message}, so its messages ` +
+                        `${this.tuneOutReach('reach')} only as that server sends them, and calling tune_out again won't change ` +
+                        'that. If you need this host to open it, ask whoever runs this host.';
             }
             if (!entry)
                 return missing;
@@ -3222,10 +3309,9 @@ export class ChannelRegistry {
      * (typing timer lifecycle is still managed for when the callback is wired).
      */
     sendTypingNotification(ref) {
-        // §14.1: channels/typing requires channels.typing in the grant. Silent
-        // skip — a typing indicator is cosmetic and per-7s, so a diagnostic per
-        // tick would be noise.
-        if (!CapabilityGrant.of(this.serverRegistry.getServer(ref.serverId)).has('channels.typing'))
+        // Silent skip — a typing indicator is cosmetic and per-7s, so a
+        // diagnostic per tick would be noise.
+        if (!this.typingGranted(ref))
             return;
         if (this.sendTypingFn) {
             this.sendTypingFn(ref.serverId, ref.channelId, this.typingMetadata.get(destinationKey(ref)));
@@ -3233,6 +3319,10 @@ export class ChannelRegistry {
         // TODO: When server-connection exposes a public sendNotification or
         // sendTyping method, wire it here directly instead of using a callback.
     }
+    /** §14.1: channels/typing, start and stop alike, requires channels.typing in the grant. */
+    typingGranted(ref) {
+        return CapabilityGrant.of(this.serverRegistry.getServer(ref.serverId)).has('channels.typing');
+    }
     // ==========================================================================
     // Private: Channel Lookup
     // ==========================================================================
@@ -3305,6 +3395,18 @@ export class ChannelRegistry {
         }
         return channelOnServer(ref);
     }
+    /** The reader of a tuned-out channel's traffic, as the host says (tuneOutReader), or the default persistent reader. */
+    tuneOutReaderNow() {
+        return this.tuneOutReaderFn?.() ?? { kind: 'persistent', name: persistentReaderName({}) };
+    }
+    /** What a tuned-out channel's messages are, after "its messages" (tuneOutHeldWords). */
+    tuneOutHeld() {
+        return tuneOutHeldWords(this.tuneOutReaderNow());
+    }
+    /** Whether a tuned-out channel's messages get to its reader, after "its messages" (tuneOutReachWords). */
+    tuneOutReach(form) {
+        return tuneOutReachWords(this.tuneOutReaderNow(), form);
+    }
     /**
      * A tool's refusal of a tuned-out channel, whose decision is the tune-out:
      * its cancel is what ends it (tuneOutEndText), and a decision recorded over
@@ -3315,7 +3417,7 @@ export class ChannelRegistry {
         return {
             success: false,
             isError: true,
-            error: `Channel ${this.quotedShown(refOf(entry))} is tuned out: its messages go to the subconscious, and ${tool} ` +
+            error: `Channel ${this.quotedShown(refOf(entry))} is tuned out: its messages ${this.tuneOutHeld()}, and ${tool} ` +
                 `doesn't change that. ${this.tuneOutEndText(entry, tool)}`,
             data: { refusal: 'tuned-out', channelId: entry.descriptor.id, serverId: entry.serverId },
         };
@@ -3334,7 +3436,7 @@ export class ChannelRegistry {
         const entry = this.entryAt(ref);
         return entry ? this.tuneOutEndText(entry) : undefined;
     }
-    tuneOutEndText(entry, tool) {
+    tuneOutEndText(entry, tool, closeWith) {
         const close = tool === 'channel_close';
         // 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
@@ -3344,7 +3446,7 @@ export class ChannelRegistry {
             ? `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.' : '.'}`;
+            `attention; cancelling delivers the diverted backlog${close ? `, and channel_close${closeWith ? ` with ${closeWith}` : ''} closes it after that.` : '.'}`;
     }
     /**
      * A channel's name as nameShown gives it, quoted for a sentence: the name
@@ -4336,15 +4438,38 @@ export class ChannelRegistry {
         }
     }
     async handleToolClose(input, origin) {
-        const resolved = this.resolveToolChannelEntry(input.channelId, input.serverId, origin?.kind === 'agent' ? origin.own : undefined);
-        const entry = resolved.entry;
-        if (!entry) {
-            return {
-                success: false,
-                error: resolved.error,
-                isError: true,
-            };
+        const own = origin?.kind === 'agent' ? origin.own : undefined;
+        // An agent's bare name for the channel the all-except hold excepts means
+        // that channel (focusNamedBare), whether its server still registers it
+        // or not: another server's channel with the id, which the name would
+        // reach otherwise, isn't closed, and the answer says so. A module's
+        // close resolves its name as any other: housekeeping doesn't end the
+        // resident's focus.
+        const focused = origin?.kind === 'module' ? undefined : this.focusNamedBare(input.channelId, input.serverId, own);
+        if (focused && 'refusal' in focused)
+            return { success: false, error: focused.refusal, isError: true };
+        if (focused) {
+            const entry = this.entryAt(focused.focus);
+            const result = entry
+                ? await this.closeToolEntry(entry, input, origin)
+                : this.unregisteredFocusClose(focused.focus) ?? { success: false, error: noLongerRegistered(focused.focus), isError: true };
+            return focused.notClosed ? withSentence(result, focused.notClosed) : result;
         }
+        const resolved = this.resolveToolChannelEntry(input.channelId, input.serverId, own);
+        if (resolved.entry)
+            return this.closeToolEntry(resolved.entry, input, origin);
+        // The name, with its serverId or as the turn's own channel, means the
+        // channel the all-except hold excepts, which its server no longer
+        // registers (unregisteredFocusNamed). A module's close of such a name is
+        // refused as any name no channel answers to.
+        const gone = origin?.kind === 'module' ? undefined : this.unregisteredFocusNamed(input.channelId, input.serverId, own);
+        return (gone && this.unregisteredFocusClose(gone)) || { success: false, error: resolved.error, isError: true };
+    }
+    /**
+     * A tool close of the channel `entry`, which its name resolved to
+     * (handleToolClose).
+     */
+    async closeToolEntry(entry, input, origin) {
         // From here, the channel's own id, whichever name the call gave for it
         // (a server-qualified one included).
         input = { ...input, channelId: entry.descriptor.id };
@@ -4375,20 +4500,23 @@ 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);
+            const hook = this.toolCloseHook(refOf(entry));
+            if ('error' in hook)
+                return { success: false, error: hook.error, isError: true };
+            const ended = hook.text;
             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.message}${ended ? ` ${ended}` : ''}`,
+                    error: `Channel ${shown} is already closed, but recording the decision to close it failed: ${err.message}${ended ? ` ${ended()}` : ''}`,
                     isError: true,
                 };
             }
             return {
                 success: true,
-                data: { channelId: input.channelId, serverId: entry.serverId, status: 'already closed' },
+                data: { channelId: input.channelId, serverId: entry.serverId, status: 'already closed', ...(ended ? { note: ended() } : {}) },
             };
         }
         // Housekeeping must not override stated intent (issue #5: GC closes wore
@@ -4425,15 +4553,23 @@ export class ChannelRegistry {
         // 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);
+        const hook = this.toolCloseHook(refOf(entry));
+        if ('error' in hook)
+            return { success: false, error: hook.error, isError: true };
+        const ended = hook.text;
         // A decision the log refused changed nothing for the channel, and the
-        // answer says so, and what the hook ended all the same.
+        // answer says so, and what the hook ended all the same. Every answer
+        // carries the hook's sentence, a success's as `note`: whether the close
+        // went through says nothing of the focus, whose end may wait (an
+        // operator's change to the store in progress). The sentence is read as
+        // the answer is built, after the transport's round-trip, during which a
+        // release that waited may have run.
+        const withEnded = (text) => (ended ? `${text} ${ended()}` : text);
         try {
             this.setDesiredState(entry.serverId, input.channelId, 'closed', closeSource);
         }
         catch (err) {
-            const text = this.lifecycleFailureText('close', entry, unrecordedDecision(err));
-            return { success: false, error: ended ? `${text} ${ended}` : text, isError: true };
+            return { success: false, error: withEnded(this.lifecycleFailureText('close', entry, unrecordedDecision(err))), isError: true };
         }
         // This channel's typing, not every channel with its id (stopTyping's
         // fan-out of a bare name).
@@ -4441,7 +4577,7 @@ export class ChannelRegistry {
         // Refused now, the close stays recorded for the server's next
         // registration, and the text says so.
         if (!this.directsLifecycle(entry.serverId)) {
-            return { success: false, error: this.lifecycleFailureText('close', entry, this.lifecycleRefusal(entry.serverId)), isError: true };
+            return { success: false, error: withEnded(this.lifecycleFailureText('close', entry, this.lifecycleRefusal(entry.serverId))), isError: true };
         }
         try {
             const applied = await this.applyDesiredChannelState(entry.serverId, input.channelId);
@@ -4450,13 +4586,167 @@ export class ChannelRegistry {
                 throw new ChannelLifecycleError(supersededClause('close', now), 'superseded');
             return {
                 success: true,
-                data: { channelId: input.channelId, serverId: entry.serverId, status: 'closed' },
+                data: { channelId: input.channelId, serverId: entry.serverId, status: 'closed', ...(ended ? { note: ended() } : {}) },
             };
         }
         catch (err) {
-            return { success: false, error: this.lifecycleFailureText('close', entry, err), isError: true };
+            return { success: false, error: withEnded(this.lifecycleFailureText('close', entry, err)), isError: true };
+        }
+    }
+    /**
+     * The tool-close hook (onToolClose) for a channel, its throw taken as the
+     * answer's text: a release of the hold that failed is the close's answer,
+     * as the registry's other failures are, never a rejected call.
+     */
+    toolCloseHook(ref, opts) {
+        try {
+            return { text: this.onToolClose?.(ref.serverId, ref.channelId, opts) };
+        }
+        catch (err) {
+            return { error: err instanceof Error ? err.message : String(err) };
         }
     }
+    /**
+     * A close naming the channel the all-except hold excepts, which its server
+     * no longer registers: the close has nothing left to close, and the hold
+     * nothing left to speak into, so it ends as a close of the registered
+     * channel ends it, what it held released, and the answer says so, as a
+     * failure, since no close ran. Undefined where no hold excepts the channel
+     * (onToolClose answers nothing).
+     */
+    unregisteredFocusClose(gone) {
+        const lead = noLongerRegistered(gone);
+        const ended = this.toolCloseHook(gone, { unregistered: true });
+        if ('error' in ended)
+            return { success: false, error: `${lead} ${ended.error}`, isError: true };
+        if (ended.text)
+            return { success: false, error: `${lead} ${ended.text()}`, isError: true };
+        return undefined;
+    }
+    /**
+     * The channel the all-except hold excepts (focusChannelResolver), where a
+     * channel_close names it by its id or its server-qualified name alone: no
+     * serverId, and no channel of the calling turn's own answering to the name
+     * (ownChannelNamed, which a turn's name means first). Such a name means
+     * the hold's channel, registered or not, and not another server's channel
+     * with the id, as when the hold's channel's server stopped registering it
+     * and another server registered the id: that one is closed only by a close
+     * that names its server. With it, where other registered channels answer
+     * to the name, the sentence saying they weren't closed (`notClosed`).
+     *
+     * Where the name is the hold channel's and a channel of the calling turn's
+     * own, another channel, answers to it too, the name means neither: a
+     * resident repeating a close that failed before its focus ended, in a turn
+     * that has since opened another server's channel with the id, would
+     * otherwise close that channel and leave the focus in force. That close is
+     * refused, naming both (`refusal`, focusOrOwnRefusal), and a close naming
+     * either's server reaches it. A turn's name for the hold's channel itself,
+     * and a name the turn's channels on more than one server answer to
+     * (ownNeitherRefusal), resolve as any other.
+     *
+     * Undefined where no hold is in force, where the name isn't the hold
+     * channel's, and where the hold's record can't be read, which leaves the
+     * name to resolve as any other (resolveToolChannelEntry).
+     *
+     * Another channel the name reaches that has a tune-out of its own is
+     * refused by a close until that tune-out is cancelled (tunedOutRefusal),
+     * so its sentence says it is tuned out, and names the cancel first, then
+     * the close by its id and server.
+     */
+    focusNamedBare(name, serverId, own) {
+        if (serverId)
+            return undefined;
+        const mine = this.ownChannelNamed(name, own);
+        if (mine && 'neither' in mine)
+            return undefined;
+        let focus;
+        try {
+            focus = this.focusChannelResolver?.();
+        }
+        catch {
+            return undefined;
+        }
+        if (!focus || (name !== focus.channelId && name !== qualifiedChannelName(focus)))
+            return undefined;
+        if (mine)
+            return sameChannel(mine.channel, focus) ? undefined : { refusal: this.focusOrOwnRefusal(name, focus, mine.channel, own) };
+        const held = focus;
+        const others = this.entriesNamed(name).filter((entry) => !sameChannel(refOf(entry), held));
+        const tunedOut = others.filter((entry) => this.getDesiredState(entry.serverId, entry.descriptor.id) === 'tuned-out');
+        const closable = others.filter((entry) => !tunedOut.includes(entry)).map(refOf);
+        const sentences = [
+            ...(closable.length > 0 ? [notClosedText(closable)] : []),
+            ...tunedOut.map((entry) => {
+                const ref = refOf(entry);
+                return `Channel ${channelOnServer(ref)} was not closed: it is tuned out, and a close doesn't change that. ` +
+                    this.tuneOutEndText(entry, 'channel_close', `channelId ${quotedValue(ref.channelId)} and serverId ${quotedValue(ref.serverId)}`);
+            }),
+        ];
+        return { focus: held, ...(sentences.length > 0 ? { notClosed: sentences.join(' ') } : {}) };
+    }
+    /**
+     * The refusal of a channel_close's bare name (focusNamedBare) that both the
+     * channel the all-except hold excepts (`focus`) and another channel of the
+     * calling turn's own (`mine`, ownChannelNamed) answer to, each named by
+     * what reaches it alone. The hold's channel is reached by its
+     * server-qualified name, registered or not (focusNamedBare), unless a
+     * channel of the turn's answers to that too; the turn's channel as a
+     * refusal of the turn's names shows it (ownCandidates), unless another
+     * channel of the turn's has its qualified name for its id. A serverId goes
+     * with the channel's own id, so it's offered only where the name is the id
+     * of both, for the hold's server (registered or not, the close reaches its
+     * channel: unregisteredFocusNamed) and for the turn's channel's where that
+     * server still registers it. Where the name is the hold channel's
+     * server-qualified name, which another of the turn's channels has for its
+     * id, the hold's channel is reached by its id and server.
+     */
+    focusOrOwnRefusal(name, focus, mine, own) {
+        const qualified = qualifiedChannelName(focus);
+        const focusReaches = this.ownChannelNamed(qualified, own) === undefined;
+        const [theirs] = this.ownCandidates([mine]);
+        // The turn's channel's name, as the focus's: a bare id answers to the
+        // turn's own channels first, so one of them with that id catches it.
+        const theirsReaches = theirs.reaches && this.ownChannelNamed(theirs.text, own) === undefined;
+        const parts = [
+            { text: focusReaches ? quotedValue(qualified) : channelOnServer(focus), reaches: focusReaches },
+            { text: theirsReaches ? quotedValue(theirs.text) : theirs.reaches ? channelOnServer(mine) : theirs.text, reaches: theirsReaches },
+        ];
+        const named = parts.filter((p) => p.reaches).map((p) => p.text);
+        const byName = named.length === 2 ? 'channelId set to one of them' : named.length === 1 ? `channelId ${named[0]}` : '';
+        const servers = name === focus.channelId ? [focus.serverId, ...(this.entryAt(mine) ? [mine.serverId] : [])] : [];
+        const byServer = servers.length > 0 ? `serverId set to ${servers.map((id) => JSON.stringify(id)).join(' or ')}` : '';
+        const how = [byName, byServer].filter((h) => h !== '').join(', or with ');
+        const focusRoute = name !== focus.channelId && !focusReaches
+            ? ` For the channel the focus excepts, call again with channelId ${quotedValue(focus.channelId)} and serverId ${JSON.stringify(focus.serverId)}.`
+            : '';
+        return `Channel ${JSON.stringify(name)} names both the channel the all-except focus excepts (${parts[0].text}) ` +
+            `and this turn's channel (${parts[1].text}), so nothing ran.${how ? ` Call again with ${how}.` : ''}${focusRoute}`;
+    }
+    /**
+     * The channel the all-except hold excepts (focusChannelResolver), where a
+     * channel tool's name with a serverId, or the calling turn's own channel's
+     * name, means it though its server no longer registers it: with a
+     * serverId, that server's channel with the id; inside the calling turn,
+     * the turn's own channel the name answers to by its id (ownChannelNamed).
+     * A name given alone is focusNamedBare's. Undefined where no hold is in
+     * force, where its channel is still registered, and where the hold's
+     * record can't be read, which leaves the name's refusal as it was.
+     */
+    unregisteredFocusNamed(name, serverId, own) {
+        let focus;
+        try {
+            focus = this.focusChannelResolver?.();
+        }
+        catch {
+            return undefined;
+        }
+        if (!focus || this.entryAt(focus))
+            return undefined;
+        if (serverId)
+            return sameChannel(focus, { serverId, channelId: name }) ? focus : undefined;
+        const mine = this.ownChannelNamed(name, own);
+        return mine && 'channel' in mine && sameChannel(mine.channel, focus) ? focus : undefined;
+    }
     async handleToolDecline(input, own) {
         const resolved = this.resolveToolChannelEntry(input.channelId, input.serverId, own);
         const entry = resolved.entry;
@@ -4651,8 +4941,8 @@ export class ChannelRegistry {
                             `diverted, and then call channel_close.${serverBack}`
                         : `. If you still want it closed, call channel_close.${serverBack}`;
             closeError = decided === 'tuned-out'
-                ? `The decline is recorded, but the channel was tuned out meanwhile, and that decision stands: its messages go to ` +
-                    `the subconscious${step}`
+                ? `The decline is recorded, but the channel was tuned out meanwhile, and that decision stands: its messages ` +
+                    `${this.tuneOutHeld()}${step}`
                 : `The decline is recorded, but a later decision to open the channel replaced it, and that decision stands${step}`;
         }
         else if (closed) {
@@ -4886,7 +5176,8 @@ export class ChannelRegistry {
         return CapabilityGrant.of(server).has('channels.streaming') ? server : null;
     }
     /** Resolve the outbound locus (fork HOME → this-turn's TRIGGERING channel →
-     *  process-global default), with its server. Public so a multi-segment
+     *  process-global default, with the configured unprompted channel in it
+     *  where the turn takes it), with its server. Public so a multi-segment
      *  caller can snapshot it ONCE and pin every segment to it via
      *  routeSpeech's locus. */
     resolveLocus(conversationId) {
@@ -4895,7 +5186,32 @@ export class ChannelRegistry {
             return home;
         // A turn that deliberately has no channel (null) takes no fallback.
         const active = this.activeChannelResolver?.(conversationId);
-        return active !== undefined ? active : this.globalFallbackFor(conversationId);
+        return active !== undefined
+            ? active
+            : this.globalFallbackFor(conversationId, () => this.configuredUnprompted(conversationId));
+    }
+    configuredUnprompted(conversationId) {
+        if (!this.unpromptedChannel)
+            return null;
+        if (conversationId !== undefined && this.takesUnpromptedChannel?.(conversationId) === false)
+            return null;
+        const named = this.entriesNamed(this.unpromptedChannel);
+        if (named.length === 1 && !isInboundOnly(named[0])) {
+            this.unpromptedChannelWarned = false;
+            return refOf(named[0]);
+        }
+        if (!this.unpromptedChannelWarned) {
+            this.unpromptedChannelWarned = true;
+            const why = named.length === 0
+                ? 'names no registered channel'
+                : named.length === 1
+                    ? 'names a channel its server declared inbound-only'
+                    : `names ${named.length} registered channels (name one with its server, as "serverId:channelId")`;
+            console.error(`[routing] unpromptedChannel ${logValue(this.unpromptedChannel)} ${why}, so a turn the agent's own timer starts `
+                + 'takes the fallback it takes without the setting until the setting names a channel it can speak in. '
+                + 'Not logged again until a turn has used it.');
+        }
+        return null;
     }
     /**
      * The process-global fallback for this conversation, or null when it takes
@@ -4903,18 +5219,20 @@ export class ChannelRegistry {
      * result, so neither the all-except hold's channel nor the latest inbound
      * message's is ever its destination.
      */
-    globalFallbackFor(conversationId) {
-        return this.takesGlobalFallback?.(conversationId) === false ? null : this.sharedFallback();
+    globalFallbackFor(conversationId, unprompted) {
+        return this.takesGlobalFallback?.(conversationId) === false ? null : this.sharedFallback(unprompted);
     }
     /**
      * 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).
+     * hold's channel while one is open, else, for a turn's locus, the
+     * configured unprompted channel where the turn takes it (resolveLocus),
+     * 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).
      */
-    sharedFallback() {
-        return this.focusChannelResolver?.() ?? this.fallbackLocus();
+    sharedFallback(unprompted) {
+        return this.focusChannelResolver?.() ?? unprompted?.() ?? this.fallbackLocus();
     }
     fallbackLocus() {
         return this.latestInboundLocus ? this.defaultPublishChannel : null;
@@ -5048,12 +5366,12 @@ export class ChannelRegistry {
         if (isInboundOnly(entry)) {
             return { status: 'failed', destination, reason: inboundOnlyReason(entry), at: at() };
         }
-        const server = this.serverRegistry.getServer(entry.serverId);
+        const server = this.publishingServer(entry.serverId);
         // §14.1: channels/publish requires channels.publish in the grant. The
         // host not sending is the enforcement, here and at the last check, and
         // the server's state words the refusal (sendRefusal).
         const ungranted = () => ({ status: 'failed', destination, reason: this.sendRefusal(entry.serverId), at: at() });
-        if (!server || !CapabilityGrant.of(server).has('channels.publish'))
+        if (!server)
             return ungranted();
         const prevented = (err) => ({
             status: 'failed', destination, reason: lifecycleClause(err) + refusalRemedy(err), at: at(),
@@ -5215,11 +5533,14 @@ export class ChannelRegistry {
     locus, 
     /** `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. */
+     *  An `unknown` outcome still gets its marker. `cameFrom`: with no
+     *  locus, the channels the turn's batch came from, each with how the
+     *  agent is shown it; the failure's reason names them, and how to reply
+     *  in those registered that take speech. */
     opts) {
         // `logged` is what the log line and the trace say, where it isn't the
-        // agent's reason (the two no-locus reasons below).
-        const fail = (channel, reason, outcome, logged = reason) => {
+        // agent's reason (the three no-locus reasons below).
+        const fail = (channel, reason, outcome, logged = reason, byDesign = false) => {
             const status = outcome.status === 'unknown' ? 'unknown' : 'failed';
             const channelId = channel?.channelId ?? null;
             const detail = outcome.detail !== undefined ? connectorText(outcome.detail) : undefined;
@@ -5239,16 +5560,18 @@ export class ChannelRegistry {
                 this.onRouteFailure?.({
                     conversationId, channelId, ...(channel ? { serverId: channel.serverId } : {}),
                     reason, textLen: text.length, outcome: status, ...(detail !== undefined ? { detail } : {}),
+                    ...(byDesign ? { byDesign: true } : {}),
                 });
             }
             return outcome;
         };
-        // These two reasons are the only ones whose log line and trace keep the
+        // These three reasons are the only ones whose log line and trace keep the
         // operator's words rather than the agent's: connectome-host's
         // connectome-doctor reads the last [routeSpeech] line for "no locus". Keep
-        // "no locus" in both logged texts. Each names no tool: whether one the
+        // "no locus" in each logged text. Each names no tool: whether one the
         // agent may call could post the words isn't known here, and the notice
-        // calls it a routing or configuration situation.
+        // calls it a routing or configuration situation, or for a turn whose
+        // batch named the channels it came from a routing one (byDesign).
         // 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.
@@ -5267,6 +5590,34 @@ export class ChannelRegistry {
             // global inbound ever seen) — the agent was told its prose stays in
             // the archive; honor that.
             // The locus froze at the turn's start, so this says what the turn had.
+            const from = opts?.cameFrom ?? [];
+            if (from.length > 0) {
+                const list = (names) => names.length === 1 ? names[0] : `${names.slice(0, -1).join(', ')} and ${names.at(-1)}`;
+                const closed = [];
+                const open = [];
+                for (const came of from) {
+                    const entry = this.entryAt(came.channel);
+                    if (!entry)
+                        closed.push(`${came.shown} isn't registered with this host now, so this host has no channel there to send to`);
+                    else if (isInboundOnly(entry))
+                        closed.push(`${came.shown} is ${inboundOnlyReason(entry)}`);
+                    else if (!this.publishingServer(entry.serverId)) {
+                        const reach = this.serverReach(entry.serverId);
+                        closed.push(reach === 'connecting' || reach === 'down'
+                            ? `${came.shown} can't take a send: ${unreachableClause(entry.serverId, reach)}, so to reply there, send your reply to that channel explicitly once it's back`
+                            : `${came.shown} can't take a send: ${this.sendRefusal(entry.serverId)}`);
+                    }
+                    else
+                        open.push(came);
+                }
+                const reply = open.length === 0 ? ''
+                    : open.length === from.length
+                        ? `; to reply ${from.length === 1 ? 'there' : 'in one of them'}, send your reply to that channel explicitly`
+                        : `; to reply in ${open.length === 1 ? open[0].shown : `one of ${list(open.map((c) => c.shown))}`}, send your reply to that channel explicitly`;
+                const reason = `this turn came from ${list(from.map((c) => c.shown))}, and no channel was chosen for its reply` +
+                    `${reply}${closed.map((c) => `; ${c}`).join('')}`;
+                return fail(null, reason, { status: 'failed', reason, at: Date.now() }, "turn has no locus (no channel was chosen for its batch's reply)", true);
+            }
             const reason = 'this turn came from no channel, and it had no home or recent channel to reply in; if it should have ' +
                 'had one, ask whoever runs this host';
             return fail(null, reason, { status: 'failed', reason, at: Date.now() }, 'turn has no locus (no home/trigger channel; nothing to deliver into)');
@@ -5293,8 +5644,8 @@ export class ChannelRegistry {
         return outcome;
     }
     /** deliverSpeech, reduced to the confirmed delivery (null when there was none). */
-    async routeSpeech(conversationId, text, locus) {
-        const outcome = await this.deliverSpeech(conversationId, text, locus);
+    async routeSpeech(conversationId, text, locus, opts) {
+        const outcome = await this.deliverSpeech(conversationId, text, locus, opts);
         if (outcome.status !== 'delivered')
             return null;
         return {
@@ -5358,8 +5709,13 @@ export class ChannelRegistry {
                         ? '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.'
                         : 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}`
+                            ? (this.channellessTurn && !this.channellessTurn(caller)
+                                // The turn came from a channel, but its speech goes to none
+                                // (a locked turn held as drafts).
+                                ? `Nothing was posted: name the channel with channelId. Your plain speech goes to no channel now, so `
+                                    + `channel_publish sends only to a channel it names. ${findIds}`
+                                : `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,
             };
@@ -5453,8 +5809,8 @@ export class ChannelRegistry {
         }
         // The same refusal, in the same words, as plain speech's (sendRefusal),
         // whose server state is the reason's: nothing awaits between the two.
-        const server = this.serverRegistry.getServer(entry.serverId);
-        if (!server || !CapabilityGrant.of(server).has('channels.publish')) {
+        const server = this.publishingServer(entry.serverId);
+        if (!server) {
             if (seen) {
                 const reach = this.serverReach(entry.serverId);
                 seen.refusal = reach === 'up' ? 'not-permitted' : `server-${reach}`;