@animalabs/agent-framework 0.6.10 → 0.7.0

package/dist/src/framework.js

@@ -57,6 +57,119 @@ function sniffImageMediaType(data) {
 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';
@@ -209,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
@@ -988,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) {
@@ -1064,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.
@@ -1097,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.
@@ -2691,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);
@@ -2890,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.
@@ -2900,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,
@@ -2909,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,
                 });
             }
         }
@@ -2990,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),
             });
         }
     }
@@ -3145,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,
@@ -3153,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') &&
@@ -3207,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),
                 });
             }
         }
@@ -3230,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;
     }
@@ -3312,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) {
@@ -3334,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;
@@ -3428,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
@@ -3475,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) {
@@ -3513,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': {
@@ -3523,6 +4063,7 @@ export class AgentFramework {
                             phase,
                             blockType: block.type,
                             blockIndex: index,
+                            channelId: typingChannel ?? undefined,
                         });
                         break;
                     }
@@ -3547,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);
@@ -3588,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) {
@@ -3867,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);
+                                    }
                                 }
                             }
                         }
@@ -3902,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'})`);
                             }
@@ -3930,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': {
@@ -4401,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;
@@ -4723,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 {};
     }
     /**
@@ -4777,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 () => {
@@ -4924,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).
@@ -5785,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
@@ -6014,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.