@animalabs/agent-framework 0.12.0 → 0.14.0

package/dist/src/framework.js

@@ -4,7 +4,9 @@ import { ReferenceFetcher, DEFAULT_FETCH_MAX_BYTES, EAGER_FETCH_TIMEOUT_MS } fro
 import { appendFileSync, mkdirSync } from 'node:fs';
 import { JsStore } from '@animalabs/chronicle';
 import { MembraneError } from '@animalabs/membrane';
-import { ContextManager, PassthroughStrategy } from '@animalabs/context-manager';
+import { ContextManager, PassthroughStrategy, WindowedPassthroughStrategy } from '@animalabs/context-manager';
+import { SUBCONSCIOUS_TOOLS, SUBCONSCIOUS_TOOL_NAMES } from './tune-out/tools.js';
+import { TuneOutCoordinator, TUNE_OUT_DEFAULTS } from './tune-out/coordinator.js';
 import { ProcessQueueImpl } from './queue.js';
 import { REFUSAL_REACTIONS, REFUSAL_REACTION_FALLBACK } from './refusal-reactions.js';
 import { Agent } from './agent.js';
@@ -17,11 +19,13 @@ import { HookOrchestrator } from './mcpl/hook-orchestrator.js';
 import { PushHandler } from './mcpl/push-handler.js';
 import { parseProsePrefix, parseHybridProsePrefix } from './mcpl/prose-grammar.js';
 import { ProseStreamRouter } from './mcpl/prose-stream-router.js';
+import { detectKnownToolWrapperProse } from './tool-wrapper-prose-guard.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, truncateForHistory, DEFAULT_TOOL_RESULT_INLINE_MAX_CHARS, } from './tool-result-history.js';
+import { TOOL_IMAGE_REF_RE, ToolImageLedger, formatPreservedImageSlots, parseImagePlaceholders, sha256Hex, splitPreservingImageSlots, } from './tool-image-ledger.js';
 import { randomUUID } from 'node:crypto';
 import { PyRunner, buildInjectedTools } from './code-execution/py-runner.js';
 import { buildCodeExecutionToolDefinition, CODE_EXECUTION_TOOL_NAME, } from './code-execution/tool-definition.js';
