@animalabs/agent-framework 0.6.6 → 0.6.8

package/dist/src/framework.js

@@ -25,15 +25,14 @@ import { splitProseSegments } from './prose-segments.js';
  *   - explicit delivery tools (channel_publish / *send_message /
  *     *reply_message / *send_dm) — already sent the message, so routing the
  *     prose again would double-post.
- * `think` is deliberately NOT here: it is silent *reasoning*, but prose
- * written around a think is the agent's actual voice and must be delivered.
+ * `think` is deliberately NOT here: it is silent *reasoning*, and same-round
+ * prose beside it is governed separately by same_round_think_text_policy.
  *
- * Scope: mid-turn rounds apply this PER ROUND (a round's prose is suppressed
- * only by a silencing tool in that same round — live delivery can't be
- * retracted by a later round's skip_reply); the turn's TRAILING prose keeps
- * the historical turn-wide rule (any silencing tool anywhere in the turn
- * suppresses it), preserving the "send_message then 'sent it.' postscript"
- * double-post guard.
+ * Scope: an explicit delivery suppresses prose from that round onward until
+ * another external message is injected. The suppression prevents a
+ * `send_message` followed by "sent it" from double-posting, but a new message
+ * starts a new conversational round and must be answerable with plain prose.
+ * `skip_reply` ends the turn at the tool-result boundary.
  */
 const SILENCING_TOOLS = new Set([
     'skip_reply', 'channel_publish', 'send_message', 'reply_message', 'send_dm',
@@ -45,6 +44,7 @@ import { isToolAllowed } from './mcpl/tool-policy.js';
 import { EventGate } from './gate/event-gate.js';
 import { UsageTracker } from './usage/usage-tracker.js';
 import { formatZonedDateTime, resolveTimeZone } from './timezone.js';
+import { DEFAULT_DISCORD_AWARENESS_EMOJI, DiscordAwarenessOutbox, defaultDiscordAwarenessOutboxPath, extractDiscordAwarenessRefs, } from './recovery/discord-awareness-outbox.js';
 const FRAMEWORK_STATE_ID = 'framework/state';
 const CONVERSATION_ROUTER_STATE_ID = 'framework/conversation-router';
 const INFERENCE_LOG_ID = 'framework/inference-log';
@@ -53,6 +53,22 @@ const TURN_CHECKPOINTS_ID = 'framework/turn-checkpoints'; // legacy single-map l
 const TURN_CHECKPOINTS_TREE_ID = 'framework/turn-checkpoints/tree';
 /** Maximum number of turn checkpoints to keep per agent. */
 const MAX_TURN_CHECKPOINTS = 20;
+const DEFAULT_DISCORD_AWARENESS_DEADLINE_MS = 10_000;
+const MIN_DISCORD_AWARENESS_DEADLINE_MS = 50;
+const MAX_DISCORD_AWARENESS_DEADLINE_MS = 60_000;
+function normalizeDiscordAwarenessDeadline(value) {
+    if (value === undefined || !Number.isFinite(value) || value <= 0) {
+        return DEFAULT_DISCORD_AWARENESS_DEADLINE_MS;
+    }
+    return Math.max(MIN_DISCORD_AWARENESS_DEADLINE_MS, Math.min(MAX_DISCORD_AWARENESS_DEADLINE_MS, Math.floor(value)));
+}
+class DiscordAwarenessAccountingError extends Error {
+    constructor(operation, cause) {
+        const detail = cause instanceof Error ? cause.message : String(cause);
+        super(`Discord awareness accounting failed during ${operation}: ${detail}`, { cause });
+        this.name = 'DiscordAwarenessAccountingError';
+    }
+}
 /**
  * Default inference policy - infer if any request exists for the agent.
  */
@@ -61,6 +77,10 @@ class DefaultInferencePolicy {
         return requests.some((r) => r.agentName === agentName);
     }
 }
+function isPermanentDiscordReactionFailure(message) {
+    return /unknown message|unknown channel|missing access|missing permissions|missing permission|cannot access|channel .* not found|message .* not found/i
+        .test(message);
+}
 /**
  * Default error policy - retry with exponential backoff.
  *
@@ -162,7 +182,7 @@ export class AgentFramework {
     maintenanceRunId = 0;
     currentMaintenanceRun = null;
     maintenanceHistory = [];
-    /** Last time we console-warned about stale (busy-requeued) inference requests, per agent. */
+    /** Last time we reported stale (busy-requeued) inference requests, per agent. */
     staleWarnAt = new Map();
     /** Per-agent last inference activity (epoch ms), for /healthz + doctor tooling. */
     lastInferenceAt = new Map();
@@ -172,9 +192,17 @@ export class AgentFramework {
     /** Per-agent output locus pinned for the CURRENT logical turn (see
      *  resolveTurnLocus in driveStream). Lives here — not in driveStream
      *  locals — so the pin survives a context-budget stream restart, which
-     *  continues the same logical turn in a fresh driveStream. Cleared at the
-     *  start of every non-restart turn. */
+     *  continues the same logical turn in a fresh driveStream. A mid-turn
+     *  injected channel message replaces the pin for the next conversational
+     *  round; otherwise it remains stable. Cleared at the start of every
+     *  non-restart turn. */
     turnLocusPins = new Map();
+    /** A tool boundary injected fresh external input into the live stream.
+     *  Presence (including a null value) tells driveStream to clear sticky
+     *  explicit-send suppression before handling the next model round. A
+     *  string also moves that round's reply locus to the newest injected
+     *  channel. */
+    midTurnRoutingResets = new Map();
     pendingAssistantBlocks = new Map();
     /** Streams the FRAMEWORK cancelled for non-terminal reasons, keyed
      *  `${agentName}:${streamId}`: an endTurn tool result or a context-budget
@@ -278,13 +306,22 @@ export class AgentFramework {
      *  subsystem can be lazily initialized by connectMcplServer when the
      *  framework started with zero configured servers. */
     mcplInferenceRoutingConfig = null;
+    /** Durable, non-Chronicle projection queue for messages removed by a branch. */
+    discordAwarenessOutbox = null;
+    discordAwarenessEmoji = DEFAULT_DISCORD_AWARENESS_EMOJI;
+    discordAwarenessDeadlineMs = DEFAULT_DISCORD_AWARENESS_DEADLINE_MS;
+    /** Serialize per-server drains so reconnect and an online undo cannot race. */
+    discordAwarenessDrains = new Map();
+    /** Framework-global inference gate; older generations cannot release it. */
+    discordAwarenessBarrier = null;
+    discordAwarenessBarrierGeneration = 0;
     // EventGate (null when FrameworkConfig.gate is omitted)
     eventGate = null;
     // Session-level token usage tracking (always-on)
     usageTracker;
     /** Presentation-only wall-clock zone; persistence remains UTC/epoch. */
     timeZone;
-    constructor(store, ownsStore, membrane, inferencePolicy, errorPolicy, syncIntervalMs, maintenanceIntervalMs, processLoggingPersist, processLoggingBroadcast, timeZone) {
+    constructor(store, ownsStore, membrane, inferencePolicy, errorPolicy, syncIntervalMs, maintenanceIntervalMs, processLoggingPersist, processLoggingBroadcast, timeZone, discordAwarenessOutbox, discordAwarenessEmoji, discordAwarenessDeadlineMs) {
         this.store = store;
         this.ownsStore = ownsStore;
         this.membrane = membrane;
@@ -295,6 +332,9 @@ export class AgentFramework {
         this.processLoggingPersist = processLoggingPersist;
         this.processLoggingBroadcast = processLoggingBroadcast;
         this.timeZone = timeZone;
+        this.discordAwarenessOutbox = discordAwarenessOutbox;
+        this.discordAwarenessEmoji = discordAwarenessEmoji;
+        this.discordAwarenessDeadlineMs = discordAwarenessDeadlineMs;
         this.queue = new ProcessQueueImpl();
         this.usageTracker = new UsageTracker({
             emitTrace: (e) => this.emitTrace({ ...e }),
@@ -374,13 +414,38 @@ export class AgentFramework {
                 // Already registered
             }
         }
-        const framework = new AgentFramework(store, ownsStore, config.membrane, config.inferencePolicy ?? new DefaultInferencePolicy(), config.errorPolicy ?? new DefaultErrorPolicy(), config.syncIntervalMs ?? DEFAULT_SYNC_INTERVAL_MS, config.maintenanceIntervalMs ?? DEFAULT_MAINTENANCE_INTERVAL_MS, processLoggingPersist, processLoggingBroadcast, resolveTimeZone(config.timeZone));
+        const discordAwarenessOutboxPath = config.discordAwarenessOutboxPath
+            ?? (config.storePath ? defaultDiscordAwarenessOutboxPath(config.storePath) : undefined);
+        const discordAwarenessOutbox = discordAwarenessOutboxPath
+            ? new DiscordAwarenessOutbox(discordAwarenessOutboxPath)
+            : null;
+        const framework = new AgentFramework(store, ownsStore, config.membrane, config.inferencePolicy ?? new DefaultInferencePolicy(), config.errorPolicy ?? new DefaultErrorPolicy(), config.syncIntervalMs ?? DEFAULT_SYNC_INTERVAL_MS, config.maintenanceIntervalMs ?? DEFAULT_MAINTENANCE_INTERVAL_MS, processLoggingPersist, processLoggingBroadcast, resolveTimeZone(config.timeZone), discordAwarenessOutbox, config.discordAwarenessEmoji ?? DEFAULT_DISCORD_AWARENESS_EMOJI, normalizeDiscordAwarenessDeadline(config.discordAwarenessDeadlineMs));
+        // If an offline recovery process crashed after switching Chronicle but
+        // before committing its prepared marker batch, the active branch is the
+        // commit record. Promote it now; no quarantined content is read.
+        if (discordAwarenessOutbox) {
+            try {
+                const activated = discordAwarenessOutbox.activatePreparedForBranch(store.currentBranch().name, store.listBranches());
+                if (activated > 0) {
+                    console.error(`[discord-awareness] recovered ${activated} prepared batch(es) for active branch ${store.currentBranch().name}`);
+                }
+            }
+            catch (error) {
+                // The branch may be safe, but reporting the framework ready while its
+                // durable awareness projection is unreadable creates a half-ready
+                // host whose data plane can never be released safely.
+                throw new DiscordAwarenessAccountingError('startup reconciliation', error);
+            }
+        }
         // Restore persisted usage data (if any) from prior session
         framework.restoreUsageState();
         // Create agents
         for (const agentConfig of config.agents) {
             await framework.createAgent(agentConfig);
         }
+        // Finish any branch-local suppression interrupted after Chronicle switched
+        // branches. This runs before modules, MCPL connections, or inbound traffic.
+        await framework.resumePreparedDiscordSuppressions();
         // Add modules
         for (const module of config.modules) {
             await framework.addModule(module);
@@ -595,10 +660,9 @@ export class AgentFramework {
         });
     }
     async runQueuedMaintenance() {
-        const allTools = this.getAllTools();
         const queued = [...this.agents.values()].flatMap((agent) => {
             const cm = agent.getContextManager();
-            const tools = allTools.filter((tool) => agent.canUseTool(tool.name));
+            const tools = this.getToolsForAgent(agent.name).filter((tool) => agent.canUseTool(tool.name));
             cm.setToolDefinitions(tools);
             if (cm.isReady())
                 return [];
@@ -786,9 +850,116 @@ export class AgentFramework {
             ...this.mcplTools,
             ...channelTools,
             ...gateTools,
-            AgentFramework.AGENT_SETTINGS_TOOL,
+            this.buildAgentSettingsTool(),
+            ...(this.getWorkspaceModule() ? [AgentFramework.SAVE_IMAGE_TOOL] : []),
         ];
     }
+    /** The registered workspace module, if any (used by save_image). */
+    getWorkspaceModule() {
+        const module = this.moduleRegistry.getAllModules().find((m) => m.name === 'workspace');
+        return module && typeof module.writeBinary === 'function'
+            ? module
+            : undefined;
+    }
+    /** Core agent_settings keys — extension keys must not collide with these. */
+    static AGENT_SETTINGS_CORE_KEYS = [
+        'context_budget_tokens',
+        'tail_tokens',
+        'transition_pace_tokens',
+        'same_round_think_text_policy',
+    ];
+    /**
+     * Collect module-declared agent_settings extensions (Module.getAgentSettingsExtension),
+     * keyed by owning module name. Extensions whose keys collide with the core
+     * settings or an earlier extension are skipped loudly — silent shadowing
+     * would make updates route to the wrong owner.
+     */
+    collectAgentSettingsExtensions() {
+        const result = new Map();
+        const taken = new Set(AgentFramework.AGENT_SETTINGS_CORE_KEYS);
+        for (const module of this.moduleRegistry.getAllModules()) {
+            const ext = module.getAgentSettingsExtension?.();
+            if (!ext)
+                continue;
+            const collision = ext.keys.find((k) => taken.has(k));
+            if (collision) {
+                console.error(`[agent-settings] extension from module '${module.name}' skipped: key '${collision}' already taken`);
+                continue;
+            }
+            ext.keys.forEach((k) => taken.add(k));
+            result.set(module.name, ext);
+        }
+        return result;
+    }
+    captureInferenceToolSnapshot(agent) {
+        return {
+            sameRoundThinkTextPolicy: agent.getEffectiveSameRoundThinkTextPolicy(),
+        };
+    }
+    buildThinkTool(policy) {
+        return {
+            name: 'think',
+            description: 'Reason privately. The think({content}) argument stays in your own context and is NOT sent ' +
+                'to channels or other surfaces. ' +
+                (policy === 'private'
+                    ? 'Your current same_round_think_text_policy is private, so ordinary text emitted in the SAME native assistant round as think() is withheld from channel routing. Later rounds without think() route normally.'
+                    : 'Your current same_round_think_text_policy is public, so ordinary text emitted in the SAME native assistant round as think() may still be routed publicly as your speech. Later rounds without think() route normally.') +
+                ' Use think() to work things out privately. To inspect or change this policy, use agent_settings get/update on same_round_think_text_policy. To deliberately not reply this turn, call skip_reply instead.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    content: {
+                        type: 'string',
+                        description: 'Your private thought / reasoning (optional; not sent anywhere).',
+                    },
+                },
+                required: [],
+            },
+        };
+    }
+    /** agent_settings tool definition with module extension fields merged in. */
+    buildAgentSettingsTool() {
+        const base = AgentFramework.AGENT_SETTINGS_TOOL;
+        const extensions = this.collectAgentSettingsExtensions();
+        if (extensions.size === 0)
+            return base;
+        const baseSchema = base.inputSchema;
+        const extProperties = {};
+        const extKeys = [];
+        for (const ext of extensions.values()) {
+            Object.assign(extProperties, ext.properties);
+            extKeys.push(...ext.keys);
+        }
+        const settingsProp = baseSchema.properties.settings;
+        return {
+            ...base,
+            description: base.description +
+                ` Additional host-managed settings also live here: ${extKeys.join(', ')}.`,
+            inputSchema: {
+                ...baseSchema,
+                properties: {
+                    ...baseSchema.properties,
+                    ...extProperties,
+                    settings: {
+                        ...baseSchema.properties.settings,
+                        items: {
+                            ...settingsProp.items,
+                            enum: [...(settingsProp.items?.enum ?? []), ...extKeys],
+                        },
+                    },
+                },
+            },
+        };
+    }
+    getToolsForAgent(agentName, snapshot) {
+        return this.getAllTools().map((tool) => {
+            if (tool.name === 'think') {
+                return this.buildThinkTool(snapshot?.sameRoundThinkTextPolicy
+                    ?? this.getAgentRuntimeSettings(agentName).sameRoundThinkTextPolicy);
+            }
+            return tool;
+        });
+    }
     getAgentRuntimeSettings(agentName) {
         const agent = this.agents.get(agentName);
         if (!agent)
@@ -870,7 +1041,7 @@ export class AgentFramework {
         if (!agent) {
             throw new Error(`Agent not found: ${agentName}`);
         }
-        const tools = this.getAllTools().filter((t) => agent.canUseTool(t.name));
+        const tools = this.getToolsForAgent(agentName).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) {
@@ -1004,6 +1175,14 @@ export class AgentFramework {
             return null;
         }
     }
+    validatePersistedAgentRuntimeSettings(agentName, overrides) {
+        if (overrides.sameRoundThinkTextPolicy !== undefined &&
+            overrides.sameRoundThinkTextPolicy !== 'public' &&
+            overrides.sameRoundThinkTextPolicy !== 'private') {
+            throw new Error(`Invalid persisted sameRoundThinkTextPolicy for agent "${agentName}": ${JSON.stringify(overrides.sameRoundThinkTextPolicy)}`);
+        }
+        return overrides;
+    }
     persistAgentRuntimeSettings(agentName, overrides) {
         const data = this.store.getStateJson(FRAMEWORK_STATE_ID);
         const state = (data && typeof data === 'object' ? data : {});
@@ -1323,10 +1502,41 @@ export class AgentFramework {
             'tagsAll / tagsNone) or in gate.js.',
         inputSchema: { type: 'object' },
     };
+    /** Synthesized save_image tool — present when a workspace module is
+     *  registered. Lets the agent persist an image it has already seen in its
+     *  own context (Discord attachments arrive inlined as base64 and are
+     *  otherwise unreachable as files). */
+    static SAVE_IMAGE_TOOL = {
+        name: 'save_recent_image',
+        description: 'Save one or more recent images from your own context to workspace files. ' +
+            'Images are counted back from the most recent (index 0). A single image is ' +
+            'written to `path` as given (e.g. "project/photos/cat.png"); when `count` > 1 ' +
+            'the range index..index+count-1 is saved with numeric suffixes ' +
+            '("cat-0.png", "cat-1.png", …; 0 = the newest of the range). Saved files are ' +
+            'visible via workspace tools and the /files/ endpoint.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                path: {
+                    type: 'string',
+                    description: 'Mount-prefixed destination path, e.g. "project/photos/name.png".',
+                },
+                index: {
+                    type: 'number',
+                    description: 'Which image, counting back from the most recent (0 = most recent). Default 0.',
+                },
+                count: {
+                    type: 'number',
+                    description: 'How many images to save, starting at `index` and going further back. Default 1.',
+                },
+            },
+            required: ['path'],
+        },
+    };
     static AGENT_SETTINGS_TOOL = {
         name: 'agent_settings',
         description: 'Read or change your hot runtime settings. This intentionally exposes only ' +
-            'context budget, recent raw tail size, and transition pace; model, prompts, ' +
+            'context budget, recent raw tail size, transition pace, and same-round think text routing; model, prompts, ' +
             'folding strategy, and other restart-bound configuration are not mutable here. ' +
             'Lower context budgets converge gradually under the transition pace before ' +
             'becoming the hard live limit; increases take effect immediately.',
@@ -1337,9 +1547,15 @@ export class AgentFramework {
                 context_budget_tokens: { type: 'number', description: 'Total input context budget, including the reserved response allowance.' },
                 tail_tokens: { type: 'number', description: 'Recent raw context retained verbatim.' },
                 transition_pace_tokens: { type: 'number', description: 'Maximum ordinary KV re-read/perturbation per compile while converging.' },
+                same_round_think_text_policy: {
+                    type: 'string',
+                    enum: ['public', 'private'],
+                    description: 'Routing policy for ordinary text emitted in the same native assistant round as think(). ' +
+                        "Omitted in the recipe preserves the compatibility carry-forward: public.",
+                },
                 settings: {
                     type: 'array',
-                    items: { type: 'string', enum: ['context_budget_tokens', 'tail_tokens', 'transition_pace_tokens'] },
+                    items: { type: 'string', enum: ['context_budget_tokens', 'tail_tokens', 'transition_pace_tokens', 'same_round_think_text_policy'] },
                     description: 'For reset: settings to restore to recipe values. Omit to reset all.',
                 },
             },
@@ -1727,8 +1943,25 @@ export class AgentFramework {
                 };
             }
             const target = allMessages[allMessages.length - 1 - n];
-            const branchName = cm.branchAt(target.id, `undo-msgs/${agentName}/${Date.now()}`);
+            const discarded = allMessages.slice(allMessages.length - n);
+            const removedRefs = extractDiscordAwarenessRefs(discarded);
+            const sourceBranch = this.store.currentBranch().name;
+            const targetBranch = `undo-msgs/${agentName}/${Date.now()}`;
+            // Prepare the external side effect before switching Chronicle. If the
+            // process dies after the switch but before activate(), startup promotes
+            // this batch by matching targetBranch to the active branch.
+            const markerBatch = this.discordAwarenessOutbox?.prepare({
+                agentName,
+                sourceBranch,
+                targetBranch,
+                refs: removedRefs,
+                emoji: this.discordAwarenessEmoji,
+            }) ?? null;
+            const branchName = cm.branchAt(target.id, targetBranch);
             await cm.switchBranch(branchName);
+            if (markerBatch)
+                this.discordAwarenessOutbox.activate(markerBatch.id);
+            await this.syncDiscordAwarenessMarkers();
             // Materialize config files from the new branch (fire-and-forget; gate
             // picks up via mtime) — mirrors undoLastTurn.
             const wsUndo = this.moduleRegistry.getModule('workspace');
@@ -1742,6 +1975,7 @@ export class AgentFramework {
             return {
                 ok: true,
                 messagesRemoved: n,
+                removedRefs,
                 lastVisible: await this.lastVisiblePreview(agentName),
             };
         }
@@ -1768,6 +2002,7 @@ export class AgentFramework {
         if (undone === 0) {
             return { ok: true, undone: 0, requested, lastVisible: null };
         }
+        await this.syncDiscordAwarenessMarkers();
         return { ok: true, undone, requested, lastVisible: await this.lastVisiblePreview(agentName) };
     }
     /**
@@ -2264,8 +2499,9 @@ export class AgentFramework {
         });
         const agent = new Agent(config, contextManager, this.membrane);
         const restoredSettings = this.readAgentRuntimeSettings(config.name);
-        if (restoredSettings)
-            agent.restoreRuntimeSettings(restoredSettings);
+        if (restoredSettings) {
+            agent.restoreRuntimeSettings(this.validatePersistedAgentRuntimeSettings(config.name, restoredSettings));
+        }
         this.agents.set(config.name, agent);
         this.agentConfigs.set(config.name, config);
         // First non-ephemeral agent becomes the primary for message routing
@@ -2294,13 +2530,22 @@ export class AgentFramework {
         this.sweepExpiredConversations();
         // Check for inference requests
         await this.processInferenceRequests();
-        // Yield to the event loop between iterations.
-        // Full 10ms sleep when truly idle; minimal yield when streams are active
-        // (needed to let stream microtasks and tool-call callbacks execute).
-        if (!event && this.pendingRequests.length === 0) {
+        // Yield to the event loop between iterations. A pending inference request
+        // is not necessarily runnable: while its agent is streaming or waiting for
+        // tools, processInferenceRequests() deliberately requeues it. Treating that
+        // requeued request as "work made progress" creates a microtask-only polling
+        // loop. If activeStreams bookkeeping is absent/stale at the same time, the
+        // old code had no await at all and starved the tool-result and HTTP I/O that
+        // could make the agent runnable again (the Sol outage, 2026-07-15).
+        //
+        // No queue event means no foreground progress, so always take the normal
+        // polling backoff. After an event, retain the low-latency macrotask yield
+        // while background work remains. Both paths give Bun/Node a real event-loop
+        // turn; neither can recurse forever through already-resolved promises.
+        if (!event) {
             await new Promise((resolve) => setTimeout(resolve, 10));
         }
-        else if (this.activeStreams.size > 0) {
+        else if (this.pendingRequests.length > 0 || this.activeStreams.size > 0) {
             await new Promise((resolve) => setTimeout(resolve, 0));
         }
     }
@@ -2403,6 +2648,21 @@ export class AgentFramework {
                             }
                         }
                     }
+                    // A newly injected message begins a new conversational round inside
+                    // the same provider inference. Remember that boundary for
+                    // driveStream: an explicit send in the preceding round must not
+                    // silence the reply, and the newest channel-bearing injection is
+                    // now the reply locus. Map presence matters even without a channel
+                    // (CLI/module input): it still clears the prior send suppression.
+                    if (midTurnInjections.length > 0) {
+                        const injectedChannelId = midTurnInjections.reduce((latest, injection) => {
+                            const candidate = injection.metadata?.channelId;
+                            return typeof candidate === 'string' && candidate.length > 0
+                                ? candidate
+                                : latest;
+                        }, null);
+                        this.midTurnRoutingResets.set(agent.name, injectedChannelId);
+                    }
                     // Check if any tool result requested endTurn
                     const shouldEndTurn = currentState.toolResults.some(tc => tc.result.endTurn);
                     // Check if accumulated input tokens exceed the agent's budget
@@ -2964,7 +3224,13 @@ export class AgentFramework {
             if (agent.state.status === 'inferring' || agent.state.status === 'streaming' || agent.state.status === 'waiting_for_tools') {
                 // Re-queue requests, but warn if they've been pending too long
                 const oldest = Math.min(...requests.map(r => r.timestamp));
-                if (now - oldest > STALE_REQUEST_MS) {
+                if (now - oldest > STALE_REQUEST_MS &&
+                    (this.staleWarnAt.get(agentName) ?? 0) < now - 60_000) {
+                    // Trace and stderr share the throttle. The old code throttled only
+                    // stderr, so a long-running tool call generated one trace per poll
+                    // (up to 100/sec after the scheduler backoff), adding avoidable work
+                    // precisely while the agent was already under pressure.
+                    this.staleWarnAt.set(agentName, now);
                     this.emitTrace({
                         type: 'inference:request_stale',
                         agentName,
@@ -2972,12 +3238,8 @@ export class AgentFramework {
                         requestCount: requests.length,
                         oldestRequestAge: now - oldest,
                     });
-                    // Loud (but throttled) note that requests are waiting on a busy agent.
-                    if ((this.staleWarnAt.get(agentName) ?? 0) < now - 60_000) {
-                        this.staleWarnAt.set(agentName, now);
-                        console.error(`[inference-stale] agent=${agentName} busy (${agent.state.status}) — ` +
-                            `${requests.length} request(s) waiting ${Math.round((now - oldest) / 1000)}s`);
-                    }
+                    console.error(`[inference-stale] agent=${agentName} busy (${agent.state.status}) — ` +
+                        `${requests.length} request(s) waiting ${Math.round((now - oldest) / 1000)}s`);
                 }
                 this.pendingRequests.push(...requests);
                 continue;
@@ -3028,7 +3290,8 @@ export class AgentFramework {
         this.eventGate?.onInferenceStarted(agent.name);
         this.lastInferenceAt.set(agent.name, { ...this.lastInferenceAt.get(agent.name), startedAt: Date.now() });
         try {
-            const allTools = this.getAllTools();
+            const requestSnapshot = this.captureInferenceToolSnapshot(agent);
+            const allTools = this.getToolsForAgent(agent.name, requestSnapshot);
             const tools = allTools.filter((t) => agent.canUseTool(t.name));
             // Gather context from modules (pull-based) and MCPL hooks (push-based)
             // Both produce ContextInjection[] that get merged before inference.
@@ -3061,7 +3324,7 @@ export class AgentFramework {
                 }
             }
             const { stream, request: compiledRequest } = await agent.startStreamWithInjections(tools, injections);
-            const handle = this.driveStream(agent, stream, trigger, attempt, compiledRequest);
+            const handle = this.driveStream(agent, stream, requestSnapshot, trigger, attempt, compiledRequest);
             this.activeStreams.set(agent.name, handle);
         }
         catch (error) {
@@ -3104,23 +3367,21 @@ export class AgentFramework {
             }
         }
     }
-    async driveStream(agent, stream, trigger, attempt = 0, compiledRequest) {
+    async driveStream(agent, stream, requestSnapshot, trigger, attempt = 0, compiledRequest) {
         const startTime = Date.now();
         const requestId = `${agent.name}-${startTime}-${Math.random().toString(36).slice(2, 8)}`;
         const myStreamId = agent.streamId;
         let hadToolCalls = false;
         // ---- Present-while-acting turn state ---------------------------------
-        // Output locus for THIS turn: resolved lazily at the first routed prose
-        // segment and pinned for the rest of the turn (mid-turn rounds AND the
-        // trailing prose at 'complete'), so one turn's voice stays in one channel
-        // even when a queued inbound from another channel overwrites the
-        // per-agent triggering channel between segments (PR #32). The pin lives
-        // in `turnLocusPins` so it survives a context-budget stream restart. A
-        // null resolution is NOT pinned — a turn whose locus is unresolvable
-        // early (e.g. heartbeat-triggered) may still resolve a channel by the
-        // time later prose routes.
+        // Output locus for the current CONVERSATIONAL ROUND: resolved lazily and
+        // kept stable across tool-only rounds. A channel message injected at a
+        // tool boundary replaces the pin before the next model round, because a
+        // single provider inference can now contain several conversations. The
+        // pin lives in `turnLocusPins` so it survives a context-budget restart. A
+        // null resolution is not pinned.
         if (trigger?.reason !== 'context_budget_restart') {
             this.turnLocusPins.delete(agent.name);
+            this.midTurnRoutingResets.delete(agent.name);
         }
         const resolveTurnLocus = () => {
             let locus = this.turnLocusPins.get(agent.name) ?? null;
@@ -3146,10 +3407,9 @@ export class AgentFramework {
             })
                 .catch((err) => console.error('mid-turn speech routing failed:', err));
         };
-        // Sticky silencing: once any round uses a SILENCING_TOOLS member,
-        // prose from that round ONWARD is suppressed — skip_reply means "stay
-        // silent", an explicit send means "I deliver my own words". Earlier
-        // rounds' prose was already delivered live and cannot be retracted.
+        // Sticky explicit-send suppression: prose after send_message stays quiet
+        // to prevent a redundant "sent it" postscript. Fresh injected input
+        // clears it, because the following prose is a reply to a new message.
         let turnSilenced = false;
         // Live routing is only trusted when the membrane provides verbatim
         // round-scoped blocks (roundContent, native tool mode, membrane ≥0.5.64).
@@ -3164,11 +3424,29 @@ export class AgentFramework {
         // 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
+        let typingChannel = this.channelRegistry
             ? trigger?.channelId ?? this.channelRegistry.getDefaultPublishChannel()
             : null;
         if (typingChannel)
             this.channelRegistry.startTyping(typingChannel);
+        const adoptInjectedRound = () => {
+            if (!this.midTurnRoutingResets.has(agent.name))
+                return;
+            const nextLocus = this.midTurnRoutingResets.get(agent.name) ?? null;
+            this.midTurnRoutingResets.delete(agent.name);
+            // A new human/agent message, not merely a tool result, means any earlier
+            // explicit delivery has completed its conversational job.
+            turnSilenced = false;
+            if (nextLocus) {
+                this.turnLocusPins.set(agent.name, nextLocus);
+                if (typingChannel !== nextLocus) {
+                    if (typingChannel)
+                        this.channelRegistry?.stopTyping(typingChannel);
+                    typingChannel = nextLocus;
+                    this.channelRegistry?.startTyping(nextLocus);
+                }
+            }
+        };
         try {
             for await (const event of stream) {
                 this.touchEphemeralRun(agent.name, true);
@@ -3194,6 +3472,7 @@ export class AgentFramework {
                         break;
                     }
                     case 'tool-calls': {
+                        adoptInjectedRound();
                         hadToolCalls = true;
                         this.recordEphemeralToolCalls(agent.name, event.calls.length);
                         this.emitTrace({
@@ -3245,6 +3524,8 @@ export class AgentFramework {
                         // note above — the fallback preamble is cumulative in XML mode).
                         if (this.channelRegistry) {
                             const roundToolNames = event.calls.map((c) => c.name);
+                            const hasSameRoundPrivateThink = roundToolNames.includes('think') &&
+                                requestSnapshot.sameRoundThinkTextPolicy === 'private';
                             if (roundToolNames.some((n) => SILENCING_TOOLS.has(bareToolName(n)))) {
                                 turnSilenced = true;
                             }
@@ -3255,6 +3536,9 @@ export class AgentFramework {
                                     if (turnSilenced) {
                                         console.error(`[routing] ${agent.name}: mid-turn round [${roundToolNames.join(', ')}] -> prose NOT routed (turn silenced)`);
                                     }
+                                    else if (hasSameRoundPrivateThink) {
+                                        console.error(`[routing] ${agent.name}: mid-turn round [${roundToolNames.join(', ')}] -> prose NOT routed (same_round_think_text_policy=private)`);
+                                    }
                                     else {
                                         const locus = resolveTurnLocus();
                                         console.error(`[routing] ${agent.name}: mid-turn round [${roundToolNames.join(', ')}] -> routing ${roundSegments.length} prose segment(s) live -> ${locus ?? '(default)'}`);
@@ -3269,6 +3553,7 @@ export class AgentFramework {
                         break;
                     }
                     case 'complete': {
+                        adoptInjectedRound();
                         const durationMs = Date.now() - startTime;
                         const response = event.response;
                         // If the agent is still waiting_for_tools when 'complete' fires
@@ -3546,15 +3831,17 @@ export class AgentFramework {
                             // speech/thoughts split is left untouched (module/TUI rendering
                             // unaffected) — this only governs what reaches the channel.
                             //
-                            // Silencing here is the sticky flag ∪ turn-wide scan: the scan
-                            // (over the whole turn's tool_use blocks) covers the fallback
-                            // path and the "send_message then a 'sent it.' postscript"
-                            // double-post guard; the sticky flag is its live-rounds twin.
+                            // Native round routing uses the live sticky flag, which a fresh
+                            // injected message can reset. The legacy/fallback path has no
+                            // reliable round boundaries, so retain its historical turn-wide
+                            // scan to avoid double-posting.
                             const toolNames = response.content
                                 .filter((b) => b.type === 'tool_use')
                                 .map((b) => b.name)
                                 .filter((n) => typeof n === 'string');
-                            const silenced = turnSilenced || toolNames.some((n) => SILENCING_TOOLS.has(bareToolName(n)));
+                            const silenced = liveProseRouting
+                                ? turnSilenced
+                                : turnSilenced || toolNames.some((n) => SILENCING_TOOLS.has(bareToolName(n)));
                             const segments = splitProseSegments(liveProseRouting ? terminalContent : response.content);
                             // Preserve in-channel ordering: everything enqueued live must
                             // land before the trailing prose. Awaited even when silenced —
@@ -3907,6 +4194,49 @@ export class AgentFramework {
             return maxTokens * 4;
         return undefined;
     }
+    approximateDecodedBase64Bytes(base64) {
+        const padding = base64.endsWith('==') ? 2 : base64.endsWith('=') ? 1 : 0;
+        return Math.max(0, Math.floor(base64.length * 3 / 4) - padding);
+    }
+    sanitizeProcessLogValue(value, seen = new WeakMap()) {
+        if (value && typeof value === 'object') {
+            const seenValue = seen.get(value);
+            if (seenValue)
+                return seenValue;
+        }
+        if (Array.isArray(value)) {
+            const clone = [];
+            seen.set(value, clone);
+            for (const item of value) {
+                clone.push(this.sanitizeProcessLogValue(item, seen));
+            }
+            return clone;
+        }
+        if (!value || typeof value !== 'object') {
+            return value;
+        }
+        const record = value;
+        if (record.type === 'image' && typeof record.data === 'string' && typeof record.mimeType === 'string') {
+            const clone = {};
+            seen.set(value, clone);
+            for (const [key, child] of Object.entries(record)) {
+                if (key === 'data' || key === 'mimeType')
+                    continue;
+                clone[key] = this.sanitizeProcessLogValue(child, seen);
+            }
+            clone.type = 'image';
+            clone.mimeType = record.mimeType;
+            clone.approxByteLength = this.approximateDecodedBase64Bytes(record.data);
+            clone.redacted = true;
+            return clone;
+        }
+        const clone = {};
+        seen.set(value, clone);
+        for (const [key, child] of Object.entries(record)) {
+            clone[key] = this.sanitizeProcessLogValue(child, seen);
+        }
+        return clone;
+    }
     logInference(entry) {
         // Store large request/response as blobs
         const entryToStore = { ...entry };
@@ -3935,13 +4265,13 @@ export class AgentFramework {
     logProcessEvent(event, responses) {
         const entry = {
             timestamp: Date.now(),
-            processEvent: event,
-            responses,
+            processEvent: this.sanitizeProcessLogValue(event),
+            responses: this.sanitizeProcessLogValue(responses),
         };
         // Blob threshold: 10KB
         const BLOB_THRESHOLD = 10000;
         const entryToStore = { ...entry };
-        const responsesJson = JSON.stringify(responses);
+        const responsesJson = JSON.stringify(entry.responses);
         if (responsesJson.length > BLOB_THRESHOLD) {
             const blobId = this.store.storeBlob(Buffer.from(responsesJson), 'application/json');
             entryToStore.responses = { blobId };
@@ -3980,6 +4310,10 @@ export class AgentFramework {
             this.dispatchAgentSettingsToolCall(agentName, enrichedCall);
             return;
         }
+        if (enrichedCall.name === 'save_recent_image') {
+            this.dispatchSaveImageToolCall(agentName, enrichedCall);
+            return;
+        }
         // Route gate_status tool
         if (enrichedCall.name === 'gate_status' && this.eventGate) {
             this.dispatchGateToolCall(agentName, enrichedCall);
@@ -4248,6 +4582,16 @@ export class AgentFramework {
      *     every ~15 min instead of flooding the channel on every occurrence.
      * See connectome docs/observability.md.
      */
+    /**
+     * Public ops-alert entry point for host-wired alarms that originate
+     * OUTSIDE the framework (e.g. context-manager's repeating
+     * compression-quarantine klaxon, wired in the host at strategy
+     * construction). Same sinks and cooldown as internal alerts:
+     * failures.log + ops:alert trace + CONNECTOME_OPS_WEBHOOK.
+     */
+    notifyOps(kind, agentName, message, data) {
+        this.opsAlert(kind, agentName, message, { data });
+    }
     opsAlert(kind, agentName, message, opts) {
         if (!opts?.skipLog) {
             this.logFailure({ agent: agentName, kind, reason: message, ...opts?.data });
@@ -4322,6 +4666,16 @@ export class AgentFramework {
         }
         return {};
     }
+    /**
+     * Public entry to the ops-alert pipeline (failures.log + ops:alert trace +
+     * throttled webhook) for host-level detectors OUTSIDE the framework's own
+     * inference driver — e.g. the host's logging adapter catching refusals on
+     * off-path calls (compression/summarizer, maintenance) that noteRefusal
+     * never sees. Same per-(agent,kind) cooldown as everything else.
+     */
+    notifyOpsAlert(kind, agentName, message, data) {
+        this.opsAlert(kind, agentName, message, { data });
+    }
     noteInferenceExhausted(agentName, reason, retryable, errorType) {
         const streak = (this.consecutiveInferenceFailures.get(agentName) ?? 0) + 1;
         this.consecutiveInferenceFailures.set(agentName, streak);
@@ -4534,9 +4888,17 @@ export class AgentFramework {
         };
         for (const config of serverConfigs) {
             try {
-                await this.connectMcplServerInternal(config);
+                // Stage every startup connection with both planes closed. This removes
+                // server-order dependence: no early heartbeat/shell push can become
+                // model-visible before a later Discord connection has joined the same
+                // awareness generation.
+                await this.connectMcplServerInternal(config, true);
             }
             catch (error) {
+                if (error instanceof DiscordAwarenessAccountingError) {
+                    await this.mcplServerRegistry.closeAll();
+                    throw error;
+                }
                 // Fail-open: log and continue with remaining servers
                 const err = error instanceof Error ? error : new Error(String(error));
                 console.error(`Failed to connect MCPL server "${config.id}":`, err.message);
@@ -4553,16 +4915,289 @@ export class AgentFramework {
                 });
             }
         }
+        // Start the durable drain only after all startup connections are staged.
+        // The awareness tools/call is written before control-plane registration is
+        // flushed, preserving the server-side queue -> registration -> call order.
+        const startupBarrier = this.installMcplDataPlaneGate();
+        this.releaseMcplDataPlaneGate(startupBarrier);
+        try {
+            await startupBarrier.promise;
+            this.completeMcplDataPlaneGate(startupBarrier);
+        }
+        catch (error) {
+            await this.mcplServerRegistry.closeAll();
+            throw error;
+        }
         // Discover tools from all connected servers
         await this.refreshMcplTools();
     }
+    /** Reconcile the durable ledger with Chronicle, then deliver every server's work. */
+    async syncDiscordAwarenessMarkers(_onlyServerId) {
+        if (!this.discordAwarenessOutbox)
+            return;
+        // A targeted retry may discover pending work for other Discord servers
+        // during reconciliation. Safety is global, so one generation accounts for
+        // all pending operations before releasing any MCPL data plane.
+        const barrier = this.installMcplDataPlaneGate();
+        this.releaseMcplDataPlaneGate(barrier);
+        try {
+            await barrier.promise;
+            this.completeMcplDataPlaneGate(barrier);
+        }
+        catch (error) {
+            await this.failMcplDataPlaneGate(barrier, 'explicit synchronization', error);
+            throw error;
+        }
+    }
+    async resumePreparedDiscordSuppressions() {
+        if (!this.discordAwarenessOutbox)
+            return;
+        const batches = this.discordAwarenessOutbox.preparedSuppressionsForBranch(this.store.currentBranch().name, this.store.listBranches());
+        for (const batch of batches) {
+            const agent = this.agents.get(batch.agentName);
+            if (!agent) {
+                throw new Error(`Cannot resume Discord suppression ${batch.id}: agent ${batch.agentName} is not configured`);
+            }
+            const cm = agent.getContextManager();
+            for (const interval of [...(batch.suppressionIntervals ?? [])].reverse()) {
+                const from = cm.getMessage(interval.fromId);
+                const to = cm.getMessage(interval.toId);
+                if (!from && !to)
+                    continue; // This interval committed before the crash.
+                if (!from || !to) {
+                    throw new Error(`Cannot safely resume Discord suppression ${batch.id}: interval ` +
+                        `${interval.fromId}..${interval.toId} is only partially present`);
+                }
+                if (interval.fromId === interval.toId)
+                    cm.removeMessage(from.id);
+                else
+                    cm.removeMessages(from.id, to.id);
+            }
+            this.discordAwarenessOutbox.activate(batch.id);
+            console.error(`[discord-awareness] resumed suppression batch ${batch.id}`);
+        }
+    }
+    /**
+     * Deliver every due ref independently. Permanent Discord failures are kept
+     * in the ledger for audit but do not block later operations; retryable
+     * failures remain pending for the next reconnect/list-change attempt.
+     */
+    drainDiscordAwarenessOutbox(serverId) {
+        if (!this.discordAwarenessOutbox) {
+            return Promise.resolve({ status: 'delivered', delivered: 0, failed: 0 });
+        }
+        const existing = this.discordAwarenessDrains.get(serverId);
+        if (existing)
+            return existing;
+        const drain = (async () => {
+            const connection = this.mcplServerRegistry?.getServer(serverId);
+            if (!connection?.isConnected) {
+                const operations = this.readDiscordAwarenessPending(serverId);
+                for (const operation of operations) {
+                    this.writeDiscordAwarenessFailure(operation.batchId, operation.ref, operation.action, 'Awareness delivery not attempted: MCPL connection unavailable', false);
+                }
+                if (operations.length > 0) {
+                    console.error(`[discord-awareness] ${serverId}: connection unavailable; ` +
+                        `durably deferred=${operations.length}`);
+                }
+                return { status: 'unavailable', accounted: operations.length };
+            }
+            let delivered = 0;
+            let failed = 0;
+            const attempted = new Set();
+            while (true) {
+                const operations = this.readDiscordAwarenessPending(serverId).filter((operation) => {
+                    const key = `${operation.batchId}\0${operation.ref.channelId}\0${operation.ref.messageId}\0${operation.action}`;
+                    if (attempted.has(key))
+                        return false;
+                    attempted.add(key);
+                    return true;
+                });
+                if (operations.length === 0)
+                    break;
+                for (const operation of operations) {
+                    const ref = operation.ref;
+                    const channelId = ref.channelId.startsWith('discord:')
+                        ? ref.channelId.split(':').at(-1)
+                        : ref.channelId;
+                    let deliveryError;
+                    try {
+                        const tool = operation.action === 'add' ? 'add_reaction' : 'remove_reaction';
+                        const result = await connection.sendToolsCallWithDeadline(tool, {
+                            channelId,
+                            messageId: ref.messageId,
+                            emoji: operation.emoji,
+                        }, this.discordAwarenessDeadlineMs);
+                        if (result.isError) {
+                            deliveryError = result.content
+                                .map((content) => content.text ?? '')
+                                .filter(Boolean)
+                                .join('; ') || `Discord ${tool} returned an error`;
+                        }
+                    }
+                    catch (error) {
+                        deliveryError = error instanceof Error ? error.message : String(error);
+                    }
+                    if (deliveryError !== undefined) {
+                        const permanent = isPermanentDiscordReactionFailure(deliveryError);
+                        this.writeDiscordAwarenessFailure(operation.batchId, ref, operation.action, deliveryError, permanent);
+                        failed++;
+                        console.error(`[discord-awareness] ${operation.action} failed for ${ref.channelId}/${ref.messageId}` +
+                            ` (${permanent ? 'permanent' : 'retryable'}): ${deliveryError}`);
+                    }
+                    else {
+                        this.writeDiscordAwarenessSuccess(operation.batchId, ref, operation.action);
+                        delivered++;
+                    }
+                }
+            }
+            if (delivered > 0 || failed > 0) {
+                console.error(`[discord-awareness] ${serverId}: delivered=${delivered} failed=${failed}`);
+            }
+            return { status: 'delivered', delivered, failed };
+        })().finally(() => {
+            this.discordAwarenessDrains.delete(serverId);
+        });
+        this.discordAwarenessDrains.set(serverId, drain);
+        return drain;
+    }
+    readDiscordAwarenessPending(serverId) {
+        try {
+            return this.discordAwarenessOutbox.pending(serverId);
+        }
+        catch (error) {
+            throw new DiscordAwarenessAccountingError(`ledger read${serverId ? ` for ${serverId}` : ''}`, error);
+        }
+    }
+    writeDiscordAwarenessSuccess(batchId, ref, action) {
+        try {
+            this.discordAwarenessOutbox.recordSuccess(batchId, ref, action);
+        }
+        catch (error) {
+            throw new DiscordAwarenessAccountingError('recordSuccess ledger write', error);
+        }
+    }
+    writeDiscordAwarenessFailure(batchId, ref, action, errorMessage, permanent) {
+        try {
+            this.discordAwarenessOutbox.recordFailure(batchId, ref, action, errorMessage, permanent);
+        }
+        catch (error) {
+            throw new DiscordAwarenessAccountingError('recordFailure ledger write', error);
+        }
+    }
+    beginDiscordAwarenessBarrier() {
+        if (!this.discordAwarenessOutbox) {
+            return {
+                requiresBarrier: false,
+                promise: Promise.resolve({ status: 'delivered', delivered: 0, failed: 0 }),
+            };
+        }
+        try {
+            this.discordAwarenessOutbox.reconcileForBranch(this.store.currentBranch().name, this.store.listBranches());
+        }
+        catch (error) {
+            throw new DiscordAwarenessAccountingError('branch reconciliation', error);
+        }
+        const pending = this.readDiscordAwarenessPending();
+        if (pending.length === 0) {
+            return {
+                requiresBarrier: false,
+                promise: Promise.resolve({ status: 'delivered', delivered: 0, failed: 0 }),
+            };
+        }
+        const serverIds = [...new Set(pending.map((operation) => operation.ref.serverId))];
+        const promise = Promise.all(serverIds.map((serverId) => this.drainDiscordAwarenessOutbox(serverId))).then((outcomes) => {
+            if (outcomes.every((outcome) => outcome.status === 'unavailable')) {
+                return {
+                    status: 'unavailable',
+                    accounted: outcomes.reduce((count, outcome) => count + (outcome.status === 'unavailable' ? outcome.accounted : 0), 0),
+                };
+            }
+            return {
+                status: 'delivered',
+                delivered: outcomes.reduce((count, outcome) => count + (outcome.status === 'delivered' ? outcome.delivered : 0), 0),
+                failed: outcomes.reduce((count, outcome) => count + (outcome.status === 'delivered' ? outcome.failed : 0), 0),
+            };
+        });
+        return { requiresBarrier: true, promise };
+    }
+    /**
+     * Install one framework-global Discord-awareness generation before releasing
+     * any inference-bearing event. With pending work, every MCPL data plane is
+     * paused while all control planes remain live. With no pending work, ready()
+     * runs synchronously so request responders preserve their historical
+     * same-stack behavior.
+     */
+    installMcplDataPlaneGate() {
+        for (const connection of this.mcplServerRegistry?.getAllServers() ?? []) {
+            connection.pauseDataPlane();
+        }
+        const generation = ++this.discordAwarenessBarrierGeneration;
+        let begun;
+        try {
+            begun = this.beginDiscordAwarenessBarrier();
+        }
+        catch (error) {
+            begun = {
+                requiresBarrier: true,
+                promise: Promise.reject(error),
+            };
+        }
+        const barrier = { generation, ...begun };
+        this.discordAwarenessBarrier = barrier;
+        return barrier;
+    }
+    releaseMcplDataPlaneGate(barrier) {
+        if (this.discordAwarenessBarrier !== barrier)
+            return;
+        if (barrier.requiresBarrier) {
+            for (const connection of this.mcplServerRegistry?.getAllServers() ?? []) {
+                connection.readyControlPlane();
+            }
+            return;
+        }
+        this.completeMcplDataPlaneGate(barrier);
+    }
+    completeMcplDataPlaneGate(barrier) {
+        if (this.discordAwarenessBarrier !== barrier)
+            return false;
+        this.discordAwarenessBarrier = null;
+        for (const connection of this.mcplServerRegistry?.getAllServers() ?? []) {
+            // ready() can synchronously flush a nested list-change notification that
+            // installs a newer global generation. Never let this older completion
+            // release any remaining server behind that newer gate.
+            if (this.discordAwarenessBarrier !== null)
+                return false;
+            connection.ready();
+        }
+        return this.discordAwarenessBarrier === null;
+    }
+    async failMcplDataPlaneGate(barrier, context, error) {
+        if (this.discordAwarenessBarrier !== barrier)
+            return;
+        const err = error instanceof Error ? error : new Error(String(error));
+        console.error(`[discord-awareness] ${context} failed globally:`, err.message);
+        const connections = this.mcplServerRegistry?.getAllServers() ?? [];
+        for (const connection of connections) {
+            this.emitTrace({
+                type: 'mcpl:server-error',
+                serverId: connection.id,
+                error: `Discord awareness accounting unhealthy: ${err.message}`,
+            });
+        }
+        await Promise.all(connections.map(async (connection) => {
+            await connection.reconnectAfterFailure().catch((closeError) => {
+                console.error(`[discord-awareness] could not recycle unhealthy connection ${connection.id}:`, closeError instanceof Error ? closeError.message : closeError);
+            });
+        }));
+    }
     /**
      * Connect a single MCPL server: register routing entries, open the
      * connection, wire events, and initialize feature sets / scopes /
      * checkpoints. Shared by startup (initializeMcpl) and the runtime
      * lifecycle API (connectMcplServer). Throws on connection failure.
      */
-    async connectMcplServerInternal(config) {
+    async connectMcplServerInternal(config, deferAwareness = false) {
         if (!this.mcplServerRegistry || !this.mcplHostCapabilities) {
             throw new Error('MCPL subsystem is not initialized');
         }
@@ -4577,12 +5212,28 @@ export class AgentFramework {
             this.channelRegistry.setSubscriptionPolicy(config.id, config.channelSubscription ?? 'manual');
         }
         const connection = await this.mcplServerRegistry.addServer(config, this.mcplHostCapabilities);
-        // Wire event listeners then flush any events that arrived during the
-        // handshake window (between setupMessageRouting and now).
+        // Wire listeners before either startup staging or the runtime global gate
+        // releases control traffic needed for registration and marker service.
         this.wireMcplEvents(connection);
-        connection.ready();
         // Initialize feature sets if server advertises MCPL capabilities
         this.registerMcplServerFeatures(config, connection);
+        if (deferAwareness) {
+            this.emitTrace({ type: 'module:added', moduleName: `mcpl:${config.id}` });
+            return;
+        }
+        const awarenessBarrier = this.installMcplDataPlaneGate();
+        this.releaseMcplDataPlaneGate(awarenessBarrier);
+        try {
+            await awarenessBarrier.promise;
+            this.completeMcplDataPlaneGate(awarenessBarrier);
+        }
+        catch (error) {
+            // Startup cannot fail open on a broken awareness ledger. Disable the
+            // reconnecting stub/connection before propagating the distinct error to
+            // initializeMcpl, which tears down any other servers and aborts create().
+            await connection.close().catch(() => { });
+            throw error;
+        }
         this.emitTrace({ type: 'module:added', moduleName: `mcpl:${config.id}` });
     }
     /**
@@ -4749,12 +5400,18 @@ export class AgentFramework {
             }
         });
         // Handle push events (Step 6)
-        connection.on('push-event', (params, responder) => {
+        connection.on('push-event', async (params, responder) => {
+            const barrier = this.discordAwarenessBarrier;
+            if (barrier)
+                await barrier.promise;
             this.pushHandler?.handlePushEvent(connection.id, params, responder);
         });
         // Handle server-initiated inference requests (Step 6)
         connection.on('inference-request', async (params, responder) => {
             if (this.inferenceRouter && responder) {
+                const barrier = this.discordAwarenessBarrier;
+                if (barrier)
+                    await barrier.promise;
                 await this.inferenceRouter.handleInferenceRequest(connection.id, params, {
                     respond: responder.respond,
                     respondError: responder.respondError,
@@ -4771,7 +5428,10 @@ export class AgentFramework {
             await this.channelRegistry?.handleChanged(connection.id, params);
         });
         // Handle incoming channel messages (Step 7)
-        connection.on('channels-incoming', (params, responder) => {
+        connection.on('channels-incoming', async (params, responder) => {
+            const barrier = this.discordAwarenessBarrier;
+            if (barrier)
+                await barrier.promise;
             this.channelRegistry?.handleIncoming(connection.id, params, responder);
         });
         // Handle host-level admin commands from a surface (e.g. Discord /undo)
@@ -4779,6 +5439,9 @@ export class AgentFramework {
             if (!responder)
                 return;
             try {
+                const barrier = this.discordAwarenessBarrier;
+                if (barrier)
+                    await barrier.promise;
                 const result = await this.handleHostCommand(connection.id, params ?? {});
                 responder.respond(result);
             }
@@ -4789,7 +5452,15 @@ export class AgentFramework {
         });
         // Handle dynamic tool list changes (notifications/tools/list_changed)
         connection.on('tools-list-changed', () => {
+            // Pause before starting any async refresh. This listener runs
+            // synchronously in the transport line callback, so a following inbound
+            // data event cannot pass before the new barrier exists.
+            const awarenessBarrier = this.installMcplDataPlaneGate();
+            this.releaseMcplDataPlaneGate(awarenessBarrier);
             this.handleToolsListChanged(connection.id);
+            void awarenessBarrier.promise.then(() => {
+                this.completeMcplDataPlaneGate(awarenessBarrier);
+            }).catch((error) => this.failMcplDataPlaneGate(awarenessBarrier, 'tools-list reconciliation', error));
         });
         // Re-establish full server registration on reconnect. The 'close' handler
         // removed the feature-set state, so pushes / inference requests from the
@@ -4799,6 +5470,10 @@ export class AgentFramework {
         // preserved across the transient close are resumed by idempotent
         // registration. Then refresh tools (server may have different tools).
         connection.on('reconnect', (info) => {
+            // Install the barrier synchronously so any inbound event emitted after
+            // reconnect observes it before doing work that could wake an agent. The
+            // connection paused its data plane before wiring the fresh transport.
+            const awarenessBarrier = this.installMcplDataPlaneGate();
             try {
                 const config = this.mcplServerConfigs.get(connection.id);
                 if (config) {
@@ -4808,15 +5483,21 @@ export class AgentFramework {
             catch (error) {
                 console.error(`MCPL server "${connection.id}" re-registration after reconnect failed:`, error instanceof Error ? error.message : error);
             }
+            this.releaseMcplDataPlaneGate(awarenessBarrier);
             this.handleToolsListChanged(connection.id);
-            this.emitTrace({
-                type: 'mcpl:server-reconnected',
-                serverId: connection.id,
-                attempts: info?.attempts ?? 0,
-            });
-            // Mirror the module:removed emitted on 'close' so module-lifecycle
-            // consumers see the server come back, not just vanish.
-            this.emitTrace({ type: 'module:added', moduleName: `mcpl:${connection.id}` });
+            void awarenessBarrier.promise.then(() => {
+                if (awarenessBarrier.requiresBarrier
+                    && !this.completeMcplDataPlaneGate(awarenessBarrier))
+                    return;
+                this.emitTrace({
+                    type: 'mcpl:server-reconnected',
+                    serverId: connection.id,
+                    attempts: info?.attempts ?? 0,
+                });
+                // Mirror the module:removed emitted on 'close' so module-lifecycle
+                // consumers see the server come back, not just vanish.
+                this.emitTrace({ type: 'module:added', moduleName: `mcpl:${connection.id}` });
+            }).catch((error) => this.failMcplDataPlaneGate(awarenessBarrier, 'reconnect reconciliation', error));
         });
         // Surface connect/reconnect failures. Before these traces existed the
         // only receipt was a console.error on the host's own stderr — invisible
@@ -4855,6 +5536,7 @@ export class AgentFramework {
                 type: 'mcpl:orphaned-response',
                 serverId: connection.id,
                 responseId: info.id,
+                method: info.method,
                 hadState: info.hadState,
                 hadCheckpoint: info.hadCheckpoint,
             });
@@ -5280,6 +5962,143 @@ export class AgentFramework {
             endTurn: true,
         });
     }
+    /**
+     * Handle the synthesized `save_recent_image` tool: locate the requested
+     * image blocks in the calling agent's context (blobs re-inlined, counted
+     * back from the most recent) and write their bytes to a workspace mount
+     * via WorkspaceModule.writeBinary.
+     */
+    dispatchSaveImageToolCall(agentName, call) {
+        this.emitTrace({ type: 'tool:started', module: 'workspace', tool: call.name, callId: call.id, input: call.input });
+        const finish = (result) => {
+            this.emitTrace({
+                type: result.isError ? 'tool:failed' : 'tool:completed',
+                module: 'workspace',
+                tool: call.name,
+                callId: call.id,
+                durationMs: 0,
+                ...(result.isError ? { error: result.error } : {}),
+            });
+            this.pushEvent({ type: 'tool-result', callId: call.id, agentName, moduleName: 'workspace', result });
+        };
+        void (async () => {
+            try {
+                const workspace = this.getWorkspaceModule();
+                if (!workspace)
+                    throw new Error('save_recent_image requires a workspace module');
+                const agent = this.agents.get(agentName);
+                if (!agent)
+                    throw new Error(`Unknown agent: ${agentName}`);
+                const input = (call.input ?? {});
+                if (typeof input.path !== 'string' || input.path.length === 0) {
+                    throw new Error('save_recent_image: `path` (mount-prefixed) is required');
+                }
+                const index = input.index === undefined ? 0 : Number(input.index);
+                if (!Number.isInteger(index) || index < 0) {
+                    throw new Error('save_recent_image: `index` must be a non-negative integer');
+                }
+                const count = input.count === undefined ? 1 : Number(input.count);
+                const MAX_COUNT = 20;
+                if (!Number.isInteger(count) || count < 1 || count > MAX_COUNT) {
+                    throw new Error(`save_recent_image: \`count\` must be an integer in 1..${MAX_COUNT}`);
+                }
+                const lastWanted = index + count - 1;
+                // Walk the message store tail-first in bounded windows, re-inlining
+                // blob media, until we've collected the requested range. Scanning is
+                // capped so a pathological index can't drag the whole store through
+                // blob resolution.
+                const MAX_SCAN = 500;
+                const WINDOW = 25;
+                const cm = agent.getContextManager();
+                const total = cm.getMessageCount();
+                let seen = 0;
+                let scanned = 0;
+                const found = [];
+                for (let end = total; end > 0 && scanned < MAX_SCAN && found.length < count; end -= WINDOW) {
+                    const start = Math.max(0, end - WINDOW);
+                    const { messages } = cm.getMessageWindow(start, end - start, { resolveBlobs: true });
+                    scanned += end - start;
+                    for (let i = messages.length - 1; i >= 0 && found.length < count; i--) {
+                        const content = messages[i]?.content;
+                        if (!Array.isArray(content))
+                            continue;
+                        for (let b = content.length - 1; b >= 0 && found.length < count; b--) {
+                            const block = content[b];
+                            if (block?.type !== 'image')
+                                continue;
+                            if (seen >= index && seen <= lastWanted) {
+                                if (block.source?.type !== 'base64' || typeof block.source.data !== 'string') {
+                                    throw new Error(`save_recent_image: image at index ${seen} is not stored inline (base64) — cannot save it`);
+                                }
+                                found.push({
+                                    rangeOffset: seen - index,
+                                    data: block.source.data,
+                                    mediaType: block.source.mediaType ?? 'image/png',
+                                    messagesBack: total - (start + i),
+                                });
+                            }
+                            seen++;
+                        }
+                    }
+                }
+                if (found.length === 0) {
+                    throw new Error(seen === 0
+                        ? `save_recent_image: no images found in the most recent ${Math.min(scanned, MAX_SCAN)} messages`
+                        : `save_recent_image: only ${seen} image(s) found in the most recent ${Math.min(scanned, MAX_SCAN)} messages (asked for index ${index})`);
+                }
+                // Single image → path as given. Range → numeric suffix before the
+                // extension ("cat.png" → "cat-0.png"), 0 = newest of the range.
+                const pathFor = (rangeOffset) => {
+                    if (count === 1)
+                        return input.path;
+                    const p = input.path;
+                    const dot = p.lastIndexOf('.');
+                    const slash = p.lastIndexOf('/');
+                    return dot > slash
+                        ? `${p.slice(0, dot)}-${rangeOffset}${p.slice(dot)}`
+                        : `${p}-${rangeOffset}`;
+                };
+                const savedFiles = [];
+                for (const image of found) {
+                    const destination = pathFor(image.rangeOffset);
+                    const bytes = Buffer.from(image.data, 'base64');
+                    const result = await workspace.writeBinary(destination, bytes, image.mediaType);
+                    if (!result.success) {
+                        finish({
+                            success: false,
+                            error: `save_recent_image: failed writing "${destination}": ${result.error}` +
+                                (savedFiles.length > 0
+                                    ? ` (already saved: ${savedFiles.map((f) => f.path).join(', ')})`
+                                    : ''),
+                            isError: true,
+                        });
+                        return;
+                    }
+                    savedFiles.push({
+                        ...result.data,
+                        imageIndex: index + image.rangeOffset,
+                        messagesBack: image.messagesBack,
+                    });
+                }
+                finish({
+                    success: true,
+                    data: {
+                        saved: savedFiles,
+                        ...(found.length < count
+                            ? { note: `only ${found.length} of ${count} requested images exist in the scanned window` }
+                            : {}),
+                    },
+                });
+            }
+            catch (error) {
+                finish({
+                    success: false,
+                    error: error instanceof Error ? error.message : String(error),
+                    isError: true,
+                });
+            }
+        })();
+    }
     dispatchAgentSettingsToolCall(agentName, call) {
         this.emitTrace({
             type: 'tool:started',
@@ -5291,9 +6110,20 @@ export class AgentFramework {
         let result;
         try {
             const input = (call.input ?? {});
+            const extensions = this.collectAgentSettingsExtensions();
+            /** Extension values merged flat alongside the core snapshot. */
+            const extGet = () => {
+                const out = {};
+                for (const ext of extensions.values())
+                    Object.assign(out, ext.get(agentName));
+                return out;
+            };
             switch (input.action) {
                 case 'get':
-                    result = { success: true, data: this.getAgentRuntimeSettings(agentName) };
+                    result = {
+                        success: true,
+                        data: { ...this.getAgentRuntimeSettings(agentName), ...extGet() },
+                    };
                     break;
                 case 'cancel':
                     result = { success: true, data: this.cancelAgentRuntimeSettingsTransition(agentName) };
@@ -5308,11 +6138,46 @@ export class AgentFramework {
                     if (input.transition_pace_tokens !== undefined) {
                         patch.transitionPaceTokens = Number(input.transition_pace_tokens);
                     }
-                    result = { success: true, data: this.updateAgentRuntimeSettings(agentName, patch) };
+                    if (input.same_round_think_text_policy !== undefined) {
+                        patch.sameRoundThinkTextPolicy = input.same_round_think_text_policy;
+                    }
+                    // Route extension-owned keys to their modules; apply the core patch
+                    // only when it touches core keys (an extension-only update must not
+                    // disturb a converging budget transition).
+                    const extResults = {};
+                    for (const ext of extensions.values()) {
+                        const slice = {};
+                        for (const key of ext.keys) {
+                            if (input[key] !== undefined)
+                                slice[key] = input[key];
+                        }
+                        if (Object.keys(slice).length > 0) {
+                            Object.assign(extResults, ext.update(agentName, slice));
+                        }
+                    }
+                    const coreTouched = Object.keys(patch).length > 0;
+                    const core = coreTouched
+                        ? this.updateAgentRuntimeSettings(agentName, patch)
+                        : this.getAgentRuntimeSettings(agentName);
+                    result = {
+                        success: true,
+                        data: {
+                            ...core,
+                            ...extGet(),
+                            ...extResults,
+                            ...(patch.sameRoundThinkTextPolicy !== undefined
+                                ? {
+                                    sameRoundThinkTextPolicyUpdateNote: 'Stored now; applies to provider think routing and description beginning with the next inference.',
+                                }
+                                : {}),
+                        },
+                    };
                     break;
                 }
                 case 'reset': {
                     let keys;
+                    const extResetKeys = new Map();
+                    const resetsAllSettings = input.settings === undefined;
                     if (input.settings !== undefined) {
                         if (!Array.isArray(input.settings))
                             throw new Error('reset `settings` must be an array');
@@ -5320,15 +6185,56 @@ export class AgentFramework {
                             context_budget_tokens: 'contextBudgetTokens',
                             tail_tokens: 'tailTokens',
                             transition_pace_tokens: 'transitionPaceTokens',
+                            same_round_think_text_policy: 'sameRoundThinkTextPolicy',
                         };
-                        keys = input.settings.map((name) => {
-                            if (typeof name !== 'string' || !names[name]) {
-                                throw new Error(`Unknown reset setting: ${String(name)}`);
+                        keys = [];
+                        for (const name of input.settings) {
+                            if (typeof name === 'string' && names[name]) {
+                                keys.push(names[name]);
+                                continue;
                             }
-                            return names[name];
-                        });
+                            const owner = [...extensions.values()].find((ext) => typeof name === 'string' && ext.keys.includes(name));
+                            if (!owner)
+                                throw new Error(`Unknown reset setting: ${String(name)}`);
+                            const list = extResetKeys.get(owner) ?? [];
+                            list.push(name);
+                            extResetKeys.set(owner, list);
+                        }
+                        if (keys.length === 0)
+                            keys = undefined;
+                    }
+                    const touchedSameRoundThinkTextPolicy = resetsAllSettings || keys?.includes('sameRoundThinkTextPolicy') === true;
+                    const extResults = {};
+                    if (input.settings === undefined) {
+                        // Reset-all covers extensions too.
+                        for (const ext of extensions.values()) {
+                            if (ext.reset)
+                                Object.assign(extResults, ext.reset(agentName));
+                        }
                     }
-                    result = { success: true, data: this.resetAgentRuntimeSettings(agentName, keys) };
+                    else {
+                        for (const [ext, list] of extResetKeys) {
+                            if (ext.reset)
+                                Object.assign(extResults, ext.reset(agentName, list));
+                        }
+                    }
+                    const coreTouched = input.settings === undefined || keys !== undefined;
+                    const core = coreTouched
+                        ? this.resetAgentRuntimeSettings(agentName, keys)
+                        : this.getAgentRuntimeSettings(agentName);
+                    result = {
+                        success: true,
+                        data: {
+                            ...core,
+                            ...extGet(),
+                            ...extResults,
+                            ...(touchedSameRoundThinkTextPolicy
+                                ? {
+                                    sameRoundThinkTextPolicyUpdateNote: 'Reset now; restored provider think routing and description apply beginning with the next inference.',
+                                }
+                                : {}),
+                        },
+                    };
                     break;
                 }
                 default: