@animalabs/agent-framework 0.6.8 → 0.7.0

package/dist/src/framework.js

@@ -17,6 +17,26 @@ import { ConversationRouter } from './mcpl/conversation-router.js';
 import { safeSlice } from './safe-slice.js';
 import { toolResultDataToHistoryString } from './tool-result-history.js';
 import { splitProseSegments } from './prose-segments.js';
+/** Detect a supported image media type from magic bytes (the model API
+ *  rejects mislabeled media types, so trust bytes over extensions).
+ *  Returns undefined for non-image content. */
+function sniffImageMediaType(data) {
+    if (data.length >= 4 && data[0] === 0x89 && data[1] === 0x50 && data[2] === 0x4e && data[3] === 0x47) {
+        return 'image/png';
+    }
+    if (data.length >= 3 && data[0] === 0xff && data[1] === 0xd8 && data[2] === 0xff) {
+        return 'image/jpeg';
+    }
+    if (data.length >= 3 && data[0] === 0x47 && data[1] === 0x49 && data[2] === 0x46) {
+        return 'image/gif';
+    }
+    if (data.length >= 12 &&
+        data[0] === 0x52 && data[1] === 0x49 && data[2] === 0x46 && data[3] === 0x46 &&
+        data[8] === 0x57 && data[9] === 0x45 && data[10] === 0x42 && data[11] === 0x50) {
+        return 'image/webp';
+    }
+    return undefined;
+}
 /**
  * Tools whose presence suppresses auto-routing of the surrounding prose,
  * for two distinct reasons:
@@ -37,6 +57,119 @@ import { splitProseSegments } from './prose-segments.js';
 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) => {
+    if (!metadata)
+        return true;
+    const m = metadata;
+    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) {
+    const text = content?.find((c) => c.type === 'text' && c.text)?.text;
+    if (!text)
+        return undefined;
+    try {
+        const parsed = JSON.parse(text);
+        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, _metadata) => Array.isArray(tags) && tags.includes('chat:addressed');
+/**
+ * Parse a prose segment's routing prefix (explicit prose routing —
+ * docs/explicit-prose-routing.md). The FIRST line may be:
+ *   `>>target [!] [body…]`   — target = channel spec or `private`
+ * The ` !` continuation modifier must immediately follow the target,
+ * whitespace-separated. Body may start on the same line or the next.
+ */
+function parseProsePrefix(text) {
+    const m = /^>>(\S+)([ \t]+!)?[ \t]*\n?/.exec(text);
+    if (!m)
+        return { kind: 'none', continueTurn: false, body: text };
+    const target = m[1];
+    const continueTurn = m[2] !== undefined;
+    const body = text.slice(m[0].length);
+    // `skip_reply` mirrors the tool the model already knows: text stays in
+    // context, nothing is delivered. (Deliberately NOT called "private"/"note" —
+    // that vocabulary sat adjacent to signed thinking in a live window and drew
+    // a reasoning_extraction classifier hit, 2026-07-24 Fable.)
+    if (target === 'skip_reply') {
+        return { kind: 'private', continueTurn, body };
+    }
+    return { kind: 'target', target, continueTurn, body };
+}
+/** One-time primer appended when an agent's proseRouting mode changes. */
+function proseModePrimer(mode) {
+    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 = {
+    name: 'prose_help',
+    description: 'Show the plain-text output routing syntax (destination prefixes, resend token, skip).',
+    inputSchema: { type: 'object', properties: {} },
+};
 /** Strip the `server--` MCPL prefix from a tool name. */
 const bareToolName = (n) => n.split('--').pop();
 import { CheckpointManager } from './mcpl/checkpoint-manager.js';
@@ -189,20 +322,37 @@ export class AgentFramework {
     processLoggingPersist;
     processLoggingBroadcast;
     activeStreams = 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. */
     turnLocusPins = 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. */
-    midTurnRoutingResets = 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. */
+    midTurnInputSignals = 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. */
+    lastAnnouncedLocus = new Map();
+    // ---- Explicit prose routing (docs/explicit-prose-routing.md) ----------
+    /** Latest bounced (undelivered) prose per agent — the `{{unsent}}` source. */
+    proseClipboards = new Map();
+    /** Sticky per-TURN delivery target set by the turn's first `>>` prefix.
+     *  Cleared at every non-restart turn start; survives context restarts. */
+    proseTargetPins = new Map();
+    /** Agents whose current turn requested `!` continuation — re-woken when the
+     *  turn completes instead of pausing until the next external event. */
+    proseContinuations = new Set();
+    /** Consecutive bounce-wakes per agent; capped so an agent that keeps
+     *  emitting unprefixed prose can't wake-loop (notices still append). */
+    proseBounceStreaks = new Map();
     pendingAssistantBlocks = new Map();
     /** Streams the FRAMEWORK cancelled for non-terminal reasons, keyed
      *  `${agentName}:${streamId}`: an endTurn tool result or a context-budget
@@ -851,7 +1001,9 @@ export class AgentFramework {
             ...channelTools,
             ...gateTools,
             this.buildAgentSettingsTool(),
-            ...(this.getWorkspaceModule() ? [AgentFramework.SAVE_IMAGE_TOOL] : []),
+            ...(this.getWorkspaceModule()
+                ? [AgentFramework.SAVE_IMAGE_TOOL, AgentFramework.READ_IMAGE_TOOL]
+                : []),
         ];
     }
     /** The registered workspace module, if any (used by save_image). */
@@ -966,20 +1118,48 @@ export class AgentFramework {
             throw new Error(`Unknown agent: ${agentName}`);
         return agent.getRuntimeSettings();
     }
-    updateAgentRuntimeSettings(agentName, patch) {
+    /**
+     * 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, patch, opts) {
         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, keys) {
+    resetAgentRuntimeSettings(agentName, keys, opts) {
         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;
     }
     cancelAgentRuntimeSettingsTransition(agentName) {
@@ -1042,10 +1222,14 @@ export class AgentFramework {
             throw new Error(`Agent not found: ${agentName}`);
         }
         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.
         // NOT transparent — see the doc comment above.
@@ -1075,7 +1259,31 @@ export class AgentFramework {
                 console.error('beforeInference hook error (preview):', error);
             }
         }
-        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, budgetTokens, overrides) {
+        const agent = this.agents.get(agentName);
+        if (!agent)
+            throw new Error(`Unknown agent: ${agentName}`);
+        const cm = agent.getContextManager();
+        if (typeof cm.previewContext !== 'function')
+            return null;
+        // reserveForResponse mirrors the live compile so the previewed middle is
+        // comparable to what the agent actually gets.
+        return cm.previewContext({ maxTokens: budgetTokens, reserveForResponse: agent.maxTokens }, overrides);
     }
     /**
      * Check if process logging is enabled.
@@ -1533,6 +1741,27 @@ export class AgentFramework {
             required: ['path'],
         },
     };
+    /** Synthesized read_image tool — present when a workspace module is
+     *  registered. Returns the image as a native image block in the tool
+     *  result, so the agent SEES it in the live turn (history keeps a compact
+     *  placeholder via the standard tool-result serializer). */
+    static READ_IMAGE_TOOL = {
+        name: 'read_image',
+        description: 'View an image file from a workspace mount. The image is returned into ' +
+            'your context so you can actually see it (e.g. after save_recent_image, ' +
+            'or for images placed in the workspace by other means). Path is ' +
+            'mount-prefixed, e.g. "project/photos/cat.png". Supports png/jpeg/gif/webp.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                path: {
+                    type: 'string',
+                    description: 'Mount-prefixed image path, e.g. "project/photos/name.png".',
+                },
+            },
+            required: ['path'],
+        },
+    };
     static AGENT_SETTINGS_TOOL = {
         name: 'agent_settings',
         description: 'Read or change your hot runtime settings. This intentionally exposes only ' +
@@ -2648,20 +2877,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((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
                     const shouldEndTurn = currentState.toolResults.some(tc => tc.result.endTurn);
@@ -2847,6 +3073,8 @@ export class AgentFramework {
         };
         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
         // to the primary conversation.
@@ -2857,6 +3085,7 @@ export class AgentFramework {
         const id = this.addMessage('user', event.content, metadata);
         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,
@@ -2866,6 +3095,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,
                 });
             }
         }
