@promptbook/cli 0.113.0-10 → 0.113.0-11

package/umd/index.umd.js

@@ -63,7 +63,7 @@
      * @generated
      * @see https://github.com/webgptorg/promptbook
      */
-    const PROMPTBOOK_ENGINE_VERSION = '0.113.0-10';
+    const PROMPTBOOK_ENGINE_VERSION = '0.113.0-11';
     /**
      * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
      * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -28109,6 +28109,47 @@
         });
     }
 
+    /**
+     * Minimum timer duration used to avoid a zero-millisecond polling loop.
+     */
+    const MINIMUM_WORLD_TIME_WAIT_POLL_INTERVAL_MS = 1;
+    /**
+     * Waits until one wall-clock deadline has passed.
+     *
+     * The remaining time is recalculated from `Date.now()` after every poll and after every tick callback.
+     * This makes waits elapse while the process is paused at a checkpoint or the computer is asleep.
+     *
+     * @private internal utility of `ptbk coder` wait handling
+     */
+    async function waitUntilWorldTimeDeadline(options) {
+        const { deadlineTimeMs, pollIntervalMs, onTick } = options;
+        const normalizedPollIntervalMs = Math.max(MINIMUM_WORLD_TIME_WAIT_POLL_INTERVAL_MS, pollIntervalMs);
+        while (true) {
+            const remainingDurationMs = getRemainingDurationMs(deadlineTimeMs);
+            if (remainingDurationMs <= 0) {
+                return;
+            }
+            await (onTick === null || onTick === void 0 ? void 0 : onTick(remainingDurationMs));
+            const remainingDurationAfterTickMs = getRemainingDurationMs(deadlineTimeMs);
+            if (remainingDurationAfterTickMs <= 0) {
+                return;
+            }
+            await waitForMilliseconds(Math.min(normalizedPollIntervalMs, remainingDurationAfterTickMs));
+        }
+    }
+    /**
+     * Returns the remaining wall-clock duration until a timestamp.
+     */
+    function getRemainingDurationMs(deadlineTimeMs) {
+        return Math.max(0, deadlineTimeMs - Date.now());
+    }
+    /**
+     * Waits for one short polling interval.
+     */
+    async function waitForMilliseconds(durationMs) {
+        await new Promise((resolve) => setTimeout(resolve, durationMs));
+    }
+
     /**
      * Base delimiter used for passing large prompts through stdin.
      */
@@ -28518,36 +28559,32 @@
      * Waits until the Claude Code session can be resumed, keeping terminal status clear.
      */
     async function waitForClaudeCodeSessionLimitReset(sessionLimit, resurrectionCount, options) {
-        var _a, _b, _c;
+        var _a, _b;
         const delayMs = getClaudeCodeSessionLimitDelayMs(sessionLimit);
+        const resetDeadlineTimeMs = Date.now() + delayMs;
         const sessionLabel = formatClaudeCodeSessionIdForDisplay(sessionLimit.sessionId);
         const resetSummary = formatClaudeCodeSessionLimitForDisplay(sessionLimit);
         if ((_a = options.shouldPrintLiveOutput) !== null && _a !== void 0 ? _a : true) {
             console.warn(colors__default["default"].yellow(`[claude-code] Session limit detected for ${sessionLimit.sessionId}. Resurrection #${resurrectionCount} will resume with --resume after ${formatDurationMs(delayMs)}. ${resetSummary}`));
         }
-        let remainingDelayMs = delayMs;
-        while (remainingDelayMs > 0) {
-            await ((_b = options.waitForPauseCheckpoint) === null || _b === void 0 ? void 0 : _b.call(options, {
-                checkpointLabel: 'the Claude Code session limit reset',
-                phase: 'waiting',
-                statusMessage: `Claude Code session ${sessionLabel} hit its limit; resurrection #${resurrectionCount} resumes in ${formatDurationMs(remainingDelayMs)}`,
-            }));
-            const currentDelayMs = Math.min(CLAUDE_CODE_SESSION_RESURRECTION_POLL_MS, remainingDelayMs);
-            await waitFor$1(currentDelayMs);
-            remainingDelayMs -= currentDelayMs;
-        }
-        await ((_c = options.waitForPauseCheckpoint) === null || _c === void 0 ? void 0 : _c.call(options, {
+        await waitUntilWorldTimeDeadline({
+            deadlineTimeMs: resetDeadlineTimeMs,
+            pollIntervalMs: CLAUDE_CODE_SESSION_RESURRECTION_POLL_MS,
+            onTick: async (remainingDelayMs) => {
+                var _a;
+                await ((_a = options.waitForPauseCheckpoint) === null || _a === void 0 ? void 0 : _a.call(options, {
+                    checkpointLabel: 'the Claude Code session limit reset',
+                    phase: 'waiting',
+                    statusMessage: `Claude Code session ${sessionLabel} hit its limit; resurrection #${resurrectionCount} resumes in ${formatDurationMs(Math.min(remainingDelayMs, delayMs))}`,
+                }));
+            },
+        });
+        await ((_b = options.waitForPauseCheckpoint) === null || _b === void 0 ? void 0 : _b.call(options, {
             checkpointLabel: 'resurrecting the Claude Code session with --resume',
             phase: 'running',
             statusMessage: `Resurrecting Claude Code session ${sessionLabel} with --resume`,
         }));
     }
-    /**
-     * Waits for a fixed amount of milliseconds.
-     */
-    async function waitFor$1(delayMs) {
-        await new Promise((resolve) => setTimeout(resolve, delayMs));
-    }
     /**
      * Formats a Claude Code session id for compact terminal status lines.
      */
@@ -29431,12 +29468,6 @@
      * Randomized delay proportion added/subtracted for retry jitter.
      */
     const RATE_LIMIT_BACKOFF_JITTER_RATIO = 0.15;
-    /**
-     * Waits for one given amount of milliseconds.
-     */
-    async function waitFor(delayMs) {
-        await new Promise((resolve) => setTimeout(resolve, delayMs));
-    }
     /**
      * Formats a delay value into a concise `xh ym zs` style label.
      */
@@ -29526,13 +29557,18 @@
                         throw error;
                     }
                     const delayMs = this.rateLimitBackoff.nextDelayMs();
-                    const retryAt = new Date(Date.now() + delayMs).toISOString();
+                    const retryDeadlineTimeMs = Date.now() + delayMs;
+                    const retryAt = new Date(retryDeadlineTimeMs).toISOString();
                     const retryIndex = this.rateLimitBackoff.retryCount;
                     const summary = extractFailureSummary(details);
                     if ((_b = options.shouldPrintLiveOutput) !== null && _b !== void 0 ? _b : true) {
                         console.warn(colors__default["default"].yellow(`[codex] Rate limit/quota detected (${summary}). Retry #${retryIndex} in ${formatDelay(delayMs)} at ${retryAt}.`));
                     }
-                    await waitForRetryDelay(delayMs, options);
+                    await waitForRetryDelay({
+                        delayMs,
+                        retryDeadlineTimeMs,
+                        promptRunOptions: options,
+                    });
                 }
             }
         }
@@ -29540,20 +29576,21 @@
     /**
      * Waits for the next Codex retry while polling for requested pause checkpoints.
      */
