@promptbook/cli 0.113.0-10 → 0.113.0-11

package/esm/index.es.js

@@ -59,7 +59,7 @@ const BOOK_LANGUAGE_VERSION = '2.0.0';
  * @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
@@ -28105,6 +28105,47 @@ async function $runGoScriptWithOutput(options) {
     });
 }
 
+/**
+ * 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.
  */
@@ -28514,36 +28555,32 @@ class ClaudeCodeRunner {
  * 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.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.
  */
@@ -29427,12 +29464,6 @@ const RATE_LIMIT_BACKOFF_MAX_MS = 30 * 60 * 1000;
  * 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.
  */
@@ -29522,13 +29553,18 @@ class OpenAiCodexRunner {
                     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.yellow(`[codex] Rate limit/quota detected (${summary}). Retry #${retryIndex} in ${formatDelay(delayMs)} at ${retryAt}.`));
                 }
-                await waitForRetryDelay(delayMs, options);
+                await waitForRetryDelay({
+                    delayMs,
+                    retryDeadlineTimeMs,
+                    promptRunOptions: options,
+                });
             }
         }
     }
@@ -29536,20 +29572,21 @@ class OpenAiCodexRunner {
 /**
  * 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`,
+            }));
+        },
+    });
 }
 
 /**
@@ -30050,12 +30087,597 @@ function buildCoderRunOctopusVisual(options) {
         .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$1(`
+                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$1(`
+                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$1(`
+                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$1(`
+            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.
@@ -72141,23 +72763,25 @@ function describeCoderRunWait(waitKind, remainingMs, totalMs) {
  * @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.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.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;
-    }
+        },
+    });
 }
 
 /**
@@ -72303,479 +72927,6 @@ async function waitForPromptStart(file, section, isFirstPrompt) {
     await waitForEnter(colors.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$1(`
-                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$1(`
-                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$1(`
-                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$1(`
-            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.
  *
@@ -72814,36 +72965,6 @@ function $detectTerminalAnsiColorDepth() {
     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.
  *
@@ -72862,33 +72983,18 @@ async function buildCoderRunAgentVisual(agentSource) {
     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);
@@ -74625,6 +74731,7 @@ async function waitAfterErrorBeforeRetry(options) {
     if (!isRichUiEnabled) {
         console.warn(colors.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',
@@ -74634,6 +74741,7 @@ async function waitAfterErrorBeforeRetry(options) {
     uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.pauseTimer();
     await sleepWithCountdown({
         durationMs: runOptions.waitAfterError,
+        deadlineTimeMs: retryDeadlineTimeMs,
         waitKind: 'after-error',
         isRichUiEnabled,
         uiHandle,
@@ -75229,31 +75337,29 @@ async function waitBetweenPromptRoundsIfNeeded(options) {
     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,