@oh-my-pi/pi-coding-agent 15.9.67 → 15.10.0

package/dist/types/modes/setup-wizard/scenes/web-search.d.ts

@@ -2,7 +2,8 @@ import type { SetupSceneHost, SetupTab } from "./types";
 /**
  * "Web search" panel: picks the provider the web_search tool should prefer and
  * reports whether the highlighted provider is ready to use given current
- * credentials (env keys or OAuth sign-ins from the Sign in tab).
+ * credentials (env keys or OAuth sign-ins from the Sign in tab) or an
+ * unauthenticated fallback.
  */
 export declare class WebSearchTab implements SetupTab {
     #private;

package/dist/types/modes/types.d.ts

@@ -241,7 +241,7 @@ export interface InteractiveModeContext {
     handleSessionDeleteCommand(): Promise<void>;
     showOAuthSelector(mode: "login" | "logout", providerId?: string): Promise<void>;
     showHookConfirm(title: string, message: string): Promise<boolean>;
-    showDebugSelector(): void;
+    showDebugSelector(): Promise<void>;
     showSessionObserver(): void;
     resetObserverRegistry(): void;
     handleCtrlC(): void;

package/dist/types/sdk.d.ts

@@ -13,7 +13,7 @@ import { type FileSlashCommand } from "./extensibility/slash-commands";
 import type { HindsightSessionState } from "./hindsight/state";
 import { type LocalProtocolOptions } from "./internal-urls";
 import { MCPManager, type MCPToolsLoadResult } from "./mcp";
-import { type MnemopiSessionState } from "./mnemopi/state";
+import type { MnemopiSessionState } from "./mnemopi/state";
 import { AgentRegistry } from "./registry/agent-registry";
 import { AgentSession } from "./session/agent-session";
 import { AuthStorage } from "./session/auth-storage";

package/dist/types/task/executor.d.ts

@@ -48,6 +48,13 @@ export interface ExecutorOptions {
     outputSchema?: unknown;
     /** Parent task recursion depth (0 = top-level, 1 = first child, etc.) */
     taskDepth?: number;
+    /**
+     * Override the `task.maxRuntimeMs` wall-clock cap for this run. When provided
+     * it wins over the settings value; `0` disables the per-subagent wall-clock
+     * limit entirely. Used by the eval `agent()` bridge, whose parent cell
+     * watchdog is already suspended for the call's duration.
+     */
+    maxRuntimeMs?: number;
     enableLsp?: boolean;
     signal?: AbortSignal;
     onProgress?: (progress: AgentProgress) => void;

package/dist/types/telemetry-export.d.ts

@@ -10,7 +10,7 @@ export declare function isTelemetryExportEnabled(): boolean;
  * the OTEL kill-switches are engaged), so it is safe to call unconditionally at
  * startup.
  */
-export declare function initTelemetryExport(): void;
+export declare function initTelemetryExport(): Promise<void>;
 /**
  * Flush any buffered spans to the exporter. No-op when export is disabled.
  * Hosts embedding the agent can call this at natural boundaries (e.g. the end

package/dist/types/tools/eval-render.d.ts

@@ -13,14 +13,6 @@ import type { EvalStatusEvent, EvalToolDetails } from "../eval/types";
 import type { RenderResultOptions } from "../extensibility/custom-tools/types";
 import { type Theme } from "../modes/theme/theme";
 export declare const EVAL_DEFAULT_PREVIEW_LINES = 10;
-/**
- * Rows of source kept in the *pending* eval preview. The window follows the
- * streaming edge (newest lines pinned to the bottom) so you can watch the code
- * being written, while staying bounded — a volatile tool block taller than the
- * viewport would otherwise strand its scrolled-off head out of native scrollback
- * on ED3-risk terminals. Matches the streaming windows used by edit/write.
- */
-export declare const EVAL_STREAMING_PREVIEW_LINES = 12;
 interface EvalRenderCellArg {
     language?: string;
     code?: string;
@@ -54,6 +46,7 @@ export declare const evalToolRenderer: {
     }, options: RenderResultOptions & {
         renderContext?: EvalRenderContext;
     }, uiTheme: Theme, _args?: EvalRenderArgs): Component;
+    isStreamingPreviewAppendOnly(_args: EvalRenderArgs, _options: RenderResultOptions, result?: unknown): boolean;
     mergeCallAndResult: boolean;
     inline: boolean;
 };

package/dist/types/tools/fetch.d.ts

@@ -17,14 +17,22 @@ export interface ParsedReadUrlTarget {
     ranges?: readonly LineRange[];
 }
 export declare function parseReadUrlTarget(readPath: string): ParsedReadUrlTarget | null;
+/** Reader backends for {@link renderHtmlToText}, in default priority order. */
+export type FetchProvider = "native" | "trafilatura" | "lynx" | "parallel" | "jina";
 /**
- * Render HTML to markdown using Parallel, jina, trafilatura, lynx, then the
- * in-process native converter. The overall `timeout` budget bounds the call,
- * but remote reader requests are additionally capped at `REMOTE_READER_MAX_MS`
- * so that a hung remote endpoint cannot prevent local fallbacks from running.
- * Only a real `userSignal` cancellation aborts the chain — remote per-attempt
- * timeouts and the overall reader-mode timeout still allow later renderers
- * (especially the purely-local native converter) to be tried.
+ * Render HTML to markdown by trying reader backends in priority order: native
+ * (in-process), trafilatura, lynx, Parallel, then Jina. The `providers.fetch`
+ * setting picks the order — `auto` uses the default above; any specific backend
+ * is tried first, then the remaining backends as fallbacks. Every backend's
+ * output must clear the same quality gate (>100 non-whitespace chars and not
+ * {@link isLowQualityOutput}) before it is accepted, otherwise the next backend
+ * is tried.
+ *
+ * The overall `timeout` budget bounds the whole call; remote backends (Parallel,
+ * Jina) are additionally capped at `REMOTE_READER_MAX_MS` so a hung endpoint
+ * cannot starve later renderers — especially the purely-local native converter,
+ * which always works on already-loaded HTML. Only a real `userSignal`
+ * cancellation aborts the chain (#1449).
  */
 export declare function renderHtmlToText(url: string, html: string, timeout: number, settings: Settings, userSignal: AbortSignal | undefined, storage: AgentStorage | null): Promise<{
     content: string;

package/dist/types/tools/render-utils.d.ts

@@ -103,6 +103,14 @@ export declare function capPreviewLines(lines: string[], theme: Theme, options?:
 }): string[];
 export declare function formatMeta(meta: string[], theme: Theme): string;
 export declare function formatErrorMessage(message: string | undefined, theme: Theme): string;
+/**
+ * Error message rendered as a subordinate detail line beneath a status header
+ * that already carries the error icon (e.g. `✘ Write: <path>`). The header's
+ * icon already signals failure, so this omits the redundant error symbol and
+ * "Error:" prefix that `formatErrorMessage` adds for standalone single-line
+ * errors, indenting two columns to sit under the header title instead.
+ */
+export declare function formatErrorDetail(message: string | undefined, theme: Theme): string;
 export declare function formatEmptyMessage(message: string, theme: Theme): string;
 export type CodeFrameMarker = "" | " " | "*" | "+" | "-" | ">";
 export declare function formatCodeFrameLine(marker: CodeFrameMarker, lineNumber: string | number, content: string, lineNumberWidth: number): string;

package/dist/types/tools/renderers.d.ts

@@ -6,7 +6,7 @@
 import type { Component } from "@oh-my-pi/pi-tui";
 import type { RenderResultOptions } from "../extensibility/custom-tools/types";
 import type { Theme } from "../modes/theme/theme";
-type ToolRenderer = {
+export type ToolRenderer = {
     renderCall: (args: unknown, options: RenderResultOptions, theme: Theme) => Component;
     renderResult: (result: {
         content: Array<{
@@ -19,8 +19,22 @@ type ToolRenderer = {
         renderContext?: Record<string, unknown>;
     }, theme: Theme, args?: unknown) => Component;
     mergeCallAndResult?: boolean;
+    /**
+     * While a tool's preview is still streaming, report whether the
+     * currently-rendered preview is append-only: its rows only grow at the bottom
+     * and never re-layout above the bottom live region (a full, top-anchored
+     * content/code preview). The transcript reports this up to the TUI so a
+     * streaming preview taller than the viewport commits its scrolled-off head to
+     * native scrollback instead of dropping it (see
+     * `ToolExecutionComponent.isTranscriptBlockAppendOnly`). `result` is the
+     * latest (possibly partial) tool result, or `undefined` before one exists —
+     * `eval`/`bash` use its presence to defer committing until the streamed input
+     * (code) has finalized. Omit (or return `false`) for previews that slide a
+     * tail window or later collapse to a compact result — committing their head
+     * would strand stale rows.
+     */
+    isStreamingPreviewAppendOnly?: (args: unknown, options: RenderResultOptions, result?: unknown) => boolean;
     /** Render without background box, inline in the response flow */
     inline?: boolean;
 };
 export declare const toolRenderers: Record<string, ToolRenderer>;
-export {};

package/dist/types/tools/search.d.ts

@@ -5,7 +5,7 @@ import type { RenderResultOptions } from "../extensibility/custom-tools/types";
 import type { Theme } from "../modes/theme/theme";
 import { type TruncationResult } from "../session/streaming-output";
 import type { ToolSession } from ".";
-import { type OutputMeta } from "./output-meta";
+import type { OutputMeta } from "./output-meta";
 declare const searchSchema: z.ZodObject<{
     pattern: z.ZodString;
     paths: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;

package/dist/types/tools/write.d.ts

@@ -53,12 +53,14 @@ interface WriteRenderArgs {
 }
 export declare const writeToolRenderer: {
     renderCall(args: WriteRenderArgs, options: RenderResultOptions, uiTheme: Theme): Component;
+    isStreamingPreviewAppendOnly(args: WriteRenderArgs, options: RenderResultOptions, _result?: unknown): boolean;
     renderResult(result: {
         content: Array<{
             type: string;
             text?: string;
         }>;
         details?: WriteToolDetails;
+        isError?: boolean;
     }, options: RenderResultOptions, uiTheme: Theme, args?: WriteRenderArgs): Component;
     mergeCallAndResult: boolean;
 };

package/dist/types/web/scrapers/github.d.ts

@@ -1,4 +1,18 @@
 import type { SpecialHandler } from "./types";
+interface GitHubUrl {
+    type: "blob" | "tree" | "repo" | "issue" | "issues" | "pull" | "pulls" | "discussion" | "discussions" | "actions-run" | "actions-job" | "other";
+    owner: string;
+    repo: string;
+    ref?: string;
+    path?: string;
+    number?: number;
+    runId?: number;
+    jobId?: number;
+}
+/**
+ * Parse GitHub URL into components
+ */
+export declare function parseGitHubUrl(url: string): GitHubUrl | null;
 /**
  * Fetch from GitHub API
  */
@@ -6,7 +20,15 @@ export declare function fetchGitHubApi(endpoint: string, timeout: number, signal
     data: unknown;
     ok: boolean;
 }>;
+/**
+ * Strip the per-line ISO-8601 timestamp prefix GitHub prepends to every job log line.
+ * Cuts ~28 bytes/line of noise while preserving the message text. Also drops the leading
+ * UTF-8 BOM GitHub puts at the start of the log file (otherwise the first line's timestamp
+ * survives because `^` no longer sits before a digit).
+ */
+export declare function stripActionsLogTimestamps(logs: string): string;
 /**
  * Handle GitHub URLs specially
  */
 export declare const handleGitHub: SpecialHandler;
+export {};

package/dist/types/web/search/providers/perplexity.d.ts

@@ -1,10 +1,11 @@
 /**
  * Perplexity Web Search Provider
  *
- * Supports three auth modes:
+ * Supports four auth modes:
  * - Cookies (`PERPLEXITY_COOKIES`) via `www.perplexity.ai/rest/sse/perplexity_ask`
  * - OAuth/session bearer via `AuthStorage` and `www.perplexity.ai/rest/sse/perplexity_ask`
  * - API key (`PERPLEXITY_API_KEY`) via `api.perplexity.ai/chat/completions`
+ * - Anonymous via `www.perplexity.ai/rest/sse/perplexity_ask`
  */
 import { type AuthStorage } from "@oh-my-pi/pi-ai";
 import type { SearchResponse } from "../../../web/search/types";
@@ -34,5 +35,11 @@ export declare class PerplexityProvider extends SearchProvider {
     readonly id = "perplexity";
     readonly label = "Perplexity";
     isAvailable(authStorage: AuthStorage): boolean;
+    /**
+     * Perplexity accepts anonymous browser-style ask requests, but keep auto
+     * provider selection credential-gated so a configured provider keeps priority
+     * over the anonymous fallback.
+     */
+    isExplicitlyAvailable(_authStorage: AuthStorage): boolean;
     search(params: SearchParams): Promise<SearchResponse>;
 }

package/dist/types/web/search/types.d.ts

@@ -18,7 +18,7 @@ export declare const SEARCH_PROVIDER_OPTIONS: readonly [{
 }, {
     readonly value: "perplexity";
     readonly label: "Perplexity";
-    readonly description: "Requires PERPLEXITY_COOKIES or PERPLEXITY_API_KEY";
+    readonly description: "Uses auth when configured; explicit selection falls back to anonymous search";
 }, {
     readonly value: "brave";
     readonly label: "Brave";

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-coding-agent",
-	"version": "15.9.67",
+	"version": "15.10.0",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
@@ -47,14 +47,14 @@
 		"@agentclientprotocol/sdk": "0.22.1",
 		"@babel/parser": "^7.29.7",
 		"@mozilla/readability": "^0.6.0",
-		"@oh-my-pi/hashline": "15.9.67",
-		"@oh-my-pi/omp-stats": "15.9.67",
-		"@oh-my-pi/pi-agent-core": "15.9.67",
-		"@oh-my-pi/pi-ai": "15.9.67",
-		"@oh-my-pi/pi-mnemopi": "15.9.67",
-		"@oh-my-pi/pi-natives": "15.9.67",
-		"@oh-my-pi/pi-tui": "15.9.67",
-		"@oh-my-pi/pi-utils": "15.9.67",
+		"@oh-my-pi/hashline": "15.10.0",
+		"@oh-my-pi/omp-stats": "15.10.0",
+		"@oh-my-pi/pi-agent-core": "15.10.0",
+		"@oh-my-pi/pi-ai": "15.10.0",
+		"@oh-my-pi/pi-mnemopi": "15.10.0",
+		"@oh-my-pi/pi-natives": "15.10.0",
+		"@oh-my-pi/pi-tui": "15.10.0",
+		"@oh-my-pi/pi-utils": "15.10.0",
 		"@opentelemetry/api": "^1.9.1",
 		"@opentelemetry/context-async-hooks": "^2.7.1",
 		"@opentelemetry/exporter-trace-otlp-proto": "^0.218.0",

package/scripts/dev-launch

@@ -0,0 +1,42 @@
+#!/bin/sh
+# Dev launcher for the omp CLI, installed by `bun run install:dev`.
+#
+# Problem it solves: Bun reads `bunfig.toml` from the *current working
+# directory* at startup and evaluates its `preload` entries before running the
+# script. A bun-shebang bin (what `bun link` creates for `src/cli.ts`)
+# therefore inherits whatever `preload` the directory you happen to be in
+# declares. Running `omp`/`pi` inside an unrelated Bun project can execute — and
+# crash on — that project's preload, e.g.
+#   error: Cannot find module '@v12sh/utils/frontmatter' from '.../loader.ts'
+#
+# Bun only reads the *exact* cwd (it does not walk parents) and ignores
+# `--config`/`BUN_BE_BUN` for this, so the fix is to launch Bun from an empty,
+# bunfig-free directory and restore the real cwd inside the process via the
+# preload shim alongside this file.
+set -e
+
+# Resolve this script's real location even when invoked through a symlink
+# (`$HOME/.bun/bin/omp` -> this file).
+self=$0
+while [ -L "$self" ]; do
+	link=$(readlink "$self")
+	case $link in
+	/*) self=$link ;;
+	*) self=$(dirname "$self")/$link ;;
+	esac
+done
+scripts_dir=$(CDPATH= cd -- "$(dirname -- "$self")" && pwd -P)
+cli=$scripts_dir/../src/cli.ts
+preload=$scripts_dir/dev-launch-preload.ts
+timing_preload=$scripts_dir/../../utils/src/module-timer.ts
+
+launch_dir=${OMP_DEV_LAUNCH_DIR:-${HOME}/.omp/.dev-cwd}
+mkdir -p "$launch_dir"
+
+OMP_LAUNCH_CWD=$PWD
+export OMP_LAUNCH_CWD
+cd "$launch_dir"
+if [ -n "${PI_TIMING:-}" ]; then
+	exec bun --preload "$preload" --preload "$timing_preload" "$cli" "$@"
+fi
+exec bun --preload "$preload" "$cli" "$@"

package/scripts/dev-launch-preload.ts

@@ -0,0 +1,19 @@
+/**
+ * Bun `--preload` shim for the omp dev launcher (`scripts/dev-launch`).
+ *
+ * The launcher starts Bun from an empty, bunfig-free directory so a foreign
+ * project's `bunfig.toml` `preload` cannot run inside the omp CLI: Bun reads
+ * `bunfig.toml` from the *current working directory* on startup and evaluates
+ * its `preload` entries before the entrypoint, so a bun-shebang bin inherits
+ * whatever `preload` the directory you launched from declares (and crashes if
+ * that preload can't resolve). This shim is loaded before the entrypoint's
+ * imports run, so it restores the user's real working directory in time for
+ * import-time snapshots (e.g. `getProjectDir()` in `@oh-my-pi/pi-utils/dirs`).
+ */
+const launchCwd = process.env.OMP_LAUNCH_CWD;
+if (launchCwd) {
+	delete process.env.OMP_LAUNCH_CWD;
+	try {
+		process.chdir(launchCwd);
+	} catch {}
+}

package/src/cli/args.ts

@@ -1,7 +1,7 @@
 /**
  * CLI argument parsing and help display
  */
-import { type Effort, THINKING_EFFORTS } from "@oh-my-pi/pi-ai";
+import { type Effort, THINKING_EFFORTS } from "@oh-my-pi/pi-ai/effort";
 import { APP_NAME, CONFIG_DIR_NAME, logger } from "@oh-my-pi/pi-utils";
 import chalk from "chalk";
 import { parseEffort } from "../thinking";
@@ -284,7 +284,7 @@ export function getExtraHelpText(): string {
   ${chalk.dim("# Search & Tools")}
   EXA_API_KEY                - Exa web search
   BRAVE_API_KEY              - Brave web search
-  PERPLEXITY_API_KEY         - Perplexity web search (API)
+  PERPLEXITY_API_KEY         - Perplexity web search API key (optional; anonymous fallback)
   PERPLEXITY_COOKIES         - Perplexity web search (session cookie)
   TAVILY_API_KEY             - Tavily web search
   ANTHROPIC_SEARCH_API_KEY   - Anthropic web search (override; isolates search from main ANTHROPIC_API_KEY)

package/src/cli/gallery-cli.ts

@@ -0,0 +1,223 @@
+/**
+ * `omp gallery` — render every built-in tool's renderer across its lifecycle.
+ *
+ * For each tool with a registered renderer, the gallery drives a real
+ * {@link ToolExecutionComponent} through four states — streaming arguments,
+ * arguments complete (in progress), success, and failure — and prints the
+ * rendered output to stdout. It exists for visual QA of tool renderers without
+ * having to provoke each state through a live agent session.
+ */
+import type { AgentTool } from "@oh-my-pi/pi-agent-core";
+import type { TUI } from "@oh-my-pi/pi-tui";
+import { getProjectDir } from "@oh-my-pi/pi-utils";
+import { Settings } from "../config/settings";
+import { ToolExecutionComponent } from "../modes/components/tool-execution";
+import { initTheme, theme } from "../modes/theme/theme";
+import { toolRenderers } from "../tools/renderers";
+import { type GalleryFixture, type GalleryResult, galleryFixtures } from "./gallery-fixtures";
+import { captureGalleryScreenshots } from "./gallery-screenshot";
+
+/** Lifecycle states the gallery renders, in display order. */
+export const GALLERY_STATES = ["streaming", "progress", "success", "error"] as const;
+export type GalleryState = (typeof GALLERY_STATES)[number];
+
+const STATE_LABELS: Record<GalleryState, string> = {
+	streaming: "streaming args",
+	progress: "in progress",
+	success: "done",
+	error: "failed",
+};
+
+export interface GalleryCommandArgs {
+	/** Render width in columns (defaults to terminal width, clamped). */
+	width?: number;
+	/** Restrict to a single tool name. */
+	tool?: string;
+	/** Restrict to specific lifecycle states. */
+	states?: GalleryState[];
+	/** Render the expanded variant of each renderer. */
+	expanded?: boolean;
+	/** Strip ANSI styling from the output (useful when redirecting to a file). */
+	plain?: boolean;
+	/** Capture the rendered gallery as PNG screenshot(s) via VHS instead of printing ANSI. */
+	screenshot?: boolean;
+	/** Screenshot output path (single image) or base path (suffixed when split across images). */
+	out?: string;
+	/** Font family for screenshots (must be installed; Nerd Font recommended for icon glyphs). */
+	font?: string;
+	/** Font size in points for screenshots. */
+	fontSize?: number;
+}
+
+/** One tool's rendered lifecycle, as ANSI lines: a leading blank, the section rule, then each state. */
+export interface GallerySection {
+	heading: string;
+	lines: string[];
+}
+
+const GENERIC_ERROR: GalleryResult = {
+	content: [{ type: "text", text: "Error: operation failed" }],
+	isError: true,
+};
+
+/**
+ * Build the fake `AgentTool` the component needs for its label, edit mode, and —
+ * for `customRendered` fixtures — the renderer functions that route it through
+ * the same custom-tool branch production uses (see {@link GalleryFixture}).
+ */
+function fakeToolFor(name: string, fixture: GalleryFixture | undefined): AgentTool | undefined {
+	if (!fixture?.label && !fixture?.editMode && !fixture?.customRendered) return undefined;
+	const tool: Record<string, unknown> = { name, label: fixture.label ?? name, mode: fixture.editMode };
+	if (fixture.customRendered) {
+		const renderer = toolRenderers[name] as
+			| { renderCall?: unknown; renderResult?: unknown; mergeCallAndResult?: unknown; inline?: unknown }
+			| undefined;
+		if (renderer) {
+			tool.renderCall = renderer.renderCall;
+			tool.renderResult = renderer.renderResult;
+			tool.mergeCallAndResult = renderer.mergeCallAndResult;
+			tool.inline = renderer.inline;
+		}
+	}
+	return tool as unknown as AgentTool;
+}
+
+/** The curated fixture for a tool, or a generic one for registry tools lacking sample data. */
+export function resolveFixture(name: string): GalleryFixture {
+	return (
+		galleryFixtures[name] ??
+		({
+			args: { note: `sample ${name} call` },
+			result: { content: [{ type: "text", text: `${name} completed` }] },
+		} satisfies GalleryFixture)
+	);
+}
+
+/**
+ * Render a single tool/state pair to lines. Builds a fresh component, drives it
+ * to the requested state, settles any async edit preview, then snapshots the
+ * render and stops all animation timers.
+ */
+export async function renderGalleryState(
+	name: string,
+	fixture: GalleryFixture,
+	state: GalleryState,
+	width: number,
+	expanded = false,
+): Promise<string[]> {
+	const tool = fakeToolFor(name, fixture);
+	const streamingArgs = state === "streaming" ? (fixture.streamingArgs ?? fixture.args) : fixture.args;
+	// The component only calls `requestRender` during a static render;
+	// `imageBudget` is consulted solely when images render, which the gallery
+	// disables. A cast avoids constructing a real terminal.
+	const ui = { requestRender() {} } as unknown as TUI;
+	const component = new ToolExecutionComponent(name, streamingArgs, { showImages: false }, tool, ui, getProjectDir());
+	component.setExpanded(expanded);
+
+	if (state !== "streaming") {
+		component.setArgsComplete();
+	}
+	if (state === "success") {
+		component.updateResult(fixture.result, false);
+	} else if (state === "error") {
+		component.updateResult(fixture.errorResult ?? GENERIC_ERROR, false);
+	}
+
+	// Edit-like renderers compute their diff preview off the render path; wait
+	// for it to settle so the snapshot is deterministic instead of racing a tick.
+	await component.whenPreviewSettled();
+
+	const lines = component.render(width);
+	component.stopAnimation();
+	return lines;
+}
+
+function resolveWidth(requested: number | undefined): number {
+	const fallback = process.stdout.columns ?? 100;
+	const width = requested ?? fallback;
+	return Math.max(40, Math.min(200, width));
+}
+
+function sectionRule(label: string, width: number): string {
+	const prefix = `── ${label} `;
+	const fill = Math.max(0, width - prefix.length);
+	return theme.fg("accent", theme.bold(`${prefix}${"─".repeat(fill)}`));
+}
+
+/**
+ * Render each requested tool's lifecycle into ANSI section blocks. The block
+ * layout (leading blank, section rule, then a blank + dim label + body per
+ * state) is shared by the stdout and screenshot paths so both stay identical.
+ */
+async function renderGallerySections(
+	names: string[],
+	states: GalleryState[],
+	width: number,
+	expanded: boolean,
+): Promise<GallerySection[]> {
+	const sections: GallerySection[] = [];
+	for (const name of names) {
+		const fixture = resolveFixture(name);
+		const heading = fixture.label && fixture.label !== name ? `${name} — ${fixture.label}` : name;
+		const lines: string[] = ["", sectionRule(heading, width)];
+		for (const state of states) {
+			lines.push("", theme.fg("dim", `  · ${STATE_LABELS[state]}`));
+			try {
+				for (const line of await renderGalleryState(name, fixture, state, width, expanded)) lines.push(line);
+			} catch (err) {
+				lines.push(theme.fg("error", `  render failed: ${String(err)}`));
+			}
+		}
+		sections.push({ heading, lines });
+	}
+	return sections;
+}
+
+/**
+ * Render the gallery. Iterates the renderer registry (or a single tool),
+ * printing each requested lifecycle state under a labeled section — or, with
+ * `screenshot`, capturing the rendered output as PNG(s) via VHS.
+ */
+export async function runGalleryCommand(args: GalleryCommandArgs): Promise<void> {
+	const settingsInstance = await Settings.init();
+	// Screenshots must carry exact theme RGB regardless of how the invoking
+	// terminal advertises its color support, so force truecolor before the theme
+	// (and therefore every SGR escape it emits) is built.
+	if (args.screenshot) process.env.COLORTERM = "truecolor";
+	await initTheme(
+		false,
+		settingsInstance.get("symbolPreset"),
+		settingsInstance.get("colorBlindMode"),
+		settingsInstance.get("theme.dark"),
+		settingsInstance.get("theme.light"),
+	);
+
+	const width = resolveWidth(args.width);
+	const expanded = args.expanded ?? false;
+	const states = args.states && args.states.length > 0 ? args.states : [...GALLERY_STATES];
+
+	const allNames = Object.keys(toolRenderers).sort();
+	const names = args.tool ? allNames.filter(name => name === args.tool) : allNames;
+	if (args.tool && names.length === 0) {
+		process.stdout.write(`Unknown tool '${args.tool}'. Known tools: ${allNames.join(", ")}\n`);
+		return;
+	}
+
+	const sections = await renderGallerySections(names, states, width, expanded);
+
+	if (args.screenshot) {
+		const paths = await captureGalleryScreenshots(sections, {
+			width,
+			font: args.font,
+			fontSize: args.fontSize,
+			out: args.out,
+		});
+		process.stdout.write(`${paths.join("\n")}\n`);
+		return;
+	}
+
+	const lines = sections.flatMap(section => section.lines);
+	lines.push("");
+	const text = lines.map(line => (args.plain ? Bun.stripANSI(line) : line)).join("\n");
+	process.stdout.write(`${text}\n`);
+}