@f5xc-salesdemos/xcsh 18.2.1 → 18.3.0

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@f5xc-salesdemos/xcsh",
-	"version": "18.2.1",
+	"version": "18.3.0",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://github.com/f5xc-salesdemos/xcsh",
 	"author": "Can Boluk",
@@ -47,12 +47,12 @@
 	"dependencies": {
 		"@agentclientprotocol/sdk": "0.16.1",
 		"@mozilla/readability": "^0.6",
-		"@f5xc-salesdemos/xcsh-stats": "18.2.1",
-		"@f5xc-salesdemos/pi-agent-core": "18.2.1",
-		"@f5xc-salesdemos/pi-ai": "18.2.1",
-		"@f5xc-salesdemos/pi-natives": "18.2.1",
-		"@f5xc-salesdemos/pi-tui": "18.2.1",
-		"@f5xc-salesdemos/pi-utils": "18.2.1",
+		"@f5xc-salesdemos/xcsh-stats": "18.3.0",
+		"@f5xc-salesdemos/pi-agent-core": "18.3.0",
+		"@f5xc-salesdemos/pi-ai": "18.3.0",
+		"@f5xc-salesdemos/pi-natives": "18.3.0",
+		"@f5xc-salesdemos/pi-tui": "18.3.0",
+		"@f5xc-salesdemos/pi-utils": "18.3.0",
 		"@sinclair/typebox": "^0.34",
 		"@xterm/headless": "^6.0",
 		"ajv": "^8.18",

package/src/internal-urls/build-info.generated.ts

@@ -17,17 +17,17 @@ export interface BuildInfo {
 }
 
 export const BUILD_INFO: BuildInfo = {
-	"version": "18.2.1",
-	"commit": "a9a7a85e9085f1327823664b584feaccf2c33527",
-	"shortCommit": "a9a7a85",
+	"version": "18.3.0",
+	"commit": "1d4143afd9489476ed3bf4dd6cfba1ffdd45b81a",
+	"shortCommit": "1d4143a",
 	"branch": "main",
-	"tag": "v18.2.1",
-	"commitDate": "2026-04-21T01:47:20Z",
-	"buildDate": "2026-04-21T02:13:22.611Z",
+	"tag": "v18.3.0",
+	"commitDate": "2026-04-21T02:39:53Z",
+	"buildDate": "2026-04-21T03:01:13.203Z",
 	"dirty": false,
 	"prNumber": "",
 	"repoUrl": "https://github.com/f5xc-salesdemos/xcsh",
 	"repoSlug": "f5xc-salesdemos/xcsh",
-	"commitUrl": "https://github.com/f5xc-salesdemos/xcsh/commit/a9a7a85e9085f1327823664b584feaccf2c33527",
-	"releaseUrl": "https://github.com/f5xc-salesdemos/xcsh/releases/tag/v18.2.1"
+	"commitUrl": "https://github.com/f5xc-salesdemos/xcsh/commit/1d4143afd9489476ed3bf4dd6cfba1ffdd45b81a",
+	"releaseUrl": "https://github.com/f5xc-salesdemos/xcsh/releases/tag/v18.3.0"
 };

package/src/modes/components/bash-execution.ts

@@ -7,6 +7,7 @@ import { Container, ImageProtocol, Loader, Spacer, TERMINAL, Text, type TUI } fr
 import { getSymbolTheme, highlightCode, theme } from "../../modes/theme/theme";
 import { formatTruncationMetaNotice, type TruncationMeta } from "../../tools/output-meta";
 import { getSixelLineMask, isSixelPassthroughEnabled, sanitizeWithOptionalSixelPassthrough } from "../../utils/sixel";
+import { sanitizeErrorMessage } from "../utils/sanitize-error-message";
 import { DynamicBorder } from "./dynamic-border";
 import { truncateToVisualLines } from "./visual-truncate";
 
@@ -43,8 +44,14 @@ const CHUNK_THROTTLE_MS = 50;
 
 export class BashExecutionComponent extends Container {
 	#outputLines: string[] = [];
-	#status: "running" | "complete" | "cancelled" | "error" = "running";
+	// Failure-mode taxonomy:
+	//   "complete"  — zero exit
+	//   "error"     — non-zero exit (shell reported failure)
+	//   "cancelled" — user cancelled (e.g. pressed Esc)
+	//   "errored"   — uncaught exception (executor threw; no exit code)
+	#status: "running" | "complete" | "cancelled" | "error" | "errored" = "running";
 	#exitCode: number | undefined = undefined;
+	#errorMessage: string | undefined = undefined;
 	#loader: Loader;
 	#truncation?: TruncationMeta;
 	#expanded = false;
@@ -136,6 +143,29 @@ export class BashExecutionComponent extends Container {
 		this.#displayDirty = true;
 	}
 
+	/**
+	 * Gutter-outcome for this execution once a terminal status has been set.
+	 * "error" for cancelled, non-zero exit, or an uncaught executor exception;
+	 * "success" for clean zero exit; undefined while still running.
+	 */
+	get outcome(): "success" | "error" | undefined {
+		if (this.#status === "running") return undefined;
+		return this.#status === "complete" ? "success" : "error";
+	}
+
+	/**
+	 * Terminal state for an uncaught executor exception — distinct from a
+	 * non-zero shell exit (which uses `setComplete`). Footer renders
+	 * `(error: <message>)`. Idempotent after the first terminal call.
+	 */
+	setError(err: Error | string): void {
+		if (this.#status !== "running") return;
+		this.#status = "errored";
+		this.#errorMessage = sanitizeErrorMessage(err instanceof Error ? err.message : String(err));
+		this.#loader.stop();
+		this.#updateDisplay();
+	}
+
 	setComplete(
 		exitCode: number | undefined,
 		cancelled: boolean,
@@ -227,6 +257,12 @@ export class BashExecutionComponent extends Container {
 				statusParts.push(theme.fg("warning", "(cancelled)"));
 			} else if (this.#status === "error") {
 				statusParts.push(theme.fg("error", `(exit ${this.#exitCode})`));
+			} else if (this.#status === "errored") {
+				// `\u00a0` (NBSP) keeps the wrapper joined to the message so
+				// the Text component does not wrap at "(error:_<msg>)" in
+				// narrow terminals. Falls back to "unknown" if setError was
+				// never called with a message.
+				statusParts.push(theme.fg("error", `(error:\u00a0${this.#errorMessage ?? "unknown"})`));
 			}
 
 			if (this.#truncation) {

package/src/modes/components/gutter-block.ts

@@ -16,13 +16,21 @@ export interface GutterConfig {
 	symbol: string;
 	/** Color function for active state (used for static active indicator) */
 	activeColorFn: (s: string) => string;
-	/** Color function for done state */
+	/**
+	 * Neutral done-state color. Used when `setDone()` is called without an
+	 * outcome, or when the specific outcome color function is not configured.
+	 */
 	doneColorFn: (s: string) => string;
+	/** Optional color function used for `setDone("success")`. */
+	doneSuccessColorFn?: (s: string) => string;
+	/** Optional color function used for `setDone("error")`. */
+	doneErrorColorFn?: (s: string) => string;
 	/** Whether to show spinner animation when active */
 	animated: boolean;
 }
 
 type GutterState = "active" | "done";
+type GutterOutcome = "success" | "error";
 
 /**
  * GutterBlock wraps a child component and prepends a 2-character left gutter
@@ -33,6 +41,7 @@ export class GutterBlock<T extends Component> implements Component {
 	#child: T;
 	#config: GutterConfig;
 	#state: GutterState;
+	#outcome?: GutterOutcome;
 	#ui: TUI;
 
 	// Spinner state
@@ -60,8 +69,9 @@ export class GutterBlock<T extends Component> implements Component {
 		return this.#state;
 	}
 
-	setDone(): void {
+	setDone(outcome?: GutterOutcome): void {
 		if (this.#state === "done") return;
+		this.#outcome = outcome;
 		this.#state = "done";
 		this.#stopSpinner();
 		this.#ui.requestRender();
@@ -125,7 +135,8 @@ export class GutterBlock<T extends Component> implements Component {
 
 	#buildGutterPrefix(): string {
 		if (this.#state === "done") {
-			return `${this.#config.doneColorFn(this.#config.symbol)} `;
+			const colorFn = this.#doneColorFnForOutcome();
+			return `${colorFn(this.#config.symbol)} `;
 		}
 
 		if (this.#config.animated) {
@@ -136,6 +147,16 @@ export class GutterBlock<T extends Component> implements Component {
 		return `${this.#config.activeColorFn(this.#config.symbol)} `;
 	}
 
+	#doneColorFnForOutcome(): (s: string) => string {
+		if (this.#outcome === "error" && this.#config.doneErrorColorFn) {
+			return this.#config.doneErrorColorFn;
+		}
+		if (this.#outcome === "success" && this.#config.doneSuccessColorFn) {
+			return this.#config.doneSuccessColorFn;
+		}
+		return this.#config.doneColorFn;
+	}
+
 	#startSpinner(): void {
 		this.#intervalId = setInterval(() => {
 			this.#currentFrame = (this.#currentFrame + 1) % this.#spinnerFrames.length;
@@ -183,12 +204,22 @@ export class DisposableContainer extends Container {
 // Factory functions
 // ============================================================================
 
-/** Animated ● gutter for active tool calls — spinner in spinnerAccent, done in dim */
+/**
+ * Animated ● gutter for tool calls and slash-command executions.
+ * Active: spinner in `spinnerAccent`.
+ * Done (unknown outcome): `dim` — neutral "completed" color when the call
+ *   site does not have success/error information.
+ * Done (success): `gutterSuccess` (falls back to `success` when the theme
+ *   does not define the dedicated token).
+ * Done (error): `gutterError` (falls back to `error`).
+ */
 export function createToolGutter<T extends Component>(ui: TUI, child: T): GutterBlock<T> {
 	return new GutterBlock(ui, child, {
 		symbol: "●",
 		activeColorFn: (s: string) => theme.fg("spinnerAccent", s),
 		doneColorFn: (s: string) => theme.fg("dim", s),
+		doneSuccessColorFn: (s: string) => theme.fg("gutterSuccess", s),
+		doneErrorColorFn: (s: string) => theme.fg("gutterError", s),
 		animated: true,
 	});
 }

package/src/modes/components/python-execution.ts

@@ -7,6 +7,7 @@ import { sanitizeText } from "@f5xc-salesdemos/pi-natives";
 import { Container, Loader, Spacer, Text, type TUI } from "@f5xc-salesdemos/pi-tui";
 import { getSymbolTheme, highlightCode, theme } from "../../modes/theme/theme";
 import { formatTruncationMetaNotice, type TruncationMeta } from "../../tools/output-meta";
+import { sanitizeErrorMessage } from "../utils/sanitize-error-message";
 import { DynamicBorder } from "./dynamic-border";
 import { truncateToVisualLines } from "./visual-truncate";
 
@@ -36,8 +37,14 @@ function highlightIfStructured(lines: string[]): string[] | undefined {
 
 export class PythonExecutionComponent extends Container {
 	#outputLines: string[] = [];
-	#status: "running" | "complete" | "cancelled" | "error" = "running";
+	// Failure-mode taxonomy:
+	//   "complete"  — zero exit
+	//   "error"     — non-zero exit (interpreter reported failure)
+	//   "cancelled" — user cancelled
+	//   "errored"   — uncaught exception (executor threw; no exit code)
+	#status: "running" | "complete" | "cancelled" | "error" | "errored" = "running";
 	#exitCode: number | undefined = undefined;
+	#errorMessage: string | undefined = undefined;
 	#loader: Loader;
 	#truncation?: TruncationMeta;
 	#expanded = false;
@@ -107,6 +114,29 @@ export class PythonExecutionComponent extends Container {
 		this.#updateDisplay();
 	}
 
+	/**
+	 * Gutter-outcome for this execution once a terminal status has been set.
+	 * "error" for cancelled, non-zero exit, or an uncaught executor exception;
+	 * "success" for clean zero exit; undefined while still running.
+	 */
+	get outcome(): "success" | "error" | undefined {
+		if (this.#status === "running") return undefined;
+		return this.#status === "complete" ? "success" : "error";
+	}
+
+	/**
+	 * Terminal state for an uncaught executor exception — distinct from a
+	 * non-zero interpreter exit (which uses `setComplete`). Footer renders
+	 * `(error: <message>)`. Idempotent after the first terminal call.
+	 */
+	setError(err: Error | string): void {
+		if (this.#status !== "running") return;
+		this.#status = "errored";
+		this.#errorMessage = sanitizeErrorMessage(err instanceof Error ? err.message : String(err));
+		this.#loader.stop();
+		this.#updateDisplay();
+	}
+
 	setComplete(
 		exitCode: number | undefined,
 		cancelled: boolean,
@@ -174,6 +204,11 @@ export class PythonExecutionComponent extends Container {
 				statusParts.push(theme.fg("warning", "(cancelled)"));
 			} else if (this.#status === "error") {
 				statusParts.push(theme.fg("error", `(exit ${this.#exitCode})`));
+			} else if (this.#status === "errored") {
+				// `\u00a0` (NBSP) keeps the wrapper joined to the message so
+				// the Text component does not wrap at "(error:_<msg>)" in
+				// narrow terminals.
+				statusParts.push(theme.fg("error", `(error:\u00a0${this.#errorMessage ?? "unknown"})`));
 			}
 
 			if (this.#truncation) {

package/src/modes/components/user-message.ts

@@ -1,4 +1,4 @@
-import { Container, Markdown } from "@f5xc-salesdemos/pi-tui";
+import { Container, Markdown, padding, Spacer, visibleWidth } from "@f5xc-salesdemos/pi-tui";
 import { getMarkdownTheme, theme } from "../../modes/theme/theme";
 
 // OSC 133 shell integration: marks prompt zones for terminal multiplexers
@@ -6,12 +6,18 @@ const OSC133_ZONE_START = "\x1b]133;A\x07";
 const OSC133_ZONE_END = "\x1b]133;B\x07";
 const OSC133_ZONE_FINAL = "\x1b]133;C\x07";
 
-// U+258C LEFT HALF BLOCK — theme-coloured left bar, matches chrome accents.
-const BAR_PREFIX = "▌ ";
-const BAR_PREFIX_WIDTH = 2;
+// U+2503 BOX DRAWINGS HEAVY VERTICAL — continuation bar on wrapped lines.
+const CONTINUATION_BAR = "┃";
+// Markdown child uses paddingX=1 and clamps contentWidth>=1, so its minimum
+// render output is 3 terminal cells. Anything narrower than prefix+3 would
+// overflow the requested width — bail out instead.
+const MIN_MARKDOWN_WIDTH = 3;
 
 /**
- * Component that renders a user message
+ * Renders a user message as an F5-branded admonition block: pi icon on the
+ * first content line, heavy vertical bar on continuations (both in `border`
+ * color), `userMessageBg` painted across the full requested width, and a
+ * leading blank spacer separating the prompt from the preceding block.
  */
 export class UserMessageComponent extends Container {
 	constructor(text: string, synthetic = false) {
@@ -19,28 +25,45 @@ export class UserMessageComponent extends Container {
 		const color = synthetic
 			? (value: string) => theme.fg("dim", value)
 			: (value: string) => theme.fg("userMessageText", value);
-		this.addChild(
-			new Markdown(text, 1, 0, getMarkdownTheme(), {
-				color,
-			}),
-		);
+		this.addChild(new Spacer(1));
+		this.addChild(new Markdown(text, 1, 0, getMarkdownTheme(), { color }));
 	}
 
 	override render(width: number): string[] {
-		const innerWidth = width - BAR_PREFIX_WIDTH;
-		if (innerWidth <= 0) {
+		const piPrefix = `${theme.icon.pi} `;
+		const contPrefix = `${CONTINUATION_BAR} `;
+		// Prefix width is theme-dependent — Unicode π is 1 col, Nerd Font
+		// glyph and ASCII "pi" are 2 cols. Measure both and reserve the
+		// larger so every content line leaves room for either shape.
+		const prefixWidth = Math.max(visibleWidth(piPrefix), visibleWidth(contPrefix));
+		const innerWidth = width - prefixWidth;
+		if (innerWidth < MIN_MARKDOWN_WIDTH) {
 			return [];
 		}
-		const inner = super.render(innerWidth);
-		if (inner.length === 0) {
-			return inner;
+		const raw = super.render(innerWidth);
+		if (raw.length === 0) {
+			return raw;
 		}
 
-		const bar = theme.fg("border", BAR_PREFIX);
-		const lines = inner.map(line => bar + line);
+		let firstContent = 0;
+		while (firstContent < raw.length && raw[firstContent] === "") {
+			firstContent++;
+		}
+		if (firstContent === raw.length) {
+			return raw;
+		}
+
+		const leading = raw.slice(0, firstContent);
+		const content = raw.slice(firstContent).map((line, i) => {
+			const prefix = theme.fg("border", i === 0 ? piPrefix : contPrefix);
+			const combined = prefix + line;
+			const pad = Math.max(0, width - visibleWidth(combined));
+			return theme.bg("userMessageBg", combined + padding(pad));
+		});
+
+		content[0] = OSC133_ZONE_START + content[0];
+		content[content.length - 1] = content[content.length - 1] + OSC133_ZONE_END + OSC133_ZONE_FINAL;
 
-		lines[0] = OSC133_ZONE_START + lines[0];
-		lines[lines.length - 1] = lines[lines.length - 1] + OSC133_ZONE_END + OSC133_ZONE_FINAL;
-		return lines;
+		return [...leading, ...content];
 	}
 }

package/src/modes/controllers/command-controller.ts

@@ -725,6 +725,7 @@ export class CommandController {
 		}
 		this.ctx.ui.requestRender();
 
+		let failed = false;
 		try {
 			const result = await this.ctx.session.executeBash(
 				command,
@@ -750,14 +751,16 @@ export class CommandController {
 					truncation: meta?.truncation,
 				});
 			}
+			failed = result.cancelled || (typeof result.exitCode === "number" && result.exitCode !== 0);
 		} catch (error) {
+			failed = true;
 			if (this.ctx.bashComponent) {
-				this.ctx.bashComponent.setComplete(undefined, false);
+				this.ctx.bashComponent.setError(error instanceof Error ? error : String(error));
 			}
 			this.ctx.showError(`Bash command failed: ${error instanceof Error ? error.message : "Unknown error"}`);
 		}
 
-		bashGutter?.setDone();
+		bashGutter?.setDone(failed ? "error" : "success");
 		this.ctx.bashComponent = undefined;
 		this.ctx.ui.requestRender();
 	}
@@ -776,6 +779,7 @@ export class CommandController {
 		}
 		this.ctx.ui.requestRender();
 
+		let failed = false;
 		try {
 			const result = await this.ctx.session.executePython(
 				code,
@@ -794,14 +798,16 @@ export class CommandController {
 					truncation: meta?.truncation,
 				});
 			}
+			failed = result.cancelled || (typeof result.exitCode === "number" && result.exitCode !== 0);
 		} catch (error) {
+			failed = true;
 			if (this.ctx.pythonComponent) {
-				this.ctx.pythonComponent.setComplete(undefined, false);
+				this.ctx.pythonComponent.setError(error instanceof Error ? error : String(error));
 			}
 			this.ctx.showError(`Python execution failed: ${error instanceof Error ? error.message : "Unknown error"}`);
 		}
 
-		pythonGutter?.setDone();
+		pythonGutter?.setDone(failed ? "error" : "success");
 		this.ctx.pythonComponent = undefined;
 		this.ctx.ui.requestRender();
 	}

package/src/modes/controllers/event-controller.ts

@@ -15,6 +15,7 @@ import { ToolExecutionComponent } from "../../modes/components/tool-execution";
 import { TtsrNotificationComponent } from "../../modes/components/ttsr-notification";
 import { getSymbolTheme, theme } from "../../modes/theme/theme";
 import type { InteractiveModeContext, TodoPhase } from "../../modes/types";
+import { ReadGroupOutcomeAggregator } from "../../modes/utils/read-group-outcome-aggregator";
 import type { AgentSessionEvent } from "../../session/agent-session";
 import { calculatePromptTokens } from "../../session/compaction/compaction";
 import type { ExitPlanModeDetails } from "../../tools";
@@ -31,6 +32,7 @@ export class EventController {
 	#lastAssistantComponent: AssistantMessageComponent | undefined = undefined;
 	#idleCompactionTimer?: NodeJS.Timeout;
 	#pendingGutters = new Map<string, GutterBlock<any>>();
+	#readGroupAggregator = new ReadGroupOutcomeAggregator();
 	// streamingAssistantGutter is stored on ctx for cross-controller access (e.g. thinking toggle)
 	constructor(private ctx: InteractiveModeContext) {}
 
@@ -63,15 +65,20 @@ export class EventController {
 		return this.#lastReadGroup;
 	}
 
-	/** Remove a read tool's gutter entry; setDone() if no other reads share the same group gutter */
-	#cleanupReadGutter(toolCallId: string): void {
+	/**
+	 * Remove a read tool's gutter entry. Records the caller-supplied outcome
+	 * into the group aggregator; finalizes the gutter (calling `setDone` with
+	 * the aggregated worst outcome) only when no other reads still share the
+	 * same group gutter. The spinner stays active during the group lifetime.
+	 */
+	#cleanupReadGutter(toolCallId: string, outcome: "success" | "error"): void {
 		const gutter = this.#pendingGutters.get(toolCallId);
 		this.#pendingGutters.delete(toolCallId);
-		if (gutter) {
-			const stillActive = Array.from(this.#pendingGutters.values()).some(g => g === gutter);
-			if (!stillActive) {
-				gutter.setDone();
-			}
+		if (!gutter) return;
+		this.#readGroupAggregator.record(gutter, outcome);
+		const stillActive = Array.from(this.#pendingGutters.values()).some(g => g === gutter);
+		if (!stillActive) {
+			this.#readGroupAggregator.finalize(gutter);
 		}
 	}
 
@@ -366,7 +373,7 @@ export class EventController {
 						event.toolCallId,
 					);
 					if (isFinalAsyncState) {
-						this.#pendingGutters.get(event.toolCallId)?.setDone();
+						this.#pendingGutters.get(event.toolCallId)?.setDone(asyncState === "failed" ? "error" : "success");
 						this.#pendingGutters.delete(event.toolCallId);
 						this.ctx.pendingTools.delete(event.toolCallId);
 						this.#backgroundToolCallIds.delete(event.toolCallId);
@@ -388,7 +395,7 @@ export class EventController {
 						if (asyncState === "running") {
 							this.#backgroundToolCallIds.add(event.toolCallId);
 						} else {
-							this.#cleanupReadGutter(event.toolCallId);
+							this.#cleanupReadGutter(event.toolCallId, event.isError ? "error" : "success");
 							this.#backgroundToolCallIds.delete(event.toolCallId);
 							this.#clearReadToolCall(event.toolCallId);
 						}
@@ -414,7 +421,7 @@ export class EventController {
 						if (isBackgroundRunning) {
 							this.#backgroundToolCallIds.add(event.toolCallId);
 						} else {
-							this.#cleanupReadGutter(event.toolCallId);
+							this.#cleanupReadGutter(event.toolCallId, event.isError ? "error" : "success");
 							this.ctx.pendingTools.delete(event.toolCallId);
 							this.#backgroundToolCallIds.delete(event.toolCallId);
 							this.#clearReadToolCall(event.toolCallId);
@@ -434,7 +441,7 @@ export class EventController {
 						if (isBackgroundRunning) {
 							this.#backgroundToolCallIds.add(event.toolCallId);
 						} else {
-							this.#pendingGutters.get(event.toolCallId)?.setDone();
+							this.#pendingGutters.get(event.toolCallId)?.setDone(event.isError ? "error" : "success");
 							this.#pendingGutters.delete(event.toolCallId);
 							this.ctx.pendingTools.delete(event.toolCallId);
 							this.#backgroundToolCallIds.delete(event.toolCallId);
@@ -479,12 +486,34 @@ export class EventController {
 					this.ctx.streamingMessage = undefined;
 				}
 				await this.ctx.flushPendingModelSwitch();
-				for (const toolCallId of Array.from(this.ctx.pendingTools.keys())) {
-					if (!this.#backgroundToolCallIds.has(toolCallId)) {
-						this.#pendingGutters.get(toolCallId)?.setDone();
+				// Orphan pending tools at agent_end mean the turn aborted or
+				// errored before those tools completed. Mark the gutter as
+				// error so the live UI matches what a transcript rebuild
+				// renders for the same condition.
+				//
+				// We deliberately do NOT call `updateResult` here: a tool
+				// may have streamed partial output via
+				// `tool_execution_update` before aborting, and replacing
+				// that content with a synthetic "did not complete" string
+				// would discard the most diagnostic output in the exact
+				// failure case the user cares about. The error gutter
+				// color carries the outcome; the body keeps whatever
+				// streamed content it had.
+				{
+					const orphanGutters = new Set<GutterBlock<any>>();
+					for (const toolCallId of Array.from(this.ctx.pendingTools.keys())) {
+						if (this.#backgroundToolCallIds.has(toolCallId)) continue;
+						const gutter = this.#pendingGutters.get(toolCallId);
+						if (gutter) {
+							this.#readGroupAggregator.record(gutter, "error");
+							orphanGutters.add(gutter);
+						}
 						this.#pendingGutters.delete(toolCallId);
 						this.ctx.pendingTools.delete(toolCallId);
 					}
+					for (const gutter of orphanGutters) {
+						this.#readGroupAggregator.finalize(gutter);
+					}
 				}
 				this.#backgroundToolCallIds = new Set(
 					Array.from(this.#backgroundToolCallIds).filter(toolCallId => this.ctx.pendingTools.has(toolCallId)),

package/src/modes/theme/dark.json

@@ -28,6 +28,8 @@
 		"warning": "yellow",
 		"muted": "gray",
 		"dim": "dimGray",
+		"gutterSuccess": "cyan",
+		"gutterError": "red",
 		"text": "",
 		"thinkingText": "gray",
 		"selectedBg": "selectedBg",

package/src/modes/theme/light.json

@@ -4,6 +4,7 @@
 	"vars": {
 		"teal": "#5a8080",
 		"blue": "#547da7",
+		"cyan": "#0077a0",
 		"green": "#588458",
 		"red": "#aa5555",
 		"yellow": "#9a7326",
@@ -27,6 +28,8 @@
 		"warning": "yellow",
 		"muted": "mediumGray",
 		"dim": "dimGray",
+		"gutterSuccess": "cyan",
+		"gutterError": "red",
 		"text": "",
 		"thinkingText": "mediumGray",
 		"selectedBg": "selectedBg",

package/src/modes/theme/theme-schema.json

@@ -128,6 +128,14 @@
 					"$ref": "#/$defs/colorValue",
 					"description": "Error states"
 				},
+				"gutterSuccess": {
+					"$ref": "#/$defs/colorValue",
+					"description": "Optional: done-state tool/command gutter dot color for successful outcomes. Falls back to `success` when omitted."
+				},
+				"gutterError": {
+					"$ref": "#/$defs/colorValue",
+					"description": "Optional: done-state tool/command gutter dot color for failed outcomes. Falls back to `error` when omitted."
+				},
 				"warning": {
 					"$ref": "#/$defs/colorValue",
 					"description": "Warning states"

package/src/modes/theme/theme.ts

@@ -818,6 +818,8 @@ const ThemeJsonSchema = Type.Object({
 		warning: ColorValueSchema,
 		muted: ColorValueSchema,
 		dim: ColorValueSchema,
+		gutterSuccess: Type.Optional(ColorValueSchema),
+		gutterError: Type.Optional(ColorValueSchema),
 		text: ColorValueSchema,
 		thinkingText: ColorValueSchema,
 		// Backgrounds & Content Text (11 colors)
@@ -937,6 +939,8 @@ export type ThemeColor =
 	| "warning"
 	| "muted"
 	| "dim"
+	| "gutterSuccess"
+	| "gutterError"
 	| "text"
 	| "thinkingText"
 	| "userMessageText"
@@ -1026,6 +1030,8 @@ const THEME_COLOR_RECORD = {
 	warning: true,
 	muted: true,
 	dim: true,
+	gutterSuccess: true,
+	gutterError: true,
 	text: true,
 	thinkingText: true,
 	userMessageText: true,
@@ -1314,6 +1320,9 @@ export class Theme {
 		// Fallback: chromeAccent and contentAccent inherit from accent when not defined
 		this.#fgColors.chromeAccent ??= this.#fgColors.accent;
 		this.#fgColors.spinnerAccent ??= this.#fgColors.accent;
+		// Gutter outcome colors inherit from success/error unless a theme overrides them
+		this.#fgColors.gutterSuccess ??= this.#fgColors.success;
+		this.#fgColors.gutterError ??= this.#fgColors.error;
 		// Powerline segment bg/fg fallbacks
 		this.#fgColors.statusLineOsIconBg ??= this.#fgColors.muted;
 		this.#fgColors.statusLineOsIconFg ??= this.#fgColors.text;

package/src/modes/utils/read-group-outcome-aggregator.ts

@@ -0,0 +1,55 @@
+import type { Component } from "@f5xc-salesdemos/pi-tui";
+import type { GutterBlock } from "../components/gutter-block";
+
+type Outcome = "success" | "error";
+
+/**
+ * Aggregates per-read outcomes across a shared read-group gutter so the
+ * final rendered dot reflects the worst-case outcome of the group.
+ *
+ * Called by two paths:
+ *   • live event-controller — reads arrive one at a time during streaming;
+ *     the gutter's spinner must stay active until the last read in the
+ *     group completes, so finalize is called only when `stillActive` is
+ *     false.
+ *   • replay ui-helpers — transcript rebuild walks completed tool results
+ *     in order; finalize is called at each group boundary.
+ *
+ * Semantics:
+ *   • `record` merges an incoming outcome into the running worst-case for
+ *     the gutter. "error" beats "success" regardless of ordering.
+ *   • `finalize` flushes the aggregated outcome to `gutter.setDone()`,
+ *     clears the entry, and returns. Calling `finalize` on a gutter that
+ *     was never `record`ed calls `setDone()` with no argument so the
+ *     gutter renders in its neutral done state.
+ *   • `peek` is read-only — useful for assertions and instrumentation.
+ */
+// Gutter generic parameter is not relevant to aggregation; constrain to
+// `Component` (the superclass required by GutterBlock) so callers with
+// concrete child types still flow in cleanly.
+type AnyGutter = GutterBlock<Component>;
+
+export class ReadGroupOutcomeAggregator {
+	#outcomes = new WeakMap<AnyGutter, Outcome>();
+
+	record(gutter: AnyGutter, outcome: Outcome): void {
+		const current = this.#outcomes.get(gutter);
+		// "error" is strictly worse than "success" — once any read in the
+		// group fails, the whole group is marked failed.
+		if (current === "error") return;
+		this.#outcomes.set(gutter, outcome);
+	}
+
+	peek(gutter: AnyGutter): Outcome | undefined {
+		return this.#outcomes.get(gutter);
+	}
+
+	finalize(gutter: AnyGutter): void {
+		const outcome = this.#outcomes.get(gutter);
+		this.#outcomes.delete(gutter);
+		gutter.setDone(outcome);
+	}
+}
+
+// Re-export for callers that need the generic gutter type alias.
+export type { AnyGutter as ReadGroupGutter, Outcome as ReadGroupOutcome };

package/src/modes/utils/sanitize-error-message.ts

@@ -0,0 +1,60 @@
+import { Ellipsis, truncateToWidth } from "@f5xc-salesdemos/pi-tui";
+
+/**
+ * Single-line-safe sanitizer for error messages rendered inside TUI status
+ * footers (e.g. `(error: <message>)`). Protects the layout from payloads that
+ * contain ANSI escape sequences, embedded newlines, tabs, other control
+ * characters, wide glyphs (CJK / emoji), or are simply too long to fit on
+ * one terminal row.
+ *
+ * Contract (applied in order):
+ *   1. Full ANSI escape sequences (CSI like `\x1b[31m`, OSC like
+ *      `\x1b]8;;...\x1b\\`, and single-byte ESC introducers) are removed
+ *      WHOLE — not just the lone ESC byte — so no `[31mboom[0m` garbage
+ *      survives.
+ *   2. Embedded newlines and tabs are collapsed to a single space.
+ *   3. Any remaining ASCII control characters (\x00–\x1F and \x7F) are
+ *      stripped.
+ *   4. Runs of whitespace are collapsed to a single space; leading/trailing
+ *      whitespace is trimmed.
+ *   5. Output is truncated to {@link MAX_ERROR_MESSAGE_WIDTH} **terminal
+ *      cells** (not UTF-16 code units) via `truncateToWidth` from pi-tui;
+ *      wide glyphs therefore count as 2 cells each. Truncation is marked
+ *      with a single horizontal ellipsis (`…`). The limit is chosen so
+ *      that `(error: <msg>)` (9-cell wrapper) fits on a single row of an
+ *      80-column terminal.
+ */
+
+// Sanitized-message budget for the `(error: <msg>)` footer.
+//
+// The footer is rendered inside GutterBlock (2-cell prefix) + the bash/
+// python execution box (which reserves a 1-cell Text indent on each side
+// plus a further gap on the right before wrapping occurs in practice).
+// Arithmetic gives ~68 cells on an 80-column terminal, but empirical
+// rendering with `createToolGutter(new BashExecutionComponent(...)).render(80)`
+// still wraps the trailing `)` onto the next row at that ceiling.
+// Pin the budget well inside the algebraic limit so the guarantee holds
+// under the real layered layout.
+//
+// Net budget for the message: 60 cells → full footer ≤ ~73 cells →
+// safe on any terminal ≥ 80 columns even after the gutter + box overhead.
+export const MAX_ERROR_MESSAGE_WIDTH = 60;
+
+// Matches CSI (Control Sequence Introducer) / SGR sequences: \x1b[ … final byte.
+const ANSI_CSI_RE = /\x1b\[[0-?]*[ -/]*[@-~]/g;
+// Matches OSC (Operating System Command) sequences: \x1b] … terminator (BEL or ESC\).
+const ANSI_OSC_RE = /\x1b\][\s\S]*?(?:\x07|\x1b\\)/g;
+// Fallback for any stray single-byte ESC sequences (e.g. "\x1bM" reverse index).
+const ANSI_ESC_RE = /\x1b[@-_]?/g;
+
+export function sanitizeErrorMessage(raw: string): string {
+	const withoutAnsi = raw.replace(ANSI_OSC_RE, "").replace(ANSI_CSI_RE, "").replace(ANSI_ESC_RE, "");
+	// Collapse whitespace-like control chars (tab, newline, CR, form feed)
+	// to a single space, then strip every remaining control character.
+	const flattened = withoutAnsi.replace(/[\t\n\r\f\v]+/g, " ").replace(/[\x00-\x1F\x7F]/g, "");
+	const collapsed = flattened.replace(/\s+/g, " ").trim();
+	// truncateToWidth measures in terminal cells (wide glyphs count as 2)
+	// and appends an ellipsis when it clips. Returns the input unchanged if
+	// already within budget.
+	return truncateToWidth(collapsed, MAX_ERROR_MESSAGE_WIDTH, Ellipsis.Unicode);
+}

package/src/modes/utils/ui-helpers.ts

@@ -20,6 +20,7 @@ import { ToolExecutionComponent } from "../../modes/components/tool-execution";
 import { UserMessageComponent } from "../../modes/components/user-message";
 import { theme } from "../../modes/theme/theme";
 import type { CompactionQueuedMessage, InteractiveModeContext } from "../../modes/types";
+import { ReadGroupOutcomeAggregator } from "../../modes/utils/read-group-outcome-aggregator";
 import { type CustomMessage, SKILL_PROMPT_MESSAGE_TYPE, type SkillPromptDetails } from "../../session/messages";
 import type { SessionContext } from "../../session/session-manager";
 import { formatBytes, formatDuration } from "../../tools/render-utils";
@@ -86,7 +87,7 @@ export class UiHelpers {
 					truncation: message.meta?.truncation,
 				});
 				const gutter = createToolGutter(this.ctx.ui, component);
-				gutter.setDone();
+				gutter.setDone(component.outcome);
 				this.ctx.chatContainer.addChild(gutter);
 				break;
 			}
@@ -99,7 +100,7 @@ export class UiHelpers {
 					truncation: message.meta?.truncation,
 				});
 				const gutter = createToolGutter(this.ctx.ui, component);
-				gutter.setDone();
+				gutter.setDone(component.outcome);
 				this.ctx.chatContainer.addChild(gutter);
 				break;
 			}
@@ -227,6 +228,30 @@ export class UiHelpers {
 		}
 
 		let readGroup: ReadToolGroupComponent | null = null;
+		// Parallel to `readGroup`: the wrapping gutter for the current read
+		// group. Held so the aggregator can finalize the correct gutter at
+		// each group boundary.
+		let readGroupGutter: ReturnType<typeof createToolGutter> | null = null;
+		// IDs of reads added to the current group but not yet matched to a
+		// toolResult. Any still-pending read at group boundary counts as an
+		// "error" outcome for the group, matching the live
+		// `agent_end`-time error coloring of orphaned tools.
+		let unmatchedReadsInGroup = new Set<string>();
+		const readGroupAggregator = new ReadGroupOutcomeAggregator();
+		const finalizeReadGroup = (): void => {
+			if (readGroupGutter) {
+				// Any read in this group that never received a toolResult
+				// is an orphan → record error so the group aggregates to
+				// "error" instead of silently ending on the last success.
+				for (const _id of unmatchedReadsInGroup) {
+					readGroupAggregator.record(readGroupGutter, "error");
+				}
+				readGroupAggregator.finalize(readGroupGutter);
+			}
+			readGroup = null;
+			readGroupGutter = null;
+			unmatchedReadsInGroup = new Set<string>();
+		};
 		const readToolCallArgs = new Map<string, Record<string, unknown>>();
 		const readToolCallAssistantComponents = new Map<string, AssistantMessageComponent>();
 		const toolGutters = new Map<string, ReturnType<typeof createToolGutter>>();
@@ -246,7 +271,9 @@ export class UiHelpers {
 				if (assistantComponent) {
 					assistantComponent.setUsageInfo(message.usage);
 				}
-				readGroup = null;
+				// New assistant message — finalize the previous group so its
+				// gutter resolves with the worst outcome seen so far.
+				finalizeReadGroup();
 				const hasErrorStop = message.stopReason === "aborted" || message.stopReason === "error";
 				const errorMessage = hasErrorStop
 					? message.stopReason === "aborted"
@@ -270,10 +297,15 @@ export class UiHelpers {
 							if (!readGroup) {
 								readGroup = new ReadToolGroupComponent();
 								readGroup.setExpanded(this.ctx.toolOutputExpanded);
-								const readGutter = createToolGutter(this.ctx.ui, readGroup);
-								readGutter.setDone();
-								this.ctx.chatContainer.addChild(readGutter);
+								readGroupGutter = createToolGutter(this.ctx.ui, readGroup);
+								this.ctx.chatContainer.addChild(readGroupGutter);
 							}
+							if (readGroupGutter) {
+								readGroupAggregator.record(readGroupGutter, "error");
+							}
+							// error-stop path injects an immediate error
+							// result, so the read is NOT unmatched.
+							unmatchedReadsInGroup.delete(content.id);
 							readGroup.updateArgs(content.arguments, content.id);
 							readGroup.updateResult(
 								{ content: [{ type: "text", text: errorMessage }], isError: true },
@@ -289,11 +321,17 @@ export class UiHelpers {
 							if (assistantComponent) {
 								readToolCallAssistantComponents.set(content.id, assistantComponent);
 							}
+							// Track this read as part of the current group.
+							// A matching toolResult will remove it; anything
+							// left at group boundary is an unmatched orphan
+							// and counts as an error for the aggregator.
+							unmatchedReadsInGroup.add(content.id);
 						}
 						continue;
 					}
 
-					readGroup = null;
+					// Non-read tool call breaks the group.
+					finalizeReadGroup();
 					const tool = this.ctx.session.getToolByName(content.name);
 					const renderArgs =
 						"partialJson" in content
@@ -322,7 +360,7 @@ export class UiHelpers {
 							false,
 							content.id,
 						);
-						toolGutter.setDone();
+						toolGutter.setDone("error");
 					} else {
 						// Tool result hasn't arrived yet — keep gutter active until completion
 						this.ctx.pendingTools.set(content.id, component);
@@ -339,19 +377,28 @@ export class UiHelpers {
 						assistantComponent.setToolResultImages(message.toolCallId, images);
 						const hasText = message.content.some(c => c.type === "text");
 						if (!hasText) {
+							// Image-only reads are still successful reads —
+							// record them into the current group aggregate
+							// and remove from unmatched tracking so the
+							// group does not wrongly aggregate to "error"
+							// on a subsequent boundary.
+							if (readGroupGutter) {
+								readGroupAggregator.record(readGroupGutter, message.isError ? "error" : "success");
+							}
+							unmatchedReadsInGroup.delete(message.toolCallId);
 							readToolCallArgs.delete(message.toolCallId);
 							readToolCallAssistantComponents.delete(message.toolCallId);
 							continue;
 						}
 					}
+					const readOutcome: "success" | "error" = message.isError ? "error" : "success";
 					let component = this.ctx.pendingTools.get(message.toolCallId);
 					if (!component) {
 						if (!readGroup) {
 							readGroup = new ReadToolGroupComponent();
 							readGroup.setExpanded(this.ctx.toolOutputExpanded);
-							const readGutter = createToolGutter(this.ctx.ui, readGroup);
-							readGutter.setDone();
-							this.ctx.chatContainer.addChild(readGutter);
+							readGroupGutter = createToolGutter(this.ctx.ui, readGroup);
+							this.ctx.chatContainer.addChild(readGroupGutter);
 						}
 						const args = readToolCallArgs.get(message.toolCallId);
 						if (args) {
@@ -360,21 +407,49 @@ export class UiHelpers {
 						component = readGroup;
 						this.ctx.pendingTools.set(message.toolCallId, readGroup);
 					}
+					if (readGroupGutter) {
+						readGroupAggregator.record(readGroupGutter, readOutcome);
+					}
+					// This read now has a matching result — it is no longer
+					// an unmatched orphan for the group's aggregation.
+					unmatchedReadsInGroup.delete(message.toolCallId);
 					component.updateResult(message, false, message.toolCallId);
 					this.ctx.pendingTools.delete(message.toolCallId);
-					toolGutters.get(message.toolCallId)?.setDone();
+					toolGutters.get(message.toolCallId)?.setDone(readOutcome);
 					toolGutters.delete(message.toolCallId);
 					readToolCallArgs.delete(message.toolCallId);
 					readToolCallAssistantComponents.delete(message.toolCallId);
 					continue;
 				}
 
-				// Match tool results to pending tool components
+				// Match tool results to pending tool components.
+				//
+				// Persisted async-running results (details.async.state ===
+				// "running") describe jobs that were active when the
+				// session was saved — the persisted outcome is neither
+				// success nor failure, just "incomplete". Finalize the
+				// gutter with the neutral (dim) done color so rebuilt
+				// transcripts don't misreport them as successful. True
+				// resumption of such a job across sessions would require
+				// handing the gutter to the live EventController's
+				// private #pendingGutters map — out of scope for this
+				// rebuild.
 				const component = this.ctx.pendingTools.get(message.toolCallId);
 				if (component) {
+					const asyncState = (message.details as { async?: { state?: string } } | undefined)?.async?.state;
+					const isAsyncRunning = asyncState === "running";
 					component.updateResult(message, false, message.toolCallId);
 					this.ctx.pendingTools.delete(message.toolCallId);
-					toolGutters.get(message.toolCallId)?.setDone();
+					const gutter = toolGutters.get(message.toolCallId);
+					if (gutter) {
+						if (isAsyncRunning) {
+							// Neutral "completed state" color — not
+							// success and not error.
+							gutter.setDone();
+						} else {
+							gutter.setDone(message.isError ? "error" : "success");
+						}
+					}
 					toolGutters.delete(message.toolCallId);
 				}
 			} else {
@@ -388,10 +463,25 @@ export class UiHelpers {
 			this.ctx.addMessageToChat(message, options);
 		}
 
-		this.ctx.pendingTools.clear();
-		// Mark any remaining tool gutters as done (tools without results in history)
-		for (const gutter of toolGutters.values()) {
-			gutter.setDone();
+		// Finalize any still-open read group at the tail of the transcript.
+		// This also records "error" for any reads in the final group that
+		// never received a toolResult, so incomplete groups aggregate to
+		// error rather than silently closing on the last success.
+		finalizeReadGroup();
+		// Tool gutters without a matching result mean the session was
+		// persisted with an unfinished tool — an aborted/errored turn.
+		// Inject an error body so the component renders as failed (it has
+		// no prior streamed content during a rebuild), and mark the
+		// gutter error.
+		for (const [toolCallId, gutter] of toolGutters.entries()) {
+			const component = this.ctx.pendingTools.get(toolCallId);
+			component?.updateResult(
+				{ content: [{ type: "text", text: "Tool call did not complete" }], isError: true },
+				false,
+				toolCallId,
+			);
+			this.ctx.pendingTools.delete(toolCallId);
+			gutter.setDone("error");
 		}
 		toolGutters.clear();
 		this.ctx.ui.requestRender();
@@ -603,14 +693,14 @@ export class UiHelpers {
 		for (const component of this.ctx.pendingBashComponents) {
 			this.ctx.pendingMessagesContainer.removeChild(component);
 			const gutter = createToolGutter(this.ctx.ui, component);
-			gutter.setDone();
+			gutter.setDone(component.outcome);
 			this.ctx.chatContainer.addChild(gutter);
 		}
 		this.ctx.pendingBashComponents = [];
 		for (const component of this.ctx.pendingPythonComponents) {
 			this.ctx.pendingMessagesContainer.removeChild(component);
 			const gutter = createToolGutter(this.ctx.ui, component);
-			gutter.setDone();
+			gutter.setDone(component.outcome);
 			this.ctx.chatContainer.addChild(gutter);
 		}
 		this.ctx.pendingPythonComponents = [];