@gajae-code/coding-agent 0.12.4 → 0.12.6

package/src/exec/bash-executor.ts

@@ -4,18 +4,28 @@
  * Uses brush-core via native bindings for shell execution.
  */
 import * as fs from "node:fs/promises";
-import { executeShell, type MinimizerOptions, Shell } from "@gajae-code/natives";
+import {
+	executeShell,
+	type MinimizerOptions,
+	type ShellRunResult as NativeShellRunResult,
+	Shell,
+} from "@gajae-code/natives";
 import { postmortem } from "@gajae-code/utils";
 import { Settings, type ShellMinimizerSettings } from "../config/settings";
 import { formatCrashDiagnosticNotice, writeCrashReport } from "../debug/crash-diagnostics";
 import {
-	DEFAULT_ARTIFACT_MAX_BYTES,
 	DEFAULT_MAX_BYTES,
 	OutputSink,
+	type OutputSummary,
 	type TerminalArtifactPublisher,
 	truncateHeadBytes,
 } from "../session/streaming-output";
-import { formatArtifactReference, resolveOutputMaxColumns, resolveOutputSinkHeadBytes } from "../tools/output-meta";
+import {
+	formatArtifactEvidenceNotice,
+	isValidArtifactId,
+	resolveOutputMaxColumns,
+	resolveOutputSinkHeadBytes,
+} from "../tools/output-meta";
 import { getOrCreateSnapshot } from "../utils/shell-snapshot";
 import { NON_INTERACTIVE_ENV } from "./non-interactive-env";
 
@@ -25,7 +35,19 @@ export interface BashArtifactSaveSummary {
 	omittedBytes?: number;
 }
 
-export type BashMinimizedSaveReturn = BashArtifactSaveResult | BashArtifactSaveSummary | string | undefined;
+export type BashMinimizedSaveReturn = BashArtifactSaveResult | BashArtifactSaveSummary | undefined;
+
+interface ValidatedNativeMinimized {
+	filter: string;
+	text: string;
+	originalText: string;
+	inputBytes: number;
+	outputBytes: number;
+}
+
+const MINIMIZED_SAVE_WAIT_MS = 500;
+const MINIMIZED_SAVE_PENDING_LIMIT = 64;
+const pendingMinimizedSaves = new Set<Promise<unknown>>();
 
 export type BashArtifactSaveResult =
 	| { status: "saved"; artifactId: string; complete: true; omittedBytes?: undefined }
@@ -33,18 +55,16 @@ export type BashArtifactSaveResult =
 	| { status: "unavailable" }
 	| { status: "failed"; diagnostic: string };
 
