@animalabs/agent-framework 0.6.7 → 0.6.10

package/dist/src/framework.js

@@ -1,6 +1,5 @@
 import { join } from 'node:path';
 import { appendFileSync, mkdirSync } from 'node:fs';
-import { createHash } from 'node:crypto';
 import { JsStore } from '@animalabs/chronicle';
 import { MembraneError } from '@animalabs/membrane';
 import { ContextManager, PassthroughStrategy } from '@animalabs/context-manager';
@@ -18,7 +17,26 @@ import { ConversationRouter } from './mcpl/conversation-router.js';
 import { safeSlice } from './safe-slice.js';
 import { toolResultDataToHistoryString } from './tool-result-history.js';
 import { splitProseSegments } from './prose-segments.js';
-import { canonicalJsonStringify } from './canonical-json.js';
+/** Detect a supported image media type from magic bytes (the model API
+ *  rejects mislabeled media types, so trust bytes over extensions).
+ *  Returns undefined for non-image content. */
+function sniffImageMediaType(data) {
+    if (data.length >= 4 && data[0] === 0x89 && data[1] === 0x50 && data[2] === 0x4e && data[3] === 0x47) {
+        return 'image/png';
+    }
+    if (data.length >= 3 && data[0] === 0xff && data[1] === 0xd8 && data[2] === 0xff) {
+        return 'image/jpeg';
+    }
+    if (data.length >= 3 && data[0] === 0x47 && data[1] === 0x49 && data[2] === 0x46) {
+        return 'image/gif';
+    }
+    if (data.length >= 12 &&
+        data[0] === 0x52 && data[1] === 0x49 && data[2] === 0x46 && data[3] === 0x46 &&
+        data[8] === 0x57 && data[9] === 0x45 && data[10] === 0x42 && data[11] === 0x50) {
+        return 'image/webp';
+    }
+    return undefined;
+}
 /**
  * Tools whose presence suppresses auto-routing of the surrounding prose,
  * for two distinct reasons:
@@ -51,12 +69,6 @@ const FRAMEWORK_STATE_ID = 'framework/state';
 const CONVERSATION_ROUTER_STATE_ID = 'framework/conversation-router';
 const INFERENCE_LOG_ID = 'framework/inference-log';
 const PROCESS_LOG_ID = 'framework/process-log';
-const PRIMARY_SUMMARY_FALLBACK_STATE_ID = 'framework/primary-summary-fallback';
-const PRIMARY_SUMMARY_SETTLEMENT_METADATA_KEY = 'primarySummarySettlement';
-const PRIMARY_SUMMARY_SETTLEMENT_VERSION = 1;
-const PRIMARY_SUMMARY_SETTLEMENT_MAX_ID_LENGTH = 1024;
-const PRIMARY_SUMMARY_SETTLEMENT_MAX_NAME_LENGTH = 256;
-const PRIMARY_SUMMARY_SETTLEMENT_MAX_REASON_LENGTH = 256;
 const TURN_CHECKPOINTS_ID = 'framework/turn-checkpoints'; // legacy single-map layout, read-only fallback
 const TURN_CHECKPOINTS_TREE_ID = 'framework/turn-checkpoints/tree';
 /** Maximum number of turn checkpoints to keep per agent. */
@@ -197,8 +209,6 @@ export class AgentFramework {
     processLoggingPersist;
     processLoggingBroadcast;
     activeStreams = new Map();
-    activeStreamContexts = new Map();
-    primarySummaryStateLock = Promise.resolve();
     /** Per-agent output locus pinned for the CURRENT logical turn (see
      *  resolveTurnLocus in driveStream). Lives here — not in driveStream
      *  locals — so the pin survives a context-budget stream restart, which
@@ -424,12 +434,6 @@ export class AgentFramework {
                 // Already registered
             }
         }
-        try {
-            store.registerState({ id: PRIMARY_SUMMARY_FALLBACK_STATE_ID, strategy: 'snapshot' });
-        }
-        catch {
-            // Already registered
-        }
         const discordAwarenessOutboxPath = config.discordAwarenessOutboxPath
             ?? (config.storePath ? defaultDiscordAwarenessOutboxPath(config.storePath) : undefined);
         const discordAwarenessOutbox = discordAwarenessOutboxPath
@@ -453,13 +457,12 @@ export class AgentFramework {
                 throw new DiscordAwarenessAccountingError('startup reconciliation', error);
             }
         }
+        // Restore persisted usage data (if any) from prior session
+        framework.restoreUsageState();
         // Create agents
         for (const agentConfig of config.agents) {
             await framework.createAgent(agentConfig);
         }
-        // Restore persisted usage data (if any) from prior session
-        framework.restoreUsageState();
-        await framework.reconcilePrimarySummaryFallbackStateOnStartup();
         // Finish any branch-local suppression interrupted after Chronicle switched
         // branches. This runs before modules, MCPL connections, or inbound traffic.
         await framework.resumePreparedDiscordSuppressions();
@@ -680,7 +683,7 @@ export class AgentFramework {
         const queued = [...this.agents.values()].flatMap((agent) => {
             const cm = agent.getContextManager();
             const tools = this.getToolsForAgent(agent.name).filter((tool) => agent.canUseTool(tool.name));
-            cm.setToolDefinitions?.(tools);
+            cm.setToolDefinitions(tools);
             if (cm.isReady())
                 return [];
             const pending = cm.getPendingWork()?.description;
@@ -868,7 +871,9 @@ export class AgentFramework {
             ...channelTools,
             ...gateTools,
             this.buildAgentSettingsTool(),
-            ...(this.getWorkspaceModule() ? [AgentFramework.SAVE_IMAGE_TOOL] : []),
+            ...(this.getWorkspaceModule()
+                ? [AgentFramework.SAVE_IMAGE_TOOL, AgentFramework.READ_IMAGE_TOOL]
+                : []),
         ];
     }
     /** The registered workspace module, if any (used by save_image). */
@@ -1251,1091 +1256,6 @@ export class AgentFramework {
         });
         return { promise, resolve, reject };
     }
