@iowarp/clio-coder 0.3.0 → 0.3.2

package/src/interactive/permission-overlay.ts

@@ -0,0 +1,170 @@
+import type { Component } from "../engine/tui.js";
+import { buildResponsiveHint } from "./overlay-frame.js";
+
+export { type AskAxis, askAxis } from "../domains/safety/approval-axis.js";
+export { describeCallTarget, sanitizeCallTargetText } from "../domains/safety/call-target.js";
+
+export interface ApprovalRequestView {
+	requestId: string;
+	tool: string;
+	actionClass: string;
+	axis: { kind: "net"; ruleId: string } | { kind: "autonomy"; level: string };
+	origin: { kind: "main" } | { kind: "worker"; agentId: string; runId: string };
+	reason: string;
+	/** Typed, sanitized multi-line artifact that this one approval authorizes. */
+	artifact?: { kind: "dispatch-plan"; text: string };
+	/**
+	 * One-line preview of the call's object: the command for bash, the path
+	 * for file tools, else a compact args preview. The operator is deciding
+	 * whether to allow this exact call, so the overlay must show what the
+	 * call will touch, not just the tool name. Main-agent asks derive it from
+	 * the parked call's args; worker escalations carry it in the escalation
+	 * payload. Absent only when nothing meaningful is derivable.
+	 */
+	target?: string;
+	queueDepth?: number;
+}
+
+const PERMISSION_OVERLAY_CONTENT_WIDTH = 78;
+
+export const PERMISSION_OVERLAY_WIDTH = PERMISSION_OVERLAY_CONTENT_WIDTH + 4;
+
+class PermissionOverlayBody implements Component {
+	constructor(private readonly view: ApprovalRequestView) {}
+
+	render(width: number): string[] {
+		return permissionOverlayLines(this.view, width);
+	}
+
+	invalidate(): void {}
+}
+
+function truncate(value: string, max: number): string {
+	return value.length <= max ? value : `${value.slice(0, Math.max(0, max - 1))}…`;
+}
+
+/** `label: value`, with the value ellipsized to what the box actually has. */
+function field(label: string, value: string, width: number): string {
+	return `${label}${truncate(value, Math.max(1, width - label.length))}`;
+}
+
+/**
+ * Greedy word wrap for prose. The safety sentences are the operator's only
+ * statement of what allow and stop mean, so they wrap: cutting them at the
+ * border produced "allow or de" on the surface where a misread is a wrong
+ * decision about a tool call.
+ */
+function wrapSentence(value: string, max: number): string[] {
+	if (max <= 0) return [value];
+	const lines: string[] = [];
+	let current = "";
+	for (const word of value.split(" ")) {
+		if (current.length === 0) current = word;
+		else if (current.length + 1 + word.length <= max) current = `${current} ${word}`;
+		else {
+			lines.push(current);
+			current = word;
+		}
+		while (current.length > max) {
+			lines.push(current.slice(0, max));
+			current = current.slice(max);
+		}
+	}
+	if (current.length > 0) lines.push(current);
+	return lines;
+}
+
+function wrapArtifactLine(value: string, max: number): string[] {
+	if (value.length <= max) return [value];
+	const lines: string[] = [];
+	let remaining = value;
+	while (remaining.length > max) {
+		const candidate = remaining.slice(0, max + 1);
+		const whitespace = candidate.lastIndexOf(" ");
+		const cut = whitespace >= Math.floor(max / 2) ? whitespace : max;
+		lines.push(remaining.slice(0, cut));
+		remaining = `    ${remaining.slice(cut).trimStart()}`;
+	}
+	lines.push(remaining);
+	return lines;
+}
+
+function axisLabel(axis: ApprovalRequestView["axis"], style: ApprovalRequestView["origin"]["kind"]): string {
+	if (axis.kind === "net") return `safety-net rail ${axis.ruleId}`;
+	return style === "worker" ? `autonomy level ${axis.level}` : `autonomy level (${axis.level})`;
+}
+
+function askedBy(view: ApprovalRequestView): string {
+	if (view.origin.kind === "worker") {
+		return `worker ${view.origin.agentId} (run ${view.origin.runId}), ${axisLabel(view.axis, "worker")}`;
+	}
+	return axisLabel(view.axis, "main");
+}
+
+export function permissionOverlayTitle(): string {
+	return "Allow this action once?";
+}
+
+/**
+ * The footer for a box `innerWidth` columns wide inside its borders.
+ *
+ * At 40 columns the old positional elider removed `[s] stop turn` and left
+ * "allow once" and an ambiguous "close" in front of an operator trying to
+ * refuse. The key kept working, so the layout was hiding a live safety action.
+ * This surface used to answer that with three hand-written width tiers; it now
+ * states the same policy as data. Allow and stop are marked critical, Esc is
+ * marked droppable, and `fitHintEntries` shortens every label before it drops
+ * anything, which reproduces the three tiers exactly.
+ */
+export const permissionOverlayHint = buildResponsiveHint(
+	[
+		{ key: "Enter", verb: "allow once", short: "allow", critical: true },
+		{ key: "s", verb: "stop turn", short: "stop", critical: true },
+	],
+	{ key: "Esc", verb: "close", critical: false },
+);
+
+const SAFETY_SENTENCES: ReadonlyArray<string> = [
+	"Parked until you decide; allow or deny applies to this call only.",
+	"Stopping the turn denies it and ends the run, so nothing asks again.",
+	"Hard-blocked actions remain blocked.",
+];
+
+/**
+ * The overlay's body, laid out for the width the frame gives it.
+ *
+ * Every line used to be sized for a 78-column box and the frame hard-cut the
+ * rest, so a 40-column terminal saw the safety sentences end mid-word and an
+ * 80-column one saw the command being authorized end mid-argument, both with
+ * nothing marking the cut.
+ */
+export function permissionOverlayLines(view: ApprovalRequestView, width: number): string[] {
+	const content = Math.max(8, Math.floor(width));
+	// The parked call is awaiting a decision, not blocked: the raw rejection
+	// short ("<tool> blocked: <class>") is never rendered here because its
+	// wording contradicts the ask. Tool, Target, Action, and the asking axis
+	// carry everything the operator needs to decide.
+	const lines = [
+		field("Tool: ", view.tool, content),
+		...(view.target !== undefined && view.target.length > 0 ? [field("Target: ", view.target, content)] : []),
+		field("Action: ", view.actionClass, content),
+		field("Asked by: ", askedBy(view), content),
+		...(view.artifact !== undefined
+			? [
+					"",
+					"Resolved dispatch plan:",
+					...view.artifact.text.split(/\r?\n/u).flatMap((line) => wrapArtifactLine(line, content)),
+				]
+			: []),
+		"",
+		...SAFETY_SENTENCES.flatMap((sentence) => wrapSentence(sentence, content)),
+	];
+	if (view.queueDepth !== undefined && view.queueDepth > 1) {
+		lines.splice(lines.indexOf(""), 0, `1 of ${view.queueDepth} parked`);
+	}
+	return lines;
+}
+
+export function createPermissionOverlayBody(view: ApprovalRequestView): Component {
+	return new PermissionOverlayBody(view);
+}

