@gajae-code/coding-agent 0.15.2 → 0.15.4

package/src/slash-commands/helpers/aside.ts

@@ -0,0 +1,299 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { sanitizeDisplayLine, sanitizeText } from "@gajae-code/utils";
+import { type ExecOptions, type ExecResult, execCommand } from "../../exec/exec";
+import type { ParsedSlashCommand, SlashCommandResult, SlashCommandRuntime } from "../types";
+import { commandConsumed, errorMessage, parseSubcommand, usage } from "./parse";
+
+/**
+ * Aside CLI discovery and `/aside` dispatch.
+ *
+ * Probe-only: never runs the installer. Missing-CLI handling is the caller's
+ * decision. This is an explicit composer frontend, not a GJC browser backend.
+ */
+
+export const ASIDE_INSTALL_URL = "https://releases.aside.com/install.sh";
+export const ASIDE_INSTALL_COMMAND = "curl -fsSL https://releases.aside.com/install.sh | bash";
+
+const ASIDE_HELP_VERBS = new Set(["help", "-h", "--help"]);
+
+const ASIDE_STATUS_TIMEOUT_MS = 15_000;
+const ASIDE_EXEC_TIMEOUT_MS = 10 * 60 * 1000;
+
+export const ASIDE_USAGE = [
+	"Aside CLI (explicit opt-in; does not enable GJC browser-control by default)",
+	"  /aside                         Show CLI path and usage",
+	"  /aside <prompt>                Run `aside exec <prompt>`",
+	"  /aside exec [args]             Pass argv through to `aside exec`",
+	"  /aside repl                    Not available inside GJC; run `aside repl` in a terminal",
+	"  /aside mcp                     Print MCP registration using the resolved CLI path",
+	"  /aside account [args]          Run `aside account` (list/status/use)",
+	"  /aside help                    Show this help",
+].join("\n");
+
+export type AsideCliProbe =
+	| { ok: true; path: string }
+	| { ok: false; searched: string[]; manualInstallCommand: string; url: string };
+
+export type AsideWhich = (command: string) => string | null | undefined;
+export type AsideIsExecutable = (filePath: string) => boolean;
+export type AsideExec = (command: string, args: string[], cwd: string, options?: ExecOptions) => Promise<ExecResult>;
+
+export interface AsideHandlerOptions {
+	homedir?: () => string;
+	which?: AsideWhich;
+	isExecutable?: AsideIsExecutable;
+	exec?: AsideExec;
+}
+
+/** Candidate absolute paths for the `aside` CLI, in priority order. */
+export function asideCliCandidates(home = os.homedir()): string[] {
+	return [
+		path.join(home, ".local", "bin", "aside"),
+		path.join(home, ".aside", "cli", "Aside CLI.app", "Contents", "MacOS", "aside"),
+	];
+}
+
+function defaultIsExecutable(filePath: string): boolean {
+	try {
+		const st = fs.statSync(filePath);
+		if (!st.isFile()) return false;
+		fs.accessSync(filePath, fs.constants.X_OK);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+function defaultWhich(command: string): string | null {
+	return Bun.which(command) ?? null;
+}
+
+function isSafeAsideCliPath(value: string): boolean {
+	return sanitizeText(value) === value && !/[\r\n]/u.test(value);
+}
+
+/** Resolve the first executable Aside CLI path, or null when none is found. */
+export function resolveAsideCliPath(
+	home = os.homedir(),
+	options: Pick<AsideHandlerOptions, "which" | "isExecutable"> = {},
+): string | null {
+	const isExecutable = options.isExecutable ?? defaultIsExecutable;
+	const which = options.which ?? defaultWhich;
+	for (const candidate of asideCliCandidates(home)) {
+		if (isExecutable(candidate) && isSafeAsideCliPath(candidate)) return candidate;
+	}
+	const fromPath = which("aside");
+	if (fromPath && isExecutable(fromPath) && isSafeAsideCliPath(fromPath)) return fromPath;
+	return null;
+}
+
+/** Structured probe result for callers that need to guide installation. */
+export function probeAsideCli(
+	home = os.homedir(),
+	options: Pick<AsideHandlerOptions, "which" | "isExecutable"> = {},
+): AsideCliProbe {
+	const searched = [...asideCliCandidates(home), "PATH (aside)"];
+	const found = resolveAsideCliPath(home, options);
+	if (found) return { ok: true, path: found };
+	return { ok: false, searched, manualInstallCommand: ASIDE_INSTALL_COMMAND, url: ASIDE_INSTALL_URL };
+}
+
+export function posixQuote(value: string): string {
+	if (value.length === 0) return "''";
+	if (/^[A-Za-z0-9_./:-]+$/.test(value)) return value;
+	return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+
+/** Quote a path for the PowerShell command shown on native Windows. */
+export function windowsPowerShellQuote(value: string): string {
+	return `'${value.replace(/'/g, "''")}'`;
+}
+
+function quoteAsidePath(value: string, platform = process.platform): string {
+	return platform === "win32" ? windowsPowerShellQuote(value) : posixQuote(value);
+}
+
+type AsideArgvResult = { ok: true; args: string[] } | { ok: false; error: string };
+
+/** Parse user-provided Aside argv without silently accepting malformed quoting. */
+export function parseAsideArgv(input: string): AsideArgvResult {
+	const args: string[] = [];
+	let current = "";
+	let tokenStarted = false;
+	let quote: "'" | '"' | null = null;
+	let escaped = false;
+
+	for (const char of input) {
+		if (escaped) {
+			current += char;
+			tokenStarted = true;
+			escaped = false;
+			continue;
+		}
+		if (quote) {
+			if (char === quote) {
+				quote = null;
+			} else if (char === "\\" && quote === '"') {
+				escaped = true;
+			} else {
+				current += char;
+			}
+			continue;
+		}
+		if (char === "'" || char === '"') {
+			quote = char;
+			tokenStarted = true;
+		} else if (char === "\\") {
+			escaped = true;
+			tokenStarted = true;
+		} else if (char === " " || char === "\t") {
+			if (tokenStarted) {
+				args.push(current);
+				current = "";
+				tokenStarted = false;
+			}
+		} else {
+			current += char;
+			tokenStarted = true;
+		}
+	}
+
+	if (escaped) return { ok: false, error: "unfinished escape" };
+	if (quote) return { ok: false, error: "unterminated quote" };
+	if (tokenStarted) args.push(current);
+	return { ok: true, args };
+}
+
+export function formatAsideMissingCli(probe: Extract<AsideCliProbe, { ok: false }>): string {
+	const installLabel = process.platform === "win32" ? "Install with in WSL or Git Bash:" : "Install with:";
+	return [
+		"Aside CLI was not found.",
+		"Looked in:",
+		...probe.searched.map(entry => `  - ${entry}`),
+		installLabel,
+		`  ${probe.manualInstallCommand}`,
+		`Docs: ${probe.url}`,
+		"Then retry /aside, or register MCP with the concrete binary path.",
+	].join("\n");
+}
+
+export function formatAsideMcpRegistration(cliPath: string, platform = process.platform): string {
+	const safeCliPath = sanitizeText(cliPath).replace(/[\r\n]/gu, " ");
+	const quotedCliPath = quoteAsidePath(safeCliPath, platform);
+	return [
+		`Aside CLI: ${safeCliPath}`,
+		"`/aside mcp` does not start a stdio server inside GJC.",
+		"Register the user-owned MCP definition with the resolved binary:",
+		`  gjc mcp add aside ${quotedCliPath} mcp --project`,
+		"Inspect the redacted record with `gjc mcp list --json`.",
+		"Do not paste cookies, screenshots, or private Aside profile paths into issues or PRs.",
+	].join("\n");
+}
+
+function formatExecOutput(result: ExecResult): string {
+	const body = [sanitizeText(result.stdout).trim(), sanitizeText(result.stderr).trim()].filter(Boolean).join("\n");
+	if (result.killed) {
+		return body ? `${body}\nAside CLI timed out or was cancelled.` : "Aside CLI timed out or was cancelled.";
+	}
+	if (!body) {
+		return result.code === 0
+			? "Aside CLI exited 0 with no output."
+			: `Aside CLI exited ${result.code} with no output.`;
+	}
+	if (result.code !== 0) return `${body}\n(exit ${result.code})`;
+	return body;
+}
+
+export function createAsideHandler(options: AsideHandlerOptions = {}) {
+	const homedir = options.homedir ?? os.homedir;
+	const exec = options.exec ?? execCommand;
+	const probeOptions = { which: options.which, isExecutable: options.isExecutable };
+
+	async function runCli(
+		runtime: SlashCommandRuntime,
+		cliPath: string,
+		args: string[],
+		timeout: number,
+	): Promise<SlashCommandResult> {
+		try {
+			const result = await exec(cliPath, args, runtime.cwd, { timeout });
+			await runtime.output(formatExecOutput(result));
+			return result.code === 0 && !result.killed
+				? commandConsumed()
+				: { consumed: true, exitCode: result.code || 1 };
+		} catch (error) {
+			return usage(`Aside CLI failed: ${errorMessage(error)}`, runtime);
+		}
+	}
+
+	return async function handleAsideAcp(
+		command: ParsedSlashCommand,
+		runtime: SlashCommandRuntime,
+	): Promise<SlashCommandResult> {
+		const { verb, rest } = parseSubcommand(command.args);
+		if (ASIDE_HELP_VERBS.has(verb)) return usage(ASIDE_USAGE, runtime);
+
+		const probe = probeAsideCli(homedir(), probeOptions);
+
+		if (verb === "mcp") {
+			if (rest) return usage("Usage: /aside mcp", runtime);
+			if (!probe.ok) return usage(formatAsideMissingCli(probe), runtime);
+			return usage(formatAsideMcpRegistration(probe.path), runtime);
+		}
+
+		if (verb === "repl") {
+			if (rest) return usage("Usage: /aside repl", runtime);
+			if (!probe.ok) return usage(formatAsideMissingCli(probe), runtime);
+			return usage(
+				[
+					"`/aside repl` needs a real terminal TTY.",
+					`Run this outside GJC: ${quoteAsidePath(probe.path)} repl`,
+				].join("\n"),
+				runtime,
+			);
+		}
+
+		if (!verb) {
+			if (!probe.ok) return usage(`${formatAsideMissingCli(probe)}\n\n${ASIDE_USAGE}`, runtime);
+			const lines = [`Aside CLI: ${probe.path}`];
+			try {
+				const version = await exec(probe.path, ["--version"], runtime.cwd, { timeout: ASIDE_STATUS_TIMEOUT_MS });
+				const label = sanitizeDisplayLine(version.stdout).trim() || sanitizeDisplayLine(version.stderr).trim();
+				if (version.code === 0 && label) lines.push(`Version: ${label.split("\n")[0]}`);
+			} catch {
+				// Status should still print when `--version` is unavailable.
+			}
+			lines.push(ASIDE_USAGE);
+			await runtime.output(lines.join("\n"));
+			return commandConsumed();
+		}
+
+		if (!probe.ok) return usage(formatAsideMissingCli(probe), runtime);
+
+		if (verb === "account") {
+			const parsed = parseAsideArgv(rest);
+			if (!parsed.ok) return usage(`Invalid Aside arguments: ${parsed.error}.`, runtime);
+			return runCli(runtime, probe.path, ["account", ...parsed.args], ASIDE_STATUS_TIMEOUT_MS);
+		}
+
+		if (verb === "exec") {
+			const parsed = parseAsideArgv(rest);
+			if (!parsed.ok) return usage(`Invalid Aside arguments: ${parsed.error}.`, runtime);
+			const argv = parsed.args;
+			if (argv.length === 0) return usage("Usage: /aside exec [args] <prompt>", runtime);
+			return runCli(runtime, probe.path, ["exec", ...argv], ASIDE_EXEC_TIMEOUT_MS);
+		}
+
+		if (verb.startsWith("-")) {
+			const parsed = parseAsideArgv(command.args);
+			if (!parsed.ok) return usage(`Invalid Aside arguments: ${parsed.error}.`, runtime);
+			return runCli(runtime, probe.path, ["exec", ...parsed.args], ASIDE_EXEC_TIMEOUT_MS);
+		}
+
+		return runCli(runtime, probe.path, ["exec", command.args.trim()], ASIDE_EXEC_TIMEOUT_MS);
+	};
+}
+
+export const handleAsideAcp = createAsideHandler();

package/src/tools/ask-contract.ts

@@ -7,6 +7,11 @@ import { INTENT_FIELD } from "@gajae-code/agent-core";
 import type { RawArgumentValidationResult } from "@gajae-code/ai/types";
 import * as z from "zod/v4";
 import { deepInterviewCharacterCount } from "../gjc-runtime/deep-interview-state";
+import {
+	isLegacyDeepInterviewPlaceholder,
+	isWorkflowPlaceholderText,
+	WORKFLOW_PLACEHOLDER_CORRECTION,
+} from "../gjc-runtime/workflow-placeholder";
 
 function deepInterviewBoundedString(maximum: number) {
 	return z.string().superRefine((value, context) => {
@@ -146,6 +151,13 @@ function createQuestionItemSchema(deepInterviewSchema: z.ZodType<DeepInterviewMe
 			workflowGate: WorkflowGateMeta.describe("optional workflow gate stage/kind override").optional(),
 		})
 		.superRefine((value, context) => {
+			if (value.deepInterview !== undefined && isWorkflowPlaceholderText(value.question)) {
+				context.addIssue({
+					code: "custom",
+					message: `deep-interview question body must ${WORKFLOW_PLACEHOLDER_CORRECTION}`,
+					path: ["question"],
+				});
+			}
 			const labels = new Set(value.options.map(option => option.label));
 			const contract = intentContract(value.deepInterview);
 			const review = intentReview(value.deepInterview);
@@ -459,19 +471,58 @@ function knownIntentRejection(arguments_: Record<string, unknown>): RawArgumentV
 		return { outcome: "reject", code: "ask-intent-contract-requires-non-empty-authority" };
 	return undefined;
 }
+
+function deepInterviewPlaceholderRejection(
+	arguments_: Record<string, unknown>,
+): RawArgumentValidationResult | undefined {
+	const root = parseEncodedContainer(arguments_);
+	if (!isPlainRecord(root)) return undefined;
+	const questions = parseEncodedContainer(root.questions);
+	if (!Array.isArray(questions)) return undefined;
+	for (const [index, rawValue] of questions.entries()) {
+		const rawQuestion = parseEncodedContainer(rawValue);
+		if (!isPlainRecord(rawQuestion) || !Object.hasOwn(rawQuestion, "deepInterview")) continue;
+		const metadata = parseEncodedContainer(rawQuestion.deepInterview);
+		if (metadata !== null && metadata !== undefined && isWorkflowPlaceholderText(rawQuestion.question)) {
+			return {
+				outcome: "reject",
+				code: "ask-deep-interview-question-body-required",
+				detail: {
+					rejectedKeys: [`questions[${index}].question`],
+					hint: WORKFLOW_PLACEHOLDER_CORRECTION,
+				},
+			};
+		}
+	}
+	for (const [index, rawValue] of questions.entries()) {
+		const question = parseEncodedContainer(rawValue);
+		if (isPlainRecord(question) && isLegacyDeepInterviewPlaceholder(question.question)) {
+			return {
+				outcome: "reject",
+				code: "ask-deep-interview-question-body-required",
+				detail: { rejectedKeys: [`questions[${index}].question`], hint: WORKFLOW_PLACEHOLDER_CORRECTION },
+			};
+		}
+	}
+	return undefined;
+}
+
 export function recoverRoundZeroIntentContract(
 	arguments_: Record<string, unknown>,
 	stage?: "topology" | "post-topology",
 ): RawArgumentValidationResult {
+	const normalizedInput = normalizeRoundZeroOptionalNulls(arguments_);
+	const placeholderRejection = deepInterviewPlaceholderRejection(normalizedInput);
+	if (placeholderRejection) return placeholderRejection;
 	// #4649: an incomplete Round-0 topology object (deepInterview present,
 	// required fields omitted) is NOT a retired-pair recovery candidate, so it
 	// would passthrough into generic Zod validation whose error names no contract
 	// and no correction — the repeat-invalid-bisect loop. Non-candidates get the
 	// targeted correction here; candidates get it only after the stricter known
 	// intent rejections below, so every previously-covered verdict is unchanged.
-	if (!isRoundZeroRecoveryCandidate(arguments_))
-		return roundZeroMetadataRejection(arguments_, stage) ?? { outcome: "passthrough" };
-	const normalizedArguments = normalizeRoundZeroOptionalNulls(arguments_);
+	if (!isRoundZeroRecoveryCandidate(normalizedInput))
+		return roundZeroMetadataRejection(normalizedInput, stage) ?? { outcome: "passthrough" };
+	const normalizedArguments = normalizedInput;
 	const knownRejection = knownIntentRejection(normalizedArguments);
 	if (knownRejection) return knownRejection;
 	const missingTopologyFields = roundZeroMetadataRejection(normalizedArguments, stage);

package/src/tools/ask.ts

@@ -114,11 +114,17 @@ const HEADLESS_CHECKBOX_CHECKED = "[x]";
 const HEADLESS_CHECKBOX_UNCHECKED = "[ ]";
 const DEEP_INTERVIEW_SELECTOR_SCROLL_TITLE_ROWS = Number.MAX_SAFE_INTEGER;
 const DEEP_INTERVIEW_RECORDER_AWAIT_TIMEOUT_MS = 250;
+export const MAX_EMPTY_CUSTOM_ATTEMPTS = 3;
+const EMPTY_CUSTOM_RETRY_MESSAGE = "Custom input cannot be empty. Enter text or cancel the ask.";
 
 function errorMessage(error: unknown): string {
 	return error instanceof Error ? error.message : String(error);
 }
 
+function nonEmptyCustomInput(value: string | undefined): string | undefined {
+	return value !== undefined && value.trim().length > 0 ? value : undefined;
+}
+
 function isAskTimeoutError(error: unknown): boolean {
 	return typeof error === "object" && error !== null && (error as { code?: unknown }).code === GJC_ASK_TIMEOUT_CODE;
 }
@@ -324,7 +330,7 @@ interface UIContext {
 			onLeft?: () => void;
 			onRight?: () => void;
 			helpText?: string;
-			customInput?: { optionLabel: string; onSubmit: (text: string) => void };
+			customInput?: { optionLabel: string; onSubmit: (text: string) => void; allowEmpty?: boolean };
 			clarificationInput?: { optionLabel: string; onSubmit: (text: string) => void; allowEmpty?: boolean };
 		},
 	): Promise<string | undefined>;
@@ -400,6 +406,7 @@ async function askSingleQuestion(
 			helpText,
 			customInput: {
 				optionLabel: otherOptionLabel,
+				allowEmpty: false,
 				onSubmit: (text: string) => {
 					inlineInput = text;
 				},
@@ -541,7 +548,9 @@ async function askSingleQuestion(
 					timedOut = true;
 					break;
 				}
-				const input = inlineInput !== undefined ? inlineInput : (await promptForCustomInput()).input;
+				const input = nonEmptyCustomInput(
+					inlineInput !== undefined ? inlineInput : (await promptForCustomInput()).input,
+				);
 				if (input === undefined) {
 					break;
 				}
@@ -642,7 +651,9 @@ async function askSingleQuestion(
 			}
 		} else if (choice === otherOptionLabel) {
 			if (!selectTimedOut) {
-				const input = inlineInput !== undefined ? inlineInput : (await promptForCustomInput()).input;
+				const input = nonEmptyCustomInput(
+					inlineInput !== undefined ? inlineInput : (await promptForCustomInput()).input,
+				);
 				if (input !== undefined) {
 					customInput = input;
 					selectedOptions = [];
@@ -733,6 +744,14 @@ export class AskTool implements AgentTool<AskParametersSchema, AskToolDetails> {
 	readonly rawArgumentValidation = (arguments_: Record<string, unknown>): RawArgumentValidationResult =>
 		recoverRoundZeroIntentContract(arguments_, this.session.getDeepInterviewAskStage?.());
 	readonly strict = true;
+	/**
+	 * Display-only fields: question text and option labels render to the user
+	 * and carry no executable or persisted meaning, so `\uXXXX`-escaped
+	 * non-ASCII text inside them degrades to a warning instead of failing the
+	 * run (issue #4983). Ids, workflow-gate metadata, and deep-interview
+	 * records stay load-bearing and keep the fail-closed rejection.
+	 */
+	readonly displaySafeEscapedArgFields = ["questions.question", "questions.options.label"] as const;
 	readonly loadMode = "discoverable";
 	constructor(private readonly session: ToolSession) {
 		this.description = prompt.render(askDescription);
@@ -1092,10 +1111,15 @@ export class AskTool implements AgentTool<AskParametersSchema, AskToolDetails> {
 
 		const askQuestion = async (
 			q: AskParams["questions"][number],
-			options?: { previous?: QuestionResult; navigation?: NavigationControls },
+			options?: {
+				previous?: QuestionResult;
+				navigation?: NavigationControls;
+				emptyCustomAttempt?: number;
+			},
 		) => {
 			const rawOptionLabels = q.options.map(o => o.label);
 			const questionIndex = params.questions.indexOf(q);
+			const emptyCustomAttempt = options?.emptyCustomAttempt ?? 0;
 			// Route headless asks through the SDK workflow-gate emitter; a connected
 			// SDK responder supplies the durable answer instead of an interactive UI.
 			if (gateEmitter && canUseWorkflowGate) {
@@ -1125,7 +1149,11 @@ export class AskTool implements AgentTool<AskParametersSchema, AskToolDetails> {
 			try {
 				const deepInterviewPrompt = formatDeepInterviewSelectorPrompt(q.question);
 				const isDeepInterviewQuestion = deepInterviewPrompt !== null || q.deepInterview !== undefined;
-				const displayQuestion = deepInterviewPrompt ?? q.question;
+				const baseDisplayQuestion = deepInterviewPrompt ?? q.question;
+				const displayQuestion =
+					emptyCustomAttempt > 0
+						? `${baseDisplayQuestion}\n\n${EMPTY_CUSTOM_RETRY_MESSAGE} (attempt ${emptyCustomAttempt + 1} of ${MAX_EMPTY_CUSTOM_ATTEMPTS})`
+						: baseDisplayQuestion;
 				const shouldNumberOptions = isDeepInterviewQuestion || isDeepInterviewAskQuestion(q.question);
 				const optionLabels = shouldNumberOptions ? numberOptionLabels(rawOptionLabels) : rawOptionLabels;
 				const clarificationOptionLabel = shouldNumberOptions
@@ -1248,7 +1276,27 @@ export class AskTool implements AgentTool<AskParametersSchema, AskToolDetails> {
 													: { kind: "resolve_without_commit", reason: "cancelled" };
 					await settleActiveRemote(settlement);
 					activeRemoteRequest = undefined;
-					if (settlement.kind === "invalid") return askQuestion(q, options);
+					if (settlement.kind === "invalid") {
+						if (emptyCustomAttempt + 1 >= MAX_EMPTY_CUSTOM_ATTEMPTS) {
+							return {
+								optionLabels: rawOptionLabels,
+								selectedOptions: [] as string[],
+								customInput: undefined,
+								clarificationQuestion: undefined,
+								navigation: undefined,
+								cancelled: true,
+								timedOut: false,
+							};
+						}
+						// A remote source may resolve synchronously. Yield to a timer queue
+						// between retries so repeated invalid answers cannot starve the
+						// event loop indefinitely.
+						await Bun.sleep(1);
+						return askQuestion(q, {
+							...options,
+							emptyCustomAttempt: emptyCustomAttempt + 1,
+						});
+					}
 				}
 				activeRemoteRequest = undefined;
 				return {

package/src/utils/clipboard.ts

@@ -34,6 +34,10 @@ export class ClipboardTransportError extends Error {
 	}
 }
 
+export type ClipboardDeliveryOutcome =
+	| { status: "verified"; transport: "ssh" }
+	| { status: "attempted"; transport: "auto" | "native" | "osc52"; reason: string };
+
 const SSH_HOST_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
 const SSH_OPERATION_TIMEOUT_MS = 5000;
 const SSH_CONNECT_TIMEOUT_S = 3;
@@ -261,41 +265,32 @@ function getClipboardTransportConfig(): { transport: "auto" | "native" | "osc52"
 	}
 }
 
-function emitOsc52(text: string): void {
-	if (!process.stdout.isTTY) return;
-	const onError = (err: unknown) => {
+function emitOsc52(text: string): boolean {
+	if (!process.stdout.isTTY) return false;
+	let delivered = false;
+	const onError = (_err: unknown) => {
 		process.stdout.off("error", onError);
-		// Prevent unhandled 'error' from crashing the process when stdout is a closed pipe.
-		if ((err as NodeJS.ErrnoException | null | undefined)?.code === "EPIPE") {
-			return;
-		}
 	};
 	try {
 		const encoded = Buffer.from(text).toString("base64");
 		const osc52 = `\x1b]52;c;${encoded}\x07`;
 		process.stdout.on("error", onError);
-		process.stdout.write(osc52, err => {
+		process.stdout.write(osc52, _err => {
 			process.stdout.off("error", onError);
-			// If stdout is closed (e.g. piped to a process that exits early),
-			// ignore EPIPE and proceed with native clipboard best-effort.
-			if ((err as NodeJS.ErrnoException | null | undefined)?.code === "EPIPE") {
-				return;
-			}
 		});
-	} catch (err) {
+		delivered = true;
+	} catch (_err) {
 		process.stdout.off("error", onError);
-		if ((err as NodeJS.ErrnoException | null | undefined)?.code !== "EPIPE") {
-			// Ignore all write failures (OSC 52 is best-effort).
-		}
 	}
+	return delivered;
 }
 
-async function copyToClipboardNative(text: string): Promise<void> {
+async function copyToClipboardNative(text: string): Promise<boolean> {
 	try {
 		if (process.env.TERMUX_VERSION) {
 			try {
 				execSync("termux-clipboard-set", { input: text, timeout: 5000 });
-				return;
+				return true;
 			} catch {
 				// Fall through to native
 			}
@@ -305,8 +300,9 @@ async function copyToClipboardNative(text: string): Promise<void> {
 		// unaffected by the ssh/osc52 explicit-transport contract below, which
 		// never reaches this function.
 		nativeClipboard().copyToClipboard(text);
+		return true;
 	} catch {
-		// Ignore — native clipboard copy is best-effort
+		return false;
 	}
 }
 
@@ -324,27 +320,40 @@ async function copyToClipboardNative(text: string): Promise<void> {
  *
  * @param text - UTF-8 text to place on the clipboard.
  */
-export async function copyToClipboard(text: string): Promise<void> {
+export async function copyToClipboard(text: string): Promise<ClipboardDeliveryOutcome> {
 	const { transport, sshHost } = getClipboardTransportConfig();
 
 	if (transport === "ssh") {
 		await copyToClipboardViaSsh(sshHost, text);
-		return;
+		return { status: "verified", transport: "ssh" };
 	}
 
 	if (transport === "osc52") {
-		emitOsc52(text);
-		return;
+		const delivered = emitOsc52(text);
+		return {
+			status: "attempted",
+			transport: "osc52",
+			reason: delivered ? "terminal accepted write; no read-back" : "terminal rejected write",
+		};
 	}
 
 	if (transport === "native") {
-		await copyToClipboardNative(text);
-		return;
+		const delivered = await copyToClipboardNative(text);
+		return {
+			status: "attempted",
+			transport: "native",
+			reason: delivered ? "native API provides no read-back verification" : "native clipboard API failed",
+		};
 	}
 
 	// auto: prior best-effort dual-path behavior.
-	emitOsc52(text);
-	await copyToClipboardNative(text);
+	const osc52Delivered = emitOsc52(text);
+	const nativeDelivered = await copyToClipboardNative(text);
+	return {
+		status: "attempted",
+		transport: "auto",
+		reason: `OSC52 ${osc52Delivered ? "accepted" : "failed"}; native ${nativeDelivered ? "accepted" : "failed"}; no read-back verification`,
+	};
 }
 
 /**