@animalabs/agent-framework 0.6.10 → 0.7.2

package/src/framework.ts

@@ -10,6 +10,7 @@ import type {
   MessageQuery,
   MessageQueryResult,
   StoredMessage,
+  TokenBudget,
 } from '@animalabs/context-manager';
 import type {
   FrameworkConfig,
@@ -58,12 +59,20 @@ import { FeatureSetManager } from './mcpl/feature-set-manager.js';
 import { ScopeManager } from './mcpl/scope-manager.js';
 import { HookOrchestrator } from './mcpl/hook-orchestrator.js';
 import { PushHandler, type McplPushEvent } from './mcpl/push-handler.js';
+import { parseProsePrefix } from './mcpl/prose-grammar.js';
+import { ProseStreamRouter } from './mcpl/prose-stream-router.js';
 import { InferenceRouter } from './mcpl/inference-router.js';
 import { ChannelRegistry } from './mcpl/channel-registry.js';
 import { ConversationRouter } from './mcpl/conversation-router.js';
 import { safeSlice } from './safe-slice.js';
 import type { WorkspaceModule } from './modules/workspace/index.js';
 import { toolResultDataToHistoryString } from './tool-result-history.js';
+import { randomUUID } from 'node:crypto';
+import { PyRunner, buildInjectedTools } from './code-execution/py-runner.js';
+import {
+  buildCodeExecutionToolDefinition,
+  CODE_EXECUTION_TOOL_NAME,
+} from './code-execution/tool-definition.js';
 import { splitProseSegments } from './prose-segments.js';
 
 /** Detect a supported image media type from magic bytes (the model API
@@ -109,6 +118,110 @@ function sniffImageMediaType(data: Buffer): string | undefined {
 const SILENCING_TOOLS = new Set([
   'skip_reply', 'channel_publish', 'send_message', 'reply_message', 'send_dm',
 ]);
+
+/**
+ * True when an injected message is real conversational input — something the
+ * agent might actually be replying to — rather than ambient machinery.
+ * System markers (`system: true` — send-failed notices, routing notices) and
+ * reactions (`chat:reaction` tag, MCPL RFC-001) don't count: they must not
+ * clear explicit-send suppression, and they never influence routing.
+ */
+const isConversationalInjection = (metadata?: MessageMetadata): boolean => {
+  if (!metadata) return true;
+  const m = metadata as Record<string, unknown>;
+  if (m.system === true) return false;
+  if (Array.isArray(m.tags) && m.tags.includes('chat:reaction')) return false;
+  return true;
+};
+
+/**
+ * Explicit delivery tools whose successful use into a closed channel OPENS
+ * it (send implies engagement — see openIfClosedForSend). Bare tool names,
+ * matched after stripping the MCPL server prefix.
+ */
+const SEND_ENGAGEMENT_TOOLS = new Set([
+  'send_message', 'reply_message', 'send_dm', 'send_file', 'send_files',
+]);
+
+/**
+ * Best-effort extraction of the delivered channel id from an MCPL send-tool
+ * result (the discord-mcpl send tools return JSON like
+ * `{"messageId":"…","channelId":"…"}` as a text block). Returns undefined on
+ * any shape mismatch — the caller falls back to the tool's input args.
+ */
+function extractChannelIdFromToolResult(
+  content: Array<{ type: string; text?: string }> | undefined,
+): string | undefined {
+  const text = content?.find((c) => c.type === 'text' && c.text)?.text;
+  if (!text) return undefined;
+  try {
+    const parsed = JSON.parse(text) as { channelId?: unknown };
+    return typeof parsed.channelId === 'string' && parsed.channelId.length > 0
+      ? parsed.channelId
+      : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * True when an incoming channel message explicitly addressed the agent.
+ * Primary signal is the MCPL RFC-001 `chat:addressed` tag (mention / reply /
+ * DM, as classified by the server); the metadata booleans are the fallback
+ * for servers that predate tags. Addressed messages outrank ambient chatter
+ * when picking a turn's frozen speech locus.
+ */
+const isAddressedMessage = (
+  tags?: string[],
+  _metadata?: Record<string, unknown>,
+): boolean => Array.isArray(tags) && tags.includes('chat:addressed');
+
+// parseProsePrefix moved to ./mcpl/prose-grammar.ts — ONE grammar shared with
+// the outgoing-stream router (Spec 14.3), so streamed chunks and delivered
+// envelopes can never disagree on what is a prefix.
+
+/** One-time primer appended when an agent's proseRouting mode changes. */
+function proseModePrimer(mode: 'explicit' | 'locus'): string {
+  if (mode === 'locus') {
+    return '[prose-routing] Mode change: your plain text auto-routes to the ' +
+      'conversational locus again. `>>` destination prefixes are no longer needed.';
+  }
+  // Deliberately terse: a short event-style notice is classifier-safe from
+  // the user role (ablation D, 2026-07-24), while the full grammar as a user
+  // message drew a deterministic reasoning_extraction refusal (ablation A/B).
+  // The grammar is TAUGHT BY BOUNCE: the first undelivered text produces a
+  // notice with the exact resend syntax, and the full reference is available
+  // on demand via the prose_help tool (a tool RESULT is model-requested
+  // content — the safest role there is). Nothing is injected into the system
+  // prompt: those bytes belong to the recipe, and the deepest KV prefix must
+  // not vary with framework code.
+  return (
+    '[prose-routing] Output mode changed: plain text is delivered only with a ' +
+    'destination prefix line, e.g. ">>#channel-name your text". ' +
+    'The prose_help tool shows the full syntax.'
+  );
+}
+
+/** Full `>>` routing reference, served as the prose_help TOOL RESULT (never
+ *  injected ambiently — see proseModePrimer note). */
+const PROSE_ROUTING_HELP =
+  'Plain-text output routing (explicit mode):\n' +
+  '  >>#channel-name …    or    >>@person …  (DM)    or    >>service:guild:id …\n' +
+  '  One message may hold several sections: each line starting with ">>" begins\n' +
+  '  a new envelope, routed to its own destination independently.\n' +
+  '  The first destination in a turn applies to the rest of that turn.\n' +
+  '  Append " !" after the destination (e.g. ">>#ops !") to start your next turn\n' +
+  '  immediately when this one ends, instead of pausing until the next event.\n' +
+  '  >>skip_reply — text stays in your context only, like the skip_reply tool.\n' +
+  'Text without a destination is not delivered: it is retained, and a notice will\n' +
+  'prompt you to resend — reply e.g. ">>#channel {{unsent}}" to deliver the retained\n' +
+  'text unchanged. Send tools (send_message, send_dm, …) are unaffected.';
+
+const PROSE_HELP_TOOL: import('./types/index.js').ToolDefinition = {
+  name: 'prose_help',
+  description: 'Show the plain-text output routing syntax (destination prefixes, resend token, skip).',
+  inputSchema: { type: 'object' as const, properties: {} },
+};
 /** Strip the `server--` MCPL prefix from a tool name. */
 const bareToolName = (n: string): string => n.split('--').pop()!;
 import { CheckpointManager } from './mcpl/checkpoint-manager.js';
@@ -391,20 +504,38 @@ export class AgentFramework {
   private processLoggingBroadcast: boolean;
   private activeStreams: Map<string, Promise<void>> = new Map();
 
-  /** Per-agent output locus pinned for the CURRENT logical turn (see
-   *  resolveTurnLocus in driveStream). Lives here — not in driveStream
-   *  locals — so the pin survives a context-budget stream restart, which
-   *  continues the same logical turn in a fresh driveStream. A mid-turn
-   *  injected channel message replaces the pin for the next conversational
-   *  round; otherwise it remains stable. Cleared at the start of every
-   *  non-restart turn. */
+  /** Per-agent output locus FROZEN for the CURRENT logical turn. Resolved
+   *  eagerly in startAgentStream (home → addressed trigger → global default)
+   *  and never moved until the next turn: mid-turn injected messages — ambient
+   *  chatter, reactions, system markers — must not hijack where the agent's
+   *  plain prose lands (2026-07-21 Cairn lounge misroute). Lives here — not in
+   *  driveStream locals — so the pin survives a context-budget stream restart,
+   *  which continues the same logical turn in a fresh driveStream. Cleared or
+   *  re-set at the start of every non-restart turn. */
   private turnLocusPins: Map<string, string> = new Map();
-  /** A tool boundary injected fresh external input into the live stream.
-   *  Presence (including a null value) tells driveStream to clear sticky
-   *  explicit-send suppression before handling the next model round. A
-   *  string also moves that round's reply locus to the newest injected
-   *  channel. */
-  private midTurnRoutingResets: Map<string, string | null> = new Map();
+  /** A tool boundary injected fresh CONVERSATIONAL input (a real message —
+   *  not a reaction or a system marker) into the live stream. Tells
+   *  driveStream to clear sticky explicit-send suppression before handling
+   *  the next model round. Never affects routing: the turn locus is frozen. */
+  private midTurnInputSignals: Set<string> = new Set();
+  /** Last outbound locus announced to each agent as a durable `[routing]`
+   *  window message. Announce-on-change only: steady state emits nothing
+   *  (KV-safe, no per-turn chatter). In-memory — after a process restart the
+   *  first turn's locus is announced once to re-establish the baseline. */
+  private lastAnnouncedLocus: Map<string, string | null> = new Map();
+
+  // ---- Explicit prose routing (docs/explicit-prose-routing.md) ----------
+  /** Latest bounced (undelivered) prose per agent — the `{{unsent}}` source. */
+  private proseClipboards: Map<string, string> = new Map();
+  /** Sticky per-TURN delivery target set by the turn's first `>>` prefix.
+   *  Cleared at every non-restart turn start; survives context restarts. */
+  private proseTargetPins: Map<string, string> = new Map();
+  /** Agents whose current turn requested `!` continuation — re-woken when the
+   *  turn completes instead of pausing until the next external event. */
+  private proseContinuations: Set<string> = new Set();
+  /** Consecutive bounce-wakes per agent; capped so an agent that keeps
+   *  emitting unprefixed prose can't wake-loop (notices still append). */
+  private proseBounceStreaks: Map<string, number> = new Map();
   private pendingAssistantBlocks: Map<string, ContentBlock[]> = new Map();
   /** Streams the FRAMEWORK cancelled for non-terminal reasons, keyed
    *  `${agentName}:${streamId}`: an endTurn tool result or a context-budget
@@ -504,6 +635,18 @@ export class AgentFramework {
   /** Forks whose TTL closure turn has been queued — disposed (removed from
    * agents/agentConfigs/conversationAgentHomes) when their stream ends. */
   private closingConversationAgents: Set<string> = new Set();
+  // Client-side programmatic tool calling (`code_execution`). Null unless
+  // config.codeExecution.enabled. One PyRunner per agent (interpreter state
+  // is per-agent, like a per-agent container); waiters resolve script-inner
+  // tool calls dispatched through the normal dispatchToolCall path.
+  private codeExecutionConfig: import('./types/index.js').CodeExecutionConfig | null = null;
+  private codeExecutionRunners: Map<string, PyRunner> = new Map();
+  private scriptToolWaiters: Map<string, (result: ToolResult) => void> = new Map();
+  /** Agents whose running script hit an endTurn-carrying inner result —
+   *  deferred and applied to the final code_execution result instead of
+   *  cancelling the stream mid-script (which would wedge the turn). */
+  private scriptDeferredEndTurn: Set<string> = new Set();
+
   private mcplTools: import('./types/index.js').ToolDefinition[] = [];
   private mcplToolRefreshInFlight = false;
   private mcplToolRefreshPending = false;
@@ -771,6 +914,10 @@ export class AgentFramework {
     // that started with zero configured servers).
     framework.mcplInferenceRoutingConfig = config.inferenceRouting ?? null;
 
+    // Client-side programmatic tool calling (code_execution). Config is only
+    // retained when enabled — everything downstream gates on the field.
+    framework.codeExecutionConfig = config.codeExecution?.enabled ? config.codeExecution : null;
+
     // Initialize MCPL subsystems if configured
     if (config.mcplServers && config.mcplServers.length > 0) {
       // Validate tool prefixes: no collisions with module names or between servers
@@ -863,6 +1010,14 @@ export class AgentFramework {
     this.running = false;
     this.queue.close();
 
+    // Kill running code_execution scripts before cancelling streams: a
+    // zombie script must not keep firing side-effectful tool calls into a
+    // framework that is shutting down.
+    for (const runner of this.codeExecutionRunners.values()) {
+      runner.dispose();
+    }
+    this.codeExecutionRunners.clear();
+
     // Cancel all active streams
     for (const agent of this.agents.values()) {
       if (agent.state.status === 'streaming' ||
@@ -1160,6 +1315,9 @@ export class AgentFramework {
       ...(this.getWorkspaceModule()
         ? [AgentFramework.SAVE_IMAGE_TOOL, AgentFramework.READ_IMAGE_TOOL]
         : []),
+      ...(this.codeExecutionConfig
+        ? [buildCodeExecutionToolDefinition(this.codeExecutionConfig)]
+        : []),
     ];
   }
 
@@ -1296,25 +1454,55 @@ export class AgentFramework {
     return agent.getRuntimeSettings();
   }
 
+  /**
+   * Apply runtime settings.
+   *
+   * `opts.persist: false` makes the change EPHEMERAL: it takes effect live but
+   * is not written to the `framework/state` slot, so a restart reverts it. That
+   * is the mode for operator experiments ("change it, watch, revert") — the
+   * default persists, because a durable operational change should survive a
+   * bounce like every other override.
+   *
+   * Nothing here notifies the agent. Discovery is deliberately PULL: the agent
+   * can read current settings any time via the `agent_settings` tool's `get`
+   * action, which costs no context perturbation. Pushing a notice injects text
+   * into the very context being tuned — it invalidates the KV prefix and can
+   * itself trip a classifier — so callers opt into that explicitly rather than
+   * getting it by default.
+   *
+   * KNOWN LIMITATION of `persist: false`: the change still lands in the agent's
+   * in-memory override map, and `persistAgentRuntimeSettings` writes that whole
+   * map. So a LATER persisting call promotes any still-live ephemeral change to
+   * durable as a side effect. Ephemeral means "not written by THIS call", not
+   * "can never be written". Reset the ephemeral key before persisting something
+   * else if that matters. Making it airtight needs per-key ephemeral tracking
+   * inside Agent.
+   */
   updateAgentRuntimeSettings(
     agentName: string,
     patch: AgentRuntimeSettingsPatch,
+    opts?: { persist?: boolean },
   ): AgentRuntimeSettingsSnapshot {
     const agent = this.agents.get(agentName);
     if (!agent) throw new Error(`Unknown agent: ${agentName}`);
     const result = agent.updateRuntimeSettings(patch);
-    this.persistAgentRuntimeSettings(agentName, agent.getRuntimeSettingsOverrides());
+    if (opts?.persist !== false) {
+      this.persistAgentRuntimeSettings(agentName, agent.getRuntimeSettingsOverrides());
+    }
     return result;
   }
 
   resetAgentRuntimeSettings(
     agentName: string,
     keys?: Array<keyof AgentRuntimeSettingsPatch>,
+    opts?: { persist?: boolean },
   ): AgentRuntimeSettingsSnapshot {
     const agent = this.agents.get(agentName);
     if (!agent) throw new Error(`Unknown agent: ${agentName}`);
     const result = agent.resetRuntimeSettings(keys);
-    this.persistAgentRuntimeSettings(agentName, agent.getRuntimeSettingsOverrides());
+    if (opts?.persist !== false) {
+      this.persistAgentRuntimeSettings(agentName, agent.getRuntimeSettingsOverrides());
+    }
     return result;
   }
 
@@ -1375,7 +1563,7 @@ export class AgentFramework {
    */
   async previewActivation(
     agentName: string,
-    opts?: { injections?: boolean }
+    opts?: { injections?: boolean; budget?: TokenBudget }
   ): Promise<NormalizedRequest> {
     const agent = this.agents.get(agentName);
     if (!agent) {
@@ -1384,10 +1572,14 @@ export class AgentFramework {
 
     const tools = this.getToolsForAgent(agentName).filter((t) => agent.canUseTool(t.name));
 
+    // An explicit budget compiles against a HYPOTHETICAL window instead of the
+    // agent's live one. That also suppresses transition-settling in
+    // compileWithInjections (which only settles when no budget is passed), so
+    // previewing a smaller window cannot advance a converging descent.
     // Default: no dynamic injection gathering → fully transparent (no
     // inference, no Chronicle writes, no external RPC). Opt in explicitly.
     if (!opts?.injections) {
-      return agent.buildActivationRequest(tools, undefined);
+      return agent.buildActivationRequest(tools, undefined, opts?.budget);
     }
 
     // Full-fidelity path: mirrors startAgentStream's injection gathering.
@@ -1422,7 +1614,47 @@ export class AgentFramework {
       }
     }
 
-    return agent.buildActivationRequest(tools, injections);
+    return agent.buildActivationRequest(tools, injections, opts?.budget);
+  }
+
+  /**
+   * Non-committing preview of the FOLD PLAN at a hypothetical budget and/or
+   * context settings — the numbers behind an operator's "what happens if I set
+   * the budget to X" before they apply it.
+   *
+   * Unlike `previewActivation` (which renders a request), this returns the
+   * picker's plan: resulting tokens, whether it fits, how many summaries would
+   * have to be produced first, and the per-chunk fold levels. Commits nothing:
+   * no resolution persistence, no compression enqueue, no transition
+   * bookkeeping — see `AutobiographicalStrategy.previewContext`.
+   *
+   * Returns null when the agent's strategy has no fold plan (non-adaptive).
+   */
+  previewContextSettings(
+    agentName: string,
+    budgetTokens: number,
+    overrides?: Record<string, unknown>,
+    opts?: { render?: boolean },
+  ): unknown {
+    const agent = this.agents.get(agentName);
+    if (!agent) throw new Error(`Unknown agent: ${agentName}`);
+    const cm = agent.getContextManager() as unknown as {
+      previewContext?: (
+        budget: TokenBudget,
+        overrides?: Record<string, unknown>,
+        opts?: { render?: boolean },
+      ) => unknown;
+    };
+    if (typeof cm.previewContext !== 'function') return null;
+    // reserveForResponse mirrors the live compile so the previewed middle is
+    // comparable to what the agent actually gets. `opts.render` additionally
+    // returns the rendered entries — opt-in, since they are megabytes on a
+    // large store, and older context-manager builds ignore the argument.
+    return cm.previewContext(
+      { maxTokens: budgetTokens, reserveForResponse: agent.maxTokens },
+      overrides,
+      opts,
+    );
   }
 
   /**
@@ -3155,6 +3387,19 @@ export class AgentFramework {
     // Anthropic API.  If we let modules or MCPL handlers run first they may add
     // messages between tool_use and tool_result, causing a 400 error.
     if (event.type === 'tool-result') {
+      // Script-inner tool calls (client-side programmatic tool calling):
+      // resolve the waiter and stop. These calls belong to a RUNNING
+      // code_execution script, not to the agent's pending tool round — they
+      // must not touch agent state (and must resolve even for ephemeral
+      // agents that aren't in this.agents, or after the agent's own round
+      // has already settled).
+      const scriptWaiter = this.scriptToolWaiters.get(event.callId);
+      if (scriptWaiter) {
+        this.scriptToolWaiters.delete(event.callId);
+        scriptWaiter(event.result);
+        return;
+      }
+
       const agent = this.agents.get(event.agentName);
       if (agent) {
         this.touchEphemeralRun(event.agentName, true);
@@ -3257,23 +3502,17 @@ export class AgentFramework {
             }
           }
 
-          // A newly injected message begins a new conversational round inside
-          // the same provider inference. Remember that boundary for
-          // driveStream: an explicit send in the preceding round must not
-          // silence the reply, and the newest channel-bearing injection is
-          // now the reply locus. Map presence matters even without a channel
-          // (CLI/module input): it still clears the prior send suppression.
-          if (midTurnInjections.length > 0) {
-            const injectedChannelId = midTurnInjections.reduce<string | null>(
-              (latest, injection) => {
-                const candidate = injection.metadata?.channelId;
-                return typeof candidate === 'string' && candidate.length > 0
-                  ? candidate
-                  : latest;
-              },
-              null,
-            );
-            this.midTurnRoutingResets.set(agent.name, injectedChannelId);
+          // A newly injected CONVERSATIONAL message begins a new
+          // conversational round inside the same provider inference. Remember
+          // that boundary for driveStream: an explicit send in the preceding
+          // round must not silence the reply. Routing is deliberately NOT
+          // affected — the turn locus is frozen at turn start, so ambient
+          // chatter, reactions, and system markers injected mid-turn can no
+          // longer hijack where the agent's prose lands. Non-conversational
+          // injections (reactions, `system: true` markers) don't even clear
+          // the send suppression: nothing new was said to the agent.
+          if (midTurnInjections.some((inj) => isConversationalInjection(inj.metadata))) {
+            this.midTurnInputSignals.add(agent.name);
           }
 
           // Check if any tool result requested endTurn
@@ -3493,6 +3732,7 @@ export class AgentFramework {
     content: ContentBlock[];
     timestamp: string;
     metadata?: Record<string, unknown>;
+    tags?: string[];
     triggerInference?: boolean;
   }): Promise<void> {
     const metadata: Record<string, unknown> = {
@@ -3504,6 +3744,7 @@ export class AgentFramework {
       serverId: event.serverId,
     };
     if (event.threadId) metadata.threadId = event.threadId;
+    if (event.tags) metadata.tags = event.tags;
 
     // Per-channel conversation routing: messages go to the channel's fork
     // agent (spawned from the template on first qualifying message), never
@@ -3517,6 +3758,7 @@ export class AgentFramework {
     this.emitTrace({ type: 'message:added', messageId: id, source: 'mcpl:channel-incoming' });
 
     if (event.triggerInference) {
+      const addressed = isAddressedMessage(event.tags, event.metadata);
       for (const agentName of this.agents.keys()) {
         this.pendingRequests.push({
           agentName,
@@ -3526,6 +3768,9 @@ export class AgentFramework {
           // Route this turn's auto-published speech back to THIS channel, not
           // the global most-recent-inbound locus (item-3 redux, trunk agents).
           channelId: event.channelId,
+          // Addressed messages outrank ambient chatter when a batched wake
+          // picks the turn's frozen speech locus.
+          addressed,
         });
       }
     }
@@ -3545,6 +3790,7 @@ export class AgentFramework {
       author: { id: string; name: string };
       content: ContentBlock[];
       metadata?: Record<string, unknown>;
+      tags?: string[];
       triggerInference?: boolean;
     },
     messageMetadata: Record<string, unknown>,
@@ -3623,6 +3869,7 @@ export class AgentFramework {
         // A fork's home channel wins in routeSpeech regardless, but carry the
         // triggering channel too so the trunk/active path stays consistent.
         channelId: event.channelId,
+        addressed: isAddressedMessage(event.tags, event.metadata),
       });
     }
   }
@@ -3800,6 +4047,7 @@ export class AgentFramework {
         event.serverId,
         triggerChannel.channelId,
         triggerChannel.label,
+        triggerChannel.metadata,
       );
     }
 
@@ -3809,7 +4057,17 @@ export class AgentFramework {
       featureSet: event.featureSet,
       eventId: event.eventId,
       triggered: event.triggerInference ?? false,
+      ...(event.tags ? { tags: event.tags } : {}),
     };
+    // `origin.channelId` is the server-internal raw id (a bare Discord
+    // snowflake) — unroutable as a locus and unresolvable by the agent. Store
+    // the composite MCPL id instead wherever we can derive it, so anything
+    // downstream that reads `metadata.channelId` (routing, provenance, the
+    // agent itself) sees the qualified form. The raw value stays available on
+    // servers that also send `rawChannelId`-style origin fields.
+    if (triggerChannel) {
+      metadata.channelId = triggerChannel.channelId;
+    }
 
     const content = [...event.content];
     const addressedWhileClosed = triggerChannel &&
@@ -3867,6 +4125,10 @@ export class AgentFramework {
           source: event.serverId,
           timestamp: Date.now(),
           channelId: triggerChannel?.channelId,
+          // DMs and addressed-while-closed messages arrive as push events;
+          // they must outrank ambient chatter in a batched wake's locus
+          // selection just like their channels/incoming counterparts.
+          addressed: isAddressedMessage(event.tags, event.origin),
         });
       }
     }
@@ -3890,13 +4152,29 @@ export class AgentFramework {
    */
   private derivePushEventChannel(
     origin: Record<string, unknown> | undefined,
-  ): { channelId: string; label?: string } | undefined {
+  ): { channelId: string; label?: string; metadata?: Record<string, unknown> } | undefined {
     if (!origin) return undefined;
-    const label = typeof origin.channelName === 'string' ? origin.channelName : undefined;
+    let label = typeof origin.channelName === 'string' && origin.channelName ? origin.channelName : undefined;
+    let metadata: Record<string, unknown> | undefined;
+
+    // A DM has no channelName — label it by the PERSON and carry their
+    // identity, so DM registrations are people-first (`DM: antra`, matchable
+    // by `>>@name` / `<@id>` mention tokens) instead of bare snowflakes.
+    const isDM = origin.isDM === true || origin.guildId === null;
+    if (isDM && typeof origin.authorName === 'string' && origin.authorName) {
+      label = label ?? `DM: ${origin.authorName}`;
+      metadata = {
+        channelType: 'dm',
+        recipientName: origin.authorName,
+        ...(typeof origin.authorId === 'string' && origin.authorId
+          ? { recipientId: origin.authorId }
+          : {}),
+      };
+    }
 
     const explicit = origin.mcplChannelId;
     if (typeof explicit === 'string' && explicit) {
-      return { channelId: explicit, label };
+      return { channelId: explicit, ...(label ? { label } : {}), ...(metadata ? { metadata } : {}) };
     }
 
     // Discord fallback: reconstruct the composite from origin parts. `guildId`
@@ -3904,7 +4182,11 @@ export class AgentFramework {
     if (origin.source === 'discord' && typeof origin.channelId === 'string' && origin.channelId) {
       const guild =
         typeof origin.guildId === 'string' && origin.guildId ? origin.guildId : 'dm';
-      return { channelId: `discord:${guild}:${origin.channelId}`, label };
+      return {
+        channelId: `discord:${guild}:${origin.channelId}`,
+        ...(label ? { label } : {}),
+        ...(metadata ? { metadata } : {}),
+      };
     }
 
     return undefined;
@@ -3992,17 +4274,302 @@ export class AgentFramework {
       const trigger = requests[0];
       // Route this turn's auto-published speech to the channel that triggered
       // it (item-3 redux). A batched wake may carry several triggering channels
-      // (messages arrived in >1 channel while the agent was busy/idle) — reply
-      // in the MOST-RECENT one: it matches the legacy last-inbound semantics and
-      // is the message the agent is most likely answering. The common case is
-      // 1 message → 1 channel (unambiguous). Non-channel wakes carry no
-      // channelId, leaving the field undefined → global fallback. `reduce`
-      // keeps the last defined channelId across the (FIFO-ordered) batch.
-      const triggerChannel = requests.reduce<string | undefined>(
-        (acc, r) => r.channelId ?? acc,
-        undefined,
+      // (messages arrived in >1 channel while the agent was busy/idle):
+      //   1. the most recent ADDRESSED channel wins (mention / reply / DM —
+      //      someone explicitly spoke TO the agent);
+      //   2. else the most recent channel-bearing request (ambient message in
+      //      an open channel — legacy last-inbound semantics).
+      // Ambient chatter must not outrank an addressed message just by being
+      // newest (2026-07-21 Cairn lounge misroute, turn-start variant).
+      // Non-channel wakes (heartbeats, module events, reactions — which never
+      // carry channelId) leave both undefined → global fallback.
+      let ambientChannel: string | undefined;
+      let addressedChannel: string | undefined;
+      for (const r of requests) {
+        if (!r.channelId) continue;
+        ambientChannel = r.channelId;
+        if (r.addressed) addressedChannel = r.channelId;
+      }
+      const triggerChannel = addressedChannel ?? ambientChannel;
+      const triggerAddressed = addressedChannel !== undefined;
+      await this.startAgentStream(agent, {
+        ...trigger,
+        channelId: triggerChannel,
+        addressed: triggerAddressed,
+      });
+    }
+  }
+
+  /**
+   * Announce-on-change locus notice (turn-frozen routing). Appends a durable
+   * `[routing]` window message when the turn's effective outbound locus
+   * differs from the last one announced — the agent must never have to guess
+   * where its plain prose lands. Durable append (never retracted) keeps the
+   * KV prefix stable; change-only keeps it out of steady-state turns. The
+   * first resolution after boot announces only a non-null locus ("prose has
+   * no destination" is the unremarkable boot default). Never triggers
+   * inference; never locus-eligible itself (system + no channel metadata).
+   */
+  private announceLocusIfChanged(agentName: string, locus: string | null): void {
+    const hasBaseline = this.lastAnnouncedLocus.has(agentName);
+    const prev = this.lastAnnouncedLocus.get(agentName) ?? null;
+    if (hasBaseline ? prev === locus : locus === null) {
+      if (!hasBaseline) this.lastAnnouncedLocus.set(agentName, locus);
+      return;
+    }
+    this.lastAnnouncedLocus.set(agentName, locus);
+
+    const agent = this.agents.get(agentName);
+    if (!agent) return;
+
+    let text: string;
+    if (locus === null) {
+      text =
+        '[routing] Your plain speech currently has no channel — it stays in ' +
+        'your archive. Use an explicit send tool to reach a channel.';
+    } else {
+      const label = this.channelRegistry?.getDescriptor(locus)?.label;
+      const shown =
+        label && label !== locus
+          ? `${label.startsWith('#') ? label : `#${label}`} (${locus})`
+          : locus;
+      text =
+        `[routing] Your plain speech now lands in ${shown}. ` +
+        'Other channels need an explicit send tool.';
+    }
+
+    try {
+      const id = agent.getContextManager().addMessage(
+        'user',
+        [{ type: 'text', text }],
+        { system: true, kind: 'routing-notice' },
+      );
+      this.emitTrace({ type: 'message:added', messageId: id, source: 'routing-notice' });
+      console.error(
+        `[routing] ${agentName}: locus ${prev ?? '(none)'} -> ${locus ?? '(none)'} (announced in window)`,
+      );
+    } catch (err) {
+      console.error('announceLocusIfChanged: failed to record routing notice:', err);
+    }
+  }
+
+  /**
+   * Durable window notice for a channel the agent did not ask to open —
+   * subscription-policy admission, or an open forced by the agent's own
+   * delivery into a closed channel. The agent must always learn that new
+   * traffic will start flowing, and that `channel_close` opts out (their
+   * decision outranks policy). System message: never triggers inference,
+   * never conversational, never locus-eligible.
+   */
+  private recordChannelAutoOpenNotice(
+    agentName: string | undefined,
+    channels: Array<{ channelId: string; label?: string }>,
+    cause: 'subscription-policy' | 'opened-by-delivery' | 'opened-by-reply',
+  ): void {
+    if (channels.length === 0) return;
+    const shown = channels
+      .map((c) => (c.label && c.label !== c.channelId ? `${c.label} (${c.channelId})` : c.channelId))
+      .join(', ');
+    const plural = channels.length > 1;
+    const causeText =
+      cause === 'subscription-policy'
+        ? 'your subscription policy just admitted ' + (plural ? 'them' : 'it')
+        : 'your own message into the closed channel engaged it';
+    const text =
+      `[channels] Now open: ${shown} — ${causeText}. Ongoing traffic from ` +
+      (plural ? 'these channels' : 'this channel') +
+      ` will reach you. If you don't want ${plural ? 'one of them' : 'it'}, use channel_close — ` +
+      'your choice sticks; neither policy nor a later send will silently reopen it.';
+    try {
+      // Through framework.addMessage for mid-turn safety (deferral +
+      // hear-while-acting injection) — a delivery-forced open happens inside
+      // a live turn, and a direct context-manager append there would store
+      // the notice out of order. Targets the primary agent; connectome-host
+      // runs trunk-only, so this is the delivering agent in practice.
+      this.addMessage('user', [{ type: 'text', text }], { system: true, kind: 'channel-notice' });
+      console.error(`[channel] auto-open notice (${cause}) -> ${agentName ?? 'primary'}: ${shown}`);
+    } catch (err) {
+      console.error('recordChannelAutoOpenNotice failed:', err);
+    }
+  }
+
+  /**
+   * Explicit-prose-routing delivery gateway (docs/explicit-prose-routing.md).
+   * Every prose segment of an `explicit`-mode agent flows through here:
+   * parse the `>>` prefix, resolve the target, deliver — or bounce to the
+   * clipboard with a resend notice. Misdelivery is structurally impossible:
+   * nothing is ever sent to a destination the model did not name (directly
+   * or via the turn's sticky target).
+   */
+  private async deliverProse(agent: Agent, rawText: string): Promise<void> {
+    // Multi-envelope: a single prose block may address SEVERAL destinations —
+    // every line beginning with `>>` opens a new envelope, routed
+    // independently (first live use: Tilde 2026-07-24, one block carrying a
+    // letter to #tilde-mythos AND a `>>#tilde` aside; the single-envelope
+    // parser delivered the aside literally into the first destination —
+    // exactly the leak class this mode exists to kill). Text before the
+    // first `>>` is its own unprefixed envelope (sticky/bounce as usual).
+    const lines = rawText.split('\n');
+    const envelopes: string[] = [];
+    let current: string[] = [];
+    for (const line of lines) {
+      // Only a REAL prefix line opens an envelope: `>>` immediately followed
+      // by a target token. A quoted `>> arrow` (space after) stays body text.
+      if (/^>>\S/.test(line.trimStart()) && current.length > 0) {
+        envelopes.push(current.join('\n'));
+        current = [];
+      }
+      current.push(line);
+    }
+    if (current.length > 0) envelopes.push(current.join('\n'));
+
+    for (const envelope of envelopes) {
+      if (!envelope.trim()) continue;
+      await this.deliverProseEnvelope(agent, envelope.replace(/^\s+(?=>>)/, ''));
+    }
+  }
+
+  private async deliverProseEnvelope(agent: Agent, rawText: string): Promise<void> {
+    const name = agent.name;
+    const parsed = parseProsePrefix(rawText);
+    if (parsed.continueTurn) this.proseContinuations.add(name);
+
+    if (parsed.kind === 'private') {
+      // The text already lives in the assistant message (window/chronicle);
+      // "delivery" is deliberately a no-op. Consumes the retained text if the
+      // segment embedded it.
+      if (parsed.body.includes('{{unsent}}')) this.proseClipboards.delete(name);
+      console.error(`[prose] ${name}: >>skip_reply — ${parsed.body.length} chars kept in context (not sent)`);
+      return;
+    }
+
+    let targetChannel: string;
+    let body: string;
+    if (parsed.kind === 'target') {
+      const res = this.channelRegistry!.resolveProseTarget(parsed.target!);
+      if ('error' in res) {
+        this.bounceProse(agent, parsed.body, res.error, res.candidates);
+        return;
+      }
+      targetChannel = res.channelId;
+      // Sticky within the turn: later unprefixed segments follow this target.
+      this.proseTargetPins.set(name, targetChannel);
+      body = parsed.body;
+    } else {
+      const sticky = this.proseTargetPins.get(name);
+      if (!sticky) {
+        this.bounceProse(agent, rawText, 'no destination prefix and no destination set yet this turn');
+        return;
+      }
+      targetChannel = sticky;
+      body = rawText;
+    }
+
+    const usedClipboard = body.includes('{{unsent}}');
+    if (usedClipboard) {
+      body = body.replaceAll('{{unsent}}', this.proseClipboards.get(name) ?? '');
+    }
+    if (!body.trim()) {
+      console.error(`[prose] ${name}: empty body after prefix/substitution — nothing to send`);
+      return;
+    }
+
+    try {
+      const result = await this.channelRegistry!.routeSpeech(name, body, targetChannel);
+      if (result?.delivered) {
+        this.proseBounceStreaks.delete(name);
+        if (usedClipboard) this.proseClipboards.delete(name);
+      }
+    } catch (err) {
+      console.error(`[prose] ${name}: delivery to ${targetChannel} failed:`, err);
+    }
+  }
+
+  /** Cap on consecutive bounce-triggered wakes (notices still append after). */
+  private static readonly PROSE_BOUNCE_WAKE_CAP = 2;
+
+  private bounceProse(agent: Agent, text: string, reason: string, candidates?: string[]): void {
+    const name = agent.name;
+    this.proseClipboards.set(name, text);
+    const streak = (this.proseBounceStreaks.get(name) ?? 0) + 1;
+    this.proseBounceStreaks.set(name, streak);
+    const cand = candidates?.length ? ` Known channels it could mean: ${candidates.join(', ')}.` : '';
+    const notice =
+      `[prose-routing] Your text (${text.length} chars) was not delivered — ${reason}.${cand} ` +
+      'The text is retained; nothing is lost. To deliver it unchanged, reply with a ' +
+      'destination plus the token {{unsent}}, e.g. ">>#channel {{unsent}}" or ">>@person {{unsent}}". ' +
+      '">>skip_reply {{unsent}}" keeps it in context only. The prose_help tool shows the full syntax.';
+    try {
+      // Through framework.addMessage, NOT the context manager directly: while
+      // the turn is still streaming this defers the notice to the next tool
+      // boundary, where it is BOTH stored in order and injected into the live
+      // stream (hear-while-acting) — the model sees the error and can correct
+      // the prefix within the same turn. A direct append here would land the
+      // notice before the turn's assistant blocks (cache bust, invisible
+      // until the next compile).
+      const id = this.addMessage(
+        'user',
+        [{ type: 'text', text: notice }],
+        { system: true, kind: 'prose-bounce' },
+      );
+      if (id) this.emitTrace({ type: 'message:added', messageId: id, source: 'prose-bounce' });
+      else this.emitTrace({ type: 'message:added', messageId: 'deferred', source: 'prose-bounce' });
+    } catch (err) {
+      console.error('bounceProse: failed to record bounce notice:', err);
+    }
+    const capped = streak > AgentFramework.PROSE_BOUNCE_WAKE_CAP;
+    console.error(
+      `[prose] ${name}: BOUNCED ${text.length} chars — ${reason}` +
+      (capped ? ' (bounce-wake cap reached; notice appended without wake)' : ''),
+    );
+    if (!capped) {
+      // Wake so the resend can happen immediately — an unsent DM reply must
+      // not sit invisible until the next unrelated event.
+      this.pendingRequests.push({
+        agentName: name,
+        reason: 'prose-bounce',
+        source: 'framework',
+        timestamp: Date.now(),
+      });
+    }
+  }
+
+  /**
+   * One-time mode primer (docs/explicit-prose-routing.md): when an agent's
+   * configured proseRouting differs from the last mode we primed them for,
+   * append the teaching notice and persist the new mode. A brand-new agent
+   * in default locus mode is recorded silently — no primer for the status quo.
+   */
+  private maybePrimeProseMode(agent: Agent): void {
+    const mode = agent.proseRouting;
+    try {
+      const data = this.store.getStateJson(FRAMEWORK_STATE_ID);
+      const state = (data && typeof data === 'object' ? data : {}) as Record<string, unknown>;
+      const primed = { ...((state.proseRoutingPrimed as Record<string, string> | undefined) ?? {}) };
+      const stored = primed[agent.name];
+      if (stored === mode) return;
+      // Absence means "always default (locus)": a locus-mode agent that was
+      // never explicit needs no entry and no primer — and skipping the write
+      // keeps framework/state from growing a record per agent (scaling gate).
+      if (mode === 'locus' && stored === undefined) return;
+      if (mode === 'locus') delete primed[agent.name];
+      else primed[agent.name] = mode;
+      state.proseRoutingPrimed = primed;
+      this.store.setStateJson(FRAMEWORK_STATE_ID, state);
+    } catch (err) {
+      console.error('maybePrimeProseMode: state read/write failed:', err);
+      return;
+    }
+    try {
+      const id = agent.getContextManager().addMessage(
+        'user',
+        [{ type: 'text', text: proseModePrimer(mode) }],
+        { system: true, kind: 'prose-routing-primer' },
       );
-      await this.startAgentStream(agent, { ...trigger, channelId: triggerChannel });
+      this.emitTrace({ type: 'message:added', messageId: id, source: 'prose-routing-primer' });
+      console.error(`[prose] ${agent.name}: mode primer appended (${mode})`);
+    } catch (err) {
+      console.error('maybePrimeProseMode: failed to append primer:', err);
     }
   }
 
@@ -4019,14 +4586,60 @@ export class AgentFramework {
     // instead falls back to the global default. A given agent runs one turn at a
     // time, so a set here is only read during THIS turn's routeSpeech /
     // buildChannelContext; retries re-run with the same trigger, re-setting it.
-    if (trigger?.channelId) {
-      this.activeTriggerChannels.set(agent.name, trigger.channelId);
-    } else {
-      this.activeTriggerChannels.delete(agent.name);
+    // A context-budget restart continues the SAME logical turn in a fresh
+    // stream — its trigger carries no channelId, and deleting the trigger
+    // channel here mid-logical-turn is exactly the hole that sent Sol's DM
+    // reply to a stale guild channel (2026-07-22): any live locus resolution
+    // after the restart fell through to the hours-old defaultPublishChannel.
+    // Keep the turn's trigger channel across restarts; only real new turns
+    // reset it.
+    if (trigger?.reason !== 'context_budget_restart') {
+      if (trigger?.channelId) {
+        this.activeTriggerChannels.set(agent.name, trigger.channelId);
+      } else {
+        this.activeTriggerChannels.delete(agent.name);
+      }
+    }
+
+    // FREEZE this turn's outbound locus now (turn-frozen routing). Resolved
+    // once — home channel for forks, else the triggering channel, else the
+    // global default — and never moved for the rest of the turn: mid-turn
+    // injections must not redirect the agent's plain prose (ambient chatter /
+    // reactions hijacked it before, 2026-07-21). A context-budget restart
+    // continues the same logical turn, so it keeps the existing pin. The
+    // eager snapshot also protects heartbeat turns from a moving
+    // defaultPublishChannel mid-turn. If the effective locus differs from the
+    // last one announced, drop a durable `[routing]` notice into the window
+    // BEFORE this turn compiles, so the agent always knows where its voice
+    // goes (announce-on-change only — no per-turn chatter, append-only for
+    // KV stability).
+    if (trigger?.reason !== 'context_budget_restart') {
+      if (attempt === 0) this.maybePrimeProseMode(agent);
+      if (agent.proseRouting === 'explicit') {
+        // Explicit prose routing: there is no locus. The model names every
+        // destination in-band (`>>` prefixes); the only turn state is the
+        // sticky target, reset for each fresh turn. No freeze, no announce.
+        this.proseTargetPins.delete(agent.name);
+        this.proseContinuations.delete(agent.name);
+        this.midTurnInputSignals.delete(agent.name);
+        this.turnLocusPins.delete(agent.name);
+      } else {
+        const locus = this.channelRegistry?.resolveLocus(agent.name) ?? null;
+        if (locus !== null) this.turnLocusPins.set(agent.name, locus);
+        else this.turnLocusPins.delete(agent.name);
+        this.midTurnInputSignals.delete(agent.name);
+        if (attempt === 0) this.announceLocusIfChanged(agent.name, locus);
+      }
     }
 
     this.touchEphemeralRun(agent.name, true);
-    this.emitTrace({ type: 'inference:started', agentName: agent.name });
+    this.emitTrace({
+      type: 'inference:started',
+      agentName: agent.name,
+      // The turn-frozen locus was pinned just above (kept across a
+      // context-budget restart, which skips the re-pin but re-emits this).
+      channelId: this.turnLocusPins.get(agent.name),
+    });
     this.eventGate?.onInferenceStarted(agent.name);
     this.lastInferenceAt.set(agent.name, { ...this.lastInferenceAt.get(agent.name), startedAt: Date.now() });
 
@@ -4034,6 +4647,9 @@ export class AgentFramework {
       const requestSnapshot = this.captureInferenceToolSnapshot(agent);
       const allTools = this.getToolsForAgent(agent.name, requestSnapshot);
       const tools = allTools.filter((t) => agent.canUseTool(t.name));
+      // Explicit-mode agents get the on-demand routing reference (teach-by-
+      // bounce: the grammar is never injected, only served when asked).
+      if (agent.proseRouting === 'explicit') tools.push(PROSE_HELP_TOOL);
 
       // Gather context from modules (pull-based) and MCPL hooks (push-based)
       // Both produce ContextInjection[] that get merged before inference.
@@ -4138,24 +4754,15 @@ export class AgentFramework {
     let hadToolCalls = false;
 
     // ---- Present-while-acting turn state ---------------------------------
-    // Output locus for the current CONVERSATIONAL ROUND: resolved lazily and
-    // kept stable across tool-only rounds. A channel message injected at a
-    // tool boundary replaces the pin before the next model round, because a
-    // single provider inference can now contain several conversations. The
-    // pin lives in `turnLocusPins` so it survives a context-budget restart. A
-    // null resolution is not pinned.
-    if (trigger?.reason !== 'context_budget_restart') {
-      this.turnLocusPins.delete(agent.name);
-      this.midTurnRoutingResets.delete(agent.name);
-    }
-    const resolveTurnLocus = (): string | null => {
-      let locus = this.turnLocusPins.get(agent.name) ?? null;
-      if (locus === null && this.channelRegistry) {
-        locus = this.channelRegistry.resolveLocus(agent.name);
-        if (locus !== null) this.turnLocusPins.set(agent.name, locus);
-      }
-      return locus;
-    };
+    // Output locus for the WHOLE logical turn: frozen in startAgentStream
+    // (home → addressed trigger → global default) before this stream began,
+    // and never moved until the next turn. Mid-turn injections do not touch
+    // it — an ambient message or a reaction arriving at a tool boundary must
+    // not redirect the agent's task narration (2026-07-21 Cairn misroute).
+    // The pin lives in `turnLocusPins` so a context-budget restart (same
+    // logical turn, fresh driveStream) keeps it.
+    const resolveTurnLocus = (): string | null =>
+      this.turnLocusPins.get(agent.name) ?? null;
 
     // Ordered delivery chain for live-routed prose. Links are enqueued
     // WITHOUT awaiting in the stream-event loop — an awaited network post
@@ -4188,32 +4795,56 @@ export class AgentFramework {
     // delivered exactly once, at turn end.
     let liveProseRouting = false;
 
-    // Typing indicator: show "<agent> is typing…" in the channel she's
-    // responding to, for the whole duration of this turn. Started here (paired
-    // with the finally below, so it can never leak) and refreshed on a 7s
-    // interval by the ChannelRegistry until stopped on any exit path.
-    let typingChannel = this.channelRegistry
-      ? trigger?.channelId ?? this.channelRegistry.getDefaultPublishChannel()
-      : null;
+    // Typing indicator: show "<agent> is typing…" for the whole duration of
+    // this turn. Started here (paired with the finally below, so it can never
+    // leak) and refreshed on a 7s interval by the ChannelRegistry until
+    // stopped on any exit path. Never moves mid-turn.
+    //   - locus mode: the frozen routing pin (where bare prose will land).
+    //   - explicit mode: there is no locus — indicate on the TRIGGER channel
+    //     (where the wake came from). Typing is presence, not delivery, so
+    //     this doesn't violate never-guess: it says "attending to what you
+    //     sent here", which is true regardless of where the reply goes.
+    //     Heartbeat/no-trigger explicit turns show no indicator.
+    const typingChannel =
+      agent.proseRouting === 'explicit'
+        ? trigger?.channelId ?? null
+        : resolveTurnLocus();
     if (typingChannel) this.channelRegistry!.startTyping(typingChannel);
 
+    // MCPL Spec 14.3 outgoing streaming: route text deltas to their
+    // destination server AS THEY GENERATE (voice synthesis, live message
+    // rendering). Pure observer surface — suppression is fail-closed (nothing
+    // streams that delivery would refuse), emission is capability-gated in
+    // the registry (`channels.streaming`), and delivery via deliverProse
+    // remains the sole authoritative send.
+    const outgoingInferenceId = `inf_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
+    let outgoingIndex = 0;
+    const proseStream = this.channelRegistry
+      ? new ProseStreamRouter({
+          mode: agent.proseRouting === 'explicit' ? 'explicit' : 'locus',
+          initialTarget: typingChannel,
+          resolve: (spec) => {
+            const r = this.channelRegistry!.resolveProseTarget(spec);
+            return 'channelId' in r ? r.channelId : null;
+          },
+        })
+      : null;
+    const emitOutgoing = (deltas: { channelId: string; delta: string }[]): void => {
+      for (const rd of deltas) {
+        this.channelRegistry!.sendOutgoingChunk(
+          rd.channelId, agent.name, outgoingInferenceId, outgoingIndex++, rd.delta,
+        );
+      }
+    };
+
     const adoptInjectedRound = (): void => {
-      if (!this.midTurnRoutingResets.has(agent.name)) return;
-      const nextLocus = this.midTurnRoutingResets.get(agent.name) ?? null;
-      this.midTurnRoutingResets.delete(agent.name);
+      if (!this.midTurnInputSignals.has(agent.name)) return;
+      this.midTurnInputSignals.delete(agent.name);
 
-      // A new human/agent message, not merely a tool result, means any earlier
-      // explicit delivery has completed its conversational job.
+      // A new conversational message, not merely a tool result, means any
+      // earlier explicit delivery has completed its conversational job.
+      // Routing is NOT touched: the turn locus stays frozen.
       turnSilenced = false;
-
-      if (nextLocus) {
-        this.turnLocusPins.set(agent.name, nextLocus);
-        if (typingChannel !== nextLocus) {
-          if (typingChannel) this.channelRegistry?.stopTyping(typingChannel);
-          typingChannel = nextLocus;
-          this.channelRegistry?.startTyping(nextLocus);
-        }
-      }
     };
 
     try {
@@ -4227,7 +4858,14 @@ export class AgentFramework {
               content: event.content,
               blockType: event.meta.type,
               blockIndex: event.meta.blockIndex,
+              // Turn-frozen locus (same value as the typing indicator above):
+              // lets trace consumers tag every chunk with the channel this
+              // turn's prose is bound for, without re-deriving routing.
+              channelId: typingChannel ?? undefined,
             });
+            if (proseStream && event.meta.type === 'text') {
+              emitOutgoing(proseStream.feed(event.content));
+            }
             break;
 
           case 'block': {
@@ -4238,6 +4876,7 @@ export class AgentFramework {
               phase,
               blockType: block.type,
               blockIndex: index,
+              channelId: typingChannel ?? undefined,
             });
             break;
           }
@@ -4265,13 +4904,30 @@ export class AgentFramework {
                 (b) => b.type !== 'tool_result'
               );
             } else {
-              // Fallback (older membrane / XML tool mode): preamble + calls
+              // Fallback (older membrane / XML tool mode): preamble + calls.
+              // XML mode: persist the verbatim generation on each tool_use
+              // (membrane#36 round-trip fidelity). context.rawText is the
+              // parser's fullMatch — the exact <function_calls> block the
+              // model wrote (plus the harness-appended close tag), shared by
+              // every call in the round; the anthropic-xml formatter replays
+              // it byte-identically instead of reconstructing. Guarded by
+              // shape so a native-path fallback can never attach non-XML.
+              const rawText = event.context.rawText;
+              const rawXml = rawText && /^<(antml:)?function_calls>/.test(rawText)
+                ? rawText
+                : undefined;
               assistantBlocks = [];
               if (event.context.preamble) {
                 assistantBlocks.push({ type: 'text', text: event.context.preamble });
               }
               for (const c of event.calls) {
-                assistantBlocks.push({ type: 'tool_use', id: c.id, name: c.name, input: c.input as Record<string, unknown> });
+                assistantBlocks.push({
+                  type: 'tool_use',
+                  id: c.id,
+                  name: c.name,
+                  input: c.input as Record<string, unknown>,
+                  ...(rawXml ? { rawXml } : {}),
+                });
               }
             }
             this.pendingAssistantBlocks.set(agent.name, assistantBlocks);
@@ -4311,7 +4967,21 @@ export class AgentFramework {
                 liveProseRouting = true;
                 const roundSegments = splitProseSegments(assistantBlocks);
                 if (roundSegments.length > 0) {
-                  if (turnSilenced) {
+                  if (agent.proseRouting === 'explicit') {
+                    // Explicit mode: every segment through the prose gateway.
+                    // Silencing does not apply — unprefixed prose bounces and
+                    // prefixed prose is deliberate; think-privacy still holds.
+                    if (!hasSameRoundPrivateThink) {
+                      console.error(
+                        `[prose] ${agent.name}: mid-turn round [${roundToolNames.join(', ')}] -> ${roundSegments.length} segment(s) via prose gateway`,
+                      );
+                      for (const seg of roundSegments) {
+                        turnSpeechChain = turnSpeechChain
+                          .then(() => this.deliverProse(agent, seg))
+                          .catch((err) => console.error('mid-turn prose delivery failed:', err));
+                      }
+                    }
+                  } else if (turnSilenced) {
                     console.error(
                       `[routing] ${agent.name}: mid-turn round [${roundToolNames.join(', ')}] -> prose NOT routed (turn silenced)`,
                     );
@@ -4635,10 +5305,29 @@ export class AgentFramework {
                 .join('\n')
                 .trim();
               if (speechText) {
-                try {
-                  await this.channelRegistry.routeSpeech(agent.name, speechText);
-                } catch (err) {
-                  console.error('speech routing failed:', err);
+                if (agent.proseRouting === 'explicit') {
+                  console.error(`[prose] ${agent.name}: text-only turn -> prose gateway`);
+                  try {
+                    await this.deliverProse(agent, speechText);
+                  } catch (err) {
+                    console.error('text-only prose delivery failed:', err);
+                  }
+                } else {
+                  // Route to the TURN-FROZEN locus, like every other speech
+                  // path. This dispatch runs AFTER the agent is idle, so a live
+                  // resolution here can read the NEXT turn's trigger state (or
+                  // a post-restart cleared one) and land the reply in a stale
+                  // channel — the 2026-07-22 Sol DM-to-guild misroute. The
+                  // frozen pin is immune to both races.
+                  const locus = resolveTurnLocus();
+                  console.error(
+                    `[routing] ${agent.name}: text-only turn -> routing speech -> ${locus ?? '(none)'}`,
+                  );
+                  try {
+                    await this.channelRegistry.routeSpeech(agent.name, speechText, locus);
+                  } catch (err) {
+                    console.error('speech routing failed:', err);
+                  }
                 }
               }
             } else if (this.channelRegistry && hadToolCalls && allText.length > 0) {
@@ -4671,7 +5360,20 @@ export class AgentFramework {
               // the chain may still be flushing earlier rounds' posts.
               await turnSpeechChain;
 
-              if (silenced || segments.length === 0) {
+              if (agent.proseRouting === 'explicit') {
+                if (segments.length > 0) {
+                  console.error(
+                    `[prose] ${agent.name}: tool-call turn [${toolNames.join(', ')}] -> ${segments.length} trailing segment(s) via prose gateway`,
+                  );
+                  for (const seg of segments) {
+                    try {
+                      await this.deliverProse(agent, seg);
+                    } catch (err) {
+                      console.error('trailing prose delivery failed:', err);
+                    }
+                  }
+                }
+              } else if (silenced || segments.length === 0) {
                 console.error(
                   `[routing] ${agent.name}: tool-call turn [${toolNames.join(', ') || 'none'}] -> trailing prose NOT routed ` +
                   `(${silenced ? 'silencing tool / explicit send' : 'no trailing prose'})`,
@@ -4702,6 +5404,21 @@ export class AgentFramework {
             // BEFORE dispatchSpeech. Locus routing is speech dispatch and
             // doesn't depend on the status field, so it correctly runs after.
 
+            // Explicit-prose `!` continuation: a prose segment this turn asked
+            // to keep going (`>>#x !` / `>>private !`) — start another turn
+            // now instead of pausing until the next external event. This gives
+            // prose the same continuation ability tool rounds have (wanted for
+            // robotics-style loops where an end-of-turn pause is harmful).
+            if (this.proseContinuations.delete(agent.name)) {
+              console.error(`[prose] ${agent.name}: '!' continuation — requesting immediate next turn`);
+              this.pendingRequests.push({
+                agentName: agent.name,
+                reason: 'prose-continuation',
+                source: 'framework',
+                timestamp: Date.now(),
+              });
+            }
+
             break;
           }
 
@@ -4728,6 +5445,7 @@ export class AgentFramework {
             // Only reset + retry if this is still the active stream
             if (agent.streamId !== myStreamId) break;
 
+            this.abortAgentScript(agent.name, 'stream error');
             agent.reset();
 
             const action = this.errorPolicy.onInferenceError(err, agent.name, attempt);
@@ -4775,6 +5493,7 @@ export class AgentFramework {
             // may have already started a new stream, bumping streamId)
             if (agent.streamId === myStreamId) {
               const durationMs = Date.now() - startTime;
+              this.abortAgentScript(agent.name, `stream aborted (${reason})`);
               agent.reset();
               this.settleAgent(agent.name, {
                 stopReason: 'exhausted',
@@ -4879,6 +5598,7 @@ export class AgentFramework {
         request: compiledRequest ?? { note: 'streaming request threw' },
         durationMs,
       });
+      this.abortAgentScript(agent.name, 'stream threw');
       agent.reset();
       this.eventGate?.onInferenceEnded(agent.name);
     } finally {
@@ -4895,6 +5615,16 @@ export class AgentFramework {
       // Stop the typing indicator on every exit path (complete, error,
       // exhausted, abort) so it never sticks after the turn ends.
       this.channelRegistry?.stopTyping();
+
+      // Spec 14.3: flush any held line-start text, then close each streamed
+      // channel with its final moderated content — the consumer's signal to
+      // finalize (end the TTS utterance, settle the rendered message).
+      if (proseStream) {
+        emitOutgoing(proseStream.finish());
+        for (const [channelId, text] of proseStream.byChannel()) {
+          this.channelRegistry!.sendOutgoingComplete(channelId, agent.name, outgoingInferenceId, text);
+        }
+      }
       this.frameworkCancelledStreams.delete(`${agent.name}:${myStreamId}`);
       this.activeStreams.delete(agent.name);
       this.pendingAssistantBlocks.delete(agent.name);
@@ -4921,6 +5651,13 @@ export class AgentFramework {
    * Used by SubagentModule to dispatch tool calls for ephemeral agents.
    */
   async executeToolCall(call: ToolCall): Promise<ToolResult> {
+    // Client-side programmatic tool calling for promise-based callers
+    // (SubagentModule ephemerals). Keyed by callerAgentName so each ephemeral
+    // gets its own interpreter state.
+    if (call.name === CODE_EXECUTION_TOOL_NAME && this.codeExecutionConfig) {
+      return this.runCodeExecution(call.callerAgentName ?? '__ephemeral__', call);
+    }
+
     // MCPL tools are dispatched via the MCPL subsystem
     if (this.mcplServerRegistry) {
       // Check if this is an MCPL-prefixed tool
@@ -4970,6 +5707,199 @@ export class AgentFramework {
     }
   }
 
+  // ---------------------------------------------------------------------------
+  // Client-side programmatic tool calling (code_execution)
+  // ---------------------------------------------------------------------------
+
+  /** Event-pushing wrapper for the model-driven dispatch path. */
+  private dispatchCodeExecutionToolCall(agentName: string, call: ToolCall): void {
+    this.emitTrace({
+      type: 'tool:started',
+      module: 'code_execution',
+      tool: call.name,
+      callId: call.id,
+      input: call.input,
+    });
+    const startTime = Date.now();
+    this.runCodeExecution(agentName, call)
+      .catch((error): ToolResult => {
+        // runCodeExecution is designed not to reject; this is the last-resort
+        // guard so a bug here can never strand the agent in waiting_for_tools.
+        const err = error instanceof Error ? error : new Error(String(error));
+        return { success: false, error: `code_execution failed: ${err.message}`, isError: true };
+      })
+      .then((result) => {
+        if (result.isError) {
+          this.emitTrace({
+            type: 'tool:failed',
+            module: 'code_execution',
+            tool: call.name,
+            callId: call.id,
+            error: result.error ?? 'unknown error',
+          });
+        } else {
+          this.emitTrace({
+            type: 'tool:completed',
+            module: 'code_execution',
+            tool: call.name,
+            callId: call.id,
+            durationMs: Date.now() - startTime,
+          });
+        }
+        this.pushEvent({
+          type: 'tool-result',
+          callId: call.id,
+          agentName,
+          moduleName: 'code_execution',
+          result,
+        });
+      });
+  }
+
+  /**
+   * Run one code_execution script for an agent. Never rejects.
+   *
+   * The script runs in the agent's persistent python interpreter with every
+   * tool on the agent's CURRENT surface injected (minus code_execution
+   * itself). Inner tool calls are dispatched through dispatchToolCall — the
+   * exact model path, including MCPL state/checkpoint handling, channel
+   * routing, and traces — and resolved via scriptToolWaiters, so their
+   * results reach the running script and never the model context.
+   */
+  private async runCodeExecution(agentName: string, call: ToolCall): Promise<ToolResult> {
+    const input = (call.input ?? {}) as { code?: unknown };
+    if (typeof input.code !== 'string' || input.code.trim() === '') {
+      return {
+        success: false,
+        error: 'code_execution requires a non-empty `code` string',
+        isError: true,
+      };
+    }
+
+    const agent = this.agents.get(agentName);
+    const surface = agent
+      ? this.getToolsForAgent(agentName).filter((t) => agent.canUseTool(t.name))
+      : this.getAllTools(); // ephemeral agents: full surface, matching executeToolCall
+    const injected = buildInjectedTools(
+      surface.map((t) => t.name).filter((name) => name !== CODE_EXECUTION_TOOL_NAME),
+    );
+
+    const runner = this.getOrCreateScriptRunner(agentName);
+    this.scriptDeferredEndTurn.delete(agentName);
+    const exec = await runner.exec(input.code, injected);
+    const endTurn = this.scriptDeferredEndTurn.delete(agentName);
+
+    return {
+      success: true,
+      data: { stdout: exec.stdout, stderr: exec.stderr, return_code: exec.returnCode },
+      isError: false,
+      ...(endTurn ? { endTurn: true } : {}),
+    };
+  }
+
+  private getOrCreateScriptRunner(agentName: string): PyRunner {
+    let runner = this.codeExecutionRunners.get(agentName);
+    if (!runner) {
+      const cfg = this.codeExecutionConfig;
+      runner = new PyRunner({
+        pythonPath: cfg?.pythonPath,
+        toolCallTimeoutMs: cfg?.toolCallTimeoutMs,
+        scriptTimeoutMs: cfg?.scriptTimeoutMs,
+        idleReclaimMs: cfg?.idleReclaimMs,
+        label: agentName,
+        onToolCall: (toolName, args) => this.handleScriptToolCall(agentName, toolName, args),
+      });
+      this.codeExecutionRunners.set(agentName, runner);
+    }
+    return runner;
+  }
+
+  /**
+   * Resolve one script-inner tool call to the string the script's tool
+   * function returns. Never rejects — errors become "Error: ..." strings,
+   * matching the managed PTC runtime ("Claude's code receives this error").
+   *
+   * Results are serialized with the HISTORY serializer (images become
+   * placeholders): programmatic tool results are text-only by contract, and
+   * a script variable holding megabytes of base64 helps nobody.
+   */
+  private async handleScriptToolCall(
+    agentName: string,
+    toolName: string,
+    args: Record<string, unknown>,
+  ): Promise<string> {
+    if (toolName === CODE_EXECUTION_TOOL_NAME) {
+      return 'Error: code_execution cannot be called from within a script';
+    }
+    const result = await this.dispatchScriptToolCall(agentName, toolName, args);
+    if (result.endTurn) {
+      // Deferred: applied to the final code_execution result (see
+      // scriptDeferredEndTurn) — ending the turn mid-script would cancel the
+      // stream while the script still runs and wedge the tool round.
+      this.scriptDeferredEndTurn.add(agentName);
+    }
+    if (result.isError) {
+      return `Error: ${result.error ?? 'tool call failed'}`;
+    }
+    if (result.data === undefined) return '';
+    const agent = this.agents.get(agentName);
+    const maxChars = agent ? this.getMaxToolResultChars(agent) : undefined;
+    return toolResultDataToHistoryString(result.data, maxChars);
+  }
+
+  /**
+   * Dispatch a script-inner tool call through the NORMAL dispatch path and
+   * resolve with its result. The waiter intercept in handleProcessEvent
+   * (keyed by the pytc- call ID) routes the tool-result event here instead
+   * of into the agent's pending tool round.
+   */
+  private dispatchScriptToolCall(
+    agentName: string,
+    toolName: string,
+    args: Record<string, unknown>,
+  ): Promise<ToolResult> {
+    return new Promise<ToolResult>((resolve) => {
+      const callId = `pytc-${randomUUID()}`;
+      // Host-side leak guard: the python runtime already raises TimeoutError
+      // at toolCallTimeoutMs; this only reclaims the waiter if a dispatch path
+      // loses the result entirely (so the map cannot grow unboundedly).
+      const safetyMs = (this.codeExecutionConfig?.toolCallTimeoutMs ?? 270_000) + 30_000;
+      const safety = setTimeout(() => {
+        if (this.scriptToolWaiters.delete(callId)) {
+          resolve({
+            success: false,
+            error: `tool '${toolName}' produced no result within ${Math.round(safetyMs / 1000)}s`,
+            isError: true,
+          });
+        }
+      }, safetyMs);
+      safety.unref?.();
+
+      this.scriptToolWaiters.set(callId, (result) => {
+        clearTimeout(safety);
+        resolve(result);
+      });
+
+      try {
+        this.dispatchToolCall(agentName, { id: callId, name: toolName, input: args });
+      } catch (error) {
+        if (this.scriptToolWaiters.delete(callId)) {
+          clearTimeout(safety);
+          const err = error instanceof Error ? error : new Error(String(error));
+          resolve({ success: false, error: err.message, isError: true });
+        }
+      }
+    });
+  }
+
+  /** Abort a running script when the agent's turn dies underneath it. */
+  private abortAgentScript(agentName: string, reason: string): void {
+    const runner = this.codeExecutionRunners.get(agentName);
+    if (runner?.busy) {
+      runner.abort(reason);
+    }
+  }
+
   private toMembraneToolResult(callId: string, afResult: ToolResult, maxChars?: number): MembraneToolResult {
     if (afResult.isError) {
       return { toolUseId: callId, content: afResult.error ?? 'Unknown error', isError: true };
@@ -5209,6 +6139,29 @@ export class AgentFramework {
       return;
     }
 
+    // Client-side programmatic tool calling: run a python script that calls
+    // the agent's other tools in-process (script-inner calls come back through
+    // this very dispatcher with waiter-tracked call IDs).
+    if (enrichedCall.name === CODE_EXECUTION_TOOL_NAME && this.codeExecutionConfig) {
+      this.dispatchCodeExecutionToolCall(agentName, enrichedCall);
+      return;
+    }
+
+    // prose_help: on-demand routing reference for explicit-prose agents.
+    // Answered inline — the grammar is a tool RESULT (model-requested), never
+    // ambient context (see PROSE_ROUTING_HELP / teach-by-bounce).
+    if (enrichedCall.name === 'prose_help') {
+      this.emitTrace({ type: 'tool:completed', module: 'framework', tool: 'prose_help', callId: enrichedCall.id, durationMs: 0 });
+      this.pushEvent({
+        type: 'tool-result',
+        callId: enrichedCall.id,
+        agentName,
+        moduleName: 'framework',
+        result: { success: true, data: PROSE_ROUTING_HELP },
+      });
+      return;
+    }
+
     const sepIndex = enrichedCall.name.indexOf('--');
     const moduleName = sepIndex >= 0 ? enrichedCall.name.substring(0, sepIndex) : 'unknown';
     const toolName = sepIndex >= 0 ? call.name.substring(sepIndex + 2) : call.name;
@@ -5587,6 +6540,13 @@ export class AgentFramework {
     if (err.name === 'OverBudgetError') {
       return { errorType: 'over_budget' };
     }
+    // context-manager's fatal coverage invariant (fix/coverage-invariant-fatal,
+    // 2026-07-26): a compile REFUSES rather than shipping a context with
+    // silently-dropped messages. Recovery is identical to over_budget — kick
+    // the compression drain so summaries cover the un-represented span.
+    if (err.name === 'UncoveredDropError') {
+      return { errorType: 'context_refusal' };
+    }
     return {};
   }
 
@@ -5656,7 +6616,25 @@ export class AgentFramework {
     // (e.g. a reason string that crossed a serialization boundary). It matches
     // CM's current OverBudgetError wording and MAY rot if CM rewords it — the
     // errorType gate is the one that's load-bearing.
-    const overBudget = errorType === 'over_budget' || /exceed hard budget/i.test(reason);
+    const overBudget =
+      errorType === 'over_budget' ||
+      errorType === 'context_refusal' ||
+      /exceed hard budget|no summary covers/i.test(reason);
+    // Observability: a refused compile means the agent cannot think AT ALL
+    // this turn — surface it on the ops-alert pipeline (ops:alert trace +
+    // webhook → fleet-watch) immediately, not only at the hard-down streak.
+    // The per-(agent,kind) cooldown throttles repeats; failures.log already
+    // has the per-exhaustion record from logFailure above.
+    if (overBudget) {
+      this.opsAlert(
+        'context-refusal',
+        agentName,
+        `compile refused (${errorType ?? 'unclassified'}): ${reason.slice(0, 300)} — ` +
+        `drain breaker ${agent ? 'kicking' : 'unavailable (no agent handle)'}; ` +
+        `if this persists, raise contextBudgetTokens or overBudgetGraceRatio.`,
+        { skipLog: true },
+      );
+    }
     if (agent && overBudget && !this.overBudgetDrainInFlight.has(agentName)) {
       this.overBudgetDrainInFlight.add(agentName);
       void (async () => {
@@ -5853,11 +6831,24 @@ export class AgentFramework {
         // yes, wake no).
         onRouteFailure: ({ channelId, reason, textLen }) => {
           try {
+            // Render a human-readable channel name when we can — a bare
+            // snowflake in the marker is unresolvable for the agent (the
+            // 2026-07-21 incident read as "a stale artifact", not a live
+            // failure). The marker is `system: true`, so it is never
+            // conversational and never influences routing.
+            const label = channelId
+              ? this.channelRegistry?.getDescriptor(channelId)?.label
+              : undefined;
+            const where = channelId
+              ? label && label !== channelId
+                ? `${label.startsWith('#') ? label : `#${label}`} (${channelId})`
+                : channelId
+              : 'the channel';
             this.addMessage(
               'user',
               [{
                 type: 'text',
-                text: `[discord-send-failed] Your previous reply (${textLen} chars) could not be delivered to ${channelId ?? 'the channel'} (${reason}). It was saved to your archive but the human did not receive it.`,
+                text: `[discord-send-failed] Your previous reply (${textLen} chars) could not be delivered to ${where} (${reason}). It was saved to your archive but the human did not receive it.`,
               }],
               { system: true, kind: 'discord-send-failed', channelId: channelId ?? '', reason },
             );
@@ -5865,6 +6856,13 @@ export class AgentFramework {
             console.error('onRouteFailure: failed to record send-failure marker:', err);
           }
         },
+        // A channel opened without the agent asking (policy admission or an
+        // open forced by delivery) must be announced in the window, with the
+        // opt-out named. Routed here so registry-driven opens and framework-
+        // driven opens produce the same durable notice.
+        onChannelAutoOpened: ({ conversationId, source, channels }) => {
+          this.recordChannelAutoOpenNotice(conversationId, channels, source);
+        },
       },
     );
 
@@ -6904,6 +7902,44 @@ export class AgentFramework {
           }
         }
 
+        // INVARIANT: engaging a channel opens it. A successful explicit send
+        // into a channel the registry knows as closed drives the same open
+        // flow as channel_open (durable desired state, server subscribe), so
+        // there is no such thing as posting into a channel that stays
+        // half-alive (no typing, no reactions, no inbound forwarding).
+        // Fire-and-forget: the send already succeeded; the open must not
+        // delay or fail the tool result.
+        if (
+          this.channelRegistry &&
+          SEND_ENGAGEMENT_TOOLS.has(toolName) &&
+          result.isError !== true
+        ) {
+          const target =
+            extractChannelIdFromToolResult(result.content) ??
+            (typeof args.channelId === 'string' ? (args.channelId as string) : undefined);
+          if (target) {
+            this.channelRegistry
+              .openIfClosedForSend(target, serverId)
+              .then(({ status, channelId, label }) => {
+                if (status === 'opened') {
+                  console.error(
+                    `[channel] ${agentName}: explicit ${toolName} into closed channel ${target} — opened (send implies engagement)`,
+                  );
+                  this.recordChannelAutoOpenNotice(
+                    agentName,
+                    [{ channelId: channelId ?? target, label }],
+                    'opened-by-reply',
+                  );
+                } else if (status === 'open-failed') {
+                  console.error(
+                    `[channel] ${agentName}: ${toolName} delivered to ${target} but the open-on-send failed — channel remains half-alive, will reconcile`,
+                  );
+                }
+              })
+              .catch((err) => console.error('[channel] open-on-send error:', err));
+          }
+        }
+
         // Convert MCP tool result to framework ToolResult.
         // When the result contains non-text blocks (e.g. images from an MCP
         // tool like zulip-mcp's fetch_attachment), pass the full content array
@@ -7152,12 +8188,29 @@ export class AgentFramework {
       : seconds >= 60 ? `${Math.round(seconds / 60)}m`
       : `${Math.round(seconds)}s`;
 
-    // Announce in the sticky channel (best-effort; never blocks the result).
+    // Announce in the TURN's frozen locus (best-effort; never blocks the
+    // result). The sleep tool runs mid-turn, so the pin is live — same
+    // authority as every other speech path, no live re-resolution.
     if (announce && this.channelRegistry) {
       const text = input.message ?? `💤 Going quiet for ${human}. I'll still see messages, but won't respond until I wake.`;
-      this.channelRegistry.routeSpeech(agentName, text).catch((err) => {
-        console.error('[sleep] announce failed:', err instanceof Error ? err.message : err);
-      });
+      const agent = this.agents.get(agentName);
+      if (agent?.proseRouting === 'explicit') {
+        // Explicit mode: announce to the turn's sticky prose target if the
+        // model has set one; otherwise stay quiet — never guess a channel.
+        const target = this.proseTargetPins.get(agentName);
+        if (target) {
+          this.channelRegistry.routeSpeech(agentName, text, target).catch((err) => {
+            console.error('[sleep] announce failed:', err instanceof Error ? err.message : err);
+          });
+        } else {
+          console.error(`[sleep] ${agentName}: no prose target this turn — sleep announcement not posted (explicit mode never guesses)`);
+        }
+      } else {
+        const locus = this.turnLocusPins.get(agentName) ?? null;
+        this.channelRegistry.routeSpeech(agentName, text, locus).catch((err) => {
+          console.error('[sleep] announce failed:', err instanceof Error ? err.message : err);
+        });
+      }
     }
 
     console.error(`[sleep] agent=${agentName} seconds=${seconds} announce=${announce} until=${new Date(until).toISOString()}`);