@@ -2947,6 +3179,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),
             });
         }
     }
@@ -3102,7 +3335,7 @@ export class AgentFramework {
     handleMcplPushEvent(event) {
         const triggerChannel = this.derivePushEventChannel(event.origin);
         if (triggerChannel && this.channelRegistry) {
-            this.channelRegistry.ensureChannelRegistered(event.serverId, triggerChannel.channelId, triggerChannel.label);
+            this.channelRegistry.ensureChannelRegistered(event.serverId, triggerChannel.channelId, triggerChannel.label, triggerChannel.metadata);
         }
         const metadata = {
             ...event.origin,
@@ -3110,7 +3343,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 &&
             event.tags?.includes('chat:addressed') &&
@@ -3122,17 +3365,29 @@ export class AgentFramework {
                 ? event.origin.messageId
                 : event.eventId;
             const maxBackscroll = descriptor?.capabilities?.history?.maxMessages ?? 0;
+            // Resolve human-readable names from the event origin wherever the
+            // surface provided them — a mind reading this should see WHO addressed
+            // it WHERE, not a wall of snowflake ids. Raw ids remain only inside the
+            // tool-argument instructions, where they are the literal values to pass.
+            const origin = (event.origin ?? {});
+            const authorName = typeof origin.authorName === 'string' && origin.authorName ? origin.authorName : 'Someone';
+            const channelLabel = triggerChannel.label ? `#${triggerChannel.label}` : `"${triggerChannel.channelId}"`;
+            const place = typeof origin.guildName === 'string' && origin.guildName
+                ? `${channelLabel} in "${origin.guildName}"`
+                : channelLabel;
             content.push({
                 type: 'text',
-                text: `\n[Channel invitation] You were addressed in closed channel ` +
-                    `"${triggerChannel.label ?? triggerChannel.channelId}" (${triggerChannel.channelId}, server ${event.serverId}). ` +
-                    `You received this one message without subscribing. ` +
+                text: `\n[Channel invitation] ${authorName} addressed you in ${place} — ` +
+                    `a channel you haven't joined. You're seeing this one message; you won't receive more from it unless you join. ` +
+                    `Your options:\n` +
+                    `1. Reply without joining — simply write your reply as normal text this turn; it will be delivered to ${channelLabel}.\n` +
+                    `2. Join the channel — call channel_open with channelId "${triggerChannel.channelId}" and serverId "${event.serverId}"` +
                     (maxBackscroll > 0
-                        ? `To subscribe, call channel_open with channelId, serverId "${event.serverId}", backscroll (0-${maxBackscroll}), and beforeMessageId "${messageId}". `
-                        : `To subscribe, call channel_open with this channelId and serverId "${event.serverId}". `) +
-                    `You may reply once without subscribing. To remain closed, call channel_decline ` +
-                    `with channelId, serverId "${event.serverId}", and messageId "${messageId}"; ` +
-                    `optionally set acknowledge to a surface value such as 👀.`,
+                        ? `; to also read recent history, add backscroll (a number up to ${maxBackscroll}) and beforeMessageId "${messageId}".\n`
+                        : `.\n`) +
+                    `3. Stay out — call channel_decline with channelId "${triggerChannel.channelId}", serverId "${event.serverId}", ` +
+                    `and messageId "${messageId}" (optionally set acknowledge to an emoji like 👀 so ${authorName} isn't left hanging).\n` +
+                    `Doing nothing is also fine.`,
             });
             metadata.channelInvitation = true;
             metadata.channelOpen = false;
@@ -3152,6 +3407,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),
                 });
             }
         }
