@animalabs/agent-framework 0.5.6 → 0.6.0

package/dist/src/framework.js

@@ -12,12 +12,16 @@ import { HookOrchestrator } from './mcpl/hook-orchestrator.js';
 import { PushHandler } 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';
 import { UsageTracker } from './usage/usage-tracker.js';
 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';
@@ -91,9 +95,6 @@ function extractGateFields(event) {
         : undefined;
     return { content, metadata, mount, paths };
 }
-/**
- * The main agent framework.
- */
 export class AgentFramework {
     store;
     ownsStore;
@@ -104,6 +105,16 @@ export class AgentFramework {
     inferencePolicy;
     errorPolicy;
     pendingRequests = [];
+    /**
+     * 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).
+     */
+    activeTriggerChannels = new Map();
     running = false;
     loopPromise = null;
     traceListeners = [];
@@ -113,6 +124,12 @@ export class AgentFramework {
     processLoggingBroadcast;
     activeStreams = new Map();
     pendingAssistantBlocks = new Map();
+    /** Per-agent count of consecutive exhausted inferences (reset on any success).
+     *  Drives hard-down escalation — see noteInferenceExhausted. */
+    consecutiveInferenceFailures = new Map();
+    /** N consecutive failed inferences ⇒ the agent is treated as hard-down and
+     *  escalated loudly to stderr. */
+    inferenceFailureEscalationThreshold = 3;
     /** Name of the primary (non-ephemeral) agent for routing framework messages. */
     primaryAgentName = null;
     // Messages deferred while an agent is waiting_for_tools (to preserve
@@ -121,6 +138,8 @@ export class AgentFramework {
     // Undo/redo state
     turnCounters = new Map(); // agentName → next turnIndex
     redoStacks = new Map(); // agentName → redo entries
+    /** Liveness watchdog (fail hard on a wedged main thread). Null unless enabled. */
+    livenessWatchdog = null;
     // MCPL subsystems (null when no mcplServers configured)
     mcplServerRegistry = null;
     featureSetManager = null;
@@ -130,6 +149,21 @@ export class AgentFramework {
     inferenceRouter = null;
     channelRegistry = null;
     checkpointManager = null;
+    /** Per-channel conversation routing (null unless config.conversations set). */
+    conversationRouter = null;
+    /** Agent configs by name — fork agents are built from the template's config. */
+    agentConfigs = 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.
+     */
+    conversationAgentHomes = new Map();
+    /** Last idle-TTL sweep timestamp. */
+    lastConversationSweep = 0;
+    /** Forks whose TTL closure turn has been queued — disposed (removed from
+     * agents/agentConfigs/conversationAgentHomes) when their stream ends. */
+    closingConversationAgents = new Set();
     mcplTools = [];
     mcplToolRefreshInFlight = false;
     mcplToolRefreshPending = false;
@@ -163,6 +197,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),
         });
     }
     /**
@@ -235,6 +271,32 @@ export class AgentFramework {
         for (const module of config.modules) {
             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);
+                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
@@ -244,6 +306,7 @@ export class AgentFramework {
             framework.eventGate = new EventGate({
                 configPath,
                 initialConfig: config.gate.config,
+                privilegedUsersPath: config.gate.privilegedUsersPath,
                 emitTrace: (e) => framework.emitTrace(e),
                 addMessage: (p, c, m) => framework.addMessage(p, c, m),
                 requestInference: (agentName, reason, source) => {
@@ -252,6 +315,18 @@ export class AgentFramework {
                 getAgentNames: () => [...framework.agents.keys()],
             });
         }
+        // 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
@@ -322,6 +397,7 @@ export class AgentFramework {
         this.channelRegistry?.stopAll();
         // Dispose EventGate (clear debounce timers)
         this.eventGate?.dispose();
+        this.livenessWatchdog?.stop();
         // Stop modules and MCPL servers in parallel
         const shutdownPromises = [this.moduleRegistry.stopAll()];
         if (this.mcplServerRegistry) {
@@ -351,6 +427,14 @@ export class AgentFramework {
      */
     onTrace(listener) {
         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);
+        };
     }
     /**
      * Public accessor for the MCPL channel registry.
@@ -396,6 +480,13 @@ export class AgentFramework {
     getAllAgents() {
         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() {
+        return this.conversationRouter;
+    }
     /**
      * Abort an in-flight inference for an agent.
      */
