@animalabs/agent-framework 0.6.8 → 0.7.0

package/src/framework.ts

@@ -10,6 +10,7 @@ import type {
   MessageQuery,
   MessageQueryResult,
   StoredMessage,
+  TokenBudget,
 } from '@animalabs/context-manager';
 import type {
   FrameworkConfig,
@@ -66,6 +67,29 @@ import type { WorkspaceModule } from './modules/workspace/index.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: Buffer): string | undefined {
+  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:
@@ -86,6 +110,134 @@ 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?: MessageMetadata): boolean => {
+  if (!metadata) return true;
+  const m = metadata as Record<string, unknown>;
+  if (m.system === true) return false;
+  if (Array.isArray(m.tags) && m.tags.includes('chat:reaction')) return false;
+  return true;
+};
+
+/**
+ * Explicit delivery tools whose successful use into a closed channel OPENS
+ * it (send implies engagement — see openIfClosedForSend). Bare tool names,
+ * matched after stripping the MCPL server prefix.
+ */
+const SEND_ENGAGEMENT_TOOLS = new Set([
+  'send_message', 'reply_message', 'send_dm', 'send_file', 'send_files',
+]);
+
+/**
+ * Best-effort extraction of the delivered channel id from an MCPL send-tool
+ * result (the discord-mcpl send tools return JSON like
+ * `{"messageId":"…","channelId":"…"}` as a text block). Returns undefined on
+ * any shape mismatch — the caller falls back to the tool's input args.
+ */
+function extractChannelIdFromToolResult(
+  content: Array<{ type: string; text?: string }> | undefined,
+): string | undefined {
+  const text = content?.find((c) => c.type === 'text' && c.text)?.text;
+  if (!text) return undefined;
+  try {
+    const parsed = JSON.parse(text) as { channelId?: unknown };
+    return typeof parsed.channelId === 'string' && parsed.channelId.length > 0
+      ? parsed.channelId
+      : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * True when an incoming channel message explicitly addressed the agent.
+ * Primary signal is the MCPL RFC-001 `chat:addressed` tag (mention / reply /
+ * DM, as classified by the server); the metadata booleans are the fallback
+ * for servers that predate tags. Addressed messages outrank ambient chatter
+ * when picking a turn's frozen speech locus.
+ */
+const isAddressedMessage = (
+  tags?: string[],
+  _metadata?: Record<string, unknown>,
+): boolean => Array.isArray(tags) && tags.includes('chat:addressed');
+
+/**
+ * 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: string): {
+  kind: 'target' | 'private' | 'none';
+  target?: string;
+  continueTurn: boolean;
+  body: string;
+} {
+  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: 'explicit' | 'locus'): string {
+  if (mode === 'locus') {
+    return '[prose-routing] Mode change: your plain text auto-routes to the ' +
+      'conversational locus again. `>>` destination prefixes are no longer needed.';
+  }
+  // Deliberately terse: a short event-style notice is classifier-safe from
+  // the user role (ablation D, 2026-07-24), while the full grammar as a user
+  // message drew a deterministic reasoning_extraction refusal (ablation A/B).
+  // The grammar is TAUGHT BY BOUNCE: the first undelivered text produces a
+  // notice with the exact resend syntax, and the full reference is available
+  // on demand via the prose_help tool (a tool RESULT is model-requested
+  // content — the safest role there is). Nothing is injected into the system
+  // prompt: those bytes belong to the recipe, and the deepest KV prefix must
+  // not vary with framework code.
+  return (
+    '[prose-routing] Output mode changed: plain text is delivered only with a ' +
+    'destination prefix line, e.g. ">>#channel-name your text". ' +
+    'The prose_help tool shows the full syntax.'
+  );
+}
+
+/** Full `>>` routing reference, served as the prose_help TOOL RESULT (never
+ *  injected ambiently — see proseModePrimer note). */
+const PROSE_ROUTING_HELP =
+  'Plain-text output routing (explicit mode):\n' +
+  '  >>#channel-name …    or    >>@person …  (DM)    or    >>service:guild:id …\n' +
+  '  One message may hold several sections: each line starting with ">>" begins\n' +
+  '  a new envelope, routed to its own destination independently.\n' +
+  '  The first destination in a turn applies to the rest of that turn.\n' +
+  '  Append " !" after the destination (e.g. ">>#ops !") to start your next turn\n' +
+  '  immediately when this one ends, instead of pausing until the next event.\n' +
+  '  >>skip_reply — text stays in your context only, like the skip_reply tool.\n' +
+  'Text without a destination is not delivered: it is retained, and a notice will\n' +
+  'prompt you to resend — reply e.g. ">>#channel {{unsent}}" to deliver the retained\n' +
+  'text unchanged. Send tools (send_message, send_dm, …) are unaffected.';
+
+const PROSE_HELP_TOOL: import('./types/index.js').ToolDefinition = {
+  name: 'prose_help',
+  description: 'Show the plain-text output routing syntax (destination prefixes, resend token, skip).',
+  inputSchema: { type: 'object' as const, properties: {} },
+};
 /** Strip the `server--` MCPL prefix from a tool name. */
 const bareToolName = (n: string): string => n.split('--').pop()!;
 import { CheckpointManager } from './mcpl/checkpoint-manager.js';
@@ -368,20 +520,38 @@ export class AgentFramework {
   private processLoggingBroadcast: boolean;
   private activeStreams: Map<string, Promise<void>> = new Map();
 
-  /** Per-agent output locus pinned for the CURRENT logical turn (see
-   *  resolveTurnLocus in driveStream). Lives here — not in driveStream
-   *  locals — so the pin survives a context-budget stream restart, which
-   *  continues the same logical turn in a fresh driveStream. A mid-turn
-   *  injected channel message replaces the pin for the next conversational
-   *  round; otherwise it remains stable. Cleared at the start of every
-   *  non-restart turn. */
+  /** Per-agent output locus FROZEN for the CURRENT logical turn. Resolved
+   *  eagerly in startAgentStream (home → addressed trigger → global default)
+   *  and never moved until the next turn: mid-turn injected messages — ambient
+   *  chatter, reactions, system markers — must not hijack where the agent's
+   *  plain prose lands (2026-07-21 Cairn lounge misroute). Lives here — not in
+   *  driveStream locals — so the pin survives a context-budget stream restart,
+   *  which continues the same logical turn in a fresh driveStream. Cleared or
+   *  re-set at the start of every non-restart turn. */
   private turnLocusPins: Map<string, string> = new Map();
-  /** A tool boundary injected fresh external input into the live stream.
-   *  Presence (including a null value) tells driveStream to clear sticky
-   *  explicit-send suppression before handling the next model round. A
-   *  string also moves that round's reply locus to the newest injected
-   *  channel. */
-  private midTurnRoutingResets: Map<string, string | null> = new Map();
+  /** A tool boundary injected fresh CONVERSATIONAL input (a real message —
+   *  not a reaction or a system marker) into the live stream. Tells
+   *  driveStream to clear sticky explicit-send suppression before handling
+   *  the next model round. Never affects routing: the turn locus is frozen. */
+  private midTurnInputSignals: Set<string> = new Set();
+  /** Last outbound locus announced to each agent as a durable `[routing]`
+   *  window message. Announce-on-change only: steady state emits nothing
+   *  (KV-safe, no per-turn chatter). In-memory — after a process restart the
+   *  first turn's locus is announced once to re-establish the baseline. */
+  private lastAnnouncedLocus: Map<string, string | null> = new Map();
+
+  // ---- Explicit prose routing (docs/explicit-prose-routing.md) ----------
+  /** Latest bounced (undelivered) prose per agent — the `{{unsent}}` source. */
+  private proseClipboards: Map<string, string> = new Map();
+  /** Sticky per-TURN delivery target set by the turn's first `>>` prefix.
+   *  Cleared at every non-restart turn start; survives context restarts. */
+  private proseTargetPins: Map<string, string> = new Map();
+  /** Agents whose current turn requested `!` continuation — re-woken when the
+   *  turn completes instead of pausing until the next external event. */
+  private proseContinuations: Set<string> = new Set();
+  /** Consecutive bounce-wakes per agent; capped so an agent that keeps
+   *  emitting unprefixed prose can't wake-loop (notices still append). */
+  private proseBounceStreaks: Map<string, number> = new Map();
   private pendingAssistantBlocks: Map<string, ContentBlock[]> = new Map();
   /** Streams the FRAMEWORK cancelled for non-terminal reasons, keyed
    *  `${agentName}:${streamId}`: an endTurn tool result or a context-budget
@@ -1134,7 +1304,9 @@ export class AgentFramework {
       ...channelTools,
       ...gateTools,
       this.buildAgentSettingsTool(),
-      ...(this.getWorkspaceModule() ? [AgentFramework.SAVE_IMAGE_TOOL] : []),
+      ...(this.getWorkspaceModule()
+        ? [AgentFramework.SAVE_IMAGE_TOOL, AgentFramework.READ_IMAGE_TOOL]
+        : []),
     ];
   }
 
@@ -1271,25 +1443,55 @@ export class AgentFramework {
     return agent.getRuntimeSettings();
   }
 
+  /**
+   * Apply runtime settings.
+   *
+   * `opts.persist: false` makes the change EPHEMERAL: it takes effect live but
+   * is not written to the `framework/state` slot, so a restart reverts it. That
+   * is the mode for operator experiments ("change it, watch, revert") — the
+   * default persists, because a durable operational change should survive a
+   * bounce like every other override.
+   *
+   * Nothing here notifies the agent. Discovery is deliberately PULL: the agent
+   * can read current settings any time via the `agent_settings` tool's `get`
+   * action, which costs no context perturbation. Pushing a notice injects text
+   * into the very context being tuned — it invalidates the KV prefix and can
+   * itself trip a classifier — so callers opt into that explicitly rather than
+   * getting it by default.
+   *
+   * KNOWN LIMITATION of `persist: false`: the change still lands in the agent's
+   * in-memory override map, and `persistAgentRuntimeSettings` writes that whole
+   * map. So a LATER persisting call promotes any still-live ephemeral change to
+   * durable as a side effect. Ephemeral means "not written by THIS call", not
+   * "can never be written". Reset the ephemeral key before persisting something
+   * else if that matters. Making it airtight needs per-key ephemeral tracking
+   * inside Agent.
+   */
   updateAgentRuntimeSettings(
     agentName: string,
     patch: AgentRuntimeSettingsPatch,
+    opts?: { persist?: boolean },
   ): AgentRuntimeSettingsSnapshot {
     const agent = this.agents.get(agentName);
     if (!agent) throw new Error(`Unknown agent: ${agentName}`);
     const result = agent.updateRuntimeSettings(patch);
-    this.persistAgentRuntimeSettings(agentName, agent.getRuntimeSettingsOverrides());
+    if (opts?.persist !== false) {
+      this.persistAgentRuntimeSettings(agentName, agent.getRuntimeSettingsOverrides());
+    }
     return result;
   }
 
   resetAgentRuntimeSettings(
     agentName: string,
     keys?: Array<keyof AgentRuntimeSettingsPatch>,
+    opts?: { persist?: boolean },
   ): AgentRuntimeSettingsSnapshot {
     const agent = this.agents.get(agentName);
     if (!agent) throw new Error(`Unknown agent: ${agentName}`);
     const result = agent.resetRuntimeSettings(keys);
-    this.persistAgentRuntimeSettings(agentName, agent.getRuntimeSettingsOverrides());
+    if (opts?.persist !== false) {
+      this.persistAgentRuntimeSettings(agentName, agent.getRuntimeSettingsOverrides());
+    }
     return result;
   }
 
@@ -1350,7 +1552,7 @@ export class AgentFramework {
    */
   async previewActivation(
     agentName: string,
-    opts?: { injections?: boolean }
+    opts?: { injections?: boolean; budget?: TokenBudget }
   ): Promise<NormalizedRequest> {
     const agent = this.agents.get(agentName);
     if (!agent) {
@@ -1359,10 +1561,14 @@ export class AgentFramework {
 
     const tools = this.getToolsForAgent(agentName).filter((t) => agent.canUseTool(t.name));
 
+    // An explicit budget compiles against a HYPOTHETICAL window instead of the
+    // agent's live one. That also suppresses transition-settling in
+    // compileWithInjections (which only settles when no budget is passed), so
+    // previewing a smaller window cannot advance a converging descent.
     // Default: no dynamic injection gathering → fully transparent (no
     // inference, no Chronicle writes, no external RPC). Opt in explicitly.
     if (!opts?.injections) {
-      return agent.buildActivationRequest(tools, undefined);
+      return agent.buildActivationRequest(tools, undefined, opts?.budget);
     }
 
     // Full-fidelity path: mirrors startAgentStream's injection gathering.
@@ -1397,7 +1603,42 @@ export class AgentFramework {
       }
     }
 
-    return agent.buildActivationRequest(tools, injections);
+    return agent.buildActivationRequest(tools, injections, opts?.budget);
+  }
+
+  /**
+   * Non-committing preview of the FOLD PLAN at a hypothetical budget and/or
+   * context settings — the numbers behind an operator's "what happens if I set
+   * the budget to X" before they apply it.
+   *
+   * Unlike `previewActivation` (which renders a request), this returns the
+   * picker's plan: resulting tokens, whether it fits, how many summaries would
+   * have to be produced first, and the per-chunk fold levels. Commits nothing:
+   * no resolution persistence, no compression enqueue, no transition
+   * bookkeeping — see `AutobiographicalStrategy.previewContext`.
+   *
+   * Returns null when the agent's strategy has no fold plan (non-adaptive).
+   */
+  previewContextSettings(
+    agentName: string,
+    budgetTokens: number,
+    overrides?: Record<string, unknown>,
+  ): unknown {
+    const agent = this.agents.get(agentName);
+    if (!agent) throw new Error(`Unknown agent: ${agentName}`);
+    const cm = agent.getContextManager() as unknown as {
+      previewContext?: (
+        budget: TokenBudget,
+        overrides?: Record<string, unknown>,
+      ) => unknown;
+    };
+    if (typeof cm.previewContext !== 'function') return null;
+    // reserveForResponse mirrors the live compile so the previewed middle is
+    // comparable to what the agent actually gets.
+    return cm.previewContext(
+      { maxTokens: budgetTokens, reserveForResponse: agent.maxTokens },
+      overrides,
+    );
   }
 
   /**
@@ -1915,6 +2156,29 @@ export class AgentFramework {
     },
   };
 
+  /** 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). */
+  private static readonly READ_IMAGE_TOOL: import('./types/index.js').ToolDefinition = {
+    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'],
+    },
+  };
+
   private static readonly AGENT_SETTINGS_TOOL: import('./types/index.js').ToolDefinition = {
     name: 'agent_settings',
     description:
@@ -3209,23 +3473,17 @@ export class AgentFramework {
             }
           }
 
-          // A newly injected message begins a new conversational round inside
-          // the same provider inference. Remember that boundary for
-          // driveStream: an explicit send in the preceding round must not
-          // silence the reply, and the newest channel-bearing injection is
-          // now the reply locus. Map presence matters even without a channel
-          // (CLI/module input): it still clears the prior send suppression.
-          if (midTurnInjections.length > 0) {
-            const injectedChannelId = midTurnInjections.reduce<string | null>(
-              (latest, injection) => {
-                const candidate = injection.metadata?.channelId;
-                return typeof candidate === 'string' && candidate.length > 0
-                  ? candidate
-                  : latest;
-              },
-              null,
-            );
-            this.midTurnRoutingResets.set(agent.name, injectedChannelId);
+          // A newly injected CONVERSATIONAL message begins a new
+          // conversational round inside the same provider inference. Remember
+          // that boundary for driveStream: an explicit send in the preceding
+          // round must not silence the reply. Routing is deliberately NOT
+          // affected — the turn locus is frozen at turn start, so ambient
+          // chatter, reactions, and system markers injected mid-turn can no
+          // longer hijack where the agent's prose lands. Non-conversational
+          // injections (reactions, `system: true` markers) don't even clear
+          // the send suppression: nothing new was said to the agent.
+          if (midTurnInjections.some((inj) => isConversationalInjection(inj.metadata))) {
+            this.midTurnInputSignals.add(agent.name);
           }
 
           // Check if any tool result requested endTurn
@@ -3445,6 +3703,7 @@ export class AgentFramework {
     content: ContentBlock[];
     timestamp: string;
     metadata?: Record<string, unknown>;
+    tags?: string[];
     triggerInference?: boolean;
   }): Promise<void> {
     const metadata: Record<string, unknown> = {
@@ -3456,6 +3715,7 @@ export class AgentFramework {
       serverId: event.serverId,
     };
     if (event.threadId) metadata.threadId = event.threadId;
+    if (event.tags) metadata.tags = event.tags;
 
     // Per-channel conversation routing: messages go to the channel's fork
     // agent (spawned from the template on first qualifying message), never
@@ -3469,6 +3729,7 @@ export class AgentFramework {
     this.emitTrace({ type: 'message:added', messageId: id, source: 'mcpl:channel-incoming' });
 
     if (event.triggerInference) {
+      const addressed = isAddressedMessage(event.tags, event.metadata);
       for (const agentName of this.agents.keys()) {
         this.pendingRequests.push({
           agentName,
@@ -3478,6 +3739,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,
         });
       }
     }
@@ -3497,6 +3761,7 @@ export class AgentFramework {
       author: { id: string; name: string };
       content: ContentBlock[];
       metadata?: Record<string, unknown>;
+      tags?: string[];
       triggerInference?: boolean;
     },
     messageMetadata: Record<string, unknown>,
@@ -3575,6 +3840,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),
       });
     }
   }
@@ -3752,6 +4018,7 @@ export class AgentFramework {
         event.serverId,
         triggerChannel.channelId,
         triggerChannel.label,
+        triggerChannel.metadata,
       );
     }
 
@@ -3761,7 +4028,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 &&
@@ -3774,18 +4051,30 @@ 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 ?? {}) as Record<string, unknown>;
+      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. ` +
+          `\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;
@@ -3807,6 +4096,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),
         });
       }
     }
