@f5-sales-demo/xcsh 19.51.2

package/src/tools/auto-generated-guard.ts

@@ -0,0 +1,305 @@
+/**
+ * Auto-generated file detection guard.
+ *
+ * Prevents editing of files that appear to be automatically generated
+ * by code generation tools (protoc, sqlc, buf, swagger, etc.).
+ */
+import * as path from "node:path";
+import { isEnoent, peekFile } from "@f5xc-salesdemos/pi-utils";
+import { LRUCache } from "lru-cache/raw";
+import { settings } from "../config/settings";
+import { ToolError } from "./tool-errors";
+
+/**
+ * Number of bytes to read from the start of a file for auto-generated detection.
+ */
+const CHECK_BYTE_COUNT = 1024;
+const HEADER_LINE_LIMIT = 40;
+
+const KNOWN_GENERATOR_PATTERN =
+	"(?:protoc(?:-gen-[\\w-]+)?|sqlc|buf|swagger(?:-codegen)?|openapi(?:-generator)?|grpc-gateway|mockery|stringer|easyjson|deepcopy-gen|defaulter-gen|conversion-gen|client-gen|lister-gen|informer-gen|kysely-codegen|napi-rs)";
+
+/**
+ * Strong marker patterns for generated-file headers.
+ *
+ * Keep these strict: broad patterns like /auto-generated/ cause false positives
+ * in normal hand-written files (including this guard implementation itself).
+ */
+const AUTO_GENERATED_HEADER_MARKERS: readonly RegExp[] = [
+	/@generated\b/i,
+	/\bcode\s+generated\s+by\s+[a-z0-9_.-]+/i,
+	/\bthis\s+file\s+was\s+automatically\s+generated\b/i,
+	new RegExp(`\\bgenerated\\s+by\\s+${KNOWN_GENERATOR_PATTERN}\\b`, "i"),
+];
+
+type CommentStyle = "slash" | "hash" | "sql" | "html";
+
+const COMMENT_STYLES_BY_EXTENSION = new Map<string, readonly CommentStyle[]>([
+	[".c", ["slash"]],
+	[".cc", ["slash"]],
+	[".cpp", ["slash"]],
+	[".cs", ["slash"]],
+	[".dart", ["slash"]],
+	[".go", ["slash"]],
+	[".h", ["slash"]],
+	[".hpp", ["slash"]],
+	[".java", ["slash"]],
+	[".js", ["slash"]],
+	[".jsx", ["slash"]],
+	[".kt", ["slash"]],
+	[".kts", ["slash"]],
+	[".mjs", ["slash"]],
+	[".cjs", ["slash"]],
+	[".php", ["slash"]],
+	[".rs", ["slash"]],
+	[".scala", ["slash"]],
+	[".swift", ["slash"]],
+	[".ts", ["slash"]],
+	[".tsx", ["slash"]],
+	[".py", ["hash"]],
+	[".rb", ["hash"]],
+	[".sh", ["hash"]],
+	[".bash", ["hash"]],
+	[".zsh", ["hash"]],
+	[".yml", ["hash"]],
+	[".yaml", ["hash"]],
+	[".toml", ["hash"]],
+	[".ini", ["hash"]],
+	[".cfg", ["hash"]],
+	[".conf", ["hash"]],
+	[".env", ["hash"]],
+	[".pl", ["hash"]],
+	[".r", ["hash"]],
+	[".sql", ["sql"]],
+	[".html", ["html"]],
+	[".htm", ["html"]],
+	[".xml", ["html"]],
+	[".svg", ["html"]],
+	[".xhtml", ["html"]],
+]);
+
+const COMMENT_STYLES_BY_BASENAME = new Map<string, readonly CommentStyle[]>([
+	["dockerfile", ["hash"]],
+	["makefile", ["hash"]],
+	["justfile", ["hash"]],
+]);
+
+/**
+ * File name patterns that strongly indicate auto-generated files.
+ * These are checked against the file name (not content).
+ */
+const AUTO_GENERATED_FILENAME_PATTERNS = [
+	/^zz_generated\./,
+	/\.pb\.(go|cc|h|c|js|ts)$/,
+	/_pb2\.py$/,
+	/_pb2_grpc\.py$/,
+	/\.gen\.(go|ts|js|py)$/,
+	/^generated\.(go|ts|js|py)$/,
+	/\.swagger\.json$/,
+	/\.openapi\.json$/,
+	/\.mock\.(go|ts)$/,
+	/\.mocks?\.(go|ts|js)$/,
+];
+
+function stripBom(content: string): string {
+	if (content.charCodeAt(0) === 0xfeff) {
+		return content.slice(1);
+	}
+	return content;
+}
+
+function getCommentStylesForPath(filePath: string): readonly CommentStyle[] {
+	const normalizedPath = filePath.toLowerCase();
+	const fileName = path.basename(normalizedPath);
+	const stylesByName = COMMENT_STYLES_BY_BASENAME.get(fileName);
+	if (stylesByName) return stylesByName;
+
+	const ext = path.extname(fileName);
+	const stylesByExt = COMMENT_STYLES_BY_EXTENSION.get(ext);
+	return stylesByExt ?? [];
+}
+
+function extractLeadingHeaderCommentText(content: string, commentStyles: readonly CommentStyle[]): string {
+	if (commentStyles.length === 0) return "";
+
+	const includeSlash = commentStyles.includes("slash");
+	const includeHash = commentStyles.includes("hash");
+	const includeSql = commentStyles.includes("sql");
+	const includeHtml = commentStyles.includes("html");
+
+	const lines = stripBom(content).split(/\r?\n/);
+	const headerLines: string[] = [];
+	let started = false;
+	let inSlashBlock = false;
+	let inHtmlBlock = false;
+
+	for (let lineIndex = 0; lineIndex < lines.length && lineIndex < HEADER_LINE_LIMIT; lineIndex += 1) {
+		const trimmed = lines[lineIndex]?.trim() ?? "";
+		if (lineIndex === 0 && trimmed.startsWith("#!")) {
+			continue;
+		}
+
+		if (inSlashBlock) {
+			headerLines.push(trimmed);
+			if (trimmed.includes("*/")) inSlashBlock = false;
+			continue;
+		}
+
+		if (inHtmlBlock) {
+			headerLines.push(trimmed);
+			if (trimmed.includes("-->")) inHtmlBlock = false;
+			continue;
+		}
+
+		if (trimmed.length === 0) {
+			if (started) headerLines.push("");
+			continue;
+		}
+
+		if (includeSlash && trimmed.startsWith("//")) {
+			started = true;
+			headerLines.push(trimmed);
+			continue;
+		}
+
+		if (includeSlash && trimmed.startsWith("/*")) {
+			started = true;
+			headerLines.push(trimmed);
+			if (!trimmed.includes("*/")) {
+				inSlashBlock = true;
+			}
+			continue;
+		}
+
+		if (includeHash && trimmed.startsWith("#")) {
+			started = true;
+			headerLines.push(trimmed);
+			continue;
+		}
+
+		if (includeSql && trimmed.startsWith("--")) {
+			started = true;
+			headerLines.push(trimmed);
+			continue;
+		}
+
+		if (includeHtml && trimmed.startsWith("<!--")) {
+			started = true;
+			headerLines.push(trimmed);
+			if (!trimmed.includes("-->")) {
+				inHtmlBlock = true;
+			}
+			continue;
+		}
+
+		if (started) break;
+		break;
+	}
+
+	return headerLines.join("\n");
+}
+
+/**
+ * Check if a file name indicates it might be auto-generated.
+ * This is a quick pre-check before reading file content.
+ */
+function isAutoGeneratedFileName(filePath: string): boolean {
+	const fileName = filePath.split("/").pop() ?? "";
+	return AUTO_GENERATED_FILENAME_PATTERNS.some(pattern => pattern.test(fileName));
+}
+
+/**
+ * Check if leading header comments contain auto-generated markers.
+ * Returns the matched marker text if found, undefined otherwise.
+ */
+function detectAutoGeneratedMarker(content: string, filePath: string): string | undefined {
+	const commentStyles = getCommentStylesForPath(filePath);
+	const headerCommentText = extractLeadingHeaderCommentText(content, commentStyles);
+	if (!headerCommentText) return undefined;
+
+	for (const markerPattern of AUTO_GENERATED_HEADER_MARKERS) {
+		const match = markerPattern.exec(headerCommentText);
+		if (match?.[0]) return match[0];
+	}
+
+	return undefined;
+}
+
+/**
+ * Build the error message for an auto-generated file.
+ */
+function buildAutoGeneratedError(displayPath: string, detected: string): ToolError {
+	return new ToolError(
+		`Cannot modify auto-generated file: ${displayPath}\n\n` +
+			`This file appears to be automatically generated (detected marker: "${detected}").\n` +
+			`Auto-generated files should not be edited directly. Instead:\n` +
+			`1. Find the source file or generator configuration\n` +
+			`2. Make changes to the source\n` +
+			`3. Regenerate the file`,
+	);
+}
+
+const decoder = new TextDecoder("utf-8");
+
+const autoGeneratedMap = new LRUCache<string, { marker: string | undefined }>({ max: 10 });
+
+async function getAutoGeneratedMarker(filePath: string): Promise<string | undefined> {
+	if (isAutoGeneratedFileName(filePath)) {
+		return filePath.split("/").pop() ?? "";
+	}
+
+	const cached = autoGeneratedMap.get(filePath);
+	if (cached) return cached.marker;
+
+	let marker: string | undefined;
+	try {
+		const content = await peekFile(filePath, CHECK_BYTE_COUNT, header => decoder.decode(header));
+		marker = detectAutoGeneratedMarker(content, filePath);
+	} catch (err) {
+		if (isEnoent(err)) {
+			return undefined;
+		}
+		throw err;
+	}
+
+	autoGeneratedMap.set(filePath, { marker });
+	return marker;
+}
+
+/**
+ * Check if a file is auto-generated by examining its content.
+ * Throws ToolError if the file appears to be auto-generated.
+ *
+ * @param absolutePath - Absolute path to the file
+ * @param displayPath - Path to show in error messages (relative or as provided)
+ */
+export async function assertEditableFile(absolutePath: string, displayPath?: string) {
+	if (!settings.get("edit.blockAutoGenerated")) {
+		return;
+	}
+	const pathForDisplay = displayPath ?? absolutePath;
+	const marker = await getAutoGeneratedMarker(absolutePath);
+	if (marker) {
+		throw buildAutoGeneratedError(pathForDisplay, marker);
+	}
+}
+
+/**
+ * Check if file content is auto-generated.
+ * Uses only the first CHECK_BYTE_COUNT characters of the content.
+ * Throws ToolError if the content appears to be auto-generated.
+ *
+ * @param content - File content to check (can be full content or prefix)
+ * @param displayPath - Path to show in error messages
+ */
+export function assertEditableFileContent(content: string, displayPath: string): void {
+	if (!settings.get("edit.blockAutoGenerated")) {
+		return;
+	}
+
+	const prefix = content.slice(0, CHECK_BYTE_COUNT);
+	const marker = detectAutoGeneratedMarker(prefix, displayPath);
+	if (marker) {
+		throw buildAutoGeneratedError(displayPath, marker);
+	}
+}