-    async function waitForRetryDelay(delayMs, options) {
-        var _a;
-        let remainingDelayMs = delayMs;
-        while (remainingDelayMs > 0) {
-            const remainingDelayLabel = formatDelay(remainingDelayMs);
-            await ((_a = options.waitForPauseCheckpoint) === null || _a === void 0 ? void 0 : _a.call(options, {
-                checkpointLabel: 'the next OpenAI Codex retry after rate limit',
-                phase: 'running',
-                statusMessage: `Waiting ${remainingDelayLabel} before retrying OpenAI Codex`,
-            }));
-            const currentDelayMs = Math.min(RATE_LIMIT_BACKOFF_POLL_MS, remainingDelayMs);
-            await waitFor(currentDelayMs);
-            remainingDelayMs -= currentDelayMs;
-        }
+    async function waitForRetryDelay(options) {
+        const { delayMs, retryDeadlineTimeMs, promptRunOptions } = options;
+        await waitUntilWorldTimeDeadline({
+            deadlineTimeMs: retryDeadlineTimeMs,
+            pollIntervalMs: RATE_LIMIT_BACKOFF_POLL_MS,
+            onTick: async (remainingDelayMs) => {
+                var _a;
+                const remainingDelayLabel = formatDelay(Math.min(remainingDelayMs, delayMs));
+                await ((_a = promptRunOptions.waitForPauseCheckpoint) === null || _a === void 0 ? void 0 : _a.call(promptRunOptions, {
+                    checkpointLabel: 'the next OpenAI Codex retry after rate limit',
+                    phase: 'running',
+                    statusMessage: `Waiting ${remainingDelayLabel} before retrying OpenAI Codex`,
+                }));
+            },
+        });
     }
 
     /**
@@ -30054,12 +30091,597 @@
             .map((line) => centerAnsiText(line, options.totalWidth));
     }
 
+    /**
+     * Stable zeroed interaction state used by non-interactive render paths.
+     *
+     * @private utility of the avatar rendering system
+     */
+    const IDLE_AVATAR_INTERACTION_STATE = {
+        gazeX: 0,
+        gazeY: 0,
+        bodyOffsetX: 0,
+        bodyOffsetY: 0,
+        intensity: 0,
+        isPointerActive: false,
+        pointerType: 'idle',
+    };
+    /**
+     * Returns the neutral interaction state used by static/server-side renders.
+     *
+     * @returns Zeroed interaction state.
+     *
+     * @private utility of the avatar rendering system
+     */
+    function createIdleAvatarInteractionState() {
+        return IDLE_AVATAR_INTERACTION_STATE;
+    }
+
+    /**
+     * Resolves the stable avatar render inputs reused across multiple frames.
+     *
+     * @param options Avatar identity and visual selection.
+     * @returns Stable render data ready to be used by `renderAvatarVisual`.
+     *
+     * @private shared helper for canvas avatar rendering
+     */
+    function resolveAvatarRenderDefinition(options) {
+        const avatarDefinition = normalizeAvatarDefinition(options.avatarDefinition);
+        const surface = options.surface || 'framed';
+        return {
+            avatarDefinition,
+            avatarVisual: getAvatarVisualById(options.visualId),
+            surface,
+            palette: createAvatarPalette(avatarDefinition, surface),
+            createRandom: createAvatarRandomFactory(avatarDefinition),
+        };
+    }
+    /**
+     * Renders one deterministic avatar frame into the provided canvas.
+     *
+     * @param options Rendering options.
+     * @param resolvedAvatarRenderDefinition Optional stable render data reused between frames.
+     *
+     * @private shared helper for canvas avatar rendering
+     */
+    function renderAvatarVisual(options, resolvedAvatarRenderDefinition) {
+        const resolvedRenderDefinition = resolvedAvatarRenderDefinition ||
+            resolveAvatarRenderDefinition({
+                avatarDefinition: options.avatarDefinition,
+                visualId: options.visualId,
+                surface: options.surface,
+            });
+        const context = options.canvas.getContext('2d');
+        if (!context) {
+            throw new Error('2D canvas rendering context is unavailable.');
+        }
+        prepareAvatarCanvas(options.canvas, context, options.size, options.devicePixelRatio || 1);
+        resolvedRenderDefinition.avatarVisual.render({
+            canvas: options.canvas,
+            context,
+            size: options.size,
+            devicePixelRatio: options.devicePixelRatio || 1,
+            timeMs: options.timeMs,
+            avatarDefinition: resolvedRenderDefinition.avatarDefinition,
+            palette: resolvedRenderDefinition.palette,
+            createRandom: resolvedRenderDefinition.createRandom,
+            surface: resolvedRenderDefinition.surface,
+            interaction: options.interaction || createIdleAvatarInteractionState(),
+        });
+    }
+
+    /**
+     * Default alpha channel value below which a half-cell is rendered as terminal background.
+     *
+     * @private within the repository
+     */
+    const DEFAULT_ALPHA_THRESHOLD = 32;
+    /**
+     * Number of channels per pixel in an RGBA buffer.
+     *
+     * @private within the repository
+     */
+    const RGBA_CHANNEL_COUNT = 4;
+    /**
+     * Upper half block character - foreground paints the top pixel, background paints the bottom pixel.
+     *
+     * @private within the repository
+     */
+    const UPPER_HALF_BLOCK = '▀'; // <- ▀
+    /**
+     * Lower half block character - foreground paints the bottom pixel while the top pixel stays transparent.
+     *
+     * @private within the repository
+     */
+    const LOWER_HALF_BLOCK = '▄'; // <- ▄
+    /**
+     * ANSI escape sequence that resets all colors and attributes.
+     *
+     * @private within the repository
+     */
+    const ANSI_RESET = '\u001b[0m';
+    /**
+     * Maximum spread between RGB channels for a color to be treated as (nearly) achromatic gray.
+     *
+     * @private within the repository
+     */
+    const ANSI_256_ACHROMATIC_CHANNEL_SPREAD = 12;
+    /**
+     * Gray level above which an achromatic color maps to the pure white color-cube entry.
+     *
+     * @private within the repository
+     */
+    const ANSI_256_NEAR_WHITE_GRAY_LEVEL = 246;
+    /**
+     * Index of pure white inside the 6×6×6 ANSI color cube.
+     *
+     * @private within the repository
+     */
+    const ANSI_256_WHITE_INDEX = 231;
+    /**
+     * Brightness of the lightest entry of the ANSI 256 grayscale ramp.
+     *
+     * @private within the repository
+     */
+    const ANSI_256_GRAYSCALE_RAMP_MAX_LEVEL = 238;
+    /**
+     * Number of grayscale ramp steps above its first entry (ANSI indexes 232-255).
+     *
+     * @private within the repository
+     */
+    const ANSI_256_GRAYSCALE_RAMP_INDEX_SPAN = 23;
+    /**
+     * Converts raw RGBA image pixels into colored ASCII art for ANSI terminals.
+     *
+     * This is the universal image-to-terminal technique used across the repository:
+     * every output character cell covers a rectangular region of source pixels which is
+     * split into a top and bottom half; each half is area-averaged and rendered with
+     * half-block characters (`▀` / `▄`) so one character shows two "pixels" vertically.
+     * Transparent halves keep the terminal background so non-rectangular images
+     * (for example rounded avatar cards) compose naturally into any terminal UI.
+     *
+     * @param options Source pixels, output grid size, and ANSI color depth.
+     * @returns One ANSI-colored string per output row, each ending with a color reset.
+     *
+     * @private within the repository
+     */
+    function convertImageDataToAsciiArt(options) {
+        const { imageData, columns, rows, colorDepth = 'TRUE_COLOR', alphaThreshold = DEFAULT_ALPHA_THRESHOLD } = options;
+        if (!Number.isInteger(columns) || columns <= 0 || !Number.isInteger(rows) || rows <= 0) {
+            throw new UnexpectedError(_spaceTrim.spaceTrim(`
+                ASCII-art grid size is invalid.
+
+                Both \`columns\` and \`rows\` must be positive integers but \`${columns}\` × \`${rows}\` was requested.
+            `));
+        }
+        if (imageData.width <= 0 ||
+            imageData.height <= 0 ||
+            imageData.data.length < imageData.width * imageData.height * RGBA_CHANNEL_COUNT) {
+            throw new UnexpectedError(_spaceTrim.spaceTrim(`
+                ASCII-art source image data is invalid.
+
+                Expected a RGBA buffer of at least \`${imageData.width} × ${imageData.height} × ${RGBA_CHANNEL_COUNT}\` bytes
+                but got \`${imageData.data.length}\` bytes.
+            `));
+        }
+        const halfCellRowCount = rows * 2;
+        const asciiArtLines = [];
+        for (let rowIndex = 0; rowIndex < rows; rowIndex++) {
+            let line = '';
+            let currentForegroundCode = undefined;
+            let currentBackgroundCode = undefined;
+            for (let columnIndex = 0; columnIndex < columns; columnIndex++) {
+                const topHalfColor = computeHalfCellColor(imageData, columnIndex, rowIndex * 2, columns, halfCellRowCount, alphaThreshold);
+                const bottomHalfColor = computeHalfCellColor(imageData, columnIndex, rowIndex * 2 + 1, columns, halfCellRowCount, alphaThreshold);
+                let character;
+                let nextForegroundCode;
+                let nextBackgroundCode;
+                if (topHalfColor.isOpaque && bottomHalfColor.isOpaque) {
+                    character = UPPER_HALF_BLOCK;
+                    nextForegroundCode = createForegroundColorCode(topHalfColor, colorDepth);
+                    nextBackgroundCode = createBackgroundColorCode(bottomHalfColor, colorDepth);
+                }
+                else if (topHalfColor.isOpaque) {
+                    character = UPPER_HALF_BLOCK;
+                    nextForegroundCode = createForegroundColorCode(topHalfColor, colorDepth);
+                    nextBackgroundCode = undefined;
+                }
+                else if (bottomHalfColor.isOpaque) {
+                    character = LOWER_HALF_BLOCK;
+                    nextForegroundCode = createForegroundColorCode(bottomHalfColor, colorDepth);
+                    nextBackgroundCode = undefined;
+                }
+                else {
+                    character = ' ';
+                    nextForegroundCode = undefined;
+                    nextBackgroundCode = undefined;
+                }
+                if (nextForegroundCode !== currentForegroundCode || nextBackgroundCode !== currentBackgroundCode) {
+                    // Note: A reset is required whenever a previously set color must be cleared,
+                    //       otherwise stale background color would bleed into transparent cells.
+                    const isResetNeeded = (currentForegroundCode !== undefined && nextForegroundCode === undefined) ||
+                        (currentBackgroundCode !== undefined && nextBackgroundCode === undefined);
+                    if (isResetNeeded) {
+                        line += ANSI_RESET;
+                        currentForegroundCode = undefined;
+                        currentBackgroundCode = undefined;
+                    }
+                    if (nextForegroundCode !== undefined && nextForegroundCode !== currentForegroundCode) {
+                        line += nextForegroundCode;
+                    }
+                    if (nextBackgroundCode !== undefined && nextBackgroundCode !== currentBackgroundCode) {
+                        line += nextBackgroundCode;
+                    }
+                    currentForegroundCode = nextForegroundCode;
+                    currentBackgroundCode = nextBackgroundCode;
+                }
+                line += character;
+            }
+            if (currentForegroundCode !== undefined || currentBackgroundCode !== undefined) {
+                line += ANSI_RESET;
+            }
+            asciiArtLines.push(line);
+        }
+        return asciiArtLines;
+    }
+    /**
+     * Computes the area-averaged color of one half-cell of the output grid.
+     *
+     * Color channels are alpha-weighted so semi-transparent edge pixels do not darken towards black.
+     *
+     * @private helper of `convertImageDataToAsciiArt`
+     */
+    function computeHalfCellColor(imageData, columnIndex, halfCellRowIndex, columns, halfCellRowCount, alphaThreshold) {
+        const startX = Math.floor((columnIndex * imageData.width) / columns);
+        const endX = Math.max(startX + 1, Math.floor(((columnIndex + 1) * imageData.width) / columns));
+        const startY = Math.floor((halfCellRowIndex * imageData.height) / halfCellRowCount);
+        const endY = Math.max(startY + 1, Math.floor(((halfCellRowIndex + 1) * imageData.height) / halfCellRowCount));
+        let redSum = 0;
+        let greenSum = 0;
+        let blueSum = 0;
+        let alphaSum = 0;
+        let sampledPixelCount = 0;
+        for (let y = startY; y < endY && y < imageData.height; y++) {
+            for (let x = startX; x < endX && x < imageData.width; x++) {
+                const pixelOffset = (y * imageData.width + x) * RGBA_CHANNEL_COUNT;
+                const alpha = imageData.data[pixelOffset + 3];
+                redSum += imageData.data[pixelOffset] * alpha;
+                greenSum += imageData.data[pixelOffset + 1] * alpha;
+                blueSum += imageData.data[pixelOffset + 2] * alpha;
+                alphaSum += alpha;
+                sampledPixelCount++;
+            }
+        }
+        const averageAlpha = sampledPixelCount === 0 ? 0 : alphaSum / sampledPixelCount;
+        if (averageAlpha < alphaThreshold || alphaSum === 0) {
+            return { red: 0, green: 0, blue: 0, isOpaque: false };
+        }
+        return {
+            red: Math.round(redSum / alphaSum),
+            green: Math.round(greenSum / alphaSum),
+            blue: Math.round(blueSum / alphaSum),
+            isOpaque: true,
+        };
+    }
+    /**
+     * Creates the ANSI escape code that sets the foreground color of following characters.
+     *
+     * @private helper of `convertImageDataToAsciiArt`
+     */
+    function createForegroundColorCode(color, colorDepth) {
+        if (colorDepth === 'TRUE_COLOR') {
+            return `\u001b[38;2;${color.red};${color.green};${color.blue}m`;
+        }
+        return `\u001b[38;5;${mapColorToAnsi256(color)}m`;
+    }
+    /**
+     * Creates the ANSI escape code that sets the background color of following characters.
+     *
+     * @private helper of `convertImageDataToAsciiArt`
+     */
+    function createBackgroundColorCode(color, colorDepth) {
+        if (colorDepth === 'TRUE_COLOR') {
+            return `\u001b[48;2;${color.red};${color.green};${color.blue}m`;
+        }
+        return `\u001b[48;5;${mapColorToAnsi256(color)}m`;
+    }
+    /**
+     * Maps a 24-bit color onto the closest entry of the 256-color ANSI palette.
+     *
+     * Uses the 6×6×6 color cube (entries 16-231) and the grayscale ramp (entries 232-255).
+     *
+     * @private helper of `convertImageDataToAsciiArt`
+     */
+    function mapColorToAnsi256(color) {
+        const { red, green, blue } = color;
+        // Note: Prefer the finer grayscale ramp when the color is (nearly) achromatic
+        const maxChannel = Math.max(red, green, blue);
+        const minChannel = Math.min(red, green, blue);
+        if (maxChannel - minChannel < ANSI_256_ACHROMATIC_CHANNEL_SPREAD) {
+            const gray = Math.round((red + green + blue) / 3);
+            if (gray < 4) {
+                return 16; // <- Note: Pure black lives in the color cube
+            }
+            if (gray > ANSI_256_NEAR_WHITE_GRAY_LEVEL) {
+                return ANSI_256_WHITE_INDEX; // <- Note: Pure white lives in the color cube
+            }
+            return 232 + Math.round(((gray - 8) / ANSI_256_GRAYSCALE_RAMP_MAX_LEVEL) * ANSI_256_GRAYSCALE_RAMP_INDEX_SPAN);
+        }
+        const redIndex = Math.round((red / 255) * 5);
+        const greenIndex = Math.round((green / 255) * 5);
+        const blueIndex = Math.round((blue / 255) * 5);
+        return 16 + 36 * redIndex + 6 * greenIndex + blueIndex;
+    }
+
+    /**
+     * Default output width of the ASCII avatar in terminal character cells.
+     *
+     * @private within the repository
+     */
+    const DEFAULT_AVATAR_ASCII_ART_COLUMNS = 32;
+    /**
+     * Stable animation timestamp used when rasterizing animated avatar visuals into a static ASCII frame.
+     *
+     * @private within the repository
+     */
+    const STATIC_AVATAR_ASCII_ART_FRAME_TIME_MS = 840;
+    /**
+     * Default source canvas width used before the pixels are converted to ASCII art.
+     *
+     * @private within the repository
+     */
+    const DEFAULT_AVATAR_ASCII_ART_CANVAS_WIDTH = DEFAULT_AVATAR_SIZE;
+    /**
+     * Default source canvas height used before the pixels are converted to ASCII art.
+     *
+     * @private within the repository
+     */
+    const DEFAULT_AVATAR_ASCII_ART_CANVAS_HEIGHT = DEFAULT_AVATAR_SIZE;
+    /**
+     * Renders one built-in avatar visual into ANSI-colored ASCII art for terminal display.
+     *
+     * This is the universal bridge between the canvas avatar visuals shown on the website and
+     * text-based terminal UIs: the visual is rasterized through the exact same `renderAvatarVisual`
+     * pipeline the web uses, then the resulting pixels are converted into colored half-block
+     * characters by `convertImageDataToAsciiArt`.
+     *
+     * @param options Avatar identity, visual selection, output grid size, and the platform canvas factory.
+     * @returns One ANSI-colored string per output row.
+     *
+     * @private within the repository
+     */
+    function renderAvatarVisualAsciiArt(options) {
+        var _a, _b, _c, _d;
+        const columns = (_a = options.columns) !== null && _a !== void 0 ? _a : DEFAULT_AVATAR_ASCII_ART_COLUMNS;
+        const rows = (_b = options.rows) !== null && _b !== void 0 ? _b : Math.round(columns / 2);
+        const canvasWidth = (_c = options.canvasWidth) !== null && _c !== void 0 ? _c : DEFAULT_AVATAR_ASCII_ART_CANVAS_WIDTH;
+        const canvasHeight = (_d = options.canvasHeight) !== null && _d !== void 0 ? _d : DEFAULT_AVATAR_ASCII_ART_CANVAS_HEIGHT;
+        assertPositiveCanvasDimension(canvasWidth, 'canvasWidth');
+        assertPositiveCanvasDimension(canvasHeight, 'canvasHeight');
+        const imageData = renderAvatarVisualAsciiArtImageData(options, canvasWidth, canvasHeight);
+        return convertImageDataToAsciiArt({
+            imageData,
+            columns,
+            rows,
+            colorDepth: options.colorDepth,
+        });
+    }
+    /**
+     * Renders one avatar visual frame into source pixels ready for ASCII conversion.
+     *
+     * @private helper of `renderAvatarVisualAsciiArt`
+     */
+    function renderAvatarVisualAsciiArtImageData(options, canvasWidth, canvasHeight) {
+        var _a;
+        const avatarSize = Math.min(canvasWidth, canvasHeight);
+        const avatarCanvas = createCanvasWithBrowserShape(options.createCanvas, avatarSize, avatarSize);
+        renderAvatarVisual({
+            canvas: avatarCanvas,
+            avatarDefinition: options.avatarDefinition,
+            visualId: options.visualId,
+            surface: options.surface,
+            size: avatarSize,
+            timeMs: (_a = options.timeMs) !== null && _a !== void 0 ? _a : STATIC_AVATAR_ASCII_ART_FRAME_TIME_MS,
+            devicePixelRatio: 1,
+        }, options.resolvedAvatarRenderDefinition);
+        if (canvasWidth === avatarSize && canvasHeight === avatarSize) {
+            return getCanvas2dContext(avatarCanvas).getImageData(0, 0, avatarSize, avatarSize);
+        }
+        const canvas = createCanvasWithBrowserShape(options.createCanvas, canvasWidth, canvasHeight);
+        const context = getCanvas2dContext(canvas);
+        const avatarLeft = (canvasWidth - avatarSize) / 2;
+        const avatarTop = (canvasHeight - avatarSize) / 2;
+        context.clearRect(0, 0, canvasWidth, canvasHeight);
+        context.drawImage(avatarCanvas, avatarLeft, avatarTop, avatarSize, avatarSize);
+        return context.getImageData(0, 0, canvasWidth, canvasHeight);
+    }
+    /**
+     * Creates a canvas and adds the small browser-shape compatibility shim expected by avatar rendering.
+     *
+     * @private helper of `renderAvatarVisualAsciiArt`
+     */
+    function createCanvasWithBrowserShape(createCanvas, width, height) {
+        const canvas = createCanvas(width, height);
+        if (!canvas.style) {
+            // Note: `renderAvatarVisual` expects a browser canvas shape; Node.js canvases only need this tiny compatibility shim.
+            canvas.style = {};
+        }
+        return canvas;
+    }
+    /**
+     * Reads a 2D rendering context or throws a branded environment error.
+     *
+     * @private helper of `renderAvatarVisualAsciiArt`
+     */
+    function getCanvas2dContext(canvas) {
+        const context = canvas.getContext('2d');
+        if (!context) {
+            throw new EnvironmentMismatchError(_spaceTrim.spaceTrim(`
+                2D canvas rendering context is unavailable while converting the avatar visual to ASCII art.
+
+                Provide a \`createCanvas\` factory whose canvases support \`getContext('2d')\`,
+                for example \`createCanvas\` of \`@napi-rs/canvas\` in Node.js.
+            `));
+        }
+        return context;
+    }
+    /**
+     * Validates one source canvas dimension.
+     *
+     * @private helper of `renderAvatarVisualAsciiArt`
+     */
+    function assertPositiveCanvasDimension(value, dimensionName) {
+        if (Number.isInteger(value) && value > 0) {
+            return;
+        }
+        throw new UnexpectedError(_spaceTrim.spaceTrim(`
+            Avatar ASCII-art source canvas dimension is invalid.
+
+            \`${dimensionName}\` must be a positive integer but \`${value}\` was requested.
+        `));
+    }
+
+    /**
+     * Default built-in avatar visual used when an agent does not define `META IMAGE`, `META AVATAR`, or `META VISUAL`.
+     *
+     * @private shared avatar contract
+     */
+    const DEFAULT_AGENT_AVATAR_VISUAL_ID = 'octopus3d4';
+    /**
+     * Resolves the avatar visual preferred by an agent, then falls back to a federated server default
+     * and finally to the caller/server default.
+     *
+     * @param agent Agent metadata and optional remote-profile visual id.
+     * @param defaultAvatarVisualId Optional metadata-resolved server default.
+     * @returns Supported avatar visual id.
+     *
+     * @private shared avatar contract
+     */
+    function resolveAgentAvatarVisualId(agent, defaultAvatarVisualId = DEFAULT_AGENT_AVATAR_VISUAL_ID) {
+        var _a;
+        return (resolveAvatarVisualId((_a = agent.meta) === null || _a === void 0 ? void 0 : _a.avatar) ||
+            agent.avatarVisualId ||
+            agent.defaultAgentAvatarVisualId ||
+            defaultAvatarVisualId);
+    }
+
+    // Note: [💞] Ignore a discrepancy between file name and entity name
+    /**
+     * Output width of the terminal agent avatar visual in character cells.
+     *
+     * @private shared helper for terminal avatar rendering
+     */
+    const TERMINAL_AGENT_AVATAR_VISUAL_COLUMNS = 48;
+    /**
+     * Output height of the terminal agent avatar visual in character cells.
+     *
+     * @private shared helper for terminal avatar rendering
+     */
+    const TERMINAL_AGENT_AVATAR_VISUAL_ROWS = 12;
+    /**
+     * Refresh cadence used while a terminal agent avatar visual is animated.
+     *
+     * @private shared helper for terminal avatar rendering
+     */
+    const TERMINAL_AGENT_AVATAR_VISUAL_REFRESH_INTERVAL_MS = 300;
+    /**
+     * Aspect ratio of the source canvas used for the terminal avatar variant.
+     *
+     * @private shared helper for terminal avatar rendering
+     */
+    const TERMINAL_AGENT_AVATAR_VISUAL_CANVAS_ASPECT_RATIO = 2;
+    /**
+     * Source canvas width used before the avatar is converted to ASCII art.
+     *
+     * @private shared helper for terminal avatar rendering
+     */
+    const TERMINAL_AGENT_AVATAR_VISUAL_CANVAS_WIDTH = DEFAULT_AVATAR_SIZE * TERMINAL_AGENT_AVATAR_VISUAL_CANVAS_ASPECT_RATIO;
+    /**
+     * Source canvas height used before the avatar is converted to ASCII art.
+     *
+     * @private shared helper for terminal avatar rendering
+     */
+    const TERMINAL_AGENT_AVATAR_VISUAL_CANVAS_HEIGHT = DEFAULT_AVATAR_SIZE;
+    /**
+     * Creates an ANSI ASCII-art avatar renderer for terminal UIs.
+     *
+     * The agent's avatar visual is resolved the same way as on the website: `META AVATAR`
+     * / `META VISUAL` wins, then the provided fallback visual, then the shared default visual.
+     * The terminal variant uses a transparent horizontal canvas instead of the website's framed square surface.
+     *
+     * @param options Agent source, canvas factory, and optional terminal color settings.
+     * @returns Runtime terminal avatar visual renderer.
+     *
+     * @private shared helper for terminal avatar rendering
+     */
+    function createTerminalAgentAvatarVisual(options) {
+        const renderInputs = createTerminalAgentAvatarVisualRenderInputs(options.agentSource, options.defaultAvatarVisualId || DEFAULT_AGENT_AVATAR_VISUAL_ID);
+        return {
+            isAnimated: renderInputs.resolvedAvatarRenderDefinition.avatarVisual.isAnimated,
+            renderFrame({ animationTimeMs }) {
+                return renderTerminalAgentAvatarVisualFrame({
+                    ...renderInputs,
+                    animationTimeMs,
+                    colorDepth: options.colorDepth,
+                    createCanvas: options.createCanvas,
+                });
+            },
+        };
+    }
+    /**
+     * Creates stable avatar render inputs from one agent source.
+     *
+     * @private shared helper for terminal avatar rendering
+     */
+    function createTerminalAgentAvatarVisualRenderInputs(agentSource, defaultAvatarVisualId) {
+        const agentBasicInformation = parseAgentSource(agentSource);
+        const avatarDefinition = createAvatarDefinitionFromAgentBasicInformation(agentBasicInformation);
+        const avatarVisualId = resolveTerminalAgentAvatarVisualIdFromAgentBasicInformation(agentBasicInformation, defaultAvatarVisualId);
+        const resolvedAvatarRenderDefinition = resolveAvatarRenderDefinition({
+            avatarDefinition,
+            visualId: avatarVisualId,
+            surface: 'transparent',
+        });
+        return {
+            avatarDefinition,
+            avatarVisualId,
+            resolvedAvatarRenderDefinition,
+        };
+    }
+    /**
+     * Resolves the terminal avatar visual id from already parsed agent information.
+     *
+     * @private shared helper for terminal avatar rendering
+     */
+    function resolveTerminalAgentAvatarVisualIdFromAgentBasicInformation(agentBasicInformation, defaultAvatarVisualId) {
+        return resolveAgentAvatarVisualId(agentBasicInformation, resolveAvatarVisualId(agentBasicInformation.meta.visual) || defaultAvatarVisualId);
+    }
+    /**
+     * Renders one terminal avatar frame through the shared avatar-to-ASCII pipeline.
+     *
+     * @private shared helper for terminal avatar rendering
+     */
+    function renderTerminalAgentAvatarVisualFrame(options) {
+        return renderAvatarVisualAsciiArt({
+            avatarDefinition: options.avatarDefinition,
+            visualId: options.avatarVisualId,
+            surface: 'transparent',
+            columns: TERMINAL_AGENT_AVATAR_VISUAL_COLUMNS,
+            rows: TERMINAL_AGENT_AVATAR_VISUAL_ROWS,
+            canvasWidth: TERMINAL_AGENT_AVATAR_VISUAL_CANVAS_WIDTH,
+            canvasHeight: TERMINAL_AGENT_AVATAR_VISUAL_CANVAS_HEIGHT,
+            colorDepth: options.colorDepth,
+            timeMs: options.animationTimeMs,
+            createCanvas: options.createCanvas,
+            resolvedAvatarRenderDefinition: options.resolvedAvatarRenderDefinition,
+        });
+    }
+
     /**
      * Refresh cadence used only while the rich coder UI needs animated updates.
      *
      * @private internal constant of coder run UI
      */
-    const ACTIVE_CODER_RUN_UI_REFRESH_INTERVAL_MS = 300;
+    const ACTIVE_CODER_RUN_UI_REFRESH_INTERVAL_MS = TERMINAL_AGENT_AVATAR_VISUAL_REFRESH_INTERVAL_MS;
     /**
      * Phases that still benefit from automatic refreshes because the frame can change
      * over time even without new runner output.
@@ -72145,23 +72767,25 @@
      * @public exported from `@promptbook/cli`
      */
     async function sleepWithCountdown(options) {
+        var _a;
         const { durationMs, waitKind, isRichUiEnabled, uiHandle } = options;
         if (durationMs <= 0) {
             return;
         }
-        let remaining = durationMs;
-        while (remaining > 0) {
-            const statusMessage = describeCoderRunWait(waitKind, remaining, durationMs);
-            if (!isRichUiEnabled) {
-                console.info(colors__default["default"].gray(`${statusMessage}...`));
-            }
-            else {
+        const deadlineTimeMs = (_a = options.deadlineTimeMs) !== null && _a !== void 0 ? _a : Date.now() + durationMs;
+        await waitUntilWorldTimeDeadline({
+            deadlineTimeMs,
+            pollIntervalMs: WAIT_COUNTDOWN_UPDATE_INTERVAL_MS,
+            onTick: (remainingDurationMs) => {
+                const visibleRemainingDurationMs = Math.min(remainingDurationMs, durationMs);
+                const statusMessage = describeCoderRunWait(waitKind, visibleRemainingDurationMs, durationMs);
+                if (!isRichUiEnabled) {
+                    console.info(colors__default["default"].gray(`${statusMessage}...`));
+                    return;
+                }
                 uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.setStatusMessage(`${statusMessage}...`);
-            }
-            const sleepMs = Math.min(WAIT_COUNTDOWN_UPDATE_INTERVAL_MS, remaining);
-            await new Promise((resolve) => setTimeout(resolve, sleepMs));
-            remaining -= sleepMs;
-        }
+            },
+        });
     }
 
     /**
@@ -72307,479 +72931,6 @@
         await waitForEnter(colors__default["default"].bgWhite(`Press Enter to start the ${label}...`));
     }
 
-    /**
-     * Stable zeroed interaction state used by non-interactive render paths.
-     *
-     * @private utility of the avatar rendering system
-     */
-    const IDLE_AVATAR_INTERACTION_STATE = {
-        gazeX: 0,
-        gazeY: 0,
-        bodyOffsetX: 0,
-        bodyOffsetY: 0,
-        intensity: 0,
-        isPointerActive: false,
-        pointerType: 'idle',
-    };
-    /**
-     * Returns the neutral interaction state used by static/server-side renders.
-     *
-     * @returns Zeroed interaction state.
-     *
-     * @private utility of the avatar rendering system
-     */
-    function createIdleAvatarInteractionState() {
-        return IDLE_AVATAR_INTERACTION_STATE;
-    }
-
-    /**
-     * Resolves the stable avatar render inputs reused across multiple frames.
-     *
-     * @param options Avatar identity and visual selection.
-     * @returns Stable render data ready to be used by `renderAvatarVisual`.
-     *
-     * @private shared helper for canvas avatar rendering
-     */
-    function resolveAvatarRenderDefinition(options) {
-        const avatarDefinition = normalizeAvatarDefinition(options.avatarDefinition);
-        const surface = options.surface || 'framed';
-        return {
-            avatarDefinition,
-            avatarVisual: getAvatarVisualById(options.visualId),
-            surface,
-            palette: createAvatarPalette(avatarDefinition, surface),
-            createRandom: createAvatarRandomFactory(avatarDefinition),
-        };
-    }
-    /**
-     * Renders one deterministic avatar frame into the provided canvas.
-     *
-     * @param options Rendering options.
-     * @param resolvedAvatarRenderDefinition Optional stable render data reused between frames.
-     *
-     * @private shared helper for canvas avatar rendering
-     */
-    function renderAvatarVisual(options, resolvedAvatarRenderDefinition) {
-        const resolvedRenderDefinition = resolvedAvatarRenderDefinition ||
-            resolveAvatarRenderDefinition({
-                avatarDefinition: options.avatarDefinition,
-                visualId: options.visualId,
-                surface: options.surface,
-            });
-        const context = options.canvas.getContext('2d');
-        if (!context) {
-            throw new Error('2D canvas rendering context is unavailable.');
-        }
-        prepareAvatarCanvas(options.canvas, context, options.size, options.devicePixelRatio || 1);
-        resolvedRenderDefinition.avatarVisual.render({
-            canvas: options.canvas,
-            context,
-            size: options.size,
-            devicePixelRatio: options.devicePixelRatio || 1,
-            timeMs: options.timeMs,
-            avatarDefinition: resolvedRenderDefinition.avatarDefinition,
-            palette: resolvedRenderDefinition.palette,
-            createRandom: resolvedRenderDefinition.createRandom,
-            surface: resolvedRenderDefinition.surface,
-            interaction: options.interaction || createIdleAvatarInteractionState(),
-        });
-    }
-
-    /**
-     * Default alpha channel value below which a half-cell is rendered as terminal background.
-     *
-     * @private within the repository
-     */
-    const DEFAULT_ALPHA_THRESHOLD = 32;
-    /**
-     * Number of channels per pixel in an RGBA buffer.
-     *
-     * @private within the repository
-     */
-    const RGBA_CHANNEL_COUNT = 4;
-    /**
-     * Upper half block character - foreground paints the top pixel, background paints the bottom pixel.
-     *
-     * @private within the repository
-     */
-    const UPPER_HALF_BLOCK = '▀'; // <- ▀
-    /**
-     * Lower half block character - foreground paints the bottom pixel while the top pixel stays transparent.
-     *
-     * @private within the repository
-     */
-    const LOWER_HALF_BLOCK = '▄'; // <- ▄
-    /**
-     * ANSI escape sequence that resets all colors and attributes.
-     *
-     * @private within the repository
-     */
-    const ANSI_RESET = '\u001b[0m';
-    /**
-     * Maximum spread between RGB channels for a color to be treated as (nearly) achromatic gray.
-     *
-     * @private within the repository
-     */
-    const ANSI_256_ACHROMATIC_CHANNEL_SPREAD = 12;
-    /**
-     * Gray level above which an achromatic color maps to the pure white color-cube entry.
-     *
-     * @private within the repository
-     */
-    const ANSI_256_NEAR_WHITE_GRAY_LEVEL = 246;
-    /**
-     * Index of pure white inside the 6×6×6 ANSI color cube.
-     *
-     * @private within the repository
-     */
-    const ANSI_256_WHITE_INDEX = 231;
-    /**
-     * Brightness of the lightest entry of the ANSI 256 grayscale ramp.
-     *
-     * @private within the repository
-     */
-    const ANSI_256_GRAYSCALE_RAMP_MAX_LEVEL = 238;
-    /**
-     * Number of grayscale ramp steps above its first entry (ANSI indexes 232-255).
-     *
-     * @private within the repository
-     */
-    const ANSI_256_GRAYSCALE_RAMP_INDEX_SPAN = 23;
-    /**
-     * Converts raw RGBA image pixels into colored ASCII art for ANSI terminals.
-     *
-     * This is the universal image-to-terminal technique used across the repository:
-     * every output character cell covers a rectangular region of source pixels which is
-     * split into a top and bottom half; each half is area-averaged and rendered with
-     * half-block characters (`▀` / `▄`) so one character shows two "pixels" vertically.
-     * Transparent halves keep the terminal background so non-rectangular images
-     * (for example rounded avatar cards) compose naturally into any terminal UI.
-     *
-     * @param options Source pixels, output grid size, and ANSI color depth.
-     * @returns One ANSI-colored string per output row, each ending with a color reset.
-     *
-     * @private within the repository
-     */
-    function convertImageDataToAsciiArt(options) {
-        const { imageData, columns, rows, colorDepth = 'TRUE_COLOR', alphaThreshold = DEFAULT_ALPHA_THRESHOLD } = options;
-        if (!Number.isInteger(columns) || columns <= 0 || !Number.isInteger(rows) || rows <= 0) {
-            throw new UnexpectedError(_spaceTrim.spaceTrim(`
-                ASCII-art grid size is invalid.
-
-                Both \`columns\` and \`rows\` must be positive integers but \`${columns}\` × \`${rows}\` was requested.
-            `));
-        }
-        if (imageData.width <= 0 ||
-            imageData.height <= 0 ||
-            imageData.data.length < imageData.width * imageData.height * RGBA_CHANNEL_COUNT) {
-            throw new UnexpectedError(_spaceTrim.spaceTrim(`
-                ASCII-art source image data is invalid.
-
-                Expected a RGBA buffer of at least \`${imageData.width} × ${imageData.height} × ${RGBA_CHANNEL_COUNT}\` bytes
-                but got \`${imageData.data.length}\` bytes.
-            `));
-        }
-        const halfCellRowCount = rows * 2;
-        const asciiArtLines = [];
-        for (let rowIndex = 0; rowIndex < rows; rowIndex++) {
-            let line = '';
-            let currentForegroundCode = undefined;
-            let currentBackgroundCode = undefined;
-            for (let columnIndex = 0; columnIndex < columns; columnIndex++) {
-                const topHalfColor = computeHalfCellColor(imageData, columnIndex, rowIndex * 2, columns, halfCellRowCount, alphaThreshold);
-                const bottomHalfColor = computeHalfCellColor(imageData, columnIndex, rowIndex * 2 + 1, columns, halfCellRowCount, alphaThreshold);
-                let character;
-                let nextForegroundCode;
-                let nextBackgroundCode;
-                if (topHalfColor.isOpaque && bottomHalfColor.isOpaque) {
-                    character = UPPER_HALF_BLOCK;
-                    nextForegroundCode = createForegroundColorCode(topHalfColor, colorDepth);
-                    nextBackgroundCode = createBackgroundColorCode(bottomHalfColor, colorDepth);
-                }
-                else if (topHalfColor.isOpaque) {
-                    character = UPPER_HALF_BLOCK;
-                    nextForegroundCode = createForegroundColorCode(topHalfColor, colorDepth);
-                    nextBackgroundCode = undefined;
-                }
-                else if (bottomHalfColor.isOpaque) {
-                    character = LOWER_HALF_BLOCK;
-                    nextForegroundCode = createForegroundColorCode(bottomHalfColor, colorDepth);
-                    nextBackgroundCode = undefined;
-                }
-                else {
-                    character = ' ';
-                    nextForegroundCode = undefined;
-                    nextBackgroundCode = undefined;
-                }
-                if (nextForegroundCode !== currentForegroundCode || nextBackgroundCode !== currentBackgroundCode) {
-                    // Note: A reset is required whenever a previously set color must be cleared,
-                    //       otherwise stale background color would bleed into transparent cells.
-                    const isResetNeeded = (currentForegroundCode !== undefined && nextForegroundCode === undefined) ||
-                        (currentBackgroundCode !== undefined && nextBackgroundCode === undefined);
-                    if (isResetNeeded) {
-                        line += ANSI_RESET;
-                        currentForegroundCode = undefined;
-                        currentBackgroundCode = undefined;
-                    }
-                    if (nextForegroundCode !== undefined && nextForegroundCode !== currentForegroundCode) {
-                        line += nextForegroundCode;
-                    }
-                    if (nextBackgroundCode !== undefined && nextBackgroundCode !== currentBackgroundCode) {
-                        line += nextBackgroundCode;
-                    }
-                    currentForegroundCode = nextForegroundCode;
-                    currentBackgroundCode = nextBackgroundCode;
-                }
-                line += character;
-            }
-            if (currentForegroundCode !== undefined || currentBackgroundCode !== undefined) {
-                line += ANSI_RESET;
-            }
-            asciiArtLines.push(line);
-        }
-        return asciiArtLines;
-    }
-    /**
-     * Computes the area-averaged color of one half-cell of the output grid.
-     *
-     * Color channels are alpha-weighted so semi-transparent edge pixels do not darken towards black.
-     *
-     * @private helper of `convertImageDataToAsciiArt`
-     */
-    function computeHalfCellColor(imageData, columnIndex, halfCellRowIndex, columns, halfCellRowCount, alphaThreshold) {
-        const startX = Math.floor((columnIndex * imageData.width) / columns);
-        const endX = Math.max(startX + 1, Math.floor(((columnIndex + 1) * imageData.width) / columns));
-        const startY = Math.floor((halfCellRowIndex * imageData.height) / halfCellRowCount);
-        const endY = Math.max(startY + 1, Math.floor(((halfCellRowIndex + 1) * imageData.height) / halfCellRowCount));
-        let redSum = 0;
-        let greenSum = 0;
-        let blueSum = 0;
-        let alphaSum = 0;
-        let sampledPixelCount = 0;
-        for (let y = startY; y < endY && y < imageData.height; y++) {
-            for (let x = startX; x < endX && x < imageData.width; x++) {
-                const pixelOffset = (y * imageData.width + x) * RGBA_CHANNEL_COUNT;
-                const alpha = imageData.data[pixelOffset + 3];
-                redSum += imageData.data[pixelOffset] * alpha;
-                greenSum += imageData.data[pixelOffset + 1] * alpha;
-                blueSum += imageData.data[pixelOffset + 2] * alpha;
-                alphaSum += alpha;
-                sampledPixelCount++;
-            }
-        }
-        const averageAlpha = sampledPixelCount === 0 ? 0 : alphaSum / sampledPixelCount;
-        if (averageAlpha < alphaThreshold || alphaSum === 0) {
-            return { red: 0, green: 0, blue: 0, isOpaque: false };
-        }
-        return {
-            red: Math.round(redSum / alphaSum),
-            green: Math.round(greenSum / alphaSum),
-            blue: Math.round(blueSum / alphaSum),
-            isOpaque: true,
-        };
-    }
-    /**
-     * Creates the ANSI escape code that sets the foreground color of following characters.
-     *
-     * @private helper of `convertImageDataToAsciiArt`
-     */
-    function createForegroundColorCode(color, colorDepth) {
-        if (colorDepth === 'TRUE_COLOR') {
-            return `\u001b[38;2;${color.red};${color.green};${color.blue}m`;
-        }
-        return `\u001b[38;5;${mapColorToAnsi256(color)}m`;
-    }
-    /**
-     * Creates the ANSI escape code that sets the background color of following characters.
-     *
-     * @private helper of `convertImageDataToAsciiArt`
-     */
-    function createBackgroundColorCode(color, colorDepth) {
-        if (colorDepth === 'TRUE_COLOR') {
-            return `\u001b[48;2;${color.red};${color.green};${color.blue}m`;
-        }
-        return `\u001b[48;5;${mapColorToAnsi256(color)}m`;
-    }
-    /**
-     * Maps a 24-bit color onto the closest entry of the 256-color ANSI palette.
-     *
-     * Uses the 6×6×6 color cube (entries 16-231) and the grayscale ramp (entries 232-255).
-     *
-     * @private helper of `convertImageDataToAsciiArt`
-     */
-    function mapColorToAnsi256(color) {
-        const { red, green, blue } = color;
-        // Note: Prefer the finer grayscale ramp when the color is (nearly) achromatic
-        const maxChannel = Math.max(red, green, blue);
-        const minChannel = Math.min(red, green, blue);
-        if (maxChannel - minChannel < ANSI_256_ACHROMATIC_CHANNEL_SPREAD) {
-            const gray = Math.round((red + green + blue) / 3);
-            if (gray < 4) {
-                return 16; // <- Note: Pure black lives in the color cube
-            }
-            if (gray > ANSI_256_NEAR_WHITE_GRAY_LEVEL) {
-                return ANSI_256_WHITE_INDEX; // <- Note: Pure white lives in the color cube
-            }
-            return 232 + Math.round(((gray - 8) / ANSI_256_GRAYSCALE_RAMP_MAX_LEVEL) * ANSI_256_GRAYSCALE_RAMP_INDEX_SPAN);
-        }
-        const redIndex = Math.round((red / 255) * 5);
-        const greenIndex = Math.round((green / 255) * 5);
-        const blueIndex = Math.round((blue / 255) * 5);
-        return 16 + 36 * redIndex + 6 * greenIndex + blueIndex;
-    }
-
-    /**
-     * Default output width of the ASCII avatar in terminal character cells.
-     *
-     * @private within the repository
-     */
-    const DEFAULT_AVATAR_ASCII_ART_COLUMNS = 32;
-    /**
-     * Stable animation timestamp used when rasterizing animated avatar visuals into a static ASCII frame.
-     *
-     * @private within the repository
-     */
-    const STATIC_AVATAR_ASCII_ART_FRAME_TIME_MS = 840;
-    /**
-     * Default source canvas width used before the pixels are converted to ASCII art.
-     *
-     * @private within the repository
-     */
-    const DEFAULT_AVATAR_ASCII_ART_CANVAS_WIDTH = DEFAULT_AVATAR_SIZE;
-    /**
-     * Default source canvas height used before the pixels are converted to ASCII art.
-     *
-     * @private within the repository
-     */
-    const DEFAULT_AVATAR_ASCII_ART_CANVAS_HEIGHT = DEFAULT_AVATAR_SIZE;
-    /**
-     * Renders one built-in avatar visual into ANSI-colored ASCII art for terminal display.
-     *
-     * This is the universal bridge between the canvas avatar visuals shown on the website and
-     * text-based terminal UIs: the visual is rasterized through the exact same `renderAvatarVisual`
-     * pipeline the web uses, then the resulting pixels are converted into colored half-block
-     * characters by `convertImageDataToAsciiArt`.
-     *
-     * @param options Avatar identity, visual selection, output grid size, and the platform canvas factory.
-     * @returns One ANSI-colored string per output row.
-     *
-     * @private within the repository
-     */
-    function renderAvatarVisualAsciiArt(options) {
-        var _a, _b, _c, _d;
-        const columns = (_a = options.columns) !== null && _a !== void 0 ? _a : DEFAULT_AVATAR_ASCII_ART_COLUMNS;
-        const rows = (_b = options.rows) !== null && _b !== void 0 ? _b : Math.round(columns / 2);
-        const canvasWidth = (_c = options.canvasWidth) !== null && _c !== void 0 ? _c : DEFAULT_AVATAR_ASCII_ART_CANVAS_WIDTH;
-        const canvasHeight = (_d = options.canvasHeight) !== null && _d !== void 0 ? _d : DEFAULT_AVATAR_ASCII_ART_CANVAS_HEIGHT;
-        assertPositiveCanvasDimension(canvasWidth, 'canvasWidth');
-        assertPositiveCanvasDimension(canvasHeight, 'canvasHeight');
-        const imageData = renderAvatarVisualAsciiArtImageData(options, canvasWidth, canvasHeight);
-        return convertImageDataToAsciiArt({
-            imageData,
-            columns,
-            rows,
-            colorDepth: options.colorDepth,
-        });
-    }
-    /**
-     * Renders one avatar visual frame into source pixels ready for ASCII conversion.
-     *
-     * @private helper of `renderAvatarVisualAsciiArt`
-     */
-    function renderAvatarVisualAsciiArtImageData(options, canvasWidth, canvasHeight) {
-        var _a;
-        const avatarSize = Math.min(canvasWidth, canvasHeight);
-        const avatarCanvas = createCanvasWithBrowserShape(options.createCanvas, avatarSize, avatarSize);
-        renderAvatarVisual({
-            canvas: avatarCanvas,
-            avatarDefinition: options.avatarDefinition,
-            visualId: options.visualId,
-            surface: options.surface,
-            size: avatarSize,
-            timeMs: (_a = options.timeMs) !== null && _a !== void 0 ? _a : STATIC_AVATAR_ASCII_ART_FRAME_TIME_MS,
-            devicePixelRatio: 1,
-        }, options.resolvedAvatarRenderDefinition);
-        if (canvasWidth === avatarSize && canvasHeight === avatarSize) {
-            return getCanvas2dContext(avatarCanvas).getImageData(0, 0, avatarSize, avatarSize);
-        }
-        const canvas = createCanvasWithBrowserShape(options.createCanvas, canvasWidth, canvasHeight);
-        const context = getCanvas2dContext(canvas);
-        const avatarLeft = (canvasWidth - avatarSize) / 2;
-        const avatarTop = (canvasHeight - avatarSize) / 2;
-        context.clearRect(0, 0, canvasWidth, canvasHeight);
-        context.drawImage(avatarCanvas, avatarLeft, avatarTop, avatarSize, avatarSize);
-        return context.getImageData(0, 0, canvasWidth, canvasHeight);
-    }
-    /**
-     * Creates a canvas and adds the small browser-shape compatibility shim expected by avatar rendering.
-     *
-     * @private helper of `renderAvatarVisualAsciiArt`
-     */
-    function createCanvasWithBrowserShape(createCanvas, width, height) {
-        const canvas = createCanvas(width, height);
-        if (!canvas.style) {
-            // Note: `renderAvatarVisual` expects a browser canvas shape; Node.js canvases only need this tiny compatibility shim.
-            canvas.style = {};
-        }
-        return canvas;
-    }
-    /**
-     * Reads a 2D rendering context or throws a branded environment error.
-     *
-     * @private helper of `renderAvatarVisualAsciiArt`
-     */
-    function getCanvas2dContext(canvas) {
-        const context = canvas.getContext('2d');
-        if (!context) {
-            throw new EnvironmentMismatchError(_spaceTrim.spaceTrim(`
-                2D canvas rendering context is unavailable while converting the avatar visual to ASCII art.
-
-                Provide a \`createCanvas\` factory whose canvases support \`getContext('2d')\`,
-                for example \`createCanvas\` of \`@napi-rs/canvas\` in Node.js.
-            `));
-        }
-        return context;
-    }
-    /**
-     * Validates one source canvas dimension.
-     *
-     * @private helper of `renderAvatarVisualAsciiArt`
-     */
-    function assertPositiveCanvasDimension(value, dimensionName) {
-        if (Number.isInteger(value) && value > 0) {
-            return;
-        }
-        throw new UnexpectedError(_spaceTrim.spaceTrim(`
-            Avatar ASCII-art source canvas dimension is invalid.
-
-            \`${dimensionName}\` must be a positive integer but \`${value}\` was requested.
-        `));
-    }
-
-    /**
-     * Default built-in avatar visual used when an agent does not define `META IMAGE`, `META AVATAR`, or `META VISUAL`.
-     *
-     * @private shared avatar contract
-     */
-    const DEFAULT_AGENT_AVATAR_VISUAL_ID = 'octopus3d4';
-    /**
-     * Resolves the avatar visual preferred by an agent, then falls back to a federated server default
-     * and finally to the caller/server default.
-     *
-     * @param agent Agent metadata and optional remote-profile visual id.
-     * @param defaultAvatarVisualId Optional metadata-resolved server default.
-     * @returns Supported avatar visual id.
-     *
-     * @private shared avatar contract
-     */
-    function resolveAgentAvatarVisualId(agent, defaultAvatarVisualId = DEFAULT_AGENT_AVATAR_VISUAL_ID) {
-        var _a;
-        return (resolveAvatarVisualId((_a = agent.meta) === null || _a === void 0 ? void 0 : _a.avatar) ||
-            agent.avatarVisualId ||
-            agent.defaultAgentAvatarVisualId ||
-            defaultAvatarVisualId);
-    }
-
     /**
      * Detects the ANSI color depth supported by the current terminal.
      *
@@ -72818,36 +72969,6 @@
         return 'ANSI_256';
     }
 
-    /**
-     * Output width of the coder-run agent visual in terminal character cells.
-     *
-     * @private internal constant of coder run UI
-     */
-    const CODER_RUN_AGENT_VISUAL_COLUMNS = 48;
-    /**
-     * Output height of the coder-run agent visual in terminal character cells.
-     *
-     * @private internal constant of coder run UI
-     */
-    const CODER_RUN_AGENT_VISUAL_ROWS = 12;
-    /**
-     * Aspect ratio of the source canvas used for the terminal variant.
-     *
-     * @private internal constant of coder run UI
-     */
-    const CODER_RUN_AGENT_VISUAL_CANVAS_ASPECT_RATIO = 2;
-    /**
-     * Source canvas width used before the avatar is converted to ASCII art.
-     *
-     * @private internal constant of coder run UI
-     */
-    const CODER_RUN_AGENT_VISUAL_CANVAS_WIDTH = DEFAULT_AVATAR_SIZE * CODER_RUN_AGENT_VISUAL_CANVAS_ASPECT_RATIO;
-    /**
-     * Source canvas height used before the avatar is converted to ASCII art.
-     *
-     * @private internal constant of coder run UI
-     */
-    const CODER_RUN_AGENT_VISUAL_CANVAS_HEIGHT = DEFAULT_AVATAR_SIZE;
     /**
      * Builds the ANSI ASCII-art visual of the `--agent` book shown above the coder-run dashboard.
      *
@@ -72866,33 +72987,18 @@
         try {
             // Note: `@napi-rs/canvas` is an optional native module, so it is imported dynamically and lazily
             const { createCanvas } = await import('@napi-rs/canvas');
-            const agentBasicInformation = parseAgentSource(agentSource);
-            const avatarDefinition = createAvatarDefinitionFromAgentBasicInformation(agentBasicInformation);
-            const avatarVisualId = resolveAgentAvatarVisualId(agentBasicInformation, resolveAvatarVisualId(agentBasicInformation.meta.visual) || DEFAULT_AGENT_AVATAR_VISUAL_ID);
-            const resolvedAvatarRenderDefinition = resolveAvatarRenderDefinition({
-                avatarDefinition,
-                visualId: avatarVisualId,
-                surface: 'transparent',
-            });
             const colorDepth = $detectTerminalAnsiColorDepth();
             const createCanvasForAsciiArt = (width, height) => createCanvas(width, height);
+            const agentVisual = createTerminalAgentAvatarVisual({
+                agentSource,
+                colorDepth,
+                createCanvas: createCanvasForAsciiArt,
+            });
             return {
-                isAnimated: resolvedAvatarRenderDefinition.avatarVisual.isAnimated,
+                isAnimated: agentVisual.isAnimated,
                 renderFrame({ animationTimeMs }) {
                     try {
-                        return renderAvatarVisualAsciiArt({
-                            avatarDefinition,
-                            visualId: avatarVisualId,
-                            surface: 'transparent',
-                            columns: CODER_RUN_AGENT_VISUAL_COLUMNS,
-                            rows: CODER_RUN_AGENT_VISUAL_ROWS,
-                            canvasWidth: CODER_RUN_AGENT_VISUAL_CANVAS_WIDTH,
-                            canvasHeight: CODER_RUN_AGENT_VISUAL_CANVAS_HEIGHT,
-                            colorDepth,
-                            timeMs: animationTimeMs,
-                            createCanvas: createCanvasForAsciiArt,
-                            resolvedAvatarRenderDefinition,
-                        });
+                        return agentVisual.renderFrame({ animationTimeMs });
                     }
                     catch (error) {
                         keepUnused(error);
@@ -74629,6 +74735,7 @@
         if (!isRichUiEnabled) {
             console.warn(colors__default["default"].yellow(`Prompt round failed (retry ${attemptedRetries}/${MAX_RETRY_ATTEMPTS_AFTER_ERROR}): ${errorMessage}`));
         }
+        const retryDeadlineTimeMs = Date.now() + runOptions.waitAfterError;
         await waitForRequestedPause({
             checkpointLabel: 'waiting after error before retrying the prompt',
             phase: 'waiting',
@@ -74638,6 +74745,7 @@
         uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.pauseTimer();
         await sleepWithCountdown({
             durationMs: runOptions.waitAfterError,
+            deadlineTimeMs: retryDeadlineTimeMs,
             waitKind: 'after-error',
             isRichUiEnabled,
             uiHandle,
@@ -75233,31 +75341,29 @@
         if (waitAfterPrompt <= 0 && waitBetweenPrompts <= 0) {
             return;
         }
-        const now = Date.now();
         const waitBetweenPromptsEndTime = previousRoundStartTime + waitBetweenPrompts;
         const waitAfterPromptEndTime = previousRoundEndTime + waitAfterPrompt;
-        // Phase 1: pace from start of previous prompt (`--wait-between-prompts`)
-        const phase1Duration = Math.max(0, waitBetweenPromptsEndTime - now);
-        // Phase 2: rest from end of previous prompt (`--wait-after-prompt`)
-        const phase2StartTime = Math.max(now, waitBetweenPromptsEndTime);
-        const phase2Duration = Math.max(0, waitAfterPromptEndTime - phase2StartTime);
-        if (phase1Duration <= 0 && phase2Duration <= 0) {
+        if (Date.now() >= waitBetweenPromptsEndTime && Date.now() >= waitAfterPromptEndTime) {
             return;
         }
         progressDisplay === null || progressDisplay === void 0 ? void 0 : progressDisplay.pauseTimer();
         uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.pauseTimer();
         uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.setPhase('waiting');
-        if (phase1Duration > 0) {
+        // Phase 1: pace from start of previous prompt (`--wait-between-prompts`)
+        if (Date.now() < waitBetweenPromptsEndTime) {
             await sleepWithCountdown({
-                durationMs: phase1Duration,
+                durationMs: waitBetweenPrompts,
+                deadlineTimeMs: waitBetweenPromptsEndTime,
                 waitKind: 'between-prompts',
                 isRichUiEnabled,
                 uiHandle,
             });
         }
-        if (phase2Duration > 0) {
+        // Phase 2: rest from end of previous prompt (`--wait-after-prompt`)
+        if (Date.now() < waitAfterPromptEndTime) {
             await sleepWithCountdown({
-                durationMs: phase2Duration,
+                durationMs: waitAfterPrompt,
+                deadlineTimeMs: waitAfterPromptEndTime,
                 waitKind: 'after-prompt',
                 isRichUiEnabled,
                 uiHandle,