@@ -422,12 +513,84 @@ export class AgentFramework {
     getAllTools() {
         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, opts) {
+        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;
+        // 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.
      */
@@ -449,6 +612,38 @@ export class AgentFramework {
     getModule(name) {
         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, options) {
+        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) {
+        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() {
+        return this.eventGate?.listPolicyNames() ?? [];
+    }
     /**
      * Get the Membrane instance.
      */
@@ -666,6 +861,409 @@ 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). */
+    static SLEEP_TOOLS = [
+        {
+            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. */
+    static WAKE_RULE_TOOLS = [
+        {
+            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. */
+    static EVENT_TAGS_TOOL = {
+        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. */
+    static CHAT_CORE_TAGS = {
+        '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 🛑. */
+    static REFUSAL_REACTIONS = {
+        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.
+     */
+    async reactToRefusal(agentName, category) {
+        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).
+     */
+    async handleHostCommand(serverId, params) {
+        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) => all.findIndex((m) => String(m.metadata?.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, hi) => {
+                const refs = [];
+                for (let i = lo; i <= hi; i++) {
+                    const md = all[i].metadata;
+                    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
+                    .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.
+     */
+    async lastVisiblePreview(agentName) {
+        try {
+            const preview = await this.previewActivation(agentName);
+            const messages = preview.messages ?? [];
+            const last = messages[messages.length - 1];
+            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.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) {
         const limit = query?.limit ?? 50;
         const offset = query?.offset ?? 0;
@@ -1052,6 +1650,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) {
             this.primaryAgentName = config.name;
@@ -1074,6 +1673,8 @@ export class AgentFramework {
         if (event) {
             await this.handleProcessEvent(event);
         }
+        // Close idle conversation forks (no-op unless conversations configured)
+        this.sweepExpiredConversations();
         // Check for inference requests
         await this.processInferenceRequests();
         // Yield to the event loop between iterations.
@@ -1124,26 +1725,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 = currentState.toolResults.map(tc => {
-                        let content;
-                        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',
-                            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 = currentState.toolResults.map(tc => ({
+                        type: 'tool_result',
+                        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.
                     // Route to the PRIMARY agent — deferred messages are framework-level
@@ -1211,7 +1804,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);
+            await this.handleMcplChannelIncoming(event);
         }
         else if (event.type === 'mcpl:push-event') {
             this.handleMcplPushEvent(event);
@@ -1282,8 +1875,10 @@ 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) {
                 const agent = this.agents.get(agentName);
@@ -1305,7 +1900,7 @@ export class AgentFramework {
      * Convert an incoming MCPL channel message to a context message.
      * This replaces the old MCPLModule.onProcess() message conversion.
      */
-    handleMcplChannelIncoming(event) {
+    async handleMcplChannelIncoming(event) {
         const metadata = {
             ...event.metadata,
             channelId: event.channelId,
@@ -1316,6 +1911,13 @@ 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' });
         if (event.triggerInference) {
@@ -1325,8 +1927,236 @@ 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.
+     */
+    async routeConversationIncoming(event, messageMetadata) {
+        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;
+        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.
+     */
+    async createConversationAgent(name, channelId) {
+        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 = { ...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()). */
+    persistConversationRouterState() {
+        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.
+     */
+    disposeConversationAgent(agentName) {
+        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.
+     */
+    scopeInjectionsForAgent(agentName, injections) {
+        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.
+     */
+    sweepExpiredConversations() {
+        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);
+            }
         }
     }
     /**
@@ -1342,18 +2172,62 @@ 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.
+     */
+    derivePushEventChannel(origin) {
+        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;
+    }
     async processInferenceRequests() {
         if (this.pendingRequests.length === 0) {
             return;
@@ -1407,7 +2281,16 @@ 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((acc, r) => r.channelId ?? acc, undefined);
+            await this.startAgentStream(agent, { ...trigger, channelId: triggerChannel });
         }
     }
     async startAgentStream(agent, trigger, attempt = 0) {
@@ -1416,6 +2299,18 @@ export class AgentFramework {
             this.recordTurnCheckpoint(agent.name);
             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);
         try {
@@ -1425,6 +2320,11 @@ export class AgentFramework {
             // Both produce ContextInjection[] that get merged before inference.
             let injections;
             // 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) {
@@ -1438,7 +2338,7 @@ 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;
                     }
@@ -1483,6 +2383,13 @@ export class AgentFramework {
         const requestId = `${agent.name}-${startTime}-${Math.random().toString(36).slice(2, 8)}`;
         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) {
@@ -1513,13 +2420,26 @@ export class AgentFramework {
                             agentName: agent.name,
                             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 = [];
-                        if (event.context.preamble) {
-                            assistantBlocks.push({ type: 'text', text: event.context.preamble });
+                        // 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.roundContent;
+                        let assistantBlocks;
+                        if (roundContent && roundContent.length > 0) {
+                            assistantBlocks = roundContent.filter((b) => b.type !== 'tool_result');
                         }
-                        for (const c of event.calls) {
-                            assistantBlocks.push({ type: 'tool_use', id: c.id, name: c.name, input: c.input });
+                        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 });
+                            }
                         }
                         this.pendingAssistantBlocks.set(agent.name, assistantBlocks);
                         // Note: max_tokens truncation cannot produce tool-calls events here.
@@ -1563,21 +2483,25 @@ export class AgentFramework {
                                 const toolResultContent = readyState.toolResults.map(tc => ({
                                     type: 'tool_result',
                                     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);
                             }
                         }
                         // 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) => b.type === 'tool_use' || b.type === 'tool_result');
-                        if (hadToolCalls) {
-                            // Filter to only trailing text/thinking blocks (no tool_use — those are already stored)
-                            const trailingContent = response.content.filter((block) => block.type !== 'tool_use' && block.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, b, i) => b.type === 'tool_use' || b.type === 'tool_result' ? i : last, -1);
+                        if (lastToolIdx >= 0) {
+                            const trailingContent = response.content.slice(lastToolIdx + 1);
                             if (trailingContent.length > 0) {
                                 agent.addAssistantResponse(trailingContent);
                             }
@@ -1673,6 +2597,19 @@ export class AgentFramework {
                             tokenUsage,
                             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?.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 = {
@@ -1686,6 +2623,91 @@ export class AgentFramework {
                             };
                             await this.moduleRegistry.dispatchSpeech(agent.name, speechContent, speechContext);
                         }
+                        // 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.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) => (n.includes('--') ? n.split('--').pop() : n);
+                            const toolNames = response.content
+                                .filter((b) => b.type === 'tool_use')
+                                .map((b) => b.name)
+                                .filter((n) => 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;
                     }
                     case 'error': {
@@ -1778,8 +2800,16 @@ export class AgentFramework {
             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);
@@ -1843,18 +2873,60 @@ export class AgentFramework {
         }
     }
     toMembraneToolResult(callId, afResult, maxChars) {
-        let content;
         if (afResult.isError) {
-            content = afResult.error ?? 'Unknown error';
+            return { toolUseId: callId, content: afResult.error ?? 'Unknown error', isError: true };
         }
-        else {
-            content = JSON.stringify(afResult.data);
-            if (maxChars && content.length > maxChars) {
-                content = safeSlice(content, 0, maxChars)
-                    + '\n\n[truncated — original was ' + content.length + ' chars]';
+        // 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.
+     */
+    tryNativeToolResultContent(data, maxChars) {
+        if (!Array.isArray(data))
+            return null;
+        let hasImage = false;
+        const blocks = [];
+        for (const raw of data) {
+            if (!raw || typeof raw !== 'object')
+                return null;
+            const b = raw;
+            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;
     }
     getMaxToolResultChars(agent) {
         const strategy = agent.getContextManager().getStrategy();
@@ -1934,11 +3006,34 @@ export class AgentFramework {
             this.dispatchChannelToolCall(agentName, enrichedCall);
             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;
@@ -2072,6 +3167,24 @@ export class AgentFramework {
         };
     }
     emitTrace(event) {
+        // 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 ?? 'unknown', event.error ?? '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;
+            if (name && this.consecutiveInferenceFailures.get(name)) {
+                this.consecutiveInferenceFailures.set(name, 0);
+            }
+        }
         const traceEvent = {
             ...event,
             timestamp: Date.now(),
@@ -2085,6 +3198,49 @@ 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).
+     */
+    noteInferenceExhausted(agentName, reason) {
+        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
     // ==========================================================================
@@ -2125,6 +3281,38 @@ 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);
+                }
+            },
         });
         // Host capabilities advertised during the MCP handshake
         const hostCapabilities = {
@@ -2241,6 +3429,19 @@ export class AgentFramework {
         connection.on('channels-incoming', (params, responder) => {
             this.channelRegistry?.handleIncoming(connection.id, params, responder);
         });
+        // Handle host-level admin commands from a surface (e.g. Discord /undo)
+        connection.on('host-command', async (params, responder) => {
+            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);
@@ -2371,15 +3572,21 @@ export class AgentFramework {
         this.emitTrace({ type: 'tool:started', module: `mcpl:${serverId}`, tool: toolName, callId: call.id, input: call.input });
         const startTime = Date.now();
         const args = (call.input && typeof call.input === 'object') ? call.input : {};
-        // 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;
         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 };
@@ -2390,18 +3597,36 @@ export class AgentFramework {
             .then((result) => {
             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',
                 callId: call.id,
@@ -2409,7 +3634,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,
                 },
@@ -2434,6 +3659,42 @@ export class AgentFramework {
      * Dispatch a synthesized channel tool call.
      */
     dispatchChannelToolCall(agentName, call) {
+        // 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) => {
+                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 ?? {});
+                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();
         this.channelRegistry.handleChannelToolCall(call.name, call.input)
@@ -2460,6 +3721,159 @@ 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.
+     */
+    dispatchWakeRuleToolCall(agentName, call) {
+        this.emitTrace({ type: 'tool:started', module: 'gate', tool: call.name, callId: call.id, input: call.input });
+        const finish = (result) => {
+            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 ?? {});
+                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 ?? {});
+            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 !== 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 = 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.
+     */
+    dispatchSleepToolCall(agentName, call) {
+        this.emitTrace({ type: 'tool:started', module: 'gate', tool: call.name, callId: call.id, input: call.input });
+        const gate = this.eventGate;
+        const input = (call.input ?? {});
+        const finish = (result) => {
+            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. */
+    buildEventTagsResult() {
+        const servers = {};
+        for (const conn of this.mcplServerRegistry?.getAllServers() ?? []) {
+            const declared = this.featureSetManager?.getDeclaredFeatureSets(conn.id) ?? {};
+            const sets = {};
+            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).',
+        };
+    }
+    dispatchEventTagsToolCall(agentName, call) {
+        this.emitTrace({ type: 'tool:started', module: 'gate', tool: call.name, callId: call.id, input: call.input });
+        let result;
+        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 });
+    }
     dispatchGateToolCall(agentName, call) {
         this.emitTrace({ type: 'tool:started', module: 'gate', tool: call.name, callId: call.id, input: call.input });
         const startTime = Date.now();
@@ -2491,7 +3905,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: {
@@ -2500,7 +3920,7 @@ export class AgentFramework {
                 contextWindow: 200000,
                 capabilities: ['tools'],
             },
-            channels: this.channelRegistry?.buildChannelContext(),
+            channels: this.channelRegistry?.buildChannelContext(agent.name),
         };
     }
 }