@@ -3830,13 +4123,29 @@ export class AgentFramework {
    */
   private derivePushEventChannel(
     origin: Record<string, unknown> | undefined,
-  ): { channelId: string; label?: string } | undefined {
+  ): { channelId: string; label?: string; metadata?: Record<string, unknown> } | undefined {
     if (!origin) return undefined;
-    const label = typeof origin.channelName === 'string' ? origin.channelName : undefined;
+    let label = typeof origin.channelName === 'string' && origin.channelName ? origin.channelName : undefined;
+    let metadata: Record<string, unknown> | undefined;
+
+    // A DM has no channelName — label it by the PERSON and carry their
+    // identity, so DM registrations are people-first (`DM: antra`, matchable
+    // by `>>@name` / `<@id>` mention tokens) instead of bare snowflakes.
+    const isDM = origin.isDM === true || origin.guildId === null;
+    if (isDM && typeof origin.authorName === 'string' && origin.authorName) {
+      label = label ?? `DM: ${origin.authorName}`;
+      metadata = {
+        channelType: 'dm',
+        recipientName: origin.authorName,
+        ...(typeof origin.authorId === 'string' && origin.authorId
+          ? { recipientId: origin.authorId }
+          : {}),
+      };
+    }
 
     const explicit = origin.mcplChannelId;
     if (typeof explicit === 'string' && explicit) {
-      return { channelId: explicit, label };
+      return { channelId: explicit, ...(label ? { label } : {}), ...(metadata ? { metadata } : {}) };
     }
 
     // Discord fallback: reconstruct the composite from origin parts. `guildId`
@@ -3844,7 +4153,11 @@ export class AgentFramework {
     if (origin.source === 'discord' && typeof origin.channelId === 'string' && origin.channelId) {
       const guild =
         typeof origin.guildId === 'string' && origin.guildId ? origin.guildId : 'dm';
-      return { channelId: `discord:${guild}:${origin.channelId}`, label };
+      return {
+        channelId: `discord:${guild}:${origin.channelId}`,
+        ...(label ? { label } : {}),
+        ...(metadata ? { metadata } : {}),
+      };
     }
 
     return undefined;
@@ -3932,17 +4245,302 @@ export class AgentFramework {
       const trigger = requests[0];
       // Route this turn's auto-published speech to the channel that triggered
       // it (item-3 redux). A batched wake may carry several triggering channels
-      // (messages arrived in >1 channel while the agent was busy/idle) — reply
-      // in the MOST-RECENT one: it matches the legacy last-inbound semantics and
-      // is the message the agent is most likely answering. The common case is
-      // 1 message → 1 channel (unambiguous). Non-channel wakes carry no
-      // channelId, leaving the field undefined → global fallback. `reduce`
-      // keeps the last defined channelId across the (FIFO-ordered) batch.
-      const triggerChannel = requests.reduce<string | undefined>(
-        (acc, r) => r.channelId ?? acc,
-        undefined,
+      // (messages arrived in >1 channel while the agent was busy/idle):
+      //   1. the most recent ADDRESSED channel wins (mention / reply / DM —
+      //      someone explicitly spoke TO the agent);
+      //   2. else the most recent channel-bearing request (ambient message in
+      //      an open channel — legacy last-inbound semantics).
+      // Ambient chatter must not outrank an addressed message just by being
+      // newest (2026-07-21 Cairn lounge misroute, turn-start variant).
+      // Non-channel wakes (heartbeats, module events, reactions — which never
+      // carry channelId) leave both undefined → global fallback.
+      let ambientChannel: string | undefined;
+      let addressedChannel: string | undefined;
+      for (const r of requests) {
+        if (!r.channelId) continue;
+        ambientChannel = r.channelId;
+        if (r.addressed) addressedChannel = r.channelId;
+      }
+      const triggerChannel = addressedChannel ?? ambientChannel;
+      const triggerAddressed = addressedChannel !== undefined;
+      await this.startAgentStream(agent, {
+        ...trigger,
+        channelId: triggerChannel,
+        addressed: triggerAddressed,
+      });
+    }
+  }
+
+  /**
+   * Announce-on-change locus notice (turn-frozen routing). Appends a durable
+   * `[routing]` window message when the turn's effective outbound locus
+   * differs from the last one announced — the agent must never have to guess
+   * where its plain prose lands. Durable append (never retracted) keeps the
+   * KV prefix stable; change-only keeps it out of steady-state turns. The
+   * first resolution after boot announces only a non-null locus ("prose has
+   * no destination" is the unremarkable boot default). Never triggers
+   * inference; never locus-eligible itself (system + no channel metadata).
+   */
+  private announceLocusIfChanged(agentName: string, locus: string | null): void {
+    const hasBaseline = this.lastAnnouncedLocus.has(agentName);
+    const prev = this.lastAnnouncedLocus.get(agentName) ?? null;
+    if (hasBaseline ? prev === locus : locus === null) {
+      if (!hasBaseline) this.lastAnnouncedLocus.set(agentName, locus);
+      return;
+    }
+    this.lastAnnouncedLocus.set(agentName, locus);
+
+    const agent = this.agents.get(agentName);
+    if (!agent) return;
+
+    let text: string;
+    if (locus === null) {
+      text =
+        '[routing] Your plain speech currently has no channel — it stays in ' +
+        'your archive. Use an explicit send tool to reach a channel.';
+    } else {
+      const label = this.channelRegistry?.getDescriptor(locus)?.label;
+      const shown =
+        label && label !== locus
+          ? `${label.startsWith('#') ? label : `#${label}`} (${locus})`
+          : locus;
+      text =
+        `[routing] Your plain speech now lands in ${shown}. ` +
+        'Other channels need an explicit send tool.';
+    }
+
+    try {
+      const id = agent.getContextManager().addMessage(
+        'user',
+        [{ type: 'text', text }],
+        { system: true, kind: 'routing-notice' },
+      );
+      this.emitTrace({ type: 'message:added', messageId: id, source: 'routing-notice' });
+      console.error(
+        `[routing] ${agentName}: locus ${prev ?? '(none)'} -> ${locus ?? '(none)'} (announced in window)`,
+      );
+    } catch (err) {
+      console.error('announceLocusIfChanged: failed to record routing notice:', err);
+    }
+  }
+
+  /**
+   * Durable window notice for a channel the agent did not ask to open —
+   * subscription-policy admission, or an open forced by the agent's own
+   * delivery into a closed channel. The agent must always learn that new
+   * traffic will start flowing, and that `channel_close` opts out (their
+   * decision outranks policy). System message: never triggers inference,
+   * never conversational, never locus-eligible.
+   */
+  private recordChannelAutoOpenNotice(
+    agentName: string | undefined,
+    channels: Array<{ channelId: string; label?: string }>,
+    cause: 'subscription-policy' | 'opened-by-delivery' | 'opened-by-reply',
+  ): void {
+    if (channels.length === 0) return;
+    const shown = channels
+      .map((c) => (c.label && c.label !== c.channelId ? `${c.label} (${c.channelId})` : c.channelId))
+      .join(', ');
+    const plural = channels.length > 1;
+    const causeText =
+      cause === 'subscription-policy'
+        ? 'your subscription policy just admitted ' + (plural ? 'them' : 'it')
+        : 'your own message into the closed channel engaged it';
+    const text =
+      `[channels] Now open: ${shown} — ${causeText}. Ongoing traffic from ` +
+      (plural ? 'these channels' : 'this channel') +
+      ` will reach you. If you don't want ${plural ? 'one of them' : 'it'}, use channel_close — ` +
+      'your choice sticks; neither policy nor a later send will silently reopen it.';
+    try {
+      // Through framework.addMessage for mid-turn safety (deferral +
+      // hear-while-acting injection) — a delivery-forced open happens inside
+      // a live turn, and a direct context-manager append there would store
+      // the notice out of order. Targets the primary agent; connectome-host
+      // runs trunk-only, so this is the delivering agent in practice.
+      this.addMessage('user', [{ type: 'text', text }], { system: true, kind: 'channel-notice' });
+      console.error(`[channel] auto-open notice (${cause}) -> ${agentName ?? 'primary'}: ${shown}`);
+    } catch (err) {
+      console.error('recordChannelAutoOpenNotice failed:', err);
+    }
+  }
+
+  /**
+   * Explicit-prose-routing delivery gateway (docs/explicit-prose-routing.md).
+   * Every prose segment of an `explicit`-mode agent flows through here:
+   * parse the `>>` prefix, resolve the target, deliver — or bounce to the
+   * clipboard with a resend notice. Misdelivery is structurally impossible:
+   * nothing is ever sent to a destination the model did not name (directly
+   * or via the turn's sticky target).
+   */
+  private async deliverProse(agent: Agent, rawText: string): Promise<void> {
+    // Multi-envelope: a single prose block may address SEVERAL destinations —
+    // every line beginning with `>>` opens a new envelope, routed
+    // independently (first live use: Tilde 2026-07-24, one block carrying a
+    // letter to #tilde-mythos AND a `>>#tilde` aside; the single-envelope
+    // parser delivered the aside literally into the first destination —
+    // exactly the leak class this mode exists to kill). Text before the
+    // first `>>` is its own unprefixed envelope (sticky/bounce as usual).
+    const lines = rawText.split('\n');
+    const envelopes: string[] = [];
+    let current: string[] = [];
+    for (const line of lines) {
+      // Only a REAL prefix line opens an envelope: `>>` immediately followed
+      // by a target token. A quoted `>> arrow` (space after) stays body text.
+      if (/^>>\S/.test(line.trimStart()) && current.length > 0) {
+        envelopes.push(current.join('\n'));
+        current = [];
+      }
+      current.push(line);
+    }
+    if (current.length > 0) envelopes.push(current.join('\n'));
+
+    for (const envelope of envelopes) {
+      if (!envelope.trim()) continue;
+      await this.deliverProseEnvelope(agent, envelope.replace(/^\s+(?=>>)/, ''));
+    }
+  }
+
+  private async deliverProseEnvelope(agent: Agent, rawText: string): Promise<void> {
+    const name = agent.name;
+    const parsed = parseProsePrefix(rawText);
+    if (parsed.continueTurn) this.proseContinuations.add(name);
+
+    if (parsed.kind === 'private') {
+      // The text already lives in the assistant message (window/chronicle);
+      // "delivery" is deliberately a no-op. Consumes the retained text if the
+      // segment embedded it.
+      if (parsed.body.includes('{{unsent}}')) this.proseClipboards.delete(name);
+      console.error(`[prose] ${name}: >>skip_reply — ${parsed.body.length} chars kept in context (not sent)`);
+      return;
+    }
+
+    let targetChannel: string;
+    let body: string;
+    if (parsed.kind === 'target') {
+      const res = this.channelRegistry!.resolveProseTarget(parsed.target!);
+      if ('error' in res) {
+        this.bounceProse(agent, parsed.body, res.error, res.candidates);
+        return;
+      }
+      targetChannel = res.channelId;
+      // Sticky within the turn: later unprefixed segments follow this target.
+      this.proseTargetPins.set(name, targetChannel);
+      body = parsed.body;
+    } else {
+      const sticky = this.proseTargetPins.get(name);
+      if (!sticky) {
+        this.bounceProse(agent, rawText, 'no destination prefix and no destination set yet this turn');
+        return;
+      }
+      targetChannel = sticky;
+      body = rawText;
+    }
+
+    const usedClipboard = body.includes('{{unsent}}');
+    if (usedClipboard) {
+      body = body.replaceAll('{{unsent}}', this.proseClipboards.get(name) ?? '');
+    }
+    if (!body.trim()) {
+      console.error(`[prose] ${name}: empty body after prefix/substitution — nothing to send`);
+      return;
+    }
+
+    try {
+      const result = await this.channelRegistry!.routeSpeech(name, body, targetChannel);
+      if (result?.delivered) {
+        this.proseBounceStreaks.delete(name);
+        if (usedClipboard) this.proseClipboards.delete(name);
+      }
+    } catch (err) {
+      console.error(`[prose] ${name}: delivery to ${targetChannel} failed:`, err);
+    }
+  }
+
+  /** Cap on consecutive bounce-triggered wakes (notices still append after). */
+  private static readonly PROSE_BOUNCE_WAKE_CAP = 2;
+
+  private bounceProse(agent: Agent, text: string, reason: string, candidates?: string[]): void {
+    const name = agent.name;
+    this.proseClipboards.set(name, text);
+    const streak = (this.proseBounceStreaks.get(name) ?? 0) + 1;
+    this.proseBounceStreaks.set(name, streak);
+    const cand = candidates?.length ? ` Known channels it could mean: ${candidates.join(', ')}.` : '';
+    const notice =
+      `[prose-routing] Your text (${text.length} chars) was not delivered — ${reason}.${cand} ` +
+      'The text is retained; nothing is lost. To deliver it unchanged, reply with a ' +
+      'destination plus the token {{unsent}}, e.g. ">>#channel {{unsent}}" or ">>@person {{unsent}}". ' +
+      '">>skip_reply {{unsent}}" keeps it in context only. The prose_help tool shows the full syntax.';
+    try {
+      // Through framework.addMessage, NOT the context manager directly: while
+      // the turn is still streaming this defers the notice to the next tool
+      // boundary, where it is BOTH stored in order and injected into the live
+      // stream (hear-while-acting) — the model sees the error and can correct
+      // the prefix within the same turn. A direct append here would land the
+      // notice before the turn's assistant blocks (cache bust, invisible
+      // until the next compile).
+      const id = this.addMessage(
+        'user',
+        [{ type: 'text', text: notice }],
+        { system: true, kind: 'prose-bounce' },
+      );
+      if (id) this.emitTrace({ type: 'message:added', messageId: id, source: 'prose-bounce' });
+      else this.emitTrace({ type: 'message:added', messageId: 'deferred', source: 'prose-bounce' });
+    } catch (err) {
+      console.error('bounceProse: failed to record bounce notice:', err);
+    }
+    const capped = streak > AgentFramework.PROSE_BOUNCE_WAKE_CAP;
+    console.error(
+      `[prose] ${name}: BOUNCED ${text.length} chars — ${reason}` +
+      (capped ? ' (bounce-wake cap reached; notice appended without wake)' : ''),
+    );
+    if (!capped) {
+      // Wake so the resend can happen immediately — an unsent DM reply must
+      // not sit invisible until the next unrelated event.
+      this.pendingRequests.push({
+        agentName: name,
+        reason: 'prose-bounce',
+        source: 'framework',
+        timestamp: Date.now(),
+      });
+    }
+  }
+
+  /**
+   * One-time mode primer (docs/explicit-prose-routing.md): when an agent's
+   * configured proseRouting differs from the last mode we primed them for,
+   * append the teaching notice and persist the new mode. A brand-new agent
+   * in default locus mode is recorded silently — no primer for the status quo.
+   */
+  private maybePrimeProseMode(agent: Agent): void {
+    const mode = agent.proseRouting;
+    try {
+      const data = this.store.getStateJson(FRAMEWORK_STATE_ID);
+      const state = (data && typeof data === 'object' ? data : {}) as Record<string, unknown>;
+      const primed = { ...((state.proseRoutingPrimed as Record<string, string> | undefined) ?? {}) };
+      const stored = primed[agent.name];
+      if (stored === mode) return;
+      // Absence means "always default (locus)": a locus-mode agent that was
+      // never explicit needs no entry and no primer — and skipping the write
+      // keeps framework/state from growing a record per agent (scaling gate).
+      if (mode === 'locus' && stored === undefined) return;
+      if (mode === 'locus') delete primed[agent.name];
+      else primed[agent.name] = mode;
+      state.proseRoutingPrimed = primed;
+      this.store.setStateJson(FRAMEWORK_STATE_ID, state);
+    } catch (err) {
+      console.error('maybePrimeProseMode: state read/write failed:', err);
+      return;
+    }
+    try {
+      const id = agent.getContextManager().addMessage(
+        'user',
+        [{ type: 'text', text: proseModePrimer(mode) }],
+        { system: true, kind: 'prose-routing-primer' },
       );
-      await this.startAgentStream(agent, { ...trigger, channelId: triggerChannel });
+      this.emitTrace({ type: 'message:added', messageId: id, source: 'prose-routing-primer' });
+      console.error(`[prose] ${agent.name}: mode primer appended (${mode})`);
+    } catch (err) {
+      console.error('maybePrimeProseMode: failed to append primer:', err);
     }
   }
 
@@ -3959,14 +4557,60 @@ export class AgentFramework {
     // instead falls back to the global default. A given agent runs one turn at a
     // time, so a set here is only read during THIS turn's routeSpeech /
     // buildChannelContext; retries re-run with the same trigger, re-setting it.
-    if (trigger?.channelId) {
-      this.activeTriggerChannels.set(agent.name, trigger.channelId);
-    } else {
-      this.activeTriggerChannels.delete(agent.name);
+    // A context-budget restart continues the SAME logical turn in a fresh
+    // stream — its trigger carries no channelId, and deleting the trigger
+    // channel here mid-logical-turn is exactly the hole that sent Sol's DM
+    // reply to a stale guild channel (2026-07-22): any live locus resolution
+    // after the restart fell through to the hours-old defaultPublishChannel.
+    // Keep the turn's trigger channel across restarts; only real new turns
+    // reset it.
+    if (trigger?.reason !== 'context_budget_restart') {
+      if (trigger?.channelId) {
+        this.activeTriggerChannels.set(agent.name, trigger.channelId);
+      } else {
+        this.activeTriggerChannels.delete(agent.name);
+      }
+    }
+
+    // FREEZE this turn's outbound locus now (turn-frozen routing). Resolved
+    // once — home channel for forks, else the triggering channel, else the
+    // global default — and never moved for the rest of the turn: mid-turn
+    // injections must not redirect the agent's plain prose (ambient chatter /
+    // reactions hijacked it before, 2026-07-21). A context-budget restart
+    // continues the same logical turn, so it keeps the existing pin. The
+    // eager snapshot also protects heartbeat turns from a moving
+    // defaultPublishChannel mid-turn. If the effective locus differs from the
+    // last one announced, drop a durable `[routing]` notice into the window
+    // BEFORE this turn compiles, so the agent always knows where its voice
+    // goes (announce-on-change only — no per-turn chatter, append-only for
+    // KV stability).
+    if (trigger?.reason !== 'context_budget_restart') {
+      if (attempt === 0) this.maybePrimeProseMode(agent);
+      if (agent.proseRouting === 'explicit') {
+        // Explicit prose routing: there is no locus. The model names every
+        // destination in-band (`>>` prefixes); the only turn state is the
+        // sticky target, reset for each fresh turn. No freeze, no announce.
+        this.proseTargetPins.delete(agent.name);
+        this.proseContinuations.delete(agent.name);
+        this.midTurnInputSignals.delete(agent.name);
+        this.turnLocusPins.delete(agent.name);
+      } else {
+        const locus = this.channelRegistry?.resolveLocus(agent.name) ?? null;
+        if (locus !== null) this.turnLocusPins.set(agent.name, locus);
+        else this.turnLocusPins.delete(agent.name);
+        this.midTurnInputSignals.delete(agent.name);
+        if (attempt === 0) this.announceLocusIfChanged(agent.name, locus);
+      }
     }
 
     this.touchEphemeralRun(agent.name, true);
-    this.emitTrace({ type: 'inference:started', agentName: agent.name });
+    this.emitTrace({
+      type: 'inference:started',
+      agentName: agent.name,
+      // The turn-frozen locus was pinned just above (kept across a
+      // context-budget restart, which skips the re-pin but re-emits this).
+      channelId: this.turnLocusPins.get(agent.name),
+    });
     this.eventGate?.onInferenceStarted(agent.name);
     this.lastInferenceAt.set(agent.name, { ...this.lastInferenceAt.get(agent.name), startedAt: Date.now() });
 
@@ -3974,6 +4618,9 @@ export class AgentFramework {
       const requestSnapshot = this.captureInferenceToolSnapshot(agent);
       const allTools = this.getToolsForAgent(agent.name, requestSnapshot);
       const tools = allTools.filter((t) => agent.canUseTool(t.name));
+      // Explicit-mode agents get the on-demand routing reference (teach-by-
+      // bounce: the grammar is never injected, only served when asked).
+      if (agent.proseRouting === 'explicit') tools.push(PROSE_HELP_TOOL);
 
       // Gather context from modules (pull-based) and MCPL hooks (push-based)
       // Both produce ContextInjection[] that get merged before inference.
@@ -4078,24 +4725,15 @@ export class AgentFramework {
     let hadToolCalls = false;
 
     // ---- Present-while-acting turn state ---------------------------------
-    // Output locus for the current CONVERSATIONAL ROUND: resolved lazily and
-    // kept stable across tool-only rounds. A channel message injected at a
-    // tool boundary replaces the pin before the next model round, because a
-    // single provider inference can now contain several conversations. The
-    // pin lives in `turnLocusPins` so it survives a context-budget restart. A
-    // null resolution is not pinned.
-    if (trigger?.reason !== 'context_budget_restart') {
-      this.turnLocusPins.delete(agent.name);
-      this.midTurnRoutingResets.delete(agent.name);
-    }
-    const resolveTurnLocus = (): string | null => {
-      let locus = this.turnLocusPins.get(agent.name) ?? null;
-      if (locus === null && this.channelRegistry) {
-        locus = this.channelRegistry.resolveLocus(agent.name);
-        if (locus !== null) this.turnLocusPins.set(agent.name, locus);
-      }
-      return locus;
-    };
+    // Output locus for the WHOLE logical turn: frozen in startAgentStream
+    // (home → addressed trigger → global default) before this stream began,
+    // and never moved until the next turn. Mid-turn injections do not touch
+    // it — an ambient message or a reaction arriving at a tool boundary must
+    // not redirect the agent's task narration (2026-07-21 Cairn misroute).
+    // The pin lives in `turnLocusPins` so a context-budget restart (same
+    // logical turn, fresh driveStream) keeps it.
+    const resolveTurnLocus = (): string | null =>
+      this.turnLocusPins.get(agent.name) ?? null;
 
     // Ordered delivery chain for live-routed prose. Links are enqueued
     // WITHOUT awaiting in the stream-event loop — an awaited network post
@@ -4128,32 +4766,30 @@ export class AgentFramework {
     // delivered exactly once, at turn end.
     let liveProseRouting = false;
 
-    // Typing indicator: show "<agent> is typing…" in the channel she's
-    // responding to, for the whole duration of this turn. Started here (paired
-    // with the finally below, so it can never leak) and refreshed on a 7s
-    // interval by the ChannelRegistry until stopped on any exit path.
-    let typingChannel = this.channelRegistry
-      ? trigger?.channelId ?? this.channelRegistry.getDefaultPublishChannel()
-      : null;
+    // Typing indicator: show "<agent> is typing…" for the whole duration of
+    // this turn. Started here (paired with the finally below, so it can never
+    // leak) and refreshed on a 7s interval by the ChannelRegistry until
+    // stopped on any exit path. Never moves mid-turn.
+    //   - locus mode: the frozen routing pin (where bare prose will land).
+    //   - explicit mode: there is no locus — indicate on the TRIGGER channel
+    //     (where the wake came from). Typing is presence, not delivery, so
+    //     this doesn't violate never-guess: it says "attending to what you
+    //     sent here", which is true regardless of where the reply goes.
+    //     Heartbeat/no-trigger explicit turns show no indicator.
+    const typingChannel =
+      agent.proseRouting === 'explicit'
+        ? trigger?.channelId ?? null
+        : resolveTurnLocus();
     if (typingChannel) this.channelRegistry!.startTyping(typingChannel);
 
     const adoptInjectedRound = (): void => {
-      if (!this.midTurnRoutingResets.has(agent.name)) return;
-      const nextLocus = this.midTurnRoutingResets.get(agent.name) ?? null;
-      this.midTurnRoutingResets.delete(agent.name);
+      if (!this.midTurnInputSignals.has(agent.name)) return;
+      this.midTurnInputSignals.delete(agent.name);
 
-      // A new human/agent message, not merely a tool result, means any earlier
-      // explicit delivery has completed its conversational job.
+      // A new conversational message, not merely a tool result, means any
+      // earlier explicit delivery has completed its conversational job.
+      // Routing is NOT touched: the turn locus stays frozen.
       turnSilenced = false;
-
-      if (nextLocus) {
-        this.turnLocusPins.set(agent.name, nextLocus);
-        if (typingChannel !== nextLocus) {
-          if (typingChannel) this.channelRegistry?.stopTyping(typingChannel);
-          typingChannel = nextLocus;
-          this.channelRegistry?.startTyping(nextLocus);
-        }
-      }
     };
 
     try {
@@ -4167,6 +4803,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;
 
@@ -4178,6 +4818,7 @@ export class AgentFramework {
               phase,
               blockType: block.type,
               blockIndex: index,
+              channelId: typingChannel ?? undefined,
             });
             break;
           }
@@ -4205,13 +4846,30 @@ export class AgentFramework {
                 (b) => b.type !== 'tool_result'
               );
             } else {
-              // Fallback (older membrane / XML tool mode): preamble + calls
+              // Fallback (older membrane / XML tool mode): preamble + calls.
+              // XML mode: persist the verbatim generation on each tool_use
+              // (membrane#36 round-trip fidelity). context.rawText is the
+              // parser's fullMatch — the exact <function_calls> block the
+              // model wrote (plus the harness-appended close tag), shared by
+              // every call in the round; the anthropic-xml formatter replays
+              // it byte-identically instead of reconstructing. Guarded by
+              // shape so a native-path fallback can never attach non-XML.
+              const rawText = event.context.rawText;
+              const rawXml = rawText && /^<(antml:)?function_calls>/.test(rawText)
+                ? rawText
+                : undefined;
               assistantBlocks = [];
               if (event.context.preamble) {
                 assistantBlocks.push({ type: 'text', text: event.context.preamble });
               }
               for (const c of event.calls) {
-                assistantBlocks.push({ type: 'tool_use', id: c.id, name: c.name, input: c.input as Record<string, unknown> });
+                assistantBlocks.push({
+                  type: 'tool_use',
+                  id: c.id,
+                  name: c.name,
+                  input: c.input as Record<string, unknown>,
+                  ...(rawXml ? { rawXml } : {}),
+                });
               }
             }
             this.pendingAssistantBlocks.set(agent.name, assistantBlocks);
@@ -4251,7 +4909,21 @@ export class AgentFramework {
                 liveProseRouting = true;
                 const roundSegments = splitProseSegments(assistantBlocks);
                 if (roundSegments.length > 0) {
-                  if (turnSilenced) {
+                  if (agent.proseRouting === 'explicit') {
+                    // Explicit mode: every segment through the prose gateway.
+                    // Silencing does not apply — unprefixed prose bounces and
+                    // prefixed prose is deliberate; think-privacy still holds.
+                    if (!hasSameRoundPrivateThink) {
+                      console.error(
+                        `[prose] ${agent.name}: mid-turn round [${roundToolNames.join(', ')}] -> ${roundSegments.length} segment(s) via prose gateway`,
+                      );
+                      for (const seg of roundSegments) {
+                        turnSpeechChain = turnSpeechChain
+                          .then(() => this.deliverProse(agent, seg))
+                          .catch((err) => console.error('mid-turn prose delivery failed:', err));
+                      }
+                    }
+                  } else if (turnSilenced) {
                     console.error(
                       `[routing] ${agent.name}: mid-turn round [${roundToolNames.join(', ')}] -> prose NOT routed (turn silenced)`,
                     );
@@ -4575,10 +5247,29 @@ export class AgentFramework {
                 .join('\n')
                 .trim();
               if (speechText) {
-                try {
-                  await this.channelRegistry.routeSpeech(agent.name, speechText);
-                } catch (err) {
-                  console.error('speech routing failed:', err);
+                if (agent.proseRouting === 'explicit') {
+                  console.error(`[prose] ${agent.name}: text-only turn -> prose gateway`);
+                  try {
+                    await this.deliverProse(agent, speechText);
+                  } catch (err) {
+                    console.error('text-only prose delivery failed:', err);
+                  }
+                } else {
+                  // Route to the TURN-FROZEN locus, like every other speech
+                  // path. This dispatch runs AFTER the agent is idle, so a live
+                  // resolution here can read the NEXT turn's trigger state (or
+                  // a post-restart cleared one) and land the reply in a stale
+                  // channel — the 2026-07-22 Sol DM-to-guild misroute. The
+                  // frozen pin is immune to both races.
+                  const locus = resolveTurnLocus();
+                  console.error(
+                    `[routing] ${agent.name}: text-only turn -> routing speech -> ${locus ?? '(none)'}`,
+                  );
+                  try {
+                    await this.channelRegistry.routeSpeech(agent.name, speechText, locus);
+                  } catch (err) {
+                    console.error('speech routing failed:', err);
+                  }
                 }
               }
             } else if (this.channelRegistry && hadToolCalls && allText.length > 0) {
@@ -4611,7 +5302,20 @@ export class AgentFramework {
               // the chain may still be flushing earlier rounds' posts.
               await turnSpeechChain;
 
-              if (silenced || segments.length === 0) {
+              if (agent.proseRouting === 'explicit') {
+                if (segments.length > 0) {
+                  console.error(
+                    `[prose] ${agent.name}: tool-call turn [${toolNames.join(', ')}] -> ${segments.length} trailing segment(s) via prose gateway`,
+                  );
+                  for (const seg of segments) {
+                    try {
+                      await this.deliverProse(agent, seg);
+                    } catch (err) {
+                      console.error('trailing prose delivery failed:', err);
+                    }
+                  }
+                }
+              } else if (silenced || segments.length === 0) {
                 console.error(
                   `[routing] ${agent.name}: tool-call turn [${toolNames.join(', ') || 'none'}] -> trailing prose NOT routed ` +
                   `(${silenced ? 'silencing tool / explicit send' : 'no trailing prose'})`,
@@ -4642,6 +5346,21 @@ export class AgentFramework {
             // BEFORE dispatchSpeech. Locus routing is speech dispatch and
             // doesn't depend on the status field, so it correctly runs after.
 
+            // Explicit-prose `!` continuation: a prose segment this turn asked
+            // to keep going (`>>#x !` / `>>private !`) — start another turn
+            // now instead of pausing until the next external event. This gives
+            // prose the same continuation ability tool rounds have (wanted for
+            // robotics-style loops where an end-of-turn pause is harmful).
+            if (this.proseContinuations.delete(agent.name)) {
+              console.error(`[prose] ${agent.name}: '!' continuation — requesting immediate next turn`);
+              this.pendingRequests.push({
+                agentName: agent.name,
+                reason: 'prose-continuation',
+                source: 'framework',
+                timestamp: Date.now(),
+              });
+            }
+
             break;
           }
 
@@ -5111,6 +5830,11 @@ export class AgentFramework {
       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);
@@ -5144,6 +5868,21 @@ export class AgentFramework {
       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;
@@ -5522,6 +6261,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 {};
   }
 
@@ -5591,7 +6337,25 @@ export class AgentFramework {
     // (e.g. a reason string that crossed a serialization boundary). It matches
     // CM's current OverBudgetError wording and MAY rot if CM rewords it — the
     // errorType gate is the one that's load-bearing.
-    const overBudget = errorType === 'over_budget' || /exceed hard budget/i.test(reason);
+    const overBudget =
+      errorType === 'over_budget' ||
+      errorType === 'context_refusal' ||
+      /exceed hard budget|no summary covers/i.test(reason);
+    // Observability: a refused compile means the agent cannot think AT ALL
+    // this turn — surface it on the ops-alert pipeline (ops:alert trace +
+    // webhook → fleet-watch) immediately, not only at the hard-down streak.
+    // The per-(agent,kind) cooldown throttles repeats; failures.log already
+    // has the per-exhaustion record from logFailure above.
+    if (overBudget) {
+      this.opsAlert(
+        'context-refusal',
+        agentName,
+        `compile refused (${errorType ?? 'unclassified'}): ${reason.slice(0, 300)} — ` +
+        `drain breaker ${agent ? 'kicking' : 'unavailable (no agent handle)'}; ` +
+        `if this persists, raise contextBudgetTokens or overBudgetGraceRatio.`,
+        { skipLog: true },
+      );
+    }
     if (agent && overBudget && !this.overBudgetDrainInFlight.has(agentName)) {
       this.overBudgetDrainInFlight.add(agentName);
       void (async () => {
@@ -5788,11 +6552,24 @@ export class AgentFramework {
         // yes, wake no).
         onRouteFailure: ({ channelId, reason, textLen }) => {
           try {
+            // Render a human-readable channel name when we can — a bare
+            // snowflake in the marker is unresolvable for the agent (the
+            // 2026-07-21 incident read as "a stale artifact", not a live
+            // failure). The marker is `system: true`, so it is never
+            // conversational and never influences routing.
+            const label = channelId
+              ? this.channelRegistry?.getDescriptor(channelId)?.label
+              : undefined;
+            const where = channelId
+              ? label && label !== channelId
+                ? `${label.startsWith('#') ? label : `#${label}`} (${channelId})`
+                : channelId
+              : 'the channel';
             this.addMessage(
               'user',
               [{
                 type: 'text',
-                text: `[discord-send-failed] Your previous reply (${textLen} chars) could not be delivered to ${channelId ?? 'the channel'} (${reason}). It was saved to your archive but the human did not receive it.`,
+                text: `[discord-send-failed] Your previous reply (${textLen} chars) could not be delivered to ${where} (${reason}). It was saved to your archive but the human did not receive it.`,
               }],
               { system: true, kind: 'discord-send-failed', channelId: channelId ?? '', reason },
             );
@@ -5800,6 +6577,13 @@ export class AgentFramework {
             console.error('onRouteFailure: failed to record send-failure marker:', err);
           }
         },
+        // A channel opened without the agent asking (policy admission or an
+        // open forced by delivery) must be announced in the window, with the
+        // opt-out named. Routed here so registry-driven opens and framework-
+        // driven opens produce the same durable notice.
+        onChannelAutoOpened: ({ conversationId, source, channels }) => {
+          this.recordChannelAutoOpenNotice(conversationId, channels, source);
+        },
       },
     );
 
@@ -6839,6 +7623,44 @@ export class AgentFramework {
           }
         }
 
+        // INVARIANT: engaging a channel opens it. A successful explicit send
+        // into a channel the registry knows as closed drives the same open
+        // flow as channel_open (durable desired state, server subscribe), so
+        // there is no such thing as posting into a channel that stays
+        // half-alive (no typing, no reactions, no inbound forwarding).
+        // Fire-and-forget: the send already succeeded; the open must not
+        // delay or fail the tool result.
+        if (
+          this.channelRegistry &&
+          SEND_ENGAGEMENT_TOOLS.has(toolName) &&
+          result.isError !== true
+        ) {
+          const target =
+            extractChannelIdFromToolResult(result.content) ??
+            (typeof args.channelId === 'string' ? (args.channelId as string) : undefined);
+          if (target) {
+            this.channelRegistry
+              .openIfClosedForSend(target, serverId)
+              .then(({ status, channelId, label }) => {
+                if (status === 'opened') {
+                  console.error(
+                    `[channel] ${agentName}: explicit ${toolName} into closed channel ${target} — opened (send implies engagement)`,
+                  );
+                  this.recordChannelAutoOpenNotice(
+                    agentName,
+                    [{ channelId: channelId ?? target, label }],
+                    'opened-by-reply',
+                  );
+                } else if (status === 'open-failed') {
+                  console.error(
+                    `[channel] ${agentName}: ${toolName} delivered to ${target} but the open-on-send failed — channel remains half-alive, will reconcile`,
+                  );
+                }
+              })
+              .catch((err) => console.error('[channel] open-on-send error:', err));
+          }
+        }
+
         // Convert MCP tool result to framework ToolResult.
         // When the result contains non-text blocks (e.g. images from an MCP
         // tool like zulip-mcp's fetch_attachment), pass the full content array
@@ -6934,6 +7756,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 as { channelId?: string } | undefined)?.channelId
+            ?? (call.input as { channelId?: string } | undefined)?.channelId;
+          if (opened) this.activeTriggerChannels.set(agentName, opened);
+        }
         this.pushEvent({
           type: 'tool-result',
           callId: call.id,
@@ -7074,12 +7909,29 @@ export class AgentFramework {
       : seconds >= 60 ? `${Math.round(seconds / 60)}m`
       : `${Math.round(seconds)}s`;
 
-    // Announce in the sticky channel (best-effort; never blocks the result).
+    // Announce in the TURN's frozen locus (best-effort; never blocks the
+    // result). The sleep tool runs mid-turn, so the pin is live — same
+    // authority as every other speech path, no live re-resolution.
     if (announce && this.channelRegistry) {
       const text = input.message ?? `💤 Going quiet for ${human}. I'll still see messages, but won't respond until I wake.`;
-      this.channelRegistry.routeSpeech(agentName, text).catch((err) => {
-        console.error('[sleep] announce failed:', err instanceof Error ? err.message : err);
-      });
+      const agent = this.agents.get(agentName);
+      if (agent?.proseRouting === 'explicit') {
+        // Explicit mode: announce to the turn's sticky prose target if the
+        // model has set one; otherwise stay quiet — never guess a channel.
+        const target = this.proseTargetPins.get(agentName);
+        if (target) {
+          this.channelRegistry.routeSpeech(agentName, text, target).catch((err) => {
+            console.error('[sleep] announce failed:', err instanceof Error ? err.message : err);
+          });
+        } else {
+          console.error(`[sleep] ${agentName}: no prose target this turn — sleep announcement not posted (explicit mode never guesses)`);
+        }
+      } else {
+        const locus = this.turnLocusPins.get(agentName) ?? null;
+        this.channelRegistry.routeSpeech(agentName, text, locus).catch((err) => {
+          console.error('[sleep] announce failed:', err instanceof Error ? err.message : err);
+        });
+      }
     }
 
     console.error(`[sleep] agent=${agentName} seconds=${seconds} announce=${announce} until=${new Date(until).toISOString()}`);
@@ -7096,6 +7948,75 @@ export class AgentFramework {
     });
   }
 
+  /**
+   * 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.
+   */
+  private dispatchReadImageToolCall(agentName: string, call: ToolCall): void {
+    this.emitTrace({ type: 'tool:started', module: 'workspace', tool: call.name, callId: call.id, input: call.input });
+    const finish = (result: ToolResult): void => {
+      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 (): Promise<void> => {
+      try {
+        const workspace = this.getWorkspaceModule();
+        if (!workspace || typeof workspace.readBinary !== 'function') {
+          throw new Error('read_image requires a workspace module');
+        }
+        const input = (call.input ?? {}) as { path?: unknown };
+        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