@animalabs/agent-framework 0.5.6 → 0.6.0

package/src/framework.ts

@@ -1,6 +1,6 @@
 import { join } from 'node:path';
 import { JsStore } from '@animalabs/chronicle';
-import type { Membrane, ContentBlock, NormalizedRequest, YieldingStream, ToolResult as MembraneToolResult } from '@animalabs/membrane';
+import type { Membrane, ContentBlock, NormalizedRequest, YieldingStream, ToolResult as MembraneToolResult, ToolResultContentBlock } from '@animalabs/membrane';
 import { MembraneError } from '@animalabs/membrane';
 import { ContextManager, PassthroughStrategy } from '@animalabs/context-manager';
 import type {
@@ -50,7 +50,10 @@ import { HookOrchestrator } from './mcpl/hook-orchestrator.js';
 import { PushHandler, type McplPushEvent } from './mcpl/push-handler.js';
 import { InferenceRouter } from './mcpl/inference-router.js';
 import { ChannelRegistry } from './mcpl/channel-registry.js';
+import { ConversationRouter } from './mcpl/conversation-router.js';
 import { safeSlice } from './safe-slice.js';
+import { toolResultDataToHistoryString } from './tool-result-history.js';
+import { splitProseSegments } from './prose-segments.js';
 import { CheckpointManager } from './mcpl/checkpoint-manager.js';
 import { isToolAllowed } from './mcpl/tool-policy.js';
 import { EventGate } from './gate/event-gate.js';
@@ -74,6 +77,7 @@ import type {
 import type { ContextInjection } from '@animalabs/context-manager';
 
 const FRAMEWORK_STATE_ID = 'framework/state';
+const CONVERSATION_ROUTER_STATE_ID = 'framework/conversation-router';
 const INFERENCE_LOG_ID = 'framework/inference-log';
 const PROCESS_LOG_ID = 'framework/process-log';
 const TURN_CHECKPOINTS_ID = 'framework/turn-checkpoints';
@@ -180,6 +184,24 @@ function extractGateFields(event: ProcessEvent): {
 /**
  * The main agent framework.
  */
+/** Params for a `host/command` request from an MCPL surface server. */
+interface HostCommandParams {
+  command?: string;
+  agentName?: string;
+  turns?: number;
+  /** Message-granular undo: branch the chronicle so the last N messages
+   *  (regardless of participant) are no longer on the active branch.
+   *  Mutually exclusive with `turns`. */
+  messages?: number;
+  /** For the `hide` command: Discord message id of the (first) message to
+   *  remove. With `toMessageId`, removes the inclusive range between them. */
+  fromMessageId?: string;
+  /** For the `hide` command: Discord message id ending an inclusive range. */
+  toMessageId?: string;
+  requesterId?: string;
+  requesterName?: string;
+}
+
 export class AgentFramework {
   private store: JsStore;
   private ownsStore: boolean;
@@ -190,6 +212,16 @@ export class AgentFramework {
   private inferencePolicy: InferencePolicy;
   private errorPolicy: ErrorPolicy;
   private pendingRequests: InferenceRequest[] = [];
+  /**
+   * Per-agent channel that triggered the agent's CURRENT inference turn, if any
+   * (item-3 redux). Read by the ChannelRegistry's `activeChannelResolver` to
+   * route a single-trunk agent's plain-text speech back to the channel it is
+   * answering, instead of the process-global most-recent-inbound locus that a
+   * concurrent message elsewhere can hijack. Set at turn start (or cleared for a
+   * heartbeat / no-trigger turn) in startAgentStream; overwritten by the next
+   * turn. Never read between turns (a given agent runs one turn at a time).
+   */
+  private activeTriggerChannels: Map<string, string> = new Map();
   private running = false;
   private loopPromise: Promise<void> | null = null;
   private traceListeners: TraceEventListener[] = [];
@@ -199,6 +231,12 @@ export class AgentFramework {
   private processLoggingBroadcast: boolean;
   private activeStreams: Map<string, Promise<void>> = new Map();
   private pendingAssistantBlocks: Map<string, ContentBlock[]> = new Map();
+  /** Per-agent count of consecutive exhausted inferences (reset on any success).
+   *  Drives hard-down escalation — see noteInferenceExhausted. */
+  private consecutiveInferenceFailures: Map<string, number> = new Map();
+  /** N consecutive failed inferences ⇒ the agent is treated as hard-down and
+   *  escalated loudly to stderr. */
+  private readonly inferenceFailureEscalationThreshold = 3;
   /** Name of the primary (non-ephemeral) agent for routing framework messages. */
   private primaryAgentName: string | null = null;
 
@@ -210,6 +248,9 @@ export class AgentFramework {
   private turnCounters: Map<string, number> = new Map(); // agentName → next turnIndex
   private redoStacks: Map<string, RedoEntry[]> = new Map(); // agentName → redo entries
 
+  /** Liveness watchdog (fail hard on a wedged main thread). Null unless enabled. */
+  private livenessWatchdog: import('./runtime/liveness-watchdog.js').LivenessWatchdog | null = null;
+
   // MCPL subsystems (null when no mcplServers configured)
   private mcplServerRegistry: McplServerRegistry | null = null;
   private featureSetManager: FeatureSetManager | null = null;
@@ -219,6 +260,22 @@ export class AgentFramework {
   private inferenceRouter: InferenceRouter | null = null;
   private channelRegistry: ChannelRegistry | null = null;
   private checkpointManager: CheckpointManager | null = null;
+  /** Per-channel conversation routing (null unless config.conversations set). */
+  private conversationRouter: ConversationRouter | null = null;
+  /** Agent configs by name — fork agents are built from the template's config. */
+  private agentConfigs: Map<string, AgentConfig> = new Map();
+  /**
+   * Fork agent → its home channel. Permanent (unlike router bindings, which
+   * expire): publish/injection scoping must survive unbinding so the closure
+   * turn still lands in the right channel.
+   */
+  private conversationAgentHomes: Map<string, string> = new Map();
+  /** Last idle-TTL sweep timestamp. */
+  private lastConversationSweep = 0;
+
+  /** Forks whose TTL closure turn has been queued — disposed (removed from
+   * agents/agentConfigs/conversationAgentHomes) when their stream ends. */
+  private closingConversationAgents: Set<string> = new Set();
   private mcplTools: import('./types/index.js').ToolDefinition[] = [];
   private mcplToolRefreshInFlight = false;
   private mcplToolRefreshPending = false;
@@ -265,6 +322,8 @@ export class AgentFramework {
       getMessage: (id) => this.getMessage(id),
       queryMessages: (filter) => this.queryMessages(filter),
       pushEvent: (event) => this.pushEvent(event),
+      onTrace: (listener) => this.onTrace(listener),
+      callTool: (call) => this.executeToolCall(call),
     });
   }
 
@@ -352,6 +411,35 @@ export class AgentFramework {
       await framework.addModule(module);
     }
 
+    // Initialize per-channel conversation routing (if configured)
+    if (config.conversations) {
+      if (!framework.agents.has(config.conversations.templateAgent)) {
+        throw new Error(
+          `conversations.templateAgent "${config.conversations.templateAgent}" ` +
+          `is not a configured agent`
+        );
+      }
+      framework.conversationRouter = new ConversationRouter(config.conversations);
+
+      // Generation counters persist across restarts — reusing generation 1's
+      // agent name after a restart would reopen (and re-seed) the previous
+      // engagement's Chronicle namespace.
+      try {
+        store.registerState({ id: CONVERSATION_ROUTER_STATE_ID, strategy: 'snapshot' });
+      } catch {
+        // Already registered
+      }
+      try {
+        const data = store.getStateJson(CONVERSATION_ROUTER_STATE_ID) as
+          { generations?: Record<string, number> } | null;
+        if (data?.generations) {
+          framework.conversationRouter.hydrateGenerations(data.generations);
+        }
+      } catch {
+        // No persisted state yet
+      }
+    }
+
     // Initialize EventGate if configured (before MCPL so it can be wired as trigger filter)
     if (config.gate) {
       const configPath = config.gate.configPath
@@ -361,6 +449,7 @@ export class AgentFramework {
       framework.eventGate = new EventGate({
         configPath,
         initialConfig: config.gate.config,
+        privilegedUsersPath: config.gate.privilegedUsersPath,
         emitTrace: (e) => framework.emitTrace(e as { type: TraceEvent['type']; [key: string]: unknown }),
         addMessage: (p, c, m) => framework.addMessage(p, c, m as MessageMetadata),
         requestInference: (agentName, reason, source) => {
@@ -370,6 +459,19 @@ export class AgentFramework {
       });
     }
 
+    // Liveness watchdog: fail hard if the main thread wedges (opt-in).
+    if (config.watchdog?.enabled) {
+      const { LivenessWatchdog } = await import('./runtime/liveness-watchdog.js');
+      framework.livenessWatchdog = new LivenessWatchdog({
+        enabled: true,
+        thresholdMs: config.watchdog.thresholdMs,
+        action: config.watchdog.action,
+        reportPath: config.watchdog.reportPath
+          ?? (config.storePath ? join(config.storePath, 'watchdog-wedge.jsonl') : undefined),
+      });
+      framework.livenessWatchdog.start();
+    }
+
     // Initialize MCPL subsystems if configured
     if (config.mcplServers && config.mcplServers.length > 0) {
       // Validate tool prefixes: no collisions with module names or between servers
@@ -455,6 +557,7 @@ export class AgentFramework {
 
     // Dispose EventGate (clear debounce timers)
     this.eventGate?.dispose();
+    this.livenessWatchdog?.stop();
 
     // Stop modules and MCPL servers in parallel
     const shutdownPromises: Promise<void>[] = [this.moduleRegistry.stopAll()];
@@ -486,8 +589,15 @@ export class AgentFramework {
   /**
    * Add a trace event listener for observability.
    */
-  onTrace(listener: TraceEventListener): void {
+  onTrace(listener: TraceEventListener): () => void {
     this.traceListeners.push(listener);
+    // Return an unsubscribe so callers with a bounded lifetime (e.g. modules
+    // that get torn down and recreated on session switch) don't leak
+    // listeners. Existing callers that ignore the return value are unaffected.
+    return () => {
+      const idx = this.traceListeners.indexOf(listener);
+      if (idx >= 0) this.traceListeners.splice(idx, 1);
+    };
   }
 
   /**
@@ -540,6 +650,14 @@ export class AgentFramework {
     return Array.from(this.agents.values());
   }
 
+  /**
+   * Get the per-channel conversation router (null unless config.conversations
+   * was set). Exposed for modules/UIs that surface active engagements.
+   */
+  getConversationRouter(): ConversationRouter | null {
+    return this.conversationRouter;
+  }
+
   /**
    * Abort an in-flight inference for an agent.
    */
@@ -568,13 +686,93 @@ export class AgentFramework {
   getAllTools(): import('./types/index.js').ToolDefinition[] {
     const moduleTools = this.moduleRegistry.getAllTools();
     const channelTools = this.channelRegistry?.getChannelTools() ?? [];
-    const gateTools = this.eventGate ? [this.eventGate.getToolDefinition()] : [];
+    const gateTools = this.eventGate
+      ? [
+          this.eventGate.getToolDefinition(),
+          ...AgentFramework.SLEEP_TOOLS,
+          ...AgentFramework.WAKE_RULE_TOOLS,
+          AgentFramework.EVENT_TAGS_TOOL,
+        ]
+      : [];
     if (this.mcplTools.length === 0 && channelTools.length === 0 && gateTools.length === 0) {
       return moduleTools;
     }
     return [...moduleTools, ...this.mcplTools, ...channelTools, ...gateTools];
   }
 
+  /**
+   * Build the membrane-normalized request that WOULD be emitted if `agentName`
+   * were activated right now — WITHOUT running inference, opening a stream, or
+   * mutating agent state. Intended for debug/preview tooling.
+   *
+   * Transparency contract (default): the preview is side-effect-free and
+   * leaves no trace on the system. It does only read-only work —
+   * `ContextManager.compile` (which never triggers compression itself;
+   * compression runs in the background out-of-band), tool filtering, and
+   * system-prompt assembly — then delegates to `Agent.buildActivationRequest`.
+   * No tokens are spent, nothing is written to Chronicle, and no external
+   * MCPL server is contacted.
+   *
+   * The trade-off is fidelity: the dynamically-gathered ContextInjection[]
+   * (module `gatherContext` + MCPL `beforeInference` hooks) are NOT included
+   * by default, because gathering them is not transparent —
+   *   - module `gatherContext` can run inference (e.g. RetrievalModule makes
+   *     Haiku calls — real token cost and latency), and
+   *   - MCPL `beforeInference` hooks are arbitrary RPCs to external servers
+   *     with side effects, and a preview never sends the paired
+   *     `afterInference`, which can leave a stateful server half-open.
+   *
+   * Pass `{ injections: true }` to opt into full-fidelity gathering and accept
+   * those side effects (byte-faithful to a real activation's injected context).
+   */
+  async previewActivation(
+    agentName: string,
+    opts?: { injections?: boolean }
+  ): Promise<NormalizedRequest> {
+    const agent = this.agents.get(agentName);
+    if (!agent) {
+      throw new Error(`Agent not found: ${agentName}`);
+    }
+
+    const tools = this.getAllTools().filter((t) => agent.canUseTool(t.name));
+
+    // 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);
+    }
+
+    // Full-fidelity path: mirrors startAgentStream's injection gathering.
+    // NOT transparent — see the doc comment above.
+    let injections: ContextInjection[] | undefined;
+
+    // Module gatherContext (fail-open, matches startAgentStream)
+    try {
+      const moduleInjections = await this.moduleRegistry.gatherContext(agentName);
+      if (moduleInjections.length > 0) {
+        injections = moduleInjections;
+      }
+    } catch (error) {
+      console.error('Module gatherContext error (preview):', error);
+    }
+
+    // MCPL beforeInference hooks (fail-open). Note: the paired afterInference
+    // is intentionally never sent here — this is a preview, not a real turn.
+    if (this.hookOrchestrator) {
+      try {
+        const hookParams = this.buildBeforeInferenceParams(agent);
+        const hookInjections = await this.hookOrchestrator.beforeInference(hookParams);
+        if (hookInjections.length > 0) {
+          injections = injections ? [...injections, ...hookInjections] : hookInjections;
+        }
+      } catch (error) {
+        console.error('beforeInference hook error (preview):', error);
+      }
+    }
+
+    return agent.buildActivationRequest(tools, injections);
+  }
+
   /**
    * Check if process logging is enabled.
    */
@@ -599,6 +797,45 @@ export class AgentFramework {
     return this.moduleRegistry.getModule(name);
   }
 
+  // =========================================================================
+  // Wake-rule surface (gate policy mutation) — backs wake_add_rule /
+  // wake_remove_rule and lets host modules compose higher-level wake modes
+  // (e.g. an "every-message-debounced" channel mode) without reaching into
+  // the private EventGate.
+  // =========================================================================
+
+  /**
+   * Add or replace (upsert) a gate policy at runtime. Validated and persisted
+   * to gate.json; hot-applied in memory. Throws if no gate is configured or the
+   * policy is invalid. `position: 'prepend'` puts a wake rule ahead of broad
+   * defer/debounce rules (first match wins).
+   */
+  addGatePolicy(
+    rawPolicy: unknown,
+    options?: { position?: 'append' | 'prepend' },
+  ): import('./gate/types.js').GatePolicy {
+    if (!this.eventGate) {
+      throw new Error('No EventGate configured (FrameworkConfig.gate is unset).');
+    }
+    return this.eventGate.addPolicy(rawPolicy, options);
+  }
+
+  /**
+   * Remove a gate policy by name at runtime. Returns false if it didn't exist.
+   * Throws if no gate is configured.
+   */
+  removeGatePolicy(name: string): boolean {
+    if (!this.eventGate) {
+      throw new Error('No EventGate configured (FrameworkConfig.gate is unset).');
+    }
+    return this.eventGate.removePolicy(name);
+  }
+
+  /** Current gate policy names (freshest on-disk view). Empty when no gate. */
+  getGatePolicyNames(): string[] {
+    return this.eventGate?.listPolicyNames() ?? [];
+  }
+
   /**
    * Get the Membrane instance.
    */
@@ -840,6 +1077,461 @@ export class AgentFramework {
    * Query inference logs.
    * Returns entries with summary info (doesn't resolve blobs).
    */
+  /** Synthesized sleep/wake tool definitions (present when a gate is wired). */
+  private static readonly SLEEP_TOOLS: import('./types/index.js').ToolDefinition[] = [
+    {
+      name: 'sleep',
+      description:
+        'Go quiet: suppress external pings and wakes for a number of seconds. ' +
+        'Messages still accumulate in your context — you just won’t be woken to ' +
+        'respond to them until the window passes. Your heartbeat still beats: you’ll ' +
+        'briefly rouse on each tick and can keep resting or call `wake` to get up early. ' +
+        'Privileged users can also still reach you. By default announces in your current channel.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          seconds: { type: 'number', description: 'How long to stay asleep, in seconds.' },
+          announce: {
+            type: 'boolean',
+            description: 'Announce the sleep in the current sticky channel (default true).',
+          },
+          message: {
+            type: 'string',
+            description: 'Optional custom announcement text (overrides the default).',
+          },
+        },
+        required: ['seconds'],
+      },
+    },
+    {
+      name: 'wake',
+      description: 'End your current sleep early, resuming normal wakes immediately.',
+      inputSchema: { type: 'object' },
+    },
+  ];
+
+  /** Synthesized wake-rule tools: add/remove a gate.json policy at runtime.
+   *  Present when a gate is wired. They write validated policies into the
+   *  hot-reloaded gate.json (same validation as load), so a rule takes effect
+   *  immediately and survives restart. */
+  private static readonly WAKE_RULE_TOOLS: import('./types/index.js').ToolDefinition[] = [
+    {
+      name: 'wake_add_rule',
+      description:
+        'Add or replace a wake rule (a gate.json policy) at runtime — no need to ' +
+        'hand-edit the file. The rule is validated and hot-applied immediately. ' +
+        'A rule with the same `name` replaces the existing one in place. Use ' +
+        '`position: "prepend"` to put a wake rule ahead of broad defer/debounce ' +
+        'rules (first match wins). Two common shapes:\n' +
+        '• Watch a FILE/workspace path: match on `mount` + `pathGlob`, e.g. ' +
+        '`{ name: "watch-notes", match: { scope: ["workspace:modified"], mount: "project", pathGlob: "notes/*.md" }, behavior: "always" }`.\n' +
+        '• Watch a CHANNEL: match on `source` + `channel` (and/or `tagsAny: ["chat:ambient"]`), ' +
+        'e.g. `{ name: "watch-cairn", match: { source: "discord", channel: "discord:*:12345", tagsAny: ["chat:ambient"] }, behavior: { debounce: 60000 } }` ' +
+        '(the channel must be subscribed for ambient events to arrive — see channel mode).',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          name: { type: 'string', description: 'Unique rule name. Reusing a name replaces that rule.' },
+          match: {
+            type: 'object',
+            description: 'Match criteria (all AND together). Omitted fields match anything.',
+            properties: {
+              scope: { type: 'array', items: { type: 'string' }, description: 'Event types, e.g. ["mcpl:channel-incoming","workspace:modified"].' },
+              source: { type: 'string', description: 'Integration/serverId, glob ok (e.g. "discord").' },
+              channel: { type: 'string', description: 'Channel id, glob ok (e.g. "discord:*:12345").' },
+              mount: { type: 'string', description: 'Workspace mount name, glob ok (workspace:* events).' },
+              pathGlob: { type: 'string', description: 'Glob over touched paths (workspace:* events).' },
+              tagsAny: { type: 'array', items: { type: 'string' }, description: 'Match if ANY tag matches (globs ok).' },
+              tagsAll: { type: 'array', items: { type: 'string' }, description: 'Match only if EVERY tag matches.' },
+              tagsNone: { type: 'array', items: { type: 'string' }, description: 'Match only if NONE match.' },
+              metadataTrue: { type: 'array', items: { type: 'string' }, description: 'Match if ANY listed metadata field is truthy.' },
+              filter: {
+                type: 'object',
+                description: 'Content filter.',
+                properties: {
+                  type: { type: 'string', enum: ['text', 'regex'] },
+                  pattern: { type: 'string' },
+                },
+                required: ['type', 'pattern'],
+              },
+            },
+          },
+          behavior: {
+            type: 'string',
+            enum: ['always', 'defer', 'skip'],
+            description:
+              'Simple behavior: "always" (wake now) or "defer" (don\'t wake; still enters ' +
+              'context). For debounce / rate-limit / sampling, use debounceMs / rateLimit / ' +
+              'passiveSample below instead of this field. Exactly one behavior must be given.',
+          },
+          debounceMs: {
+            type: 'number',
+            description: 'Shorthand for { debounce: ms }: wake once after ms of quiet (100–300000).',
+          },
+          rateLimit: {
+            type: 'object',
+            description: 'Token-bucket wake: at most `tokens` wakes per window; refills one per refillIntervalMs.',
+            properties: {
+              tokens: { type: 'number', description: 'Bucket capacity (> 0).' },
+              refillIntervalMs: { type: 'number', description: 'Ms between token refills (> 0).' },
+              keyBy: { type: 'string', description: 'Metadata field to partition buckets by (e.g. "channelId").' },
+            },
+            required: ['tokens', 'refillIntervalMs'],
+          },
+          passiveSample: {
+            type: 'object',
+            description: 'Wake every Nth matching event.',
+            properties: {
+              every: { type: 'number', description: 'Fire every N matches (positive integer).' },
+              keyBy: { type: 'string', description: 'Metadata field for separate per-key counters.' },
+            },
+            required: ['every'],
+          },
+          position: {
+            type: 'string',
+            enum: ['append', 'prepend'],
+            description: 'Where to insert a NEW rule (ignored when replacing by name). Default "append".',
+          },
+          resets: {
+            type: 'array',
+            items: { type: 'string' },
+            description: 'Names of other rules whose runtime state to clear when this rule fires.',
+          },
+        },
+        required: ['name'],
+      },
+    },
+    {
+      name: 'wake_remove_rule',
+      description:
+        'Remove a wake rule (gate.json policy) by name at runtime. Any pending ' +
+        'debounce batch for that rule is delivered first. Returns whether a rule ' +
+        'was removed (false if no rule had that name).',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          name: { type: 'string', description: 'The rule name to remove.' },
+        },
+        required: ['name'],
+      },
+    },
+  ];
+
+  /** Discoverability for event tags (MCPL RFC-001): the reserved chat:* core,
+   *  each connected server's declared tag ontology, and gate.js status. */
+  private static readonly EVENT_TAGS_TOOL: import('./types/index.js').ToolDefinition = {
+    name: 'event_tags',
+    description:
+      'List the event tags available for gating: the reserved cross-platform ' +
+      'chat:* core, each connected server\'s declared tag ontology (descriptions, ' +
+      'implications, suggested treatments), and the status of your programmable ' +
+      'gate (gate.js). Use these tag names in gate.json policies (tagsAny / ' +
+      'tagsAll / tagsNone) or in gate.js.',
+    inputSchema: { type: 'object' },
+  };
+
+  /** Reserved chat:* core vocabulary (MCPL RFC-001 §4) — short descriptions so
+   *  the agent can author rules without reading the spec. */
+  private static readonly CHAT_CORE_TAGS: Record<string, string> = {
+    'chat:addressed': 'Directed at you (umbrella: dm/mention/reply)',
+    'chat:mention': 'You were explicitly @-mentioned',
+    'chat:reply': 'A reply to your own message',
+    'chat:dm': 'A direct/private message to you',
+    'chat:ambient': 'Overheard in a followed channel; not addressed',
+    'chat:broadcast': 'Channel-wide ping (@everyone / channel post)',
+    'chat:to-self': 'Acts on your own content (reaction/reply to you)',
+    'chat:from-human': 'Authored by a human',
+    'chat:from-bot': 'Authored by a bot/automation',
+    'chat:from-self': 'Your own message, echoed back',
+    'chat:from-agent': 'Authored by another persona/agent',
+    'chat:edited': 'An edit of an existing message',
+    'chat:deleted': 'A deletion',
+    'chat:reaction': 'An emoji reaction was added',
+    'chat:reaction-remove': 'A reaction was removed',
+    'chat:has-image': 'Has an image attachment',
+    'chat:has-audio': 'Has an audio attachment',
+    'chat:has-file': 'Has a file attachment',
+    'chat:has-link': 'Contains a link',
+    'chat:command': 'A slash/bot command invocation',
+    'chat:private': 'Private conversation',
+    'chat:group': 'Group (multi-party) conversation',
+    'chat:thread': 'Occurred in a thread',
+  };
+
+  /** Refusal category → Discord reaction emoji. Unknown categories get 🛑. */
+  private static readonly REFUSAL_REACTIONS: Record<string, string> = {
+    bio: '☣️',
+    chem: '🧪',
+    nuclear: '☢️',
+    cyber: '💻',
+    reasoning_extraction: '🧠',
+  };
+
+  /**
+   * Mark an inference refusal visibly: react on the message that holds the
+   * conversational locus (the most recent incoming channel message) with a
+   * category-specific emoji. Best-effort — failures are logged, never thrown,
+   * and non-Discord loci are silently skipped.
+   */
+  private async reactToRefusal(agentName: string, category: string): Promise<void> {
+    try {
+      const incoming = this.channelRegistry?.buildChannelContext()?.incoming;
+      if (!incoming) return;
+      // incoming.channelId is the MCPL composite id ("discord:<guild>:<channel>");
+      // the reaction tool wants the raw Discord channel (or thread) id — the
+      // last segment.
+      const parts = incoming.channelId.split(':');
+      if (parts[0] !== 'discord') return;
+      const channelId = parts[parts.length - 1];
+      const emoji = AgentFramework.REFUSAL_REACTIONS[category] ?? '🛑';
+      // Resolve the MCPL server that owns the locus channel and call
+      // tools/call directly on its connection (bare tool name — no prefix
+      // games), bypassing the agent event queue so no synthetic tool-result
+      // is injected into a turn the agent never took.
+      const serverId = this.channelRegistry?.getChannelServerId(incoming.channelId);
+      const server = serverId ? this.mcplServerRegistry?.getServer(serverId) : null;
+      if (!server) {
+        console.error(
+          `[inference-refusal] reaction skipped: no MCPL server for locus "${incoming.channelId}" (agent=${agentName})`,
+        );
+        return;
+      }
+      await server.sendToolsCall('add_reaction', {
+        channelId,
+        messageId: incoming.messageId,
+        emoji,
+      });
+    } catch (err) {
+      console.error(
+        '[inference-refusal] reaction failed:',
+        err instanceof Error ? err.message : err,
+      );
+    }
+  }
+
+  /**
+   * Handle a `host/command` request from an MCPL surface server (e.g. a
+   * Discord slash command). Currently supports:
+   *
+   *   undo — revert the last N inference turns (branch-based, see
+   *   `undoLastTurn`). The response includes the last message the agent
+   *   would see in its context after the undo, obtained via the transparent
+   *   `previewActivation` render (no inference, no Chronicle writes).
+   */
+  private async handleHostCommand(
+    serverId: string,
+    params: HostCommandParams,
+  ): Promise<{
+    ok: boolean;
+    error?: string;
+    undone?: number;
+    requested?: number;
+    messagesRemoved?: number;
+    hidden?: number;
+    /** For `hide`: the Discord (channelId, messageId) of each removed message
+     *  that carried one — so the surface can mark them with a reaction. */
+    hiddenRefs?: Array<{ channelId: string; messageId: string }>;
+    lastVisible?: { participant?: string; role?: string; preview?: string } | null;
+  }> {
+    if (params.command !== 'undo' && params.command !== 'hide') {
+      return { ok: false, error: `Unknown host command: ${String(params.command)}` };
+    }
+
+    const agentName = params.agentName ?? [...this.agents.keys()][0];
+    if (!agentName || !this.agents.has(agentName)) {
+      return { ok: false, error: `Unknown agent: ${String(agentName)}` };
+    }
+
+    // hide: redact a single message (or an inclusive range) from the active
+    // branch, addressed by Discord message id. Unlike undo this is a
+    // removal-in-place (chronicle redact), not a branch rewind.
+    if (params.command === 'hide') {
+      const agent = this.agents.get(agentName)!;
+      if (agent.state.status !== 'idle') {
+        return { ok: false, error: `Cannot hide while agent is ${agent.state.status}` };
+      }
+      if (!params.fromMessageId) {
+        return { ok: false, error: 'hide: fromMessageId is required' };
+      }
+      const cm = agent.getContextManager();
+      const all = cm.getAllMessages();
+      const byDiscordId = (did: string) =>
+        all.findIndex((m) => String((m.metadata as { messageId?: unknown } | undefined)?.messageId) === String(did));
+
+      // Collect Discord refs of every message in [lo, hi] that carries one,
+      // so the surface can mark them. channelId here is whatever the ingest
+      // path stored (raw id or "discord:guild:channel"); the surface
+      // normalizes it.
+      const refsIn = (lo: number, hi: number) => {
+        const refs: Array<{ channelId: string; messageId: string }> = [];
+        for (let i = lo; i <= hi; i++) {
+          const md = all[i].metadata as { messageId?: unknown; channelId?: unknown } | undefined;
+          if (md?.messageId && md?.channelId) {
+            refs.push({ channelId: String(md.channelId), messageId: String(md.messageId) });
+          }
+        }
+        return refs;
+      };
+
+      const fromIdx = byDiscordId(params.fromMessageId);
+      if (fromIdx < 0) {
+        return {
+          ok: false,
+          error: `Message ${params.fromMessageId} is not an addressable message in context (it may only exist inside backscroll text, or predates this session).`,
+        };
+      }
+
+      try {
+        if (params.toMessageId) {
+          const toIdx = byDiscordId(params.toMessageId);
+          if (toIdx < 0) {
+            return { ok: false, error: `Message ${params.toMessageId} is not an addressable message in context.` };
+          }
+          const [lo, hi] = fromIdx <= toIdx ? [fromIdx, toIdx] : [toIdx, fromIdx];
+          const refs = refsIn(lo, hi);
+          cm.removeMessages(all[lo].id, all[hi].id);
+          console.error(
+            `[host-command] hide agent=${agentName} range removed=${hi - lo + 1} ` +
+              `(${params.fromMessageId}..${params.toMessageId}) by=${params.requesterName ?? params.requesterId ?? 'unknown'} (server=${serverId})`,
+          );
+          return {
+            ok: true,
+            hidden: hi - lo + 1,
+            hiddenRefs: refs,
+            lastVisible: await this.lastVisiblePreview(agentName),
+          };
+        }
+        const refs = refsIn(fromIdx, fromIdx);
+        cm.removeMessage(all[fromIdx].id);
+        console.error(
+          `[host-command] hide agent=${agentName} removed=1 (${params.fromMessageId}) ` +
+            `by=${params.requesterName ?? params.requesterId ?? 'unknown'} (server=${serverId})`,
+        );
+        return {
+          ok: true,
+          hidden: 1,
+          hiddenRefs: refs,
+          lastVisible: await this.lastVisiblePreview(agentName),
+        };
+      } catch (error) {
+        return { ok: false, error: error instanceof Error ? error.message : String(error) };
+      }
+    }
+
+    // Message-granular mode: branch the chronicle at the message that should
+    // become the new tail (ContextManager.branchAt — origin-sequence-based
+    // time-travel branching; see chronicle's rfc-state-item-origins addendum).
+    // No turn checkpoints involved, so this reaches past turn boundaries.
+    if (typeof params.messages === 'number' && params.messages > 0) {
+      const agent = this.agents.get(agentName)!;
+      if (agent.state.status !== 'idle') {
+        return { ok: false, error: `Cannot undo while agent is ${agent.state.status}` };
+      }
+      const n = Math.max(1, Math.min(50, Math.floor(params.messages)));
+      const cm = agent.getContextManager();
+      const allMessages = cm.getAllMessages();
+      if (n >= allMessages.length) {
+        return {
+          ok: false,
+          error: `Cannot remove ${n} message(s) — history has ${allMessages.length}; at least one must remain.`,
+        };
+      }
+      const target = allMessages[allMessages.length - 1 - n];
+      const branchName = cm.branchAt(target.id, `undo-msgs/${agentName}/${Date.now()}`);
+      await cm.switchBranch(branchName);
+
+      // Materialize config files from the new branch (fire-and-forget; gate
+      // picks up via mtime) — mirrors undoLastTurn.
+      const wsUndo = this.moduleRegistry.getModule('workspace');
+      if (wsUndo && 'materializeMount' in wsUndo) {
+        (wsUndo as { materializeMount: (m: string) => Promise<void> })
+          .materializeMount('_config')
+          .catch(() => {});
+      }
+
+      console.error(
+        `[host-command] undo-messages agent=${agentName} removed=${n} branch=${branchName}` +
+          ` by=${params.requesterName ?? params.requesterId ?? 'unknown'} (server=${serverId})`,
+      );
+
+      return {
+        ok: true,
+        messagesRemoved: n,
+        lastVisible: await this.lastVisiblePreview(agentName),
+      };
+    }
+
+    const requested = Math.max(1, Math.min(20, Math.floor(params.turns ?? 1)));
+    let undone = 0;
+    try {
+      for (let i = 0; i < requested; i++) {
+        const r = this.undoLastTurn(agentName);
+        if (!r.undone) break;
+        undone++;
+      }
+    } catch (error) {
+      // e.g. "Cannot undo while agent is streaming" — report what happened,
+      // including any turns already undone before the failure.
+      const msg = error instanceof Error ? error.message : String(error);
+      if (undone === 0) return { ok: false, error: msg };
+      console.error(`[host-command] undo partially failed after ${undone}/${requested}: ${msg}`);
+    }
+
+    console.error(
+      `[host-command] undo agent=${agentName} requested=${requested} undone=${undone}` +
+        ` by=${params.requesterName ?? params.requesterId ?? 'unknown'} (server=${serverId})`,
+    );
+
+    if (undone === 0) {
+      return { ok: true, undone: 0, requested, lastVisible: null };
+    }
+
+    return { ok: true, undone, requested, lastVisible: await this.lastVisiblePreview(agentName) };
+  }
+
+  /**
+   * The last message the agent would see in its context right now, via the
+   * transparent `previewActivation` render (no inference, no Chronicle
+   * writes). Returns null if the preview fails or the context is empty.
+   */
+  private async lastVisiblePreview(
+    agentName: string,
+  ): Promise<{ participant?: string; role?: string; preview?: string } | null> {
+    try {
+      const preview = await this.previewActivation(agentName);
+      const messages = (preview as { messages?: unknown[] }).messages ?? [];
+      const last = messages[messages.length - 1] as
+        | { role?: string; participant?: string; content?: unknown }
+        | undefined;
+      if (!last) return null;
+      const blocks = Array.isArray(last.content) ? last.content : [];
+      const text = blocks
+        .map((b) => (b && typeof b === 'object' && 'text' in b ? String((b as { text: unknown }).text) : ''))
+        .join(' ')
+        .trim();
+      // Surface-injected preambles (<system>…</system>, <backscroll>…
+      // </backscroll>) can dominate the head of a bundled incoming message
+      // and bury the actual conversational line. Strip them for the
+      // preview; fall back to the raw text if nothing else remains.
+      const stripped = text
+        .replace(/<system>[\s\S]*?<\/system>/g, '')
+        .replace(/<backscroll\b[\s\S]*?<\/backscroll>/g, '')
+        .trim();
+      const body = stripped.length > 0 ? stripped : text;
+      return {
+        participant: last.participant,
+        role: last.role,
+        preview: body.length > 400 ? `${body.slice(0, 400)}…` : body,
+      };
+    } catch (error) {
+      console.error(
+        '[host-command] post-undo context preview failed:',
+        error instanceof Error ? error.message : error,
+      );
+      return null;
+    }
+  }
+
   queryInferenceLogs(query?: InferenceLogQuery): InferenceLogQueryResult {
     const limit = query?.limit ?? 50;
     const offset = query?.offset ?? 0;
@@ -1307,6 +1999,7 @@ export class AgentFramework {
 
     const agent = new Agent(config, contextManager, this.membrane);
     this.agents.set(config.name, agent);
+    this.agentConfigs.set(config.name, config);
 
     // First non-ephemeral agent becomes the primary for message routing
     if (!this.primaryAgentName) {
@@ -1334,6 +2027,9 @@ export class AgentFramework {
       await this.handleProcessEvent(event);
     }
 
+    // Close idle conversation forks (no-op unless conversations configured)
+    this.sweepExpiredConversations();
+
     // Check for inference requests
     await this.processInferenceRequests();
 
@@ -1392,25 +2088,18 @@ export class AgentFramework {
           // Compute truncation limit from agent's strategy (maxMessageTokens * 4 chars)
           const maxChars = this.getMaxToolResultChars(agent);
 
-          // Store tool results as a user message (tool_result blocks)
-          const toolResultContent: ContentBlock[] = currentState.toolResults.map(tc => {
-            let content: string;
-            if (tc.result.isError) {
-              content = tc.result.error ?? 'Unknown error';
-            } else {
-              content = JSON.stringify(tc.result.data);
-              if (maxChars && content.length > maxChars) {
-                content = safeSlice(content, 0, maxChars)
-                  + '\n\n[truncated — original was ' + content.length + ' chars]';
-              }
-            }
-            return {
-              type: 'tool_result' as const,
-              toolUseId: tc.id,
-              content,
-              isError: tc.result.isError,
-            };
-          });
+          // Store tool results as a user message (tool_result blocks).
+          // Use the history serializer so MCP image blocks become a short
+          // `[image: type, size]` placeholder instead of megabytes of base64
+          // that would corrupt under truncation.
+          const toolResultContent: ContentBlock[] = currentState.toolResults.map(tc => ({
+            type: 'tool_result' as const,
+            toolUseId: tc.id,
+            content: tc.result.isError
+              ? tc.result.error ?? 'Unknown error'
+              : toolResultDataToHistoryString(tc.result.data, maxChars),
+            isError: tc.result.isError,
+          }));
           agent.getContextManager().addMessage('user', toolResultContent);
 
           // Flush any messages that were deferred while waiting for tool results.
@@ -1482,7 +2171,7 @@ export class AgentFramework {
     // These events are protocol-level (spec Sections 9 & 14) and always
     // represent content intended for the model's context window.
     if (event.type === 'mcpl:channel-incoming') {
-      this.handleMcplChannelIncoming(event as unknown as {
+      await this.handleMcplChannelIncoming(event as unknown as {
         type: 'mcpl:channel-incoming';
         serverId: string;
         channelId: string;
@@ -1578,9 +2267,11 @@ export class AgentFramework {
         if (!decision.trigger) return;
       }
 
+      // Broadcast requests exclude conversation forks — they are driven by
+      // their own channel's messages, not by framework-wide events.
       const targetAgents =
         response.requestInference === true
-          ? Array.from(this.agents.keys())
+          ? Array.from(this.agents.keys()).filter((n) => !this.conversationAgentHomes.has(n))
           : response.requestInference;
 
       for (const agentName of targetAgents) {
@@ -1605,7 +2296,7 @@ export class AgentFramework {
    * Convert an incoming MCPL channel message to a context message.
    * This replaces the old MCPLModule.onProcess() message conversion.
    */
-  private handleMcplChannelIncoming(event: {
+  private async handleMcplChannelIncoming(event: {
     type: 'mcpl:channel-incoming';
     serverId: string;
     channelId: string;
@@ -1616,7 +2307,7 @@ export class AgentFramework {
     timestamp: string;
     metadata?: Record<string, unknown>;
     triggerInference?: boolean;
-  }): void {
+  }): Promise<void> {
     const metadata: Record<string, unknown> = {
       ...event.metadata,
       channelId: event.channelId,
@@ -1627,6 +2318,14 @@ export class AgentFramework {
     };
     if (event.threadId) metadata.threadId = event.threadId;
 
+    // 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.
+    if (this.conversationRouter) {
+      await this.routeConversationIncoming(event, metadata);
+      return;
+    }
+
     const id = this.addMessage('user', event.content, metadata);
     this.emitTrace({ type: 'message:added', messageId: id, source: 'mcpl:channel-incoming' });
 
@@ -1637,7 +2336,268 @@ export class AgentFramework {
           reason: 'mcpl:channel-incoming',
           source: event.serverId,
           timestamp: Date.now(),
+          // 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,
+        });
+      }
+    }
+  }
+
+  /**
+   * Route an incoming channel message through the ConversationRouter:
+   * deliver to the channel's bound fork agent, spawning it from the template
+   * agent first when the bind policy matches. Unrouted messages are dropped —
+   * the template ("trunk") is a dormant warm checkpoint, not a listener.
+   */
+  private async routeConversationIncoming(
+    event: {
+      serverId: string;
+      channelId: string;
+      messageId: string;
+      author: { id: string; name: string };
+      content: ContentBlock[];
+      metadata?: Record<string, unknown>;
+      triggerInference?: boolean;
+    },
+    messageMetadata: Record<string, unknown>,
+  ): Promise<void> {
+    const router = this.conversationRouter!;
+    const descriptor = this.channelRegistry?.getDescriptor(event.channelId);
+
+    const decision = router.route({
+      channelId: event.channelId,
+      mentioned: event.metadata?.mentioned === true,
+      kind: ConversationRouter.classifyChannel(descriptor, event.metadata),
+    });
+
+    if (decision.kind === 'unbound') {
+      this.emitTrace({
+        type: 'mcpl:conversation-unrouted',
+        channelId: event.channelId,
+        messageId: event.messageId,
+      });
+      return;
+    }
+
+    let agent: Agent | undefined;
+    if (decision.kind === 'spawn') {
+      try {
+        agent = await this.createConversationAgent(decision.agentName, event.channelId);
+        router.bind(event.channelId, decision.agentName, decision.generation);
+        this.persistConversationRouterState();
+        this.emitTrace({
+          type: 'mcpl:conversation-spawned',
+          channelId: event.channelId,
+          agentName: decision.agentName,
+          generation: decision.generation,
+          template: router.templateAgent,
+        });
+      } catch (error) {
+        const err = error instanceof Error ? error : new Error(String(error));
+        console.error(`Failed to spawn conversation agent for ${event.channelId}:`, err);
+        this.emitTrace({
+          type: 'mcpl:conversation-spawn-failed',
+          channelId: event.channelId,
+          agentName: decision.agentName,
+          error: err.message,
         });
+        return; // next qualifying message proposes the same spawn again
+      }
+    } else {
+      agent = this.agents.get(decision.agentName);
+      if (!agent) {
+        // Bound agent vanished (e.g. external reset) — unbind so the next
+        // qualifying message respawns a fresh fork.
+        router.unbind(event.channelId);
+        this.emitTrace({
+          type: 'mcpl:conversation-binding-orphaned',
+          channelId: event.channelId,
+          agentName: decision.agentName,
+        });
+        return;
+      }
+    }
+
+    // Respect an explicit server-config-level veto (shouldTriggerInference)
+    // on top of the router's own trigger policy.
+    const trigger = decision.trigger && event.triggerInference !== false;
+    messageMetadata.triggered = trigger;
+
+    const id = agent.getContextManager().addMessage('user', event.content, messageMetadata);
+    this.emitTrace({ type: 'message:added', messageId: id, source: 'mcpl:channel-incoming' });
+
+    if (trigger) {
+      this.pendingRequests.push({
+        agentName: agent.name,
+        reason: 'mcpl:channel-incoming',
+        source: event.serverId,
+        timestamp: Date.now(),
+        // 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,
+      });
+    }
+  }
+
+  /**
+   * Spawn a persistent per-channel conversation agent ("fork") from the
+   * template agent: own ContextManager under `conversations/{name}`, seeded
+   * with a copy of the template's compiled context (the SubagentModule
+   * wholesale-copy pattern), registered in the event loop like any agent —
+   * but never primary.
+   */
+  private async createConversationAgent(name: string, channelId: string): Promise<Agent> {
+    const router = this.conversationRouter!;
+    const templateConfig = this.agentConfigs.get(router.templateAgent);
+    const template = this.agents.get(router.templateAgent);
+    if (!template || !templateConfig) {
+      throw new Error(`conversation template agent "${router.templateAgent}" not found`);
+    }
+
+    const contextManager = await ContextManager.open({
+      store: this.store,
+      namespace: `conversations/${name}`,
+      isolate: true,
+      // Strategy instances are stateful — never share the template's.
+      strategy: router.strategyFactory?.() ?? new PassthroughStrategy(),
+      membrane: this.membrane,
+      debugLogContext: !!process.env.DEBUG_CONTEXT,
+    });
+
+    // Seed with the template's compiled context, renaming the template
+    // participant so the fork reads its inheritance as its own history.
+    // Guard: only seed a genuinely fresh namespace. Generation counters are
+    // persisted precisely so names aren't reused, but if this namespace has
+    // history anyway (counter state lost, crash between spawn and persist),
+    // seeding again would stack another template copy on top of it.
+    const { messages: existing } = await contextManager.compile();
+    if (existing.length === 0) {
+      const { messages: compiled } = await template.getContextManager().compile();
+      for (const msg of compiled) {
+        const participant = msg.participant === template.name ? name : msg.participant;
+        contextManager.addMessage(participant, msg.content);
+      }
+    }
+
+    const config: AgentConfig = { ...templateConfig, name, strategy: undefined };
+    const agent = new Agent(config, contextManager, this.membrane);
+    this.agents.set(name, agent);
+    this.agentConfigs.set(name, config);
+    this.conversationAgentHomes.set(name, channelId);
+    return agent;
+  }
+
+  /** Persist the router's generation counters (see hydration in create()). */
+  private persistConversationRouterState(): void {
+    if (!this.conversationRouter) return;
+    try {
+      this.store.setStateJson(CONVERSATION_ROUTER_STATE_ID, {
+        generations: this.conversationRouter.exportGenerations(),
+      });
+    } catch (error) {
+      console.error('Failed to persist conversation router state:', error);
+    }
+  }
+
+  /**
+   * Remove a closed conversation fork from the framework: its closure turn
+   * has finished, so the home mapping has served its purpose and keeping the
+   * agent registered would just grow every agent scan and broadcast filter
+   * forever. The fork's context stays in Chronicle for investigation.
+   */
+  private disposeConversationAgent(agentName: string): void {
+    this.closingConversationAgents.delete(agentName);
+    const channelId = this.conversationAgentHomes.get(agentName);
+    this.agents.delete(agentName);
+    this.agentConfigs.delete(agentName);
+    this.conversationAgentHomes.delete(agentName);
+    this.emitTrace({
+      type: 'mcpl:conversation-disposed',
+      agentName,
+      channelId,
+    });
+  }
+
+  /**
+   * Scope MCPL context injections for a conversation-bound agent: drop
+   * injections that are another open channel's context (injection namespace
+   * = channelId by adapter convention), keep its own channel and anything
+   * that isn't channel context.
+   */
+  private scopeInjectionsForAgent(
+    agentName: string,
+    injections: ContextInjection[],
+  ): ContextInjection[] {
+    const home = this.conversationAgentHomes.get(agentName);
+    if (!home || !this.channelRegistry || injections.length === 0) {
+      return injections;
+    }
+    const openChannelIds = new Set(
+      this.channelRegistry.getOpenChannels().map((e) => e.descriptor.id),
+    );
+    return injections.filter((inj) => {
+      const ns = inj.namespace;
+      if (!ns || !openChannelIds.has(ns)) return true;
+      return ns === home;
+    });
+  }
+
+  /**
+   * Idle-TTL sweep for conversation bindings (runs at most once per minute
+   * from the event loop). Expired forks get a final system-initiated closure
+   * turn — publish scoping still works because the agent's home channel
+   * mapping is permanent — and the channel unbinds immediately, so the next
+   * qualifying message spawns a fresh fork from the current template.
+   */
+  private sweepExpiredConversations(): void {
+    if (!this.conversationRouter) return;
+    const now = Date.now();
+    if (now - this.lastConversationSweep < 60_000) return;
+    this.lastConversationSweep = now;
+
+    for (const binding of this.conversationRouter.expired(now)) {
+      this.conversationRouter.unbind(binding.channelId);
+      this.emitTrace({
+        type: 'mcpl:conversation-closed',
+        channelId: binding.channelId,
+        agentName: binding.agentName,
+        reason: 'idle-ttl',
+      });
+
+      const agent = this.agents.get(binding.agentName);
+      if (!agent) {
+        // Agent vanished (external reset) — nothing to close, just make sure
+        // its bookkeeping doesn't linger.
+        this.agentConfigs.delete(binding.agentName);
+        this.conversationAgentHomes.delete(binding.agentName);
+        continue;
+      }
+      agent.getContextManager().addMessage(
+        'user',
+        [{ type: 'text', text: this.conversationRouter.closurePrompt }],
+        { channelId: binding.channelId, conversationClosure: true },
+      );
+      this.pendingRequests.push({
+        agentName: binding.agentName,
+        reason: 'conversation:closure',
+        source: 'framework',
+        timestamp: now,
+      });
+      // Disposed when the closure stream ends (driveStream finally), with
+      // the reaper below as fallback.
+      this.closingConversationAgents.add(binding.agentName);
+    }
+
+    // Fallback reaper: a closing fork whose closure inference never ran
+    // (request dropped as stale, inference policy veto) would otherwise stay
+    // registered forever. No active stream + no pending request = done.
+    for (const agentName of [...this.closingConversationAgents]) {
+      if (
+        !this.activeStreams.has(agentName) &&
+        !this.pendingRequests.some((r) => r.agentName === agentName)
+      ) {
+        this.disposeConversationAgent(agentName);
       }
     }
   }
@@ -1657,19 +2617,74 @@ export class AgentFramework {
     const id = this.addMessage('user', event.content, metadata);
     this.emitTrace({ type: 'message:added', messageId: id, source: 'mcpl:push-event' });
 
+    // Some push events carry a channel of origin (Discord DMs arrive here, not
+    // via channels/incoming, because discord-mcpl forwards them with the channel
+    // closed). Register + open that channel so routeSpeech can resolve it, and
+    // thread it onto the wake request so the reply routes back to it instead of
+    // the global locus (item-3 redux, DM sub-case).
+    const triggerChannel = this.derivePushEventChannel(event.origin);
+    if (triggerChannel && this.channelRegistry) {
+      this.channelRegistry.ensureChannelRegistered(
+        event.serverId,
+        triggerChannel.channelId,
+        triggerChannel.label,
+      );
+    }
+
     if (event.triggerInference) {
-      const targetAgents = event.targetAgents ?? [...this.agents.keys()];
+      // Default broadcast excludes conversation forks (channel-driven).
+      const targetAgents = event.targetAgents
+        ?? [...this.agents.keys()].filter((n) => !this.conversationAgentHomes.has(n));
       for (const agentName of targetAgents) {
         this.pendingRequests.push({
           agentName,
           reason: 'mcpl:push-event',
           source: event.serverId,
           timestamp: Date.now(),
+          channelId: triggerChannel?.channelId,
         });
       }
     }
   }
 
+  /**
+   * Derive the MCPL composite channel id (the outbound routing locus) for a
+   * push event from its server-defined `origin`, if it carries one.
+   *
+   * Discord DMs are the motivating case: discord-mcpl forwards them via
+   * push/event (the DM channel is closed), so they never pass through
+   * channels/incoming and their channel is never registered — leaving the
+   * agent's reply with nowhere to route (item-3 redux, DM sub-case). Prefers an
+   * explicit `origin.mcplChannelId` (a surface declaring its own composite id —
+   * the surface-agnostic contract); otherwise reconstructs the Discord form
+   * `discord:{guildId|dm}:{channelId}` from origin fields, matching
+   * discord-mcpl's `mcplChannelId()` / `parseMcplChannelId()` convention so the
+   * fix works even against a discord-mcpl build that predates `mcplChannelId`.
+   * Returns undefined for push events with no channel provenance (heartbeats,
+   * timers), which correctly keep the global fallback.
+   */
+  private derivePushEventChannel(
+    origin: Record<string, unknown> | undefined,
+  ): { channelId: string; label?: string } | undefined {
+    if (!origin) return undefined;
+    const label = typeof origin.channelName === 'string' ? origin.channelName : undefined;
+
+    const explicit = origin.mcplChannelId;
+    if (typeof explicit === 'string' && explicit) {
+      return { channelId: explicit, label };
+    }
+
+    // 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 undefined;
+  }
+
   private async processInferenceRequests(): Promise<void> {
     if (this.pendingRequests.length === 0) {
       return;
@@ -1730,7 +2745,19 @@ export class AgentFramework {
 
       // Start streaming inference (non-blocking — driveStream runs in background)
       const trigger = requests[0];
-      await this.startAgentStream(agent, trigger);
+      // 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,
+      );
+      await this.startAgentStream(agent, { ...trigger, channelId: triggerChannel });
     }
   }
 
@@ -1741,6 +2768,18 @@ export class AgentFramework {
       this.redoStacks.delete(agent.name); // new work invalidates redo
     }
 
+    // Establish this turn's outbound routing locus (item-3 redux). Set it to the
+    // triggering channel for a channel/DM-triggered turn; clear it otherwise so
+    // a heartbeat / no-trigger turn doesn't inherit a previous turn's channel and
+    // 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);
+    }
+
     this.emitTrace({ type: 'inference:started', agentName: agent.name });
     this.eventGate?.onInferenceStarted(agent.name);
 
@@ -1753,6 +2792,11 @@ export class AgentFramework {
       let injections: ContextInjection[] | undefined;
 
       // Module gatherContext (fail-open, 5s timeout per module)
+      // NOTE: module injections are NOT channel-scoped — only the MCPL hook
+      // injections below pass through scopeInjectionsForAgent (channel
+      // context arrives via beforeInference hooks by adapter convention). A
+      // module that starts emitting per-channel context must scope it per
+      // agent itself, or conversation forks will see cross-channel content.
       try {
         const moduleInjections = await this.moduleRegistry.gatherContext(agent.name);
         if (moduleInjections.length > 0) {
@@ -1766,7 +2810,10 @@ export class AgentFramework {
       if (this.hookOrchestrator) {
         try {
           const hookParams = this.buildBeforeInferenceParams(agent, trigger);
-          const hookInjections = await this.hookOrchestrator.beforeInference(hookParams);
+          const hookInjections = this.scopeInjectionsForAgent(
+            agent.name,
+            await this.hookOrchestrator.beforeInference(hookParams),
+          );
           if (hookInjections.length > 0) {
             injections = injections ? [...injections, ...hookInjections] : hookInjections;
           }
@@ -1819,6 +2866,13 @@ export class AgentFramework {
     const myStreamId = agent.streamId;
     let hadToolCalls = 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.
+    const typingChannel = this.channelRegistry?.getDefaultPublishChannel();
+    if (typingChannel) this.channelRegistry!.startTyping(typingChannel);
+
     try {
       for await (const event of stream) {
         switch (event.type) {
@@ -1852,13 +2906,27 @@ export class AgentFramework {
               calls: event.calls.map((c) => ({ id: c.id, name: c.name, input: c.input })),
             });
 
-            // Build assistant content blocks from preamble text + tool_use blocks
-            const assistantBlocks: ContentBlock[] = [];
-            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> });
+            // Build assistant content blocks for this round. Prefer the
+            // membrane's verbatim round content (membrane ≥0.5.64): it
+            // preserves native thinking / redacted_thinking blocks with
+            // their signatures IN ORDER — the API requires signed thinking
+            // to precede its tool_use in the same assistant turn, so
+            // rebuilding from preamble + calls would break thinking+tools.
+            const roundContent = (event.context as { roundContent?: ContentBlock[] }).roundContent;
+            let assistantBlocks: ContentBlock[];
+            if (roundContent && roundContent.length > 0) {
+              assistantBlocks = roundContent.filter(
+                (b) => b.type !== 'tool_result'
+              );
+            } else {
+              // Fallback (older membrane / XML tool mode): preamble + calls
+              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> });
+              }
             }
             this.pendingAssistantBlocks.set(agent.name, assistantBlocks);
 
@@ -1909,7 +2977,9 @@ export class AgentFramework {
                 const toolResultContent: ContentBlock[] = readyState.toolResults.map(tc => ({
                   type: 'tool_result' as const,
                   toolUseId: tc.id,
-                  content: tc.result.isError ? (tc.result.error ?? 'Unknown error') : JSON.stringify(tc.result.data),
+                  content: tc.result.isError
+                    ? (tc.result.error ?? 'Unknown error')
+                    : toolResultDataToHistoryString(tc.result.data),
                   isError: tc.result.isError,
                 }));
                 agent.getContextManager().addMessage('user', toolResultContent);
@@ -1917,18 +2987,20 @@ export class AgentFramework {
             }
 
             // Add assistant response to context.
-            // If we had tool calls, the tool_use blocks were already stored as
-            // pendingAssistantBlocks and flushed when tool results arrived.
-            // Only store trailing content (text after the last tool round) to
-            // avoid double-storing tool_use blocks.
-            const hadToolCalls = response.content.some(
-              (b: ContentBlock) => b.type === 'tool_use' || b.type === 'tool_result'
+            // If we had tool calls, each round's blocks (thinking + text +
+            // tool_use) were already stored as pendingAssistantBlocks and
+            // flushed when tool results arrived. Only store TRAILING content
+            // — blocks after the last tool block. A type-based filter would
+            // double-store earlier rounds' text/thinking AND detach signed
+            // thinking blocks from their tool_use turn (the API requires
+            // thinking to precede tool_use in the same assistant turn).
+            const lastToolIdx = response.content.reduce(
+              (last: number, b: ContentBlock, i: number) =>
+                b.type === 'tool_use' || b.type === 'tool_result' ? i : last,
+              -1
             );
-            if (hadToolCalls) {
-              // Filter to only trailing text/thinking blocks (no tool_use — those are already stored)
-              const trailingContent = response.content.filter(
-                (block: ContentBlock) => block.type !== 'tool_use' && block.type !== 'tool_result'
-              );
+            if (lastToolIdx >= 0) {
+              const trailingContent = response.content.slice(lastToolIdx + 1);
               if (trailingContent.length > 0) {
                 agent.addAssistantResponse(trailingContent);
               }
@@ -2034,6 +3106,24 @@ export class AgentFramework {
               stopReason: response.stopReason,
             });
 
+            // Surface refusals instead of going silently mute: stderr line
+            // (headless inference failures are otherwise under-logged) + an
+            // emoji reaction on the triggering Discord message, keyed by the
+            // refusal category from stop_details.
+            if (response.stopReason === 'refusal') {
+              // stop_details lives on the raw PROVIDER response
+              // (response.raw is RawAccess = { request, response, headers }).
+              const stopDetails = (response.raw?.response as {
+                stop_details?: { category?: string; explanation?: string };
+              } | undefined)?.stop_details;
+              const category = stopDetails?.category ?? 'unknown';
+              console.error(
+                `[inference-refusal] agent=${agent.name} category=${category}` +
+                  (stopDetails?.explanation ? ` explanation=${stopDetails.explanation}` : ''),
+              );
+              void this.reactToRefusal(agent.name, category);
+            }
+
             // Dispatch speech (and thoughts if any)
             if (speechContent.length > 0 || thoughts.length > 0) {
               const speechContext: SpeechContext = {
@@ -2052,6 +3142,94 @@ export class AgentFramework {
               );
             }
 
+            // Host-owned output routing (see LOCUS-ROUTING-DESIGN). On a
+            // text-only turn (no tool calls => speechContent populated),
+            // publish the agent's speech to the conversational locus — the
+            // most recent incoming channel, tracked cross-surface in the
+            // ChannelRegistry. This replaces discord-mcpl's per-surface sticky
+            // auto-post. Tool-call turns produce `thoughts`, not `speech`, so
+            // they are never routed here — which is precisely how the `think`
+            // tool (and any explicit send tool) yields a silent turn.
+            if (speechContent.length > 0 && this.channelRegistry) {
+              const speechText = speechContent
+                .map((b) => (b as ContentBlock & { type: 'text' }).text)
+                .join('\n')
+                .trim();
+              if (speechText) {
+                try {
+                  await this.channelRegistry.routeSpeech(agent.name, speechText);
+                } catch (err) {
+                  console.error('speech routing failed:', err);
+                }
+              }
+            } else if (this.channelRegistry && hadToolCalls && allText.length > 0) {
+              // Tool-call turn that also produced prose. Per design, route the
+              // prose to the locus as a reply UNLESS the turn used an explicit
+              // send/publish tool (channel_publish, *--send_message,
+              // *--reply_message, *--send_dm) — already delivered, so routing
+              // again would double-post. `think` and other non-sending tools
+              // (shell, workspace, etc.) still let the agent speak in the same
+              // turn. The global speech/thoughts split is left untouched
+              // (module/TUI rendering unaffected) — this only governs what
+              // reaches the channel.
+              // Tools whose presence suppresses the trailing prose, for two
+              // distinct reasons:
+              //   - `skip_reply` — the agent EXPLICITLY chose not to reply this
+              //     turn (the deliberate "stay silent" signal).
+              //   - explicit delivery tools (channel_publish / *send_message /
+              //     *reply_message / *send_dm) — already sent the message, so
+              //     routing it again would double-post.
+              // `think` is deliberately NOT here: it is silent *reasoning*, but
+              // prose written after a think is the agent's actual reply and must
+              // be delivered. (A think-only turn has no trailing prose and stays
+              // silent via the `!t` check below.)
+              const SILENCING = new Set([
+                'skip_reply', 'channel_publish', 'send_message', 'reply_message', 'send_dm',
+              ]);
+              const bare = (n: string) => (n.includes('--') ? n.split('--').pop()! : n);
+              const toolNames = response.content
+                .filter((b) => b.type === 'tool_use')
+                .map((b) => (b as unknown as { name?: string }).name)
+                .filter((n): n is string => typeof n === 'string');
+              const silenced = toolNames.some((n) => SILENCING.has(bare(n)));
+
+              // Split the turn's content into ordered prose segments, broken at
+              // each tool_use / tool_result boundary. `response.content` holds the
+              // WHOLE turn's blocks in provider order — earlier tool rounds
+              // included (see the trailing-slice note above, which slices exactly
+              // because the full turn is present) — so a left-to-right walk
+              // reconstructs the emission order. Interleaved prose
+              // ("msgA → [tool] → msgB → [tool] → msgC") is then delivered as
+              // separate messages IN ORDER instead of being collapsed into one
+              // trailing post (item 4). The silencing rule stays turn-wide: an
+              // explicit send / skip suppresses ALL auto-routed prose this turn,
+              // preserving the double-post guard.
+              const segments = splitProseSegments(response.content);
+
+              if (silenced || segments.length === 0) {
+                console.error(
+                  `[routing] ${agent.name}: tool-call turn [${toolNames.join(', ') || 'none'}] -> NOT routed ` +
+                  `(${silenced ? 'silencing tool / explicit send' : 'no prose'})`,
+                );
+              } else {
+                console.error(
+                  `[routing] ${agent.name}: tool-call turn [${toolNames.join(', ')}] -> routing ${segments.length} prose segment(s) in order`,
+                );
+                // Deliver sequentially (await each) so the segments land in order.
+                for (const seg of segments) {
+                  try {
+                    await this.channelRegistry.routeSpeech(agent.name, seg);
+                  } catch (err) {
+                    console.error('speech routing failed:', err);
+                  }
+                }
+              }
+            }
+            // NOTE: agent.reset() + onInferenceEnded() already ran above, BEFORE
+            // dispatchSpeech (main's zombie-subagent fix, PR #32 — sync listeners
+            // must see status === 'idle'). Locus routing is speech dispatch and
+            // doesn't depend on the status field, so it correctly runs after.
+
             break;
           }
 
@@ -2147,9 +3325,18 @@ export class AgentFramework {
       agent.reset();
       this.eventGate?.onInferenceEnded(agent.name);
     } finally {
+      // Stop the typing indicator on every exit path (complete, error,
+      // exhausted, abort) so it never sticks after the turn ends.
+      this.channelRegistry?.stopTyping();
       this.activeStreams.delete(agent.name);
       this.pendingAssistantBlocks.delete(agent.name);
 
+      // A conversation fork whose TTL closure turn just finished is done for
+      // good — dispose it so the agent map doesn't grow monotonically.
+      if (this.closingConversationAgents.has(agent.name)) {
+        this.disposeConversationAgent(agent.name);
+      }
+
       // Flush any deferred messages (e.g. if stream failed while tools were pending)
       if (this.deferredMessages.length > 0 && this.pendingAssistantBlocks.size === 0) {
         const deferred = this.deferredMessages.splice(0);
@@ -2216,17 +3403,57 @@ export class AgentFramework {
   }
 
   private toMembraneToolResult(callId: string, afResult: ToolResult, maxChars?: number): MembraneToolResult {
-    let content: string;
     if (afResult.isError) {
-      content = afResult.error ?? 'Unknown error';
-    } else {
-      content = JSON.stringify(afResult.data);
-      if (maxChars && content.length > maxChars) {
-        content = safeSlice(content, 0, maxChars)
-          + '\n\n[truncated — original was ' + content.length + ' chars]';
+      return { toolUseId: callId, content: afResult.error ?? 'Unknown error', isError: true };
+    }
+    // MCPL tool results arrive as `data: McpToolResultContent[]` — preserve image
+    // blocks natively rather than JSON-stringifying them away. Anything else
+    // (objects, scalars) falls through to JSON. The error path was handled
+    // above, so isError is always false on these return paths.
+    const blocks = this.tryNativeToolResultContent(afResult.data, maxChars);
+    if (blocks) {
+      return { toolUseId: callId, content: blocks, isError: false };
+    }
+    let content = JSON.stringify(afResult.data);
+    if (maxChars && content.length > maxChars) {
+      content = safeSlice(content, 0, maxChars)
+        + '\n\n[truncated — original was ' + content.length + ' chars]';
+    }
+    return { toolUseId: callId, content, isError: false };
+  }
+
+  /**
+   * If `data` is an MCP tool-result content array carrying at least one image,
+   * convert to Membrane's native ToolResultContentBlock[]. Returns null when
+   * the array is text-only (let JSON path handle it; saves a code path).
+   * `maxChars`, when provided, caps each accompanying text block so an image
+   * inlined alongside an enormous text payload can't blow the context.
+   */
+  private tryNativeToolResultContent(data: unknown, maxChars?: number): ToolResultContentBlock[] | null {
+    if (!Array.isArray(data)) return null;
+    let hasImage = false;
+    const blocks: ToolResultContentBlock[] = [];
+    for (const raw of data) {
+      if (!raw || typeof raw !== 'object') return null;
+      const b = raw as { type?: unknown; text?: unknown; data?: unknown; mimeType?: unknown };
+      if (b.type === 'text' && typeof b.text === 'string') {
+        let text = b.text;
+        if (maxChars && text.length > maxChars) {
+          text = safeSlice(text, 0, maxChars)
+            + '\n\n[truncated — original was ' + text.length + ' chars]';
+        }
+        blocks.push({ type: 'text', text });
+      } else if (b.type === 'image' && typeof b.data === 'string' && typeof b.mimeType === 'string') {
+        hasImage = true;
+        blocks.push({
+          type: 'image',
+          source: { type: 'base64', data: b.data, mediaType: b.mimeType },
+        });
+      } else {
+        return null; // unknown shape — bail to JSON path
       }
     }
-    return { toolUseId: callId, content, isError: afResult.isError };
+    return hasImage ? blocks : null;
   }
 
   private getMaxToolResultChars(agent: Agent): number | undefined {
@@ -2320,12 +3547,39 @@ export class AgentFramework {
       return;
     }
 
-    // Route gate:status tool
-    if (enrichedCall.name === 'gate:status' && this.eventGate) {
+    // Route gate_status tool
+    if (enrichedCall.name === 'gate_status' && this.eventGate) {
       this.dispatchGateToolCall(agentName, enrichedCall);
       return;
     }
 
+    // Route sleep / wake tools
+    if ((enrichedCall.name === 'sleep' || enrichedCall.name === 'wake') && this.eventGate) {
+      this.dispatchSleepToolCall(agentName, enrichedCall);
+      return;
+    }
+
+    // Route wake-rule tools (runtime gate.json policy add/remove)
+    if ((enrichedCall.name === 'wake_add_rule' || enrichedCall.name === 'wake_remove_rule') && this.eventGate) {
+      this.dispatchWakeRuleToolCall(agentName, enrichedCall);
+      return;
+    }
+
+    // Route event_tags (tag/ontology discovery)
+    if (enrichedCall.name === 'event_tags' && this.eventGate) {
+      this.dispatchEventTagsToolCall(agentName, enrichedCall);
+      return;
+    }
+
+    // Route synthesized 'think' (private reasoning) and 'skip_reply' (deliberate
+    // stay-silent) tools — handled by the channel registry like the other
+    // synthesized channel tools, but they aren't `channel_`-prefixed so they
+    // need an explicit route here.
+    if ((enrichedCall.name === 'think' || enrichedCall.name === 'skip_reply') && this.channelRegistry) {
+      this.dispatchChannelToolCall(agentName, enrichedCall);
+      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;
@@ -2479,6 +3733,27 @@ export class AgentFramework {
   }
 
   private emitTrace(event: { type: TraceEvent['type']; [key: string]: unknown }): void {
+    // Centralized inference-health observability. Every terminal failure path
+    // funnels through an `inference:exhausted` trace and every successful model
+    // response through `inference:completed`, so intercepting here is the one
+    // place that reliably sees all outcomes regardless of which code path
+    // produced them. In headless/daemon mode no trace client is attached, so
+    // without this the only durable record of a failed inference is a field in
+    // llm-calls.jsonl — invisible to operator, agent, and monitoring.
+    if (event.type === 'inference:exhausted') {
+      this.noteInferenceExhausted(
+        (event.agentName as string) ?? 'unknown',
+        (event.error as string) ?? 'unknown error',
+      );
+    } else if (event.type === 'inference:completed') {
+      // A successful response — even mid-turn between tool calls — proves the
+      // agent isn't hard-down; clear its consecutive-failure streak.
+      const name = event.agentName as string | undefined;
+      if (name && this.consecutiveInferenceFailures.get(name)) {
+        this.consecutiveInferenceFailures.set(name, 0);
+      }
+    }
+
     const traceEvent = {
       ...event,
       timestamp: Date.now(),
@@ -2493,6 +3768,59 @@ export class AgentFramework {
     }
   }
 
+  /**
+   * Handle a fully-exhausted inference (the agent could not produce a response
+   * this turn, after retries). Severity here is high — the agent can't think
+   * at all — yet historically the only durable record was a buried field in
+   * llm-calls.jsonl. This surfaces it three ways:
+   *
+   *   1. stderr  — always, with the underlying API reason. The place an
+   *      operator greps; previously empty in headless mode.
+   *   2. chronicle marker — a `[inference-failed]` message so the agent itself
+   *      learns its turn failed and why (otherwise it's an experiential blank,
+   *      indistinguishable from "not addressed"). addMessage does NOT request
+   *      inference, so this never causes a retry/wake loop.
+   *   3. escalation — after N consecutive failures the agent is hard-down;
+   *      log that loudly (a repeated identical failure is the textbook signal).
+   */
+  private noteInferenceExhausted(agentName: string, reason: string): void {
+    const streak = (this.consecutiveInferenceFailures.get(agentName) ?? 0) + 1;
+    this.consecutiveInferenceFailures.set(agentName, streak);
+
+    // (1) Durable stderr line — works in headless/daemon mode with no client.
+    console.error(`[inference-failed] agent=${agentName} consecutive=${streak}: ${reason}`);
+
+    // (2) Agent-facing chronicle marker (no inference triggered → no loop).
+    const agent = this.agents.get(agentName);
+    if (agent && process.env.SUPPRESS_INFERENCE_FAILED_MARKER !== '1') {
+      try {
+        agent.getContextManager().addMessage(
+          'user',
+          [{
+            type: 'text',
+            text:
+              `[inference-failed] Your previous turn did not complete: the model ` +
+              `call failed and produced no response, so nothing was sent. Reason: ` +
+              `${reason}. If this recurs with the same cause, change approach ` +
+              `rather than retrying identically (e.g. drop an oversized attachment ` +
+              `or an unsupported setting).`,
+          }],
+          { system: true, kind: 'inference-failed', reason, consecutive: streak },
+        );
+      } catch (err) {
+        console.error(`[inference-failed] could not record chronicle marker for ${agentName}:`, err);
+      }
+    }
+
+    // (3) Hard-down escalation on repeated identical failure.
+    if (streak >= this.inferenceFailureEscalationThreshold) {
+      console.error(
+        `[inference-hard-down] agent=${agentName} has FAILED ${streak} consecutive ` +
+        `inferences — it cannot complete a turn. Last reason: ${reason}`,
+      );
+    }
+  }
+
   // ==========================================================================
   // MCPL subsystem wiring
   // ==========================================================================
@@ -2563,6 +3891,42 @@ export class AgentFramework {
           }
         },
         shouldTriggerInference: triggerFilter,
+        // Route a conversation fork's plain-text speech to its HOME channel, not
+        // the process-global most-recent-inbound locus (item 3). The trunk agent
+        // has no home entry, so this returns undefined and routeSpeech falls back
+        // to defaultPublishChannel. `conversationAgentHomes` is the permanent
+        // spawn-time binding; `channelForAgent` is the router's live binding as a
+        // belt-and-suspenders fallback.
+        homeChannelResolver: (agentName) =>
+          this.conversationAgentHomes.get(agentName)
+          ?? this.conversationRouter?.channelForAgent(agentName),
+        // Route a single TRUNK agent's plain-text speech to the channel that
+        // triggered its CURRENT turn (item-3 redux). connectome-host runs every
+        // agent as a trunk (it never exposes conversation forks), so without this
+        // a reply falls back to the process-global most-recent-inbound locus and
+        // a concurrent message in another channel hijacks it. Empty for
+        // heartbeat / no-trigger turns → correct global fallback.
+        activeChannelResolver: (agentName) => this.activeTriggerChannels.get(agentName),
+        // A text-only turn whose speech couldn't be delivered must not vanish
+        // silently: record a `[discord-send-failed]` marker in chronicle so the
+        // agent sees, on her next turn, that her reply never reached the human.
+        // addMessage() alone does not request inference, so this never wakes
+        // her (matching the `discord-send-failed-skip` gate intent: context
+        // yes, wake no).
+        onRouteFailure: ({ channelId, reason, textLen }) => {
+          try {
+            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.`,
+              }],
+              { system: true, kind: 'discord-send-failed', channelId: channelId ?? '', reason },
+            );
+          } catch (err) {
+            console.error('onRouteFailure: failed to record send-failure marker:', err);
+          }
+        },
       },
     );
 
@@ -2716,6 +4080,21 @@ export class AgentFramework {
       this.channelRegistry?.handleIncoming(connection.id, params, responder as never);
     });
 
+    // Handle host-level admin commands from a surface (e.g. Discord /undo)
+    connection.on('host-command', async (
+      params: HostCommandParams,
+      responder?: { respond: (result: unknown) => void; respondError: (code: number, message: string) => void },
+    ) => {
+      if (!responder) return;
+      try {
+        const result = await this.handleHostCommand(connection.id, params ?? {});
+        responder.respond(result);
+      } catch (error) {
+        const err = error instanceof Error ? error : new Error(String(error));
+        responder.respondError(-32603, err.message);
+      }
+    });
+
     // Handle dynamic tool list changes (notifications/tools/list_changed)
     connection.on('tools-list-changed', () => {
       this.handleToolsListChanged(connection.id);
@@ -2860,14 +4239,20 @@ export class AgentFramework {
     const startTime = Date.now();
     const args = (call.input && typeof call.input === 'object') ? call.input as Record<string, unknown> : {};
 
-    // Build state params for stateful tools (Step 8)
+    // Build state params for stateful tools (Step 8).
+    // Host-managed state is single-valued per server, so inject the host-managed
+    // set's `state` for any call; otherwise fall back to a server-managed set's
+    // opaque `checkpoint`. Never blindly pick "first stateful" — when a server
+    // mixes host-managed (e.g. a feed) and server-managed (e.g. post/undo) sets,
+    // that misattributes the feed's state.
     let stateParams: { state?: unknown; checkpoint?: string } | undefined;
     if (this.checkpointManager) {
-      const fs = this.checkpointManager.getStatefulFeatureSet(serverId);
-      if (fs) {
-        if (this.checkpointManager.isHostManaged(serverId, fs)) {
-          stateParams = { state: this.checkpointManager.getCurrentState(serverId, fs) };
-        } else {
+      const hostFs = this.checkpointManager.getHostManagedFeatureSet(serverId);
+      if (hostFs) {
+        stateParams = { state: this.checkpointManager.getCurrentState(serverId, hostFs) };
+      } else {
+        const fs = this.checkpointManager.getStatefulFeatureSet(serverId);
+        if (fs) {
           const cp = this.checkpointManager.getCurrentCheckpoint(serverId, fs);
           if (cp) stateParams = { checkpoint: cp };
         }
@@ -2879,19 +4264,37 @@ export class AgentFramework {
         const durationMs = Date.now() - startTime;
         this.emitTrace({ type: 'tool:completed', module: `mcpl:${serverId}`, tool: toolName, callId: call.id, durationMs });
 
-        // Record checkpoint from stateful tool response (Step 8)
+        // Record checkpoint from stateful tool response (Step 8).
+        // Attribute to the set the server tagged (result.state.featureSet) first;
+        // else the host-managed set (host-managed checkpoints carry data/patch);
+        // else the single stateful set. Avoids recording a feed checkpoint onto a
+        // server-managed set just because it registered first.
         if (result.state && this.checkpointManager) {
-          const fs = this.checkpointManager.getStatefulFeatureSet(serverId);
-          if (fs) {
+          const tagged = result.state.featureSet;
+          const fs = tagged
+            ?? this.checkpointManager.getHostManagedFeatureSet(serverId)
+            ?? this.checkpointManager.getStatefulFeatureSet(serverId);
+          if (fs && this.checkpointManager.isStateful(serverId, fs)) {
             this.checkpointManager.recordCheckpoint(serverId, fs, result.state);
           }
         }
 
-        // Convert MCP tool result to framework ToolResult
+        // 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
+        // through so toMembraneToolResult can preserve image blocks natively.
+        // Text-only results still collapse to a joined string for backward
+        // compatibility with callers that expect data to be string-ish.
         const textContent = result.content
           ?.filter((c) => c.type === 'text' && c.text)
           .map((c) => c.text!)
           .join('\n');
+        const hasNonText = result.content?.some((c) => c.type !== 'text');
+        const data = result.isError
+          ? undefined
+          : hasNonText
+            ? result.content
+            : (textContent || undefined);
 
         this.pushEvent({
           type: 'tool-result',
@@ -2900,7 +4303,7 @@ export class AgentFramework {
           moduleName: `mcpl:${serverId}`,
           result: {
             success: !result.isError,
-            data: result.isError ? undefined : textContent || undefined,
+            data,
             error: result.isError ? (textContent || 'Tool call failed') : undefined,
             isError: result.isError ?? false,
           },
@@ -2927,6 +4330,43 @@ export class AgentFramework {
    * Dispatch a synthesized channel tool call.
    */
   private dispatchChannelToolCall(agentName: string, call: ToolCall): void {
+    // Conversation forks act only on their home channel. channel_publish and
+    // channel_close default a missing channelId to home and reject foreign
+    // ones; channel_open is rejected outright — opening channels mutates
+    // framework-global state (the open-channel set every agent's injections
+    // are scoped against), which is not a fork's call to make.
+    const home = this.conversationAgentHomes.get(agentName);
+    if (home) {
+      const reject = (error: string): void => {
+        this.emitTrace({
+          type: 'tool:failed', module: 'channels', tool: call.name, callId: call.id,
+          error: `conversation agent ${agentName}: ${error}`,
+        });
+        this.pushEvent({
+          type: 'tool-result',
+          callId: call.id,
+          agentName,
+          moduleName: 'channels',
+          result: { success: false, error, isError: true },
+        });
+      };
+
+      if (call.name === 'channel_open') {
+        reject(`This conversation is bound to channel ${home}; conversation agents cannot open channels.`);
+        return;
+      }
+      if (call.name === 'channel_publish' || call.name === 'channel_close') {
+        const input = (call.input ?? {}) as { channelId?: string };
+        if (!input.channelId) {
+          call = { ...call, input: { ...input, channelId: home } };
+        } else if (input.channelId !== home) {
+          const verb = call.name === 'channel_publish' ? 'publishing to' : 'closing';
+          reject(`This conversation is bound to channel ${home}; ${verb} ${input.channelId} is not allowed.`);
+          return;
+        }
+      }
+    }
+
     this.emitTrace({ type: 'tool:started', module: 'channels', tool: call.name, callId: call.id, input: call.input });
     const startTime = Date.now();
 
@@ -2955,6 +4395,174 @@ export class AgentFramework {
       });
   }
 
+  /**
+   * Handle the synthesized `wake_add_rule` / `wake_remove_rule` tools: mutate
+   * the hot-reloaded gate.json at runtime. Validation lives in the EventGate
+   * (same path as gate.json load), so an invalid rule is surfaced as a tool
+   * error and nothing is written.
+   */
+  private dispatchWakeRuleToolCall(agentName: string, call: ToolCall): void {
+    this.emitTrace({ type: 'tool:started', module: 'gate', tool: call.name, callId: call.id, input: call.input });
+    const finish = (result: ToolResult) => {
+      this.emitTrace({
+        type: result.isError ? 'tool:failed' : 'tool:completed',
+        module: 'gate', tool: call.name, callId: call.id, durationMs: 0,
+        ...(result.isError ? { error: result.error } : {}),
+      });
+      this.pushEvent({ type: 'tool-result', callId: call.id, agentName, moduleName: 'gate', result });
+    };
+
+    try {
+      if (call.name === 'wake_remove_rule') {
+        const input = (call.input ?? {}) as { name?: unknown };
+        if (typeof input.name !== 'string' || !input.name) {
+          finish({ success: false, error: 'wake_remove_rule: `name` (string) is required', isError: true });
+          return;
+        }
+        const removed = this.removeGatePolicy(input.name);
+        finish({
+          success: true,
+          data: { removed, name: input.name, policies: this.getGatePolicyNames() },
+        });
+        return;
+      }
+
+      // wake_add_rule — assemble the canonical behavior from the typed fields
+      // (exactly one), then let the gate's own validator do the authoritative
+      // range/shape checks.
+      const input = (call.input ?? {}) as {
+        name?: unknown; match?: unknown; resets?: unknown; position?: unknown;
+        behavior?: unknown; debounceMs?: unknown; rateLimit?: unknown; passiveSample?: unknown;
+      };
+      const behaviorSources = [
+        input.behavior !== undefined ? 'behavior' : null,
+        input.debounceMs !== undefined ? 'debounceMs' : null,
+        input.rateLimit !== undefined ? 'rateLimit' : null,
+        input.passiveSample !== undefined ? 'passiveSample' : null,
+      ].filter((s): s is string => s !== null);
+      if (behaviorSources.length === 0) {
+        finish({
+          success: false,
+          error: 'wake_add_rule: specify exactly one behavior — `behavior` ("always"/"defer"/"skip"), `debounceMs`, `rateLimit`, or `passiveSample`.',
+          isError: true,
+        });
+        return;
+      }
+      if (behaviorSources.length > 1) {
+        finish({
+          success: false,
+          error: `wake_add_rule: give only one behavior, got [${behaviorSources.join(', ')}].`,
+          isError: true,
+        });
+        return;
+      }
+      const behavior: unknown =
+        input.debounceMs !== undefined ? { debounce: input.debounceMs }
+        : input.rateLimit !== undefined ? { rate_limit: input.rateLimit }
+        : input.passiveSample !== undefined ? { passive_sample: input.passiveSample }
+        : input.behavior;
+
+      const position = input.position === 'prepend' ? 'prepend' : 'append';
+      const rawPolicy = {
+        name: input.name,
+        match: input.match ?? {},
+        behavior,
+        ...(input.resets !== undefined ? { resets: input.resets } : {}),
+      };
+      const policy = this.addGatePolicy(rawPolicy, { position });
+      finish({
+        success: true,
+        data: { added: policy.name, policies: this.getGatePolicyNames() },
+      });
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      finish({ success: false, error: msg, isError: true });
+    }
+  }
+
+  /**
+   * Handle the synthesized `sleep` / `wake` tools. `sleep` arms the gate's
+   * suppression window, optionally announces in the sticky channel, and ends
+   * the turn (the agent goes idle immediately). `wake` clears sleep.
+   */
+  private dispatchSleepToolCall(agentName: string, call: ToolCall): void {
+    this.emitTrace({ type: 'tool:started', module: 'gate', tool: call.name, callId: call.id, input: call.input });
+    const gate = this.eventGate!;
+    const input = (call.input ?? {}) as { seconds?: number; announce?: boolean; message?: string };
+
+    const finish = (result: ToolResult) => {
+      this.emitTrace({ type: 'tool:completed', module: 'gate', tool: call.name, callId: call.id, durationMs: 0 });
+      this.pushEvent({ type: 'tool-result', callId: call.id, agentName, moduleName: 'gate', result });
+    };
+
+    if (call.name === 'wake') {
+      const was = gate.clearSleep();
+      finish({ success: true, data: { woke: was } });
+      return;
+    }
+
+    const seconds = Number(input.seconds);
+    if (!Number.isFinite(seconds) || seconds <= 0) {
+      finish({ success: false, error: 'sleep: `seconds` must be a positive number', isError: true });
+      return;
+    }
+
+    const { until } = gate.setSleep(seconds, input.message);
+    const announce = input.announce !== false; // default true
+    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).
+    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);
+      });
+    }
+
+    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.
+    finish({ success: true, data: { sleepingFor: human, until }, endTurn: true });
+  }
+
+  /** Aggregate the event-tag vocabulary: reserved chat:* core + each connected
+   *  server's declared tag ontology + gate.js status. */
+  private buildEventTagsResult(): Record<string, unknown> {
+    const servers: Record<string, Record<string, unknown>> = {};
+    for (const conn of this.mcplServerRegistry?.getAllServers() ?? []) {
+      const declared = this.featureSetManager?.getDeclaredFeatureSets(conn.id) ?? {};
+      const sets: Record<string, unknown> = {};
+      for (const [name, decl] of Object.entries(declared)) {
+        if (decl.tagOntology) sets[name] = decl.tagOntology;
+      }
+      if (Object.keys(sets).length > 0) servers[conn.id] = sets;
+    }
+    return {
+      core: AgentFramework.CHAT_CORE_TAGS,
+      servers,
+      gateScript: this.eventGate?.getStatus().script ?? null,
+      hint:
+        'Use these in gate.json policies (match.tagsAny / tagsAll / tagsNone) or ' +
+        'in gate.js. Unknown/undeclared tags are tolerated (open ontologies).',
+    };
+  }
+
+  private dispatchEventTagsToolCall(agentName: string, call: ToolCall): void {
+    this.emitTrace({ type: 'tool:started', module: 'gate', tool: call.name, callId: call.id, input: call.input });
+    let result: import('./types/events.js').ToolResult;
+    try {
+      result = { success: true, data: this.buildEventTagsResult() };
+      this.emitTrace({ type: 'tool:completed', module: 'gate', tool: call.name, callId: call.id, durationMs: 0 });
+    } catch (error) {
+      const err = error instanceof Error ? error : new Error(String(error));
+      this.emitTrace({ type: 'tool:failed', module: 'gate', tool: call.name, callId: call.id, error: err.message });
+      result = { success: false, error: err.message, isError: true };
+    }
+    this.pushEvent({ type: 'tool-result', callId: call.id, agentName, moduleName: 'gate', result });
+  }
+
   private dispatchGateToolCall(agentName: string, call: ToolCall): void {
     this.emitTrace({ type: 'tool:started', module: 'gate', tool: call.name, callId: call.id, input: call.input });
     const startTime = Date.now();
@@ -2988,7 +4596,13 @@ export class AgentFramework {
     const inferenceId = `${agent.name}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
     return {
       inferenceId,
-      conversationId: agent.name, // Simplified; proper conversation tracking TODO
+      // Conversation identity = the agent (a trunk agent IS its own conversation;
+      // forks get their own agent). The turn's channel LOCUS — the "proper
+      // conversation tracking" this once flagged as a TODO — is now tracked
+      // per-agent in `activeTriggerChannels` and surfaced to the agent via
+      // buildChannelContext (channels.defaultOutgoing) below, so the agent is
+      // told the same channel its speech will route to (item-3 redux).
+      conversationId: agent.name,
       turnIndex: 0, // Simplified; needs per-conversation counter TODO
       userMessage: null, // Could extract from trigger context
       model: {
@@ -2997,7 +4611,7 @@ export class AgentFramework {
         contextWindow: 200000,
         capabilities: ['tools'],
       },
-      channels: this.channelRegistry?.buildChannelContext(),
+      channels: this.channelRegistry?.buildChannelContext(agent.name),
     };
   }
 }