-    hashJson(value) {
-        return createHash('sha256').update(canonicalJsonStringify(value), 'utf8').digest('hex');
-    }
-    estimateStringTokens(text, overhead = 0) {
-        return Math.ceil(Buffer.byteLength(text, 'utf8') / 4) + overhead;
-    }
-    estimateUnknownTokens(value, overhead = 0) {
-        return this.estimateStringTokens(JSON.stringify(value) ?? 'null', overhead);
-    }
-    estimateRequestInputBoundTokens(request) {
-        let total = 96;
-        total += this.estimateStringTokens(request.system ?? '', 48);
-        for (const message of request.messages) {
-            total += 24;
-            total += this.estimateStringTokens(message.participant, 8);
-            if (message.cacheBreakpoint)
-                total += 8;
-            for (const block of message.content) {
-                switch (block.type) {
-                    case 'text':
-                        total += this.estimateStringTokens(block.text, 24);
-                        break;
-                    case 'thinking':
-                        total += this.estimateStringTokens(block.thinking, 32);
-                        total += block.signature ? this.estimateStringTokens(block.signature, 8) : 0;
-                        break;
-                    case 'redacted_thinking':
-                        total += this.estimateUnknownTokens(block, 32);
-                        break;
-                    default:
-                        total += this.estimateUnknownTokens(block, 32);
-                        break;
-                }
-            }
-        }
-        if (request.tools && request.tools.length > 0) {
-            total += 32;
-            for (const tool of request.tools) {
-                total += this.estimateUnknownTokens({
-                    name: tool.name,
-                    description: tool.description,
-                    inputSchema: tool.inputSchema,
-                }, 48);
-            }
-        }
-        total += this.estimateUnknownTokens(request.config, 48);
-        if (request.providerParams !== undefined) {
-            total += this.estimateUnknownTokens(request.providerParams, 32);
-        }
-        total += request.promptCaching ? 16 : 0;
-        total += request.cacheTtl ? this.estimateStringTokens(request.cacheTtl, 8) : 0;
-        total += request.assistantParticipant
-            ? this.estimateStringTokens(request.assistantParticipant, 8)
-            : 0;
-        return total;
-    }
-    estimateRequestCompleteBoundTokens(request) {
-        const reserve = typeof request.config.maxTokens === 'number' && Number.isFinite(request.config.maxTokens)
-            ? request.config.maxTokens
-            : 0;
-        return this.estimateRequestInputBoundTokens(request) + reserve + 96;
-    }
-    primarySummaryAdmissionBoundTokens(originalRequestInputTokens, expandedRequest, originalProviderInputTokens) {
-        const expandedInput = this.estimateRequestInputBoundTokens(expandedRequest);
-        const expandedComplete = this.estimateRequestCompleteBoundTokens(expandedRequest);
-        if (originalProviderInputTokens === undefined)
-            return expandedComplete;
-        const reserve = typeof expandedRequest.config.maxTokens === 'number' && Number.isFinite(expandedRequest.config.maxTokens)
-            ? expandedRequest.config.maxTokens
-            : 0;
-        const positiveDelta = Math.max(0, expandedInput - originalRequestInputTokens);
-        return Math.max(expandedComplete, originalProviderInputTokens + positiveDelta + reserve + 96);
-    }
-    readPrimarySummaryFallbackState() {
-        const raw = this.store
-            ?.getStateJson?.(PRIMARY_SUMMARY_FALLBACK_STATE_ID);
-        if (!raw || typeof raw !== 'object')
-            return { requests: [] };
-        const requests = Array.isArray(raw.requests)
-            ? (raw.requests)
-            : [];
-        return { requests };
-    }
-    writePrimarySummaryFallbackState(state) {
-        this.store.setStateJson(PRIMARY_SUMMARY_FALLBACK_STATE_ID, state);
-    }
-    async withPrimarySummaryStateLock(work) {
-        const previous = this.primarySummaryStateLock;
-        let release;
-        this.primarySummaryStateLock = new Promise((resolve) => { release = resolve; });
-        await previous;
-        try {
-            return await work();
-        }
-        finally {
-            release();
-        }
-    }
-    async reconcilePrimarySummaryFallbackStateOnStartup() {
-        const alerts = [];
-        const unsettledRequests = (await this.withPrimarySummaryStateLock(() => this.readPrimarySummaryFallbackState().requests
-            .filter((record) => record.finalStatus === 'pending'
-            || record.finalStatus === 'refusal'
-            || record.fallbackStatus === 'pending')
-            .map((record) => structuredClone(record))));
-        const resolvedRequestIds = new Set();
-        for (const record of unsettledRequests) {
-            const result = await this.finalizePrimarySummarySettlementOnStartup(record);
-            if (result === 'finalized') {
-                resolvedRequestIds.add(record.requestId);
-                continue;
-            }
-            if (result && typeof result === 'object' && 'invalidReason' in result) {
-                resolvedRequestIds.add(record.requestId);
-                alerts.push({ agentName: record.agentName, requestId: record.requestId, reason: result.invalidReason });
-                await this.markPrimarySummaryRequestRestartFailure(record, result.invalidReason);
-            }
-        }
-        await this.withPrimarySummaryStateLock(() => {
-            const state = this.readPrimarySummaryFallbackState();
-            let changed = false;
-            state.requests = state.requests.map((record) => {
-                if (resolvedRequestIds.has(record.requestId))
-                    return record;
-                if (record.dispatchKind === 'primary_summary_fallback_retry' && (record.finalStatus === 'pending' || record.finalStatus === 'refusal')) {
-                    changed = true;
-                    const reason = 'primary_summary_fallback_unresolved_on_restart';
-                    alerts.push({ agentName: record.agentName, requestId: record.requestId, reason });
-                    return {
-                        ...record,
-                        finalStatus: 'held',
-                        fallbackHeldReason: reason,
-                    };
-                }
-                if (record.fallbackIntent && record.fallbackStatus === 'pending') {
-                    changed = true;
-                    const reason = 'primary_summary_fallback_unresolved_on_restart';
-                    alerts.push({ agentName: record.agentName, requestId: record.requestId, reason });
-                    return {
-                        ...record,
-                        fallbackStatus: 'held',
-                        fallbackHeldReason: reason,
-                    };
-                }
-                if (record.finalStatus === 'refusal') {
-                    changed = true;
-                    const reason = 'primary_summary_request_unresolved_on_restart';
-                    alerts.push({ agentName: record.agentName, requestId: record.requestId, reason });
-                    return {
-                        ...record,
-                        finalStatus: 'held',
-                        fallbackStatus: 'held',
-                        fallbackHeldReason: reason,
-                    };
-                }
-                if (record.finalStatus === 'pending') {
-                    changed = true;
-                    const reason = 'primary_summary_request_unresolved_on_restart';
-                    alerts.push({ agentName: record.agentName, requestId: record.requestId, reason });
-                    return {
-                        ...record,
-                        finalStatus: 'timeout_unknown',
-                        fallbackHeldReason: reason,
-                    };
-                }
-                return record;
-            });
-            if (changed)
-                this.writePrimarySummaryFallbackState({ requests: state.requests.slice(-256) });
-        });
-        for (const alert of alerts) {
-            this.opsAlert('refusal-held', alert.agentName, alert.reason, {
-                data: { requestId: alert.requestId },
-            });
-        }
-    }
-    primarySummaryIdentityKey(identity) {
-        return [
-            identity.id,
-            identity.contentHash,
-            identity.carrierHash,
-            identity.sourceLeafHash,
-        ].join('\u0000');
-    }
-    primarySummaryProjectionKeys(projection) {
-        return projection?.selectedSummaries.map((selection) => this.primarySummaryIdentityKey(selection.identity)) ?? [];
-    }
-    primarySummaryFallbackConfig(agent) {
-        const raw = agent.refusalHandling?.primarySummaryFallback;
-        const fallbackBudgetBase = agent.contextBudgetTokens ?? 100_000;
-        return {
-            enabled: raw?.enabled === true,
-            maxNewSummaries: typeof raw?.maxNewSummaries === 'number' && Number.isSafeInteger(raw.maxNewSummaries)
-                ? Math.max(0, raw.maxNewSummaries)
-                : 4,
-            requestBudgetTokens: typeof raw?.requestBudgetTokens === 'number' && Number.isFinite(raw.requestBudgetTokens) && raw.requestBudgetTokens > 0
-                ? raw.requestBudgetTokens
-                : fallbackBudgetBase + agent.maxTokens,
-        };
-    }
-    latestCompatibleHealthyPrimaryRequest(current, state) {
-        for (let i = state.requests.length - 1; i >= 0; i--) {
-            const candidate = state.requests[i];
-            if (candidate.requestId === current.requestId)
-                continue;
-            if (candidate.agentName !== current.agentName)
-                continue;
-            if (candidate.namespace !== current.namespace)
-                continue;
-            if (candidate.branch.id !== current.branch.id)
-                continue;
-            if (candidate.branch.generation !== current.branch.generation)
-                continue;
-            if (candidate.systemHash !== current.systemHash)
-                continue;
-            if (candidate.modelConfigHash !== current.modelConfigHash)
-                continue;
-            if (candidate.toolContractHash !== current.toolContractHash)
-                continue;
-            if (candidate.dispatchKind !== 'primary')
-                continue;
-            if (candidate.fallbackIntent || candidate.fallbackStatus)
-                continue;
-            if (candidate.finalStatus !== 'success')
-                continue;
-            return candidate;
-        }
-        return null;
-    }
-    async persistPrimarySummaryRequestRecord(record) {
-        await this.withPrimarySummaryStateLock(() => {
-            const state = this.readPrimarySummaryFallbackState();
-            const requests = state.requests.filter((entry) => entry.requestId !== record.requestId);
-            requests.push(record);
-            this.writePrimarySummaryFallbackState({ requests: requests.slice(-256) });
-        });
-    }
-    async updatePrimarySummaryRequestRecord(requestId, update) {
-        return this.withPrimarySummaryStateLock(() => {
-            const state = this.readPrimarySummaryFallbackState();
-            const index = state.requests.findIndex((entry) => entry.requestId === requestId);
-            if (index < 0)
-                return null;
-            state.requests[index] = update(state.requests[index]);
-            this.writePrimarySummaryFallbackState({ requests: state.requests.slice(-256) });
-            return state.requests[index];
-        });
-    }
-    async getPrimarySummaryRequestRecord(requestId) {
-        return this.withPrimarySummaryStateLock(() => {
-            const state = this.readPrimarySummaryFallbackState();
-            return state.requests.find((entry) => entry.requestId === requestId) ?? null;
-        });
-    }
-    primarySummaryContractsMatch(left, right) {
-        return left.systemHash === right.systemHash
-            && left.modelConfigHash === right.modelConfigHash
-            && left.toolContractHash === right.toolContractHash;
-    }
-    primarySummaryFallbackOutputPhaseHash(blocks) {
-        return this.hashJson(blocks);
-    }
-    primarySummaryFallbackBlockTypes(blocks) {
-        return blocks.map((block) => block.type);
-    }
-    static NON_EXECUTED_TOOL_RESULT_TEXT = '[tool not executed]';
-    buildNonExecutedToolResults(blocks) {
-        const seenToolUseIds = new Set();
-        return blocks
-            .filter((block) => block.type === 'tool_use')
-            .filter((block) => {
-            if (seenToolUseIds.has(block.id))
-                return false;
-            seenToolUseIds.add(block.id);
-            return true;
-        })
-            .map((block) => ({
-            type: 'tool_result',
-            toolUseId: block.id,
-            content: AgentFramework.NON_EXECUTED_TOOL_RESULT_TEXT,
-            isError: true,
-        }));
-    }
-    buildPrimarySummarySettlementId(record, outcome) {
-        return `${record.dispatchKind}:${outcome}:terminal:v${PRIMARY_SUMMARY_SETTLEMENT_VERSION}`;
-    }
-    buildPrimarySummarySettlementMetadata(record, options) {
-        const settlementId = options.settlementId ?? this.buildPrimarySummarySettlementId(record, options.outcome);
-        return {
-            [PRIMARY_SUMMARY_SETTLEMENT_METADATA_KEY]: {
-                version: PRIMARY_SUMMARY_SETTLEMENT_VERSION,
-                requestId: record.requestId,
-                settlementId,
-                agentName: record.agentName,
-                dispatchKind: record.dispatchKind,
-                outcome: options.outcome,
-                ...(options.stopReason ? { stopReason: options.stopReason } : {}),
-                ...(options.holdReason ? { holdReason: options.holdReason } : {}),
-                ...(options.providerInputTokens !== undefined
-                    ? { providerInputTokens: options.providerInputTokens }
-                    : {}),
-                visibleAssistantOutput: options.visibleAssistantOutput,
-                executedToolCalls: options.executedToolCalls,
-                branch: {
-                    id: record.branch.id,
-                    name: record.branch.name,
-                    generation: record.branch.generation,
-                },
-                role: options.role,
-                kind: options.kind,
-                entryIndex: options.entryIndex,
-                entryCount: options.entryCount,
-            },
-        };
-    }
-    isBoundedNonEmptyString(value, maxLength) {
-        return typeof value === 'string' && value.length > 0 && value.length <= maxLength;
-    }
-    isSafeNonNegativeInteger(value) {
-        return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
-    }
-    primarySummarySettlementRequestId(message) {
-        const raw = message.metadata?.[PRIMARY_SUMMARY_SETTLEMENT_METADATA_KEY];
-        if (!raw || typeof raw !== 'object')
-            return null;
-        const requestId = raw.requestId;
-        return typeof requestId === 'string' ? requestId : null;
-    }
-    parsePrimarySummarySettlementMetadata(message) {
-        const raw = message.metadata?.[PRIMARY_SUMMARY_SETTLEMENT_METADATA_KEY];
-        if (!raw || typeof raw !== 'object')
-            return null;
-        const candidate = raw;
-        if (candidate.version !== PRIMARY_SUMMARY_SETTLEMENT_VERSION ||
-            !this.isBoundedNonEmptyString(candidate.requestId, PRIMARY_SUMMARY_SETTLEMENT_MAX_ID_LENGTH) ||
-            !this.isBoundedNonEmptyString(candidate.settlementId, PRIMARY_SUMMARY_SETTLEMENT_MAX_ID_LENGTH) ||
-            !this.isBoundedNonEmptyString(candidate.agentName, PRIMARY_SUMMARY_SETTLEMENT_MAX_NAME_LENGTH) ||
-            (candidate.dispatchKind !== 'primary' && candidate.dispatchKind !== 'primary_summary_fallback_retry') ||
-            (candidate.outcome !== 'success' && candidate.outcome !== 'held') ||
-            typeof candidate.visibleAssistantOutput !== 'boolean' ||
-            !this.isSafeNonNegativeInteger(candidate.executedToolCalls) ||
-            !this.isSafeNonNegativeInteger(candidate.entryIndex) ||
-            !this.isSafeNonNegativeInteger(candidate.entryCount) ||
-            (candidate.role !== 'assistant' && candidate.role !== 'user') ||
-            (candidate.kind !== 'assistant_output' && candidate.kind !== 'generated_tool_result') ||
-            !candidate.branch ||
-            !this.isBoundedNonEmptyString(candidate.branch.id, PRIMARY_SUMMARY_SETTLEMENT_MAX_ID_LENGTH) ||
-            !this.isBoundedNonEmptyString(candidate.branch.name, PRIMARY_SUMMARY_SETTLEMENT_MAX_NAME_LENGTH) ||
-            !this.isSafeNonNegativeInteger(candidate.branch.generation) ||
-            candidate.entryCount < 1 ||
-            candidate.entryIndex >= candidate.entryCount ||
-            (candidate.stopReason !== undefined
-                && !this.isBoundedNonEmptyString(candidate.stopReason, PRIMARY_SUMMARY_SETTLEMENT_MAX_REASON_LENGTH)) ||
-            (candidate.holdReason !== undefined
-                && !this.isBoundedNonEmptyString(candidate.holdReason, PRIMARY_SUMMARY_SETTLEMENT_MAX_REASON_LENGTH)) ||
-            (candidate.providerInputTokens !== undefined
-                && !this.isSafeNonNegativeInteger(candidate.providerInputTokens)) ||
-            (candidate.outcome === 'held' && candidate.holdReason === undefined) ||
-            (candidate.outcome === 'success' && candidate.holdReason !== undefined)) {
-            return { invalidReason: 'primary_summary_settlement_metadata_invalid_on_restart' };
-        }
-        return candidate;
-    }
-    primarySummarySettlementMetadataConsistent(left, right) {
-        return left.version === right.version
-            && left.requestId === right.requestId
-            && left.settlementId === right.settlementId
-            && left.agentName === right.agentName
-            && left.dispatchKind === right.dispatchKind
-            && left.outcome === right.outcome
-            && left.stopReason === right.stopReason
-            && left.holdReason === right.holdReason
-            && left.providerInputTokens === right.providerInputTokens
-            && left.visibleAssistantOutput === right.visibleAssistantOutput
-            && left.executedToolCalls === right.executedToolCalls
-            && left.branch.id === right.branch.id
-            && left.branch.name === right.branch.name
-            && left.branch.generation === right.branch.generation
-            && left.entryCount === right.entryCount;
-    }
-    primarySummaryShardEnvelopeConsistent(participant, left, candidateParticipant, right) {
-        return participant === candidateParticipant
-            && this.primarySummarySettlementMetadataConsistent(left, right)
-            && left.role === right.role
-            && left.kind === right.kind
-            && left.entryIndex === right.entryIndex;
-    }
-    primarySummaryLogicalSettlementEntries(agent, requestId) {
-        const allMessages = agent.getContextManager().getAllMessages()
-            .slice()
-            .sort((left, right) => left.sequence - right.sequence);
-        const entries = [];
-        for (let index = 0; index < allMessages.length;) {
-            const message = allMessages[index];
-            if (this.primarySummarySettlementRequestId(message) !== requestId) {
-                index++;
-                continue;
-            }
-            const parsed = this.parsePrimarySummarySettlementMetadata(message);
-            if (!parsed) {
-                index++;
-                continue;
-            }
-            if ('invalidReason' in parsed)
-                return parsed;
-            if (message.bodyGroupId === undefined) {
-                if (message.shardIndex !== undefined) {
-                    return { invalidReason: 'primary_summary_settlement_shard_group_invalid_on_restart' };
-                }
-                entries.push({
-                    messages: [message],
-                    settlement: parsed,
-                    participant: message.participant,
-                    content: message.content,
-                });
-                index++;
-                continue;
-            }
-            const groupId = message.bodyGroupId;
-            if (!this.isBoundedNonEmptyString(groupId, PRIMARY_SUMMARY_SETTLEMENT_MAX_ID_LENGTH)) {
-                return { invalidReason: 'primary_summary_settlement_shard_group_invalid_on_restart' };
-            }
-            if (index > 0 && allMessages[index - 1]?.bodyGroupId === groupId) {
-                return { invalidReason: 'primary_summary_settlement_shard_group_invalid_on_restart' };
-            }
-            const groupMessages = [];
-            while (index < allMessages.length && allMessages[index].bodyGroupId === groupId) {
-                groupMessages.push(allMessages[index]);
-                index++;
-            }
-            if (allMessages.slice(index).some((candidate) => candidate.bodyGroupId === groupId)) {
-                return { invalidReason: 'primary_summary_settlement_shard_group_invalid_on_restart' };
-            }
-            const orderedGroupMessages = [];
-            let expectedShardIndex = 0;
-            for (const groupMessage of groupMessages) {
-                if (this.primarySummarySettlementRequestId(groupMessage) !== requestId) {
-                    return { invalidReason: 'primary_summary_settlement_shard_group_invalid_on_restart' };
-                }
-                const groupParsed = this.parsePrimarySummarySettlementMetadata(groupMessage);
-                if (!groupParsed) {
-                    return { invalidReason: 'primary_summary_settlement_shard_group_invalid_on_restart' };
-                }
-                if ('invalidReason' in groupParsed)
-                    return groupParsed;
-                if (!this.primarySummaryShardEnvelopeConsistent(message.participant, parsed, groupMessage.participant, groupParsed)) {
-                    return { invalidReason: 'primary_summary_settlement_shard_group_invalid_on_restart' };
-                }
-                if (groupMessage.shardIndex !== expectedShardIndex) {
-                    return { invalidReason: 'primary_summary_settlement_shard_group_invalid_on_restart' };
-                }
-                orderedGroupMessages.push(groupMessage);
-                expectedShardIndex++;
-            }
-            entries.push({
-                messages: orderedGroupMessages,
-                settlement: parsed,
-                participant: message.participant,
-                content: orderedGroupMessages.flatMap((groupMessage) => groupMessage.content),
-                bodyGroupId: groupId,
-            });
-        }
-        return entries;
-    }
-    primarySummaryContentMatches(left, right) {
-        return this.primarySummaryFallbackOutputPhaseHash(left) === this.primarySummaryFallbackOutputPhaseHash(right);
-    }
-    async persistPrimarySummaryChronicleEntries(agent, entries) {
-        const messageIds = [];
-        for (const entry of entries) {
-            if (entry.content.length === 0)
-                continue;
-            messageIds.push(agent.getContextManager().addMessage(entry.participant, entry.content, entry.metadata));
-        }
-        return messageIds;
-    }
-    async markPrimarySummaryRequestRestartFailure(record, reason) {
-        if (record.dispatchKind === 'primary_summary_fallback_retry') {
-            const parent = await this.findPrimarySummaryRetryParent(record.requestId);
-            await this.updatePrimarySummaryRequestRecord(record.requestId, (entry) => ({
-                ...entry,
-                finalStatus: 'held',
-                fallbackHeldReason: reason,
-            }));
-            if (parent) {
-                await this.updatePrimarySummaryRequestRecord(parent.originalRequestId, (entry) => ({
-                    ...entry,
-                    finalStatus: 'held',
-                    fallbackStatus: 'held',
-                    fallbackHeldReason: reason,
-                }));
-            }
-            return;
-        }
-        await this.updatePrimarySummaryRequestRecord(record.requestId, (current) => ({
-            ...current,
-            finalStatus: 'held',
-            fallbackStatus: 'held',
-            fallbackHeldReason: reason,
-        }));
-    }
-    async persistPrimarySummaryHeldOutput(agent, requestId, holdReason, options) {
-        const record = await this.getPrimarySummaryRequestRecord(requestId);
-        if (!record) {
-            throw new Error(`Primary summary request '${requestId}' disappeared before held-output persistence`);
-        }
-        const placeholderBlocks = this.buildNonExecutedToolResults(options.assistantBlocks);
-        const entryCount = placeholderBlocks.length > 0 ? 2 : 1;
-        const assistantMetadata = this.buildPrimarySummarySettlementMetadata(record, {
-            outcome: 'held',
-            stopReason: options.stopReason,
-            holdReason,
-            providerInputTokens: options.providerInputTokens,
-            visibleAssistantOutput: options.visibleAssistantOutput,
-            executedToolCalls: options.executedToolCalls,
-            entryIndex: 0,
-            entryCount,
-            role: 'assistant',
-            kind: 'assistant_output',
-        });
-        const settlementId = assistantMetadata[PRIMARY_SUMMARY_SETTLEMENT_METADATA_KEY].settlementId;
-        const placeholderMetadata = placeholderBlocks.length > 0
-            ? this.buildPrimarySummarySettlementMetadata(record, {
-                outcome: 'held',
-                settlementId,
-                stopReason: options.stopReason,
-                holdReason,
-                providerInputTokens: options.providerInputTokens,
-                visibleAssistantOutput: options.visibleAssistantOutput,
-                executedToolCalls: options.executedToolCalls,
-                entryIndex: 1,
-                entryCount,
-                role: 'user',
-                kind: 'generated_tool_result',
-            })
-            : undefined;
-        const messageIds = await this.persistPrimarySummaryChronicleEntries(agent, [
-            { participant: agent.name, content: options.assistantBlocks, metadata: assistantMetadata },
-            ...(placeholderBlocks.length > 0 && placeholderMetadata
-                ? [{ participant: 'user', content: placeholderBlocks, metadata: placeholderMetadata }]
-                : []),
-        ]);
-        if (options.retryDispatch && options.retryPhase && options.assistantBlocks.length > 0) {
-            await this.recordPrimarySummaryRetryOutput(options.retryDispatch.originalRequestId, options.retryDispatch.intentId, {
-                phase: options.retryPhase,
-                contentHash: this.primarySummaryFallbackOutputPhaseHash(options.assistantBlocks),
-                messageId: messageIds[0] ?? '',
-                blockTypes: this.primarySummaryFallbackBlockTypes(options.assistantBlocks),
-                persistedAt: Date.now(),
-            });
-        }
-        if (options.retryDispatch) {
-            await this.holdPrimarySummaryRetryFamily(agent, requestId, options.retryDispatch, holdReason, options.holdData);
-            return;
-        }
-        await this.holdPrimarySummaryRequest(agent, requestId, holdReason, options.holdData);
-    }
-    async findPrimarySummaryRetryParent(retryRequestId) {
-        return this.withPrimarySummaryStateLock(() => {
-            const state = this.readPrimarySummaryFallbackState();
-            for (const record of state.requests) {
-                const intent = record.fallbackIntent;
-                if (intent?.retryRequestId === retryRequestId) {
-                    return { originalRequestId: record.requestId, intentId: intent.intentId };
-                }
-            }
-            return null;
-        });
-    }
-    async finalizePrimarySummarySettlementOnStartup(record) {
-        const agent = this.agents.get(record.agentName);
-        if (!agent)
-            return false;
-        const settlementEntries = this.primarySummaryLogicalSettlementEntries(agent, record.requestId);
-        if ('invalidReason' in settlementEntries)
-            return settlementEntries;
-        if (settlementEntries.length === 0) {
-            return false;
-        }
-        const currentBranch = agent.getCurrentBranchGeneration();
-        const assistantEntry = settlementEntries[0];
-        const settlement = assistantEntry.settlement;
-        if (assistantEntry.participant !== record.agentName ||
-            settlement.agentName !== record.agentName ||
-            settlement.dispatchKind !== record.dispatchKind ||
-            settlement.entryIndex !== 0 ||
-            settlement.role !== 'assistant' ||
-            settlement.kind !== 'assistant_output') {
-            return { invalidReason: 'primary_summary_settlement_invalid_assistant_marker_on_restart' };
-        }
-        if (!currentBranch) {
-            return { invalidReason: 'primary_summary_settlement_branch_unknown_on_restart' };
-        }
-        if (settlement.branch.id !== record.branch.id ||
-            settlement.branch.name !== record.branch.name ||
-            settlement.branch.generation !== record.branch.generation ||
-            settlement.branch.id !== currentBranch.id ||
-            settlement.branch.name !== currentBranch.name ||
-            settlement.branch.generation !== currentBranch.generation) {
-            return { invalidReason: 'primary_summary_settlement_branch_mismatch_on_restart' };
-        }
-        if (settlement.entryCount < 1 || settlement.entryCount > 2) {
-            return { invalidReason: 'primary_summary_settlement_entry_count_invalid_on_restart' };
-        }
-        const entriesByIndex = new Map();
-        for (const entry of settlementEntries) {
-            if (!this.primarySummarySettlementMetadataConsistent(settlement, entry.settlement)) {
-                return { invalidReason: 'primary_summary_settlement_marker_conflict_on_restart' };
-            }
-            if (entriesByIndex.has(entry.settlement.entryIndex)) {
-                return { invalidReason: 'primary_summary_settlement_duplicate_entry_on_restart' };
-            }
-            entriesByIndex.set(entry.settlement.entryIndex, entry);
-        }
-        const placeholderEntry = entriesByIndex.get(1);
-        if (placeholderEntry
-            && (placeholderEntry.participant !== 'user'
-                || placeholderEntry.settlement.role !== 'user'
-                || placeholderEntry.settlement.kind !== 'generated_tool_result')) {
-            return { invalidReason: 'primary_summary_settlement_placeholder_marker_invalid_on_restart' };
-        }
-        if ([...entriesByIndex.keys()].some((index) => index !== 0 && index !== 1)) {
-            return { invalidReason: 'primary_summary_settlement_out_of_order_entries_on_restart' };
-        }
-        const expectedPlaceholder = settlement.outcome === 'held'
-            ? this.buildNonExecutedToolResults(assistantEntry.content)
-            : [];
-        if (settlement.outcome === 'success') {
-            if (settlement.entryCount !== 1 || placeholderEntry) {
-                return { invalidReason: 'primary_summary_success_settlement_shape_invalid_on_restart' };
-            }
-        }
-        else {
-            const expectedEntryCount = expectedPlaceholder.length > 0 ? 2 : 1;
-            if (settlement.entryCount !== expectedEntryCount) {
-                return { invalidReason: 'primary_summary_held_settlement_shape_invalid_on_restart' };
-            }
-            if (placeholderEntry) {
-                if (!this.primarySummaryContentMatches(placeholderEntry.content, expectedPlaceholder)) {
-                    return { invalidReason: 'primary_summary_settlement_placeholder_content_mismatch_on_restart' };
-                }
-            }
-            else if (expectedPlaceholder.length > 0) {
-                const placeholderMetadata = this.buildPrimarySummarySettlementMetadata(record, {
-                    outcome: 'held',
-                    settlementId: settlement.settlementId,
-                    stopReason: settlement.stopReason,
-                    holdReason: settlement.holdReason,
-                    providerInputTokens: settlement.providerInputTokens,
-                    visibleAssistantOutput: settlement.visibleAssistantOutput,
-                    executedToolCalls: settlement.executedToolCalls,
-                    entryIndex: 1,
-                    entryCount: settlement.entryCount,
-                    role: 'user',
-                    kind: 'generated_tool_result',
-                });
-                await this.persistPrimarySummaryChronicleEntries(agent, [
-                    { participant: 'user', content: expectedPlaceholder, metadata: placeholderMetadata },
-                ]);
-            }
-        }
-        if (record.dispatchKind === 'primary_summary_fallback_retry') {
-            const parent = await this.findPrimarySummaryRetryParent(record.requestId);
-            if (!parent)
-                return { invalidReason: 'primary_summary_fallback_parent_missing_on_restart' };
-            if (settlement.outcome === 'success') {
-                await this.updatePrimarySummaryRequestRecord(record.requestId, (entry) => ({
-                    ...entry,
-                    stopReason: settlement.stopReason ?? entry.stopReason,
-                    providerInputTokens: settlement.providerInputTokens ?? entry.providerInputTokens,
-                    visibleAssistantOutput: settlement.visibleAssistantOutput,
-                    executedToolCalls: settlement.executedToolCalls,
-                    finalStatus: 'success',
-                    fallbackHeldReason: undefined,
-                }));
-                await this.updatePrimarySummaryRequestRecord(parent.originalRequestId, (entry) => {
-                    const intent = entry.fallbackIntent;
-                    return {
-                        ...entry,
-                        finalStatus: 'success',
-                        fallbackStatus: 'success',
-                        fallbackHeldReason: undefined,
-                        fallbackIntent: intent && intent.intentId === parent.intentId
-                            ? { ...intent, finalizedAt: intent.finalizedAt ?? Date.now() }
-                            : intent,
-                    };
-                });
-                return 'finalized';
-            }
-            await this.updatePrimarySummaryRequestRecord(record.requestId, (entry) => ({
-                ...entry,
-                stopReason: settlement.stopReason ?? entry.stopReason,
-                providerInputTokens: settlement.providerInputTokens ?? entry.providerInputTokens,
-                visibleAssistantOutput: settlement.visibleAssistantOutput,
-                executedToolCalls: settlement.executedToolCalls,
-                finalStatus: 'held',
-                fallbackHeldReason: settlement.holdReason,
-            }));
-            await this.updatePrimarySummaryRequestRecord(parent.originalRequestId, (entry) => ({
-                ...entry,
-                finalStatus: 'held',
-                fallbackStatus: 'held',
-                fallbackHeldReason: settlement.holdReason,
-            }));
-            return 'finalized';
-        }
-        await this.updatePrimarySummaryRequestRecord(record.requestId, (entry) => ({
-            ...entry,
-            stopReason: settlement.stopReason ?? entry.stopReason,
-            providerInputTokens: settlement.providerInputTokens ?? entry.providerInputTokens,
-            visibleAssistantOutput: settlement.visibleAssistantOutput,
-            executedToolCalls: settlement.executedToolCalls,
-            finalStatus: settlement.outcome === 'success' ? 'success' : 'held',
-            fallbackStatus: settlement.outcome === 'success' ? entry.fallbackStatus : 'held',
-            fallbackHeldReason: settlement.outcome === 'held' ? settlement.holdReason : undefined,
-        }));
-        return 'finalized';
-    }
-    summarizePrimarySummaryRetryRequest(request) {
-        const blockCounts = new Map();
-        for (const message of request.messages) {
-            for (const block of message.content) {
-                blockCounts.set(block.type, (blockCounts.get(block.type) ?? 0) + 1);
-            }
-        }
-        return {
-            kind: 'primary_summary_fallback_retry',
-            requestHash: this.hashJson(request),
-            systemHash: this.hashJson(request.system ?? ''),
-            messageCount: request.messages.length,
-            toolCount: request.tools?.length ?? 0,
-            participantCount: [...new Set(request.messages.map((message) => message.participant))].length,
-            blockCounts: Object.fromEntries([...blockCounts.entries()].sort(([left], [right]) => left.localeCompare(right))),
-            promptCaching: request.promptCaching === true,
-            cacheTtl: request.cacheTtl,
-            assistantParticipant: request.assistantParticipant,
-            requestCompleteBoundTokens: this.estimateRequestCompleteBoundTokens(request),
-        };
-    }
-    summarizePrimarySummaryRetryResponse(response) {
-        const blockCounts = new Map();
-        for (const block of response.content) {
-            blockCounts.set(block.type, (blockCounts.get(block.type) ?? 0) + 1);
-        }
-        return {
-            kind: 'primary_summary_fallback_retry',
-            stopReason: response.stopReason,
-            rawAssistantTextHash: response.rawAssistantText
-                ? this.hashJson(response.rawAssistantText)
-                : undefined,
-            blockCounts: Object.fromEntries([...blockCounts.entries()].sort(([left], [right]) => left.localeCompare(right))),
-            toolCallIds: response.toolCalls.map((call) => call.id),
-            usage: response.usage
-                ? {
-                    inputTokens: response.usage.inputTokens,
-                    outputTokens: response.usage.outputTokens,
-                }
-                : undefined,
-        };
-    }
-    async claimPrimarySummaryRetryIntent(originalRequestId, intentId, retryRequestId) {
-        let outcome = 'missing';
-        await this.updatePrimarySummaryRequestRecord(originalRequestId, (record) => {
-            const intent = record.fallbackIntent;
-            if (!intent || intent.intentId !== intentId || record.fallbackStatus !== 'pending') {
-                return record;
-            }
-            if (intent.retryRequestId && intent.retryRequestId !== retryRequestId) {
-                outcome = 'duplicate';
-                return record;
-            }
-            outcome = 'claimed';
-            return {
-                ...record,
-                fallbackIntent: {
-                    ...intent,
-                    retryRequestId,
-                    dispatchedAt: intent.dispatchedAt ?? Date.now(),
-                },
-            };
-        });
-        return outcome;
-    }
-    async validatePrimarySummaryRetryMutation(agent, requestId, retryDispatch, compiledRequest, artifacts, phase) {
-        const branch = agent.getCurrentBranchGeneration();
-        if (!branch || branch.id !== retryDispatch.branch.id || branch.generation !== retryDispatch.branch.generation) {
-            return {
-                ok: false,
-                reason: `primary_summary_fallback_branch_changed_${phase}`,
-                data: {
-                    expectedBranchId: retryDispatch.branch.id,
-                    expectedGeneration: retryDispatch.branch.generation,
-                    actualBranchId: branch?.id,
-                    actualGeneration: branch?.generation,
-                },
-            };
-        }
-        const requestHash = this.hashJson(compiledRequest);
-        if (requestHash !== retryDispatch.expectedRetryRequestHash) {
-            return {
-                ok: false,
-                reason: `primary_summary_fallback_request_changed_${phase}`,
-                data: {
-                    expectedRetryRequestHash: retryDispatch.expectedRetryRequestHash,
-                    actualRetryRequestHash: requestHash,
-                },
-            };
-        }
-        if (this.primarySummaryProjectionKeys(artifacts.compileResult.primarySummaryProjection ?? null).join('\u0000') !==
-            retryDispatch.originalProjectionKeys.join('\u0000')) {
-            return {
-                ok: false,
-                reason: `primary_summary_fallback_projection_changed_${phase}`,
-                data: {
-                    expectedProjectionKeys: retryDispatch.originalProjectionKeys,
-                    actualProjectionKeys: this.primarySummaryProjectionKeys(artifacts.compileResult.primarySummaryProjection ?? null),
-                },
-            };
-        }
-        if (!this.primarySummaryContractsMatch(artifacts.contract, retryDispatch.originalArtifacts.contract)) {
-            return {
-                ok: false,
-                reason: `primary_summary_fallback_contract_changed_${phase}`,
-                data: {
-                    expectedContract: retryDispatch.originalArtifacts.contract,
-                    actualContract: artifacts.contract,
-                },
-            };
-        }
-        const original = await this.getPrimarySummaryRequestRecord(retryDispatch.originalRequestId);
-        if (!original?.fallbackIntent ||
-            original.fallbackIntent.intentId !== retryDispatch.intentId ||
-            original.fallbackIntent.retryRequestId !== requestId ||
-            original.fallbackStatus !== 'pending') {
-            return {
-                ok: false,
-                reason: `primary_summary_fallback_intent_changed_${phase}`,
-                data: {
-                    expectedIntentId: retryDispatch.intentId,
-                    actualIntentId: original?.fallbackIntent?.intentId,
-                    retryRequestId: original?.fallbackIntent?.retryRequestId,
-                    fallbackStatus: original?.fallbackStatus,
-                },
-            };
-        }
-        return { ok: true };
-    }
-    async recordPrimarySummaryRetryQuarantine(originalRequestId, intentId) {
-        await this.updatePrimarySummaryRequestRecord(originalRequestId, (record) => {
-            const intent = record.fallbackIntent;
-            if (!intent || intent.intentId !== intentId || intent.quarantinePersistedAt)
-                return record;
-            return {
-                ...record,
-                fallbackIntent: {
-                    ...intent,
-                    quarantinePersistedAt: Date.now(),
-                },
-            };
-        });
-    }
-    async recordPrimarySummaryRetryOutput(originalRequestId, intentId, output) {
-        await this.updatePrimarySummaryRequestRecord(originalRequestId, (record) => {
-            const intent = record.fallbackIntent;
-            if (!intent || intent.intentId !== intentId)
-                return record;
-            const existing = intent.outputs?.find((entry) => entry.phase === output.phase);
-            if (existing &&
-                existing.contentHash === output.contentHash &&
-                existing.messageId === output.messageId) {
-                return record;
-            }
-            if (existing) {
-                throw new Error(`Primary summary fallback output phase '${output.phase}' changed after persistence`);
-            }
-            return {
-                ...record,
-                fallbackIntent: {
-                    ...intent,
-                    outputs: [...(intent.outputs ?? []), output],
-                },
-            };
-        });
-    }
-    async recordPrimarySummaryRetryToolDispatch(originalRequestId, intentId, call) {
-        await this.updatePrimarySummaryRequestRecord(originalRequestId, (record) => {
-            const intent = record.fallbackIntent;
-            if (!intent || intent.intentId !== intentId)
-                return record;
-            const inputHash = this.hashJson(call.input);
-            const existing = intent.toolDispatches?.find((entry) => entry.callId === call.id);
-            if (existing?.inputHash === inputHash)
-                return record;
-            if (existing) {
-                throw new Error(`Primary summary fallback tool dispatch '${call.id}' changed after persistence`);
-            }
-            return {
-                ...record,
-                fallbackIntent: {
-                    ...intent,
-                    toolDispatches: [
-                        ...(intent.toolDispatches ?? []),
-                        {
-                            callId: call.id,
-                            inputHash,
-                            recordedAt: Date.now(),
-                        },
-                    ],
-                },
-            };
-        });
-    }
-    async resolveContextBudgetRestartDispatch(requestId, retryDispatch) {
-        const retryIdentity = retryDispatch
-            ? {
-                requestId,
-                dispatchKind: 'primary_summary_fallback_retry',
-                originalRequestId: retryDispatch.originalRequestId,
-                intentId: retryDispatch.intentId,
-            }
-            : null;
-        const record = await this.getPrimarySummaryRequestRecord(requestId);
-        if (record?.dispatchKind === 'primary_summary_fallback_retry' && retryIdentity) {
-            return retryIdentity;
-        }
-        if (retryIdentity) {
-            const original = await this.getPrimarySummaryRequestRecord(retryIdentity.originalRequestId);
-            if (original?.fallbackIntent?.intentId === retryIdentity.intentId
-                && original.fallbackIntent.retryRequestId === requestId) {
-                return retryIdentity;
-            }
-        }
-        return {
-            requestId,
-            dispatchKind: 'primary',
-        };
-    }
-    contextBudgetRestartMatchesIdentity(request, identity) {
-        if (request.reason !== 'context_budget_restart')
-            return false;
-        const restart = request.contextBudgetRestart;
-        if (!restart)
-            return false;
-        if (restart.dispatchKind !== identity.dispatchKind)
-            return false;
-        if (restart.requestId !== identity.requestId)
-            return false;
-        if (identity.dispatchKind !== 'primary_summary_fallback_retry')
-            return true;
-        return restart.originalRequestId === identity.originalRequestId
-            && restart.intentId === identity.intentId;
-    }
-    clearQueuedContextBudgetRestart(identity) {
-        const before = this.pendingRequests.length;
-        this.pendingRequests = this.pendingRequests.filter((request) => !this.contextBudgetRestartMatchesIdentity(request, identity));
-        return before - this.pendingRequests.length;
-    }
-    async markPrimarySummaryRetrySuccess(requestId, retryDispatch, stopReason, providerInputTokens, visibleAssistantOutput, executedToolCalls) {
-        await this.updatePrimarySummaryRequestRecord(requestId, (record) => ({
-            ...record,
-            stopReason,
-            providerInputTokens,
-            visibleAssistantOutput,
-            executedToolCalls,
-            finalStatus: 'success',
-            fallbackHeldReason: undefined,
-        }));
-        await this.updatePrimarySummaryRequestRecord(retryDispatch.originalRequestId, (record) => {
-            const intent = record.fallbackIntent;
-            return {
-                ...record,
-                finalStatus: 'success',
-                fallbackStatus: 'success',
-                fallbackHeldReason: undefined,
-                fallbackIntent: intent && intent.intentId === retryDispatch.intentId
-                    ? { ...intent, finalizedAt: Date.now() }
-                    : intent,
-            };
-        });
-    }
-    async holdPrimarySummaryRetryFamily(agent, requestId, retryDispatch, reason, data, options) {
-        const clearedQueuedContextBudgetRestarts = this.clearQueuedContextBudgetRestart({
-            requestId,
-            dispatchKind: 'primary_summary_fallback_retry',
-            originalRequestId: retryDispatch.originalRequestId,
-            intentId: retryDispatch.intentId,
-        });
-        const holdData = clearedQueuedContextBudgetRestarts > 0
-            ? { ...(data ?? {}), clearedQueuedContextBudgetRestarts }
-            : data;
-        await this.updatePrimarySummaryRequestRecord(requestId, (record) => ({
-            ...record,
-            ...(options?.stopReason ? { stopReason: options.stopReason } : {}),
-            finalStatus: 'held',
-            fallbackHeldReason: reason,
-        }));
-        await this.updatePrimarySummaryRequestRecord(retryDispatch.originalRequestId, (record) => ({
-            ...record,
-            finalStatus: 'held',
-            fallbackStatus: 'held',
-            fallbackHeldReason: reason,
-        }));
-        this.opsAlert('refusal-held', agent.name, reason, { data: holdData });
-        if (options?.emitChronicleMarker === false)
-            return;
-        try {
-            agent.getContextManager().addMessage('user', [{
-                    type: 'text',
-                    text: `[refusal-held] Your previous turn was refused by the provider and ` +
-                        `is being held for operator review rather than silently retried. ` +
-                        `Automatic raw-expansion recovery was either unsafe or unsuccessful.`,
-                }], { system: true, kind: 'refusal-held', reason });
-        }
-        catch (error) {
-            console.error('[refusal-held] could not record chronicle marker:', error);
-        }
-    }
-    async primarySummaryRetryAlreadySucceeded(requestId, retryDispatch) {
-        const [retryRecord, originalRecord] = await Promise.all([
-            this.getPrimarySummaryRequestRecord(requestId),
-            this.getPrimarySummaryRequestRecord(retryDispatch.originalRequestId),
-        ]);
-        return retryRecord?.finalStatus === 'success'
-            || originalRecord?.fallbackStatus === 'success'
-            || originalRecord?.finalStatus === 'success';
-    }
-    async primarySummaryRetryFamilyAlreadySettled(requestId, retryDispatch) {
-        const [retryRecord, originalRecord] = await Promise.all([
-            this.getPrimarySummaryRequestRecord(requestId),
-            this.getPrimarySummaryRequestRecord(retryDispatch.originalRequestId),
-        ]);
-        return retryRecord?.finalStatus === 'held'
-            || retryRecord?.finalStatus === 'success'
-            || originalRecord?.fallbackStatus === 'held'
-            || originalRecord?.fallbackStatus === 'success'
-            || originalRecord?.finalStatus === 'held'
-            || originalRecord?.finalStatus === 'success';
-    }
-    async holdPrimarySummaryRequest(agent, requestId, reason, data) {
-        await this.updatePrimarySummaryRequestRecord(requestId, (record) => ({
-            ...record,
-            finalStatus: 'held',
-            fallbackStatus: 'held',
-            fallbackHeldReason: reason,
-        }));
-        this.opsAlert('refusal-held', agent.name, reason, { data });
-        try {
-            agent.getContextManager().addMessage('user', [{
-                    type: 'text',
-                    text: `[refusal-held] Your previous turn was refused by the provider and ` +
-                        `is being held for operator review rather than silently retried. ` +
-                        `Automatic raw-expansion recovery was either unsafe or unsuccessful.`,
-                }], { system: true, kind: 'refusal-held', reason });
-        }
-        catch (error) {
-            console.error('[refusal-held] could not record chronicle marker:', error);
-        }
-    }
-    hasVisibleAssistantOutput(blocks) {
-        return blocks.some((block) => block.type !== 'thinking' && block.type !== 'redacted_thinking');
-    }
-    buildPrimarySummaryRequestRecord(agent, requestId, dispatchKind, request, artifacts, branch, stopReason, visibleAssistantOutput, executedToolCalls, providerInputTokens, finalStatus) {
-        const projection = artifacts?.compileResult.primarySummaryProjection ?? null;
-        return {
-            requestId,
-            agentName: agent.name,
-            namespace: projection?.namespace ?? `agents/${agent.name}`,
-            timestamp: Date.now(),
-            dispatchKind,
-            branch: branch
-                ? { id: branch.id, name: branch.name, generation: branch.generation }
-                : { id: 'unknown', name: 'unknown', generation: -1 },
-            projection,
-            requestInputBoundTokens: this.estimateRequestInputBoundTokens(request),
-            requestCompleteBoundTokens: this.estimateRequestCompleteBoundTokens(request),
-            providerInputTokens,
-            systemHash: artifacts?.contract.systemHash ?? this.hashJson(request.system ?? ''),
-            modelConfigHash: artifacts?.contract.modelConfigHash ?? this.hashJson({ request: request.config }),
-            toolContractHash: artifacts?.contract.toolContractHash ?? this.hashJson(request.tools ?? []),
-            stopReason,
-            visibleAssistantOutput,
-            executedToolCalls,
-            finalStatus,
-        };
-    }
     /** Liveness ping for an active ephemeral run (no-op otherwise). */
     touchEphemeralRun(agentName, inferenceStarted = false) {
         const run = this.ephemeralRuns.get(agentName);
@@ -2635,6 +1555,27 @@ export class AgentFramework {
             required: ['path'],
         },
     };