package/src/tools/bash-interactive.ts

@@ -0,0 +1,383 @@
+import type { AgentToolContext } from "@f5xc-salesdemos/pi-agent-core";
+import { type PtyRunResult, PtySession, sanitizeText } from "@f5xc-salesdemos/pi-natives";
+import {
+	type Component,
+	extractPrintableText,
+	matchesKey,
+	padding,
+	parseKey,
+	parseKittySequence,
+	truncateToWidth,
+	visibleWidth,
+} from "@f5xc-salesdemos/pi-tui";
+import type { Terminal as XtermTerminalType } from "@xterm/headless";
+import xterm from "@xterm/headless";
+import { NON_INTERACTIVE_ENV } from "../exec/non-interactive-env";
+import type { Theme } from "../modes/theme/theme";
+import { OutputSink, type OutputSummary } from "../session/streaming-output";
+import { sanitizeWithImagePassthrough } from "../utils/image-passthrough";
+import { formatStatusIcon, replaceTabs } from "./render-utils";
+
+export interface BashInteractiveResult extends OutputSummary {
+	exitCode: number | undefined;
+	cancelled: boolean;
+	timedOut: boolean;
+}
+
+function normalizeCaptureChunk(chunk: string): string {
+	const normalized = chunk.replace(/\r\n/gu, "\n").replace(/\r/gu, "\n");
+	return sanitizeWithImagePassthrough(normalized, sanitizeText);
+}
+
+const XtermTerminal = xterm.Terminal;
+
+function normalizeInputForPty(data: string, applicationCursorKeysMode: boolean): string {
+	const kitty = parseKittySequence(data);
+	if (kitty?.eventType === 3) {
+		return "";
+	}
+	const printableText = extractPrintableText(data);
+	if (printableText) {
+		return printableText;
+	}
+	if (!kitty) {
+		return data;
+	}
+	const keyId = parseKey(data);
+	if (!keyId) {
+		return data;
+	}
+	const normalizedKey = keyId.toLowerCase();
+	if (normalizedKey === "up") return applicationCursorKeysMode ? "\x1bOA" : "\x1b[A";
+	if (normalizedKey === "down") return applicationCursorKeysMode ? "\x1bOB" : "\x1b[B";
+	if (normalizedKey === "right") return applicationCursorKeysMode ? "\x1bOC" : "\x1b[C";
+	if (normalizedKey === "left") return applicationCursorKeysMode ? "\x1bOD" : "\x1b[D";
+	if (normalizedKey === "home") return applicationCursorKeysMode ? "\x1bOH" : "\x1b[H";
+	if (normalizedKey === "end") return applicationCursorKeysMode ? "\x1bOF" : "\x1b[F";
+	if (normalizedKey === "pageup") return "\x1b[5~";
+	if (normalizedKey === "pagedown") return "\x1b[6~";
+	if (normalizedKey === "insert") return "\x1b[2~";
+	if (normalizedKey === "delete") return "\x1b[3~";
+	if (normalizedKey === "shift+tab") return "\x1b[Z";
+	if (normalizedKey === "enter") return "\r";
+	if (normalizedKey === "tab") return "\t";
+	if (normalizedKey === "space") return " ";
+	if (normalizedKey === "backspace") return "\x7f";
+	if (normalizedKey === "escape") return "\x1b";
+	const ctrlMatch = /^ctrl\+([a-z])$/u.exec(normalizedKey);
+	if (ctrlMatch) {
+		const letter = ctrlMatch[1]!;
+		return String.fromCharCode(letter.charCodeAt(0) - 96);
+	}
+	const altMatch = /^alt\+([a-z])$/u.exec(normalizedKey);
+	if (altMatch) {
+		return `\x1b${altMatch[1]!}`;
+	}
+	// For any other Kitty sequence with a printable codepoint, emit the character directly
+	if (kitty.codepoint >= 32 && kitty.codepoint < 127) {
+		let ch = String.fromCharCode(kitty.codepoint);
+		// Apply ctrl modifier if present (modifier bit 4 = ctrl)
+		if (kitty.modifier & 4) {
+			const code = kitty.codepoint;
+			if (code >= 97 && code <= 122) {
+				ch = String.fromCharCode(code - 96);
+			}
+		}
+		// Apply alt modifier if present (modifier bit 2 = alt)
+		if (kitty.modifier & 2) {
+			ch = `\x1b${ch}`;
+		}
+		return ch;
+	}
+	return data;
+}
+class BashInteractiveOverlayComponent implements Component {
+	#terminal: XtermTerminalType;
+	#state: "running" | "complete" | "timed_out" | "killed" = "running";
+	#exitCode: number | undefined;
+	#onInput: (data: string) => void = () => {};
+	#onDismiss: () => void = () => {};
+	#onDispose: () => void = () => {};
+	#session: PtySession | null = null;
+	#lastCols = 0;
+	#lastRows = 0;
+	#writeQueue: string[] = [];
+	#writeOffset = 0;
+	#flushResolvers: Array<() => void> = [];
+	#writing = false;
+
+	constructor(
+		private readonly command: string,
+		private readonly uiTheme: Theme,
+		private readonly getTerminalRows: () => number,
+	) {
+		this.#terminal = new XtermTerminal({
+			cols: 120,
+			rows: 40,
+			disableStdin: true,
+			allowProposedApi: true,
+			scrollback: 10_000,
+		});
+	}
+
+	setHandlers(onInput: (data: string) => void, onDismiss: () => void, onDispose: () => void): void {
+		this.#onInput = onInput;
+		this.#onDismiss = onDismiss;
+		this.#onDispose = onDispose;
+	}
+
+	appendOutput(chunk: string): void {
+		this.#writeQueue.push(chunk);
+		this.#drainQueue();
+	}
+
+	#drainQueue(): void {
+		if (this.#writing) return;
+		if (this.#writeOffset >= this.#writeQueue.length) {
+			this.#resolveFlushWaiters();
+			return;
+		}
+		this.#writing = true;
+		const data = this.#writeQueue[this.#writeOffset]!;
+		this.#terminal.write(data, () => {
+			this.#writing = false;
+			this.#writeOffset += 1;
+			if (this.#writeOffset >= this.#writeQueue.length) {
+				this.#writeQueue = [];
+				this.#writeOffset = 0;
+				this.#resolveFlushWaiters();
+			}
+			this.#drainQueue();
+		});
+	}
+
+	#resolveFlushWaiters(): void {
+		if (this.#writing || this.#writeOffset < this.#writeQueue.length) return;
+		if (this.#flushResolvers.length === 0) return;
+		const resolvers = this.#flushResolvers;
+		this.#flushResolvers = [];
+		for (const resolve of resolvers) {
+			resolve();
+		}
+	}
+
+	flushOutput(): Promise<void> {
+		if (!this.#writing && this.#writeOffset >= this.#writeQueue.length) {
+			return Promise.resolve();
+		}
+		const { promise, resolve } = Promise.withResolvers<void>();
+		this.#flushResolvers.push(resolve);
+		return promise;
+	}
+
+	setSession(session: PtySession): void {
+		this.#session = session;
+	}
+
+	setComplete(result: { exitCode: number | undefined; cancelled: boolean; timedOut: boolean }): void {
+		this.#exitCode = result.exitCode;
+		if (result.timedOut) {
+			this.#state = "timed_out";
+			return;
+		}
+		if (result.cancelled) {
+			this.#state = "killed";
+			return;
+		}
+		this.#state = "complete";
+	}
+
+	handleInput(data: string): void {
+		if (this.#state === "running" && (matchesKey(data, "escape") || matchesKey(data, "esc"))) {
+			this.#onDismiss();
+			return;
+		}
+		if (this.#state !== "running") {
+			return;
+		}
+		const normalizedInput = normalizeInputForPty(data, this.#terminal.modes.applicationCursorKeysMode);
+		if (!normalizedInput) {
+			return;
+		}
+		this.#onInput(normalizedInput);
+	}
+	#stateText(): string {
+		if (this.#state === "running") return this.uiTheme.fg("warning", "running");
+		if (this.#state === "timed_out") return this.uiTheme.fg("warning", "timed out");
+		if (this.#state === "killed") return this.uiTheme.fg("warning", "killed");
+		if (this.#exitCode === 0) return this.uiTheme.fg("success", "exit 0");
+		if (this.#exitCode === undefined) return this.uiTheme.fg("warning", "exited");
+		return this.uiTheme.fg("error", `exit ${this.#exitCode}`);
+	}
+
+	#readViewport(innerWidth: number, maxContentRows: number): string[] {
+		this.#terminal.resize(innerWidth, maxContentRows);
+		const buffer = this.#terminal.buffer.active;
+		const viewportY = buffer.viewportY;
+		const visibleLines: string[] = [];
+		for (let i = 0; i < maxContentRows; i++) {
+			const line = buffer.getLine(viewportY + i)?.translateToString(true) ?? "";
+			visibleLines.push(truncateToWidth(replaceTabs(sanitizeText(line)), innerWidth));
+		}
+		return visibleLines;
+	}
+	render(width: number): string[] {
+		const safeWidth = Math.max(20, width);
+		const innerWidth = Math.max(1, safeWidth - 2);
+		const maxOverlayRows = Math.max(5, Math.floor(this.getTerminalRows() * 0.8));
+		const chromeRows = 4;
+		const maxContentRows = Math.max(1, maxOverlayRows - chromeRows);
+		// Propagate terminal resize to PTY session
+		const currentCols = innerWidth;
+		const currentRows = maxContentRows;
+		if (this.#session && (currentCols !== this.#lastCols || currentRows !== this.#lastRows)) {
+			this.#lastCols = currentCols;
+			this.#lastRows = currentRows;
+			try {
+				this.#session.resize(currentCols, currentRows);
+			} catch {
+				// Session may have ended
+			}
+		}
+		const statusIcon =
+			this.#state === "running"
+				? formatStatusIcon("running", this.uiTheme)
+				: this.#state === "complete" && this.#exitCode === 0
+					? formatStatusIcon("success", this.uiTheme)
+					: formatStatusIcon("warning", this.uiTheme);
+		const title = this.uiTheme.fg("contentAccent", "Console");
+		const statusBadge = `${this.uiTheme.fg("dim", this.uiTheme.format.bracketLeft)}${this.#stateText()}${this.uiTheme.fg("dim", this.uiTheme.format.bracketRight)}`;
+		const prefix = `${statusIcon} ${title} `;
+		const suffix = ` ${statusBadge}`;
+		const available = Math.max(1, innerWidth - visibleWidth(prefix) - visibleWidth(suffix));
+		const cmd = truncateToWidth(this.uiTheme.fg("muted", replaceTabs(this.command)), available);
+		const header = truncateToWidth(`${prefix}${cmd}${suffix}`, innerWidth);
+		const footer =
+			this.#state === "running"
+				? truncateToWidth(
+						`${this.uiTheme.fg("warning", "esc")} ${this.uiTheme.fg("dim", "force-kill")} ${this.uiTheme.fg("dim", "· input forwarded to PTY")}`,
+						innerWidth,
+					)
+				: truncateToWidth(this.uiTheme.fg("dim", "session finished"), innerWidth);
+		const visibleLines = this.#readViewport(innerWidth, maxContentRows);
+		const content = visibleLines.length > 0 ? visibleLines : [padding(innerWidth)];
+		const borderHorizontal = this.uiTheme.fg("border", this.uiTheme.boxSharp.horizontal.repeat(innerWidth));
+		const borderVertical = this.uiTheme.fg("border", this.uiTheme.boxSharp.vertical);
+		const boxLine = (line: string) =>
+			`${borderVertical}${line}${padding(Math.max(0, innerWidth - visibleWidth(line)))}${borderVertical}`;
+		return [
+			`${this.uiTheme.fg("border", this.uiTheme.boxSharp.topLeft)}${borderHorizontal}${this.uiTheme.fg("border", this.uiTheme.boxSharp.topRight)}`,
+			boxLine(header),
+			...content.map(boxLine),
+			boxLine(footer),
+			`${this.uiTheme.fg("border", this.uiTheme.boxSharp.bottomLeft)}${borderHorizontal}${this.uiTheme.fg("border", this.uiTheme.boxSharp.bottomRight)}`,
+		];
+	}
+
+	invalidate(): void {}
+
+	dispose(): void {
+		this.#terminal.dispose();
+		this.#onDispose();
+	}
+}
+
+export async function runInteractiveBashPty(
+	ui: NonNullable<AgentToolContext["ui"]>,
+	options: {
+		command: string;
+		cwd: string;
+		timeoutMs: number;
+		signal?: AbortSignal;
+		env?: Record<string, string>;
+		artifactPath?: string;
+		artifactId?: string;
+		maskSecrets?: (text: string) => string;
+	},
+): Promise<BashInteractiveResult> {
+	const sink = new OutputSink({
+		artifactPath: options.artifactPath,
+		artifactId: options.artifactId,
+		maskSecrets: options.maskSecrets,
+	});
+	const result = await ui.custom<BashInteractiveResult>(
+		(tui, uiTheme, _keybindings, done) => {
+			const session = new PtySession();
+			const component = new BashInteractiveOverlayComponent(options.command, uiTheme, () => tui.terminal.rows);
+			component.setSession(session);
+			let finished = false;
+			const finalize = (run: PtyRunResult) => {
+				if (finished) return;
+				finished = true;
+				component.setComplete({ exitCode: run.exitCode, cancelled: run.cancelled, timedOut: run.timedOut });
+				tui.requestRender();
+				void (async () => {
+					await component.flushOutput();
+					const summary = await sink.dump();
+					done({
+						exitCode: run.exitCode,
+						cancelled: run.cancelled,
+						timedOut: run.timedOut,
+						...summary,
+					});
+				})();
+			};
+			const cols = Math.max(20, tui.terminal.columns - 2);
+			const rows = Math.max(5, tui.terminal.rows - 4);
+			component.setHandlers(
+				data => {
+					try {
+						session.write(data);
+					} catch {
+						// ignore writes after command exits
+					}
+				},
+				() => {
+					try {
+						session.kill();
+					} catch {
+						// ignore
+					}
+				},
+				() => {
+					try {
+						session.kill();
+					} catch {
+						// ignore
+					}
+				},
+			);
+			void session
+				.start(
+					{
+						command: options.command,
+						cwd: options.cwd,
+						timeoutMs: options.timeoutMs,
+						env: {
+							...NON_INTERACTIVE_ENV,
+							...options.env,
+						},
+						signal: options.signal,
+						cols,
+						rows,
+					},
+					(err, chunk) => {
+						if (finished || err || !chunk) return;
+						const masked = options.maskSecrets ? options.maskSecrets(chunk) : chunk;
+						component.appendOutput(masked);
+						const normalizedChunk = normalizeCaptureChunk(masked);
+						sink.push(normalizedChunk);
+						tui.requestRender();
+					},
+				)
+				.then(finalize)
+				.catch(error => {
+					sink.push(`PTY error: ${error instanceof Error ? error.message : String(error)}\n`);
+					finalize({ exitCode: undefined, cancelled: false, timedOut: false });
+				});
+			return component;
+		},
+		{ overlay: true },
+	);
+	return result;
+}