@oh-my-pi/pi-coding-agent 12.18.3 → 12.19.2

package/CHANGELOG.md

@@ -2,6 +2,59 @@
 
 ## [Unreleased]
 
+## [12.19.1] - 2026-02-22
+### Removed
+
+- Removed `replaceText` edit operation from hashline mode (substring-based text replacement)
+- Removed autocorrect heuristics that attempted to detect and fix line merges and formatting rewrites in hashline edits
+
+## [12.19.0] - 2026-02-22
+### Added
+
+- Added `poll_jobs` tool to block until background jobs complete, providing an alternative to polling `read jobs://` in loops
+- Added `task.maxConcurrency` setting to limit the number of concurrently executing subagent tasks
+- Added support for rendering markdown output from Python cells with proper formatting and theme styling
+- Added async background job execution for bash commands and tasks with `async: true` parameter
+- Added `cancel_job` tool to cancel running background jobs
+- Added `jobs://` internal protocol to inspect background job status and results
+- Added `/jobs` slash command to display running and recent background jobs in interactive mode
+- Added `async.enabled` and `async.maxJobs` settings to control background job execution
+- Added background job status indicator in status line showing count of running jobs
+- Added support for GitLab Duo authentication provider
+- Added clearer truncation notices across tools with consistent line/size context and continuation hints
+
+### Changed
+
+- Updated bash and task tool guidance to recommend `poll_jobs` instead of polling `read jobs://` in loops when waiting for async results
+- Improved parallel task execution to schedule multiple background jobs independently instead of batching all tasks into a single job, enabling true concurrent execution
+- Enhanced task progress tracking to report per-task status (pending, running, completed, failed, aborted) with individual timing and token metrics for each background task
+- Updated background task messaging to provide real-time progress counts (e.g., '2/5 finished') and distinguish between single and multiple task jobs
+- Hid internal `agent__intent` parameter from tool argument displays in UI and logs to reduce visual clutter
+- Updated Python tool to detect and handle markdown display output separately from plain text
+- Updated bash tool to support async execution mode with streaming progress updates
+- Updated task tool to support async execution mode for parallel subagent execution
+- Modified subagent settings to disable async execution in child agents to prevent nesting
+- Updated tool execution component to handle background async task state without spinner animation
+- Changed event controller to keep background tool calls pending until async completion
+- Updated status line width calculation to accommodate background job indicator
+- Updated the system prompt pipeline to reduce injected environment noise and make instructions more focused on execution quality
+- Updated system prompt/workflow guidance to emphasize root-cause fixes, code quality, and explicit handoff/testing expectations
+- Changed default value of `todo.reminders` setting from false to true to enable todo reminders by default
+- Improved truncation/output handling for large command results to reduce memory pressure and keep previews responsive
+- Updated internal artifact handling so tool output artifacts stay consistent across session switches and resumes
+
+### Removed
+
+- Removed git context (branch, status, commit history) from system prompt — version control information is no longer injected into agent instructions
+
+### Fixed
+
+- Fixed task progress display to hide tool count and token metrics when zero, reducing visual clutter in status output
+- Fixed Lobsters scraper to correctly parse API responses where user fields are strings instead of objects, resolving undefined user display in story listings
+- Fixed artifact manager caching to properly invalidate when session file changes, preventing stale artifact references
+- Fixed truncation behavior around UTF-8 boundaries and chunked output accounting
+- Fixed `submit_result` schema generation to use valid JSON Schema when no explicit output schema is provided
+
 ## [12.18.1] - 2026-02-21
 ### Added
 

package/package.json

@@ -1,10 +1,10 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-coding-agent",
-	"version": "12.18.3",
+	"version": "12.19.2",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://github.com/can1357/oh-my-pi",
-	"author": "Can Bölük",
+	"author": "Can Boluk",
 	"contributors": [
 		"Mario Zechner"
 	],
