@oh-my-pi-zen/pi-utils 16.3.6-zen.1

package/src/env.ts

@@ -0,0 +1,226 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { getAgentDir, getConfigRootDir, refreshDirsFromEnv } from "./dirs";
+
+export * from "./worker-host";
+
+const ENV_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+/**
+ * Strict shell-identifier shape. Used for dotenv keys we accept into
+ * `Bun.env` — those should be referenceable as `$NAME` from POSIX shells,
+ * so we reject anything outside `[A-Za-z_][A-Za-z0-9_]*`.
+ */
+export function isValidEnvName(name: string): boolean {
+	return ENV_NAME_RE.test(name);
+}
+
+/**
+ * The only names that are genuinely unsafe to forward to a native `execve`
+ * spawn: empty, containing `=` (would corrupt the `KEY=VALUE` framing) or
+ * NUL (terminates the C string mid-entry). Windows ships standard variables
+ * whose names contain parentheses (e.g. `ProgramFiles(x86)`, `CommonProgramFiles(x86)`)
+ * — those MUST survive the scrub so downstream resolvers (Git Bash discovery
+ * in `procmgr.ts`, etc.) can still read them.
+ */
+export function isSafeEnvName(name: string): boolean {
+	return name.length > 0 && !name.includes("=") && !name.includes("\0");
+}
+
+export function isSafeEnvValue(value: string): boolean {
+	return !value.includes("\0");
+}
+
+export function isMacosMallocStackLoggingEnvName(name: string): boolean {
+	return name === "MallocStackLogging" || name === "MallocStackLoggingNoCompact";
+}
+
+export function filterProcessEnv(env: Record<string, string | undefined>): Record<string, string> {
+	const result: Record<string, string> = {};
+	for (const key in env) {
+		const value = env[key];
+		if (
+			!isSafeEnvName(key) ||
+			isMacosMallocStackLoggingEnvName(key) ||
+			value === undefined ||
+			!isSafeEnvValue(value)
+		) {
+			continue;
+		}
+		result[key] = value;
+	}
+	return result;
+}
+
+/**
+ * Parses a .env file synchronously and extracts key-value string pairs.
+ * Ignores lines that are empty or start with '#'. Trims whitespace.
+ * Allows values to be quoted with single or double quotes.
+ * Returns an object of key-value pairs.
+ */
+export function parseEnvFile(filePath: string): Record<string, string> {
+	const result: Record<string, string> = {};
+	try {
+		const content = fs.readFileSync(filePath, "utf-8");
+		for (const line of content.split("\n")) {
+			const trimmed = line.trim();
+			// Skip comments and blank lines
+			if (!trimmed || trimmed.startsWith("#")) continue;
+
+			const eqIndex = trimmed.indexOf("=");
+			if (eqIndex === -1) continue;
+
+			const key = trimmed.slice(0, eqIndex).trim();
+			if (!isValidEnvName(key)) continue;
+
+			let value = trimmed.slice(eqIndex + 1).trim();
+
+			// Remove surrounding quotes (" or ')
+			if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+				value = value.slice(1, -1);
+			}
+			if (!isSafeEnvValue(value)) continue;
+
+			result[key] = value;
+		}
+	} catch {
+		// File doesn't exist or can't be read - return empty result
+	}
+
+	// OMP_ overrides PI_
+	for (const k in result) {
+		if (k.startsWith("OMP_")) {
+			result[`PI_${k.slice(4)}`] = result[k];
+		}
+	}
+
+	return result;
+}
+
+// Eagerly parse the user's $HOME/.env and the current project's .env (from cwd)
+const homeEnv = parseEnvFile(path.join(os.homedir(), ".env"));
+const piEnv = parseEnvFile(path.join(getConfigRootDir(), ".env"));
+const agentEnv = parseEnvFile(path.join(getAgentDir(), ".env"));
+const projectEnv = parseEnvFile(path.join(process.cwd(), ".env"));
+
+for (const key of Object.keys(Bun.env)) {
+	const value = Bun.env[key];
+	if (!isSafeEnvName(key) || isMacosMallocStackLoggingEnvName(key) || value === undefined || !isSafeEnvValue(value)) {
+		delete Bun.env[key];
+	}
+}
+
+for (const file of [projectEnv, agentEnv, piEnv, homeEnv]) {
+	for (const key in file) {
+		if (!isMacosMallocStackLoggingEnvName(key) && !Bun.env[key]) {
+			Bun.env[key] = file[key];
+		}
+	}
+}
+
+// Directory-affecting keys (XDG_*_HOME, and in default mode PI_CODING_AGENT_DIR)
+// may have just arrived from the profile/agent `.env` applied above. The dirs
+// resolver cached its paths at module load — before this file ran — so rebuild
+// it now from the updated env. `getAgentDir()` already located the `.env` from
+// the profile name + home, so this re-reads only the directory vars.
+refreshDirsFromEnv();
+
+/**
+ * Intentional re-export of Bun.env.
+ *
+ * All users should import this env module (import { $env } from "@oh-my-pi-zen/pi-utils")
+ * before using environment variables. This ensures that .env files have been loaded and
+ * overrides (project, home) have been applied, so $env always reflects the correct values.
+ */
+export const $env: Record<string, string> = Bun.env as Record<string, string>;
+
+/**
+ * Resolve the first environment variable value from the given keys.
+ * @param keys - The keys to resolve.
+ * @returns The first environment variable value, or undefined if no value is found.
+ */
+export function $pickenv(...keys: string[]): string | undefined {
+	for (const key of keys) {
+		const value = Bun.env[key]?.trim();
+		if (value) {
+			return value;
+		}
+	}
+	return undefined;
+}
+
+/**
+ * Parses a positive decimal integer from `$env[name]`.
+ * Empty, invalid, NaN, zero, or negative values return `defaultValue`.
+ */
+export function $envpos(name: string, defaultValue: number): number {
+	const raw = $env[name];
+	if (!raw) return defaultValue;
+	const parsed = Number.parseInt(raw, 10);
+	if (Number.isNaN(parsed) || parsed <= 0) return defaultValue;
+	return parsed;
+}
+
+/** True when `BUN_ENV` or `NODE_ENV` is the string `test`. */
+export function isBunTestRuntime(): boolean {
+	return Bun.env.BUN_ENV === "test" || Bun.env.NODE_ENV === "test";
+}
+
+let terminalHeadless = isBunTestRuntime();
+
+/**
+ * True when real-terminal side effects must be suppressed: stdout escape/frame
+ * writes, stdin raw-mode + resume, CSI/OSC capability probes, SIGWINCH, window
+ * title changes, and emergency restore. Defaults to {@link isBunTestRuntime} so
+ * `bun test` launched inside a real TTY never paints the TUI, leaks probe
+ * queries, or hijacks the developer's stdin; production runtimes stay
+ * interactive.
+ *
+ * Terminal-contract tests that must exercise the real I/O path opt out with
+ * `setTerminalHeadless(false)` and restore it afterwards.
+ */
+export function isTerminalHeadless(): boolean {
+	return terminalHeadless;
+}
+
+/**
+ * Override the {@link isTerminalHeadless} default and return the previous value
+ * so callers can restore exact prior state (`const prev = setTerminalHeadless(false); … setTerminalHeadless(prev);`).
+ */
+export function setTerminalHeadless(headless: boolean): boolean {
+	const previous = terminalHeadless;
+	terminalHeadless = headless;
+	return previous;
+}
+
+/**
+ * True when this code is running inside a `bun build --compile` standalone
+ * binary. Detects via the embedded virtual-filesystem path markers
+ * (`$bunfs`, `~BUN`, or its URL-encoded form `%7EBUN`) in `import.meta.url`,
+ * which Bun rewrites for every module bundled into the executable. The
+ * `PI_COMPILED` env var (set by the build script's `--define`) is checked
+ * first for cheap fast-path detection.
+ */
+export function isCompiledBinary(): boolean {
+	if (process.env.PI_COMPILED || Bun.env.PI_COMPILED) return true;
+	const url = import.meta.url;
+	return url.includes("$bunfs") || url.includes("~BUN") || url.includes("%7EBUN");
+}
+
+const TRUTHY: Dict<boolean> = {
+	"1": true,
+	Y: true,
+	y: true,
+	TRUE: true,
+	true: true,
+	YES: true,
+	yes: true,
+	ON: true,
+	on: true,
+};
+export function $flag(name: string, def: boolean = false): boolean {
+	const value = $env[name];
+	if (!value) return def;
+	return TRUTHY[value] === true;
+}