+    /** Synthesized read_image tool — present when a workspace module is
+     *  registered. Returns the image as a native image block in the tool
+     *  result, so the agent SEES it in the live turn (history keeps a compact
+     *  placeholder via the standard tool-result serializer). */
+    static READ_IMAGE_TOOL = {
+        name: 'read_image',
+        description: 'View an image file from a workspace mount. The image is returned into ' +
+            'your context so you can actually see it (e.g. after save_recent_image, ' +
+            'or for images placed in the workspace by other means). Path is ' +
+            'mount-prefixed, e.g. "project/photos/cat.png". Supports png/jpeg/gif/webp.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                path: {
+                    type: 'string',
+                    description: 'Mount-prefixed image path, e.g. "project/photos/name.png".',
+                },
+            },
+            required: ['path'],
+        },
+    };
     static AGENT_SETTINGS_TOOL = {
         name: 'agent_settings',
         description: 'Read or change your hot runtime settings. This intentionally exposes only ' +
@@ -3684,7 +2625,6 @@ export class AgentFramework {
                 // Cast to AgentState to bypass TypeScript's control flow narrowing
                 const currentState = agent.state;
                 if (currentState.status === 'ready') {
-                    const activeStreamContext = this.activeStreamContexts.get(agent.name);
                     // Flush pending assistant blocks (tool_use + preamble text) to context
                     const pendingBlocks = this.pendingAssistantBlocks.get(agent.name);
                     if (pendingBlocks) {
@@ -3795,34 +2735,6 @@ export class AgentFramework {
                         // a terminal failure — rejecting an ephemeral's promise mid-run
                         // and emitting a spurious inference:exhausted (same race shape as
                         // endTurn above).
-                        const requestId = activeStreamContext?.requestId;
-                        const primarySummaryRetry = activeStreamContext?.trigger?.primarySummaryFallbackRetry;
-                        const compiledRequest = activeStreamContext?.compiledRequest;
-                        const artifacts = activeStreamContext?.artifacts;
-                        const restartDispatch = await this.resolveContextBudgetRestartDispatch(requestId ?? `${agent.name}:context_budget_restart`, primarySummaryRetry);
-                        if (restartDispatch.dispatchKind === 'primary_summary_fallback_retry'
-                            && requestId
-                            && primarySummaryRetry
-                            && compiledRequest
-                            && artifacts) {
-                            const validation = await this.validatePrimarySummaryRetryMutation(agent, requestId, primarySummaryRetry, compiledRequest, artifacts, 'before_context_budget_restart_hold');
-                            if (!validation.ok) {
-                                await this.holdPrimarySummaryRetryFamily(agent, requestId, primarySummaryRetry, validation.reason, validation.data, { emitChronicleMarker: false, stopReason: 'abort' });
-                            }
-                            else {
-                                await this.holdPrimarySummaryRetryFamily(agent, requestId, primarySummaryRetry, 'primary_summary_fallback_context_budget_restart_required', {
-                                    inputTokens: agent.lastStreamInputTokens,
-                                    budget: agent.maxStreamTokens,
-                                    originalRequestId: primarySummaryRetry.originalRequestId,
-                                    intentId: primarySummaryRetry.intentId,
-                                }, { emitChronicleMarker: false, stopReason: 'abort' });
-                            }
-                            this.frameworkCancelledStreams.set(`${agent.name}:${agent.streamId}`, 'budget_restart');
-                            currentState.stream?.cancel();
-                            agent.reset();
-                            this.settleAgent(agent.name, { stopReason: 'completed', speech: '' });
-                            return;
-                        }
                         if (currentState.stream) {
                             this.frameworkCancelledStreams.set(`${agent.name}:${agent.streamId}`, 'budget_restart');
                         }
@@ -3839,8 +2751,6 @@ export class AgentFramework {
                             reason: 'context_budget_restart',
                             source: 'framework',
                             timestamp: Date.now(),
-                            channelId: activeStreamContext?.trigger?.channelId,
-                            contextBudgetRestart: restartDispatch,
                         });
                     }
                     else if (currentState.stream) {
@@ -4255,17 +3165,29 @@ export class AgentFramework {
                 ? event.origin.messageId
                 : event.eventId;
             const maxBackscroll = descriptor?.capabilities?.history?.maxMessages ?? 0;
+            // Resolve human-readable names from the event origin wherever the
+            // surface provided them — a mind reading this should see WHO addressed
+            // it WHERE, not a wall of snowflake ids. Raw ids remain only inside the
+            // tool-argument instructions, where they are the literal values to pass.
+            const origin = (event.origin ?? {});
+            const authorName = typeof origin.authorName === 'string' && origin.authorName ? origin.authorName : 'Someone';
+            const channelLabel = triggerChannel.label ? `#${triggerChannel.label}` : `"${triggerChannel.channelId}"`;
+            const place = typeof origin.guildName === 'string' && origin.guildName
+                ? `${channelLabel} in "${origin.guildName}"`
+                : channelLabel;
             content.push({
                 type: 'text',
-                text: `\n[Channel invitation] You were addressed in closed channel ` +
-                    `"${triggerChannel.label ?? triggerChannel.channelId}" (${triggerChannel.channelId}, server ${event.serverId}). ` +
-                    `You received this one message without subscribing. ` +
+                text: `\n[Channel invitation] ${authorName} addressed you in ${place} — ` +
+                    `a channel you haven't joined. You're seeing this one message; you won't receive more from it unless you join. ` +
+                    `Your options:\n` +
+                    `1. Reply without joining — simply write your reply as normal text this turn; it will be delivered to ${channelLabel}.\n` +
+                    `2. Join the channel — call channel_open with channelId "${triggerChannel.channelId}" and serverId "${event.serverId}"` +
                     (maxBackscroll > 0
-                        ? `To subscribe, call channel_open with channelId, serverId "${event.serverId}", backscroll (0-${maxBackscroll}), and beforeMessageId "${messageId}". `
-                        : `To subscribe, call channel_open with this channelId and serverId "${event.serverId}". `) +
-                    `You may reply once without subscribing. To remain closed, call channel_decline ` +
-                    `with channelId, serverId "${event.serverId}", and messageId "${messageId}"; ` +
-                    `optionally set acknowledge to a surface value such as 👀.`,
+                        ? `; to also read recent history, add backscroll (a number up to ${maxBackscroll}) and beforeMessageId "${messageId}".\n`
+                        : `.\n`) +
+                    `3. Stay out — call channel_decline with channelId "${triggerChannel.channelId}", serverId "${event.serverId}", ` +
+                    `and messageId "${messageId}" (optionally set acknowledge to an emoji like 👀 so ${authorName} isn't left hanging).\n` +
+                    `Doing nothing is also fine.`,
             });
             metadata.channelInvitation = true;
             metadata.channelOpen = false;
@@ -4338,8 +3260,7 @@ export class AgentFramework {
         // Clear pending (we'll re-add if inference doesn't run)
         this.pendingRequests = [];
         // Check each agent
-        for (const [agentName, queuedRequests] of requestsByAgent) {
-            let requests = queuedRequests;
+        for (const [agentName, requests] of requestsByAgent) {
             const agent = this.agents.get(agentName);
             if (!agent) {
                 // Agent not found — request is orphaned. Emit warning and drop.
@@ -4378,15 +3299,6 @@ export class AgentFramework {
                 this.pendingRequests.push(...requests);
                 continue;
             }
-            if (this.discordAwarenessBarrier) {
-                this.pendingRequests.push(...requests);
-                continue;
-            }
-            requests = requests.filter((request) => request.reason !== 'context_budget_restart'
-                || request.contextBudgetRestart?.dispatchKind !== 'primary_summary_fallback_retry');
-            if (requests.length === 0) {
-                continue;
-            }
             // Check policy
             if (!this.inferencePolicy.shouldInfer(agentName, requests, state)) {
                 // Loud drop: a queued request that dies here is otherwise invisible —
@@ -4397,13 +3309,7 @@ export class AgentFramework {
                 continue;
             }
             // Start streaming inference (non-blocking — driveStream runs in background)
-            const trigger = requests.find((request) => request.primarySummaryFallbackRetry) ?? requests[0];
-            if (trigger.primarySummaryFallbackRetry) {
-                for (const request of requests) {
-                    if (request !== trigger)
-                        this.pendingRequests.push(request);
-                }
-            }
+            const trigger = requests[0];
             // Route this turn's auto-published speech to the channel that triggered
             // it (item-3 redux). A batched wake may carry several triggering channels
             // (messages arrived in >1 channel while the agent was busy/idle) — reply
@@ -4418,7 +3324,7 @@ export class AgentFramework {
     }
     async startAgentStream(agent, trigger, attempt = 0) {
         // Record turn checkpoint before inference (only on first attempt, not retries)
-        if (attempt === 0 && trigger?.reason !== 'primary-summary-fallback-retry') {
+        if (attempt === 0) {
             this.recordTurnCheckpoint(agent.name);
             this.redoStacks.delete(agent.name); // new work invalidates redo
         }
@@ -4438,180 +3344,46 @@ export class AgentFramework {
         this.emitTrace({ type: 'inference:started', agentName: agent.name });
         this.eventGate?.onInferenceStarted(agent.name);
         this.lastInferenceAt.set(agent.name, { ...this.lastInferenceAt.get(agent.name), startedAt: Date.now() });
-        const requestId = `${agent.name}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
         try {
             const requestSnapshot = this.captureInferenceToolSnapshot(agent);
             const allTools = this.getToolsForAgent(agent.name, requestSnapshot);
             const tools = allTools.filter((t) => agent.canUseTool(t.name));
-            const fallbackConfig = this.primarySummaryFallbackConfig(agent);
-            const retryDispatch = trigger?.primarySummaryFallbackRetry;
-            let compiledRequest;
-            let artifacts;
-            let branch = agent.getCurrentBranchGeneration();
-            if (retryDispatch) {
-                if (!fallbackConfig.enabled) {
-                    await this.holdPrimarySummaryRequest(agent, retryDispatch.originalRequestId, 'primary_summary_fallback_disabled_before_retry');
-                    agent.reset();
-                    this.settleAgent(agent.name, { stopReason: 'completed', speech: '' });
-                    this.eventGate?.onInferenceEnded(agent.name);
-                    this.lastInferenceAt.set(agent.name, { ...this.lastInferenceAt.get(agent.name), endedAt: Date.now() });
-                    return;
-                }
-                const claim = await this.claimPrimarySummaryRetryIntent(retryDispatch.originalRequestId, retryDispatch.intentId, requestId);
-                if (claim !== 'claimed') {
-                    await this.holdPrimarySummaryRequest(agent, retryDispatch.originalRequestId, claim === 'duplicate'
-                        ? 'primary_summary_fallback_duplicate_retry_blocked'
-                        : 'primary_summary_fallback_retry_intent_missing', { intentId: retryDispatch.intentId, retryRequestId: requestId });
-                    agent.reset();
-                    this.settleAgent(agent.name, { stopReason: 'completed', speech: '' });
-                    this.eventGate?.onInferenceEnded(agent.name);
-                    this.lastInferenceAt.set(agent.name, { ...this.lastInferenceAt.get(agent.name), endedAt: Date.now() });
-                    return;
-                }
-                if (!branch ||
-                    branch.id !== retryDispatch.branch.id ||
-                    branch.generation !== retryDispatch.branch.generation) {
-                    await this.holdPrimarySummaryRequest(agent, retryDispatch.originalRequestId, 'primary_summary_fallback_branch_changed_before_retry', {
-                        expectedBranchId: retryDispatch.branch.id,
-                        expectedGeneration: retryDispatch.branch.generation,
-                        actualBranchId: branch?.id,
-                        actualGeneration: branch?.generation,
-                    });
-                    agent.reset();
-                    this.settleAgent(agent.name, { stopReason: 'completed', speech: '' });
-                    this.eventGate?.onInferenceEnded(agent.name);
-                    this.lastInferenceAt.set(agent.name, { ...this.lastInferenceAt.get(agent.name), endedAt: Date.now() });
-                    return;
-                }
-                const rebuilt = agent.buildPrimarySummaryRawExpansionRequest(retryDispatch.originalArtifacts, retryDispatch.candidateSummaries, tools);
-                compiledRequest = rebuilt.request;
-                artifacts = rebuilt.artifacts;
-                const rebuiltHash = this.hashJson(compiledRequest);
-                if (rebuiltHash !== retryDispatch.expectedRetryRequestHash ||
-                    this.primarySummaryProjectionKeys(artifacts.compileResult.primarySummaryProjection ?? null).join('\u0000') !==
-                        retryDispatch.originalProjectionKeys.join('\u0000')) {
-                    await this.holdPrimarySummaryRequest(agent, retryDispatch.originalRequestId, 'primary_summary_fallback_revalidation_failed_before_retry', {
-                        expectedRetryRequestHash: retryDispatch.expectedRetryRequestHash,
-                        actualRetryRequestHash: rebuiltHash,
-                    });
-                    agent.reset();
-                    this.settleAgent(agent.name, { stopReason: 'completed', speech: '' });
-                    this.eventGate?.onInferenceEnded(agent.name);
-                    this.lastInferenceAt.set(agent.name, { ...this.lastInferenceAt.get(agent.name), endedAt: Date.now() });
-                    return;
-                }
-                const retryRecord = this.buildPrimarySummaryRequestRecord(agent, requestId, 'primary_summary_fallback_retry', compiledRequest, artifacts, branch, undefined, false, 0, undefined, 'pending');
-                await this.persistPrimarySummaryRequestRecord(retryRecord);
-                const admittedTokens = this.primarySummaryAdmissionBoundTokens(retryDispatch.originalRequestInputBoundTokens, compiledRequest, retryDispatch.originalProviderInputTokens);
-                if (admittedTokens > retryDispatch.requestBudgetTokens) {
-                    await this.holdPrimarySummaryRequest(agent, requestId, 'primary_summary_fallback_retry_over_budget', {
-                        admittedTokens,
-                        requestBudgetTokens: retryDispatch.requestBudgetTokens,
-                        retryRequestHash: rebuiltHash,
-                    });
-                    await this.updatePrimarySummaryRequestRecord(retryDispatch.originalRequestId, (record) => ({
-                        ...record,
-                        fallbackStatus: 'held',
-                        fallbackHeldReason: 'primary_summary_fallback_retry_over_budget',
-                    }));
-                    agent.reset();
-                    this.settleAgent(agent.name, { stopReason: 'completed', speech: '' });
-                    this.eventGate?.onInferenceEnded(agent.name);
-                    this.lastInferenceAt.set(agent.name, { ...this.lastInferenceAt.get(agent.name), endedAt: Date.now() });
-                    return;
+            // Gather context from modules (pull-based) and MCPL hooks (push-based)
+            // Both produce ContextInjection[] that get merged before inference.
+            let injections;
+            // Module gatherContext (fail-open, per-module timeout — the module's
+            // contextTimeoutMs, else the registry default). Injections are
+            // channel-scoped via scopeInjectionsForAgent, matching the MCPL hook
+            // injections below, so conversation forks don't see cross-channel
+            // content.
+            try {
+                const moduleInjections = this.scopeInjectionsForAgent(agent.name, await this.moduleRegistry.gatherContext(agent.name));
+                if (moduleInjections.length > 0) {
+                    injections = moduleInjections;
                 }
             }
-            else {
-                // Gather context from modules (pull-based) and MCPL hooks (push-based)
-                // Both produce ContextInjection[] that get merged before inference.
-                let injections;
-                // Module gatherContext (fail-open, per-module timeout — the module's
-                // contextTimeoutMs, else the registry default). Injections are
-                // channel-scoped via scopeInjectionsForAgent, matching the MCPL hook
-                // injections below, so conversation forks don't see cross-channel
-                // content.
+            catch (error) {
+                console.error('Module gatherContext error:', error);
+            }
+            // MCPL beforeInference hooks (fail-open)
+            if (this.hookOrchestrator) {
                 try {
-                    const moduleInjections = this.scopeInjectionsForAgent(agent.name, await this.moduleRegistry.gatherContext(agent.name));
-                    if (moduleInjections.length > 0) {
-                        injections = moduleInjections;
+                    const hookParams = this.buildBeforeInferenceParams(agent, trigger);
+                    const hookInjections = this.scopeInjectionsForAgent(agent.name, await this.hookOrchestrator.beforeInference(hookParams));
+                    if (hookInjections.length > 0) {
+                        injections = injections ? [...injections, ...hookInjections] : hookInjections;
                     }
                 }
                 catch (error) {
-                    console.error('Module gatherContext error:', error);
-                }
-                // MCPL beforeInference hooks (fail-open)
-                if (this.hookOrchestrator) {
-                    try {
-                        const hookParams = this.buildBeforeInferenceParams(agent, trigger);
-                        const hookInjections = this.scopeInjectionsForAgent(agent.name, await this.hookOrchestrator.beforeInference(hookParams));
-                        if (hookInjections.length > 0) {
-                            injections = injections ? [...injections, ...hookInjections] : hookInjections;
-                        }
-                    }
-                    catch (error) {
-                        console.error('beforeInference hook error:', error);
-                    }
-                }
-                const prepared = await agent.prepareActivationRequest(tools, injections);
-                compiledRequest = prepared.request;
-                artifacts = prepared.artifacts;
-                branch = agent.getCurrentBranchGeneration();
-                if (fallbackConfig.enabled) {
-                    const record = this.buildPrimarySummaryRequestRecord(agent, requestId, 'primary', compiledRequest, artifacts, branch, undefined, false, 0, undefined, 'pending');
-                    await this.persistPrimarySummaryRequestRecord(record);
-                    const expandedByQuarantine = artifacts.compileResult.primarySummaryProjection?.selectedSummaries.some((selection) => selection.renderedAs === 'raw_expansion') ?? false;
-                    if (expandedByQuarantine) {
-                        const admittedTokens = this.estimateRequestCompleteBoundTokens(compiledRequest);
-                        if (admittedTokens > fallbackConfig.requestBudgetTokens) {
-                            await this.holdPrimarySummaryRequest(agent, requestId, 'primary_summary_quarantine_over_budget', {
-                                admittedTokens,
-                                requestBudgetTokens: fallbackConfig.requestBudgetTokens,
-                            });
-                            agent.reset();
-                            this.settleAgent(agent.name, { stopReason: 'completed', speech: '' });
-                            this.eventGate?.onInferenceEnded(agent.name);
-                            this.lastInferenceAt.set(agent.name, { ...this.lastInferenceAt.get(agent.name), endedAt: Date.now() });
-                            return;
-                        }
-                    }
+                    console.error('beforeInference hook error:', error);
                 }
             }
-            const { stream } = agent.startStreamFromRequest(compiledRequest, artifacts);
-            this.activeStreamContexts.set(agent.name, {
-                requestId,
-                trigger,
-                compiledRequest,
-                artifacts,
-            });
-            const handle = this.driveStream(agent, stream, requestSnapshot, requestId, trigger, attempt, compiledRequest, artifacts);
+            const { stream, request: compiledRequest } = await agent.startStreamWithInjections(tools, injections);
+            const handle = this.driveStream(agent, stream, requestSnapshot, trigger, attempt, compiledRequest);
             this.activeStreams.set(agent.name, handle);
         }
         catch (error) {
             const err = error instanceof Error ? error : new Error(String(error));
-            if (trigger?.primarySummaryFallbackRetry) {
-                await this.updatePrimarySummaryRequestRecord(requestId, (record) => ({
-                    ...record,
-                    finalStatus: 'held',
-                    fallbackHeldReason: err.message,
-                }));
-                await this.updatePrimarySummaryRequestRecord(trigger.primarySummaryFallbackRetry.originalRequestId, (record) => ({
-                    ...record,
-                    finalStatus: 'held',
-                    fallbackStatus: 'held',
-                    fallbackHeldReason: err.message,
-                }));
-                this.opsAlert('refusal-held', agent.name, err.message, {
-                    data: { requestId, originalRequestId: trigger.primarySummaryFallbackRetry.originalRequestId },
-                });
-                agent.reset();
-                this.settleAgent(agent.name, {
-                    stopReason: 'completed',
-                    speech: '',
-                });
-                this.eventGate?.onInferenceEnded(agent.name);
-                this.lastInferenceAt.set(agent.name, { ...this.lastInferenceAt.get(agent.name), endedAt: Date.now() });
-                return;
-            }
             this.emitTrace({
                 type: 'inference:failed',
                 agentName: agent.name,
@@ -4650,17 +3422,11 @@ export class AgentFramework {
             }
         }
     }
-    async driveStream(agent, stream, requestSnapshot, requestId, trigger, attempt = 0, compiledRequest, artifacts) {
+    async driveStream(agent, stream, requestSnapshot, trigger, attempt = 0, compiledRequest) {
         const startTime = Date.now();
+        const requestId = `${agent.name}-${startTime}-${Math.random().toString(36).slice(2, 8)}`;
         const myStreamId = agent.streamId;
         let hadToolCalls = false;
-        let executedToolCalls = 0;
-        const primarySummaryConfig = this.primarySummaryFallbackConfig(agent);
-        const primarySummaryRetry = trigger?.primarySummaryFallbackRetry;
-        let primarySummaryQuarantinePersisted = false;
-        const fallbackRetryRequestForLog = primarySummaryRetry && compiledRequest
-            ? this.summarizePrimarySummaryRetryRequest(compiledRequest)
-            : compiledRequest ?? { note: 'streaming request' };
         // ---- Present-while-acting turn state ---------------------------------
         // Output locus for the current CONVERSATIONAL ROUND: resolved lazily and
         // kept stable across tool-only rounds. A channel message injected at a
@@ -4668,7 +3434,7 @@ export class AgentFramework {
         // single provider inference can now contain several conversations. The
         // pin lives in `turnLocusPins` so it survives a context-budget restart. A
         // null resolution is not pinned.
-        if (trigger?.reason !== 'context_budget_restart' && trigger?.reason !== 'primary-summary-fallback-retry') {
+        if (trigger?.reason !== 'context_budget_restart') {
             this.turnLocusPins.delete(agent.name);
             this.midTurnRoutingResets.delete(agent.name);
         }
@@ -4736,61 +3502,6 @@ export class AgentFramework {
                 }
             }
         };
-        const persistPrimarySummaryRetryQuarantine = async () => {
-            if (!primarySummaryRetry || primarySummaryQuarantinePersisted || !artifacts)
-                return true;
-            const validation = await this.validatePrimarySummaryRetryMutation(agent, requestId, primarySummaryRetry, compiledRequest, artifacts, 'before_quarantine');
-            if (!validation.ok) {
-                await this.holdPrimarySummaryRetryFamily(agent, requestId, primarySummaryRetry, validation.reason, validation.data, { emitChronicleMarker: false });
-                stream.cancel();
-                agent.reset();
-                this.settleAgent(agent.name, { stopReason: 'completed', speech: '' });
-                return false;
-            }
-            try {
-                const quarantinePrimarySummaryForPrimaryLane = agent.getContextManager().quarantinePrimarySummaryForPrimaryLane;
-                if (typeof quarantinePrimarySummaryForPrimaryLane !== 'function') {
-                    throw new Error('Primary summary quarantine is unavailable in the active context strategy');
-                }
-                await quarantinePrimarySummaryForPrimaryLane.call(agent.getContextManager(), artifacts.contract, primarySummaryRetry.candidateSummaries);
-                primarySummaryQuarantinePersisted = true;
-                await this.recordPrimarySummaryRetryQuarantine(primarySummaryRetry.originalRequestId, primarySummaryRetry.intentId);
-                return true;
-            }
-            catch (error) {
-                const reason = 'primary_summary_fallback_quarantine_failed';
-                await this.holdPrimarySummaryRetryFamily(agent, requestId, primarySummaryRetry, reason, {
-                    error: error instanceof Error ? error.message : String(error),
-                });
-                stream.cancel();
-                agent.reset();
-                this.settleAgent(agent.name, { stopReason: 'completed', speech: '' });
-                return false;
-            }
-        };
-        const persistPrimarySummaryRetryOutput = async (phase, blocks, participant = agent.name, metadata) => {
-            if (!primarySummaryRetry || !artifacts)
-                return true;
-            if (blocks.length === 0)
-                return true;
-            const validation = await this.validatePrimarySummaryRetryMutation(agent, requestId, primarySummaryRetry, compiledRequest, artifacts, `before_${phase}`);
-            if (!validation.ok) {
-                await this.holdPrimarySummaryRetryFamily(agent, requestId, primarySummaryRetry, validation.reason, validation.data, { emitChronicleMarker: false });
-                stream.cancel();
-                agent.reset();
-                this.settleAgent(agent.name, { stopReason: 'completed', speech: '' });
-                return false;
-            }
-            const messageId = agent.getContextManager().addMessage(participant, blocks, metadata);
-            await this.recordPrimarySummaryRetryOutput(primarySummaryRetry.originalRequestId, primarySummaryRetry.intentId, {
-                phase,
-                contentHash: this.primarySummaryFallbackOutputPhaseHash(blocks),
-                messageId,
-                blockTypes: this.primarySummaryFallbackBlockTypes(blocks),
-                persistedAt: Date.now(),
-            });
-            return true;
-        };
         try {
             for await (const event of stream) {
                 this.touchEphemeralRun(agent.name, true);
@@ -4818,6 +3529,7 @@ export class AgentFramework {
                     case 'tool-calls': {
                         adoptInjectedRound();
                         hadToolCalls = true;
+                        this.recordEphemeralToolCalls(agent.name, event.calls.length);
                         this.emitTrace({
                             type: 'inference:tool_calls_yielded',
                             agentName: agent.name,
@@ -4851,30 +3563,7 @@ export class AgentFramework {
                         // Truncated responses yield 'complete' with stop_reason 'max_tokens' directly.
                         // So all calls here have valid input — {} is legitimate for parameterless tools.
                         agent.enterWaitingForTools(event.calls, stream);
-                        if (!(await persistPrimarySummaryRetryQuarantine())) {
-                            return;
-                        }
-                        if (primarySummaryRetry) {
-                            const phase = `tool_round_${event.context.depth ?? 0}`;
-                            if (!(await persistPrimarySummaryRetryOutput(phase, assistantBlocks))) {
-                                return;
-                            }
-                            this.pendingAssistantBlocks.delete(agent.name);
-                        }
-                        executedToolCalls += event.calls.length;
-                        this.recordEphemeralToolCalls(agent.name, event.calls.length);
                         for (const call of event.calls) {
-                            if (primarySummaryRetry) {
-                                const validation = await this.validatePrimarySummaryRetryMutation(agent, requestId, primarySummaryRetry, compiledRequest, artifacts, `before_tool_dispatch_${call.id}`);
-                                if (!validation.ok) {
-                                    await this.holdPrimarySummaryRetryFamily(agent, requestId, primarySummaryRetry, validation.reason, validation.data, { emitChronicleMarker: false });
-                                    stream.cancel();
-                                    agent.reset();
-                                    this.settleAgent(agent.name, { stopReason: 'completed', speech: '' });
-                                    return;
-                                }
-                                await this.recordPrimarySummaryRetryToolDispatch(primarySummaryRetry.originalRequestId, primarySummaryRetry.intentId, call);
-                            }
                             this.dispatchToolCall(agent.name, call);
                         }
                         // Speak-while-acting: route THIS round's prose to the locus NOW
@@ -4956,167 +3645,6 @@ export class AgentFramework {
                                 agent.getContextManager().addMessage('user', toolResultContent);
                             }
                         }
-                        const lastToolIdx = response.content.reduce((last, b, i) => b.type === 'tool_use' || b.type === 'tool_result' ? i : last, -1);
-                        const terminalContent = lastToolIdx >= 0
-                            ? response.content.slice(lastToolIdx + 1)
-                            : response.content;
-                        const heldAssistantContent = response.content;
-                        const visibleAssistantOutput = this.hasVisibleAssistantOutput(response.content);
-                        const providerInputTokens = response.usage?.inputTokens ??
-                            response.details?.usage?.inputTokens;
-                        if (primarySummaryConfig.enabled && compiledRequest && artifacts && response.stopReason === 'refusal') {
-                            const stopDetails = response.raw?.response?.stop_details;
-                            const category = stopDetails?.category ?? 'unknown';
-                            console.error(`[inference-refusal] agent=${agent.name} category=${category}` +
-                                (stopDetails?.explanation ? ` explanation=${stopDetails.explanation}` : ''));
-                            this.noteRefusal(agent.name, category, response.details?.usage
-                                ? {
-                                    input: response.details.usage.inputTokens,
-                                    output: response.details.usage.outputTokens,
-                                }
-                                : undefined);
-                            const currentRecord = await this.updatePrimarySummaryRequestRecord(requestId, (record) => ({
-                                ...record,
-                                stopReason: response.stopReason,
-                                providerInputTokens,
-                                visibleAssistantOutput,
-                                executedToolCalls,
-                                finalStatus: 'refusal',
-                            }));
-                            const holdReasonData = {
-                                category,
-                                visibleAssistantOutput,
-                                executedToolCalls,
-                                candidateLimit: primarySummaryConfig.maxNewSummaries,
-                            };
-                            if (primarySummaryRetry) {
-                                const reason = visibleAssistantOutput
-                                    ? 'primary_summary_fallback_retry_partial_output'
-                                    : executedToolCalls > 0
-                                        ? 'primary_summary_fallback_retry_tool_already_executed'
-                                        : 'primary_summary_fallback_retry_refusal';
-                                if (visibleAssistantOutput || executedToolCalls > 0) {
-                                    await this.persistPrimarySummaryHeldOutput(agent, requestId, reason, {
-                                        stopReason: response.stopReason,
-                                        providerInputTokens,
-                                        visibleAssistantOutput,
-                                        executedToolCalls,
-                                        assistantBlocks: heldAssistantContent,
-                                        retryDispatch: primarySummaryRetry,
-                                        retryPhase: 'refusal_visible_output',
-                                        holdData: holdReasonData,
-                                    });
-                                }
-                                else {
-                                    await this.holdPrimarySummaryRetryFamily(agent, requestId, primarySummaryRetry, reason, holdReasonData);
-                                }
-                            }
-                            else if (visibleAssistantOutput || executedToolCalls > 0 || !currentRecord?.projection) {
-                                const reason = visibleAssistantOutput
-                                    ? 'primary_summary_refusal_partial_output'
-                                    : executedToolCalls > 0
-                                        ? 'primary_summary_refusal_tool_already_executed'
-                                        : 'primary_summary_refusal_no_projection';
-                                if (visibleAssistantOutput || executedToolCalls > 0) {
-                                    await this.persistPrimarySummaryHeldOutput(agent, requestId, reason, {
-                                        stopReason: response.stopReason,
-                                        providerInputTokens,
-                                        visibleAssistantOutput,
-                                        executedToolCalls,
-                                        assistantBlocks: heldAssistantContent,
-                                        holdData: holdReasonData,
-                                    });
-                                }
-                                else {
-                                    await this.holdPrimarySummaryRequest(agent, requestId, reason, holdReasonData);
-                                }
-                            }
-                            else {
-                                const state = this.readPrimarySummaryFallbackState();
-                                const baseline = this.latestCompatibleHealthyPrimaryRequest(currentRecord, state);
-                                if (!baseline?.projection) {
-                                    await this.holdPrimarySummaryRequest(agent, requestId, 'primary_summary_refusal_no_compatible_healthy_baseline', holdReasonData);
-                                }
-                                else {
-                                    const baselineKeys = new Set(this.primarySummaryProjectionKeys(baseline.projection));
-                                    const candidates = currentRecord.projection.selectedSummaries
-                                        .filter((selection) => !baselineKeys.has(this.primarySummaryIdentityKey(selection.identity)))
-                                        .map((selection) => selection.identity);
-                                    if (candidates.length === 0) {
-                                        await this.holdPrimarySummaryRequest(agent, requestId, 'primary_summary_refusal_no_newly_admitted_candidates', holdReasonData);
-                                    }
-                                    else if (candidates.length > primarySummaryConfig.maxNewSummaries) {
-                                        await this.holdPrimarySummaryRequest(agent, requestId, 'primary_summary_refusal_too_many_candidates', { ...holdReasonData, candidateCount: candidates.length });
-                                    }
-                                    else {
-                                        try {
-                                            const retry = agent.buildPrimarySummaryRawExpansionRequest(artifacts, candidates, compiledRequest.tools ?? []);
-                                            const retryRequestHash = this.hashJson(retry.request);
-                                            const admittedTokens = this.primarySummaryAdmissionBoundTokens(currentRecord.requestInputBoundTokens, retry.request, providerInputTokens);
-                                            if (admittedTokens > primarySummaryConfig.requestBudgetTokens) {
-                                                await this.holdPrimarySummaryRequest(agent, requestId, 'primary_summary_refusal_retry_over_budget', {
-                                                    ...holdReasonData,
-                                                    admittedTokens,
-                                                    requestBudgetTokens: primarySummaryConfig.requestBudgetTokens,
-                                                });
-                                            }
-                                            else {
-                                                const intentId = `${requestId}:fallback:${Math.random().toString(36).slice(2, 8)}`;
-                                                await this.updatePrimarySummaryRequestRecord(requestId, (record) => ({
-                                                    ...record,
-                                                    fallbackIntent: {
-                                                        intentId,
-                                                        createdAt: Date.now(),
-                                                        baselineRequestId: baseline.requestId,
-                                                        candidateSummaries: candidates,
-                                                        retryRequestHash,
-                                                        retryCompleteBoundTokens: admittedTokens,
-                                                        requestBudgetTokens: primarySummaryConfig.requestBudgetTokens,
-                                                    },
-                                                    fallbackStatus: 'pending',
-                                                }));
-                                                this.pendingRequests.push({
-                                                    agentName: agent.name,
-                                                    reason: 'primary-summary-fallback-retry',
-                                                    source: 'framework',
-                                                    timestamp: Date.now(),
-                                                    channelId: trigger?.channelId,
-                                                    primarySummaryFallbackRetry: {
-                                                        originalRequestId: requestId,
-                                                        baselineRequestId: baseline.requestId,
-                                                        intentId,
-                                                        branch: {
-                                                            id: currentRecord.branch.id,
-                                                            generation: currentRecord.branch.generation,
-                                                        },
-                                                        candidateSummaries: candidates,
-                                                        originalArtifacts: artifacts,
-                                                        originalProjectionKeys: this.primarySummaryProjectionKeys(currentRecord.projection),
-                                                        expectedRetryRequestHash: retryRequestHash,
-                                                        requestBudgetTokens: primarySummaryConfig.requestBudgetTokens,
-                                                        originalRequestInputBoundTokens: currentRecord.requestInputBoundTokens,
-                                                        originalProviderInputTokens: providerInputTokens,
-                                                    },
-                                                });
-                                            }
-                                        }
-                                        catch (error) {
-                                            await this.holdPrimarySummaryRequest(agent, requestId, 'primary_summary_refusal_retry_build_failed', {
-                                                ...holdReasonData,
-                                                error: error instanceof Error ? error.message : String(error),
-                                            });
-                                        }
-                                    }
-                                }
-                            }
-                            agent.reset();
-                            this.eventGate?.onInferenceEnded(agent.name);
-                            this.settleAgent(agent.name, { stopReason: 'completed', speech: '' });
-                            continue;
-                        }
-                        if (!(await persistPrimarySummaryRetryQuarantine())) {
-                            return;
-                        }
                         // Add assistant response to context.
                         // If we had tool calls, each round's blocks (thinking + text +
                         // tool_use) were already stored as pendingAssistantBlocks and
@@ -5125,55 +3653,17 @@ export class AgentFramework {
                         // double-store earlier rounds' text/thinking AND detach signed
                         // thinking blocks from their tool_use turn (the API requires
                         // thinking to precede tool_use in the same assistant turn).
+                        const lastToolIdx = response.content.reduce((last, b, i) => b.type === 'tool_use' || b.type === 'tool_result' ? i : last, -1);
+                        const terminalContent = lastToolIdx >= 0
+                            ? response.content.slice(lastToolIdx + 1)
+                            : response.content;
                         if (lastToolIdx >= 0) {
                             if (terminalContent.length > 0) {
-                                if (primarySummaryRetry) {
-                                    const retryRecord = await this.getPrimarySummaryRequestRecord(requestId);
-                                    const terminalMetadata = retryRecord
-                                        ? this.buildPrimarySummarySettlementMetadata(retryRecord, {
-                                            outcome: 'success',
-                                            stopReason: response.stopReason,
-                                            providerInputTokens,
-                                            visibleAssistantOutput,
-                                            executedToolCalls,
-                                            entryIndex: 0,
-                                            entryCount: 1,
-                                            role: 'assistant',
-                                            kind: 'assistant_output',
-                                        })
-                                        : undefined;
-                                    if (!(await persistPrimarySummaryRetryOutput('terminal', terminalContent, agent.name, terminalMetadata))) {
-                                        return;
-                                    }
-                                }
-                                else {
-                                    agent.addAssistantResponse(terminalContent);
-                                }
+                                agent.addAssistantResponse(terminalContent);
                             }
                         }
                         else {
-                            if (primarySummaryRetry) {
-                                const retryRecord = await this.getPrimarySummaryRequestRecord(requestId);
-                                const terminalMetadata = retryRecord && terminalContent.length > 0
-                                    ? this.buildPrimarySummarySettlementMetadata(retryRecord, {
-                                        outcome: 'success',
-                                        stopReason: response.stopReason,
-                                        providerInputTokens,
-                                        visibleAssistantOutput,
-                                        executedToolCalls,
-                                        entryIndex: 0,
-                                        entryCount: 1,
-                                        role: 'assistant',
-                                        kind: 'assistant_output',
-                                    })
-                                    : undefined;
-                                if (!(await persistPrimarySummaryRetryOutput('terminal', terminalContent, agent.name, terminalMetadata))) {
-                                    return;
-                                }
-                            }
-                            else {
-                                agent.addAssistantResponse(terminalContent);
-                            }
+                            agent.addAssistantResponse(terminalContent);
                         }
                         // Run afterInference hooks (no-op if no MCPL servers)
                         if (this.hookOrchestrator) {
@@ -5228,28 +3718,6 @@ export class AgentFramework {
                                 cacheRead: du.cacheReadTokens,
                             }
                             : undefined;
-                        if (primarySummaryRetry && artifacts) {
-                            const validation = await this.validatePrimarySummaryRetryMutation(agent, requestId, primarySummaryRetry, compiledRequest, artifacts, 'before_success_markers');
-                            if (!validation.ok) {
-                                await this.holdPrimarySummaryRetryFamily(agent, requestId, primarySummaryRetry, validation.reason, validation.data, { emitChronicleMarker: false });
-                                return;
-                            }
-                        }
-                        if (primarySummaryConfig.enabled) {
-                            if (primarySummaryRetry) {
-                                await this.markPrimarySummaryRetrySuccess(requestId, primarySummaryRetry, response.stopReason, providerInputTokens, visibleAssistantOutput, executedToolCalls);
-                            }
-                            else {
-                                await this.updatePrimarySummaryRequestRecord(requestId, (record) => ({
-                                    ...record,
-                                    stopReason: response.stopReason,
-                                    providerInputTokens,
-                                    visibleAssistantOutput,
-                                    executedToolCalls,
-                                    finalStatus: 'success',
-                                }));
-                            }
-                        }
                         // 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.
@@ -5285,10 +3753,8 @@ export class AgentFramework {
                             agentName: agent.name,
                             requestId,
                             success: true,
-                            request: fallbackRetryRequestForLog,
-                            response: primarySummaryRetry
-                                ? this.summarizePrimarySummaryRetryResponse(response)
-                                : response.raw ?? { note: 'streaming response' },
+                            request: compiledRequest ?? { note: 'streaming request' },
+                            response: response.raw ?? { note: 'streaming response' },
                             durationMs,
                             tokenUsage,
                             stopReason: response.stopReason,
@@ -5481,22 +3947,12 @@ export class AgentFramework {
                             requestId,
                             success: false,
                             error: err.message,
-                            request: fallbackRetryRequestForLog,
+                            request: compiledRequest ?? { note: 'streaming request failed' },
                             durationMs,
                         });
                         // Only reset + retry if this is still the active stream
                         if (agent.streamId !== myStreamId)
                             break;
-                        if (primarySummaryRetry) {
-                            await this.holdPrimarySummaryRetryFamily(agent, requestId, primarySummaryRetry, 'primary_summary_fallback_retry_stream_error', { error: err.message });
-                            agent.reset();
-                            this.eventGate?.onInferenceEnded(agent.name);
-                            this.settleAgent(agent.name, {
-                                stopReason: 'completed',
-                                speech: '',
-                            });
-                            return;
-                        }
                         agent.reset();
                         const action = this.errorPolicy.onInferenceError(err, agent.name, attempt);
                         if (action.retry) {
@@ -5535,11 +3991,6 @@ export class AgentFramework {
                         // reject an ephemeral's promise mid-run and bump the failure
                         // streak). Gate release + stream teardown happen in `finally`.
                         if (this.frameworkCancelledStreams.delete(`${agent.name}:${myStreamId}`)) {
-                            if (primarySummaryRetry) {
-                                if (!(await this.primarySummaryRetryFamilyAlreadySettled(requestId, primarySummaryRetry))) {
-                                    await this.holdPrimarySummaryRetryFamily(agent, requestId, primarySummaryRetry, 'primary_summary_fallback_retry_cancelled_before_success', { frameworkCancelled: true });
-                                }
-                            }
                             this.eventGate?.onInferenceEnded(agent.name);
                             return;
                         }
@@ -5548,33 +3999,6 @@ export class AgentFramework {
                         // may have already started a new stream, bumping streamId)
                         if (agent.streamId === myStreamId) {
                             const durationMs = Date.now() - startTime;
-                            if (primarySummaryRetry) {
-                                await this.holdPrimarySummaryRetryFamily(agent, requestId, primarySummaryRetry, `stream_aborted:${reason}`, { reason }, { stopReason: 'abort' });
-                                agent.reset();
-                                this.eventGate?.onInferenceEnded(agent.name);
-                                this.logInference({
-                                    timestamp: startTime,
-                                    agentName: agent.name,
-                                    requestId,
-                                    success: false,
-                                    error: `Stream aborted: ${reason}`,
-                                    request: fallbackRetryRequestForLog,
-                                    durationMs,
-                                });
-                                this.settleAgent(agent.name, {
-                                    stopReason: 'completed',
-                                    speech: '',
-                                });
-                                return;
-                            }
-                            if (primarySummaryConfig.enabled) {
-                                await this.updatePrimarySummaryRequestRecord(requestId, (record) => ({
-                                    ...record,
-                                    stopReason: 'abort',
-                                    finalStatus: 'error',
-                                    fallbackHeldReason: `stream_aborted:${reason}`,
-                                }));
-                            }
                             agent.reset();
                             this.settleAgent(agent.name, {
                                 stopReason: 'exhausted',
@@ -5598,7 +4022,7 @@ export class AgentFramework {
                                 requestId,
                                 success: false,
                                 error: `Stream aborted: ${reason}`,
-                                request: fallbackRetryRequestForLog,
+                                request: compiledRequest ?? { note: 'streaming request aborted' },
                                 durationMs,
                             });
                             this.eventGate?.onInferenceEnded(agent.name);
@@ -5644,58 +4068,12 @@ export class AgentFramework {
             // inference:exhausted so ephemeral agent promises can settle.
             const err = error instanceof Error ? error : new Error(String(error));
             const durationMs = Date.now() - startTime;
-            if (primarySummaryRetry) {
-                if (await this.primarySummaryRetryAlreadySucceeded(requestId, primarySummaryRetry)) {
-                    this.logInference({
-                        timestamp: startTime,
-                        agentName: agent.name,
-                        requestId,
-                        success: true,
-                        request: fallbackRetryRequestForLog,
-                        response: { kind: 'primary_summary_fallback_retry', postSuccessError: err.message },
-                        durationMs,
-                    });
-                    agent.reset();
-                    this.eventGate?.onInferenceEnded(agent.name);
-                    this.settleAgent(agent.name, {
-                        stopReason: 'completed',
-                        speech: '',
-                    });
-                    return;
-                }
-                await this.holdPrimarySummaryRetryFamily(agent, requestId, primarySummaryRetry, 'primary_summary_fallback_retry_stream_threw', { error: err.message });
-            }
-            else if (primarySummaryConfig.enabled) {
-                await this.updatePrimarySummaryRequestRecord(requestId, (record) => ({
-                    ...record,
-                    finalStatus: 'error',
-                    fallbackHeldReason: err.message,
-                }));
-            }
             this.emitTrace({
                 type: 'inference:failed',
                 agentName: agent.name,
                 error: err.message,
                 stack: err.stack,
             });
-            if (primarySummaryRetry) {
-                this.logInference({
-                    timestamp: startTime,
-                    agentName: agent.name,
-                    requestId,
-                    success: false,
-                    error: `Stream threw: ${err.message}`,
-                    request: fallbackRetryRequestForLog,
-                    durationMs,
-                });
-                agent.reset();
-                this.eventGate?.onInferenceEnded(agent.name);
-                this.settleAgent(agent.name, {
-                    stopReason: 'completed',
-                    speech: '',
-                });
-                return;
-            }
             this.settleAgent(agent.name, {
                 stopReason: 'exhausted',
                 speech: '',
@@ -5716,7 +4094,7 @@ export class AgentFramework {
                 requestId,
                 success: false,
                 error: `Stream threw: ${err.message}`,
-                request: fallbackRetryRequestForLog,
+                request: compiledRequest ?? { note: 'streaming request threw' },
                 durationMs,
             });
             agent.reset();
@@ -5737,7 +4115,6 @@ export class AgentFramework {
             this.channelRegistry?.stopTyping();
             this.frameworkCancelledStreams.delete(`${agent.name}:${myStreamId}`);
             this.activeStreams.delete(agent.name);
-            this.activeStreamContexts.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.
@@ -5992,6 +4369,10 @@ export class AgentFramework {
             this.dispatchSaveImageToolCall(agentName, enrichedCall);
             return;
         }
+        if (enrichedCall.name === 'read_image') {
+            this.dispatchReadImageToolCall(agentName, enrichedCall);
+            return;
+        }
         // Route gate_status tool
         if (enrichedCall.name === 'gate_status' && this.eventGate) {
             this.dispatchGateToolCall(agentName, enrichedCall);
@@ -6224,22 +4605,12 @@ export class AgentFramework {
      * work, per-agent status + last inference activity. Cheap and read-only.
      */
     healthSnapshot() {
-        const primarySummary = this.readPrimarySummaryFallbackState();
         return {
             at: new Date().toISOString(),
             uptimeSec: Math.round(process.uptime()),
             gate: this.eventGate?.inferenceDiagnostics() ?? null,
             pendingRequests: this.pendingRequests.length,
             activeStreams: [...this.activeStreams.keys()],
-            primarySummaryFallback: {
-                requests: primarySummary.requests.length,
-                pendingDispatches: primarySummary.requests.filter((record) => record.finalStatus === 'pending').length,
-                unresolvedIntents: primarySummary.requests.filter((record) => record.fallbackStatus === 'pending').length,
-                held: primarySummary.requests.filter((record) => record.finalStatus === 'held' ||
-                    record.finalStatus === 'timeout_unknown' ||
-                    record.fallbackStatus === 'held' ||
-                    record.fallbackStatus === 'timeout_unknown').length,
-            },
             agents: [...this.agents.entries()].map(([name, agent]) => ({
                 name,
                 status: agent.state.status,
@@ -7504,6 +5875,19 @@ export class AgentFramework {
             .then((result) => {
             const durationMs = Date.now() - startTime;
             this.emitTrace({ type: 'tool:completed', module: 'channels', tool: call.name, callId: call.id, durationMs });
+            // A successful channel_open plants the agent's feet in the opened
+            // channel: pin it as this turn's reply locus so plain-text speech
+            // written right after opening routes THERE. Found live 2026-07-21
+            // (Aria bring-up): open → plain-text reply → "no locus (no
+            // home/active channel, defaultPublishChannel null)" on a turn with
+            // no channel trigger (post-restart continuation). Next turn start
+            // re-resolves the locus as usual (startAgentStream set/delete).
+            if (call.name === 'channel_open' && result?.success) {
+                const opened = result.data?.channelId
+                    ?? call.input?.channelId;
+                if (opened)
+                    this.activeTriggerChannels.set(agentName, opened);
+            }
             this.pushEvent({
                 type: 'tool-result',
                 callId: call.id,
@@ -7650,6 +6034,72 @@ export class AgentFramework {
             endTurn: true,
         });
     }
+    /**
+     * Handle the synthesized `read_image` tool: read image bytes from a
+     * workspace mount and return them as a native MCP-shaped content array
+     * (`[{type:'text'…},{type:'image', data, mimeType}]`). The live-turn
+     * converter (tryNativeToolResultContent → membrane tool_result image
+     * blocks) delivers the actual image to the model; history storage keeps
+     * the standard compact `[image: …]` placeholder.
+     */
+    dispatchReadImageToolCall(agentName, call) {
+        this.emitTrace({ type: 'tool:started', module: 'workspace', tool: call.name, callId: call.id, input: call.input });
+        const finish = (result) => {
+            this.emitTrace({
+                type: result.isError ? 'tool:failed' : 'tool:completed',
+                module: 'workspace',
+                tool: call.name,
+                callId: call.id,
+                durationMs: 0,
+                ...(result.isError ? { error: result.error } : {}),
+            });
+            this.pushEvent({ type: 'tool-result', callId: call.id, agentName, moduleName: 'workspace', result });
+        };
+        void (async () => {
+            try {
+                const workspace = this.getWorkspaceModule();
+                if (!workspace || typeof workspace.readBinary !== 'function') {
+                    throw new Error('read_image requires a workspace module');
+                }
+                const input = (call.input ?? {});
+                if (typeof input.path !== 'string' || input.path.length === 0) {
+                    throw new Error('read_image: `path` (mount-prefixed) is required');
+                }
+                const read = await workspace.readBinary(input.path);
+                if ('error' in read)
+                    throw new Error(read.error);
+                const mediaType = sniffImageMediaType(read.data);
+                if (!mediaType) {
+                    throw new Error(`read_image: "${input.path}" does not look like a supported image ` +
+                        '(png/jpeg/gif/webp — checked by magic bytes, not extension)');
+                }
+                // Anthropic rejects images >5MB (and >8000px); guard the hard byte
+                // limit here — resizing is out of scope without an image library.
+                const MAX_IMAGE_BYTES = 5 * 1024 * 1024;
+                if (read.data.byteLength > MAX_IMAGE_BYTES) {
+                    throw new Error(`read_image: "${input.path}" is ${read.data.byteLength} bytes — ` +
+                        `over the ${MAX_IMAGE_BYTES}-byte model limit`);
+                }
+                finish({
+                    success: true,
+                    data: [
+                        {
+                            type: 'text',
+                            text: `${input.path} (${mediaType}, ${Math.ceil(read.data.byteLength / 1024)} KB):`,
+                        },
+                        { type: 'image', data: read.data.toString('base64'), mimeType: mediaType },
+                    ],
+                });
+            }
+            catch (error) {
+                finish({
+                    success: false,
+                    error: error instanceof Error ? error.message : String(error),
+                    isError: true,
+                });
+            }
+        })();
+    }
     /**
      * Handle the synthesized `save_recent_image` tool: locate the requested
      * image blocks in the calling agent's context (blobs re-inlined, counted