package/src/interactive/render-trace.ts

@@ -0,0 +1,534 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { appendFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import type { TuiRenderObserver, TuiRenderPhase } from "../engine/tui.js";
+
+/** The trace format is append-only JSONL so partial sessions remain readable. */
+export const RENDER_TRACE_VERSION = 2;
+
+export type RenderInputAction = "editor" | "overlay" | "scroll" | "submit" | "no-visual-change";
+export type VisibleEventKind = "text" | "thinking";
+
+export interface RenderTraceCommit {
+	writeId: number;
+	at: number;
+	bytes: number;
+	enqueueMs: number;
+	returned: boolean;
+	backpressured: boolean;
+}
+
+export interface RenderTraceFrameRecord {
+	type: "frame";
+	version: typeof RENDER_TRACE_VERSION;
+	frameId: number;
+	mode: "regular" | "fullscreen";
+	columns: number;
+	rows: number;
+	beginAt: number;
+	endAt: number;
+	durationMs: number;
+	sinceLastCommitMs: number | null;
+	panelHighWater: number;
+	inputHighWater: number;
+	panel: { durationMs: number; cacheHit: boolean; entriesRendered: number } | null;
+	pipeline: {
+		componentMs: number;
+		overlayCompositionMs: number;
+		normalizationMs: number;
+		cursorExtractionMs: number;
+		/** Viewport selection, diffing, ANSI construction, and cursor work not exposed as narrower pi-tui hooks. */
+		viewportDiffAnsiCursorMs: number;
+		terminalEnqueueMs: number;
+	};
+	commits: RenderTraceCommit[];
+}
+
+export type RenderTraceRecord =
+	| { type: "trace_start"; version: typeof RENDER_TRACE_VERSION; at: number }
+	| {
+			type: "event_ingress";
+			version: typeof RENDER_TRACE_VERSION;
+			eventSeq: number;
+			generation: number;
+			kind: VisibleEventKind;
+			contentIndex: number;
+			at: number;
+			codeUnitStart: number;
+			codeUnitEnd: number;
+			graphemeStart: number;
+			graphemeEnd: number;
+			bytes: number;
+	  }
+	| {
+			type: "queue";
+			version: typeof RENDER_TRACE_VERSION;
+			eventSeq: number;
+			action: "admit" | "dequeue";
+			at: number;
+			depth: number;
+	  }
+	| {
+			type: "panel";
+			version: typeof RENDER_TRACE_VERSION;
+			eventSeq: number;
+			at: number;
+			highWater: number;
+	  }
+	| {
+			type: "input_ingress";
+			version: typeof RENDER_TRACE_VERSION;
+			inputSeq: number;
+			action: RenderInputAction;
+			at: number;
+			bytes: number;
+			visualExpected: boolean;
+	  }
+	| RenderTraceFrameRecord
+	| {
+			type: "terminal_write";
+			version: typeof RENDER_TRACE_VERSION;
+			writeId: number;
+			frameId: number | null;
+			at: number;
+			bytes: number;
+			enqueueMs: number;
+			returned: boolean;
+			backpressured: boolean;
+	  }
+	| {
+			type: "terminal_drain";
+			version: typeof RENDER_TRACE_VERSION;
+			writeId: number;
+			frameId: number | null;
+			at: number;
+			waitMs: number;
+	  }
+	| { type: "trace_drop"; version: typeof RENDER_TRACE_VERSION; at: number; records: number };
+
+interface TraceWriter {
+	enqueue(record: RenderTraceRecord): void;
+	close(): Promise<void>;
+}
+
+interface AsyncTraceWriterOptions {
+	maxRecords?: number;
+	batchRecords?: number;
+	append?: (path: string, payload: string) => Promise<void>;
+	recordTime?: () => number;
+	appendTimeoutMs?: number;
+}
+
+/**
+ * One bounded producer queue and at most one asynchronous append in flight.
+ * JSON serialization is the only render-stack work; filesystem I/O never runs
+ * in a render callback, and a slow disk cannot grow an unbounded promise chain.
+ */
+function createAsyncTraceWriter(path: string, options: AsyncTraceWriterOptions = {}): TraceWriter {
+	const maxRecords = options.maxRecords ?? 4_096;
+	const batchRecords = options.batchRecords ?? 128;
+	const append = options.append ?? ((target, payload) => appendFile(target, payload, "utf8"));
+	const recordTime = options.recordTime ?? (() => performance.now());
+	// Stage 0 deliberately commits immediately before a large synchronous ESM
+	// evaluation. A 500 ms timer could become runnable before the already-finished
+	// append callback when that evaluation held the event loop, falsely disabling
+	// the trace after its first frame. Five seconds still bounds a genuinely
+	// wedged filesystem while surviving boot-time callback starvation.
+	const appendTimeoutMs = options.appendTimeoutMs ?? 5_000;
+	const pending: string[] = [];
+	let dropped = 0;
+	let inFlight = false;
+	let scheduled = false;
+	let failed = false;
+	let closing = false;
+	let closePromise: Promise<void> | null = null;
+	let resolveClose: (() => void) | null = null;
+
+	const settleClose = (): void => {
+		if (closing && !inFlight && pending.length === 0) resolveClose?.();
+	};
+	const pump = (): void => {
+		scheduled = false;
+		if (failed || inFlight || pending.length === 0) {
+			settleClose();
+			return;
+		}
+		inFlight = true;
+		const payload = pending.splice(0, batchRecords).join("");
+		let appendTimer: NodeJS.Timeout | null = null;
+		const appendDeadline = new Promise<never>((_resolve, reject) => {
+			appendTimer = setTimeout(() => reject(new Error("render trace append timed out")), appendTimeoutMs);
+		});
+		void Promise.race([append(path, payload), appendDeadline])
+			.catch(() => {
+				failed = true;
+				pending.length = 0;
+			})
+			.finally(() => {
+				if (appendTimer) clearTimeout(appendTimer);
+				inFlight = false;
+				if (pending.length > 0 && !failed) queueMicrotask(pump);
+				else settleClose();
+			});
+	};
+	const schedule = (): void => {
+		if (scheduled || inFlight || failed) return;
+		scheduled = true;
+		queueMicrotask(pump);
+	};
+
+	return {
+		enqueue(record): void {
+			if (failed || closing) return;
+			if (pending.length >= maxRecords) {
+				pending.shift();
+				dropped += 1;
+			}
+			pending.push(`${JSON.stringify(record)}\n`);
+			schedule();
+		},
+		close(): Promise<void> {
+			if (closePromise) return closePromise;
+			if (dropped > 0 && !failed) {
+				pending.push(
+					`${JSON.stringify({ type: "trace_drop", version: RENDER_TRACE_VERSION, at: recordTime(), records: dropped })}\n`,
+				);
+			}
+			closing = true;
+			closePromise = new Promise((resolve) => {
+				resolveClose = resolve;
+			});
+			if (failed) {
+				pending.length = 0;
+				resolveClose?.();
+			} else {
+				schedule();
+				settleClose();
+			}
+			return closePromise;
+		},
+	};
+}
+
+interface FrameState {
+	frameId: number;
+	mode: "regular" | "fullscreen";
+	columns: number;
+	rows: number;
+	beginAt: number;
+	panelHighWater: number;
+	inputHighWater: number;
+	panel: { durationMs: number; cacheHit: boolean; entriesRendered: number } | null;
+	phases: Record<"component" | TuiRenderPhase, number>;
+	commits: RenderTraceCommit[];
+}
+
+export interface RenderTrace extends TuiRenderObserver {
+	recordPanelRender(metrics: { durationMs: number; cacheHit: boolean; entriesRendered: number }): void;
+	beginGeneration(): void;
+	recordVisibleEvent(fields: { kind: VisibleEventKind; contentIndex: number; delta: string }): number;
+	recordQueue(eventSeq: number, action: "admit" | "dequeue"): void;
+	recordPanelApplied(eventSeq: number): void;
+	recordInputIngress(action: RenderInputAction, bytes: number, visualExpected?: boolean): number;
+	beginComponentRender(): unknown;
+	endComponentRender(token: unknown): void;
+	recordTerminalWrite(fields: { bytes: number; enqueueMs: number; returned: boolean }): number;
+	recordTerminalDrain(writeId: number): void;
+	currentFrameId(): number | null;
+	onFirstFrameCommit(listener: (frameId: number) => void): void;
+	close(): Promise<void>;
+}
+
+function rounded(value: number): number {
+	return Math.round(value * 1_000) / 1_000;
+}
+
+function graphemeCount(text: string): number {
+	const segmenter = new Intl.Segmenter(undefined, { granularity: "grapheme" });
+	let count = 0;
+	for (const _part of segmenter.segment(text)) count += 1;
+	return count;
+}
+
+export function renderTracePath(env: NodeJS.ProcessEnv = process.env): string | null {
+	const raw = env.CLIO_CODER_RENDER_TRACE?.trim();
+	return raw && raw.length > 0 ? raw : null;
+}
+
+export function createRenderTrace(
+	path: string,
+	now: () => number = () => performance.now(),
+	writerOptions: AsyncTraceWriterOptions = {},
+): RenderTrace {
+	// Initialization happens before the terminal/TUI starts, never in a frame.
+	mkdirSync(dirname(path), { recursive: true });
+	writeFileSync(path, "", "utf8");
+	const openedAt = now();
+	const at = (): number => rounded(now() - openedAt);
+	const writer = createAsyncTraceWriter(path, { ...writerOptions, recordTime: at });
+	let frameSeq = 0;
+	let writeSeq = 0;
+	let eventSeq = 0;
+	let inputSeq = 0;
+	let generation = 0;
+	let panelHighWater = 0;
+	let inputHighWater = 0;
+	let queueDepth = 0;
+	let currentFrame: FrameState | null = null;
+	let pendingPanel: FrameState["panel"] = null;
+	let lastCommitAt: number | null = null;
+	let firstCommitListener: ((frameId: number) => void) | null = null;
+	let firstCommitDelivered = false;
+	const ranges = new Map<string, { codeUnits: number; graphemes: number }>();
+	const pendingDrains = new Map<number, { frameId: number | null; at: number }>();
+
+	writer.enqueue({ type: "trace_start", version: RENDER_TRACE_VERSION, at: 0 });
+
+	const trace: RenderTrace = {
+		recordPanelRender(metrics): void {
+			pendingPanel = metrics;
+		},
+		beginGeneration(): void {
+			generation += 1;
+			ranges.clear();
+		},
+		recordVisibleEvent(fields): number {
+			eventSeq += 1;
+			const key = `${generation}:${fields.kind}:${fields.contentIndex}`;
+			const previous = ranges.get(key) ?? { codeUnits: 0, graphemes: 0 };
+			const graphemes = graphemeCount(fields.delta);
+			const next = { codeUnits: previous.codeUnits + fields.delta.length, graphemes: previous.graphemes + graphemes };
+			ranges.set(key, next);
+			writer.enqueue({
+				type: "event_ingress",
+				version: RENDER_TRACE_VERSION,
+				eventSeq,
+				generation,
+				kind: fields.kind,
+				contentIndex: fields.contentIndex,
+				at: at(),
+				codeUnitStart: previous.codeUnits,
+				codeUnitEnd: next.codeUnits,
+				graphemeStart: previous.graphemes,
+				graphemeEnd: next.graphemes,
+				bytes: Buffer.byteLength(fields.delta, "utf8"),
+			});
+			return eventSeq;
+		},
+		recordQueue(sequence, action): void {
+			queueDepth = Math.max(0, queueDepth + (action === "admit" ? 1 : -1));
+			writer.enqueue({
+				type: "queue",
+				version: RENDER_TRACE_VERSION,
+				eventSeq: sequence,
+				action,
+				at: at(),
+				depth: queueDepth,
+			});
+		},
+		recordPanelApplied(sequence): void {
+			panelHighWater = Math.max(panelHighWater, sequence);
+			writer.enqueue({
+				type: "panel",
+				version: RENDER_TRACE_VERSION,
+				eventSeq: sequence,
+				at: at(),
+				highWater: panelHighWater,
+			});
+		},
+		recordInputIngress(action, bytes, visualExpected = action !== "no-visual-change"): number {
+			inputSeq += 1;
+			if (visualExpected) inputHighWater = inputSeq;
+			writer.enqueue({
+				type: "input_ingress",
+				version: RENDER_TRACE_VERSION,
+				inputSeq,
+				action,
+				at: at(),
+				bytes,
+				visualExpected,
+			});
+			return inputSeq;
+		},
+		beginFrame(fields): FrameState {
+			frameSeq += 1;
+			const frame: FrameState = {
+				frameId: frameSeq,
+				...fields,
+				beginAt: at(),
+				panelHighWater,
+				inputHighWater,
+				panel: pendingPanel,
+				phases: { component: 0, overlay: 0, normalization: 0, cursor: 0 },
+				commits: [],
+			};
+			pendingPanel = null;
+			currentFrame = frame;
+			return frame;
+		},
+		endFrame(frameToken): void {
+			const frame = frameToken as FrameState;
+			const endAt = at();
+			const terminalEnqueueMs = frame.commits.reduce((sum, commit) => sum + commit.enqueueMs, 0);
+			const measured =
+				frame.phases.component +
+				frame.phases.overlay +
+				frame.phases.normalization +
+				frame.phases.cursor +
+				terminalEnqueueMs;
+			const record: RenderTraceFrameRecord = {
+				type: "frame",
+				version: RENDER_TRACE_VERSION,
+				frameId: frame.frameId,
+				mode: frame.mode,
+				columns: frame.columns,
+				rows: frame.rows,
+				beginAt: frame.beginAt,
+				endAt,
+				durationMs: rounded(Math.max(0, endAt - frame.beginAt)),
+				sinceLastCommitMs:
+					lastCommitAt === null || frame.commits.length === 0
+						? null
+						: rounded(Math.max(0, (frame.commits[0]?.at ?? endAt) - lastCommitAt)),
+				panelHighWater: frame.panelHighWater,
+				inputHighWater: frame.inputHighWater,
+				panel: frame.panel,
+				pipeline: {
+					componentMs: rounded(frame.phases.component),
+					overlayCompositionMs: rounded(frame.phases.overlay),
+					normalizationMs: rounded(frame.phases.normalization),
+					cursorExtractionMs: rounded(frame.phases.cursor),
+					viewportDiffAnsiCursorMs: rounded(Math.max(0, endAt - frame.beginAt - measured)),
+					terminalEnqueueMs: rounded(terminalEnqueueMs),
+				},
+				commits: frame.commits,
+			};
+			writer.enqueue(record);
+			if (frame.commits.length > 0) {
+				lastCommitAt = frame.commits.at(-1)?.at ?? endAt;
+				if (!firstCommitDelivered) {
+					firstCommitDelivered = true;
+					firstCommitListener?.(frame.frameId);
+				}
+			}
+			if (currentFrame === frame) currentFrame = null;
+		},
+		beginPhase(_frame, _phase): number {
+			return now();
+		},
+		endPhase(frameToken, phase, phaseToken): void {
+			const frame = frameToken as FrameState;
+			frame.phases[phase] += Math.max(0, now() - (phaseToken as number));
+		},
+		beginComponentRender(): number | null {
+			return currentFrame ? now() : null;
+		},
+		endComponentRender(token): void {
+			if (currentFrame === null || token === null) return;
+			currentFrame.phases.component += Math.max(0, now() - (token as number));
+		},
+		recordTerminalWrite(fields): number {
+			writeSeq += 1;
+			const frameId = currentFrame?.frameId ?? null;
+			const commit: RenderTraceCommit = {
+				writeId: writeSeq,
+				at: at(),
+				bytes: fields.bytes,
+				enqueueMs: rounded(fields.enqueueMs),
+				returned: fields.returned,
+				backpressured: !fields.returned,
+			};
+			currentFrame?.commits.push(commit);
+			writer.enqueue({ type: "terminal_write", version: RENDER_TRACE_VERSION, frameId, ...commit });
+			if (!fields.returned) pendingDrains.set(writeSeq, { frameId, at: commit.at });
+			return writeSeq;
+		},
+		recordTerminalDrain(writeId): void {
+			const pending = pendingDrains.get(writeId);
+			if (!pending) return;
+			pendingDrains.delete(writeId);
+			const drainAt = at();
+			writer.enqueue({
+				type: "terminal_drain",
+				version: RENDER_TRACE_VERSION,
+				writeId,
+				frameId: pending.frameId,
+				at: drainAt,
+				waitMs: rounded(Math.max(0, drainAt - pending.at)),
+			});
+		},
+		currentFrameId: () => currentFrame?.frameId ?? null,
+		onFirstFrameCommit(listener): void {
+			firstCommitListener = listener;
+		},
+		close: () => writer.close(),
+	};
+	return trace;
+}
+
+/** Time the root component without replacing its identity or layout markers. */
+export function traceComponentRenders<TComponent extends { render(width: number): string[] }>(
+	component: TComponent,
+	trace: Pick<RenderTrace, "beginComponentRender" | "endComponentRender">,
+): () => void {
+	const original = component.render;
+	const wrapped = function (this: TComponent, width: number): string[] {
+		const token = trace.beginComponentRender();
+		try {
+			return original.call(this, width);
+		} finally {
+			trace.endComponentRender(token);
+		}
+	};
+	component.render = wrapped;
+	return () => {
+		if (component.render === wrapped) component.render = original;
+	};
+}
+
+/**
+ * Observe the real Node stdout boundary. This catches writes made by terminal
+ * helpers that bypass `Terminal.write()` and records the Writable boolean plus
+ * the matching `drain`, while preserving Node's overloaded write contract.
+ */
+export function traceProcessStdout(
+	trace: Pick<RenderTrace, "recordTerminalWrite" | "recordTerminalDrain">,
+	now: () => number = () => performance.now(),
+	stdout: Pick<typeof process.stdout, "write" | "once"> = process.stdout,
+): () => void {
+	const original = stdout.write;
+	const pendingDrainWrites: number[] = [];
+	let drainListening = false;
+	const wrapped = function (this: typeof stdout, ...args: unknown[]): boolean {
+		const chunk = args[0];
+		const start = now();
+		const returned = Reflect.apply(original, this, args) as boolean;
+		const enqueueMs = Math.max(0, now() - start);
+		let bytes = 0;
+		try {
+			bytes = Buffer.isBuffer(chunk)
+				? chunk.byteLength
+				: ArrayBuffer.isView(chunk)
+					? chunk.byteLength
+					: Buffer.byteLength(String(chunk), typeof args[1] === "string" ? (args[1] as BufferEncoding) : "utf8");
+		} catch {
+			bytes = Buffer.byteLength(String(chunk), "utf8");
+		}
+		const writeId = trace.recordTerminalWrite({ bytes, enqueueMs, returned });
+		if (!returned) {
+			pendingDrainWrites.push(writeId);
+			if (!drainListening) {
+				drainListening = true;
+				stdout.once("drain", () => {
+					drainListening = false;
+					for (const pendingWriteId of pendingDrainWrites.splice(0)) trace.recordTerminalDrain(pendingWriteId);
+				});
+			}
+		}
+		return returned;
+	} as typeof stdout.write;
+	stdout.write = wrapped;
+	return () => {
+		if (stdout.write === wrapped) stdout.write = original;
+	};
+}