@gajae-code/coding-agent 0.4.5 → 0.5.1

package/src/session/agent-session.ts

@@ -244,7 +244,7 @@ import { parseCommandArgs } from "../utils/command-args";
 import { type EditMode, resolveEditMode } from "../utils/edit-mode";
 import { resolveFileDisplayMode } from "../utils/file-display-mode";
 import { extractFileMentions, generateFileMentionMessages } from "../utils/file-mentions";
-import { buildNamedToolChoice } from "../utils/tool-choice";
+import { buildNamedToolChoice, buildNamedToolChoiceResult } from "../utils/tool-choice";
 import type { AuthStorage } from "./auth-storage";
 import type { ClientBridge, ClientBridgePermissionOption, ClientBridgePermissionOutcome } from "./client-bridge";
 import {
@@ -322,7 +322,10 @@ function isUnderProjectGjc(cwd: string, targetPath: string): boolean {
 
 /** Listener function for agent session events */
 export type AgentSessionEventListener = (event: AgentSessionEvent) => void;
-export type AsyncJobSnapshotItem = Pick<AsyncJob, "id" | "type" | "status" | "label" | "startTime" | "metadata">;
+export type AsyncJobSnapshotItem = Pick<
+	AsyncJob,
+	"id" | "type" | "status" | "label" | "startTime" | "endTime" | "metadata"
+>;
 
 export interface AsyncJobSnapshot {
 	running: AsyncJobSnapshotItem[];
@@ -839,6 +842,8 @@ export type BeforeAgentStartInternalMessage = Pick<
 	"customType" | "content" | "display" | "details" | "attribution"
 >;
 
+type ProviderReplaySourceCacheEntry = { source: string; hash: bigint };
+
 /**
  * Internal (first-party, non-user-hook) contributor invoked at the active
  * before-agent-start point alongside the extension runner. Returns an optional
@@ -863,6 +868,7 @@ export class AgentSession {
 
 	#scopedModels: ScopedModelSelection[];
 	#thinkingLevel: ThinkingLevel | undefined;
+	#activeModelProfile: string | undefined;
 	#promptTemplates: PromptTemplate[];
 	#slashCommands: FileSlashCommand[];
 
@@ -900,6 +906,7 @@ export class AgentSession {
 	// Compaction state
 	#compactionAbortController: AbortController | undefined = undefined;
 	#autoCompactionAbortController: AbortController | undefined = undefined;
+	#prePromptContextCheckPromise: Promise<void> | undefined = undefined;
 
 	// Branch summarization state
 	#branchSummaryAbortController: AbortController | undefined = undefined;
@@ -1056,6 +1063,7 @@ export class AgentSession {
 	#pendingAgentEndEmit: AgentSessionEvent | undefined;
 	#obfuscator: SecretObfuscator | undefined;
 	#checkpointState: CheckpointState | undefined = undefined;
+	#providerReplaySourceCache = new WeakMap<AgentMessage, ProviderReplaySourceCacheEntry>();
 	#pendingRewindReport: string | undefined = undefined;
 	#lastSuccessfulYieldToolCallId: string | undefined = undefined;
 	#promptGeneration = 0;
@@ -1419,7 +1427,7 @@ export class AgentSession {
 				recordSkip("unsupported-role");
 				return undefined;
 			}
-			const cloned = structuredClone(message) as Message;
+			const cloned = cloneJsonValueForForkSeed(message) as Message;
 			if ("providerPayload" in cloned) {
 				delete (cloned as { providerPayload?: unknown }).providerPayload;
 			}
@@ -1466,7 +1474,7 @@ export class AgentSession {
 		}
 		return {
 			messages,
-			agentMessages: messages.map(message => structuredClone(message) as AgentMessage),
+			agentMessages: messages.map(message => cloneJsonValueForForkSeed(message) as AgentMessage),
 			metadata: {
 				sourceSessionId: this.sessionId,
 				parentMessageCount: providerMessages.length,
@@ -1559,6 +1567,7 @@ export class AgentSession {
 			status: job.status,
 			label: job.label,
 			startTime: job.startTime,
+			endTime: job.endTime,
 			metadata: job.metadata,
 		}));
 		const recent = manager.getRecentJobs(options?.recentLimit ?? 5, ownerFilter).map(job => ({
@@ -1567,6 +1576,7 @@ export class AgentSession {
 			status: job.status,
 			label: job.label,
 			startTime: job.startTime,
+			endTime: job.endTime,
 			metadata: job.metadata,
 		}));
 		const delivery = manager.getDeliveryState(ownerFilter);
@@ -4588,7 +4598,7 @@ export class AgentSession {
 			: { role: "user" as const, content: userContent, attribution: promptAttribution, timestamp: Date.now() };
 		await this.refreshGjcSubskillTools();
 
-		if (eagerTodoPrelude) {
+		if (eagerTodoPrelude?.toolChoice) {
 			this.#toolChoiceQueue.pushOnce(eagerTodoPrelude.toolChoice, {
 				label: "eager-todo",
 			});
@@ -4749,6 +4759,13 @@ export class AgentSession {
 			if (lastAssistant && !options?.skipCompactionCheck) {
 				await this.#checkCompaction(lastAssistant, false);
 			}
+			if (!options?.skipCompactionCheck) {
+				await this.#checkEstimatedContextBeforePrompt([
+					...(options?.prependMessages ?? []),
+					message,
+					...this.#pendingNextTurnMessages,
+				]);
+			}
 
 			// Build messages array (session context, eager todo prelude, then active prompt message)
 			const messages: AgentMessage[] = [];
@@ -5212,7 +5229,9 @@ export class AgentSession {
 				}
 				await this.#syncSkillPromptActiveStateSafely(appMessage, true);
 				try {
-					await this.agent.prompt(appMessage);
+					await this.#promptWithMessage(appMessage, this.#getCustomMessageTextContent(appMessage), {
+						skipPostPromptRecoveryWait: true,
+					});
 				} finally {
 					await this.#syncSkillPromptActiveStateSafely(appMessage, false);
 				}
@@ -5236,7 +5255,9 @@ export class AgentSession {
 			}
 			await this.#syncSkillPromptActiveStateSafely(appMessage, true);
 			try {
-				await this.agent.prompt(appMessage);
+				await this.#promptWithMessage(appMessage, this.#getCustomMessageTextContent(appMessage), {
+					skipPostPromptRecoveryWait: true,
+				});
 			} finally {
 				await this.#syncSkillPromptActiveStateSafely(appMessage, false);
 			}
@@ -5728,6 +5749,14 @@ export class AgentSession {
 		await this.#syncEditToolModeAfterModelChange(previousEditMode);
 	}
 
+	setActiveModelProfile(name: string | undefined): void {
+		this.#activeModelProfile = name;
+	}
+
+	getActiveModelProfile(): string | undefined {
+		return this.#activeModelProfile;
+	}
+
 	/**
 	 * Set model temporarily (for this session only).
 	 * Validates API key, saves to session log but NOT to settings.
@@ -6530,6 +6559,47 @@ export class AgentSession {
 			}
 		}
 	}
+
+	async #checkEstimatedContextBeforePrompt(pendingMessages: readonly AgentMessage[] = []): Promise<void> {
+		if (this.#prePromptContextCheckPromise) {
+			await this.#prePromptContextCheckPromise;
+		}
+
+		const checkPromise = this.#checkEstimatedContextBeforePromptOnce(pendingMessages);
+		this.#prePromptContextCheckPromise = checkPromise;
+		try {
+			await checkPromise;
+		} finally {
+			if (this.#prePromptContextCheckPromise === checkPromise) {
+				this.#prePromptContextCheckPromise = undefined;
+			}
+		}
+	}
+
+	async #checkEstimatedContextBeforePromptOnce(pendingMessages: readonly AgentMessage[]): Promise<void> {
+		const model = this.model;
+		if (!model) return;
+		const contextWindow = model.contextWindow ?? 0;
+		if (contextWindow <= 0) return;
+		const compactionSettings = this.settings.getGroup("compaction");
+		if (!compactionSettings.enabled || compactionSettings.strategy === "off") return;
+
+		let contextTokens = this.#estimateContextTokensForCompaction(pendingMessages).tokens;
+		const maxOutputTokens = model.maxTokens ?? 0;
+		if (!shouldCompact(contextTokens, contextWindow, compactionSettings, maxOutputTokens)) return;
+
+		const pruneResult = await this.#pruneToolOutputs();
+		if (pruneResult) {
+			contextTokens = Math.max(0, contextTokens - pruneResult.tokensSaved);
+		}
+		if (shouldCompact(contextTokens, contextWindow, compactionSettings, maxOutputTokens)) {
+			await this.#runAutoCompaction("threshold", false, false, {
+				continueAfterMaintenance: false,
+				deferHandoffMaintenance: false,
+			});
+		}
+	}
+
 	#assistantEndedWithSuccessfulYield(assistantMessage: AssistantMessage): boolean {
 		const toolCallId = this.#lastSuccessfulYieldToolCallId;
 		if (!toolCallId) return false;
@@ -6627,7 +6697,7 @@ export class AgentSession {
 		});
 	}
 
-	#createEagerTodoPrelude(promptText: string): { message: AgentMessage; toolChoice: ToolChoice } | undefined {
+	#createEagerTodoPrelude(promptText: string): { message: AgentMessage; toolChoice?: ToolChoice } | undefined {
 		const eagerTodosEnabled = this.settings.get("todo.eager");
 		const todosEnabled = this.settings.get("todo.enabled");
 		if (!eagerTodosEnabled || !todosEnabled) {
@@ -6661,13 +6731,15 @@ export class AgentSession {
 			return undefined;
 		}
 
-		const todoWriteToolChoice = buildNamedToolChoice("todo_write", this.model);
-		if (!todoWriteToolChoice) {
-			logger.warn("Eager todo enforcement skipped because the current model does not support forcing todo_write", {
+		const todoWriteToolChoiceResult = buildNamedToolChoiceResult("todo_write", this.model);
+		const todoWriteToolChoice = todoWriteToolChoiceResult.exactNamed ? todoWriteToolChoiceResult.choice : undefined;
+		if (!todoWriteToolChoiceResult.exactNamed) {
+			logger.debug("Eager todo enforcement degraded; sending reminder without forced tool choice", {
 				modelApi: this.model?.api,
 				modelId: this.model?.id,
+				resolvedLevel: todoWriteToolChoiceResult.resolved?.resolvedLevel,
+				reason: todoWriteToolChoiceResult.resolved?.reason,
 			});
-			return undefined;
 		}
 
 		const eagerTodoReminder = prompt.render(eagerTodoPrompt);
@@ -7049,11 +7121,37 @@ export class AgentSession {
 		}
 	}
 
+	#getProviderReplaySource(message: AgentMessage): ProviderReplaySourceCacheEntry {
+		const cached = this.#providerReplaySourceCache.get(message);
+		if (cached) return cached;
+		const source = JSON.stringify(this.#normalizeSessionMessageForProviderReplay(message));
+		const hash = this.#hashProviderReplaySource(source);
+		const entry = { source, hash };
+		this.#providerReplaySourceCache.set(message, entry);
+		return entry;
+	}
+
+	#hashProviderReplaySource(source: string): bigint {
+		return Bun.hash.xxHash64(source);
+	}
+
 	#didSessionMessagesChange(previousMessages: AgentMessage[], nextMessages: AgentMessage[]): boolean {
-		return (
-			JSON.stringify(previousMessages.map(message => this.#normalizeSessionMessageForProviderReplay(message))) !==
-			JSON.stringify(nextMessages.map(message => this.#normalizeSessionMessageForProviderReplay(message)))
-		);
+		if (previousMessages.length !== nextMessages.length) return true;
+
+		const previousSources: ProviderReplaySourceCacheEntry[] = [];
+		const nextSources: ProviderReplaySourceCacheEntry[] = [];
+		for (let i = 0; i < previousMessages.length; i++) {
+			const previous = this.#getProviderReplaySource(previousMessages[i]!);
+			const next = this.#getProviderReplaySource(nextMessages[i]!);
+			if (previous.hash !== next.hash) return true;
+			previousSources.push(previous);
+			nextSources.push(next);
+		}
+
+		for (let i = 0; i < previousSources.length; i++) {
+			if (previousSources[i]!.source !== nextSources[i]!.source) return true;
+		}
+		return false;
 	}
 
 	#getModelKey(model: Model): string {
@@ -7258,17 +7356,24 @@ export class AgentSession {
 		reason: "overflow" | "threshold" | "idle",
 		willRetry: boolean,
 		deferred = false,
+		options?: { continueAfterMaintenance?: boolean; deferHandoffMaintenance?: boolean },
 	): Promise<void> {
 		const compactionSettings = this.settings.getGroup("compaction");
 		if (compactionSettings.strategy === "off") return;
 		if (reason !== "idle" && !compactionSettings.enabled) return;
 		const generation = this.#promptGeneration;
-		if (!deferred && reason !== "overflow" && reason !== "idle" && compactionSettings.strategy === "handoff") {
+		if (
+			options?.deferHandoffMaintenance !== false &&
+			!deferred &&
+			reason !== "overflow" &&
+			reason !== "idle" &&
+			compactionSettings.strategy === "handoff"
+		) {
 			this.#schedulePostPromptTask(
 				async signal => {
 					await Promise.resolve();
 					if (signal.aborted) return;
-					await this.#runAutoCompaction(reason, willRetry, true);
+					await this.#runAutoCompaction(reason, willRetry, true, options);
 				},
 				{ generation },
 			);
@@ -7277,6 +7382,7 @@ export class AgentSession {
 
 		let action: "context-full" | "handoff" =
 			compactionSettings.strategy === "handoff" && reason !== "overflow" ? "handoff" : "context-full";
+		const continueAfterMaintenance = options?.continueAfterMaintenance !== false;
 		await this.#emitSessionEvent({ type: "auto_compaction_start", reason, action });
 		// Abort any older auto-compaction before installing this run's controller.
 		this.#autoCompactionAbortController?.abort();
@@ -7316,7 +7422,12 @@ export class AgentSession {
 						aborted: false,
 						willRetry: false,
 					});
-					if (!autoCompactionSignal.aborted && reason !== "idle" && compactionSettings.autoContinue !== false) {
+					if (
+						continueAfterMaintenance &&
+						!autoCompactionSignal.aborted &&
+						reason !== "idle" &&
+						compactionSettings.autoContinue !== false
+					) {
 						this.#scheduleAutoContinuePrompt(generation);
 					}
 					return;
@@ -7378,7 +7489,7 @@ export class AgentSession {
 							stopReason: tail?.stopReason,
 						});
 					}
-				} else if (reason !== "idle" && this.agent.hasQueuedMessages()) {
+				} else if (continueAfterMaintenance && reason !== "idle" && this.agent.hasQueuedMessages()) {
 					this.#scheduleAgentContinue({
 						delayMs: 100,
 						generation,
@@ -7386,7 +7497,7 @@ export class AgentSession {
 						onSkip: skipReason => this.#logCompactionContinuationSkipped("queued_continue", skipReason),
 						onError: error => this.#logCompactionContinuationError("queued_continue", error),
 					});
-				} else if (reason !== "idle" && compactionSettings.autoContinue !== false) {
+				} else if (continueAfterMaintenance && reason !== "idle" && compactionSettings.autoContinue !== false) {
 					this.#scheduleAutoContinuePrompt(generation);
 				}
 				return;
@@ -7607,7 +7718,7 @@ export class AgentSession {
 						onError: error => this.#logCompactionContinuationError("overflow_retry", error),
 					});
 				}
-			} else if (reason !== "idle" && this.agent.hasQueuedMessages()) {
+			} else if (continueAfterMaintenance && reason !== "idle" && this.agent.hasQueuedMessages()) {
 				// Auto-compaction can complete while follow-up/steering/custom messages are waiting.
 				// Kick the loop so queued messages are actually delivered.
 				this.#scheduleAgentContinue({
@@ -7617,7 +7728,7 @@ export class AgentSession {
 					onSkip: reason => this.#logCompactionContinuationSkipped("queued_continue", reason),
 					onError: error => this.#logCompactionContinuationError("queued_continue", error),
 				});
-			} else if (reason !== "idle" && compactionSettings.autoContinue !== false) {
+			} else if (continueAfterMaintenance && reason !== "idle" && compactionSettings.autoContinue !== false) {
 				this.#scheduleAutoContinuePrompt(generation);
 			}
 		} catch (error) {
@@ -9516,6 +9627,21 @@ export class AgentSession {
 	 */
 	#estimateContextTokens(): {
 		tokens: number;
+	} {
+		return this.#estimateContextTokensWith(message => this.#estimateMessageDisplayTokens(message));
+	}
+
+	#estimateContextTokensForCompaction(pendingMessages: readonly AgentMessage[]): {
+		tokens: number;
+	} {
+		const estimate = this.#estimateContextTokensWith(message => this.#estimateMessageNativeContextTokens(message));
+		return {
+			tokens: estimate.tokens + this.#estimateMessagesNativeContextTokens(pendingMessages),
+		};
+	}
+
+	#estimateContextTokensWith(estimateMessage: (message: AgentMessage) => number): {
+		tokens: number;
 	} {
 		const messages = this.messages;
 
@@ -9538,7 +9664,7 @@ export class AgentSession {
 			// No usage data - estimate all messages
 			let estimated = 0;
 			for (const message of messages) {
-				estimated += estimateMessageTokensHeuristic(message);
+				estimated += estimateMessage(message);
 			}
 			return {
 				tokens: estimated,
@@ -9548,7 +9674,7 @@ export class AgentSession {
 		const usageTokens = calculatePromptTokens(lastUsage);
 		let trailingTokens = 0;
 		for (let i = lastUsageIndex + 1; i < messages.length; i++) {
-			trailingTokens += estimateMessageTokensHeuristic(messages[i]);
+			trailingTokens += estimateMessage(messages[i]);
 		}
 
 		return {
@@ -9556,6 +9682,30 @@ export class AgentSession {
 		};
 	}
 
+	#estimateMessagesNativeContextTokens(messages: readonly AgentMessage[]): number {
+		let tokens = 0;
+		for (const message of messages) {
+			tokens += this.#estimateMessageNativeContextTokens(message);
+		}
+		return tokens;
+	}
+
+	#estimateMessageDisplayTokens(message: AgentMessage): number {
+		let tokens = 0;
+		for (const llmMessage of convertToLlm([message])) {
+			tokens += estimateMessageTokensHeuristic(llmMessage);
+		}
+		return tokens;
+	}
+
+	#estimateMessageNativeContextTokens(message: AgentMessage): number {
+		let tokens = 0;
+		for (const llmMessage of convertToLlm([message])) {
+			tokens += estimateTokens(llmMessage);
+		}
+		return tokens;
+	}
+
 	/**
 	 * Export session to HTML.
 	 * @param outputPath Optional output path (defaults to session directory)
@@ -9768,3 +9918,7 @@ export class AgentSession {
 		return this.#extensionRunner;
 	}
 }
+
+function cloneJsonValueForForkSeed<T>(value: T): T {
+	return JSON.parse(JSON.stringify(value)) as T;
+}

package/src/session/blob-store.ts

@@ -95,6 +95,77 @@ export class BlobStore {
 	}
 }
 
+export class EphemeralBlobStore extends BlobStore {
+	/**
+	 * Bounded LRU byte budget for the in-memory buffer cache. Keeps recent
+	 * resident blobs hot for rematerialization after the weak materialized
+	 * view is collected, without re-pinning the whole session in RAM.
+	 */
+	static readonly #BUFFER_CACHE_MAX_BYTES = 8 * 1024 * 1024;
+
+	#bufferCache = new Map<string, Buffer>();
+	#bufferCacheBytes = 0;
+
+	constructor(dir: string) {
+		super(dir);
+		fs.rmSync(dir, { recursive: true, force: true });
+		fs.mkdirSync(dir, { recursive: true });
+	}
+
+	#cachePut(hash: string, data: Buffer): void {
+		const existing = this.#bufferCache.get(hash);
+		if (existing) {
+			this.#bufferCache.delete(hash);
+			this.#bufferCacheBytes -= existing.byteLength;
+		}
+		if (data.byteLength > EphemeralBlobStore.#BUFFER_CACHE_MAX_BYTES) return;
+		this.#bufferCache.set(hash, data);
+		this.#bufferCacheBytes += data.byteLength;
+		for (const [oldHash, oldData] of this.#bufferCache) {
+			if (this.#bufferCacheBytes <= EphemeralBlobStore.#BUFFER_CACHE_MAX_BYTES) break;
+			this.#bufferCache.delete(oldHash);
+			this.#bufferCacheBytes -= oldData.byteLength;
+		}
+	}
+
+	putSync(data: Buffer): BlobPutResult {
+		const result = super.putSync(data);
+		this.#cachePut(result.hash, Buffer.from(data));
+		return result;
+	}
+
+	getSync(hash: string): Buffer | null {
+		const cached = this.#bufferCache.get(hash);
+		if (cached) {
+			const blobPath = path.join(this.dir, hash);
+			if (fs.existsSync(blobPath)) {
+				// Refresh LRU recency on hit.
+				this.#bufferCache.delete(hash);
+				this.#bufferCache.set(hash, cached);
+				return Buffer.from(cached);
+			}
+			this.#bufferCache.delete(hash);
+			this.#bufferCacheBytes -= cached.byteLength;
+		}
+		const data = super.getSync(hash);
+		if (data) this.#cachePut(hash, Buffer.from(data));
+		return data;
+	}
+
+	clear(): void {
+		this.#bufferCache.clear();
+		this.#bufferCacheBytes = 0;
+		fs.rmSync(this.dir, { recursive: true, force: true });
+		fs.mkdirSync(this.dir, { recursive: true });
+	}
+
+	dispose(): void {
+		this.#bufferCache.clear();
+		this.#bufferCacheBytes = 0;
+		fs.rmSync(this.dir, { recursive: true, force: true });
+	}
+}
+
 export class MemoryBlobStore extends BlobStore {
 	#blobs = new Map<string, Buffer>();
 
@@ -132,6 +203,18 @@ export class MemoryBlobStore extends BlobStore {
 	}
 }
 
+export class ResidentBlobMissingError extends Error {
+	constructor(
+		readonly hash: string,
+		readonly kind: "text" | "imageUrl" | "imageData",
+		readonly sessionId?: string,
+		readonly sessionFile?: string,
+	) {
+		super(`Missing resident ${kind} blob: ${hash}`);
+		this.name = "ResidentBlobMissingError";
+	}
+}
+
 /** Check if a data string is a blob reference. */
 export function isBlobRef(data: string): boolean {
 	return data.startsWith(BLOB_PREFIX);
@@ -184,7 +267,13 @@ export function externalizeImageDataSync(blobStore: BlobStore, base64Data: strin
 /**
  * Resolve an externalized provider image data URL back to its original string.
  * If the data is not a blob reference, returns it unchanged.
- * If the blob is missing, logs a warning and returns the reference as-is.
+ *
+ * LEGACY PERSISTED-IMAGE COMPATIBILITY BOUNDARY: when the persisted blob is missing
+ * (e.g. resuming an old session whose image blob was pruned), this warns and returns
+ * the reference as-is rather than throwing, so legacy resume degrades gracefully.
+ * New resident byte-sensitive TEXT uses the fail-closed path instead
+ * (`resolveTextBlobSync` -> `ResidentBlobMissingError`). Do NOT route new byte-sensitive
+ * resident data through this warn-and-return path.
  */
 export async function resolveImageDataUrl(blobStore: BlobStore, data: string): Promise<string> {
 	const hash = parseBlobRef(data);
@@ -201,7 +290,11 @@ export async function resolveImageDataUrl(blobStore: BlobStore, data: string): P
 /**
  * Resolve a blob reference back to base64 data.
  * If the data is not a blob reference, returns it unchanged.
- * If the blob is missing, logs a warning and returns a placeholder.
+ *
+ * LEGACY PERSISTED-IMAGE COMPATIBILITY BOUNDARY: when the blob is missing this warns
+ * and returns the reference as-is (downstream sees an invalid base64 ref but does not
+ * crash), preserving legacy-session resume. Byte-sensitive resident TEXT is fail-closed
+ * via `resolveTextBlobSync`; do NOT route new byte-sensitive resident data here.
  */
 export async function resolveImageData(blobStore: BlobStore, data: string): Promise<string> {
 	const hash = parseBlobRef(data);
@@ -239,14 +332,63 @@ export function resolveImageDataSync(blobStore: BlobStore, data: string): string
 	return buffer.toString("base64");
 }
 
-/** Synchronously resolve a blob reference back to utf8 text. */
-export function resolveTextBlobSync(blobStore: BlobStore, data: string): string {
+/**
+ * Synchronously resolve a blob reference back to utf8 text.
+ *
+ * FAIL-CLOSED byte-sensitive path: a missing resident blob throws
+ * `ResidentBlobMissingError` rather than degrading, so a missing resident text blob can
+ * never silently leak a `blob:sha256:` ref into provider payloads, UI, or exports.
+ * (Contrast the legacy persisted-image warn-and-return resolvers above.)
+ */
+export function resolveTextBlobSync(
+	blobStore: BlobStore,
+	data: string,
+	context?: { kind?: "text"; sessionId?: string; sessionFile?: string },
+): string {
 	const hash = parseBlobRef(data);
 	if (!hash) return data;
 	const buffer = blobStore.getSync(hash);
 	if (!buffer) {
-		logger.warn("Blob not found for text reference", { hash });
-		return data;
+		throw new ResidentBlobMissingError(hash, context?.kind ?? "text", context?.sessionId, context?.sessionFile);
 	}
 	return buffer.toString("utf8");
 }
+
+/**
+ * FAIL-CLOSED resident variant of {@link resolveImageDataUrlSync}: a missing resident
+ * image-data-url blob throws `ResidentBlobMissingError` ("imageUrl") instead of warn-returning,
+ * so resident byte-sensitive provider image data can never leak a `blob:sha256:` ref into
+ * materialized entries, context, or provider payloads. The warn-and-return `resolveImageDataUrl*`
+ * resolvers remain ONLY for legacy persisted-image resume.
+ */
+export function resolveResidentImageDataUrlSync(
+	blobStore: BlobStore,
+	data: string,
+	context?: { sessionId?: string; sessionFile?: string },
+): string {
+	const hash = parseBlobRef(data);
+	if (!hash) return data;
+	const buffer = blobStore.getSync(hash);
+	if (!buffer) {
+		throw new ResidentBlobMissingError(hash, "imageUrl", context?.sessionId, context?.sessionFile);
+	}
+	return buffer.toString("utf8");
+}
+
+/**
+ * FAIL-CLOSED resident variant of {@link resolveImageDataSync}: a missing resident image blob
+ * throws `ResidentBlobMissingError` ("imageData") instead of warn-returning a placeholder.
+ */
+export function resolveResidentImageDataSync(
+	blobStore: BlobStore,
+	data: string,
+	context?: { sessionId?: string; sessionFile?: string },
+): string {
+	const hash = parseBlobRef(data);
+	if (!hash) return data;
+	const buffer = blobStore.getSync(hash);
+	if (!buffer) {
+		throw new ResidentBlobMissingError(hash, "imageData", context?.sessionId, context?.sessionFile);
+	}
+	return buffer.toString("base64");
+}