@@ -40,33 +40,33 @@
 		"test": "bun test"
 	},
 	"dependencies": {
-		"@mozilla/readability": "0.6.0",
-		"@oh-my-pi/omp-stats": "12.18.3",
-		"@oh-my-pi/pi-agent-core": "12.18.3",
-		"@oh-my-pi/pi-ai": "12.18.3",
-		"@oh-my-pi/pi-natives": "12.18.3",
-		"@oh-my-pi/pi-tui": "12.18.3",
-		"@oh-my-pi/pi-utils": "12.18.3",
-		"@sinclair/typebox": "^0.34.48",
-		"@xterm/headless": "^6.0.0",
-		"ajv": "^8.18.0",
-		"chalk": "^5.6.2",
-		"diff": "^8.0.3",
-		"file-type": "^21.3.0",
-		"glob": "^13.0.3",
-		"handlebars": "^4.7.8",
-		"ignore": "^7.0.5",
-		"linkedom": "^0.18.12",
-		"marked": "^17.0.2",
-		"node-html-parser": "^7.0.2",
-		"puppeteer": "^24.37.3",
-		"smol-toml": "^1.6.0",
-		"zod": "^4.3.6"
+		"@mozilla/readability": "^0.6",
+		"@oh-my-pi/omp-stats": "12.19.2",
+		"@oh-my-pi/pi-agent-core": "12.19.2",
+		"@oh-my-pi/pi-ai": "12.19.2",
+		"@oh-my-pi/pi-natives": "12.19.2",
+		"@oh-my-pi/pi-tui": "12.19.2",
+		"@oh-my-pi/pi-utils": "12.19.2",
+		"@sinclair/typebox": "^0.34",
+		"@xterm/headless": "^6.0",
+		"ajv": "^8.18",
+		"chalk": "^5.6",
+		"diff": "^8.0",
+		"file-type": "^21.3",
+		"glob": "^13.0",
+		"handlebars": "^4.7",
+		"ignore": "^7.0",
+		"linkedom": "^0.18",
+		"marked": "^17.0",
+		"node-html-parser": "^7.0",
+		"puppeteer": "^24.37",
+		"smol-toml": "^1.6",
+		"zod": "^4.3"
 	},
 	"devDependencies": {
-		"@types/bun": "^1.3.9",
-		"@types/ms": "^2.1.0",
-		"ms": "^2.1.3"
+		"@types/bun": "^1.3",
+		"@types/ms": "^2.1",
+		"ms": "^2.1"
 	},
 	"engines": {
 		"bun": ">=1.3.7"
@@ -87,6 +87,14 @@
 			"types": "./src/*.ts",
 			"import": "./src/*.ts"
 		},
