@gajae-code/coding-agent 0.12.4 → 0.12.6

package/src/tools/output-meta.ts

@@ -15,19 +15,80 @@ import type { ImageContent, TextContent } from "@gajae-code/ai";
 import { getDefault, type Settings } from "../config/settings";
 import { formatGroupedDiagnosticMessages } from "../lsp/utils";
 import type { Theme } from "../modes/theme/theme";
-import { sessionArtifactCapability } from "../session/session-manager";
+import { type SessionArtifactCapability, sessionArtifactCapability } from "../session/session-manager";
 import {
+	DEFAULT_ARTIFACT_MAX_BYTES,
 	formatMiddleElisionMarker,
+	hasCurrentExecutionArtifactProof,
 	type OutputSummary,
 	type ReadWindow,
 	type TruncationResult,
+	truncateHeadBytes,
 	truncateMiddle,
 	truncateTail,
 } from "../session/streaming-output";
+import { isValidArtifactId } from "../utils/artifact-id";
+
+export { isValidArtifactId } from "../utils/artifact-id";
 
 import { formatBytes, wrapBrackets } from "./render-utils";
 import { renderError } from "./tool-errors";
 
+const kCurrentExecutionArtifactProof = Symbol("OutputMeta.CurrentExecutionArtifactProof");
+const pendingArtifactLookupsByOwner = new WeakMap<SessionArtifactCapability, Set<Promise<boolean>>>();
+
+function bindCurrentExecutionArtifactProof(truncation: TruncationMeta, summary: OutputSummary): void {
+	const artifactId = truncation.artifactId;
+	if (!artifactId || !hasCurrentExecutionArtifactProof(summary, artifactId, summary.output)) return;
+	Object.defineProperty(truncation, kCurrentExecutionArtifactProof, {
+		value: { artifactId, payload: summary.output, consumed: false },
+		enumerable: false,
+		configurable: false,
+		writable: false,
+	});
+}
+
+function hasBoundCurrentExecutionArtifactProof(
+	truncation: TruncationMeta,
+	artifactId: string,
+	payload: string,
+): boolean {
+	const proof = (
+		truncation as TruncationMeta & {
+			[kCurrentExecutionArtifactProof]?: { artifactId: string; payload: string; consumed: boolean };
+		}
+	)[kCurrentExecutionArtifactProof];
+	if (!proof || proof.artifactId !== artifactId || proof.payload !== payload || proof.consumed) return false;
+	proof.consumed = true;
+	return true;
+}
+
+function pendingArtifactLookupsForOwner(capability: SessionArtifactCapability): Set<Promise<boolean>> {
+	let pending = pendingArtifactLookupsByOwner.get(capability);
+	if (!pending) {
+		pending = new Set();
+		pendingArtifactLookupsByOwner.set(capability, pending);
+	}
+	return pending;
+}
+
+async function resolveArtifactForCurrentSessionBounded(
+	capability: SessionArtifactCapability | undefined,
+	artifactId: string,
+): Promise<boolean> {
+	if (!capability) return false;
+	const pending = pendingArtifactLookupsForOwner(capability);
+	if (pending.size >= INLINE_ARTIFACT_PENDING_LIMIT) return false;
+	const lookup = Promise.resolve()
+		.then(async () => (await capability.getArtifactPath(artifactId)) !== null)
+		.catch(() => false);
+	pending.add(lookup);
+	void lookup.then(
+		() => pending.delete(lookup),
+		() => pending.delete(lookup),
+	);
+	return Promise.race([lookup, Bun.sleep(INLINE_ARTIFACT_SAVE_WAIT_MS).then(() => false)]);
+}
 /**
  * Truncation metadata for the output notice.
  */