@@ -3175,16 +3434,35 @@ export class AgentFramework {
     derivePushEventChannel(origin) {
         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;
+        // 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`
         // is null for a DM (→ 'dm'); a real guild id for a non-open guild channel.
         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;
     }
@@ -3257,14 +3535,287 @@ 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((acc, r) => r.channelId ?? acc, undefined);
-            await this.startAgentStream(agent, { ...trigger, channelId: triggerChannel });
+            // (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;
+            let addressedChannel;
+            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).
+     */
+    announceLocusIfChanged(agentName, locus) {
+        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;
+        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.
+     */
+    recordChannelAutoOpenNotice(agentName, channels, cause) {
+        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).
+     */
+    async deliverProse(agent, rawText) {
+        // 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 = [];
+        let current = [];
+        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+(?=>>)/, ''));
+        }
+    }
+    async deliverProseEnvelope(agent, rawText) {
+        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;
+        let body;
+        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). */
+    static PROSE_BOUNCE_WAKE_CAP = 2;
+    bounceProse(agent, text, reason, candidates) {
+        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.
+     */
+    maybePrimeProseMode(agent) {
+        const mode = agent.proseRouting;
+        try {
+            const data = this.store.getStateJson(FRAMEWORK_STATE_ID);
+            const state = (data && typeof data === 'object' ? data : {});
+            const primed = { ...(state.proseRoutingPrimed ?? {}) };
+            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' });
+            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);
         }
     }
     async startAgentStream(agent, trigger, attempt = 0) {
@@ -3279,20 +3830,74 @@ 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);
+        // 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);
+            }
         }
