@animalabs/agent-framework 0.12.0 → 0.14.0

package/src/framework.ts

@@ -5,8 +5,10 @@ import { appendFileSync, mkdirSync } from 'node:fs';
 import { JsStore } from '@animalabs/chronicle';
 import type { Membrane, ContentBlock, NormalizedRequest, YieldingStream, ToolResult as MembraneToolResult, ToolResultContentBlock } from '@animalabs/membrane';
 import { MembraneError } from '@animalabs/membrane';
-import { ContextManager, PassthroughStrategy } from '@animalabs/context-manager';
+import { ContextManager, PassthroughStrategy, WindowedPassthroughStrategy } from '@animalabs/context-manager';
 import type { CacheWireReceipt } from './kv-unified-wire.js';
+import { SUBCONSCIOUS_TOOLS, SUBCONSCIOUS_TOOL_NAMES, type SubconsciousConfig } from './tune-out/tools.js';
+import { TuneOutCoordinator, TUNE_OUT_DEFAULTS } from './tune-out/coordinator.js';
 import type {
   MessageId,
   MessageMetadata,
@@ -67,6 +69,7 @@ import { HookOrchestrator } from './mcpl/hook-orchestrator.js';
 import { PushHandler, type McplPushEvent } 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, type ChannelToolOrigin } from './mcpl/channel-registry.js';
 import { ConversationRouter } from './mcpl/conversation-router.js';
@@ -77,6 +80,15 @@ import {
   truncateForHistory,
   DEFAULT_TOOL_RESULT_INLINE_MAX_CHARS,
 } from './tool-result-history.js';