@@ -55,8 +116,16 @@ export interface TruncationMeta {
 	elidedLines?: number;
 	/** Artifact ID when output was persisted; completeness is tracked separately below. */
 	artifactId?: string;
+	/** Artifact existence was proven by a successful save or publisher receipt. */
+	artifactVerified?: boolean;
 	/** Bytes omitted from an artifact after its hard storage cap was reached. */
 	artifactTruncatedBytes?: number;
+	/** Bytes dropped before Bash received the native output stream. */
+	sourceTruncatedBytes?: number;
+	/** Exact source capture completeness could not be proven. */
+	sourceCaptureIncomplete?: boolean;
+	/** Bytes omitted from the visible output by per-line column capping. */
+	columnDroppedBytes?: number;
 	/** Bounded diagnostic when artifact writer creation, write, or finalization failed. */
 	artifactFailureDiagnostic?: string;
 	/** Next offset for pagination (head truncation only) */
@@ -97,6 +166,8 @@ export interface OutputMeta {
 	source?: SourceMeta;
 	diagnostics?: DiagnosticMeta;
 	limits?: LimitsMeta;
+	/** Diagnostics were omitted to preserve the configured inline byte cap. */
+	diagnosticsOmitted?: boolean;
 }
 
 // =============================================================================
@@ -108,6 +179,9 @@ export interface TruncationOptions {
 	startLine?: number;
 	totalFileLines?: number;
 	artifactId?: string;
+	artifactVerified?: boolean;
+	artifactFailureDiagnostic?: string;
+	sourceCaptureIncomplete?: boolean;
 	maxBytes?: number;
 	noticeOwner?: "body";
 }
@@ -125,6 +199,8 @@ export interface TruncationTextOptions {
 	totalBytes?: number;
 	maxBytes?: number;
 	artifactId?: string;
+	artifactVerified?: boolean;
+	sourceCaptureIncomplete?: boolean;
 	noticeOwner?: "body";
 }
 
@@ -147,7 +223,17 @@ export class OutputMetaBuilder {
 	truncation(result: TruncationResult, options: TruncationOptions): this {
 		if (!result.truncated) return this;
 
-		const { direction, startLine = 1, totalFileLines, artifactId, noticeOwner, maxBytes } = options;
+		const {
+			direction,
+			startLine = 1,
+			totalFileLines,
+			artifactId,
+			artifactVerified,
+			artifactFailureDiagnostic,
+			sourceCaptureIncomplete,
+			noticeOwner,
+			maxBytes,
+		} = options;
 		const outputLines = result.outputLines ?? result.totalLines;
 		const outputBytes = result.outputBytes ?? result.totalBytes;
 		const isMiddle = direction === "middle" || result.truncatedBy === "middle";
@@ -163,12 +249,6 @@ export class OutputMetaBuilder {
 		if (isMiddle) {
 			const elidedLines = result.elidedLines ?? Math.max(0, effectiveTotalLines - outputLines);
 			const elidedBytes = result.elidedBytes ?? Math.max(0, result.totalBytes - outputBytes);
-			// Reconstruct head/tail line ranges. The kept output spans the first
-			// `headLines` lines and the last `tailLines` lines of the source; lines
-			// in the middle (count == elidedLines) are dropped.
-			const keptLines = Math.max(0, outputLines - 1); // -1 for marker line
-			const headLines = Math.ceil(keptLines / 2);
-			const tailLines = keptLines - headLines;
 			this.#meta.truncation = {
 				direction: "middle",
 				truncatedBy: "middle",
@@ -178,12 +258,14 @@ export class OutputMetaBuilder {
 				outputLines,
 				outputBytes,
 				...(maxBytes !== undefined ? { maxBytes } : {}),
-				headRange: headLines > 0 ? { start: 1, end: headLines } : undefined,
-				tailRange:
-					tailLines > 0 ? { start: effectiveTotalLines - tailLines + 1, end: effectiveTotalLines } : undefined,
+				headRange: result.firstLinePartial ? undefined : result.headRange,
+				tailRange: result.lastLinePartial ? undefined : result.tailRange,
 				elidedLines,
 				elidedBytes,
 				artifactId,
+				artifactVerified,
+				artifactFailureDiagnostic,
+				sourceCaptureIncomplete: sourceCaptureIncomplete || undefined,
 			};
 			return this;
 		}
@@ -208,8 +290,11 @@ export class OutputMetaBuilder {
 			outputLines,
 			outputBytes,
 			...(maxBytes !== undefined ? { maxBytes } : {}),
-			shownRange: { start: shownStart, end: shownEnd },
+			shownRange: direction === "tail" && result.lastLinePartial ? undefined : { start: shownStart, end: shownEnd },
 			artifactId,
+			artifactVerified,
+			artifactFailureDiagnostic,
+			sourceCaptureIncomplete: sourceCaptureIncomplete || undefined,
 			nextOffset: direction === "head" ? shownEnd + 1 : undefined,
 		};
 
@@ -221,6 +306,7 @@ export class OutputMetaBuilder {
 		windows: ReadWindow,
 		options: {
 			artifactId?: string;
+			artifactVerified?: boolean;
 			noticeOwner?: "body";
 			maxBytes?: number;
 			rangeBase?: "file" | "window";
@@ -228,7 +314,7 @@ export class OutputMetaBuilder {
 	): this {
 		if (windows.kind === "full") return this;
 
-		const { artifactId, noticeOwner, rangeBase } = options;
+		const { artifactId, artifactVerified, noticeOwner, rangeBase } = options;
 		const maxBytes = options.maxBytes ?? (windows as ReadWindow & { maxBytes?: number }).maxBytes;
 		const outputLinesOverride = (windows as ReadWindow & { outputLinesOverride?: number }).outputLinesOverride;
 		const outputBytesOverride = (windows as ReadWindow & { outputBytesOverride?: number }).outputBytesOverride;
@@ -264,6 +350,7 @@ export class OutputMetaBuilder {
 					sourceBytes: partialTail.sourceLineBytes,
 				},
 				artifactId,
+				artifactVerified,
 			};
 			return this;
 		}
@@ -282,6 +369,7 @@ export class OutputMetaBuilder {
 				...(maxBytes !== undefined ? { maxBytes } : {}),
 				shownRange: { start: head.origin.startLine, end: head.origin.endLine },
 				artifactId,
+				artifactVerified,
 				nextOffset: head.origin.endLine + 1,
 			};
 			return this;
@@ -301,6 +389,7 @@ export class OutputMetaBuilder {
 				...(maxBytes !== undefined ? { maxBytes } : {}),
 				shownRange: { start: tail.origin.startLine, end: tail.origin.endLine },
 				artifactId,
+				artifactVerified,
 			};
 			return this;
 		}
@@ -319,10 +408,12 @@ export class OutputMetaBuilder {
 			outputBytes: head.bytes + tail.bytes + Buffer.byteLength(marker, "utf-8") + 2,
 			...(maxBytes !== undefined ? { maxBytes } : {}),
 			headRange: { start: head.origin.startLine, end: head.origin.endLine },
-			tailRange: { start: tail.origin.startLine, end: tail.origin.endLine },
+			tailRange:
+				tail.kind === "partial-line" ? undefined : { start: tail.origin.startLine, end: tail.origin.endLine },
 			elidedLines: windows.elidedLines,
 			elidedBytes: windows.elidedBytes,
 			artifactId,
+			artifactVerified,
 		};
 		return this;
 	}
@@ -330,14 +421,45 @@ export class OutputMetaBuilder {
 	/** Add truncation info from OutputSummary. No-op if not truncated or artifact evidence is absent. */
 	truncationFromSummary(summary: OutputSummary, options: TruncationSummaryOptions): this {
 		const artifactFailureDiagnostic = summary.artifactFailureDiagnostic;
+		const artifactLossValid = isValidLossCounter(summary.artifactTruncatedBytes);
+		const sourceLossValid = isValidLossCounter(summary.sourceTruncatedBytes);
+		const columnLossValid =
+			isValidLossCounter(summary.columnDroppedBytes) &&
+			isValidLossCounter(summary.columnTruncatedLines) &&
+			isValidLossCounter(summary.columnMax);
+		const sourceCaptureFlagValid =
+			summary.sourceCaptureIncomplete === undefined || typeof summary.sourceCaptureIncomplete === "boolean";
 		const artifactTruncatedBytes =
-			summary.artifactTruncatedBytes != null && summary.artifactTruncatedBytes > 0
+			artifactLossValid && summary.artifactTruncatedBytes != null && summary.artifactTruncatedBytes > 0
 				? summary.artifactTruncatedBytes
 				: undefined;
+		const sourceTruncatedBytes =
+			sourceLossValid && summary.sourceTruncatedBytes != null && summary.sourceTruncatedBytes > 0
+				? summary.sourceTruncatedBytes
+				: undefined;
+		const columnDroppedBytes =
+			columnLossValid && summary.columnDroppedBytes != null && summary.columnDroppedBytes > 0
+				? summary.columnDroppedBytes
+				: undefined;
+		const sourceCaptureIncomplete =
+			summary.sourceCaptureIncomplete === true ||
+			!sourceCaptureFlagValid ||
+			!artifactLossValid ||
+			!sourceLossValid ||
+			!columnLossValid
+				? true
+				: undefined;
+		if (columnLossValid && (summary.columnTruncatedLines ?? 0) > 0 && (summary.columnMax ?? 0) > 0) {
+			this.columnTruncated(summary.columnMax ?? 0);
+		}
+		const sourceCoordinatesIncomplete =
+			sourceTruncatedBytes !== undefined || sourceCaptureIncomplete === true || columnDroppedBytes !== undefined;
 		const hasArtifactEvidence =
 			summary.artifactId !== undefined ||
 			artifactFailureDiagnostic !== undefined ||
-			artifactTruncatedBytes !== undefined;
+			artifactTruncatedBytes !== undefined ||
+			sourceTruncatedBytes !== undefined ||
+			sourceCaptureIncomplete !== undefined;
 		if (!summary.truncated && !hasArtifactEvidence) return this;
 
 		const { direction, startLine = 1, totalFileLines, noticeOwner } = options;
@@ -346,18 +468,26 @@ export class OutputMetaBuilder {
 			summary.artifactId !== undefined && summary.output.includes(`artifact://${summary.artifactId}`);
 		const bodyOwnsArtifact =
 			bodyHasArtifact &&
-			(artifactTruncatedBytes === undefined ||
-				(summary.artifactId !== undefined &&
-					summary.output.includes(formatArtifactReference(summary.artifactId, artifactTruncatedBytes))));
+			(artifactTruncatedBytes === undefined &&
+			sourceTruncatedBytes === undefined &&
+			sourceCaptureIncomplete === undefined &&
+			summary.columnDroppedBytes === undefined
+				? true
+				: summary.artifactId !== undefined &&
+					summary.output.includes(
+						formatArtifactReference(
+							summary.artifactId,
+							artifactTruncatedBytes,
+							sourceTruncatedBytes,
+							sourceCaptureIncomplete,
+						),
+					));
 		const owner =
 			noticeOwner !== undefined ? { noticeOwner } : bodyOwnsArtifact ? { noticeOwner: "body" as const } : {};
 
 		// Middle elision: the sink retained head + tail with an elision marker.
 		if (summary.elidedBytes != null && summary.elidedBytes > 0) {
 			const elidedLines = summary.elidedLines ?? Math.max(0, totalLines - summary.outputLines);
-			const keptLines = Math.max(0, summary.outputLines - 1); // -1 for marker line
-			const headLines = Math.ceil(keptLines / 2);
-			const tailLines = keptLines - headLines;
 			this.#meta.truncation = {
 				direction: "middle",
 				truncatedBy: "middle",
@@ -366,14 +496,19 @@ export class OutputMetaBuilder {
 				totalBytes: summary.totalBytes,
 				outputLines: summary.outputLines,
 				outputBytes: summary.outputBytes,
-				headRange: headLines > 0 ? { start: 1, end: headLines } : undefined,
-				tailRange: tailLines > 0 ? { start: totalLines - tailLines + 1, end: totalLines } : undefined,
+				headRange: sourceCoordinatesIncomplete || summary.firstLinePartial ? undefined : summary.headRange,
+				tailRange: sourceCoordinatesIncomplete || summary.lastLinePartial ? undefined : summary.tailRange,
 				elidedBytes: summary.elidedBytes,
 				elidedLines,
 				artifactId: summary.artifactId,
+				artifactVerified: summary.artifactVerified,
 				artifactTruncatedBytes,
+				sourceTruncatedBytes,
+				sourceCaptureIncomplete,
+				columnDroppedBytes,
 				artifactFailureDiagnostic,
 			};
+			bindCurrentExecutionArtifactProof(this.#meta.truncation, summary);
 			return this;
 		}
 
@@ -403,12 +538,20 @@ export class OutputMetaBuilder {
 			totalBytes: summary.totalBytes,
 			outputLines: summary.outputLines,
 			outputBytes: summary.outputBytes,
-			shownRange: { start: shownStart, end: shownEnd },
+			shownRange:
+				sourceCoordinatesIncomplete || (direction === "tail" && summary.lastLinePartial)
+					? undefined
+					: { start: shownStart, end: shownEnd },
 			artifactId: summary.artifactId,
+			artifactVerified: summary.artifactVerified,
 			artifactTruncatedBytes,
+			sourceTruncatedBytes,
+			sourceCaptureIncomplete,
+			columnDroppedBytes,
 			artifactFailureDiagnostic,
-			nextOffset: direction === "head" ? shownEnd + 1 : undefined,
+			nextOffset: direction === "head" && !sourceCoordinatesIncomplete ? shownEnd + 1 : undefined,
 		};
+		bindCurrentExecutionArtifactProof(this.#meta.truncation, summary);
 
 		return this;
 	}
@@ -453,8 +596,13 @@ export class OutputMetaBuilder {
 			outputBytes,
 			maxBytes: options.maxBytes,
 			artifactId: options.artifactId,
-			shownRange: { start: shownStart, end: shownEnd },
-			nextOffset: options.direction === "head" ? shownEnd + 1 : undefined,
+			artifactVerified: options.artifactVerified,
+			shownRange:
+				options.sourceCaptureIncomplete || options.direction === "middle"
+					? undefined
+					: { start: shownStart, end: shownEnd },
+			sourceCaptureIncomplete: options.sourceCaptureIncomplete || undefined,
+			nextOffset: options.direction === "head" && !options.sourceCaptureIncomplete ? shownEnd + 1 : undefined,
 		};
 
 		return this;
@@ -549,33 +697,196 @@ export function formatFullOutputReference(artifactId: string): string {
 	return `Read artifact://${artifactId} for full output`;
 }
 
-/**
- * Format an artifact reference without claiming completeness when storage was hard-capped.
- */
-export function formatArtifactReference(artifactId: string, artifactTruncatedBytes?: number): string {
+function boundArtifactFailureDiagnostic(error: unknown): string {
+	const message = (error instanceof Error ? error.message : String(error)).replace(/\s+/gu, " ").trim();
+	return truncateHeadBytes(message || "unknown storage error", 512).text;
+}
+
+const INLINE_ARTIFACT_SAVE_WAIT_MS = 500;
+const INLINE_ARTIFACT_PENDING_LIMIT = 64;
+const pendingInlineArtifactSavesByOwner = new WeakMap<SessionArtifactCapability, Set<Promise<unknown>>>();
+
+function pendingInlineArtifactSavesForOwner(capability: SessionArtifactCapability): Set<Promise<unknown>> {
+	let pending = pendingInlineArtifactSavesByOwner.get(capability);
+	if (!pending) {
+		pending = new Set<Promise<unknown>>();
+		pendingInlineArtifactSavesByOwner.set(capability, pending);
+	}
+	return pending;
+}
+
+async function saveInlineArtifactBounded(
+	capability: SessionArtifactCapability,
+	save: () => Promise<string | null | undefined>,
+	resolvePath: (artifactId: string) => Promise<string | null>,
+): Promise<
+	{ status: "ok"; artifactId: string; artifactTruncatedBytes?: number } | { status: "failed"; diagnostic: string }
+> {
+	const pendingInlineArtifactSaves = pendingInlineArtifactSavesForOwner(capability);
+	if (pendingInlineArtifactSaves.size >= INLINE_ARTIFACT_PENDING_LIMIT) {
+		return { status: "failed", diagnostic: "pending artifact save limit reached for this session" };
+	}
+	const promise = Promise.resolve()
+		.then(save)
+		.then(async artifactId => {
+			if (!isValidArtifactId(artifactId)) {
+				return { status: "failed", diagnostic: "storage returned an invalid artifact id" } as const;
+			}
+			const artifactPath = await resolvePath(artifactId);
+			if (!artifactPath) {
+				return { status: "failed", diagnostic: "saved artifact is not protocol-resolvable" } as const;
+			}
+			return { status: "ok", artifactId } as const;
+		})
+		.catch(error => ({ status: "failed", diagnostic: boundArtifactFailureDiagnostic(error) }) as const);
+	pendingInlineArtifactSaves.add(promise);
+	void promise.then(
+		() => pendingInlineArtifactSaves.delete(promise),
+		() => pendingInlineArtifactSaves.delete(promise),
+	);
+	return Promise.race([
+		promise,
+		Bun.sleep(INLINE_ARTIFACT_SAVE_WAIT_MS).then(
+			() => ({ status: "failed", diagnostic: `did not settle within ${INLINE_ARTIFACT_SAVE_WAIT_MS}ms` }) as const,
+		),
+	]);
+}
+
+function genericArtifactOmittedBytes(content: string): number | undefined {
+	const contentBytes = Buffer.byteLength(content, "utf-8");
+	if (contentBytes <= DEFAULT_ARTIFACT_MAX_BYTES) return undefined;
+	const retained = truncateHeadBytes(content, DEFAULT_ARTIFACT_MAX_BYTES);
+	return contentBytes - retained.bytes;
+}
+
+const ARTIFACT_FAILURE_PREVIEW_DEFAULT_BYTES = 8 * 1024;
+
+export interface ArtifactFailurePreview {
+	text: string;
+	omittedBytes: number;
+}
+
+/** Build a bounded, UTF-8-safe preview when artifact storage cannot retain the full payload. */
+export function createArtifactFailurePreview(
+	fullText: string,
+	maxInlineBytes: number | undefined,
+	diagnostic: string,
+): ArtifactFailurePreview {
+	const totalBytes = Buffer.byteLength(fullText, "utf-8");
+	const previewLimit =
+		maxInlineBytes !== undefined && maxInlineBytes > 0 ? maxInlineBytes : ARTIFACT_FAILURE_PREVIEW_DEFAULT_BYTES;
+	const boundedDiagnostic = boundArtifactFailureDiagnostic(diagnostic);
+	let bodyBudget = Math.min(Math.max(0, totalBytes - 1), previewLimit);
+	for (let attempt = 0; attempt < 8; attempt++) {
+		const body = truncateTail(fullText, { maxBytes: bodyBudget }).content;
+		const bodyBytes = Buffer.byteLength(body, "utf-8");
+		const omittedBytes = Math.max(1, totalBytes - bodyBytes);
+		const marker = `\n\n[${omittedBytes} bytes omitted; no artifact available: ${boundedDiagnostic}]\n\n`;
+		const markerBytes = Buffer.byteLength(marker, "utf-8");
+		if (bodyBytes + markerBytes <= previewLimit) {
+			return { text: `${body}${marker}`, omittedBytes };
+		}
+		bodyBudget = Math.max(0, Math.min(bodyBudget - 1, previewLimit - markerBytes));
+	}
+	const marker = `\n\n[${totalBytes} bytes omitted; no artifact available: ${boundedDiagnostic}]\n\n`;
+	return { text: truncateHeadBytes(marker, previewLimit).text, omittedBytes: totalBytes };
+}
+
+/** Format an artifact reference without claiming completeness when capture or storage omitted bytes. */
+export function formatArtifactReference(
+	artifactId: string,
+	artifactTruncatedBytes?: number,
+	sourceTruncatedBytes?: number,
+	sourceCaptureIncomplete?: boolean,
+): string {
+	const omissions: string[] = [];
+	if (!isValidLossCounter(sourceTruncatedBytes) || !isValidLossCounter(artifactTruncatedBytes)) {
+		omissions.push("loss accounting was invalid");
+	}
+	if (sourceTruncatedBytes != null && sourceTruncatedBytes > 0) {
+		omissions.push(`at least ${formatBytes(sourceTruncatedBytes)} dropped before Bash capture`);
+	}
+	if (sourceCaptureIncomplete) {
+		omissions.push("source capture completeness could not be proven");
+	}
 	if (artifactTruncatedBytes != null && artifactTruncatedBytes > 0) {
-		return `Read artifact://${artifactId} for retained output (at least ${formatBytes(artifactTruncatedBytes)} omitted by the artifact storage cap)`;
+		omissions.push(`at least ${formatBytes(artifactTruncatedBytes)} omitted by the artifact storage cap`);
 	}
-	return formatFullOutputReference(artifactId);
+	return omissions.length > 0
+		? `Read artifact://${artifactId} for retained output (${omissions.join("; ")})`
+		: formatFullOutputReference(artifactId);
 }
 
-function formatTruncationArtifactNotice(truncation: TruncationMeta): string {
-	const reference = truncation.artifactId
-		? formatArtifactReference(truncation.artifactId, truncation.artifactTruncatedBytes)
-		: undefined;
-	if (truncation.artifactFailureDiagnostic) {
-		const failure = `Artifact storage failed: ${truncation.artifactFailureDiagnostic}`;
-		if (reference) return `${reference}; ${failure}`;
-		return failure;
+export interface ArtifactEvidence {
+	artifactId?: string;
+	artifactVerified?: boolean;
+	artifactTruncatedBytes?: number;
+	sourceTruncatedBytes?: number;
+	sourceCaptureIncomplete?: boolean;
+	artifactFailureDiagnostic?: string;
+	columnDroppedBytes?: number;
+}
+
+export function formatArtifactEvidenceNotice(evidence: ArtifactEvidence): string | undefined {
+	const parts: string[] = [];
+	if (
+		isValidArtifactId(evidence.artifactId) &&
+		evidence.artifactVerified === true &&
+		!evidence.artifactFailureDiagnostic
+	) {
+		parts.push(
+			formatArtifactReference(
+				evidence.artifactId,
+				evidence.artifactTruncatedBytes,
+				evidence.sourceTruncatedBytes,
+				evidence.sourceCaptureIncomplete || (evidence.columnDroppedBytes ?? 0) > 0,
+			),
+		);
+		if ((evidence.columnDroppedBytes ?? 0) > 0) {
+			parts.push(`Visible line caps omitted ${formatBytes(evidence.columnDroppedBytes ?? 0)}`);
+		}
+	} else {
+		if (evidence.artifactId && evidence.artifactVerified !== true) {
+			parts.push("Artifact availability could not be proven");
+		}
+		if ((evidence.sourceTruncatedBytes ?? 0) > 0) {
+			parts.push(
+				`Bash capture omitted at least ${formatBytes(evidence.sourceTruncatedBytes ?? 0)} before artifact storage`,
+			);
+		}
+		if (evidence.sourceCaptureIncomplete) {
+			parts.push("Source capture completeness could not be proven before retained output was finalized");
+		}
+		if ((evidence.artifactTruncatedBytes ?? 0) > 0) {
+			parts.push(`Artifact storage omitted at least ${formatBytes(evidence.artifactTruncatedBytes ?? 0)}`);
+		}
+		if ((evidence.columnDroppedBytes ?? 0) > 0) {
+			parts.push(`Visible line caps omitted ${formatBytes(evidence.columnDroppedBytes ?? 0)}`);
+		}
+		if (parts.length > 0) {
+			parts.push("no artifact reference is available");
+		}
+	}
+	if (evidence.artifactFailureDiagnostic) {
+		parts.push(`Artifact storage failed: ${evidence.artifactFailureDiagnostic}`);
+	}
+	if (!evidence.artifactId && parts.length > 0 && !parts.includes("no artifact reference is available")) {
+		parts.push("no artifact reference is available");
 	}
-	if (reference) return reference;
-	return `Artifact storage omitted at least ${formatBytes(truncation.artifactTruncatedBytes ?? 0)}; no artifact reference is available`;
+	return parts.length > 0 ? parts.join("; ") : undefined;
+}
+
+function formatTruncationArtifactNotice(truncation: TruncationMeta): string {
+	return formatArtifactEvidenceNotice(truncation) ?? "";
 }
 
 function hasArtifactNotice(truncation: TruncationMeta): boolean {
 	return (
 		truncation.artifactId != null ||
 		(truncation.artifactTruncatedBytes ?? 0) > 0 ||
+		(truncation.sourceTruncatedBytes ?? 0) > 0 ||
+		truncation.sourceCaptureIncomplete ||
+		(truncation.columnDroppedBytes ?? 0) > 0 ||
 		truncation.artifactFailureDiagnostic != null
 	);
 }
@@ -588,6 +899,16 @@ function formatTruncationRangeTotal(truncation: TruncationMeta): string {
 
 export function formatTruncationMetaNotice(truncation: TruncationMeta): string {
 	const rangeTotal = formatTruncationRangeTotal(truncation);
+	if ((truncation.sourceTruncatedBytes ?? 0) > 0 || truncation.sourceCaptureIncomplete) {
+		let notice = `Showing ${truncation.outputLines} retained line${truncation.outputLines === 1 ? "" : "s"} from an incomplete Bash capture`;
+		if (truncation.truncatedBy === "bytes" && truncation.maxBytes != null) {
+			notice += ` (${formatBytes(truncation.maxBytes)} limit)`;
+		}
+		if (hasArtifactNotice(truncation)) {
+			notice += `. ${formatTruncationArtifactNotice(truncation)}`;
+		}
+		return notice;
+	}
 	if (truncation.partialLine) {
 		let notice = `Showing last ${formatBytes(truncation.partialLine.bytes)} of line ${truncation.partialLine.line} of ${rangeTotal}`;
 		if (truncation.partialLine.sourceBytes > truncation.partialLine.bytes) {
@@ -614,7 +935,7 @@ export function formatTruncationMetaNotice(truncation: TruncationMeta): string {
 		} else if (headPart && tailPart) {
 			notice = `Showing ${headPart} and ${tailPart} of ${rangeTotal}; ${elidedLines.toLocaleString()} middle line${elidedLines === 1 ? "" : "s"} (${formatBytes(elidedBytes)}) elided`;
 		} else {
-			notice = `Showing ${truncation.outputLines} of ${rangeTotal}${truncation.rangeBase === "window" ? "" : " lines"}; ${formatBytes(elidedBytes)} middle bytes elided`;
+			notice = `Showing retained head and tail fragments of ${rangeTotal}; ${formatBytes(elidedBytes)} middle bytes elided`;
 		}
 		if (hasArtifactNotice(truncation)) {
 			notice += `. ${formatTruncationArtifactNotice(truncation)}`;
@@ -688,8 +1009,12 @@ export function formatOutputNotice(meta: OutputMeta | undefined): string {
 	let diagnosticsNotice = "";
 	if (meta.diagnostics && meta.diagnostics.messages.length > 0) {
 		const d = meta.diagnostics;
-		diagnosticsNotice = `\n\nLSP Diagnostics (${d.summary}):\n${formatGroupedDiagnosticMessages(d.messages)}`;
+		const grouped = formatGroupedDiagnosticMessages(d.messages);
+		const bounded = truncateHeadBytes(grouped, 1024);
+		const suffix = bounded.bytes < Buffer.byteLength(grouped, "utf-8") ? "\n[diagnostics truncated]" : "";
+		diagnosticsNotice = `\n\nLSP Diagnostics (${d.summary}):\n${bounded.text}${suffix}`;
 	}
+	if (meta.diagnosticsOmitted) parts.push("Diagnostics omitted by inline result cap");
 
 	const notice = parts.length ? `\n\n[${parts.join(". ")}]` : "";
 	return notice + diagnosticsNotice;
@@ -791,13 +1116,15 @@ function getSpillConfig(s: Settings | undefined) {
 		| "tools.maxInlineResultBytes"
 		| "tools.readArtifactSpillThreshold";
 	const get = <P extends Path>(path: P) => s?.get(path) ?? getDefault(path);
+	const configuredInlineKiB = get("tools.maxInlineResultBytes");
+	const maxInlineBytes = configuredInlineKiB > 0 ? Math.max(1024, Math.floor(configuredInlineKiB * 1024)) : 0;
 	return {
 		threshold: get("tools.artifactSpillThreshold") * 1024,
 		readThreshold: get("tools.readArtifactSpillThreshold") * 1024,
 		tailBytes: get("tools.artifactTailBytes") * 1024,
 		tailLines: get("tools.artifactTailLines"),
 		headBytes: get("tools.artifactHeadBytes") * 1024,
-		maxInlineBytes: get("tools.maxInlineResultBytes") * 1024,
+		maxInlineBytes,
 	};
 }
 
@@ -818,7 +1145,12 @@ export const BASH_DEFAULT_OUTPUT_TAIL_BYTES = 1024;
  * budget still wins.
  */
 export function resolveBashOutputSinkTailBytes(s: Settings): number {
-	return s.has("tools.artifactTailBytes") ? s.get("tools.artifactTailBytes") * 1024 : BASH_DEFAULT_OUTPUT_TAIL_BYTES;
+	const configuredTailBytes = s.get("tools.artifactTailBytes");
+	const hasExplicitTailBytes =
+		typeof s.has === "function" ? s.has("tools.artifactTailBytes") : configuredTailBytes !== undefined;
+	return hasExplicitTailBytes && configuredTailBytes !== undefined
+		? configuredTailBytes * 1024
+		: BASH_DEFAULT_OUTPUT_TAIL_BYTES;
 }
 /**
  * Bash keeps only the tail unless the user explicitly opts into the shared
@@ -826,7 +1158,111 @@ export function resolveBashOutputSinkTailBytes(s: Settings): number {
  * tools without silently turning Bash back into middle-elision mode.
  */
 export function resolveBashOutputSinkHeadBytes(s: Settings): number {
-	return s.has("tools.artifactHeadBytes") ? resolveOutputSinkHeadBytes(s) : 0;
+	const configuredHeadBytes = s.get("tools.artifactHeadBytes");
+	const hasExplicitHeadBytes =
+		typeof s.has === "function" ? s.has("tools.artifactHeadBytes") : configuredHeadBytes !== undefined;
+	return hasExplicitHeadBytes && configuredHeadBytes !== undefined ? configuredHeadBytes * 1024 : 0;
+}
+
+function isValidLossCounter(value: number | undefined): boolean {
+	return value === undefined || (Number.isSafeInteger(value) && value >= 0);
+}
+
+function stripBodyArtifactReferences(result: AgentToolResult, artifactId: string): AgentToolResult["content"] {
+	return result.content.map(block => {
+		if (block.type !== "text") return block;
+		const lines = block.text.split("\n");
+		const kept = lines.filter(line => {
+			const trimmed = line.trim();
+			return !(
+				(trimmed.startsWith("[raw output:") && trimmed.includes(`artifact://${artifactId}`)) ||
+				trimmed.startsWith(`Read artifact://${artifactId} `)
+			);
+		});
+		return kept.length === lines.length ? block : { ...block, text: kept.join("\n") };
+	});
+}
+
+async function sanitizeArtifactIdEvidence(
+	result: AgentToolResult,
+	context: AgentToolContext | undefined,
+): Promise<AgentToolResult> {
+	const meta: OutputMeta | undefined = result.details?.meta;
+	const truncation = meta?.truncation;
+	if (!truncation) return result;
+	const artifactId = truncation.artifactId;
+	const artifactIdValid = artifactId === undefined || isValidArtifactId(artifactId);
+	const countersValid =
+		isValidLossCounter(truncation.artifactTruncatedBytes) &&
+		isValidLossCounter(truncation.sourceTruncatedBytes) &&
+		isValidLossCounter(truncation.columnDroppedBytes);
+	const sourceCaptureFlagValid =
+		truncation.sourceCaptureIncomplete === undefined || typeof truncation.sourceCaptureIncomplete === "boolean";
+	const sourceCoordinatesIncomplete =
+		!countersValid ||
+		!sourceCaptureFlagValid ||
+		truncation.sourceCaptureIncomplete === true ||
+		(truncation.sourceTruncatedBytes ?? 0) > 0;
+	const artifactCapability = artifactCapabilityForContext(context);
+	const artifactResolvable =
+		artifactId === undefined ? true : await resolveArtifactForCurrentSessionBounded(artifactCapability, artifactId);
+	const resultPayload = result.content.map(block => (block.type === "text" ? block.text : "")).join("");
+	const artifactProven =
+		artifactId === undefined ||
+		(truncation.artifactVerified === true &&
+			hasBoundCurrentExecutionArtifactProof(truncation, artifactId, resultPayload) &&
+			artifactResolvable);
+	const artifactFailed = truncation.artifactFailureDiagnostic !== undefined;
+	const invalidateArtifact = artifactId !== undefined && (!artifactIdValid || !artifactProven || artifactFailed);
+	const staleFullClaim =
+		artifactId !== undefined &&
+		(sourceCoordinatesIncomplete ||
+			(truncation.artifactTruncatedBytes ?? 0) > 0 ||
+			(truncation.columnDroppedBytes ?? 0) > 0);
+	if (
+		artifactIdValid &&
+		countersValid &&
+		sourceCaptureFlagValid &&
+		!sourceCoordinatesIncomplete &&
+		!invalidateArtifact &&
+		!staleFullClaim
+	)
+		return result;
+	const diagnostic = !artifactIdValid
+		? "existing metadata contained an invalid artifact id"
+		: artifactFailed
+			? truncation.artifactFailureDiagnostic
+			: !artifactProven
+				? artifactResolvable
+					? "existing metadata did not prove artifact availability"
+					: "existing artifact is not protocol-resolvable in the current session"
+				: undefined;
+	return {
+		...result,
+		content:
+			artifactId && (invalidateArtifact || staleFullClaim)
+				? stripBodyArtifactReferences(result, artifactId)
+				: result.content,
+		details: {
+			...(result.details ?? {}),
+			meta: {
+				...meta,
+				truncation: {
+					...truncation,
+					noticeOwner: invalidateArtifact || staleFullClaim ? undefined : truncation.noticeOwner,
+					artifactId: invalidateArtifact ? undefined : artifactId,
+					artifactVerified: invalidateArtifact ? false : truncation.artifactVerified,
+					sourceCaptureIncomplete:
+						!countersValid || !sourceCaptureFlagValid || truncation.sourceCaptureIncomplete || undefined,
+					shownRange: sourceCoordinatesIncomplete ? undefined : truncation.shownRange,
+					headRange: sourceCoordinatesIncomplete ? undefined : truncation.headRange,
+					tailRange: sourceCoordinatesIncomplete ? undefined : truncation.tailRange,
+					nextOffset: sourceCoordinatesIncomplete ? undefined : truncation.nextOffset,
+					artifactFailureDiagnostic: diagnostic,
+				},
+			},
+		},
+	};
 }
 
 /**
@@ -858,35 +1294,95 @@ async function spillLargeResultToArtifact(
 		return result;
 	}
 
-	const artifactCapability = artifactCapabilityForContext(context);
-	if (!artifactCapability) return result;
-	const { threshold, readThreshold, tailBytes, tailLines, headBytes } = getSpillConfig(context?.settings);
+	const { threshold, readThreshold, tailBytes, tailLines, headBytes, maxInlineBytes } = getSpillConfig(
+		context?.settings,
+	);
 	// `read` manages its own per-range truncation, but the combined multi-range
 	// output has no cap — enforce a read-specific (higher) combined threshold
 	// instead of exempting read entirely. 0 disables read spill (backstop only).
 	const effectiveThreshold = toolName === "read" ? readThreshold : threshold;
-	if (effectiveThreshold <= 0) return result;
-
-	// Skip if tool already saved an artifact
 	const existingMeta: OutputMeta | undefined = result.details?.meta;
-	if (existingMeta?.truncation?.artifactId) return result;
 
-	// Measure total text content
+	// Measure total text content before any threshold early return so the absolute
+	// inline cap is enforced even when token-based spilling is disabled.
 	const textParts: string[] = [];
 	for (const block of result.content) {
-		if (block.type === "text" && block.text) {
-			textParts.push(block.text);
-		}
+		if (block.type === "text" && block.text) textParts.push(block.text);
 	}
 	if (textParts.length === 0) return result;
 
 	const fullText = textParts.length === 1 ? textParts[0] : textParts.join("\n");
+	const existingTruncation = existingMeta?.truncation;
+	const existingArtifactProven =
+		existingTruncation?.artifactId !== undefined &&
+		isValidArtifactId(existingTruncation.artifactId) &&
+		existingTruncation.artifactFailureDiagnostic === undefined &&
+		existingTruncation.artifactVerified === true;
+	if (existingArtifactProven) return result;
 	const totalBytes = Buffer.byteLength(fullText, "utf-8");
-	if (totalBytes <= effectiveThreshold) return result;
+	const exceedsInlineCap = maxInlineBytes > 0 && totalBytes > maxInlineBytes;
+	if (!exceedsInlineCap && (effectiveThreshold <= 0 || totalBytes <= effectiveThreshold)) return result;
 
-	// Save full output as artifact
-	const artifactId = await artifactCapability.saveArtifact(fullText, toolName);
-	if (!artifactId) return result;
+	const artifactCapability = artifactCapabilityForContext(context);
+	const saveFailure = (diagnostic: string): AgentToolResult => {
+		const failurePreview = createArtifactFailurePreview(
+			fullText,
+			maxInlineBytes > 0 ? maxInlineBytes : undefined,
+			diagnostic,
+		);
+		const outputLines = failurePreview.text.length > 0 ? failurePreview.text.split("\n").length : 0;
+		const outputBytes = Buffer.byteLength(failurePreview.text, "utf-8");
+		const failureTruncation: TruncationMeta = {
+			...(existingTruncation ?? {}),
+			direction: "tail",
+			truncatedBy: "bytes",
+			noticeOwner: undefined,
+			totalLines: fullText.length > 0 ? fullText.split("\n").length : 0,
+			totalBytes,
+			outputLines,
+			outputBytes,
+			maxBytes: maxInlineBytes > 0 ? maxInlineBytes : undefined,
+			shownRange: undefined,
+			headRange: undefined,
+			tailRange: undefined,
+			nextOffset: undefined,
+			artifactId: undefined,
+			artifactVerified: false,
+			sourceCaptureIncomplete: true,
+			artifactFailureDiagnostic: diagnostic,
+		};
+		const content: (TextContent | ImageContent)[] = result.content.filter(block => block.type !== "text");
+		content.push({ type: "text", text: failurePreview.text });
+		return {
+			...result,
+			content,
+			details: {
+				...(result.details ?? {}),
+				meta: { ...(existingMeta ?? {}), truncation: failureTruncation },
+			},
+		};
+	};
+	if (!artifactCapability) return saveFailure("artifact storage is unavailable");
+
+	// Save full output through the bounded, validating path. Failed threshold
+	// spills preserve their diagnostic even when the absolute backstop is disabled.
+	const saveOutcome = await saveInlineArtifactBounded(
+		artifactCapability,
+		() => artifactCapability.saveArtifact(fullText, toolName),
+		artifactId => artifactCapability.getArtifactPath(artifactId),
+	);
+	if (saveOutcome.status !== "ok") return saveFailure(saveOutcome.diagnostic);
+
+	const artifactId = saveOutcome.artifactId;
+	const newArtifactOmissions = genericArtifactOmittedBytes(fullText) ?? 0;
+	const priorArtifactOmissions = isValidLossCounter(existingTruncation?.artifactTruncatedBytes)
+		? (existingTruncation?.artifactTruncatedBytes ?? 0)
+		: 0;
+	const artifactTruncatedBytes = Math.max(newArtifactOmissions, priorArtifactOmissions) || undefined;
+	const sourceTruncatedBytes = existingTruncation?.sourceTruncatedBytes;
+	const columnDroppedBytes = existingTruncation?.columnDroppedBytes;
+	const sourceCaptureIncomplete =
+		existingTruncation?.sourceCaptureIncomplete || (columnDroppedBytes ?? 0) > 0 || undefined;
 
 	// Truncate: middle elision when a head budget is configured, otherwise tail-only.
 	const useMiddle = headBytes > 0;
@@ -902,25 +1398,20 @@ async function spillLargeResultToArtifact(
 				maxLines: tailLines,
 			});
 
-	// Replace text blocks with single truncated block, keep images
+	// Replace text blocks with single truncated block, keep images.
 	const newContent: (TextContent | ImageContent)[] = [];
 	for (const block of result.content) {
-		if (block.type !== "text") {
-			newContent.push(block);
-		}
+		if (block.type !== "text") newContent.push(block);
 	}
 	newContent.push({ type: "text", text: truncated.content });
 
-	// Build truncation meta
+	// Build truncation meta.
 	const outputLines = truncated.outputLines ?? truncated.totalLines;
 	const outputBytes = truncated.outputBytes ?? truncated.totalBytes;
 	let truncationMeta: TruncationMeta;
 	if (truncated.truncatedBy === "middle") {
 		const elidedLines = truncated.elidedLines ?? Math.max(0, truncated.totalLines - outputLines);
 		const elidedBytes = truncated.elidedBytes ?? Math.max(0, truncated.totalBytes - outputBytes);
-		const keptLines = Math.max(0, outputLines - 1); // -1 for marker line
-		const headLines = Math.ceil(keptLines / 2);
-		const tailLineCount = keptLines - headLines;
 		truncationMeta = {
 			direction: "middle",
 			truncatedBy: "middle",
@@ -929,14 +1420,16 @@ async function spillLargeResultToArtifact(
 			outputLines,
 			outputBytes,
 			maxBytes: headBytes + tailBytes,
-			headRange: headLines > 0 ? { start: 1, end: headLines } : undefined,
-			tailRange:
-				tailLineCount > 0
-					? { start: truncated.totalLines - tailLineCount + 1, end: truncated.totalLines }
-					: undefined,
+			headRange: sourceCaptureIncomplete ? undefined : truncated.headRange,
+			tailRange: sourceCaptureIncomplete ? undefined : truncated.tailRange,
 			elidedLines,
 			elidedBytes,
 			artifactId,
+			artifactVerified: true,
+			artifactTruncatedBytes,
+			sourceTruncatedBytes,
+			sourceCaptureIncomplete,
+			columnDroppedBytes,
 		};
 	} else {
 		const shownStart = truncated.totalLines - outputLines + 1;
@@ -948,8 +1441,13 @@ async function spillLargeResultToArtifact(
 			outputLines,
 			outputBytes,
 			maxBytes: tailBytes,
-			shownRange: { start: shownStart, end: truncated.totalLines },
+			shownRange: sourceCaptureIncomplete ? undefined : { start: shownStart, end: truncated.totalLines },
 			artifactId,
+			artifactVerified: true,
+			artifactTruncatedBytes,
+			sourceTruncatedBytes,
+			sourceCaptureIncomplete,
+			columnDroppedBytes,
 		};
 	}
 
@@ -996,26 +1494,68 @@ async function enforceInlineResultBackstop(
 			textParts.push(block.text);
 		}
 	}
-	if (textParts.length === 0) return result;
 
 	const renderedText = textParts.length === 1 ? textParts[0] : textParts.join("\n");
 	const fullText = stripBodyOwnedTruncationFooter(renderedText, result.details);
-	const totalBytes = Buffer.byteLength(fullText, "utf-8");
-	if (totalBytes <= maxInlineBytes) return result;
-
-	// Reuse an existing artifact (avoid double-artifacting); otherwise save the
-	// full output so the truncated view keeps a reference to the complete text.
+	const totalBytes = Buffer.byteLength(renderedText, "utf-8");
 	const existingMeta: OutputMeta | undefined = result.details?.meta;
-	let artifactId = existingMeta?.truncation?.artifactId;
+	const existingNoticeBytes = Buffer.byteLength(formatOutputNotice(existingMeta), "utf-8");
+	if (totalBytes + existingNoticeBytes <= maxInlineBytes) return result;
+
+	// Reuse only storage-complete artifacts. Source-loss evidence remains bound
+	// to the rendered body even when a new complete artifact is saved.
+	const existingTruncation = existingMeta?.truncation;
+	const previousArtifactId = existingTruncation?.artifactId;
+	const previousArtifactIdValid = previousArtifactId === undefined || isValidArtifactId(previousArtifactId);
+	const previousArtifactProven =
+		previousArtifactId !== undefined && previousArtifactIdValid && existingTruncation?.artifactVerified === true;
+	const existingArtifactStorageComplete =
+		previousArtifactProven && existingTruncation?.artifactFailureDiagnostic === undefined;
+	let artifactId = existingArtifactStorageComplete ? previousArtifactId : undefined;
+	let artifactFailureDiagnostic = previousArtifactIdValid
+		? existingTruncation?.artifactFailureDiagnostic
+		: "existing metadata contained an invalid artifact id";
+	let artifactTruncatedBytes = existingTruncation?.artifactTruncatedBytes;
+	let artifactVerified = existingArtifactStorageComplete;
+	let savedReplacementArtifact = false;
 	const artifactCapability = artifactCapabilityForContext(context);
-	if (!artifactId && artifactCapability) {
-		artifactId = (await artifactCapability.saveArtifact(fullText, toolName)) ?? undefined;
+	if (!artifactId && artifactCapability && fullText.length > 0) {
+		const saveOutcome = await saveInlineArtifactBounded(
+			artifactCapability,
+			() => artifactCapability.saveArtifact(fullText, toolName),
+			artifactId => artifactCapability.getArtifactPath(artifactId),
+		);
+		if (saveOutcome.status === "ok") {
+			artifactId = saveOutcome.artifactId;
+			const newArtifactOmissions = genericArtifactOmittedBytes(fullText) ?? 0;
+			const priorArtifactOmissions = artifactTruncatedBytes ?? 0;
+			artifactTruncatedBytes = Math.max(newArtifactOmissions, priorArtifactOmissions) || undefined;
+			artifactFailureDiagnostic = undefined;
+			artifactVerified = true;
+			savedReplacementArtifact = true;
+		} else {
+			artifactFailureDiagnostic = saveOutcome.diagnostic;
+		}
+	} else if (!artifactId && !artifactCapability) {
+		artifactFailureDiagnostic ??= "artifact storage is unavailable";
 	}
-
-	// Budget head+tail below the cap, reserving room for the elision marker so the
-	// composed `<head>\n<marker>\n<tail>` view never exceeds the configured cap.
+	const sourceTruncatedBytes = existingTruncation?.sourceTruncatedBytes;
+	const columnDroppedBytes = existingTruncation?.columnDroppedBytes;
+	const sourceCaptureIncomplete =
+		existingTruncation?.sourceCaptureIncomplete ||
+		(savedReplacementArtifact && (columnDroppedBytes ?? 0) > 0) ||
+		undefined;
+	const sourceCoordinatesIncomplete = (sourceTruncatedBytes ?? 0) > 0 || sourceCaptureIncomplete === true;
+
+	// Reserve the actual pre-existing notice plus room for the bounded truncation
+	// evidence appended below. This prevents large diagnostics from bypassing the
+	// final inline cap while retaining both head/tail content when space permits.
 	const MARKER_RESERVE = 256;
-	const budget = maxInlineBytes - MARKER_RESERVE;
+	const NOTICE_RESERVE = Math.min(
+		Math.max(0, maxInlineBytes - MARKER_RESERVE),
+		Math.max(4096, existingNoticeBytes + 1024),
+	);
+	const budget = Math.max(0, maxInlineBytes - MARKER_RESERVE - NOTICE_RESERVE);
 	const useMiddle = headBytes > 0 && budget > 0;
 	let truncated = useMiddle
 		? truncateMiddle(fullText, {
@@ -1024,11 +1564,10 @@ async function enforceInlineResultBackstop(
 				maxHeadBytes: Math.min(headBytes, Math.floor(budget / 2)),
 				maxHeadLines: tailLines,
 			})
-		: truncateTail(fullText, { maxBytes: maxInlineBytes, maxLines: tailLines });
+		: truncateTail(fullText, { maxBytes: budget, maxLines: tailLines });
 
-	// Defensive clamp: guarantee the contract even for pathological marker sizes.
-	if (Buffer.byteLength(truncated.content, "utf-8") > maxInlineBytes) {
-		truncated = truncateTail(fullText, { maxBytes: maxInlineBytes, maxLines: tailLines });
+	if (Buffer.byteLength(truncated.content, "utf-8") > budget) {
+		truncated = truncateTail(fullText, { maxBytes: budget, maxLines: tailLines });
 	}
 
 	const newContent: (TextContent | ImageContent)[] = [];
@@ -1054,6 +1593,12 @@ async function enforceInlineResultBackstop(
 					elidedLines: truncated.elidedLines ?? Math.max(0, truncated.totalLines - outputLines),
 					elidedBytes: truncated.elidedBytes ?? Math.max(0, truncated.totalBytes - outputBytes),
 					artifactId,
+					artifactVerified,
+					artifactTruncatedBytes,
+					sourceTruncatedBytes,
+					sourceCaptureIncomplete,
+					columnDroppedBytes,
+					artifactFailureDiagnostic,
 				}
 			: {
 					direction: "tail",
@@ -1063,13 +1608,71 @@ async function enforceInlineResultBackstop(
 					outputLines,
 					outputBytes,
 					maxBytes: maxInlineBytes,
-					shownRange: { start: truncated.totalLines - outputLines + 1, end: truncated.totalLines },
+					shownRange: sourceCoordinatesIncomplete
+						? undefined
+						: { start: truncated.totalLines - outputLines + 1, end: truncated.totalLines },
 					artifactId,
+					artifactVerified,
+					artifactTruncatedBytes,
+					sourceTruncatedBytes,
+					sourceCaptureIncomplete,
+					columnDroppedBytes,
+					artifactFailureDiagnostic,
 				};
 
-	const newMeta: OutputMeta = { ...(existingMeta ?? {}), truncation: truncationMeta };
+	let newMeta: OutputMeta = { ...(existingMeta ?? {}), truncation: truncationMeta };
+	let finalText = truncated.content;
+	let renderedBytes = Buffer.byteLength(finalText, "utf-8") + Buffer.byteLength(formatOutputNotice(newMeta), "utf-8");
+	if (renderedBytes > maxInlineBytes && newMeta.diagnostics) {
+		newMeta = { ...newMeta, diagnostics: undefined, diagnosticsOmitted: true };
+		renderedBytes = Buffer.byteLength(finalText, "utf-8") + Buffer.byteLength(formatOutputNotice(newMeta), "utf-8");
+	}
+	if (renderedBytes > maxInlineBytes) {
+		const compactTruncation = newMeta.truncation
+			? {
+					...newMeta.truncation,
+					artifactFailureDiagnostic: newMeta.truncation.artifactFailureDiagnostic
+						? truncateHeadBytes(newMeta.truncation.artifactFailureDiagnostic, 64).text
+						: undefined,
+					shownRange: undefined,
+					headRange: undefined,
+					tailRange: undefined,
+					nextOffset: undefined,
+				}
+			: undefined;
+		newMeta = { ...newMeta, truncation: compactTruncation, limits: undefined };
+		const noticeBytes = Buffer.byteLength(formatOutputNotice(newMeta), "utf-8");
+		const bodyBudget = Math.max(0, maxInlineBytes - noticeBytes);
+		const finalTruncated = truncateTail(finalText, { maxBytes: bodyBudget, maxLines: tailLines });
+		finalText = finalTruncated.content;
+		if (newMeta.truncation) {
+			newMeta = {
+				...newMeta,
+				truncation: {
+					...newMeta.truncation,
+					direction: "tail",
+					truncatedBy: "bytes",
+					outputBytes: Buffer.byteLength(finalText, "utf-8"),
+					outputLines: finalText.length > 0 ? finalText.split("\n").length : 0,
+				},
+			};
+		}
+	}
+	const boundedContent = newContent.map(block => (block.type === "text" ? { ...block, text: finalText } : block));
 	const newDetails = { ...(result.details ?? {}), meta: newMeta };
-	return { ...result, content: newContent, details: newDetails };
+	return { ...result, content: boundedContent, details: newDetails };
+}
+
+export async function finalizeToolResultForDelivery(
+	result: AgentToolResult,
+	toolName: string,
+	context: AgentToolContext | undefined,
+): Promise<AgentToolResult> {
+	let finalized = await sanitizeArtifactIdEvidence(result, context);
+	finalized = await spillLargeResultToArtifact(finalized, toolName, context);
+	finalized = await enforceInlineResultBackstop(finalized, toolName, context);
+	const meta: OutputMeta | undefined = finalized.details?.meta;
+	return meta ? { ...finalized, content: appendOutputNotice(finalized.content, meta) } : finalized;
 }
 
 // =============================================================================
@@ -1087,24 +1690,11 @@ async function wrappedExecute(
 	const originalExecute = this[kUnwrappedExecute];
 
 	try {
-		let result = await originalExecute.call(this, toolCallId, params, signal, onUpdate, context);
-
-		// Spill large results to artifact, truncate to tail
-		result = await spillLargeResultToArtifact(result, this.name, context);
-
-		// Absolute inline-size backstop: catches oversized text the threshold spill
-		// skipped (read exemption, tools with pre-existing partial artifact meta).
-		result = await enforceInlineResultBackstop(result, this.name, context);
-
-		// Append notices from meta
-		const meta: OutputMeta | undefined = result.details?.meta;
-		if (meta) {
-			return {
-				...result,
-				content: appendOutputNotice(result.content, meta),
-			};
-		}
-		return result;
+		return await finalizeToolResultForDelivery(
+			await originalExecute.call(this, toolCallId, params, signal, onUpdate, context),
+			this.name,
+			context,
+		);
 	} catch (e) {
 		// Re-throw with formatted message so agent-loop sets isError flag
 		throw new Error(renderError(e));