-        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() });
         try {
             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.
             let injections;
@@ -3373,25 +3978,14 @@ export class AgentFramework {
         const myStreamId = agent.streamId;
         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 = () => {
-            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 = () => 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
         // here would stall consumption of the next round's events by
@@ -3420,32 +4014,29 @@ export class AgentFramework {
         // historical whole-turn routing so fallback-mode prose is still
         // 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);
         const adoptInjectedRound = () => {
-            if (!this.midTurnRoutingResets.has(agent.name))
+            if (!this.midTurnInputSignals.has(agent.name))
                 return;
-            const nextLocus = this.midTurnRoutingResets.get(agent.name) ?? null;
-            this.midTurnRoutingResets.delete(agent.name);
-            // A new human/agent message, not merely a tool result, means any earlier
-            // explicit delivery has completed its conversational job.
+            this.midTurnInputSignals.delete(agent.name);
+            // 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 {
             for await (const event of stream) {
@@ -3458,6 +4049,10 @@ 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,
                         });
                         break;
                     case 'block': {
@@ -3468,6 +4063,7 @@ export class AgentFramework {
                             phase,
                             blockType: block.type,
                             blockIndex: index,
+                            channelId: typingChannel ?? undefined,
                         });
                         break;
                     }
@@ -3492,13 +4088,30 @@ export class AgentFramework {
                             assistantBlocks = roundContent.filter((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 });
+                                assistantBlocks.push({
+                                    type: 'tool_use',
+                                    id: c.id,
+                                    name: c.name,
+                                    input: c.input,
+                                    ...(rawXml ? { rawXml } : {}),
+                                });
                             }
                         }
                         this.pendingAssistantBlocks.set(agent.name, assistantBlocks);
@@ -3533,7 +4146,20 @@ 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)`);
                                     }
                                     else if (hasSameRoundPrivateThink) {
@@ -3812,11 +4438,30 @@ export class AgentFramework {
                                 .join('\n')
                                 .trim();
                             if (speechText) {
-                                try {
-                                    await this.channelRegistry.routeSpeech(agent.name, speechText);
+                                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);
+                                    }
                                 }
-                                catch (err) {
-                                    console.error('speech routing 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);
+                                    }
                                 }
                             }
                         }
@@ -3847,7 +4492,20 @@ export class AgentFramework {
                             // land before the trailing prose. Awaited even when silenced —
                             // 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'})`);
                             }