package/src/fetch-retry.ts

@@ -0,0 +1,355 @@
+import { scheduler } from "node:timers/promises";
+
+// "reset after 1h2m3s" / "10m15s" / "39s"
+const QUOTA_RESET_PATTERN = /reset after (?:(\d+)h)?(?:(\d+)m)?(\d+(?:\.\d+)?)s/i;
+// "Please retry in 250ms" / "Please retry in 12s"
+const PLEASE_RETRY_PATTERN = /Please retry in ([0-9.]+)(ms|s)/i;
+// JSON field: "retryDelay": "34.074824224s"
+const RETRY_DELAY_FIELD_PATTERN = /"retryDelay":\s*"([0-9.]+)(ms|s)"/i;
+// "try again in 250ms" / "try again in 12s" / "try again in 12sec" /
+// "try again in 5 min" / "try again in ~158 min." / "try again in 2h" /
+// "try again in 90 minutes" / "try again in 1 hour"
+const TRY_AGAIN_PATTERN = /try again in\s+~?\s*([0-9.]+)\s*(ms|sec|s|minutes?|mins?|m|hours?|hrs?|h)\b/i;
+
+/**
+ * Server-suggested retry delay extraction. Merges the patterns historically used
+ * by the OpenAI Codex and Google Gemini retry helpers.
+ *
+ * Header sources (checked in order):
+ *  - `Retry-After` (numeric seconds, or HTTP date)
+ *  - `x-ratelimit-reset` (Unix epoch seconds)
+ *  - `x-ratelimit-reset-after` (seconds)
+ *
+ * Body patterns:
+ *  - `Your quota will reset after 18h31m10s` / `10m15s` / `39s`
+ *  - `Please retry in 250ms` / `Please retry in 12s`
+ *  - `"retryDelay": "34.074824224s"` (JSON error detail field)
+ *  - `try again in 250ms` / `try again in 12s` / `try again in 5 min` / `try again in ~158 min`
+ *
+ * Returns `undefined` if no signal is found.
+ */
+export function extractRetryHint(source: Response | Headers | null | undefined, body?: string): number | undefined {
+	const headers = source instanceof Headers ? source : (source?.headers ?? undefined);
+	if (headers) {
+		const retryAfter = headers.get("retry-after");
+		if (retryAfter) {
+			const seconds = Number(retryAfter);
+			if (Number.isFinite(seconds)) return Math.max(0, seconds * 1000);
+			const parsedDate = Date.parse(retryAfter);
+			if (!Number.isNaN(parsedDate)) return Math.max(0, parsedDate - Date.now());
+		}
+		const rateLimitReset = headers.get("x-ratelimit-reset");
+		if (rateLimitReset) {
+			const resetSeconds = Number.parseInt(rateLimitReset, 10);
+			if (!Number.isNaN(resetSeconds)) {
+				const delta = resetSeconds * 1000 - Date.now();
+				if (delta > 0) return delta;
+			}
+		}
+		const rateLimitResetAfter = headers.get("x-ratelimit-reset-after");
+		if (rateLimitResetAfter) {
+			const seconds = Number(rateLimitResetAfter);
+			if (Number.isFinite(seconds) && seconds > 0) return seconds * 1000;
+		}
+	}
+
+	if (!body) return undefined;
+
+	const quotaMatch = QUOTA_RESET_PATTERN.exec(body);
+	if (quotaMatch) {
+		const hours = quotaMatch[1] ? Number.parseInt(quotaMatch[1], 10) : 0;
+		const minutes = quotaMatch[2] ? Number.parseInt(quotaMatch[2], 10) : 0;
+		const seconds = Number.parseFloat(quotaMatch[3]!);
+		if (!Number.isNaN(seconds)) {
+			const totalMs = ((hours * 60 + minutes) * 60 + seconds) * 1000;
+			if (totalMs > 0) return totalMs;
+		}
+	}
+	for (const pattern of [PLEASE_RETRY_PATTERN, RETRY_DELAY_FIELD_PATTERN, TRY_AGAIN_PATTERN]) {
+		const match = pattern.exec(body);
+		if (match?.[1]) {
+			const value = Number.parseFloat(match[1]);
+			if (Number.isFinite(value) && value > 0) {
+				const unitMs = unitToMs(match[2]!);
+				if (unitMs !== undefined) return value * unitMs;
+			}
+		}
+	}
+	return undefined;
+}
+
+function unitToMs(unit: string): number | undefined {
+	switch (unit.toLowerCase()) {
+		case "ms":
+			return 1;
+		case "s":
+		case "sec":
+			return 1000;
+		case "m":
+		case "min":
+		case "mins":
+		case "minute":
+		case "minutes":
+			return 60_000;
+		case "h":
+		case "hr":
+		case "hrs":
+		case "hour":
+		case "hours":
+			return 60 * 60_000;
+		default:
+			return undefined;
+	}
+}
+
+export interface FetchWithRetryOptions extends RequestInit {
+	/** Total fetch attempts (initial + retries). Default `5`. */
+	maxAttempts?: number;
+	/**
+	 * Per-delay cap. Server-provided `Retry-After` hints exceeding this return
+	 * the current response immediately — caller deals with the `!response.ok`.
+	 * Default `60_000`.
+	 */
+	maxDelayMs?: number;
+	/**
+	 * Fallback delay schedule when no server hint is present. Number, array
+	 * (indexed by attempt, clamped to last), or function. Default exponential
+	 * `500ms * 2 ** attempt` capped at `maxDelayMs`.
+	 */
+	defaultDelayMs?: number | readonly number[] | ((attempt: number) => number);
+	/**
+	 * Optional per-attempt overlay merged into the base `RequestInit` each try.
+	 * Headers from the overlay shallow-merge over the base. Useful for auth
+	 * token refresh or user-agent rotation.
+	 */
+	prepareInit?: (attempt: number) => RequestInit | Promise<RequestInit>;
+	/**
+	 * Optional `fetch` implementation override. Defaults to `globalThis.fetch`.
+	 * Useful for routing requests through a proxy, instrumented transport, or
+	 * mock during tests.
+	 */
+	fetch?: (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+	/**
+	 * Optional retry gate for HTTP responses whose status is retryable. Receives a
+	 * cloned body string so callers can fail fast on deterministic provider
+	 * failures that happen to use a 5xx status.
+	 */
+	shouldRetryResponse?: (response: Response, bodyText: string, attempt: number) => boolean | Promise<boolean>;
+	/**
+	 * Bun extension forwarded verbatim to the underlying `fetch` call. `false`
+	 * disables Bun's native ~300s pre-response timeout (callers that own a
+	 * configurable first-event/idle watchdog or an external `AbortSignal`
+	 * supply this so the runtime ceiling cannot pre-empt them); a positive
+	 * number sets a custom ceiling in ms. Bare browser/Node fetch ignores it.
+	 */
+	timeout?: number | false;
+}
+
+const DEFAULT_MAX_DELAY_MS = 60_000;
+const DEFAULT_MAX_ATTEMPTS = 5;
+
+/**
+ * Fetch with bounded retries and sensible defaults. Retries on any
+ * `isRetryableStatus` (5xx, 408, 429) and on transient network errors. Server
+ * `Retry-After`/quota hints are honoured up to `maxDelayMs`; a hint that exceeds
+ * the cap returns the current response so the caller can fail fast. Aborts on
+ * `init.signal` propagate as `"Request was aborted"`.
+ *
+ * The caller is responsible for inspecting `!response.ok` once the call returns.
+ */
+export async function fetchWithRetry(
+	url: string | URL | ((attempt: number) => string | URL),
+	options: FetchWithRetryOptions = {},
+): Promise<Response> {
+	const {
+		maxAttempts = DEFAULT_MAX_ATTEMPTS,
+		maxDelayMs = DEFAULT_MAX_DELAY_MS,
+		defaultDelayMs,
+		prepareInit,
+		shouldRetryResponse,
+		fetch: fetchImpl = fetch,
+		timeout = false,
+		...baseInit
+	} = options;
+	const signal = baseInit.signal as AbortSignal | undefined;
+
+	for (let attempt = 0; ; attempt++) {
+		if (signal?.aborted) throw new Error("Request was aborted");
+		const requestUrl = typeof url === "function" ? url(attempt) : url;
+		// `timeout` is destructured out of `baseInit`, so forward it to the underlying
+		// fetch on the no-`prepareInit` path too. Without this, callers that pass
+		// `timeout: false` (every streaming provider, to disable Bun's native ~300s
+		// fetch ceiling in favor of their own first-event/idle watchdog) had it
+		// silently dropped, so long-running streams were killed at ~300s (issue #602).
+		// Only forward when the caller actually set `timeout`, so callers that never
+		// set it keep Bun's default ceiling.
+		const init = prepareInit
+			? mergeInit(baseInit, await prepareInit(attempt), timeout)
+			: "timeout" in options
+				? ({ ...baseInit, timeout } as unknown as RequestInit)
+				: baseInit;
+
+		let response: Response;
+		try {
+			response = await fetchImpl(requestUrl, init);
+		} catch (error) {
+			if (signal?.aborted) throw new Error("Request was aborted");
+			const wrapped = wrapNetworkError(error);
+			if (attempt + 1 >= maxAttempts) throw wrapped;
+			await scheduler.wait(resolveDefaultDelay(defaultDelayMs, attempt, maxDelayMs), { signal });
+			continue;
+		}
+
+		if (!isRetryableStatus(response.status)) return response;
+		if (attempt + 1 >= maxAttempts) return response;
+
+		const retryBody = await response.clone().text();
+		if (shouldRetryResponse && !(await shouldRetryResponse(response, retryBody, attempt))) return response;
+
+		const hint = extractRetryHint(response, retryBody);
+		if (hint !== undefined && hint > maxDelayMs) return response;
+
+		const delayMs = Math.min(hint ?? resolveDefaultDelay(defaultDelayMs, attempt, maxDelayMs), maxDelayMs);
+		await scheduler.wait(delayMs, { signal });
+	}
+}
+
+function mergeInit(base: RequestInit, overlay: RequestInit, timeout: number | false): RequestInit {
+	const merged = { ...base, ...overlay, timeout } as unknown as RequestInit;
+	if (base.headers || overlay.headers) {
+		const baseHeaders = new Headers(base.headers ?? undefined);
+		const overlayHeaders = new Headers(overlay.headers ?? undefined);
+		overlayHeaders.forEach((value, key) => {
+			baseHeaders.set(key, value);
+		});
+		merged.headers = baseHeaders;
+	}
+	return merged;
+}
+
+function wrapNetworkError(error: unknown): Error {
+	if (error instanceof Error) {
+		if (error.name === "AbortError" || error.message === "Request was aborted") {
+			return new Error("Request was aborted");
+		}
+		if (error.message === "fetch failed" && error.cause instanceof Error) {
+			return new Error(`Network error: ${error.cause.message}`);
+		}
+		return error;
+	}
+	return new Error(String(error));
+}
+
+function resolveDefaultDelay(
+	option: FetchWithRetryOptions["defaultDelayMs"],
+	attempt: number,
+	maxDelayMs: number,
+): number {
+	if (option === undefined) return Math.min(500 * 2 ** attempt, maxDelayMs);
+	if (typeof option === "number") return Math.min(option, maxDelayMs);
+	if (typeof option === "function") return Math.min(option(attempt), maxDelayMs);
+	return Math.min(option[Math.min(attempt, option.length - 1)] ?? 0, maxDelayMs);
+}
+
+/**
+ * Inspect an arbitrary error value (or its `cause` chain, up to depth 2) for an
+ * HTTP status code. Reads `status`, `statusCode`, and `response.status` fields,
+ * coerces string values, and falls back to scanning the error message for
+ * common patterns like `Error: 401`, `error (429)`, or `HTTP 503`.
+ */
+export function extractHttpStatusFromError(error: unknown): number | undefined {
+	return extractHttpStatusFromErrorInternal(error, 0);
+}
+
+type HttpErrorLike = {
+	message?: string;
+	name?: string;
+	status?: number | string;
+	statusCode?: number | string;
+	response?: { status?: number | string };
+	cause?: unknown;
+};
+
+function extractHttpStatusFromErrorInternal(error: unknown, depth: number): number | undefined {
+	if (!error || typeof error !== "object" || depth > 2) return undefined;
+	const info = error as HttpErrorLike;
+	const rawStatus = info.status ?? info.statusCode ?? info.response?.status;
+
+	let status: number | undefined;
+	if (typeof rawStatus === "number" && Number.isFinite(rawStatus)) {
+		status = rawStatus;
+	} else if (typeof rawStatus === "string") {
+		const parsed = Number(rawStatus);
+		if (Number.isFinite(parsed)) status = parsed;
+	}
+	if (status !== undefined && status >= 100 && status <= 599) return status;
+
+	if (info.message) {
+		const extracted = extractStatusFromMessage(info.message);
+		if (extracted !== undefined) return extracted;
+	}
+	if (info.cause) return extractHttpStatusFromErrorInternal(info.cause, depth + 1);
+	return undefined;
+}
+
+const STATUS_MESSAGE_PATTERNS = [
+	/\berror\s*[:=]\s*(\d{3})\b/i,
+	/error\s*\((\d{3})\)/i,
+	/status\s*[:=]?\s*(\d{3})/i,
+	/\bhttp\s*(\d{3})\b/i,
+	/\b(\d{3})\s*(?:status|error)\b/i,
+] as const;
+
+function extractStatusFromMessage(message: string): number | undefined {
+	for (const pattern of STATUS_MESSAGE_PATTERNS) {
+		const match = pattern.exec(message);
+		if (!match) continue;
+		const value = Number(match[1]);
+		if (Number.isFinite(value) && value >= 100 && value <= 599) return value;
+	}
+	return undefined;
+}
+
+/**
+ * `true` if the given HTTP status code is one we treat as transient: 408
+ * (Request Timeout), 429 (Too Many Requests), or any 5xx (server error).
+ */
+export function isRetryableStatus(status: number): boolean {
+	return status >= 500 || status === 408 || status === 429;
+}
+
+/**
+ * `true` if the message describes an unexpected socket closure — Bun and some
+ * proxies surface these for any HTTP/2 stream reset.
+ */
+export function isUnexpectedSocketCloseMessage(message: string): boolean {
+	return /\b(?:the\s+)?socket connection (?:was )?closed unexpectedly\b/i.test(message);
+}
+
+const TRANSIENT_MESSAGE_PATTERN =
+	/overloaded|rate.?limit|too many requests|service.?unavailable|server error|internal error|connection.?error|unable to connect|fetch failed|network error|stream stall|other side closed|HTTP2(?:StreamReset|RefusedStream|EnhanceYourCalm)/i;
+
+const VALIDATION_MESSAGE_PATTERN =
+	/invalid|validation|bad request|unsupported|schema|missing required|not found|unauthorized|forbidden/i;
+
+/**
+ * Identify errors that should be retried: aborts/timeouts in the error name or
+ * message, retryable HTTP statuses (see `isRetryableStatus`), unexpected socket
+ * closes, and the standard transient phrases. 4xx statuses other than 408/429
+ * and validation-shaped messages short-circuit to `false`.
+ */
+export function isRetryableError(error: unknown): boolean {
+	const info = error as { message?: string; name?: string } | null;
+	const message = info?.message ?? "";
+	const name = info?.name ?? "";
+	if (name === "AbortError" || /timeout|timed out|aborted/i.test(message)) return true;
+
+	const status = extractHttpStatusFromError(error);
+	if (status !== undefined) {
+		if (isRetryableStatus(status)) return true;
+		if (status >= 400 && status < 500) return false;
+	}
+
+	if (VALIDATION_MESSAGE_PATTERN.test(message)) return false;
+	return isUnexpectedSocketCloseMessage(message) || TRANSIENT_MESSAGE_PATTERN.test(message);
+}

package/src/format.ts

@@ -0,0 +1,113 @@
+const SEC = 1_000;
+const MIN = 60 * SEC;
+const HOUR = 60 * MIN;
+const DAY = 24 * HOUR;
+
+/**
+ * Format a duration in milliseconds to a short human-readable string.
+ * Examples: "123ms", "1.5s", "30m15s", "2h30m", "3d2h"
+ */
+export function formatDuration(ms: number): string {
+	if (!Number.isFinite(ms) || ms <= 0) return "0ms";
+	if (ms < SEC) return `${ms}ms`;
+	if (ms < MIN) return `${(ms / SEC).toFixed(1)}s`;
+	if (ms < HOUR) {
+		const mins = Math.floor(ms / MIN);
+		const secs = Math.floor((ms % MIN) / SEC);
+		return secs > 0 ? `${mins}m${secs}s` : `${mins}m`;
+	}
+	if (ms < DAY) {
+		const hours = Math.floor(ms / HOUR);
+		const mins = Math.floor((ms % HOUR) / MIN);
+		return mins > 0 ? `${hours}h${mins}m` : `${hours}h`;
+	}
+	const days = Math.floor(ms / DAY);
+	const hours = Math.floor((ms % DAY) / HOUR);
+	return hours > 0 ? `${days}d${hours}h` : `${days}d`;
+}
+
+/**
+ * Format a number with K/M/B suffix for compact display.
+ * Uses 1 decimal for small leading digits when non-zero, rounded otherwise.
+ * Examples: "999", "1K", "1.5K", "25K", "1M", "1.5M", "25M", "1.5B"
+ */
+export function formatNumber(n: number): string {
+	if (n < 1_000) return n.toString();
+	if (n < 10_000) return `${trim1(n / 1_000)}K`;
+	if (n < 1_000_000) return `${Math.round(n / 1_000)}K`;
+	if (n < 10_000_000) return `${trim1(n / 1_000_000)}M`;
+	if (n < 1_000_000_000) return `${Math.round(n / 1_000_000)}M`;
+	if (n < 10_000_000_000) return `${trim1(n / 1_000_000_000)}B`;
+	return `${Math.round(n / 1_000_000_000)}B`;
+}
+
+/** Format with up to 1 decimal place, dropping trailing `.0`. */
+function trim1(n: number): string {
+	const s = n.toFixed(1);
+	return s.endsWith(".0") ? s.slice(0, -2) : s;
+}
+
+/**
+ * Format a byte count to a human-readable string.
+ * Examples: "512B", "1.5KB", "2.3MB", "1.2GB"
+ */
+export function formatBytes(bytes: number): string {
+	if (bytes < 1024) return `${bytes}B`;
+	if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)}KB`;
+	if (bytes < 1024 * 1024 * 1024) return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
+	return `${(bytes / (1024 * 1024 * 1024)).toFixed(1)}GB`;
+}
+
+/**
+ * Truncate a string to maxLen characters, appending an ellipsis if truncated.
+ * For display-width-aware truncation (terminals), use truncateToWidth from @oh-my-pi-zen/pi-tui.
+ */
+export function truncate(str: string, maxLen: number, ellipsis = "…"): string {
+	if (str.length <= maxLen) return str;
+	const sliceLen = Math.max(0, maxLen - ellipsis.length);
+	return `${str.slice(0, sliceLen)}${ellipsis}`;
+}
+
+/**
+ * Format count with pluralized label (e.g., "3 files", "1 error").
+ */
+export function formatCount(label: string, count: number): string {
+	const safeCount = Number.isFinite(count) ? count : 0;
+	return `${safeCount} ${pluralize(label, safeCount)}`;
+}
+
+/**
+ * Format age from seconds to human-readable string.
+ */
+export function formatAge(ageSeconds: number | null | undefined): string {
+	if (!ageSeconds) return "";
+	const mins = Math.floor(ageSeconds / 60);
+	const hours = Math.floor(mins / 60);
+	const days = Math.floor(hours / 24);
+	const weeks = Math.floor(days / 7);
+	const months = Math.floor(days / 30);
+
+	if (months > 0) return `${months}mo ago`;
+	if (weeks > 0) return `${weeks}w ago`;
+	if (days > 0) return `${days}d ago`;
+	if (hours > 0) return `${hours}h ago`;
+	if (mins > 0) return `${mins}m ago`;
+	return "just now";
+}
+
+/**
+ * Pluralize a label based on the count.
+ */
+export function pluralize(label: string, count: number): string {
+	if (count === 1) return label;
+	if (/(?:ch|sh|s|x|z)$/i.test(label)) return `${label}es`;
+	if (/[^aeiou]y$/i.test(label)) return `${label.slice(0, -1)}ies`;
+	return `${label}s`;
+}
+
+/**
+ * Format a ratio as a percentage.
+ */
+export function formatPercent(ratio: number): string {
+	return `${(ratio * 100).toFixed(1)}%`;
+}