+		"./async": {
+			"types": "./src/async/index.ts",
+			"import": "./src/async/index.ts"
+		},
+		"./async/*": {
+			"types": "./src/async/*.ts",
+			"import": "./src/async/*.ts"
+		},
 		"./capability": {
 			"types": "./src/capability/index.ts",
 			"import": "./src/capability/index.ts"

package/src/async/index.ts

@@ -0,0 +1 @@
+export * from "./job-manager";

package/src/async/job-manager.ts

@@ -0,0 +1,341 @@
+import { logger, Snowflake } from "@oh-my-pi/pi-utils";
+
+const DELIVERY_RETRY_BASE_MS = 500;
+const DELIVERY_RETRY_MAX_MS = 30_000;
+const DELIVERY_RETRY_JITTER_MS = 200;
+const DEFAULT_RETENTION_MS = 5 * 60 * 1000;
+const DEFAULT_MAX_RUNNING_JOBS = 15;
+
+export interface AsyncJob {
+	id: string;
+	type: "bash" | "task";
+	status: "running" | "completed" | "failed" | "cancelled";
+	startTime: number;
+	label: string;
+	abortController: AbortController;
+	promise: Promise<void>;
+	resultText?: string;
+	errorText?: string;
+}
+
+export interface AsyncJobManagerOptions {
+	onJobComplete: (jobId: string, text: string, job?: AsyncJob) => void | Promise<void>;
+	maxRunningJobs?: number;
+	retentionMs?: number;
+}
+
+interface AsyncJobDelivery {
+	jobId: string;
+	text: string;
+	attempt: number;
+	nextAttemptAt: number;
+	lastError?: string;
+}
+
+export interface AsyncJobDeliveryState {
+	queued: number;
+	delivering: boolean;
+	nextRetryAt?: number;
+	pendingJobIds: string[];
+}
+
+export interface AsyncJobRegisterOptions {
+	id?: string;
+	onProgress?: (text: string, details?: Record<string, unknown>) => void | Promise<void>;
+}
+
+export class AsyncJobManager {
+	readonly #jobs = new Map<string, AsyncJob>();
+	readonly #deliveries: AsyncJobDelivery[] = [];
+	readonly #evictionTimers = new Map<string, NodeJS.Timeout>();
+	readonly #onJobComplete: AsyncJobManagerOptions["onJobComplete"];
+	readonly #maxRunningJobs: number;
+	readonly #retentionMs: number;
+	#deliveryLoop: Promise<void> | undefined;
+	#disposed = false;
+
+	constructor(options: AsyncJobManagerOptions) {
+		this.#onJobComplete = options.onJobComplete;
+		this.#maxRunningJobs = Math.max(1, Math.floor(options.maxRunningJobs ?? DEFAULT_MAX_RUNNING_JOBS));
+		this.#retentionMs = Math.max(0, Math.floor(options.retentionMs ?? DEFAULT_RETENTION_MS));
+	}
+
+	register(
+		type: "bash" | "task",
+		label: string,
+		run: (ctx: {
+			jobId: string;
+			signal: AbortSignal;
+			reportProgress: (text: string, details?: Record<string, unknown>) => Promise<void>;
+		}) => Promise<string>,
+		options?: AsyncJobRegisterOptions,
+	): string {
+		if (this.#disposed) {
+			throw new Error("Async job manager is disposed");
+		}
+		const runningCount = this.getRunningJobs().length;
+		if (runningCount >= this.#maxRunningJobs) {
+			throw new Error(
+				`Background job limit reached (${this.#maxRunningJobs}). Wait for running jobs to finish or cancel one.`,
+			);
+		}
+
+		const id = this.#resolveJobId(options?.id);
+		const abortController = new AbortController();
+		const startTime = Date.now();
+
+		const job: AsyncJob = {
+			id,
+			type,
+			status: "running",
+			startTime,
+			label,
+			abortController,
+			promise: Promise.resolve(),
+		};
+
+		const reportProgress = async (text: string, details?: Record<string, unknown>): Promise<void> => {
+			if (!options?.onProgress) return;
+			try {
+				await options.onProgress(text, details);
+			} catch (error) {
+				logger.warn("Async job progress callback failed", {
+					jobId: id,
+					error: error instanceof Error ? error.message : String(error),
+				});
+			}
+		};
+		job.promise = (async () => {
+			try {
+				const text = await run({ jobId: id, signal: abortController.signal, reportProgress });
+				if (job.status === "cancelled") {
+					job.resultText = text;
+					this.#scheduleEviction(id);
+					return;
+				}
+				job.status = "completed";
+				job.resultText = text;
+				this.#enqueueDelivery(id, text);
+				this.#scheduleEviction(id);
+			} catch (error) {
+				if (job.status === "cancelled") {
+					job.errorText = error instanceof Error ? error.message : String(error);
+					this.#scheduleEviction(id);
+					return;
+				}
+				const errorText = error instanceof Error ? error.message : String(error);
+				job.status = "failed";
+				job.errorText = errorText;
+				this.#enqueueDelivery(id, errorText);
+				this.#scheduleEviction(id);
+			}
+		})();
+
+		this.#jobs.set(id, job);
+		return id;
+	}
+
+	cancel(id: string): boolean {
+		const job = this.#jobs.get(id);
+		if (!job) return false;
+		if (job.status !== "running") return false;
+		job.status = "cancelled";
+		job.abortController.abort();
+		this.#scheduleEviction(id);
+		return true;
+	}
+
+	getJob(id: string): AsyncJob | undefined {
+		return this.#jobs.get(id);
+	}
+
+	getRunningJobs(): AsyncJob[] {
+		return Array.from(this.#jobs.values()).filter(job => job.status === "running");
+	}
+
+	getRecentJobs(limit = 10): AsyncJob[] {
+		return Array.from(this.#jobs.values())
+			.filter(job => job.status !== "running")
+			.sort((a, b) => b.startTime - a.startTime)
+			.slice(0, limit);
+	}
+
+	getAllJobs(): AsyncJob[] {
+		return Array.from(this.#jobs.values());
+	}
+
+	getDeliveryState(): AsyncJobDeliveryState {
+		const nextRetryAt = this.#deliveries.reduce<number | undefined>((next, delivery) => {
+			if (next === undefined) return delivery.nextAttemptAt;
+			return Math.min(next, delivery.nextAttemptAt);
+		}, undefined);
+
+		return {
+			queued: this.#deliveries.length,
+			delivering: this.#deliveryLoop !== undefined,
+			nextRetryAt,
+			pendingJobIds: this.#deliveries.map(delivery => delivery.jobId),
+		};
+	}
+
+	hasPendingDeliveries(): boolean {
+		return this.#deliveries.length > 0;
+	}
+
+	cancelAll(): void {
+		for (const job of this.getRunningJobs()) {
+			job.status = "cancelled";
+			job.abortController.abort();
+			this.#scheduleEviction(job.id);
+		}
+	}
+
+	async waitForAll(): Promise<void> {
+		await Promise.all(Array.from(this.#jobs.values()).map(job => job.promise));
+	}
+
+	async drainDeliveries(options?: { timeoutMs?: number }): Promise<boolean> {
+		const timeoutMs = options?.timeoutMs;
+		const hasDeadline = timeoutMs !== undefined;
+		const deadline = hasDeadline ? Date.now() + Math.max(timeoutMs, 0) : Number.POSITIVE_INFINITY;
+
+		while (this.hasPendingDeliveries()) {
+			this.#ensureDeliveryLoop();
+			const loop = this.#deliveryLoop;
+			if (!loop) {
+				continue;
+			}
+
+			if (!hasDeadline) {
+				await loop;
+				continue;
+			}
+
+			const remainingMs = deadline - Date.now();
+			if (remainingMs <= 0) {
+				return false;
+			}
+
+			await Promise.race([loop, Bun.sleep(remainingMs)]);
+			if (Date.now() >= deadline && this.hasPendingDeliveries()) {
+				return false;
+			}
+		}
+
+		return true;
+	}
+
+	async dispose(options?: { timeoutMs?: number }): Promise<boolean> {
+		this.#disposed = true;
+		this.#clearEvictionTimers();
+		this.cancelAll();
+		await this.waitForAll();
+		const drained = await this.drainDeliveries({ timeoutMs: options?.timeoutMs ?? 3_000 });
+		this.#clearEvictionTimers();
+		this.#jobs.clear();
+		this.#deliveries.length = 0;
+		return drained;
+	}
+
+	#resolveJobId(preferredId?: string): string {
+		if (!preferredId || preferredId.trim().length === 0) {
+			return `bg_${Snowflake.next()}`;
+		}
+
+		const base = preferredId.trim();
+		if (!this.#jobs.has(base)) return base;
+
+		let suffix = 2;
+		let candidate = `${base}-${suffix}`;
+		while (this.#jobs.has(candidate)) {
+			suffix += 1;
+			candidate = `${base}-${suffix}`;
+		}
+		return candidate;
+	}
+
+	#scheduleEviction(jobId: string): void {
+		if (this.#retentionMs <= 0) {
+			this.#jobs.delete(jobId);
+			return;
+		}
+		const existing = this.#evictionTimers.get(jobId);
+		if (existing) {
+			clearTimeout(existing);
+		}
+		const timer = setTimeout(() => {
+			this.#evictionTimers.delete(jobId);
+			this.#jobs.delete(jobId);
+		}, this.#retentionMs);
+		timer.unref();
+		this.#evictionTimers.set(jobId, timer);
+	}
+
+	#clearEvictionTimers(): void {
+		for (const timer of this.#evictionTimers.values()) {
+			clearTimeout(timer);
+		}
+		this.#evictionTimers.clear();
+	}
+
+	#enqueueDelivery(jobId: string, text: string): void {
+		this.#deliveries.push({
+			jobId,
+			text,
+			attempt: 0,
+			nextAttemptAt: Date.now(),
+		});
+		this.#ensureDeliveryLoop();
+	}
+
+	#ensureDeliveryLoop(): void {
+		if (this.#deliveryLoop) {
+			return;
+		}
+
+		this.#deliveryLoop = this.#runDeliveryLoop()
+			.catch(error => {
+				logger.error("Async job delivery loop crashed", { error: String(error) });
+			})
+			.finally(() => {
+				this.#deliveryLoop = undefined;
+				if (this.#deliveries.length > 0) {
+					this.#ensureDeliveryLoop();
+				}
+			});
+	}
+
+	async #runDeliveryLoop(): Promise<void> {
+		while (this.#deliveries.length > 0) {
+			const delivery = this.#deliveries[0];
+			const waitMs = delivery.nextAttemptAt - Date.now();
+			if (waitMs > 0) {
+				await Bun.sleep(waitMs);
+			}
+
+			try {
+				await this.#onJobComplete(delivery.jobId, delivery.text, this.#jobs.get(delivery.jobId));
+				this.#deliveries.shift();
+			} catch (error) {
+				delivery.attempt += 1;
+				delivery.lastError = error instanceof Error ? error.message : String(error);
+				delivery.nextAttemptAt = Date.now() + this.#getRetryDelay(delivery.attempt);
+				this.#deliveries.shift();
+				this.#deliveries.push(delivery);
+				logger.warn("Async job completion delivery failed", {
+					jobId: delivery.jobId,
+					attempt: delivery.attempt,
+					nextRetryAt: delivery.nextAttemptAt,
+					error: delivery.lastError,
+				});
+			}
+		}
+	}
+
+	#getRetryDelay(attempt: number): number {
+		const exp = Math.min(Math.max(attempt - 1, 0), 8);
+		const backoffMs = DELIVERY_RETRY_BASE_MS * 2 ** exp;
+		const jitterMs = Math.floor(Math.random() * DELIVERY_RETRY_JITTER_MS);
+		return Math.min(DELIVERY_RETRY_MAX_MS, backoffMs + jitterMs);
+	}
+}