@@ -3875,6 +4533,20 @@ export class AgentFramework {
                         // NOTE: agent.reset() + onInferenceEnded() already ran above,
                         // 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;
                     }
                     case 'error': {
@@ -4314,6 +4986,10 @@ export class AgentFramework {
             this.dispatchSaveImageToolCall(agentName, enrichedCall);
             return;
         }
+        if (enrichedCall.name === 'read_image') {
+            this.dispatchReadImageToolCall(agentName, enrichedCall);
+            return;
+        }
         // Route gate_status tool
         if (enrichedCall.name === 'gate_status' && this.eventGate) {
             this.dispatchGateToolCall(agentName, enrichedCall);
@@ -4342,6 +5018,20 @@ export class AgentFramework {
             this.dispatchChannelToolCall(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;
@@ -4664,6 +5354,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 {};
     }
     /**
@@ -4718,7 +5415,19 @@ 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 () => {
@@ -4865,15 +5574,35 @@ 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 });
                 }
                 catch (err) {
                     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);
+            },
         });
         // Host capabilities advertised during the MCP handshake — stored so
         // servers can also be connected later at runtime (connectMcplServer).
@@ -5726,6 +6455,33 @@ export class AgentFramework {
                     this.checkpointManager.recordCheckpoint(serverId, fs, result.state);
                 }
             }
+            // 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 : 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
@@ -5816,6 +6572,19 @@ export class AgentFramework {
             .then((result) => {
             const durationMs = Date.now() - startTime;
             this.emitTrace({ type: 'tool:completed', module: 'channels', tool: call.name, callId: call.id, durationMs });
+            // A successful channel_open plants the agent's feet in the opened
+            // channel: pin it as this turn's reply locus so plain-text speech
+            // written right after opening routes THERE. Found live 2026-07-21
+            // (Aria bring-up): open → plain-text reply → "no locus (no
+            // home/active channel, defaultPublishChannel null)" on a turn with
+            // no channel trigger (post-restart continuation). Next turn start
+            // re-resolves the locus as usual (startAgentStream set/delete).
+            if (call.name === 'channel_open' && result?.success) {
+                const opened = result.data?.channelId
+                    ?? call.input?.channelId;
+                if (opened)
+                    this.activeTriggerChannels.set(agentName, opened);
+            }
             this.pushEvent({
                 type: 'tool-result',
                 callId: call.id,
@@ -5942,12 +6711,31 @@ export class AgentFramework {
         const human = seconds >= 3600 ? `${(seconds / 3600).toFixed(1)}h`
             : 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()}`);
         // endTurn: the agent stops here and goes idle for the duration.
@@ -5962,6 +6750,72 @@ export class AgentFramework {
             endTurn: true,
         });
     }
+    /**
+     * Handle the synthesized `read_image` tool: read image bytes from a
+     * workspace mount and return them as a native MCP-shaped content array
+     * (`[{type:'text'…},{type:'image', data, mimeType}]`). The live-turn
+     * converter (tryNativeToolResultContent → membrane tool_result image
+     * blocks) delivers the actual image to the model; history storage keeps
+     * the standard compact `[image: …]` placeholder.
+     */
+    dispatchReadImageToolCall(agentName, call) {
+        this.emitTrace({ type: 'tool:started', module: 'workspace', tool: call.name, callId: call.id, input: call.input });
+        const finish = (result) => {
+            this.emitTrace({
+                type: result.isError ? 'tool:failed' : 'tool:completed',
+                module: 'workspace',
+                tool: call.name,
+                callId: call.id,
+                durationMs: 0,
+                ...(result.isError ? { error: result.error } : {}),
+            });
+            this.pushEvent({ type: 'tool-result', callId: call.id, agentName, moduleName: 'workspace', result });
+        };
+        void (async () => {
+            try {
+                const workspace = this.getWorkspaceModule();
+                if (!workspace || typeof workspace.readBinary !== 'function') {
+                    throw new Error('read_image requires a workspace module');
+                }
+                const input = (call.input ?? {});
+                if (typeof input.path !== 'string' || input.path.length === 0) {
+                    throw new Error('read_image: `path` (mount-prefixed) is required');
+                }
+                const read = await workspace.readBinary(input.path);
+                if ('error' in read)
+                    throw new Error(read.error);
+                const mediaType = sniffImageMediaType(read.data);
+                if (!mediaType) {
+                    throw new Error(`read_image: "${input.path}" does not look like a supported image ` +
+                        '(png/jpeg/gif/webp — checked by magic bytes, not extension)');
+                }
+                // Anthropic rejects images >5MB (and >8000px); guard the hard byte
+                // limit here — resizing is out of scope without an image library.
+                const MAX_IMAGE_BYTES = 5 * 1024 * 1024;
+                if (read.data.byteLength > MAX_IMAGE_BYTES) {
+                    throw new Error(`read_image: "${input.path}" is ${read.data.byteLength} bytes — ` +
+                        `over the ${MAX_IMAGE_BYTES}-byte model limit`);
+                }
+                finish({
+                    success: true,
+                    data: [
+                        {
+                            type: 'text',
+                            text: `${input.path} (${mediaType}, ${Math.ceil(read.data.byteLength / 1024)} KB):`,
+                        },
+                        { type: 'image', data: read.data.toString('base64'), mimeType: mediaType },
+                    ],
+                });
+            }
+            catch (error) {
+                finish({
+                    success: false,
+                    error: error instanceof Error ? error.message : String(error),
+                    isError: true,
+                });
+            }
+        })();
+    }
     /**
      * Handle the synthesized `save_recent_image` tool: locate the requested
      * image blocks in the calling agent's context (blobs re-inlined, counted