@@ -522,6 +526,16 @@ export class AgentFramework {
     frameworkCancelledStreams = new Map();
     /** Active runEphemeralToCompletion runs, keyed by agent name. */
     ephemeralRuns = new Map();
+    /** Ephemeral namespaces/names are single-generation for this framework
+     * lifetime. Reusing one while an old stream drains would let name-keyed
+     * liveness/settlement state cross generations. */
+    usedEphemeralAgentNames = new Set();
+    /** One-shot generation tickets minted by createEphemeralAgent. */
+    ephemeralCandidates = new WeakMap();
+    /** Physical ephemeral frames deliberately disposed by their run watchdog/caller.
+     * The name is single-generation, so these frames still own their terminal
+     * typing/outgoing close even after runEphemeralToCompletion deregisters them. */
+    disposedEphemeralFrames = new WeakSet();
     /** Per-agent count of consecutive exhausted inferences (reset on any success).
      *  Drives hard-down escalation — see noteInferenceExhausted. */
     consecutiveInferenceFailures = new Map();
@@ -569,6 +583,14 @@ export class AgentFramework {
     primaryAgentName = null;
     // Messages deferred while an agent is waiting_for_tools (to preserve
     // tool_use → tool_result adjacency required by the Anthropic API).
+    /** The subconscious resident's registry name (issue #77), or null. */
+    subconsciousAgentName = null;
+    /** Its windowed strategy — the coordinator moves the anchor on tune-out entry. */
+    subconsciousStrategy = null;
+    /** Its config (speak_in_channel gate, voice block provenance). */
+    subconsciousConfig = null;
+    /** Tune-out coordinator (issue #77); non-null iff subconscious + channels. */
+    tuneOutCoordinator = null;
     deferredMessages = [];
     // Turn-alive markers (2026-07-31 Mythos phantom-skip incident): agentName →
     // token of the turn currently in progress. Set at startAgentStream ENTRY —
@@ -599,6 +621,9 @@ export class AgentFramework {
     getActiveTurnTrigger(agentName) {
         return this.activeTurnTriggers.get(agentName);
     }
+    /** Structured calls executed in the current logical turn. Unlike the
+     * per-stream local this survives framework retries and budget restarts. */
+    logicalTurnToolCalls = new WeakMap();
     nextTurnToken = 1;
     // Undo/redo state
     turnCounters = new Map(); // agentName → next turnIndex
@@ -649,6 +674,11 @@ export class AgentFramework {
      *  framework state like the core runtime settings and restored at create
      *  (antra + Sol, 08-06); reset clears it back to the residence default. */
     toolResultInlineMaxCharsOverride = new Map();
+    /** Per-agent retention of tool-result images with provenance (issue
+     *  #104). In-memory and bounded by design: history keeps only the
+     *  placeholder; this is what lets `save_recent_image` reach the bytes the
+     *  resident actually saw — or fail at that exact index when they're gone. */
+    toolImageLedgers = new Map();
     /** Durable residence-configured inline cap from
      *  FrameworkConfig.toolResultInlineMaxChars; null → house default. */
     toolResultInlineMaxCharsConfig = null;
@@ -810,6 +840,12 @@ export class AgentFramework {
         for (const agentConfig of config.agents) {
             await framework.createAgent(agentConfig);
         }
+        // The subconscious resident (issue #77) registers after the residents so
+        // it can never become primary; it is excluded from every broadcast
+        // fan-out and woken only by the tune-out coordinator's explicit pushes.
+        if (config.subconscious?.enabled) {
+            await framework.createSubconsciousAgent(config.subconscious);
+        }
         // Finish any branch-local suppression interrupted after Chronicle switched
         // branches. This runs before modules, MCPL connections, or inbound traffic.
         await framework.resumePreparedDiscordSuppressions();
@@ -854,11 +890,20 @@ export class AgentFramework {
                 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) => {
-                    framework.pendingRequests.push({ agentName, reason, source, timestamp: Date.now() });
+                addMessage: (p, c, m, forAgent) => framework.addMessage(p, c, m, forAgent ? { forAgent } : undefined),
+                requestInference: (agentName, reason, source, provenance) => {
+                    framework.pendingRequests.push({
+                        agentName, reason, source, timestamp: Date.now(),
+                        // gate-requested wakes carry where/who (EventGate wakeProvenance)
+                        // as TELEMETRY fields — the host's stamp reads them; the turn's
+                        // speech locus (channelId / addressed) is deliberately NOT set
+                        // here, so a batched wake routes exactly as it did before.
+                        ...(provenance?.channelId ? { wakeChannelId: provenance.channelId } : {}),
+                        ...(provenance?.counterparty ? { counterparty: provenance.counterparty } : {}),
+                        ...(provenance?.at ? { wakeAt: provenance.at } : {}),
+                    });
                 },
-                getAgentNames: () => [...framework.agents.keys()],
+                getAgentNames: () => [...framework.agents.keys()].filter((n) => n !== framework.subconsciousAgentName),
             });
         }
         // Liveness watchdog: fail hard if the main thread wedges (opt-in).
@@ -909,6 +954,30 @@ export class AgentFramework {
             }
             await framework.initializeMcpl(config.mcplServers, config.inferenceRouting);
         }
+        // Tune-out coordinator (issue #77): needs both the subconscious resident
+        // and the MCPL channel subsystem; created after both exist.
+        if (framework.subconsciousAgentName && framework.channelRegistry) {
+            framework.tuneOutCoordinator = new TuneOutCoordinator(framework.channelRegistry, framework.mcplServerRegistry, {
+                addMessage: (participant, content, metadata, forAgent) => framework.addMessage(participant, content, metadata, forAgent ? { forAgent } : undefined),
+                requestInference: (agentName, reason, source) => {
+                    framework.pendingRequests.push({ agentName, reason, source, timestamp: Date.now() });
+                },
+                subconsciousName: () => framework.subconsciousAgentName,
+                primaryName: () => framework.primaryAgentName,
+                getStoredMessages: () => {
+                    const primary = framework.primaryAgentName
+                        ? framework.agents.get(framework.primaryAgentName) : undefined;
+                    return primary ? primary.getContextManager().getAllMessages() : [];
+                },
+                currentSequence: () => framework.store.currentSequence(),
+                setSubconsciousAnchor: (sequence) => framework.subconsciousStrategy?.setAnchor(sequence),
+                isForkBound: (channelId) => [...framework.conversationAgentHomes.values()].includes(channelId),
+                isPrivilegedAuthor: (authorId) => framework.eventGate?.isPrivilegedUser(authorId) ?? false,
+                allowChannelSpeech: () => !!framework.subconsciousConfig?.allowChannelSpeech,
+                emitTrace: (e) => framework.emitTrace(e),
+            });
+            framework.tuneOutCoordinator.resumeActiveEpochs();
+        }
         // Diagnostics: `kill -USR2 <pid>` dumps live wake/inference state to stderr
         // (journal) without a restart — for catching the wake-wedge on the running
         // process. Shows the gate's `inferring` set + buffered-event count (the
@@ -973,6 +1042,7 @@ export class AgentFramework {
         this.running = false;
         this.providerAdmissionClosed = true;
         this.queue.close();
+        this.tuneOutCoordinator?.stop();
         // Kill running code_execution scripts before cancelling streams: a
         // zombie script must not keep firing side-effectful tool calls into a
         // framework that is shutting down.
@@ -991,6 +1061,9 @@ export class AgentFramework {
             record.runner.dispose();
         }
         this.backgroundScripts.clear();
+        // Retained tool images are per-process by design; a retained stopped
+        // framework must not keep up to the whole ledger budget referenced.
+        this.toolImageLedgers.clear();
         // A stopped host must never hang behind its own cooldown.
         this.cancelProviderAdmission();
         // Cancel all active streams
@@ -1404,7 +1477,12 @@ export class AgentFramework {
      */
     getAllTools() {
         const moduleTools = this.moduleRegistry.getAllTools();
-        const channelTools = this.channelRegistry?.getChannelTools() ?? [];
+        // Copy: getChannelTools() returns the registry's shared definitions
+        // array; pushing onto it would append another tune_out on every call.
+        const channelTools = [...(this.channelRegistry?.getChannelTools() ?? [])];
+        if (this.tuneOutCoordinator) {
+            channelTools.push(AgentFramework.TUNE_OUT_TOOL);
+        }
         const gateTools = this.eventGate
             ? [
                 this.eventGate.getToolDefinition(),
@@ -1634,6 +1712,18 @@ export class AgentFramework {
         };
     }
     getToolsForAgent(agentName, snapshot) {
+        // The subconscious gets its own small surface (plus think/skip_reply/
+        // end_turn), not the residents' tool board: no channel lifecycle, no
+        // gate rules, no workspace — it observes, judges, and reports.
+        if (agentName === this.subconsciousAgentName) {
+            const basics = this.getAllTools()
+                .filter((t) => t.name === 'think' || t.name === 'skip_reply' || t.name === 'end_turn')
+                .map((t) => t.name === 'think'
+                ? this.buildThinkTool(snapshot?.sameRoundThinkTextPolicy
+                    ?? this.getAgentRuntimeSettings(agentName).sameRoundThinkTextPolicy)
+                : t);
+            return [...SUBCONSCIOUS_TOOLS, ...basics];
+        }
         return this.getAllTools().map((tool) => {
             if (tool.name === 'think') {
                 return this.buildThinkTool(snapshot?.sameRoundThinkTextPolicy
@@ -1989,21 +2079,35 @@ export class AgentFramework {
      * Call cleanup() when done to release the ContextManager.
      */
     async createEphemeralAgent(config) {
-        const namespace = `subagent/${config.name}`;
-        const contextManager = await ContextManager.open({
-            store: this.store,
-            namespace,
-            isolate: true,
-            strategy: config.strategy ?? new PassthroughStrategy(),
-            membrane: this.membrane,
-            debugLogContext: !!process.env.DEBUG_CONTEXT,
-        });
-        const agent = new Agent(config, contextManager, this.membrane);
-        const cleanup = () => {
-            // Don't close the store — it's shared. Just release the CM.
-            // Data persists in the store under the namespace for investigation.
-        };
-        return { agent, contextManager, cleanup };
+        // Names are Chronicle namespaces and generation identities. Reserve before
+        // opening the namespace so a second creation cannot append to an earlier
+        // generation before runEphemeralToCompletion has a chance to reject it.
+        if (this.usedEphemeralAgentNames.has(config.name) || this.agents.has(config.name)) {
+            throw new Error(`Ephemeral agent name \"${config.name}\" is already registered or has been used in this framework`);
+        }
+        this.usedEphemeralAgentNames.add(config.name);
+        try {
+            const namespace = `subagent/${config.name}`;
+            const contextManager = await ContextManager.open({
+                store: this.store,
+                namespace,
+                isolate: true,
+                strategy: config.strategy ?? new PassthroughStrategy(),
+                membrane: this.membrane,
+                debugLogContext: !!process.env.DEBUG_CONTEXT,
+            });
+            const agent = new Agent(config, contextManager, this.membrane);
+            this.ephemeralCandidates.set(agent, contextManager);
+            const cleanup = () => {
+                // Don't close the store — it's shared. Just release the CM.
+                // Data persists in the store under the namespace for investigation.
+            };
+            return { agent, contextManager, cleanup };
+        }
+        catch (error) {
+            this.usedEphemeralAgentNames.delete(config.name);
+            throw error;
+        }
     }
     createDeferred() {
         let resolve;
@@ -2024,6 +2128,18 @@ export class AgentFramework {
         }
         run.lastActivity = Date.now();
     }
+    /** Record structured calls for the current logical turn. Ignore late stream
+     * events after an ephemeral/conversation agent has been disposed. */
+    recordLogicalTurnToolCalls(agent, turnToken, count) {
+        if (count <= 0 || this.agents.get(agent.name) !== agent)
+            return;
+        const state = this.logicalTurnToolCalls.get(agent);
+        // The Agent object is the generation: a late stream from a disposed
+        // ephemeral/conversation fork cannot contaminate a same-name successor.
+        if (!state || state.turnToken !== turnToken)
+            return;
+        this.logicalTurnToolCalls.set(agent, { turnToken, count: state.count + count });
+    }
     recordEphemeralToolCalls(agentName, count) {
         const run = this.ephemeralRuns.get(agentName);
         if (!run)
@@ -2060,7 +2176,18 @@ export class AgentFramework {
      * The task message should already be in the context manager.
      */
     async runEphemeralToCompletion(agent, contextManager, watchdogs) {
-        // Register temporarily so the event loop can drive it
+        // Only a fresh object returned by createEphemeralAgent may enter this path.
+        // Never overwrite a resident/conversation owner or a concurrent run: their
+        // cleanup is name-keyed and could cancel/deregister the legitimate owner.
+        if (this.ephemeralCandidates.get(agent) !== contextManager) {
+            throw new Error(`Ephemeral agent "${agent.name}" has no fresh generation ticket from this framework`);
+        }
+        // Consume before any await/registration: the exact (Agent, ContextManager)
+        // generation is one-shot even if startup later fails.
+        this.ephemeralCandidates.delete(agent);
+        if (this.agents.has(agent.name) || this.ephemeralRuns.has(agent.name)) {
+            throw new Error(`Ephemeral agent "${agent.name}" is already registered or running`);
+        }
         this.agents.set(agent.name, agent);
         const run = {
             settle: this.createDeferred(),
@@ -2119,8 +2246,27 @@ export class AgentFramework {
                 clearTimeout(startupWatchdog);
             if (completionWatchdog)
                 clearInterval(completionWatchdog);
-            this.ephemeralRuns.delete(agent.name);
-            this.agents.delete(agent.name);
+            // Mark before cancellation: an adapter may synchronously settle its
+            // iterator, and this physical frame still owns terminal typing/outgoing
+            // closure even though the ephemeral name is about to be deregistered.
+            this.disposedEphemeralFrames.add(agent);
+            // Cancel before deregistration. Adapters may still yield a queued event;
+            // driveStream's Agent-identity check above discards it before dispatch.
+            agent.cancelStream();
+            if (this.ephemeralRuns.get(agent.name) === run)
+                this.ephemeralRuns.delete(agent.name);
+            if (this.agents.get(agent.name) === agent) {
+                // Exact-generation disposal owns these name-keyed entries. Remove them
+                // before deregistration; the late driveStream finally will see the
+                // generation mismatch and leave any future owner untouched.
+                this.activeStreams.delete(agent.name);
+                this.pendingAssistantBlocks.delete(agent.name);
+                // The late stream finalizer intentionally refuses name-keyed cleanup once
+                // deregistered, so disposal must release EventGate liveness itself.
+                this.eventGate?.onInferenceEnded(agent.name);
+                this.agents.delete(agent.name);
+            }
+            this.toolImageLedgers.delete(agent.name);
             // Spawn-and-dispose bookkeeping (main, d453165/fee96a7): without this,
             // ephemeral agents leave checkpoint-tree keys and diagnostics map
             // entries behind for the life of the store/session.
@@ -2132,6 +2278,7 @@ export class AgentFramework {
             // of the map, and a late driveStream finally token-match no-ops.
             this.activeTurnTokens.delete(agent.name);
             this.activeTurnTriggers.delete(agent.name);
+            this.logicalTurnToolCalls.delete(agent);
         }
     }
     /**
@@ -2144,6 +2291,44 @@ export class AgentFramework {
      * Query inference logs.
      * Returns entries with summary info (doesn't resolve blobs).
      */
+    /** Tune-out (issue #77): divert a channel to your subconscious. Present
+     *  only when the subconscious resident is configured. */
+    static TUNE_OUT_TOOL = {
+        name: 'tune_out',
+        description: 'Divert a channel to your subconscious for a while: its traffic stops ' +
+            'entering your context and stops waking you. Your subconscious watches ' +
+            'it instead — summarizing on a cadence in its own voice, judging ' +
+            'whether mentions merit interrupting, and able to cancel. People who ' +
+            'mention you get an automatic reaction so they know you saw nothing. ' +
+            'Cancelling (mode "cancel") delivers the diverted backlog. The ' +
+            'tune-out auto-cancels after maxWakes mention-bursts.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                channelId: { type: 'string' },
+                mode: { type: 'string', enum: ['enter', 'cancel'], description: 'Default: enter.' },
+                cadenceSeconds: {
+                    type: 'number',
+                    description: `Summary cadence in seconds (default ${TUNE_OUT_DEFAULTS.cadenceSeconds}; floors at 30).`,
+                },
+                backlogCap: {
+                    type: 'number',
+                    description: `Max raw messages delivered at cancel (default ${TUNE_OUT_DEFAULTS.backlogCap}). ` +
+                        '0 = deliver no raw backlog at all: your subconscious\'s report is the whole delivery.',
+                },
+                maxWakes: {
+                    type: 'number',
+                    description: `Wake budget before auto-cancel (default ${TUNE_OUT_DEFAULTS.maxWakes}; floors at 1).`,
+                },
+                durationSeconds: {
+                    type: 'number',
+                    description: 'Optional bounded duration: the tune-out auto-cancels (backlog ' +
+                        'delivered) after this many seconds; floors at 60. Unset = until cancelled.',
+                },
+            },
+            required: ['channelId'],
+        },
+    };
     /** Synthesized sleep/wake tool definitions (present when a gate is wired). */
     static SLEEP_TOOLS = [
         {
@@ -2324,11 +2509,18 @@ export class AgentFramework {
     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 ' +
+            'Images are counted back from the most recent (index 0), across BOTH ' +
+            'attachments in messages and images returned by tools (their history ' +
+            'placeholder shows a ref like `[image: image/png, ~691KB, ref img_k7x3q2_7]`; pass ' +
+            '`ref` to save that exact image regardless of position). 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.',
+            '("cat-0.png", "cat-1.png", …; 0 = the newest of the range). If the image at ' +
+            'the requested position is no longer retained (evicted, or from before a ' +
+            'restart) the call fails and writes nothing — it never substitutes an older ' +
+            'image. When other tool calls in the same batch are still running, the save ' +
+            'waits for them so their images are counted. Receipts carry source tool call, MIME, byte size and SHA-256. Saved ' +
+            'files are visible via workspace tools and the /files/ endpoint.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -2344,6 +2536,11 @@ export class AgentFramework {
                     type: 'number',
                     description: 'How many images to save, starting at `index` and going further back. Default 1.',
                 },
+                ref: {
+                    type: 'string',
+                    description: 'Save a specific tool-result image by its history ref (e.g. "img_k7x3q2_7", as shown in its placeholder in your context) instead of by position. ' +
+                        'Mutually exclusive with `index`/`count`.',
+                },
             },
             required: ['path'],
         },
@@ -3395,6 +3592,15 @@ export class AgentFramework {
             // streaming agent keeps the original Membrane.
             membrane: this.auxiliaryMembraneFor(config.name),
             debugLogContext: !!process.env.DEBUG_CONTEXT,
+            // Tune-out (issue #77): messages stamped at ingestion as diverted
+            // (metadata.tuneOut = { epochId }) never enter a resident's compiled
+            // view — not at emission, not via chunking into the memory pyramid.
+            // The stamp is permanent: after cancel, the backlog arrives as one
+            // appended <tuned-out-backlog> dump instead of retro-inserting into
+            // the timeline (KV-prefix-stable delivery). The stored originals
+            // remain in the shared slot for the subconscious's merged view,
+            // fetch_history, and audit.
+            viewFilter: (message) => !message.metadata?.tuneOut,
         });
         const agent = new Agent(config, contextManager, this.membrane);
         const restoredSettings = this.readAgentRuntimeSettings(config.name);
@@ -3409,6 +3615,68 @@ export class AgentFramework {
         }
         return agent;
     }
+    /**
+     * Create and register the subconscious resident (issue #77): a persistent
+     * side-agent with an isolated slot (`subconscious/<primary>`) whose
+     * strategy view merges the residents' shared timeline with its own —
+     * including the tuned-out-stamped messages the residents' viewFilter
+     * excludes; the backlog is precisely what it exists to see. Windowed
+     * passthrough, no memory pyramid: its durable output is what it delivers
+     * into the resident's window, which accumulates there.
+     */
+    async createSubconsciousAgent(cfg) {
+        const primaryName = this.primaryAgentName;
+        const primaryConfig = primaryName ? this.agentConfigs.get(primaryName) : undefined;
+        if (!primaryName || !primaryConfig) {
+            throw new Error('subconscious requires a primary agent to attend to');
+        }
+        const name = cfg.name ?? 'Subconscious';
+        if (this.agents.has(name)) {
+            throw new Error(`subconscious name "${name}" collides with a registered agent`);
+        }
+        const strategy = new WindowedPassthroughStrategy({
+            reAnchorFraction: cfg.reAnchorFraction,
+            // Mirror the principal's per-message truncation ceiling so both see
+            // oversized tool results / attachments under the same policy.
+            maxMessageTokens: primaryConfig.strategy?.maxMessageTokens,
+        });
+        const contextManager = await ContextManager.open({
+            store: this.store,
+            namespace: `subconscious/${primaryName}`,
+            isolate: true,
+            // The residents' shared un-namespaced slot, merged read-only and
+            // UNfiltered (no viewFilter here — stamped messages included).
+            auxiliaryMessageViews: [{}],
+            strategy,
+            membrane: this.membrane,
+            debugLogContext: !!process.env.DEBUG_CONTEXT,
+        });
+        // Inherit the principal's inference settings wholesale (fork-template
+        // idiom): reasoning effort (thinking), provider params, token ceilings,
+        // caching, refusal handling, timezone — a same-model side-process must
+        // not silently run under different inference conditions than the
+        // resident it serves. Only identity- and surface-defining fields are
+        // overridden below.
+        const agentConfig = {
+            ...primaryConfig,
+            name,
+            model: cfg.model ?? primaryConfig.model,
+            systemPrompt: cfg.systemPrompt,
+            strategy: undefined, // its CM owns the windowed strategy instance
+            // Prose is never auto-routed: a cadence-triggered turn carries no
+            // locus, and bare prose must not fall through to the default channel.
+            // Speech happens only via speak_in_channel (its own marked voice).
+            proseRouting: 'explicit',
+            allowedTools: [...SUBCONSCIOUS_TOOL_NAMES, 'think', 'skip_reply', 'end_turn'],
+        };
+        const agent = new Agent(agentConfig, contextManager, this.membrane);
+        this.agents.set(name, agent);
+        this.agentConfigs.set(name, agentConfig);
+        this.subconsciousAgentName = name;
+        this.subconsciousStrategy = strategy;
+        this.subconsciousConfig = cfg;
+        return agent;
+    }
     async runLoop() {
         while (this.running) {
             try {
@@ -3508,7 +3776,7 @@ export class AgentFramework {
                     // history copy and the live wire copy below — the two must stay
                     // byte-matched (the window stores what the membrane sends;
                     // divergence breaks the compile prefix).
-                    const { blocks: toolResultContent, spilled } = await this.buildStoredToolResultContent(currentState.toolResults, maxChars);
+                    const { blocks: toolResultContent, spilled } = await this.buildStoredToolResultContent(agent.name, currentState.toolResults, maxChars);
                     agent.getContextManager().addMessage('user', toolResultContent);
                     // Flush any messages that were deferred while this turn was in
                     // flight. Route to the PRIMARY agent — deferred messages are
@@ -3533,12 +3801,11 @@ export class AgentFramework {
                     // queued, they flush at the target's own next boundary — with
                     // injection — or in driveStream's finally when its turn ends.
                     const midTurnInjections = [];
-                    if (this.deferredMessages.length > 0) {
-                        const target = (this.primaryAgentName ? this.agents.get(this.primaryAgentName) : undefined) ?? agent;
-                        if (target === agent) {
-                            const deferred = this.deferredMessages.splice(0);
+                    {
+                        const deferred = this.drainDeferredFor(agent.name);
+                        if (deferred.length > 0) {
                             for (const msg of deferred) {
-                                target.getContextManager().addMessage(msg.participant, msg.content, msg.metadata);
+                                agent.getContextManager().addMessage(msg.participant, msg.content, msg.metadata);
                                 // Injection guards: tool blocks would corrupt the tool-cycle
                                 // structure the membrane enforces, and a message named as the
                                 // agent itself would render as an ASSISTANT turn on the wire
@@ -3835,7 +4102,7 @@ export class AgentFramework {
             // 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()).filter((n) => !this.conversationAgentHomes.has(n))
+                ? Array.from(this.agents.keys()).filter((n) => !this.conversationAgentHomes.has(n) && n !== this.subconsciousAgentName)
                 : response.requestInference;
             for (const agentName of targetAgents) {
                 const agent = this.agents.get(agentName);
@@ -3902,11 +4169,31 @@ export class AgentFramework {
                 Object.assign(metadata, invitation.metadataPatch);
             }
         }
+        // Tune-out divert (issue #77): stamped, stored, no resident wake. The
+        // coordinator has already handled wake bookkeeping (coalesced
+        // subconscious invocation, durable count, suppression ack) before we
+        // stamp; the subconscious reads the message through its merged view.
+        const divert = this.tuneOutCoordinator?.onIncoming(event.serverId, event.channelId, event.messageId, event.tags, event.author?.id, 
+        // The resident's gate verdict rides the event; it preconditions
+        // subconscious wakes (gate composes, it is not replaced).
+        event.triggerInference !== false) ?? null;
+        if (divert) {
+            metadata.tuneOut = { epochId: divert.epochId };
+        }
         const id = this.addMessage('user', incomingContent, metadata);
         this.emitTrace({ type: 'message:added', messageId: id, source: 'mcpl:channel-incoming' });
-        if (event.triggerInference) {
+        if (event.triggerInference && !divert) {
             const addressed = isAddressedMessage(event.tags, event.metadata);
-            for (const agentName of this.agents.keys()) {
+            // Honor explicit targeting, mirroring the push-event path: an event
+            // that names its agents wakes exactly those; an untargeted event
+            // keeps the historical broadcast. (targetAgents was declared on
+            // McplChannelIncomingEvent from the start but never honored here —
+            // tune-out's wake routing is the first setter.)
+            const targetAgents = event.targetAgents
+                ?? [...this.agents.keys()].filter((n) => n !== this.subconsciousAgentName);
+            for (const agentName of targetAgents) {
+                if (!this.agents.has(agentName))
+                    continue;
                 this.pendingRequests.push({
                     agentName,
                     reason: 'mcpl:channel-incoming',
@@ -4019,38 +4306,48 @@ export class AgentFramework {
         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(),
-            // Dynamic conversation forks retain the established provider policy in
-            // this bounded first slice. Provider cooldown ownership belongs to the
-            // persistent resident only; generation-unique forks must not leak gates.
-            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;
+        if (this.usedEphemeralAgentNames.has(name) || this.agents.has(name)) {
+            throw new Error(`Conversation agent name "${name}" is already registered or reserved`);
+        }
+        this.usedEphemeralAgentNames.add(name);
+        try {
+            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(),
+                // Dynamic conversation forks retain the established provider policy in
+                // this bounded first slice. Provider cooldown ownership belongs to the
+                // persistent resident only; generation-unique forks must not leak gates.
+                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;
+        }
+        catch (error) {
+            this.usedEphemeralAgentNames.delete(name);
+            throw error;
+        }
     }
     /** Persist the router's generation counters (see hydration in create()). */
     persistConversationRouterState() {
@@ -4074,10 +4371,14 @@ export class AgentFramework {
     disposeConversationAgent(agentName) {
         this.closingConversationAgents.delete(agentName);
         const channelId = this.conversationAgentHomes.get(agentName);
+        const agent = this.agents.get(agentName);
         this.agents.delete(agentName);
+        this.toolImageLedgers.delete(agentName);
         this.agentConfigs.delete(agentName);
         this.conversationAgentHomes.delete(agentName);
         this.evictTurnCheckpoints(agentName);
+        if (agent)
+            this.logicalTurnToolCalls.delete(agent);
         this.emitTrace({
             type: 'mcpl:conversation-disposed',
             agentName,
@@ -4277,7 +4578,7 @@ export class AgentFramework {
         if (event.triggerInference) {
             // Default broadcast excludes conversation forks (channel-driven).
             const targetAgents = event.targetAgents
-                ?? [...this.agents.keys()].filter((n) => !this.conversationAgentHomes.has(n));
+                ?? [...this.agents.keys()].filter((n) => !this.conversationAgentHomes.has(n) && n !== this.subconsciousAgentName);
             for (const agentName of targetAgents) {
                 this.pendingRequests.push({
                     agentName,
@@ -4459,6 +4760,10 @@ export class AgentFramework {
                 // exactly this class of silent drop. One stderr line per drop.
                 console.error(`[inference-dropped] agent=${agentName} reason=policy-skip ` +
                     `requests=${requests.length} triggers=${requests.map((r) => r.reason).join(',')}`);
+                // A context-budget restart inherits the predecessor's EventGate liveness.
+                // If policy drops the queued successor, no driveStream remains to release it.
+                if (budgetRestart)
+                    this.eventGate?.onInferenceEnded(agentName);
                 const gate = this.providerGates.get(agentName);
                 if (gate?.primaryPending && this.providerAccelerationRecoveries.has(agentName)) {
                     gate.primaryPending = false;
@@ -4499,6 +4804,19 @@ export class AgentFramework {
                     addressedReq = r;
             }
             const channelReq = addressedReq ?? ambientReq;
+            // Telemetry provenance (who/where woke the agent): from the routing
+            // winner when it carries one; else from the most recent request that
+            // does (gate wakes name a counterparty without setting a locus),
+            // ordered by the event's own time (wakeAt) rather than flush order.
+            let provReq = channelReq?.counterparty || channelReq?.wakeChannelId ? channelReq : undefined;
+            if (!provReq) {
+                for (const r of requests) {
+                    if (!r.counterparty && !r.wakeChannelId)
+                        continue;
+                    if (!provReq || (r.wakeAt ?? r.timestamp) >= (provReq.wakeAt ?? provReq.timestamp))
+                        provReq = r;
+                }
+            }
             await this.startAgentStream(agent, {
                 ...trigger,
                 channelId: channelReq?.channelId,
@@ -4507,7 +4825,9 @@ export class AgentFramework {
                 // the channel for routing but names no author — the restart is its
                 // own cause, and borrowing another request's author would be false
                 // provenance.
-                counterparty: budgetRestart ? undefined : channelReq?.counterparty,
+                counterparty: budgetRestart ? undefined : provReq?.counterparty,
+                wakeChannelId: budgetRestart ? undefined : provReq?.wakeChannelId,
+                wakeAt: budgetRestart ? undefined : provReq?.wakeAt,
             });
         }
     }
@@ -5012,9 +5332,8 @@ export class AgentFramework {
         if (attempt === 0 &&
             trigger?.reason !== 'context_budget_restart' &&
             this.deferredMessages.length > 0) {
-            const target = (this.primaryAgentName ? this.agents.get(this.primaryAgentName) : undefined) ?? agent;
-            if (target === agent) {
-                const deferred = this.deferredMessages.splice(0);
+            {
+                const deferred = this.drainDeferredFor(agent.name);
                 for (const msg of deferred) {
                     // Per-message try/catch (mirrors announceLocusIfChanged): one
                     // poison message — or a transient store-write failure — must not
@@ -5068,9 +5387,22 @@ export class AgentFramework {
         // BEFORE this turn compiles, so the agent always knows where its voice
         // goes (announce-on-change only — no per-turn chatter, append-only for
         // KV stability).
+        if (trigger?.reason === 'context_budget_restart') {
+            const previousLogicalToolState = this.logicalTurnToolCalls.get(agent);
+            this.logicalTurnToolCalls.set(agent, { turnToken, count: previousLogicalToolState?.count ?? 0 });
+        }
         if (trigger?.reason !== 'context_budget_restart') {
             if (attempt === 0)
                 this.maybePrimeProseMode(agent);
+            const previousLogicalToolState = this.logicalTurnToolCalls.get(agent);
+            if (attempt === 0) {
+                // A true new turn gets a fresh generation and count.
+                this.logicalTurnToolCalls.set(agent, { turnToken, count: 0 });
+            }
+            else {
+                // A framework retry is a new physical stream in the same logical turn.
+                this.logicalTurnToolCalls.set(agent, { turnToken, count: previousLogicalToolState?.count ?? 0 });
+            }
             // Fresh turn: forget the previous turn's explicit-send engagements and
             // prose deliveries — both are strictly turn-scoped (a restart continues
             // the same logical turn and keeps them).
@@ -5108,7 +5440,11 @@ export class AgentFramework {
             // context-budget restart, which skips the re-pin but re-emits this).
             channelId: this.turnLocusPins.get(agent.name),
         });
-        this.eventGate?.onInferenceStarted(agent.name);
+        // A budget restart continues the same logical inference window. The
+        // predecessor keeps EventGate liveness until its successor terminates.
+        if (trigger?.reason !== 'context_budget_restart') {
+            this.eventGate?.onInferenceStarted(agent.name);
+        }
         this.lastInferenceAt.set(agent.name, { ...this.lastInferenceAt.get(agent.name), startedAt: Date.now() });
         // Typing indicator, started at TURN START. It says "attending", which is
         // true from the moment the turn is accepted — but it used to start inside
@@ -5162,8 +5498,32 @@ export class AgentFramework {
                     console.error('beforeInference hook error:', error);
                 }
             }
+            // An ephemeral watchdog may dispose this Agent while hooks/compile await.
+            // Do not create a provider stream after its generation lost ownership.
+            if (this.agents.get(agent.name) !== agent) {
+                this.channelRegistry?.stopTyping();
+                this.eventGate?.onInferenceEnded(agent.name);
+                return false;
+            }
+            // The subconscious's standing dispositions ride a fixed system-position
+            // injection (antra, #tuneout-talk): never repeated in its timeline, and
+            // — since it has no long-term memory — structurally unable to wash out
+            // of its window. Bytes change only when a disposition changes.
+            if (agent.name === this.subconsciousAgentName && this.tuneOutCoordinator) {
+                const dispositionInjection = this.tuneOutCoordinator.getDispositionsInjection();
+                if (dispositionInjection) {
+                    injections = injections ? [...injections, dispositionInjection] : [dispositionInjection];
+                }
+            }
             const { stream, request: compiledRequest, takeKvSubmission, drainKvSubmissionIds, } = await agent.startStreamWithInjections(tools, injections);
-            const handle = this.driveStream(agent, stream, requestSnapshot, trigger, attempt, compiledRequest, ownsProviderGate, takeKvSubmission, drainKvSubmissionIds);
+            if (this.agents.get(agent.name) !== agent) {
+                stream.cancel();
+                agent.cancelStream();
+                this.channelRegistry?.stopTyping();
+                this.eventGate?.onInferenceEnded(agent.name);
+                return false;
+            }
+            const handle = this.driveStream(agent, stream, requestSnapshot, trigger, attempt, compiledRequest, ownsProviderGate, takeKvSubmission, drainKvSubmissionIds, new Set(tools.map((tool) => tool.name)));
             this.activeStreams.set(agent.name, handle);
             // Handoff: driveStream captured the token in its synchronous prefix;
             // its finally now owns clearing it. The caller's finally must not.
@@ -5236,7 +5596,7 @@ export class AgentFramework {
             return false;
         }
     }
-    async driveStream(agent, stream, requestSnapshot, trigger, attempt = 0, compiledRequest, ownsProviderGate = false, takeKvSubmission, drainKvSubmissionIds) {
+    async driveStream(agent, stream, requestSnapshot, trigger, attempt = 0, compiledRequest, ownsProviderGate = false, takeKvSubmission, drainKvSubmissionIds, knownToolNames = new Set()) {
         const startTime = Date.now();
         const requestId = `${agent.name}-${startTime}-${Math.random().toString(36).slice(2, 8)}`;
         const myStreamId = agent.streamId;
@@ -5255,6 +5615,7 @@ export class AgentFramework {
         // means no successor turn can have replaced it while we compiled.
         const myTurnToken = this.activeTurnTokens.get(agent.name);
         let hadToolCalls = false;
+        let generationLost = false;
         // ---- Present-while-acting turn state ---------------------------------
         // Output locus for the WHOLE logical turn: frozen in startAgentStream
         // (home → addressed trigger → global default) before this stream began,
@@ -5329,13 +5690,20 @@ export class AgentFramework {
         // failed, a framework-cancelled stream sets aborted. Best-effort
         // notifications — consumers dedupe by inferenceId and keep a timeout.
         let lifecyclePhase = 'completed';
+        let preserveEventGateForSuccessor = false;
         this.hookOrchestrator?.emitLifecycle({
             inferenceId: outgoingInferenceId,
             conversationId: agent.name,
             turnIndex: 0,
             phase: 'started',
         });
-        const proseStream = this.channelRegistry && agent.proseRouting !== 'disabled'
+        // The wrapper guard needs the complete response before it can distinguish
+        // an exact invocation-shaped body from ordinary XML/prose. Buffer guarded
+        // turns until completion: otherwise speculative outgoing chunks could
+        // expose the wrapper before the fail-closed classifier runs.
+        const proseStream = this.channelRegistry &&
+            agent.proseRouting !== 'disabled' &&
+            !agent.toolWrapperProseGuard
             ? new ProseStreamRouter({
                 mode: agent.proseRouting === 'explicit' ? 'explicit' : agent.proseRouting === 'hybrid' ? 'hybrid' : 'locus',
                 initialTarget: typingChannel,
@@ -5361,6 +5729,14 @@ export class AgentFramework {
         };
         try {
             for await (const event of stream) {
+                // Ignore every late event from an Agent generation that no longer owns
+                // this name (ephemeral watchdog/disposal, conversation replacement).
+                if (this.agents.get(agent.name) !== agent || agent.streamId !== myStreamId) {
+                    generationLost = true;
+                    lifecyclePhase = 'aborted';
+                    stream.cancel();
+                    break;
+                }
                 this.touchEphemeralRun(agent.name, true);
                 switch (event.type) {
                     case 'tokens':
@@ -5423,6 +5799,7 @@ export class AgentFramework {
                     case 'tool-calls': {
                         adoptInjectedRound();
                         hadToolCalls = true;
+                        this.recordLogicalTurnToolCalls(agent, myTurnToken ?? -1, event.calls.length);
                         this.recordEphemeralToolCalls(agent.name, event.calls.length);
                         this.emitTrace({
                             type: 'inference:tool_calls_yielded',
@@ -5588,7 +5965,7 @@ export class AgentFramework {
                             // one door a giant blob still walks through).
                             const readyState = agent.state;
                             if (readyState.status === 'ready') {
-                                const { blocks: toolResultContent } = await this.buildStoredToolResultContent(readyState.toolResults, this.resolveToolResultInlineCap(agent).cap);
+                                const { blocks: toolResultContent } = await this.buildStoredToolResultContent(agent.name, readyState.toolResults, this.resolveToolResultInlineCap(agent).cap);
                                 agent.getContextManager().addMessage('user', toolResultContent);
                             }
                         }
@@ -5604,7 +5981,29 @@ export class AgentFramework {
                         const terminalContent = lastToolIdx >= 0
                             ? response.content.slice(lastToolIdx + 1)
                             : response.content;
-                        if (lastToolIdx >= 0) {
+                        // This is a whole-response boundary, not a trailing-prose
+                        // classifier. If the turn executed any genuine structured tool
+                        // call, preserve its later prose exactly as ordinary history.
+                        const logicalToolState = this.logicalTurnToolCalls.get(agent);
+                        const logicalTurnHadToolCalls = logicalToolState?.turnToken === myTurnToken && (logicalToolState?.count ?? 0) > 0;
+                        const guardedWrapperTool = agent.toolWrapperProseGuard && !logicalTurnHadToolCalls
+                            ? detectKnownToolWrapperProse(response.content, knownToolNames)
+                            : null;
+                        if (guardedWrapperTool) {
+                            // AF #133: containment only. Never execute wrapper text, never
+                            // publish it, and never retain it as the freshest assistant
+                            // self-seed. Exact raw output remains in the provider ledger.
+                            agent.getContextManager().addMessage('user', [{
+                                    type: 'text',
+                                    text: '[tool-boundary] No tool was called.',
+                                }], {
+                                system: true,
+                                kind: 'tool-wrapper-prose-contained',
+                                toolName: guardedWrapperTool,
+                            });
+                            console.error(`[tool-boundary] ${agent.name}: contained whole-response prose wrapper for registered tool ${guardedWrapperTool}; no tool called`);
+                        }
+                        else if (lastToolIdx >= 0) {
                             if (terminalContent.length > 0) {
                                 agent.addAssistantResponse(terminalContent);
                             }
@@ -5627,7 +6026,9 @@ export class AgentFramework {
                         // convention remains "text is thoughts"; on a text-only turn all
                         // text is speech.
                         const isTextBlock = (block) => block.type === 'text';
-                        const allText = response.content.filter(isTextBlock);
+                        const allText = guardedWrapperTool
+                            ? []
+                            : response.content.filter(isTextBlock);
                         const speechContent = hadToolCalls ? [] : allText;
                         const thoughts = hadToolCalls ? allText : [];
                         const du = response.details?.usage;
@@ -5639,19 +6040,30 @@ export class AgentFramework {
                                 cacheRead: du.cacheReadTokens,
                             }
                             : undefined;
+                        // Async completion work may overlap a replacement stream. Recheck
+                        // physical ownership before any terminal state/settlement side effect.
+                        if (this.agents.get(agent.name) !== agent || agent.streamId !== myStreamId) {
+                            generationLost = true;
+                            lifecyclePhase = 'aborted';
+                            stream.cancel();
+                            return;
+                        }
                         // Reset agent state before emitting inference:completed. Traces are
                         // observability-only, but external synchronous listeners should
                         // still see the terminal state at the terminal trace boundary.
                         // Speech dispatch happens after but doesn't depend on the status
                         // field.
                         agent.reset();
-                        this.eventGate?.onInferenceEnded(agent.name);
+                        if (this.agents.get(agent.name) === agent && agent.streamId === myStreamId)
+                            this.eventGate?.onInferenceEnded(agent.name);
                         this.settleAgent(agent.name, {
                             stopReason: 'completed',
-                            speech: terminalContent
-                                .filter((block) => block.type === 'text')
-                                .map((block) => block.text)
-                                .join('\n'),
+                            speech: guardedWrapperTool
+                                ? ''
+                                : terminalContent
+                                    .filter((block) => block.type === 'text')
+                                    .map((block) => block.text)
+                                    .join('\n'),
                         });
                         this.emitTrace({
                             type: 'inference:completed',
@@ -5992,7 +6404,8 @@ export class AgentFramework {
                         agent.reset();
                         if (ownsProviderGate && this.holdProviderAcceleration(agent, err, trigger)) {
                             lifecyclePhase = 'failed';
-                            this.eventGate?.onInferenceEnded(agent.name);
+                            if (this.agents.get(agent.name) === agent && agent.streamId === myStreamId)
+                                this.eventGate?.onInferenceEnded(agent.name);
                             break;
                         }
                         const action = this.errorPolicy.onInferenceError(err, agent.name, attempt);
@@ -6016,7 +6429,8 @@ export class AgentFramework {
                                 // itself) means retrying the same context can never succeed.
                                 ...this.classifyInferenceError(err),
                             });
-                            this.eventGate?.onInferenceEnded(agent.name);
+                            if (this.agents.get(agent.name) === agent && agent.streamId === myStreamId)
+                                this.eventGate?.onInferenceEnded(agent.name);
                             if (action.emit) {
                                 this.pushEvent(action.emit);
                             }
@@ -6037,7 +6451,14 @@ export class AgentFramework {
                             if (cancelKind !== undefined) {
                                 this.frameworkCancelledStreams.delete(cancelKey);
                                 lifecyclePhase = 'aborted'; // §10.5 — terminal emitted in finally
-                                this.eventGate?.onInferenceEnded(agent.name);
+                                // A budget restart continues the same EventGate window. Do not
+                                // end it here or in finally; the replacement owns final release.
+                                if (cancelKind === 'budget_restart') {
+                                    preserveEventGateForSuccessor = true;
+                                }
+                                else if (this.agents.get(agent.name) === agent && agent.streamId === myStreamId) {
+                                    this.eventGate?.onInferenceEnded(agent.name);
+                                }
                                 // endTurn IS a logical turn end — earlier rounds may have
                                 // live-routed prose (narrate → skip_reply is a real shape),
                                 // so settle the delivery chain and drop the receipt. A
@@ -6084,7 +6505,8 @@ export class AgentFramework {
                                 request: compiledRequest ?? { note: 'streaming request aborted' },
                                 durationMs,
                             });
-                            this.eventGate?.onInferenceEnded(agent.name);
+                            if (this.agents.get(agent.name) === agent && agent.streamId === myStreamId)
+                                this.eventGate?.onInferenceEnded(agent.name);
                         }
                         break;
                     }
@@ -6160,6 +6582,14 @@ export class AgentFramework {
             }
         }
         catch (error) {
+            // A superseded physical stream may throw after its replacement starts.
+            // It has no authority to settle, reset, gate-release, or publish failure.
+            if (this.agents.get(agent.name) !== agent || agent.streamId !== myStreamId) {
+                generationLost = true;
+                lifecyclePhase = 'aborted';
+                stream.cancel();
+                return;
+            }
             // Stream itself threw. Organization acceleration is deferred from a
             // fresh compile; every other throw keeps the ordinary exhausted path.
             const err = error instanceof Error ? error : new Error(String(error));
@@ -6172,7 +6602,8 @@ export class AgentFramework {
                 this.abortAgentScript(agent.name, 'provider acceleration cooldown');
                 lifecyclePhase = 'failed';
                 agent.reset();
-                this.eventGate?.onInferenceEnded(agent.name);
+                if (this.agents.get(agent.name) === agent && agent.streamId === myStreamId)
+                    this.eventGate?.onInferenceEnded(agent.name);
                 return;
             }
             this.emitTrace({
@@ -6207,7 +6638,8 @@ export class AgentFramework {
             this.abortAgentScript(agent.name, 'stream threw');
             lifecyclePhase = 'failed'; // §10.5 — terminal emitted in finally
             agent.reset();
-            this.eventGate?.onInferenceEnded(agent.name);
+            if (this.agents.get(agent.name) === agent && agent.streamId === myStreamId)
+                this.eventGate?.onInferenceEnded(agent.name);
         }
         finally {
             const unsettledKvSubmissions = drainKvSubmissionIds?.() ?? [];
@@ -6220,6 +6652,19 @@ export class AgentFramework {
                 }
                 catch { /* receipt cleanup must not mask inference teardown */ }
             }
+            // A framework retry/budget restart can overlap physical streams on the
+            // same Agent object. Name + Agent identity is not enough: only the
+            // current stream generation may mutate name-keyed teardown state.
+            const ownsPhysicalStream = this.agents.get(agent.name) === agent && agent.streamId === myStreamId;
+            // Ephemeral completion resolves its caller before this finally runs, so
+            // runEphemeralToCompletion may already have deregistered the name. The
+            // terminal frame still owns its typing/outgoing completion unless it was
+            // genuinely superseded or handed EventGate liveness to a budget restart.
+            const disposedEphemeralWithoutSuccessor = generationLost &&
+                this.disposedEphemeralFrames.has(agent) &&
+                !this.agents.has(agent.name);
+            const frameReachedTerminal = (!generationLost || disposedEphemeralWithoutSuccessor) &&
+                !preserveEventGateForSuccessor;
             // §10.5: exactly one terminal per `started`, on every exit path the
             // host controls. Which one was decided by the path taken (default
             // completed; catch → failed; framework-cancel → aborted). A host
@@ -6238,28 +6683,35 @@ export class AgentFramework {
             // all incoming events → the agent silently stops waking on messages
             // (typing still stops, compression still runs — matching the observed
             // wedge). onInferenceEnded is idempotent, so a redundant call is safe.
-            this.eventGate?.onInferenceEnded(agent.name);
-            this.lastInferenceAt.set(agent.name, { ...this.lastInferenceAt.get(agent.name), endedAt: Date.now() });
+            if (ownsPhysicalStream && !preserveEventGateForSuccessor) {
+                this.eventGate?.onInferenceEnded(agent.name);
+            }
+            if (!generationLost && ownsPhysicalStream) {
+                this.lastInferenceAt.set(agent.name, { ...this.lastInferenceAt.get(agent.name), endedAt: Date.now() });
+            }
             if (ownsProviderGate)
                 this.releasePrimaryProviderGate(agent.name);
             // Stop the typing indicator on every exit path (complete, error,
             // exhausted, abort) so it never sticks after the turn ends.
-            this.channelRegistry?.stopTyping();
+            if (frameReachedTerminal)
+                this.channelRegistry?.stopTyping();
             // Spec 14.3: flush any held line-start text, then close each streamed
             // channel with its final moderated content — the consumer's signal to
             // finalize (end the TTS utterance, settle the rendered message).
-            if (proseStream) {
+            if (frameReachedTerminal && proseStream) {
                 emitOutgoing(proseStream.finish());
                 for (const [channelId, text] of proseStream.byChannel()) {
                     this.channelRegistry.sendOutgoingComplete(channelId, agent.name, outgoingInferenceId, text);
                 }
             }
             this.frameworkCancelledStreams.delete(`${agent.name}:${myStreamId}`);
-            this.activeStreams.delete(agent.name);
-            this.pendingAssistantBlocks.delete(agent.name);
+            if (ownsPhysicalStream) {
+                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)) {
+            if (ownsPhysicalStream && this.closingConversationAgents.has(agent.name)) {
                 this.disposeConversationAgent(agent.name);
             }
             // The turn is torn down — release the turn-alive marker BEFORE the
@@ -6273,11 +6725,14 @@ export class AgentFramework {
                 this.activeTurnTokens.delete(agent.name);
                 this.activeTurnTriggers.delete(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);
+            // Flush any deferred messages (e.g. if stream failed while tools were
+            // pending). Only THIS agent's messages: other targets' entries wait
+            // for their own boundaries (re-adding via addMessage re-defers if the
+            // target has meanwhile started a turn).
+            if (frameReachedTerminal && this.deferredMessages.length > 0 && this.pendingAssistantBlocks.size === 0) {
+                const deferred = this.drainDeferredFor(agent.name);
                 for (const msg of deferred) {
-                    this.addMessage(msg.participant, msg.content, msg.metadata);
+                    this.addMessage(msg.participant, msg.content, msg.metadata, msg.forAgent ? { forAgent: msg.forAgent } : undefined);
                 }
             }
         }
@@ -6368,7 +6823,7 @@ export class AgentFramework {
         // and a message arriving during that await must land before the pair,
         // never between tool_use and its tool_result. The two addMessage calls
         // below are synchronous and adjacent — nothing can interleave.
-        const { blocks } = await this.buildStoredToolResultContent([{ id: toolUseId, name: toolName, input, result, durationMs }], this.resolveToolResultInlineCap(agent).cap);
+        const { blocks } = await this.buildStoredToolResultContent(agentName, [{ id: toolUseId, name: toolName, input, result, durationMs }], this.resolveToolResultInlineCap(agent).cap);
         const cm = agent.getContextManager();
         cm.addMessage(agentName, [
             { type: 'tool_use', id: toolUseId, name: toolName, input },
@@ -6816,13 +7271,25 @@ export class AgentFramework {
      * #89). Returns the stored blocks plus the per-call spill outcomes so the
      * live wire copy can reuse the identical strings.
      */
-    async buildStoredToolResultContent(toolResults, maxChars) {
+    async buildStoredToolResultContent(agentName, toolResults, maxChars) {
         const spilled = new Map();
         const dateLabel = new Date().toISOString().slice(0, 10);
+        const ledger = this.toolImageLedgerFor(agentName);
         for (const tc of toolResults) {
+            // Retain every image the result carries BEFORE the placeholder is
+            // written (issue #104): the placeholder embeds the ref, so the image
+            // stays reachable by provenance after the bytes leave the wire.
             const raw = tc.result.isError
                 ? tc.result.error ?? 'Unknown error'
-                : toolResultDataToHistoryString(tc.result.data, undefined);
+                : toolResultDataToHistoryString(tc.result.data, undefined, {
+                    imageRef: (blockIndex, image) => ledger.retain({
+                        toolCallId: tc.id,
+                        toolName: tc.name,
+                        blockIndex,
+                        data: image.data,
+                        mediaType: image.mimeType,
+                    }).ref,
+                });
             spilled.set(tc.id, await this.spillOrTruncate(raw, maxChars, `${dateLabel}-${tc.id}`));
         }
         const blocks = toolResults.map(tc => ({
@@ -6839,6 +7306,13 @@ export class AgentFramework {
     async spillOrTruncate(content, cap, label) {
         if (!cap || content.length <= cap)
             return { text: content, filePath: null };
+        // The stored text is the only place save_recent_image discovers tool
+        // images, and the live wire delivers every image regardless of text
+        // length — so an image slot dropped by the cut is an image the resident
+        // saw that the index would silently slide past (issue #104). Keep the
+        // slots at or past the cut, re-appended after the notice.
+        const { head, tail } = splitPreservingImageSlots(content, cap);
+        const kept = formatPreservedImageSlots(tail);
         const workspace = this.getWorkspaceModule();
         const mountName = workspace ? this.firstWritableMountName(workspace) : null;
         if (workspace && mountName) {
@@ -6849,10 +7323,11 @@ export class AgentFramework {
                 const result = await workspace.writeBinary(path, Buffer.from(content, 'utf8'), 'text/plain');
                 if (result.success) {
                     return {
-                        text: safeSlice(content, 0, cap)
-                            + `\n\n[truncated — showing ${cap} of ${content.length} chars; full content: workspace file ${path}. `
+                        text: head
+                            + `\n\n[truncated — showing ${head.length} of ${content.length} chars; full content: workspace file ${path}. `
                             + 'Read/grep it with your file tools, or raise the inline cap via '
-                            + 'agent_settings update tool_result_inline_max_chars.]',
+                            + 'agent_settings update tool_result_inline_max_chars.]'
+                            + kept,
                         filePath: path,
                     };
                 }
@@ -6874,15 +7349,17 @@ export class AgentFramework {
             });
             console.error(`[spill] workspace write failed for ${path} (${content.length} chars): ${failure}`);
             return {
-                text: safeSlice(content, 0, cap)
-                    + `\n\n[truncated — showing ${cap} of ${content.length} chars; spill to workspace file ${path} FAILED`
-                    + ` (${failure}); content over the cap was not retained]`,
+                text: head
+                    + `\n\n[truncated — showing ${head.length} of ${content.length} chars; spill to workspace file ${path} FAILED`
+                    + ` (${failure}); content over the cap was not retained]`
+                    + kept,
                 filePath: null,
             };
         }
         return {
-            text: safeSlice(content, 0, cap)
-                + '\n\n[truncated — original was ' + content.length + ' chars; no writable workspace, full content not retained]',
+            text: head
+                + '\n\n[truncated — original was ' + content.length + ' chars; no writable workspace, full content not retained]'
+                + kept,
             filePath: null,
         };
     }
@@ -7085,6 +7562,14 @@ export class AgentFramework {
         }
         return hasImage ? blocks : null;
     }
+    toolImageLedgerFor(agentName) {
+        let ledger = this.toolImageLedgers.get(agentName);
+        if (!ledger) {
+            ledger = new ToolImageLedger();
+            this.toolImageLedgers.set(agentName, ledger);
+        }
+        return ledger;
+    }
     /** Strategy-derived per-message bound (maxMessageTokens * 4 chars). */
     strategyDerivedToolResultChars(agent) {
         const strategy = agent.getContextManager().getStrategy();
@@ -7255,6 +7740,27 @@ export class AgentFramework {
             this.dispatchGateToolCall(agentName, enrichedCall);
             return;
         }
+        // Route the tune-out tool (residents) and the subconscious's surface
+        if (enrichedCall.name === 'tune_out' && this.tuneOutCoordinator) {
+            this.dispatchTuneOutToolCall(agentName, enrichedCall);
+            return;
+        }
+        if (this.tuneOutCoordinator &&
+            agentName === this.subconsciousAgentName &&
+            SUBCONSCIOUS_TOOL_NAMES.includes(enrichedCall.name)) {
+            void this.tuneOutCoordinator
+                .handleSubconsciousTool(enrichedCall.name, enrichedCall.input)
+                .then((result) => {
+                this.queue.push({
+                    type: 'tool-result',
+                    callId: enrichedCall.id,
+                    agentName,
+                    moduleName: 'tune-out',
+                    result,
+                });
+            });
+            return;
+        }
         // Route sleep / wake tools
         if ((enrichedCall.name === 'sleep' || enrichedCall.name === 'wake') && this.eventGate) {
             this.dispatchSleepToolCall(agentName, enrichedCall);
@@ -7383,12 +7889,19 @@ export class AgentFramework {
             });
         });
     }
-    addMessage(participant, content, metadata) {
-        // Route to the primary agent's context manager (not ephemeral subagents).
-        const agent = this.primaryAgentName
-            ? this.agents.get(this.primaryAgentName)
-            : this.agents.values().next().value;
+    addMessage(participant, content, metadata, opts) {
+        // Route to the named agent, else the primary (not ephemeral subagents).
+        const agent = opts?.forAgent
+            ? this.agents.get(opts.forAgent)
+            : this.primaryAgentName
+                ? this.agents.get(this.primaryAgentName)
+                : this.agents.values().next().value;
         if (!agent) {
+            if (opts?.forAgent) {
+                console.error(`[addMessage] delivery target "${opts.forAgent}" is not a registered agent — message dropped ` +
+                    `(participant=${participant})`);
+                return '';
+            }
             throw new Error('No agents configured');
         }
         // Defer non-tool_result messages while a tool cycle is mid-flight
@@ -7408,15 +7921,39 @@ export class AgentFramework {
         // ALSO injected into the live stream — hear-while-acting), or in
         // driveStream's finally when the turn ends.
         const hasToolResult = content.some(b => b.type === 'tool_result');
+        // Explicitly-targeted deliveries scope the tool-cycle check to the
+        // target (pendingAssistantBlocks is keyed by agent); the default path
+        // keeps the historical GLOBAL check byte-for-byte (conservative: any
+        // agent's pending cycle defers primary-bound messages).
+        const midToolCycle = opts?.forAgent
+            ? this.pendingAssistantBlocks.has(agent.name)
+            : this.pendingAssistantBlocks.size > 0;
         if (!hasToolResult &&
-            (this.pendingAssistantBlocks.size > 0 ||
+            (midToolCycle ||
                 this.activeTurnTokens.has(agent.name) ||
                 this.activeStreams.has(agent.name))) {
-            this.deferredMessages.push({ participant, content, metadata });
-            return ''; // Deferred — flushed at the next boundary
+            this.deferredMessages.push({ participant, content, metadata, forAgent: opts?.forAgent });
+            return ''; // Deferred — flushed at the target's next boundary
         }
         return agent.getContextManager().addMessage(participant, content, metadata);
     }
+    /**
+     * Splice out the deferred messages addressed to `agentName` (explicitly
+     * via forAgent, or implicitly when it is the primary), leaving other
+     * targets' messages queued for their own boundaries.
+     */
+    drainDeferredFor(agentName) {
+        if (this.deferredMessages.length === 0)
+            return [];
+        const mine = [];
+        const rest = [];
+        for (const msg of this.deferredMessages) {
+            const target = msg.forAgent ?? this.primaryAgentName;
+            (target === agentName ? mine : rest).push(msg);
+        }
+        this.deferredMessages = rest;
+        return mine;
+    }
     editMessage(id, content) {
         const agent = this.primaryAgentName
             ? this.agents.get(this.primaryAgentName)
@@ -9400,6 +9937,50 @@ export class AgentFramework {
      * suppression window, optionally announces in the sticky channel, and ends
      * the turn (the agent goes idle immediately). `wake` clears sleep.
      */
+    /** tune_out tool (residents): enter or cancel a channel tune-out. */
+    dispatchTuneOutToolCall(agentName, call) {
+        const coordinator = this.tuneOutCoordinator;
+        const input = (call.input ?? {});
+        const channelId = String(input.channelId ?? '');
+        const entry = this.channelRegistry?.listChannelsRaw()
+            .find((e) => e.descriptor.id === channelId);
+        let result;
+        if (!entry) {
+            result = { success: false, error: `unknown channel: ${channelId}`, isError: false };
+        }
+        else if (input.mode === 'cancel') {
+            const r = coordinator.cancel(entry.serverId, channelId, 'agent-tool', 'agent request');
+            result = r.ok
+                ? { success: true, data: { cancelled: channelId } }
+                : { success: false, error: r.error, isError: false };
+        }
+        else {
+            const r = coordinator.enter(entry.serverId, channelId, {
+                cadenceSeconds: input.cadenceSeconds,
+                backlogCap: input.backlogCap,
+                maxWakes: input.maxWakes,
+                durationSeconds: input.durationSeconds,
+            }, 'agent-tool');
+            result = r.ok
+                ? {
+                    success: true,
+                    data: {
+                        tunedOut: channelId,
+                        cadenceSeconds: r.params.cadenceSeconds,
+                        backlogCap: r.params.backlogCap,
+                        maxWakes: r.params.maxWakes,
+                    },
+                }
+                : { success: false, error: r.error, isError: false };
+        }
+        this.queue.push({
+            type: 'tool-result',
+            callId: call.id,
+            agentName,
+            moduleName: 'tune-out',
+            result,
+        });
+    }
     dispatchSleepToolCall(agentName, call) {
         this.emitTrace({ type: 'tool:started', module: 'gate', tool: call.name, callId: call.id, input: call.input });
         const gate = this.eventGate;
@@ -9591,10 +10172,53 @@ export class AgentFramework {
         })();
     }
     /**
-     * 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.
+     * `save_recent_image` barrier. Module tool calls in a batch are only
+     * ENQUEUED by dispatch, while the save runs at once — so a [snap, save]
+     * round would inventory before the snapshot exists and silently save the
+     * newest OLDER image (issue #104, same-batch representation). Wait for
+     * every sibling in the round to settle; if one never does, fail closed
+     * rather than trust an index the batch may still change. Sibling saves
+     * produce no images and are not waited on (two saves in one batch would
+     * otherwise deadlock into a double timeout). Script-inner calls
+     * (`pytc-…`) run sequentially inside their script host and skip the
+     * barrier — the host call itself is the only pending sibling they'd see.
+     */
+    async awaitSiblingToolCalls(agent, call) {
+        if (call.id.startsWith('pytc-'))
+            return;
+        const BARRIER_MS = 120_000;
+        const POLL_MS = 20;
+        const startedAt = Date.now();
+        for (;;) {
+            const state = agent.state;
+            // Idle (puppet path) or the round was torn down: nothing to wait on.
+            if (state.status !== 'waiting_for_tools')
+                return;
+            const open = [...state.pending.values()].filter((p) => p.id !== call.id && p.name !== 'save_recent_image');
+            if (open.length === 0)
+                return;
+            if (Date.now() - startedAt > BARRIER_MS) {
+                throw new Error(`save_recent_image: ${open.length} sibling tool call(s) in this batch still pending after ` +
+                    `${Math.round(BARRIER_MS / 1000)}s (${open.map((p) => `${p.name} (call ${p.id})`).join(', ')}) — their results ` +
+                    'may carry newer images than anything in your context, so no index can be trusted yet. Nothing written. ' +
+                    'Save again once they have finished.');
+            }
+            await new Promise((r) => setTimeout(r, POLL_MS));
+        }
+    }
+    /**
+     * Handle the synthesized `save_recent_image` tool (issue #104): build ONE
+     * ordered inventory of every image the calling agent has seen — attachment
+     * image blocks (blobs re-inlined) AND tool-result images (their history
+     * placeholders carry a ref, resolved through the agent's ToolImageLedger)
+     * — counted back from the most recent, then write the requested bytes to
+     * a workspace mount via WorkspaceModule.writeBinary.
+     *
+     * Fail-closed: when the image at a requested position cannot be produced
+     * (bytes evicted, minted by an earlier process, or a placeholder written
+     * before retention existed) the call fails AT THAT INDEX and writes
+     * nothing. It never slides to an older image — a filename must not
+     * authenticate bytes from another surface.
      */
     dispatchSaveImageToolCall(agentName, call) {
         this.emitTrace({ type: 'tool:started', module: 'workspace', tool: call.name, callId: call.id, input: call.input });
@@ -9621,16 +10245,166 @@ export class AgentFramework {
                 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 ledger = this.toolImageLedgerFor(agentName);
+                const describeTool = (c) => `${c.toolName} (call ${c.toolCallId})`;
+                const unavailable = (status) => status === 'evicted'
+                    ? 'its bytes were evicted from the bounded retention budget'
+                    : 'this process has no record of that ref (refs are per-process and a restart clears them; ' +
+                        'very old refs age out; a mistyped ref looks the same)';
+                const resolve = (candidate, position) => {
+                    const rangeOffset = 0; // filled by the caller
+                    if (candidate.kind === 'attachment') {
+                        if (candidate.data === null) {
+                            throw new Error(`save_recent_image: image at index ${position} is not stored inline (base64) — cannot save it. Nothing written.`);
+                        }
+                        const bytes = Buffer.from(candidate.data, 'base64');
+                        return {
+                            rangeOffset,
+                            data: candidate.data,
+                            mediaType: candidate.mediaType,
+                            receipt: {
+                                source: 'attachment',
+                                mediaType: candidate.mediaType,
+                                byteSize: bytes.byteLength,
+                                sha256: sha256Hex(bytes),
+                                messagesBack: candidate.messagesBack,
+                            },
+                        };
+                    }
+                    if (candidate.kind === 'reference') {
+                        throw new Error(`save_recent_image: image at index ${position} is a reference (${candidate.refId}, ${candidate.mediaType}, ` +
+                            `from ${describeTool(candidate)}) — its bytes are not held here. Nothing written. ` +
+                            'Fetch it with fetch_reference and save the materialized file instead.');
+                    }
+                    if (candidate.ref === null) {
+                        throw new Error(`save_recent_image: image at index ${position} is a tool-result image from ${describeTool(candidate)} ` +
+                            'recorded without a retention ref (written before tool-image retention existed, or inside a ' +
+                            'script run, where tool images are not retained) — its bytes are not available. Nothing written. ' +
+                            'Re-run the tool for a fresh image rather than saving an older one.');
+                    }
+                    const lookup = ledger.lookup(candidate.ref);
+                    // The placeholder came out of stored TEXT, which a tool result can
+                    // quote from anywhere (a fetch_history of a channel where someone
+                    // pasted their save receipt). A genuine placeholder is written by
+                    // its own call's serialization, so the ref's provenance names that
+                    // call; a quoted or forged one cannot. Refuse the mismatch.
+                    if (lookup.status !== 'unknown' && lookup.image.toolCallId !== candidate.toolCallId) {
+                        throw new Error(`save_recent_image: image at index ${position} cites ${candidate.ref}, but that image belongs to ` +
+                            `${describeTool(lookup.image)}, not to ${describeTool(candidate)} where the placeholder appears — ` +
+                            'the placeholder is quoted or forged text, not this result\'s own image. Nothing written.');
+                    }
+                    if (lookup.status !== 'retained') {
+                        throw new Error(`save_recent_image: image at index ${position} (${candidate.ref}, from ${describeTool(candidate)}) ` +
+                            `is no longer retained — ${unavailable(lookup.status)}. Nothing written. ` +
+                            'Re-run the tool for a fresh image rather than saving an older one.');
+                    }
+                    const image = lookup.image;
+                    return {
+                        rangeOffset,
+                        data: image.data,
+                        mediaType: image.mediaType,
+                        receipt: {
+                            source: 'tool-result',
+                            ref: image.ref,
+                            toolName: image.toolName,
+                            toolCallId: image.toolCallId,
+                            blockIndex: image.blockIndex,
+                            mediaType: image.mediaType,
+                            byteSize: image.byteSize,
+                            sha256: image.sha256,
+                            messagesBack: candidate.messagesBack,
+                        },
+                    };
+                };
+                // Barrier: a save dispatched alongside other calls in one batch must
+                // not inventory before their results exist — those are the newest
+                // images. Waits (bounded) for every sibling to settle, or fails closed.
+                await this.awaitSiblingToolCalls(agent, call);
+                const found = [];
+                let index = 0;
+                let count = 1;
+                /** Direct-ref mode: the one ref to find in the scannable context. */
+                let wantedRef = null;
+                if (input.ref !== undefined) {
+                    if (typeof input.ref !== 'string' || !TOOL_IMAGE_REF_RE.test(input.ref)) {
+                        throw new Error('save_recent_image: `ref` must look like "img_k7x3q2_7" (copy it from the image placeholder in your context)');
+                    }
+                    if (input.index !== undefined || input.count !== undefined) {
+                        throw new Error('save_recent_image: `ref` is mutually exclusive with `index`/`count`');
+                    }
+                    wantedRef = input.ref;
                 }
-                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}`);
+                else {
+                    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');
+                    }
+                    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;
+                let seen = 0;
+                const collecting = () => (wantedRef !== null ? found.length === 0 : found.length < count);
+                // One walk serves both modes. By index: the requested range of the
+                // ordered inventory. By ref: the slot whose placeholder cites that
+                // ref — the ref is resolved THROUGH its occurrence in context, so
+                // the same provenance cross-check applies (a ref that is not visible
+                // in the scannable window — an undone branch, quoted text naming a
+                // real ref — is not saveable by name either).
+                const consider = (candidate) => {
+                    if (wantedRef !== null) {
+                        if (candidate.kind === 'tool' && candidate.ref === wantedRef && found.length === 0) {
+                            found.push(resolve(candidate, seen));
+                        }
+                    }
+                    else if (seen >= index && seen <= lastWanted) {
+                        const resolved = resolve(candidate, seen);
+                        resolved.rangeOffset = seen - index;
+                        found.push(resolved);
+                    }
+                    seen++;
+                };
+                const considerToolResultImages = (toolCallId, toolName, placeholders, messagesBack) => {
+                    for (let p = placeholders.length - 1; p >= 0 && collecting(); p--) {
+                        const ph = placeholders[p];
+                        if (ph.kind === 'inline') {
+                            consider({ kind: 'tool', ref: ph.ref, toolCallId, toolName, mediaType: ph.mediaType, messagesBack });
+                            continue;
+                        }
+                        // Reference stub: the registry's testimony (when this process
+                        // still has the record) says whether it was an image; the
+                        // sniffed stub text is the fallback. Non-image references
+                        // are not slots.
+                        const testimony = referenceRegistry.get(ph.refId)?.testimony.mimeType?.toLowerCase() ?? ph.mediaType;
+                        if (!testimony || !testimony.startsWith('image/'))
+                            continue;
+                        consider({ kind: 'reference', refId: ph.refId, mediaType: testimony, toolCallId, toolName, messagesBack });
+                    }
+                };
+                // Same-batch results (e.g. a snapshot dispatched alongside the save)
+                // are not in the store yet but ARE the newest images. Classify them
+                // with the very serializer the commit path will run — contradiction
+                // blocks withheld, uri-form blocks as reference stubs, unknown shapes
+                // as no slot at all — so the inventory means the same thing before
+                // and after commit. Retention is idempotent per block, so the
+                // placeholder written at commit time carries the same ref.
+                const state = agent.state;
+                if (state.status === 'waiting_for_tools') {
+                    for (let i = state.completed.length - 1; i >= 0 && collecting(); i--) {
+                        const tc = state.completed[i];
+                        if (tc.result.isError)
+                            continue;
+                        const text = toolResultDataToHistoryString(tc.result.data, undefined, {
+                            imageRef: (blockIndex, image) => ledger.retain({
+                                toolCallId: tc.id, toolName: tc.name, blockIndex, data: image.data, mediaType: image.mimeType,
+                            }).ref,
+                        });
+                        considerToolResultImages(tc.id, tc.name, parseImagePlaceholders(text), 0);
+                    }
+                }
                 // 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
@@ -9639,37 +10413,45 @@ export class AgentFramework {
                 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) {
+                for (let end = total; end > 0 && scanned < MAX_SCAN && collecting(); end -= WINDOW) {
                     const start = Math.max(0, end - WINDOW);
-                    const { messages } = cm.getMessageWindow(start, end - start, { resolveBlobs: true });
+                    // By ref, attachment bytes are never needed — skip blob resolution.
+                    const { messages } = cm.getMessageWindow(start, end - start, { resolveBlobs: wantedRef === null });
                     scanned += end - start;
-                    for (let i = messages.length - 1; i >= 0 && found.length < count; i--) {
+                    for (let i = messages.length - 1; i >= 0 && collecting(); i--) {
                         const content = messages[i]?.content;
                         if (!Array.isArray(content))
                             continue;
-                        for (let b = content.length - 1; b >= 0 && found.length < count; b--) {
+                        const messagesBack = total - (start + i);
+                        for (let b = content.length - 1; b >= 0 && collecting(); 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),
+                            if (block?.type === 'image') {
+                                const inline = block.source?.type === 'base64' && typeof block.source.data === 'string';
+                                consider({
+                                    kind: 'attachment',
+                                    data: inline ? block.source.data : null,
+                                    mediaType: block.source?.mediaType ?? 'image/png',
+                                    messagesBack,
                                 });
                             }
-                            seen++;
+                            else if (block?.type === 'tool_result' && typeof block.content === 'string') {
+                                considerToolResultImages(block.toolUseId ?? 'unknown', block.toolName ?? 'unknown tool', parseImagePlaceholders(block.content), messagesBack);
+                            }
                         }
                     }
                 }
                 if (found.length === 0) {
+                    if (wantedRef !== null) {
+                        const lookup = ledger.lookup(wantedRef);
+                        throw new Error(lookup.status === 'unknown'
+                            ? `save_recent_image: ref ${wantedRef} cannot be saved — ${unavailable('unknown')}. Nothing written.`
+                            : `save_recent_image: ref ${wantedRef} (from ${describeTool(lookup.image)}) does not appear in your recent ` +
+                                `context (scanned ${Math.min(scanned, MAX_SCAN)} messages) — a ref is saved through its placeholder, ` +
+                                'which must be visible to you' +
+                                (lookup.status === 'evicted' ? '; its bytes were also evicted from the bounded retention budget' : '') +
+                                '. Nothing written.');
+                    }
                     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})`);
@@ -9705,7 +10487,7 @@ export class AgentFramework {
                     savedFiles.push({
                         ...result.data,
                         imageIndex: index + image.rangeOffset,
-                        messagesBack: image.messagesBack,
+                        ...image.receipt,
                     });
                 }
                 finish({