package/src/cli/file-processor.ts

@@ -8,7 +8,7 @@ import { isEnoent } from "@oh-my-pi/pi-utils";
 import { getProjectDir } from "@oh-my-pi/pi-utils/dirs";
 import chalk from "chalk";
 import { resolveReadPath } from "../tools/path-utils";
-import { formatSize } from "../tools/truncate";
+import { formatBytes } from "../tools/render-utils";
 import { formatDimensionNote, resizeImage } from "../utils/image-resize";
 import { detectSupportedImageMimeTypeFromFile } from "../utils/mime";
 
@@ -47,9 +47,9 @@ export async function processFileArguments(fileArgs: string[], options?: Process
 		const maxBytes = mimeType ? MAX_CLI_IMAGE_BYTES : MAX_CLI_TEXT_BYTES;
 		if (stat.size > maxBytes) {
 			console.error(
-				chalk.yellow(`Warning: Skipping file contents (too large: ${formatSize(stat.size)}): ${absolutePath}`),
+				chalk.yellow(`Warning: Skipping file contents (too large: ${formatBytes(stat.size)}): ${absolutePath}`),
 			);
-			text += `<file name="${absolutePath}">(skipped: too large, ${formatSize(stat.size)})</file>\n`;
+			text += `<file name="${absolutePath}">(skipped: too large, ${formatBytes(stat.size)})</file>\n`;
 			continue;
 		}
 

package/src/cli/list-models.ts

@@ -2,24 +2,10 @@
  * List available models with optional fuzzy search
  */
 import type { Api, Model } from "@oh-my-pi/pi-ai";
+import { formatNumber } from "@oh-my-pi/pi-utils";
 import type { ModelRegistry } from "../config/model-registry";
 import { fuzzyFilter } from "../utils/fuzzy";
 
-/**
- * Format a number as human-readable (e.g., 200000 -> "200K", 1000000 -> "1M")
- */
-function formatTokenCount(count: number): string {
-	if (count >= 1_000_000) {
-		const millions = count / 1_000_000;
-		return millions % 1 === 0 ? `${millions}M` : `${millions.toFixed(1)}M`;
-	}
-	if (count >= 1_000) {
-		const thousands = count / 1_000;
-		return thousands % 1 === 0 ? `${thousands}K` : `${thousands.toFixed(1)}K`;
-	}
-	return count.toString();
-}
-
 /**
  * List available models, optionally filtered by search pattern
  */
@@ -53,8 +39,8 @@ export async function listModels(modelRegistry: ModelRegistry, searchPattern?: s
 	const rows = filteredModels.map(m => ({
 		provider: m.provider,
 		model: m.id,
-		context: formatTokenCount(m.contextWindow),
-		maxOut: formatTokenCount(m.maxTokens),
+		context: formatNumber(m.contextWindow),
+		maxOut: formatNumber(m.maxTokens),
 		thinking: m.reasoning ? "yes" : "no",
 		images: m.input.includes("image") ? "yes" : "no",
 	}));

package/src/cli/stats-cli.ts

@@ -4,6 +4,7 @@
  * Handles `omp stats` subcommand for viewing AI usage statistics.
  */
 
+import { formatDuration, formatNumber, formatPercent } from "@oh-my-pi/pi-utils";
 import { APP_NAME } from "@oh-my-pi/pi-utils/dirs";
 import chalk from "chalk";
 import { openPath } from "../utils/open";
@@ -53,32 +54,12 @@ export function parseStatsArgs(args: string[]): StatsCommandArgs | undefined {
 	return result;
 }
 
-// =============================================================================
-// Formatting Helpers
-// =============================================================================
-
-function formatNumber(n: number): string {
-	if (n >= 1_000_000) return `${(n / 1_000_000).toFixed(1)}M`;
-	if (n >= 1_000) return `${(n / 1_000).toFixed(1)}K`;
-	return n.toFixed(0);
-}
-
 function formatCost(n: number): string {
 	if (n < 0.01) return `$${n.toFixed(4)}`;
 	if (n < 1) return `$${n.toFixed(3)}`;
 	return `$${n.toFixed(2)}`;
 }
 
-function formatDuration(ms: number | null): string {
-	if (ms === null) return "-";
-	if (ms < 1000) return `${ms.toFixed(0)}ms`;
-	return `${(ms / 1000).toFixed(1)}s`;
-}
-
-function formatPercent(n: number): string {
-	return `${(n * 100).toFixed(1)}%`;
-}
-
 // =============================================================================
 // Command Handler
 // =============================================================================
@@ -140,8 +121,8 @@ async function printStatsSummary(): Promise<void> {
 	console.log(`  Total Tokens: ${formatNumber(overall.totalInputTokens + overall.totalOutputTokens)}`);
 	console.log(`  Cache Rate: ${formatPercent(overall.cacheRate)}`);
 	console.log(`  Total Cost: ${formatCost(overall.totalCost)}`);
-	console.log(`  Avg Duration: ${formatDuration(overall.avgDuration)}`);
-	console.log(`  Avg TTFT: ${formatDuration(overall.avgTtft)}`);
+	console.log(`  Avg Duration: ${overall.avgDuration !== null ? formatDuration(overall.avgDuration) : "-"}`);
+	console.log(`  Avg TTFT: ${overall.avgTtft !== null ? formatDuration(overall.avgTtft) : "-"}`);
 	if (overall.avgTokensPerSecond !== null) {
 		console.log(`  Avg Tokens/s: ${overall.avgTokensPerSecond.toFixed(1)}`);
 	}

package/src/cli/web-search-cli.ts

@@ -64,24 +64,24 @@ export function parseSearchArgs(args: string[]): SearchCommandArgs | undefined {
 
 export async function runSearchCommand(cmd: SearchCommandArgs): Promise<void> {
 	if (!cmd.query) {
-		writeStderr(chalk.red("Error: Query is required"));
+		process.stderr.write(`${chalk.red("Error: Query is required")}\n`);
 		process.exit(1);
 	}
 
 	if (cmd.provider && !PROVIDERS.includes(cmd.provider)) {
-		writeStderr(chalk.red(`Error: Unknown provider "${cmd.provider}"`));
-		writeStderr(chalk.dim(`Valid providers: ${PROVIDERS.join(", ")}`));
+		process.stderr.write(`${chalk.red(`Error: Unknown provider "${cmd.provider}"`)}\n`);
+		process.stderr.write(`${chalk.dim(`Valid providers: ${PROVIDERS.join(", ")}`)}\n`);
 		process.exit(1);
 	}
 
 	if (cmd.recency && !RECENCY_OPTIONS.includes(cmd.recency)) {
-		writeStderr(chalk.red(`Error: Invalid recency "${cmd.recency}"`));
-		writeStderr(chalk.dim(`Valid recency values: ${RECENCY_OPTIONS.join(", ")}`));
+		process.stderr.write(`${chalk.red(`Error: Invalid recency "${cmd.recency}"`)}\n`);
+		process.stderr.write(`${chalk.dim(`Valid recency values: ${RECENCY_OPTIONS.join(", ")}`)}\n`);
 		process.exit(1);
 	}
 
 	if (cmd.limit !== undefined && Number.isNaN(cmd.limit)) {
-		writeStderr(chalk.red("Error: --limit must be a number"));
+		process.stderr.write(`${chalk.red("Error: --limit must be a number")}\n`);
 		process.exit(1);
 	}
 
@@ -104,7 +104,7 @@ export async function runSearchCommand(cmd: SearchCommandArgs): Promise<void> {
 	});
 
 	const width = Math.max(60, process.stdout.columns ?? 100);
-	writeStdout(component.render(width).join("\n"));
+	process.stdout.write(`${component.render(width).join("\n")}\n`);
 
 	if (result.details?.error) {
 		process.exitCode = 1;
@@ -112,7 +112,7 @@ export async function runSearchCommand(cmd: SearchCommandArgs): Promise<void> {
 }
 
 export function printSearchHelp(): void {
-	writeStdout(`${chalk.bold(`${APP_NAME} q`)} - Test web search providers
+	process.stdout.write(`${chalk.bold(`${APP_NAME} q`)} - Test web search providers
 
 ${chalk.bold("Usage:")}
   ${APP_NAME} q [options] <query>
@@ -133,11 +133,3 @@ ${chalk.bold("Examples:")}
   ${APP_NAME} q --provider=brave --recency=week "latest TypeScript 5.7 changes"
 `);
 }
-
-function writeStdout(message: string): void {
-	process.stdout.write(`${message}\n`);
-}
-
-function writeStderr(message: string): void {
-	process.stderr.write(`${message}\n`);
-}