+import {
+  TOOL_IMAGE_REF_RE,
+  ToolImageLedger,
+  formatPreservedImageSlots,
+  parseImagePlaceholders,
+  sha256Hex,
+  splitPreservingImageSlots,
+  type ParsedImagePlaceholder,
+} from './tool-image-ledger.js';
 import { randomUUID } from 'node:crypto';
 import { PyRunner, buildInjectedTools } from './code-execution/py-runner.js';
 import {
@@ -788,6 +800,16 @@ export class AgentFramework {
   private frameworkCancelledStreams: Map<string, 'turn_ended' | 'budget_restart'> = new Map();
   /** Active runEphemeralToCompletion runs, keyed by agent name. */
   private ephemeralRuns: Map<string, EphemeralRun> = 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. */
+  private usedEphemeralAgentNames: Set<string> = new Set();
+  /** One-shot generation tickets minted by createEphemeralAgent. */
+  private ephemeralCandidates: WeakMap<Agent, ContextManager> = 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. */
+  private disposedEphemeralFrames: WeakSet<Agent> = new WeakSet();
   /** Per-agent count of consecutive exhausted inferences (reset on any success).
    *  Drives hard-down escalation — see noteInferenceExhausted. */
   private consecutiveInferenceFailures: Map<string, number> = new Map();
@@ -841,7 +863,23 @@ export class AgentFramework {
 
   // Messages deferred while an agent is waiting_for_tools (to preserve
   // tool_use → tool_result adjacency required by the Anthropic API).
-  private deferredMessages: Array<{ participant: string; content: ContentBlock[]; metadata?: MessageMetadata }> = [];
+  /** The subconscious resident's registry name (issue #77), or null. */
+  private subconsciousAgentName: string | null = null;
+  /** Its windowed strategy — the coordinator moves the anchor on tune-out entry. */
+  private subconsciousStrategy: WindowedPassthroughStrategy | null = null;
+  /** Its config (speak_in_channel gate, voice block provenance). */
+  private subconsciousConfig: SubconsciousConfig | null = null;
+  /** Tune-out coordinator (issue #77); non-null iff subconscious + channels. */
+  private tuneOutCoordinator: TuneOutCoordinator | null = null;
+
+  private deferredMessages: Array<{
+    participant: string;
+    content: ContentBlock[];
+    metadata?: MessageMetadata;
+    /** Delivery target (registry name). Absent = the primary agent —
+     *  the historical behavior of every existing caller. */
+    forAgent?: string;
+  }> = [];
 
   // Turn-alive markers (2026-07-31 Mythos phantom-skip incident): agentName →
   // token of the turn currently in progress. Set at startAgentStream ENTRY —
@@ -873,6 +911,10 @@ export class AgentFramework {
   getActiveTurnTrigger(agentName: string): InferenceRequest | undefined {
     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. */
+  private logicalTurnToolCalls: WeakMap<Agent, { turnToken: number; count: number }> = new WeakMap();
   private nextTurnToken = 1;
 
   // Undo/redo state
@@ -927,6 +969,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. */
   private toolResultInlineMaxCharsOverride: Map<string, number> = 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. */
+  private toolImageLedgers: Map<string, ToolImageLedger> = new Map();
   /** Durable residence-configured inline cap from
    *  FrameworkConfig.toolResultInlineMaxChars; null → house default. */
   private toolResultInlineMaxCharsConfig: number | null = null;
@@ -1131,6 +1178,13 @@ export class AgentFramework {
       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();
@@ -1180,11 +1234,21 @@ export class AgentFramework {
         initialConfig: config.gate.config,
         privilegedUsersPath: config.gate.privilegedUsersPath,
         emitTrace: (e) => framework.emitTrace(e as { type: TraceEvent['type']; [key: string]: unknown }),
-        addMessage: (p, c, m) => framework.addMessage(p, c, m as MessageMetadata),
-        requestInference: (agentName, reason, source) => {
-          framework.pendingRequests.push({ agentName, reason, source, timestamp: Date.now() });
+        addMessage: (p, c, m, forAgent) => framework.addMessage(p, c, m as MessageMetadata, 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),
       });
     }
 
@@ -1247,6 +1311,40 @@ 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 as MessageMetadata,
+              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 as never),
+        },
+      );
+      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
@@ -1316,6 +1414,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
@@ -1335,6 +1434,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();
@@ -1751,7 +1853,12 @@ export class AgentFramework {
    */
   getAllTools(): import('./types/index.js').ToolDefinition[] {
     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(),
@@ -2001,6 +2108,20 @@ export class AgentFramework {
     agentName: string,
     snapshot?: InferenceToolSnapshot,
   ): import('./types/index.js').ToolDefinition[] {
+    // 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(
@@ -2421,25 +2542,38 @@ export class AgentFramework {
     contextManager: ContextManager;
     cleanup: () => void;
   }> {
-    const namespace = `subagent/${config.name}`;
+    // 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 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 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.
-    };
+      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 };
+      return { agent, contextManager, cleanup };
+    } catch (error) {
+      this.usedEphemeralAgentNames.delete(config.name);
+      throw error;
+    }
   }
 
   private createDeferred<T>(): Deferred<T> {
@@ -2462,6 +2596,17 @@ 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. */
+  private recordLogicalTurnToolCalls(agent: Agent, turnToken: number, count: number): void {
+    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 });
+  }
+
   private recordEphemeralToolCalls(agentName: string, count: number): void {
     const run = this.ephemeralRuns.get(agentName);
     if (!run) return;
@@ -2505,7 +2650,18 @@ export class AgentFramework {
     contextManager: ContextManager,
     watchdogs?: { startupTimeoutMs?: number; idleTimeoutMs?: number; idlePollMs?: number },
   ): Promise<{ speech: string; toolCallsCount: number }> {
-    // 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: EphemeralRun = {
       settle: this.createDeferred<AgentSettleResult>(),
@@ -2570,8 +2726,26 @@ export class AgentFramework {
     } finally {
       if (startupWatchdog) 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.
@@ -2583,6 +2757,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);
     }
   }
 
@@ -2597,6 +2772,48 @@ 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. */
+  private static readonly TUNE_OUT_TOOL: import('./types/index.js').ToolDefinition = {
+    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). */
   private static readonly SLEEP_TOOLS: import('./types/index.js').ToolDefinition[] = [
     {
@@ -2789,11 +3006,18 @@ export class AgentFramework {
     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: {
@@ -2809,6 +3033,12 @@ 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'],
     },
@@ -4040,6 +4270,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 as { tuneOut?: unknown } | undefined)?.tuneOut,
     });
 
     const agent = new Agent(config, contextManager, this.membrane);
@@ -4060,6 +4299,71 @@ 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.
+   */
+  private async createSubconsciousAgent(cfg: SubconsciousConfig): Promise<Agent> {
+    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: 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;
+  }
+
   private async runLoop(): Promise<void> {
     while (this.running) {
       try {
@@ -4172,7 +4476,7 @@ export class AgentFramework {
           // byte-matched (the window stores what the membrane sends;
           // divergence breaks the compile prefix).
           const { blocks: toolResultContent, spilled } =
-            await this.buildStoredToolResultContent(currentState.toolResults, maxChars);
+            await this.buildStoredToolResultContent(agent.name, currentState.toolResults, maxChars);
           agent.getContextManager().addMessage('user', toolResultContent);
 
           // Flush any messages that were deferred while this turn was in
@@ -4198,12 +4502,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: Array<{ participant: string; content: ContentBlock[]; metadata?: MessageMetadata }> = [];
-          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
@@ -4538,7 +4841,8 @@ export class AgentFramework {
       // 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) {
@@ -4575,6 +4879,7 @@ export class AgentFramework {
     metadata?: Record<string, unknown>;
     tags?: string[];
     triggerInference?: boolean;
+    targetAgents?: string[];
   }): Promise<void> {
     const metadata: Record<string, unknown> = {
       ...event.metadata,
@@ -4621,12 +4926,38 @@ export class AgentFramework {
       }
     }
 
+    // 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',
@@ -4757,41 +5088,50 @@ export class AgentFramework {
     if (!template || !templateConfig) {
       throw new Error(`conversation template agent "${router.templateAgent}" not found`);
     }
+    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,
-    });
+      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);
+      // Seed with the template's compiled context, renaming the template
+      // participant so the fork reads its inheritance as its own history.
+      // Guard: only seed a genuinely fresh namespace. Generation counters are
+      // persisted precisely so names aren't reused, but if this namespace has
+      // history anyway (counter state lost, crash between spawn and persist),
+      // seeding again would stack another template copy on top of it.
+      const { messages: existing } = await contextManager.compile();
+      if (existing.length === 0) {
+        const { messages: compiled } = await template.getContextManager().compile();
+        for (const msg of compiled) {
+          const participant = msg.participant === template.name ? name : msg.participant;
+          contextManager.addMessage(participant, msg.content);
+        }
       }
-    }
 
-    const config: AgentConfig = { ...templateConfig, name, strategy: undefined };
-    const agent = new Agent(config, contextManager, this.membrane);
-    this.agents.set(name, agent);
-    this.agentConfigs.set(name, config);
-    this.conversationAgentHomes.set(name, channelId);
-    return agent;
+      const config: AgentConfig = { ...templateConfig, name, strategy: undefined };
+      const agent = new Agent(config, contextManager, this.membrane);
+      this.agents.set(name, agent);
+      this.agentConfigs.set(name, config);
+      this.conversationAgentHomes.set(name, channelId);
+      return agent;
+    } catch (error) {
+      this.usedEphemeralAgentNames.delete(name);
+      throw error;
+    }
   }
 
   /** Persist the router's generation counters (see hydration in create()). */
@@ -4815,10 +5155,13 @@ export class AgentFramework {
   private disposeConversationAgent(agentName: string): void {
     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,
@@ -5054,7 +5397,8 @@ 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,
@@ -5255,6 +5599,9 @@ export class AgentFramework {
           `[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;
@@ -5294,6 +5641,17 @@ export class AgentFramework {
         if (r.addressed) 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: InferenceRequest | undefined = 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,
@@ -5302,7 +5660,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,
       });
     }
   }
@@ -5846,9 +6206,8 @@ export class AgentFramework {
       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
@@ -5906,8 +6265,21 @@ 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).
@@ -5941,7 +6313,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
@@ -6004,12 +6380,38 @@ export class AgentFramework {
         }
       }
 
+      // 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);
+      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,
@@ -6021,6 +6423,7 @@ export class AgentFramework {
         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;
@@ -6105,6 +6508,7 @@ export class AgentFramework {
     ownsProviderGate = false,
     takeKvSubmission?: () => { submissionId: string; wireReceipt: CacheWireReceipt } | undefined,
     drainKvSubmissionIds?: () => string[],
+    knownToolNames: ReadonlySet<string> = new Set(),
   ): Promise<void> {
     const startTime = Date.now();
     const requestId = `${agent.name}-${startTime}-${Math.random().toString(36).slice(2, 8)}`;
@@ -6124,6 +6528,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
@@ -6207,13 +6612,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' | 'aborted' | 'failed' = '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,
@@ -6243,6 +6655,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':
@@ -6310,6 +6730,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',
@@ -6492,6 +6913,7 @@ export class AgentFramework {
               const readyState = agent.state as AgentState;
               if (readyState.status === 'ready') {
                 const { blocks: toolResultContent } = await this.buildStoredToolResultContent(
+                  agent.name,
                   readyState.toolResults,
                   this.resolveToolResultInlineCap(agent).cap,
                 );
@@ -6515,7 +6937,30 @@ 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);
               }
@@ -6541,7 +6986,9 @@ export class AgentFramework {
             // text is speech.
             const isTextBlock = (block: ContentBlock): block is ContentBlock & { type: 'text' } =>
               block.type === 'text';
-            const allText = response.content.filter(isTextBlock);
+            const allText = guardedWrapperTool
+              ? []
+              : response.content.filter(isTextBlock);
 
             const speechContent = hadToolCalls ? [] : allText;
             const thoughts = hadToolCalls ? allText : [];
@@ -6556,19 +7003,30 @@ export class AgentFramework {
                 }
               : 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: ContentBlock): block is ContentBlock & { type: 'text' } => block.type === 'text')
-                .map((block) => block.text)
-                .join('\n'),
+              speech: guardedWrapperTool
+                ? ''
+                : terminalContent
+                    .filter((block: ContentBlock): block is ContentBlock & { type: 'text' } => block.type === 'text')
+                    .map((block) => block.text)
+                    .join('\n'),
             });
 
             this.emitTrace({
@@ -6942,7 +7400,7 @@ export class AgentFramework {
 
             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;
             }
 
@@ -6966,7 +7424,7 @@ 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);
               }
@@ -6988,7 +7446,13 @@ 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
@@ -7035,7 +7499,7 @@ 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;
           }
@@ -7128,6 +7592,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));
@@ -7138,7 +7610,7 @@ export class AgentFramework {
           error: `Provider acceleration cooldown: ${err.message}`,
           request: compiledRequest ?? { note: 'streaming request rate-limited' }, durationMs });
         this.abortAgentScript(agent.name, 'provider acceleration cooldown');
-        lifecyclePhase = 'failed'; agent.reset(); this.eventGate?.onInferenceEnded(agent.name);
+        lifecyclePhase = 'failed'; agent.reset(); if (this.agents.get(agent.name) === agent && agent.streamId === myStreamId) this.eventGate?.onInferenceEnded(agent.name);
         return;
       }
       this.emitTrace({
@@ -7173,7 +7645,7 @@ 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?.() ?? [];
       if (unsettledKvSubmissions.length > 0) {
@@ -7186,6 +7658,22 @@ 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
@@ -7204,30 +7692,36 @@ 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);
       }
 
@@ -7243,11 +7737,15 @@ export class AgentFramework {
         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);
         }
       }
     }
@@ -7350,6 +7848,7 @@ export class AgentFramework {
     // 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(
+      agentName,
       [{ id: toolUseId, name: toolName, input, result, durationMs }],
       this.resolveToolResultInlineCap(agent).cap,
     );
@@ -7856,6 +8355,7 @@ export class AgentFramework {
    * live wire copy can reuse the identical strings.
    */
   private async buildStoredToolResultContent(
+    agentName: string,
     toolResults: CompletedToolCall[],
     maxChars: number | undefined,
   ): Promise<{
@@ -7864,10 +8364,22 @@ export class AgentFramework {
   }> {
     const spilled = new Map<string, { text: string; filePath: string | null }>();
     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: ContentBlock[] = toolResults.map(tc => ({
@@ -7888,6 +8400,13 @@ export class AgentFramework {
     label: string,
   ): Promise<{ text: string; filePath: string | null }> {
     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;
@@ -7899,10 +8418,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,
           };
         }
@@ -7925,15 +8445,17 @@ export class AgentFramework {
         `[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,
     };
   }
@@ -8151,6 +8673,15 @@ export class AgentFramework {
     return hasImage ? blocks : null;
   }
 
+  private toolImageLedgerFor(agentName: string): ToolImageLedger {
+    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). */
   private strategyDerivedToolResultChars(agent: Agent): number | undefined {
     const strategy = agent.getContextManager().getStrategy();
@@ -8348,6 +8879,30 @@ export class AgentFramework {
       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 as readonly string[]).includes(enrichedCall.name)
+    ) {
+      void this.tuneOutCoordinator
+        .handleSubconsciousTool(enrichedCall.name, enrichedCall.input as Record<string, unknown>)
+        .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);
@@ -8492,13 +9047,32 @@ export class AgentFramework {
   private addMessage(
     participant: string,
     content: ContentBlock[],
-    metadata?: MessageMetadata
+    metadata?: MessageMetadata,
+    opts?: {
+      /**
+       * Deliver into this registry agent's window instead of the primary's,
+       * with the deferral/turn-alive guard evaluated against THAT agent's
+       * turn state. Default (absent) is byte-identical to the historical
+       * primary-only behavior. Unknown names log and drop (loud, non-fatal:
+       * this is reachable from timer callbacks that may outlive an agent).
+       */
+      forAgent?: string;
+    }
   ): MessageId {
-    // 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;
+    // 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 '' as MessageId;
+      }
       throw new Error('No agents configured');
     }
 
@@ -8519,19 +9093,48 @@ 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 '' as MessageId; // Deferred — flushed at the next boundary
+      this.deferredMessages.push({ participant, content, metadata, forAgent: opts?.forAgent });
+      return '' as MessageId; // 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.
+   */
+  private drainDeferredFor(agentName: string): Array<{
+    participant: string;
+    content: ContentBlock[];
+    metadata?: MessageMetadata;
+    forAgent?: string;
+  }> {
+    if (this.deferredMessages.length === 0) return [];
+    const mine: typeof this.deferredMessages = [];
+    const rest: typeof this.deferredMessages = [];
+    for (const msg of this.deferredMessages) {
+      const target = msg.forAgent ?? this.primaryAgentName;
+      (target === agentName ? mine : rest).push(msg);
+    }
+    this.deferredMessages = rest;
+    return mine;
+  }
+
   private editMessage(id: MessageId, content: ContentBlock[]): void {
     const agent = this.primaryAgentName
       ? this.agents.get(this.primaryAgentName)
@@ -10922,6 +11525,53 @@ 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. */
+  private dispatchTuneOutToolCall(agentName: string, call: ToolCall): void {
+    const coordinator = this.tuneOutCoordinator!;
+    const input = (call.input ?? {}) as {
+      channelId?: string; mode?: string;
+      cadenceSeconds?: number; backlogCap?: number; maxWakes?: number;
+      durationSeconds?: number;
+    };
+    const channelId = String(input.channelId ?? '');
+    const entry = this.channelRegistry?.listChannelsRaw()
+      .find((e) => e.descriptor.id === channelId);
+    let result: { success: boolean; data?: unknown; error?: string; isError?: boolean };
+    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,
+    });
+  }
+
   private dispatchSleepToolCall(agentName: string, call: ToolCall): void {
     this.emitTrace({ type: 'tool:started', module: 'gate', tool: call.name, callId: call.id, input: call.input });
     const gate = this.eventGate!;
@@ -11128,10 +11778,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.
+   */
+  private async awaitSiblingToolCalls(agent: Agent, call: ToolCall): Promise<void> {
+    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.
    */
   private dispatchSaveImageToolCall(agentName: string, call: ToolCall): void {
     this.emitTrace({ type: 'tool:started', module: 'workspace', tool: call.name, callId: call.id, input: call.input });
@@ -11146,26 +11839,219 @@ export class AgentFramework {
       });
       this.pushEvent({ type: 'tool-result', callId: call.id, agentName, moduleName: 'workspace', result });
     };
+    type Candidate =
+      | { kind: 'attachment'; data: string | null; mediaType: string; messagesBack: number }
+      | {
+        kind: 'tool';
+        ref: string | null;
+        /** The tool_result block the placeholder was found in — NOT trusted
+         *  text; a resolved ref must belong to this very call. */
+        toolCallId: string;
+        toolName: string;
+        mediaType: string;
+        messagesBack: number;
+      }
+      | {
+        kind: 'reference';
+        refId: string;
+        mediaType: string;
+        toolCallId: string;
+        toolName: string;
+        messagesBack: number;
+      };
+    interface Resolved {
+      rangeOffset: number;
+      data: string;
+      mediaType: string;
+      receipt: Record<string, unknown>;
+    }
     void (async (): Promise<void> => {
       try {
         const workspace = this.getWorkspaceModule();
         if (!workspace) throw new Error('save_recent_image requires a workspace module');
         const agent = this.agents.get(agentName);
         if (!agent) throw new Error(`Unknown agent: ${agentName}`);
-        const input = (call.input ?? {}) as { path?: unknown; index?: unknown; count?: unknown };
+        const input = (call.input ?? {}) as { path?: unknown; index?: unknown; count?: unknown; ref?: unknown };
         if (typeof input.path !== 'string' || input.path.length === 0) {
           throw new Error('save_recent_image: `path` (mount-prefixed) is required');
         }
-        const index = input.index === undefined ? 0 : Number(input.index);
-        if (!Number.isInteger(index) || index < 0) {
-          throw new Error('save_recent_image: `index` must be a non-negative integer');
-        }
-        const count = input.count === undefined ? 1 : Number(input.count);
-        const MAX_COUNT = 20;
-        if (!Number.isInteger(count) || count < 1 || count > MAX_COUNT) {
-          throw new Error(`save_recent_image: \`count\` must be an integer in 1..${MAX_COUNT}`);
+        const ledger = this.toolImageLedgerFor(agentName);
+
+        const describeTool = (c: { toolName: string; toolCallId: string }): string =>
+          `${c.toolName} (call ${c.toolCallId})`;
+        const unavailable = (status: 'evicted' | 'unknown'): string =>
+          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: Candidate, position: number): Resolved => {
+          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: Resolved[] = [];
+        let index = 0;
+        let count = 1;
+        /** Direct-ref mode: the one ref to find in the scannable context. */
+        let wantedRef: string | null = 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;
+        } 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 = (): boolean => (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: Candidate): void => {
+          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: string,
+          toolName: string,
+          placeholders: ParsedImagePlaceholder[],
+          messagesBack: number,
+        ): void => {
+          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
@@ -11175,45 +12061,56 @@ export class AgentFramework {
         const WINDOW = 25;
         const cm = agent.getContextManager();
         const total = cm.getMessageCount();
-        let seen = 0;
         let scanned = 0;
-        const found: Array<{
-          rangeOffset: number;
-          data: string;
-          mediaType: string;
-          messagesBack: number;
-        }> = [];
-        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] as {
                 type?: string;
                 source?: { type?: string; data?: string; mediaType?: string };
+                toolUseId?: string;
+                toolName?: string;
+                content?: unknown;
               };
-              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,
                 });
+              } else if (block?.type === 'tool_result' && typeof block.content === 'string') {
+                considerToolResultImages(
+                  block.toolUseId ?? 'unknown',
+                  block.toolName ?? 'unknown tool',
+                  parseImagePlaceholders(block.content),
+                  messagesBack,
+                );
               }
-              seen++;
             }
           }
         }
         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`
@@ -11252,7 +12149,7 @@ export class AgentFramework {
           savedFiles.push({
             ...(result.data as Record<string, unknown>),
             imageIndex: index + image.rangeOffset,
-            messagesBack: image.messagesBack,
+            ...image.receipt,
           });
         }
         finish({