-function summarizeLegacyArtifactSave(artifactId: string, originalText: string): BashArtifactSaveResult {
-	const inputBytes = Buffer.byteLength(originalText, "utf-8");
-	if (inputBytes <= DEFAULT_ARTIFACT_MAX_BYTES) {
-		return { status: "saved", artifactId, complete: true };
-	}
-	const retainedBytes = truncateHeadBytes(originalText, DEFAULT_ARTIFACT_MAX_BYTES).bytes;
-	return {
-		status: "saved",
-		artifactId,
-		complete: false,
-		omittedBytes: inputBytes - retainedBytes,
-	};
+function isValidOmittedBytes(omittedBytes: number): boolean {
+	return Number.isSafeInteger(omittedBytes) && omittedBytes >= 0;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null;
+}
+
+function invalidArtifactSaveShape(): BashArtifactSaveResult {
+	return { status: "failed", diagnostic: "artifact save returned an invalid result" };
 }
 
 function normalizeExplicitSavedArtifact(
@@ -52,6 +72,12 @@ function normalizeExplicitSavedArtifact(
 	complete: boolean,
 	omittedBytes: number | undefined,
 ): BashArtifactSaveResult {
+	if (!isValidArtifactId(artifactId)) {
+		return { status: "failed", diagnostic: "artifact save reported an invalid artifact id" };
+	}
+	if (omittedBytes !== undefined && !isValidOmittedBytes(omittedBytes)) {
+		return { status: "failed", diagnostic: "artifact save reported invalid omitted bytes" };
+	}
 	if (complete) {
 		return (omittedBytes ?? 0) > 0
 			? { status: "failed", diagnostic: "artifact save reported complete output with omitted bytes" }
@@ -62,35 +88,143 @@ function normalizeExplicitSavedArtifact(
 		: { status: "failed", diagnostic: "artifact save reported incomplete output without omitted bytes" };
 }
 
-function normalizeMinimizedSaveResult(value: BashMinimizedSaveReturn, originalText: string): BashArtifactSaveResult {
-	if (typeof value === "string") return summarizeLegacyArtifactSave(value, originalText);
-	if (!value) return { status: "unavailable" };
-	if (!("status" in value)) {
-		return normalizeExplicitSavedArtifact(value.artifactId, value.complete, value.omittedBytes);
+function normalizeMinimizedSaveResult(value: unknown): BashArtifactSaveResult {
+	if (value === undefined) return { status: "unavailable" };
+	if (typeof value === "string") return invalidArtifactSaveShape();
+	if (!isRecord(value)) return invalidArtifactSaveShape();
+
+	const status = value.status;
+	if (status === "unavailable") return { status: "unavailable" };
+	if (status === "failed") {
+		const diagnostic = value.diagnostic;
+		return typeof diagnostic === "string" && diagnostic.trim().length > 0
+			? { status: "failed", diagnostic: diagnostic.slice(0, 512) }
+			: invalidArtifactSaveShape();
+	}
+	if (status !== undefined && status !== "saved") return invalidArtifactSaveShape();
+	if (typeof value.artifactId !== "string" || typeof value.complete !== "boolean") {
+		return invalidArtifactSaveShape();
+	}
+	if (value.omittedBytes !== undefined && typeof value.omittedBytes !== "number") {
+		return invalidArtifactSaveShape();
 	}
-	if (value.status !== "saved") return value;
 	return normalizeExplicitSavedArtifact(value.artifactId, value.complete, value.omittedBytes);
 }
 
-export function normalizeMinimizedSaveResultForTests(
-	value: BashMinimizedSaveReturn,
-	originalText: string,
-): BashArtifactSaveResult {
-	return normalizeMinimizedSaveResult(value, originalText);
+export function normalizeMinimizedSaveResultForTests(value: unknown, _originalText?: string): BashArtifactSaveResult {
+	return normalizeMinimizedSaveResult(value);
+}
+
+function normalizeNativeMinimized(value: unknown): { minimized?: ValidatedNativeMinimized; malformed: boolean } {
+	if (value === undefined) return { malformed: false };
+	if (!isRecord(value)) return { malformed: true };
+	const { filter, text, originalText, inputBytes, outputBytes } = value;
+	if (
+		typeof filter !== "string" ||
+		typeof text !== "string" ||
+		typeof originalText !== "string" ||
+		!Number.isSafeInteger(inputBytes) ||
+		!Number.isSafeInteger(outputBytes) ||
+		(inputBytes as number) < 0 ||
+		(outputBytes as number) < 0 ||
+		Buffer.byteLength(originalText, "utf-8") !== inputBytes ||
+		Buffer.byteLength(text, "utf-8") !== outputBytes
+	) {
+		return { malformed: true };
+	}
+	return {
+		minimized: { filter, text, originalText, inputBytes: inputBytes as number, outputBytes: outputBytes as number },
+		malformed: false,
+	};
+}
+
+function nativeCaptureStatusIncomplete(result: NativeShellRunResult | undefined): boolean {
+	if (!result) return true;
+	const capture = result.outputCaptureIncomplete as unknown;
+	const saturated = result.outputLossCountSaturated as unknown;
+	return (
+		(capture !== undefined && typeof capture !== "boolean") ||
+		(saturated !== undefined && typeof saturated !== "boolean") ||
+		capture === true ||
+		saturated === true
+	);
+}
+
+async function saveMinimizedArtifactBounded(
+	operation: () => Promise<BashMinimizedSaveReturn>,
+): Promise<BashArtifactSaveResult> {
+	if (pendingMinimizedSaves.size >= MINIMIZED_SAVE_PENDING_LIMIT) {
+		return { status: "failed", diagnostic: "pending minimized artifact save limit reached" };
+	}
+	const promise = Promise.resolve().then(operation);
+	pendingMinimizedSaves.add(promise);
+	void promise.then(
+		() => pendingMinimizedSaves.delete(promise),
+		() => pendingMinimizedSaves.delete(promise),
+	);
+	const outcome = await Promise.race([
+		promise.then(
+			value => ({ status: "ok" as const, value }),
+			error => ({ status: "failed" as const, diagnostic: error instanceof Error ? error.message : String(error) }),
+		),
+		Bun.sleep(MINIMIZED_SAVE_WAIT_MS).then(() => ({
+			status: "failed" as const,
+			diagnostic: `did not settle within ${MINIMIZED_SAVE_WAIT_MS}ms`,
+		})),
+	]);
+	if (outcome.status === "failed") {
+		return {
+			status: "failed",
+			diagnostic: truncateHeadBytes(outcome.diagnostic.replace(/\s+/gu, " ").trim(), 512).text,
+		};
+	}
+	return normalizeMinimizedSaveResult(outcome.value);
 }
 
 function completeRawArtifactAvailable(summary: {
 	artifactId?: string;
 	artifactTruncatedBytes?: number;
+	sourceTruncatedBytes?: number;
+	sourceCaptureIncomplete?: boolean;
 	artifactFailureDiagnostic?: string;
 }): boolean {
 	return (
 		summary.artifactId !== undefined &&
 		(summary.artifactTruncatedBytes ?? 0) <= 0 &&
+		(summary.sourceTruncatedBytes ?? 0) <= 0 &&
+		!summary.sourceCaptureIncomplete &&
 		summary.artifactFailureDiagnostic === undefined
 	);
 }
 
+function applyShellCallbackLoss(
+	summary: OutputSummary,
+	droppedOutputBytes: number | undefined,
+	droppedOutputChunks: number | undefined,
+	sourceCaptureIncomplete = false,
+): OutputSummary {
+	const bytesValid =
+		droppedOutputBytes === undefined || (Number.isSafeInteger(droppedOutputBytes) && droppedOutputBytes >= 0);
+	const chunksValid =
+		droppedOutputChunks === undefined || (Number.isSafeInteger(droppedOutputChunks) && droppedOutputChunks >= 0);
+	const counterPairValid = (droppedOutputBytes === undefined) === (droppedOutputChunks === undefined);
+	const knownDroppedBytes = bytesValid && droppedOutputBytes !== undefined && droppedOutputBytes > 0;
+	const knownDroppedChunks = chunksValid && droppedOutputChunks !== undefined && droppedOutputChunks > 0;
+	const captureIncomplete =
+		sourceCaptureIncomplete ||
+		!bytesValid ||
+		!chunksValid ||
+		!counterPairValid ||
+		knownDroppedBytes !== knownDroppedChunks;
+	if (!knownDroppedBytes && !captureIncomplete) return summary;
+	return {
+		...summary,
+		truncated: true,
+		...(knownDroppedBytes ? { sourceTruncatedBytes: droppedOutputBytes } : {}),
+		...(captureIncomplete ? { sourceCaptureIncomplete: true } : {}),
+	};
+}
+
 function appendModelNotice(output: string, notice: string): string {
 	const separator = output.length > 0 && !output.endsWith("\n") ? "\n" : "";
 	return `${output}${separator}${notice}\n`;
@@ -98,7 +232,13 @@ function appendModelNotice(output: string, notice: string): string {
 
 function minimizedSaveNotice(
 	result: BashArtifactSaveResult,
-	summary: { artifactId?: string; artifactTruncatedBytes?: number; artifactFailureDiagnostic?: string },
+	summary: {
+		artifactId?: string;
+		artifactTruncatedBytes?: number;
+		sourceTruncatedBytes?: number;
+		sourceCaptureIncomplete?: boolean;
+		artifactFailureDiagnostic?: string;
+	},
 ): string | undefined {
 	if (result.status === "failed") return `Bash output artifact save failed: ${result.diagnostic}`;
 	if (result.status === "unavailable" && !completeRawArtifactAvailable(summary)) {
@@ -107,13 +247,6 @@ function minimizedSaveNotice(
 	return undefined;
 }
 
-function minimizedArtifactFooter(result: Extract<BashArtifactSaveResult, { status: "saved" }>): string {
-	const reference = result.complete
-		? `artifact://${result.artifactId}`
-		: formatArtifactReference(result.artifactId, result.omittedBytes);
-	return `[raw output: ${reference}]`;
-}
-
 export interface BashExecutorOptions {
 	/**
 	 * Invoked when the native minimizer rewrote the command's output, giving
@@ -170,40 +303,122 @@ export interface BashResult {
 	outputBytes: number;
 	artifactId?: string;
 	artifactTruncatedBytes?: number;
+	/** Bytes dropped before the Bash executor received the native output stream. */
+	sourceTruncatedBytes?: number;
+	/** Exact source capture completeness could not be proven. */
+	sourceCaptureIncomplete?: boolean;
 	artifactFailureDiagnostic?: string;
 }
 
 const shellSessions = new Map<string, Shell>();
-const brokenShellSessions = new Set<string>();
+const brokenShellSessions = new Map<string, Shell>();
 const retiringShellSessions = new Set<Shell>();
-// Cover pi-shell's normal cancellation kill waves without turning a stalled
-// native cleanup into a multi-second JavaScript tool stall.
+const shellInFlightRuns = new Map<Shell, number>();
+const shellSessionKeys = new Map<Shell, string>();
+const MAX_OWNED_SHELL_SESSIONS = 64;
+let shellSessionAdmissionTail = Promise.resolve();
+
+async function withShellSessionAdmission<T>(operation: () => Promise<T>): Promise<T> {
+	const previous = shellSessionAdmissionTail;
+	const release = Promise.withResolvers<void>();
+	shellSessionAdmissionTail = previous.then(() => release.promise);
+	await previous;
+	try {
+		return await operation();
+	} finally {
+		release.resolve();
+	}
+}
+
+function touchShellSession(sessionKey: string, shellSession: Shell): void {
+	if (shellSessions.get(sessionKey) !== shellSession) return;
+	shellSessions.delete(sessionKey);
+	shellSessions.set(sessionKey, shellSession);
+}
+
+async function evictLeastRecentlyUsedIdleShell(): Promise<boolean> {
+	for (const [sessionKey, shellSession] of shellSessions) {
+		if ((shellInFlightRuns.get(shellSession) ?? 0) > 0) continue;
+		quarantineShellSession(sessionKey, shellSession);
+		const abortPromise = Promise.resolve()
+			.then(() => shellSession.abort())
+			.catch(() => undefined);
+		void abortPromise.finally(() => releaseQuarantinedShellIfIdle(sessionKey, shellSession));
+		return Promise.race([abortPromise.then(() => true), Bun.sleep(CANCEL_CLEANUP_WAIT_MS).then(() => false)]);
+	}
+	return false;
+}
+
+function beginShellRun(shellSession: Shell): void {
+	shellInFlightRuns.set(shellSession, (shellInFlightRuns.get(shellSession) ?? 0) + 1);
+}
+
+function releaseQuarantinedShellIfIdle(sessionKey: string, shellSession: Shell): void {
+	if ((shellInFlightRuns.get(shellSession) ?? 0) > 0) return;
+	clearBrokenShellSession(sessionKey, shellSession);
+	retiringShellSessions.delete(shellSession);
+	shellSessionKeys.delete(shellSession);
+}
+
+function endShellRun(sessionKey: string, shellSession: Shell): void {
+	const remaining = Math.max(0, (shellInFlightRuns.get(shellSession) ?? 1) - 1);
+	if (remaining > 0) {
+		shellInFlightRuns.set(shellSession, remaining);
+		return;
+	}
+	const quarantined = brokenShellSessions.get(sessionKey) === shellSession;
+	shellInFlightRuns.delete(shellSession);
+	if (quarantined) releaseQuarantinedShellIfIdle(sessionKey, shellSession);
+}
+
+function quarantineShellSession(sessionKey: string, shellSession: Shell): void {
+	retiringShellSessions.add(shellSession);
+	brokenShellSessions.set(sessionKey, shellSession);
+	shellSessionKeys.set(shellSession, sessionKey);
+	if (shellSessions.get(sessionKey) === shellSession) shellSessions.delete(sessionKey);
+}
+// Give ordinary native cancellation time to settle without turning a stalled
+// cleanup into a multi-second JavaScript tool delay.
 const CANCEL_CLEANUP_WAIT_MS = 400;
+function clearBrokenShellSession(sessionKey: string, shellSession: Shell): void {
+	if (brokenShellSessions.get(sessionKey) === shellSession) brokenShellSessions.delete(sessionKey);
+}
+
+interface AbortCleanupOutcome {
+	settled: boolean;
+	result?: NativeShellRunResult;
+}
 
-/** Number of persistent shell sessions currently retained (owner gauge). */
+/** Number of persistent and retiring shell sessions currently retained (owner gauge). */
 export function getShellSessionCount(): number {
-	return shellSessions.size;
+	return new Set([...shellSessions.values(), ...retiringShellSessions, ...shellSessionKeys.keys()]).size;
 }
 
 /**
- * Dispose all persistent shell sessions: abort in-flight work and drop the
- * strong references so the native shells can be finalized. Healthy persistent
- * sessions are otherwise retained for the whole process lifetime (MEM-7). This
- * is registered as a postmortem cleanup so shutdown/signals release native
- * shell resources, and is also callable directly (e.g. on owner teardown).
+ * Dispose all persistent shell sessions without waiting forever on a native
+ * abort that failed to settle. Quarantine entries are owner-scoped so a late
+ * finalizer cannot erase a successor shell's quarantine.
  */
 export async function disposeAllShellSessions(): Promise<void> {
-	// Snapshot and drop strong references up front so concurrent callers cannot
-	// reuse a session that is being torn down, then await every native abort so
-	// shutdown/signal cleanup does not return before resources are released.
-	// Include retiring shells whose JS call returned after bounded abort cleanup
-	// while the native run is still unwinding; they are no longer reusable but
-	// remain owned until their run promise settles.
 	const sessions = new Set([...shellSessions.values(), ...retiringShellSessions]);
+	for (const session of sessions) {
+		const sessionKey = shellSessionKeys.get(session);
+		if (sessionKey) quarantineShellSession(sessionKey, session);
+		else retiringShellSessions.add(session);
+	}
 	shellSessions.clear();
-	retiringShellSessions.clear();
-	brokenShellSessions.clear();
-	await Promise.allSettled([...sessions].map(session => session.abort()));
+	await Promise.all(
+		[...sessions].map(async session => {
+			const sessionKey = shellSessionKeys.get(session);
+			const abortPromise = Promise.resolve()
+				.then(() => session.abort())
+				.catch(() => undefined);
+			if (sessionKey) {
+				void abortPromise.finally(() => releaseQuarantinedShellIfIdle(sessionKey, session));
+			}
+			await Promise.race([abortPromise, Bun.sleep(CANCEL_CLEANUP_WAIT_MS)]);
+		}),
+	);
 }
 
 postmortem.register("bash-executor:shell-sessions", () => disposeAllShellSessions());
@@ -233,6 +448,9 @@ export function buildMinimizerOptions(group: ShellMinimizerSettings): MinimizerO
 }
 
 export async function executeBash(command: string, options?: BashExecutorOptions): Promise<BashResult> {
+	if (options?.artifactId !== undefined && !isValidArtifactId(options.artifactId)) {
+		throw new Error("Invalid Bash artifact id");
+	}
 	const settings = await Settings.init();
 	const { shell, env: shellEnv, prefix } = settings.getShellConfig();
 	const configuredPrefix = options?.ignoreShellPrefix ? undefined : prefix;
@@ -279,51 +497,71 @@ export async function executeBash(command: string, options?: BashExecutorOptions
 		};
 	}
 
-	const usePersistentShell = options?.oneShot !== true;
-	const sessionKey = buildSessionKey(shell, configuredPrefix, snapshotPath, shellEnv, options?.sessionKey, minimizer);
-	const persistentSessionBroken = usePersistentShell && brokenShellSessions.has(sessionKey);
-
-	let shellSession = persistentSessionBroken || !usePersistentShell ? undefined : shellSessions.get(sessionKey);
-	if (!shellSession && !persistentSessionBroken && usePersistentShell) {
-		shellSession = new Shell({
-			sessionEnv: shellEnv,
-			snapshotPath: snapshotPath ?? undefined,
-			minimizer,
-		});
-		shellSessions.set(sessionKey, shellSession);
-	}
 	const userSignal = options?.signal;
 	const runAbortController = new AbortController();
 	const abortCurrentExecution = () => {
-		if (!runAbortController.signal.aborted) {
-			runAbortController.abort();
-		}
-		if (shellSession && !abortPromise) {
-			abortPromise = shellSession.abort();
-		}
+		if (!runAbortController.signal.aborted) runAbortController.abort();
 	};
 	const abortDeferred = Promise.withResolvers<"abort">();
-	let abortPromise: Promise<unknown> | undefined;
 	const abortHandler = () => {
 		abortCurrentExecution();
 		abortDeferred.resolve("abort");
 	};
-	const awaitAbortCleanup = async (runPromise: Promise<unknown>): Promise<boolean> => {
-		const settled = await Promise.race([
+	userSignal?.addEventListener("abort", abortHandler, { once: true });
+	if (userSignal?.aborted) abortHandler();
+
+	const usePersistentShell = options?.oneShot !== true;
+	const sessionKey = buildSessionKey(shell, configuredPrefix, snapshotPath, shellEnv, options?.sessionKey, minimizer);
+	let shellSession: Shell | undefined;
+	try {
+		shellSession = usePersistentShell
+			? await withShellSessionAdmission(async () => {
+					if (brokenShellSessions.has(sessionKey)) return undefined;
+					const existing = shellSessions.get(sessionKey);
+					if (existing) {
+						touchShellSession(sessionKey, existing);
+						beginShellRun(existing);
+						return existing;
+					}
+					if (getShellSessionCount() >= MAX_OWNED_SHELL_SESSIONS) {
+						const evicted = await evictLeastRecentlyUsedIdleShell();
+						if (!evicted || getShellSessionCount() >= MAX_OWNED_SHELL_SESSIONS) {
+							throw new Error(`Bash shell session limit reached (${MAX_OWNED_SHELL_SESSIONS})`);
+						}
+					}
+					const created = new Shell({
+						sessionEnv: shellEnv,
+						snapshotPath: snapshotPath ?? undefined,
+						minimizer,
+					});
+					shellSessions.set(sessionKey, created);
+					shellSessionKeys.set(created, sessionKey);
+					beginShellRun(created);
+					return created;
+				})
+			: undefined;
+	} catch (error) {
+		userSignal?.removeEventListener("abort", abortHandler);
+		throw error;
+	}
+	if (userSignal?.aborted) {
+		if (shellSession) endShellRun(sessionKey, shellSession);
+		userSignal.removeEventListener("abort", abortHandler);
+		return {
+			exitCode: undefined,
+			cancelled: true,
+			...(await sink.dump("Command cancelled")),
+		};
+	}
+
+	const awaitAbortCleanup = (runPromise: Promise<NativeShellRunResult>): Promise<AbortCleanupOutcome> =>
+		Promise.race([
 			runPromise.then(
-				() => true,
-				() => true,
+				result => ({ settled: true, result }) satisfies AbortCleanupOutcome,
+				() => ({ settled: true }) satisfies AbortCleanupOutcome,
 			),
-			Bun.sleep(CANCEL_CLEANUP_WAIT_MS).then(() => false),
+			Bun.sleep(CANCEL_CLEANUP_WAIT_MS).then(() => ({ settled: false }) satisfies AbortCleanupOutcome),
 		]);
-		if (abortPromise) {
-			await Promise.race([abortPromise.catch(() => undefined), Bun.sleep(CANCEL_CLEANUP_WAIT_MS)]);
-		}
-		return settled;
-	};
-	if (userSignal) {
-		userSignal.addEventListener("abort", abortHandler, { once: true });
-	}
 
 	let timeoutTimer: NodeJS.Timeout | undefined;
 	const timeoutDeferred = Promise.withResolvers<"timeout">();
@@ -337,11 +575,12 @@ export async function executeBash(command: string, options?: BashExecutorOptions
 	}
 
 	let resetSession = false;
-	let runSettled = false;
 
 	try {
-		const runPromise = shellSession
-			? shellSession.run(
+		let runPromise: Promise<NativeShellRunResult>;
+		if (shellSession) {
+			try {
+				runPromise = shellSession.run(
 					{
 						command: finalCommand,
 						cwd: commandCwd,
@@ -350,28 +589,31 @@ export async function executeBash(command: string, options?: BashExecutorOptions
 						signal: runAbortController.signal,
 					},
 					(err, chunk) => {
-						if (!err) {
-							enqueueChunk(chunk);
-						}
-					},
-				)
-			: executeShell(
-					{
-						command: finalCommand,
-						cwd: commandCwd,
-						env: commandEnv,
-						sessionEnv: shellEnv,
-						snapshotPath: snapshotPath ?? undefined,
-						minimizer,
-						timeoutMs: executionTimeoutMs,
-						signal: runAbortController.signal,
-					},
-					(err, chunk) => {
-						if (!err) {
-							enqueueChunk(chunk);
-						}
+						if (!err) enqueueChunk(chunk);
 					},
 				);
+			} catch (error) {
+				endShellRun(sessionKey, shellSession);
+				throw error;
+			}
+			void runPromise.finally(() => endShellRun(sessionKey, shellSession)).catch(() => undefined);
+		} else {
+			runPromise = executeShell(
+				{
+					command: finalCommand,
+					cwd: commandCwd,
+					env: commandEnv,
+					sessionEnv: shellEnv,
+					snapshotPath: snapshotPath ?? undefined,
+					minimizer,
+					timeoutMs: executionTimeoutMs,
+					signal: runAbortController.signal,
+				},
+				(err, chunk) => {
+					if (!err) enqueueChunk(chunk);
+				},
+			);
+		}
 
 		const winner = await Promise.race([
 			runPromise.then(result => ({ kind: "result" as const, result })),
@@ -380,44 +622,37 @@ export async function executeBash(command: string, options?: BashExecutorOptions
 		]);
 
 		if (winner.kind === "timeout" || winner.kind === "abort") {
+			const abortOutcome = await awaitAbortCleanup(runPromise);
 			acceptingChunks = false;
 			if (shellSession) {
 				resetSession = true;
-				retiringShellSessions.add(shellSession);
-				brokenShellSessions.add(sessionKey);
-				shellSessions.delete(sessionKey);
-				runSettled = await awaitAbortCleanup(runPromise);
-				if (runSettled) {
-					brokenShellSessions.delete(sessionKey);
-					retiringShellSessions.delete(shellSession);
-				} else {
-					void runPromise
-						.finally(() => {
-							brokenShellSessions.delete(sessionKey);
-							retiringShellSessions.delete(shellSession);
-							if (shellSessions.get(sessionKey) === shellSession) {
-								shellSessions.delete(sessionKey);
-							}
-						})
-						.catch(() => undefined);
-				}
-			} else {
+				quarantineShellSession(sessionKey, shellSession);
+				releaseQuarantinedShellIfIdle(sessionKey, shellSession);
+			} else if (!abortOutcome.settled) {
 				void runPromise.catch(() => undefined);
 			}
-			return {
-				exitCode: undefined,
-				cancelled: true,
-				...(await sink.dump(
+			const summary = applyShellCallbackLoss(
+				await sink.dump(
 					winner.kind === "timeout" && baseTimeoutMs !== undefined
 						? `Command timed out after ${Math.round(baseTimeoutMs / 1000)} seconds`
 						: "Command cancelled",
-				)),
+				),
+				abortOutcome.result?.droppedOutputBytes,
+				abortOutcome.result?.droppedOutputChunks,
+				nativeCaptureStatusIncomplete(abortOutcome.result),
+			);
+			return {
+				exitCode: undefined,
+				cancelled: true,
+				...summary,
 			};
 		}
 		if (timeoutTimer) {
 			clearTimeout(timeoutTimer);
 			timeoutTimer = undefined;
 		}
+		const minimizedEvidence = normalizeNativeMinimized(winner.result.minimized);
+		const nativeEvidenceIncomplete = nativeCaptureStatusIncomplete(winner.result) || minimizedEvidence.malformed;
 
 		// Handle timeout
 		if (winner.result.timedOut) {
@@ -428,7 +663,12 @@ export async function executeBash(command: string, options?: BashExecutorOptions
 			return {
 				exitCode: undefined,
 				cancelled: true,
-				...(await sink.dump(annotation)),
+				...applyShellCallbackLoss(
+					await sink.dump(annotation),
+					winner.result.droppedOutputBytes,
+					winner.result.droppedOutputChunks,
+					nativeEvidenceIncomplete,
+				),
 			};
 		}
 
@@ -438,7 +678,12 @@ export async function executeBash(command: string, options?: BashExecutorOptions
 			return {
 				exitCode: undefined,
 				cancelled: true,
-				...(await sink.dump("Command cancelled")),
+				...applyShellCallbackLoss(
+					await sink.dump("Command cancelled"),
+					winner.result.droppedOutputBytes,
+					winner.result.droppedOutputChunks,
+					nativeEvidenceIncomplete,
+				),
 			};
 		}
 
@@ -446,21 +691,24 @@ export async function executeBash(command: string, options?: BashExecutorOptions
 		// raw stream for the minimized text, persist the original as a session
 		// artifact, and splice an artifact footer into the visible text so the agent
 		// can retrieve retained raw bytes without a false completeness claim.
-		const minimized = winner.result.minimized;
+		const minimized = minimizedEvidence.minimized;
 		let minimizedSaveResult: BashArtifactSaveResult | undefined;
 		if (minimized && minimized.text !== minimized.originalText) {
 			sink.replace(minimized.text);
-			const saved = options?.onMinimizedSave
-				? await options.onMinimizedSave(minimized.originalText, {
-						filter: minimized.filter,
-						inputBytes: minimized.inputBytes,
-						outputBytes: minimized.outputBytes,
-					})
-				: undefined;
-			minimizedSaveResult = normalizeMinimizedSaveResult(saved, minimized.originalText);
+			minimizedSaveResult = options?.onMinimizedSave
+				? await saveMinimizedArtifactBounded(() =>
+						options.onMinimizedSave!(minimized.originalText, {
+							filter: minimized.filter,
+							inputBytes: minimized.inputBytes,
+							outputBytes: minimized.outputBytes,
+						}),
+					)
+				: { status: "unavailable" };
 			if (minimizedSaveResult.status === "saved") {
-				const sep = minimized.text.endsWith("\n") ? "" : "\n";
-				sink.push(`${sep}${minimizedArtifactFooter(minimizedSaveResult)}\n`);
+				minimizedSaveResult = {
+					status: "failed",
+					diagnostic: "artifact save could not be verified in the current session",
+				};
 			}
 		}
 
@@ -480,7 +728,12 @@ export async function executeBash(command: string, options?: BashExecutorOptions
 		}
 
 		// Normal completion
-		const summary = await sink.dump();
+		const summary = applyShellCallbackLoss(
+			await sink.dump(),
+			winner.result.droppedOutputBytes,
+			winner.result.droppedOutputChunks,
+			nativeEvidenceIncomplete,
+		);
 		const saveNotice = minimizedSaveResult ? minimizedSaveNotice(minimizedSaveResult, summary) : undefined;
 		return {
 			exitCode: winner.result.exitCode,
@@ -490,7 +743,23 @@ export async function executeBash(command: string, options?: BashExecutorOptions
 		};
 	} catch (err) {
 		resetSession = true;
-		throw err;
+		acceptingChunks = false;
+		const captured = await sink.dump();
+		const rawErrorMessage = err instanceof Error ? err.message : String(err);
+		const boundedErrorMessage = truncateHeadBytes(rawErrorMessage, 1024);
+		const errorMessage = `${boundedErrorMessage.text}${
+			boundedErrorMessage.bytes < Buffer.byteLength(rawErrorMessage, "utf-8") ? "\n[native error truncated]" : ""
+		}`;
+		if (captured.totalBytes <= 0) {
+			throw new Error(
+				`Source capture completeness could not be proven before any output was retained\n\nNative shell execution failed: ${errorMessage}`,
+			);
+		}
+		const summary = applyShellCallbackLoss(captured, undefined, undefined, true);
+		const evidence = formatArtifactEvidenceNotice(summary);
+		const suffix = [evidence, `Native shell execution failed: ${errorMessage}`].filter(Boolean).join("\n\n");
+		const separator = summary.output.length > 0 ? (summary.output.endsWith("\n") ? "\n" : "\n\n") : "";
+		throw new Error(`${summary.output}${separator}${suffix}`);
 	} finally {
 		if (timeoutTimer) {
 			clearTimeout(timeoutTimer);
@@ -498,8 +767,13 @@ export async function executeBash(command: string, options?: BashExecutorOptions
 		if (userSignal) {
 			userSignal.removeEventListener("abort", abortHandler);
 		}
-		if (resetSession && runSettled && shellSessions.get(sessionKey) === shellSession) {
-			shellSessions.delete(sessionKey);
+		if (resetSession && shellSession) {
+			if (shellSessions.get(sessionKey) === shellSession) shellSessions.delete(sessionKey);
+			if ((shellInFlightRuns.get(shellSession) ?? 0) > 0) {
+				quarantineShellSession(sessionKey, shellSession);
+			} else {
+				releaseQuarantinedShellIfIdle(sessionKey, shellSession);
+			}
 		}
 	}
 }