@gajae-code/coding-agent 0.7.2 → 0.7.4

package/src/session/agent-session.ts

@@ -50,7 +50,11 @@ import {
 	type SummaryOptions,
 	shouldCompact,
 } from "@gajae-code/agent-core/compaction";
-import { DEFAULT_PRUNE_CONFIG, pruneToolOutputs } from "@gajae-code/agent-core/compaction/pruning";
+import {
+	DEFAULT_PRUNE_CONFIG,
+	pruneAssistantToolArguments,
+	pruneToolOutputs,
+} from "@gajae-code/agent-core/compaction/pruning";
 import type {
 	AssistantMessage,
 	Context,
@@ -127,7 +131,7 @@ import {
 import { type AsyncJob, type AsyncJobDeliveryState, AsyncJobManager } from "../async";
 import { reset as resetCapabilities } from "../capability";
 import type { Rule } from "../capability/rule";
-import { MODEL_ROLE_IDS, type ModelRegistry } from "../config/model-registry";
+import { GJC_MODEL_ASSIGNMENT_TARGETS, MODEL_ROLE_IDS, type ModelRegistry } from "../config/model-registry";
 import {
 	extractExplicitThinkingSelector,
 	formatModelSelectorValue,
@@ -421,6 +425,13 @@ export interface AgentSessionConfig {
 	 * **MUST NOT** dispose it on their own teardown.
 	 */
 	ownedAsyncJobManager?: AsyncJobManager;
+	/**
+	 * MCPManager whose lifecycle this session owns (top-level sessions that
+	 * connected plugin-bundle MCP servers). Only the owned manager is
+	 * disconnected on dispose; subagents and callers that merely observe the
+	 * process-global manager **MUST NOT** dispose it on their own teardown.
+	 */
+	ownedMcpManager?: MCPManager;
 	/** Optional fork-context seed used to initialize a child session before its first prompt. */
 	forkContextSeed?: ForkContextSeed;
 	/** Optional provider state override. Fork-context children should omit this by default. */
@@ -958,6 +969,7 @@ export class AgentSession {
 	 * this undefined and **MUST NOT** dispose the global instance on teardown.
 	 */
 	readonly #ownedAsyncJobManager: AsyncJobManager | undefined;
+	readonly #ownedMcpManager: MCPManager | undefined;
 	#pendingPythonMessages: PythonExecutionMessage[] = [];
 	#activeEvalExecutions = new Set<Promise<unknown>>();
 	#evalExecutionDisposing = false;
@@ -1087,6 +1099,16 @@ export class AgentSession {
 	#lastSuccessfulYieldToolCallId: string | undefined = undefined;
 	#promptGeneration = 0;
 	#providerSessionState = new Map<string, ProviderSessionState>();
+	/**
+	 * Provider keys for which the Anthropic fast-mode auto-fallback fired this
+	 * session (the provider rejected `speed:"fast"` and we retried without it).
+	 * Provider/API-session scoped — matching the provider's own per-session
+	 * `fastModeDisabled` flag — NOT model-keyed. Transient (never persisted): it
+	 * suppresses the current-model fast indicator and dedups the one-time warning
+	 * WITHOUT mutating the user's intended `serviceTier`, so task subagents still
+	 * inherit the intended tier and a different provider still shows fast.
+	 */
+	#fastModeAutoDisabledProviderKeys = new Set<string>();
 	#hindsightSessionState: HindsightSessionState | undefined = undefined;
 	readonly rawSseDebugBuffer: RawSseDebugBuffer;
 
@@ -1161,6 +1183,7 @@ export class AgentSession {
 		// Power assertions are taken per turn (see #beginInFlight); nothing acquired here.
 		this.#evalKernelOwnerId = config.evalKernelOwnerId ?? `agent-session:${Snowflake.next()}`;
 		this.#ownedAsyncJobManager = config.ownedAsyncJobManager;
+		this.#ownedMcpManager = config.ownedMcpManager;
 		this.#scopedModels = config.scopedModels ?? [];
 		this.#thinkingLevel = config.thinkingLevel;
 		this.#promptTemplates = config.promptTemplates ?? [];
@@ -1976,12 +1999,18 @@ export class AgentSession {
 				const currentGrantsAnthropicPriority =
 					this.serviceTier === "priority" || this.serviceTier === "claude-only";
 				if (assistantMsg.disabledFeatures?.includes("priority") && currentGrantsAnthropicPriority) {
-					this.setServiceTier(undefined);
-					this.emitNotice(
-						"warning",
-						"Priority/fast mode rejected for this model; retried without it. Fast mode is now off.",
-						"priority",
-					);
+					// The provider auto-dropped `speed:"fast"` for the current model's
+					// provider this turn. Record a transient, provider-scoped marker
+					// instead of clearing the user's intended tier, so task subagents
+					// still inherit it and a different provider still gets fast mode.
+					// Warn once per provider until the user re-arms with `/fast on`.
+					if (this.#markFastModeAutoDisabledForCurrentModel()) {
+						this.emitNotice(
+							"warning",
+							"Priority/fast mode rejected for this model; retried without it. Fast mode is off for this model until you re-enable it with /fast on.",
+							"priority",
+						);
+					}
 				}
 				// Resolve TTSR resume gate before checking for new deferred injections.
 				// Gate on #ttsrAbortPending, not stopReason: a non-TTSR abort (e.g. streaming
@@ -3240,10 +3269,14 @@ export class AgentSession {
 				AsyncJobManager.setInstance(undefined);
 			}
 		}
-		const mcpManager = MCPManager.instance();
-		if (mcpManager) {
-			await mcpManager.disconnectAll();
-			if (MCPManager.instance() === mcpManager) {
+		// Only disconnect the MCP manager THIS session owns (top-level sessions that
+		// connected plugin-bundle MCP servers). Subagents and callers that merely
+		// observe the process-global manager must never tear down a manager they do
+		// not own. Mirrors the ownedAsyncJobManager rule above.
+		const ownedMcpManager = this.#ownedMcpManager;
+		if (ownedMcpManager) {
+			await ownedMcpManager.disconnectAll();
+			if (MCPManager.instance() === ownedMcpManager) {
 				MCPManager.setInstance(undefined);
 			}
 		}
@@ -5604,7 +5637,7 @@ export class AgentSession {
 	}
 
 	#syncTodoPhasesFromBranch(): void {
-		const phases = getLatestTodoPhasesFromEntries(this.sessionManager.getBranch());
+		const phases = getLatestTodoPhasesFromEntries(this.sessionManager.getActivePathEntriesCanonical());
 		// Strip completed/abandoned tasks — they were done in a previous run,
 		// so they have no bearing on progress tracking for the new turn.
 		for (const phase of phases) {
@@ -5613,6 +5646,42 @@ export class AgentSession {
 		this.setTodoPhases(phases.filter(p => p.tasks.length > 0));
 	}
 
+	async #applyCompactionPostAppend(
+		compactionEntryId: string,
+		firstKeptEntryId: string,
+		fromExtension?: boolean,
+	): Promise<CompactionEntry | undefined> {
+		const eviction = this.sessionManager.evictCompactedContent(firstKeptEntryId, compactionEntryId);
+		if (eviction.evictedEntries > 0) await this.sessionManager.rewriteEntries();
+		const sessionContext = this.buildDisplaySessionContext();
+		this.agent.replaceMessages(sessionContext.messages);
+		this.#syncTodoPhasesFromBranch();
+		this.#closeCodexProviderSessionsForHistoryRewrite();
+
+		// Get the saved compaction entry for the hook without materializing all entries.
+		const savedCompactionEntry = this.sessionManager.getEntryForFidelity(compactionEntryId) as
+			| CompactionEntry
+			| undefined;
+
+		if (this.#extensionRunner && savedCompactionEntry) {
+			await this.#extensionRunner.emit({
+				type: "session_compact",
+				compactionEntry: savedCompactionEntry,
+				fromExtension: fromExtension ?? false,
+			});
+		}
+
+		return savedCompactionEntry;
+	}
+
+	async applyCompactionPostAppendForTests(
+		compactionEntryId: string,
+		firstKeptEntryId: string,
+		fromExtension?: boolean,
+	): Promise<CompactionEntry | undefined> {
+		return this.#applyCompactionPostAppend(compactionEntryId, firstKeptEntryId, fromExtension);
+	}
+
 	#cloneTodoPhases(phases: TodoPhase[]): TodoPhase[] {
 		return phases.map(phase => ({
 			name: phase.name,
@@ -6242,33 +6311,81 @@ export class AgentSession {
 		return resolveServiceTier(this.#subagentServiceTier(), provider) === "priority";
 	}
 
+	/**
+	 * Provider/API-session key used to scope the fast-mode auto-disable marker.
+	 * Mirrors the provider's own per-session `fastModeDisabled` scope (the key in
+	 * {@link #providerSessionState} cleared by `clearAnthropicFastModeFallback`),
+	 * so the marker is provider-scoped, never model-keyed. Returns `undefined`
+	 * when no model/provider is selected.
+	 */
+	#fastModeProviderKey(provider: string | undefined = this.model?.provider): string | undefined {
+		return provider;
+	}
+
+	/**
+	 * Record that the current model's provider had fast mode auto-dropped this
+	 * session. Returns `true` only when the provider key is newly marked, so the
+	 * caller emits the one-time warning exactly once per provider until re-arm.
+	 */
+	#markFastModeAutoDisabledForCurrentModel(): boolean {
+		const key = this.#fastModeProviderKey();
+		if (key === undefined) return false;
+		if (this.#fastModeAutoDisabledProviderKeys.has(key)) return false;
+		this.#fastModeAutoDisabledProviderKeys.add(key);
+		return true;
+	}
+
+	/** True when `provider`'s fast mode was auto-disabled this session. */
+	#isFastModeAutoDisabledForProvider(provider?: string): boolean {
+		const key = this.#fastModeProviderKey(provider);
+		return key !== undefined && this.#fastModeAutoDisabledProviderKeys.has(key);
+	}
+
+	/**
+	 * Re-arm fast mode after an auto-disable: clear the provider's sticky
+	 * `fastModeDisabled` fallback flag and the session auto-disable markers so the
+	 * next request carries `speed:"fast"` again and a future rejection can warn
+	 * once more. Called on explicit re-enable (`/fast on`, re-arming tier change),
+	 * never by the transient Q1 auto-disable path.
+	 */
+	#rearmFastMode(): void {
+		clearAnthropicFastModeFallback(this.#providerSessionState);
+		this.#fastModeAutoDisabledProviderKeys.clear();
+	}
+
 	/**
 	 * True when the configured `serviceTier` resolves to `"priority"` for the
-	 * *currently selected model's provider*. Returns false for scoped tiers
-	 * that don't match (e.g. `"openai-only"` on an anthropic model) and when
-	 * no model is selected.
+	 * *currently selected model's provider* AND fast mode was not auto-disabled
+	 * for that provider this session. This is the current-model EFFECTIVE
+	 * predicate (what the next request actually does); use {@link isFastForProvider}
+	 * for pure configured intent (e.g. subagent/`modelRoles` display rows).
 	 */
 	isFastModeActive(): boolean {
-		return this.isFastForProvider(this.model?.provider);
+		const provider = this.model?.provider;
+		return this.isFastForProvider(provider) && !this.#isFastModeAutoDisabledForProvider(provider);
 	}
 
 	setServiceTier(serviceTier: ServiceTier | undefined): void {
-		if (this.serviceTier === serviceTier) return;
-		// Re-arming priority on Anthropic? Clear the per-session auto-fallback
-		// sticky disable so the next request actually carries `speed: "fast"`
-		// again. Without this, `/fast on` (or user switching to a tier that
-		// grants anthropic priority) after an auto-disable is a silent no-op
-		// and the warning notice fires every turn.
+		// Re-arming a priority-granting tier always clears the per-session
+		// auto-fallback sticky disable AND the auto-disable markers so the next
+		// request carries `speed: "fast"` again — even when the tier is unchanged
+		// (re-selecting the same tier is a deliberate re-arm), and before the
+		// no-op early-return below.
 		if (serviceTier === "priority" || serviceTier === "claude-only") {
-			clearAnthropicFastModeFallback(this.#providerSessionState);
+			this.#rearmFastMode();
 		}
+		if (this.serviceTier === serviceTier) return;
 		this.agent.serviceTier = serviceTier;
 		this.sessionManager.appendServiceTierChange(serviceTier ?? null);
 	}
 
 	setFastMode(enabled: boolean): void {
 		if (enabled && this.isFastModeEnabled()) {
-			// Already on under any scope — keep the user's scoped value.
+			// Intent already grants fast mode under some scope — keep the user's
+			// scoped value but still re-arm, so an explicit `/fast on` after a
+			// provider auto-disable actually clears the sticky fallback + markers
+			// (otherwise it is a silent no-op). No history append: intent is unchanged.
+			this.#rearmFastMode();
 			return;
 		}
 		this.setServiceTier(enabled ? "priority" : undefined);
@@ -6326,19 +6443,23 @@ export class AgentSession {
 	async #pruneToolOutputs(): Promise<{ prunedCount: number; tokensSaved: number } | undefined> {
 		const branchEntries = this.sessionManager.getBranch();
 		const result = pruneToolOutputs(branchEntries, DEFAULT_PRUNE_CONFIG);
-		if (result.prunedCount === 0) {
+		const argumentResult = pruneAssistantToolArguments(branchEntries, DEFAULT_PRUNE_CONFIG);
+		const tokensSaved = result.tokensSaved + argumentResult.argumentTokensSaved;
+		const prunedCount = result.prunedCount + argumentResult.argumentPrunedCount;
+		if (prunedCount === 0) {
 			return undefined;
 		}
 
 		// getBranch() returns materialized copies for blob-externalized entries, so
 		// the pruning mutations must be written back into the canonical store.
-		this.sessionManager.applyEntryMessageUpdates(result.prunedEntries);
+		const combined = [...result.prunedEntries, ...argumentResult.prunedEntries];
+		this.sessionManager.applyEntryMessageUpdates(combined);
 		await this.sessionManager.rewriteEntries();
 		const sessionContext = this.buildDisplaySessionContext();
 		this.agent.replaceMessages(sessionContext.messages);
 		this.#syncTodoPhasesFromBranch();
 		this.#closeCodexProviderSessionsForHistoryRewrite();
-		return result;
+		return { prunedCount, tokensSaved };
 	}
 
 	/**
@@ -6456,7 +6577,7 @@ export class AgentSession {
 				throw new CompactionCancelledError();
 			}
 
-			this.sessionManager.appendCompaction(
+			const compactionEntryId = this.sessionManager.appendCompaction(
 				summary,
 				shortSummary,
 				firstKeptEntryId,
@@ -6465,24 +6586,7 @@ export class AgentSession {
 				fromExtension,
 				preserveData,
 			);
-			const newEntries = this.sessionManager.getEntries();
-			const sessionContext = this.buildDisplaySessionContext();
-			this.agent.replaceMessages(sessionContext.messages);
-			this.#syncTodoPhasesFromBranch();
-			this.#closeCodexProviderSessionsForHistoryRewrite();
-
-			// Get the saved compaction entry for the hook
-			const savedCompactionEntry = newEntries.find(e => e.type === "compaction" && e.summary === summary) as
-				| CompactionEntry
-				| undefined;
-
-			if (this.#extensionRunner && savedCompactionEntry) {
-				await this.#extensionRunner.emit({
-					type: "session_compact",
-					compactionEntry: savedCompactionEntry,
-					fromExtension,
-				});
-			}
+			await this.#applyCompactionPostAppend(compactionEntryId, firstKeptEntryId, fromExtension);
 
 			const compactionResult: CompactionResult = {
 				summary,
@@ -7480,11 +7584,14 @@ export class AgentSession {
 		availableModels: Model[],
 		currentModel: Model | undefined,
 	): ResolvedModelRoleValue {
+		const target = GJC_MODEL_ASSIGNMENT_TARGETS[role as keyof typeof GJC_MODEL_ASSIGNMENT_TARGETS];
 		const roleModelStr =
-			role === "default"
-				? (this.settings.getModelRole("default") ??
-					(currentModel ? `${currentModel.provider}/${currentModel.id}` : undefined))
-				: this.settings.getModelRole(role);
+			target?.settingsPath === "task.agentModelOverrides"
+				? this.settings.get("task.agentModelOverrides")[role]
+				: role === "default"
+					? (this.settings.getModelRole("default") ??
+						(currentModel ? `${currentModel.provider}/${currentModel.id}` : undefined))
+					: this.settings.getModelRole(role);
 
 		if (!roleModelStr) {
 			return { model: undefined, thinkingLevel: undefined, explicitThinkingLevel: false, warning: undefined };
@@ -7969,7 +8076,7 @@ export class AgentSession {
 				return;
 			}
 
-			this.sessionManager.appendCompaction(
+			const compactionEntryId = this.sessionManager.appendCompaction(
 				summary,
 				shortSummary,
 				firstKeptEntryId,
@@ -7978,24 +8085,7 @@ export class AgentSession {
 				fromExtension,
 				preserveData,
 			);
-			const newEntries = this.sessionManager.getEntries();
-			const sessionContext = this.buildDisplaySessionContext();
-			this.agent.replaceMessages(sessionContext.messages);
-			this.#syncTodoPhasesFromBranch();
-			this.#closeCodexProviderSessionsForHistoryRewrite();
-
-			// Get the saved compaction entry for the hook
-			const savedCompactionEntry = newEntries.find(e => e.type === "compaction" && e.summary === summary) as
-				| CompactionEntry
-				| undefined;
-
-			if (this.#extensionRunner && savedCompactionEntry) {
-				await this.#extensionRunner.emit({
-					type: "session_compact",
-					compactionEntry: savedCompactionEntry,
-					fromExtension,
-				});
-			}
+			await this.#applyCompactionPostAppend(compactionEntryId, firstKeptEntryId, fromExtension);
 
 			const result: CompactionResult = {
 				summary,
@@ -9613,7 +9703,7 @@ export class AgentSession {
 		cancelled: boolean;
 	}> {
 		const previousSessionFile = this.sessionFile;
-		const selectedEntry = this.sessionManager.getEntry(entryId);
+		const selectedEntry = this.sessionManager.getEntryForFidelity(entryId);
 
 		if (selectedEntry?.type !== "message" || selectedEntry.message.role !== "user") {
 			throw new Error("Invalid entry ID for branching");
@@ -9711,7 +9801,7 @@ export class AgentSession {
 			throw new Error("No model available for summarization");
 		}
 
-		const targetEntry = this.sessionManager.getEntry(targetId);
+		const targetEntry = this.sessionManager.getEntryForFidelity(targetId);
 		if (!targetEntry) {
 			throw new Error(`Entry ${targetId} not found`);
 		}
@@ -9867,9 +9957,11 @@ export class AgentSession {
 
 		for (const entry of entries) {
 			if (entry.type !== "message") continue;
-			if (entry.message.role !== "user") continue;
+			const fidelityEntry = this.sessionManager.getEntryForFidelity(entry.id);
+			if (fidelityEntry?.type !== "message") continue;
+			if (fidelityEntry.message.role !== "user") continue;
 
-			const text = this.#extractUserMessageText(entry.message.content);
+			const text = this.#extractUserMessageText(fidelityEntry.message.content);
 			if (text) {
 				result.push({ entryId: entry.id, text });
 			}

package/src/session/blob-store.ts

@@ -11,6 +11,82 @@ export interface BlobPutResult {
 	get ref(): string;
 }
 
+export interface CheckedBlobPutResult extends BlobPutResult {
+	bytes: number;
+}
+
+export class BlobCorruptError extends Error {
+	constructor(
+		readonly hash: string,
+		readonly path: string,
+	) {
+		super(`Blob ${hash} at ${path} failed SHA-256 verification`);
+		this.name = "BlobCorruptError";
+	}
+}
+
+function sha256Hex(data: Buffer): string {
+	return new Bun.SHA256().update(data).digest("hex");
+}
+
+function makeBlobPutResult(hash: string, blobPath: string): BlobPutResult;
+function makeBlobPutResult(hash: string, blobPath: string, bytes: number): CheckedBlobPutResult;
+function makeBlobPutResult(hash: string, blobPath: string, bytes?: number): BlobPutResult | CheckedBlobPutResult {
+	const result = {
+		hash,
+		path: blobPath,
+		get ref() {
+			return `${BLOB_PREFIX}${hash}`;
+		},
+	};
+	if (bytes === undefined) return result;
+	return { ...result, bytes };
+}
+
+function fsyncDirBestEffortSync(dir: string): void {
+	let fd: number | null = null;
+	try {
+		fd = fs.openSync(dir, "r");
+		fs.fsyncSync(fd);
+	} catch {
+		// Best-effort only: some platforms/filesystems do not support fsync on directories.
+	} finally {
+		if (fd !== null) fs.closeSync(fd);
+	}
+}
+
+/**
+ * Best-effort fsync of an installed blob file. Used on install paths that
+ * create the destination by copy (not hard-link from an already-fsynced temp),
+ * so the durable-install contract holds there too. Failures are best-effort:
+ * some platforms/filesystems reject fsync on read-only handles.
+ */
+function fsyncFileBestEffortSync(filePath: string): void {
+	let fd: number | null = null;
+	try {
+		fd = fs.openSync(filePath, "r");
+		fs.fsyncSync(fd);
+	} catch {
+		// Best-effort only.
+	} finally {
+		if (fd !== null) fs.closeSync(fd);
+	}
+}
+
+function uniqueTempBlobPath(dir: string, hash: string): string {
+	return path.join(dir, `${hash}.tmp.${process.pid}.${Date.now()}.${Math.random().toString(16).slice(2)}`);
+}
+
+function verifyBlobBytesSync(hash: string, blobPath: string, data: Buffer): void {
+	if (sha256Hex(data) !== hash) throw new BlobCorruptError(hash, blobPath);
+}
+
+function verifyBlobFileSync(hash: string, blobPath: string): Buffer {
+	const data = fs.readFileSync(blobPath);
+	verifyBlobBytesSync(hash, blobPath, data);
+	return data;
+}
+
 /**
  * Content-addressed blob store for externalizing large binary data (images) from session JSONL files.
  *
@@ -60,6 +136,79 @@ export class BlobStore {
 		return result;
 	}
 
+	/**
+	 * Durably install binary data as an immutable content-addressed blob.
+	 *
+	 * Callers that persist references to this blob must mutate canonical session entries only
+	 * after this method returns successfully. A corrupt pre-existing target is reported with
+	 * {@link BlobCorruptError}; it is never silently overwritten or trusted.
+	 */
+	putImmutableSync(data: Buffer): CheckedBlobPutResult {
+		const hash = sha256Hex(data);
+		const blobPath = path.join(this.dir, hash);
+		const result = makeBlobPutResult(hash, blobPath, data.byteLength);
+		fs.mkdirSync(this.dir, { recursive: true });
+
+		if (fs.existsSync(blobPath)) {
+			verifyBlobFileSync(hash, blobPath);
+			return result;
+		}
+
+		const tempPath = uniqueTempBlobPath(this.dir, hash);
+		try {
+			const fd = fs.openSync(tempPath, "wx");
+			try {
+				fs.writeFileSync(fd, data);
+				fs.fsyncSync(fd);
+			} finally {
+				fs.closeSync(fd);
+			}
+
+			try {
+				fs.linkSync(tempPath, blobPath);
+			} catch (err) {
+				if (isEnoent(err)) throw err;
+				const code = typeof err === "object" && err !== null && "code" in err ? err.code : undefined;
+				if (code === "EEXIST") {
+					verifyBlobFileSync(hash, blobPath);
+					return result;
+				}
+				if (code === "EPERM" || code === "ENOTSUP" || code === "EOPNOTSUPP") {
+					// Hard links unsupported (e.g. cross-device / some network FS). Use an
+					// EXCLUSIVE copy so a concurrently installed winner is never overwritten;
+					// verify it by hash on EEXIST instead of clobbering it.
+					try {
+						fs.copyFileSync(tempPath, blobPath, fs.constants.COPYFILE_EXCL);
+						// The temp was fsync'd before install, but copyFileSync creates a
+						// fresh destination whose bytes are not yet durable — fsync it so the
+						// durable-install contract holds on hard-link-unsupported paths too.
+						fsyncFileBestEffortSync(blobPath);
+					} catch (copyErr) {
+						const copyCode =
+							typeof copyErr === "object" && copyErr !== null && "code" in copyErr ? copyErr.code : undefined;
+						if (copyCode === "EEXIST") {
+							verifyBlobFileSync(hash, blobPath);
+							return result;
+						}
+						throw copyErr;
+					}
+				} else {
+					throw err;
+				}
+			}
+
+			verifyBlobFileSync(hash, blobPath);
+			fsyncDirBestEffortSync(this.dir);
+			return result;
+		} finally {
+			try {
+				fs.unlinkSync(tempPath);
+			} catch {
+				// Best-effort temp cleanup: never mask the primary result or throw.
+			}
+		}
+	}
+
 	/** Read blob by hash, returns Buffer or null if not found. */
 	async get(hash: string): Promise<Buffer | null> {
 		const blobPath = path.join(this.dir, hash);
@@ -84,6 +233,22 @@ export class BlobStore {
 		}
 	}
 
+	/** Read blob by hash and verify its content hash; returns null if not found. */
+	async getChecked(hash: string): Promise<Buffer | null> {
+		return this.getCheckedSync(hash);
+	}
+
+	/** Synchronously read blob by hash and verify its content hash; returns null if not found. */
+	getCheckedSync(hash: string): Buffer | null {
+		const blobPath = path.join(this.dir, hash);
+		try {
+			return verifyBlobFileSync(hash, blobPath);
+		} catch (err) {
+			if (isEnoent(err)) return null;
+			throw err;
+		}
+	}
+
 	/** Check if a blob exists. */
 	async has(hash: string): Promise<boolean> {
 		try {
@@ -134,6 +299,12 @@ export class EphemeralBlobStore extends BlobStore {
 		return result;
 	}
 
+	putImmutableSync(data: Buffer): CheckedBlobPutResult {
+		const result = super.putImmutableSync(data);
+		this.#cachePut(result.hash, Buffer.from(data));
+		return result;
+	}
+
 	getSync(hash: string): Buffer | null {
 		const cached = this.#bufferCache.get(hash);
 		if (cached) {
@@ -152,6 +323,12 @@ export class EphemeralBlobStore extends BlobStore {
 		return data;
 	}
 
+	getCheckedSync(hash: string): Buffer | null {
+		const data = super.getCheckedSync(hash);
+		if (data) this.#cachePut(hash, Buffer.from(data));
+		return data;
+	}
+
 	clear(): void {
 		this.#bufferCache.clear();
 		this.#bufferCacheBytes = 0;
@@ -208,15 +385,15 @@ export class MemoryBlobStore extends BlobStore {
 	}
 
 	putSync(data: Buffer): BlobPutResult {
-		const hash = new Bun.SHA256().update(data).digest("hex");
+		const hash = sha256Hex(data);
 		this.#store(hash, Buffer.from(data));
-		return {
-			hash,
-			path: `memory:${hash}`,
-			get ref() {
-				return `${BLOB_PREFIX}${hash}`;
-			},
-		};
+		return makeBlobPutResult(hash, `memory:${hash}`);
+	}
+
+	putImmutableSync(data: Buffer): CheckedBlobPutResult {
+		const hash = sha256Hex(data);
+		this.#store(hash, Buffer.from(data));
+		return makeBlobPutResult(hash, `memory:${hash}`, data.byteLength);
 	}
 
 	async get(hash: string): Promise<Buffer | null> {
@@ -232,6 +409,17 @@ export class MemoryBlobStore extends BlobStore {
 		return Buffer.from(data);
 	}
 
+	async getChecked(hash: string): Promise<Buffer | null> {
+		return this.getCheckedSync(hash);
+	}
+
+	getCheckedSync(hash: string): Buffer | null {
+		const data = this.getSync(hash);
+		if (!data) return null;
+		verifyBlobBytesSync(hash, `memory:${hash}`, data);
+		return data;
+	}
+
 	async has(hash: string): Promise<boolean> {
 		return this.#blobs.has(hash);
 	}