@promptbook/cli 0.113.0-4 → 0.113.0-8

package/umd/index.umd.js

@@ -63,7 +63,7 @@
      * @generated
      * @see https://github.com/webgptorg/promptbook
      */
-    const PROMPTBOOK_ENGINE_VERSION = '0.113.0-4';
+    const PROMPTBOOK_ENGINE_VERSION = '0.113.0-8';
     /**
      * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
      * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -4547,7 +4547,7 @@
         const visibleOutputLines = buildVisibleOutputLines(options.agentOutputLines);
         const controls = buildControlPills(pausePresentation.pauseControl, options.pendingEnterLabel).join('  ');
         const frame = [
-            ...buildCoderRunOctopusVisual({ totalWidth, animationFrame: octopusAnimationFrame }),
+            ...buildFrameHeaderVisual(options, totalWidth, octopusAnimationFrame),
             '',
             ...renderBox('Session', sessionLines, totalWidth, colors__default["default"].yellow.bold),
             ...renderBox(options.currentPromptLabel ? 'Current task' : 'Queue', currentTaskLines, totalWidth, colors__default["default"].magenta.bold),
@@ -4559,6 +4559,18 @@
         frame.push(...renderBox('Controls', [controls], totalWidth, colors__default["default"].white.bold));
         return frame;
     }
+    /**
+     * Builds the header visual above the dashboard boxes.
+     *
+     * Shows the ASCII-art `--agent` avatar visual when one is available and
+     * falls back to the default brand banner otherwise.
+     */
+    function buildFrameHeaderVisual(options, totalWidth, octopusAnimationFrame) {
+        if (options.agentVisualLines !== undefined && options.agentVisualLines.length > 0) {
+            return options.agentVisualLines.map((agentVisualLine) => centerAnsiText(agentVisualLine, totalWidth));
+        }
+        return buildCoderRunOctopusVisual({ totalWidth, animationFrame: octopusAnimationFrame });
+    }
     /**
      * Builds the structured session lines that combine state, runner, queue, and timing metadata.
      */
@@ -4859,6 +4871,13 @@
             this.config = config;
             this.emitChange();
         }
+        /**
+         * Replaces the ASCII-art agent visual shown instead of the default brand banner.
+         */
+        setAgentVisualLines(agentVisualLines) {
+            this.agentVisualLines = agentVisualLines === undefined ? undefined : [...agentVisualLines];
+            this.emitChange();
+        }
         /**
          * Feeds new prompt statistics from the main loop so the progress bar updates.
          */
@@ -5194,6 +5213,7 @@
                 pauseState: getPauseState(),
                 pauseTargetLabel: getPauseTargetLabel(),
                 config: state.config,
+                agentVisualLines: state.agentVisualLines,
                 phase: state.phase,
                 currentPromptLabel: state.currentPromptLabel,
                 currentScriptPaths: state.currentScriptPaths,
@@ -9835,12 +9855,150 @@
     }
 
     /* eslint-disable no-magic-numbers */
+    // Note: [💞] Ignore a discrepancy between file name and entity name
+    /**
+     * Default square size used by avatar renderers.
+     *
+     * @private utility of the avatar rendering system
+     */
+    const DEFAULT_AVATAR_SIZE = 192;
+    /**
+     * Default fallback hash used when no explicit hash is provided.
+     *
+     * @private utility of the avatar rendering system
+     */
+    const DEFAULT_AVATAR_HASH = '0000000000000000000000000000000000000000000000000000000000000000';
+    /**
+     * Default fallback name used when no explicit name is provided.
+     *
+     * @private utility of the avatar rendering system
+     */
+    const DEFAULT_AVATAR_NAME = 'Anonymous Agent';
     /**
      * Corner radius ratio used for the common rounded card frame.
      *
      * @private utility of the avatar rendering system
      */
     const FRAME_RADIUS_RATIO = 0.18;
+    /**
+     * Normalizes arbitrary agent colors into a stable non-empty color list.
+     *
+     * @param colors Raw color list.
+     * @returns Stable list of usable colors.
+     *
+     * @private utility of the avatar rendering system
+     */
+    function normalizeAvatarColors(colors) {
+        const normalizedColors = colors
+            .map((color) => String(color).trim())
+            .filter((color) => color !== '')
+            .map((color) => Color.fromSafe(color).toHex());
+        if (normalizedColors.length > 0) {
+            return normalizedColors;
+        }
+        return [PROMPTBOOK_COLOR.toHex()];
+    }
+    /**
+     * Normalizes the avatar input so visuals can rely on consistent data.
+     *
+     * @param avatarDefinition Raw avatar input.
+     * @returns Normalized avatar definition.
+     *
+     * @private utility of the avatar rendering system
+     */
+    function normalizeAvatarDefinition(avatarDefinition) {
+        return {
+            agentName: (avatarDefinition.agentName || DEFAULT_AVATAR_NAME).trim() || DEFAULT_AVATAR_NAME,
+            agentHash: (avatarDefinition.agentHash || DEFAULT_AVATAR_HASH).trim() || DEFAULT_AVATAR_HASH,
+            colors: normalizeAvatarColors(avatarDefinition.colors),
+        };
+    }
+    /**
+     * Extracts avatar colors from the flexible `META COLOR` agent field.
+     *
+     * @param colorValue Raw `META COLOR` value.
+     * @returns Parsed avatar colors.
+     *
+     * @private utility of the avatar rendering system
+     */
+    function parseAvatarColors(colorValue) {
+        if (!colorValue) {
+            return [];
+        }
+        const colors = [];
+        let currentColor = '';
+        let bracketDepth = 0;
+        for (const character of colorValue) {
+            if (character === '(') {
+                bracketDepth++;
+                currentColor += character;
+                continue;
+            }
+            if (character === ')') {
+                bracketDepth = Math.max(0, bracketDepth - 1);
+                currentColor += character;
+                continue;
+            }
+            if (bracketDepth === 0 && [',', ';', '|', '\n'].includes(character)) {
+                const normalizedColor = currentColor.trim();
+                if (normalizedColor !== '') {
+                    colors.push(normalizedColor);
+                }
+                currentColor = '';
+                continue;
+            }
+            currentColor += character;
+        }
+        const lastColor = currentColor.trim();
+        if (lastColor !== '') {
+            colors.push(lastColor);
+        }
+        return colors;
+    }
+    /**
+     * Creates a reusable avatar definition from parsed agent information.
+     *
+     * @param agentBasicInformation Parsed agent information.
+     * @returns Avatar definition ready for canvas rendering.
+     *
+     * @private shared helper for app-level avatar previews
+     */
+    function createAvatarDefinitionFromAgentBasicInformation(agentBasicInformation) {
+        return normalizeAvatarDefinition({
+            agentName: agentBasicInformation.agentName,
+            agentHash: agentBasicInformation.agentHash,
+            colors: parseAvatarColors(agentBasicInformation.meta.color),
+        });
+    }
+    /**
+     * Creates the shared derived palette used by every avatar visual.
+     *
+     * @param avatarDefinition Stable avatar definition.
+     * @param surface Surface style used by the parent UI.
+     * @returns Derived palette.
+     *
+     * @private utility of the avatar rendering system
+     */
+    function createAvatarPalette(avatarDefinition, surface = 'framed') {
+        const normalizedAvatarDefinition = normalizeAvatarDefinition(avatarDefinition);
+        const primaryColor = Color.fromSafe(normalizedAvatarDefinition.colors[0] || PROMPTBOOK_COLOR);
+        const secondaryColor = Color.fromSafe(normalizedAvatarDefinition.colors[1] || primaryColor.then(lighten(0.12)).then(saturate(0.16)));
+        const accentColor = Color.fromSafe(normalizedAvatarDefinition.colors[2] || primaryColor.then(saturate(0.32)).then(lighten(0.22)));
+        const backgroundColor = Color.fromSafe(primaryColor.then(darken(0.34)).then(saturate(-0.1)));
+        const backgroundSecondaryColor = Color.fromSafe(secondaryColor.then(darken(0.42)).then(saturate(-0.16)).then(lighten(0.04)));
+        const highlightColor = Color.fromSafe(accentColor.then(lighten(0.22)).then(saturate(0.08)));
+        const shadowColor = Color.fromSafe(primaryColor.then(darken(0.46)).then(saturate(0.14)));
+        return {
+            background: surface === 'transparent' ? 'transparent' : backgroundColor.toHex(),
+            backgroundSecondary: surface === 'transparent' ? 'transparent' : backgroundSecondaryColor.toHex(),
+            primary: primaryColor.toHex(),
+            secondary: secondaryColor.toHex(),
+            accent: accentColor.toHex(),
+            highlight: highlightColor.toHex(),
+            shadow: shadowColor.toHex(),
+            ink: createInkColor(primaryColor),
+        };
+    }
     /**
      * Draws the common rounded background frame used by most visuals.
      *
@@ -9891,6 +10049,67 @@
         context.arcTo(x, y, x + width, y, normalizedRadius);
         context.closePath();
     }
+    /**
+     * Creates a stable pseudo-random number generator from a string seed.
+     *
+     * @param seedSource String seed.
+     * @returns Generator producing values in `[0, 1)`.
+     *
+     * @private utility of the avatar rendering system
+     */
+    function createSeededRandom(seedSource) {
+        let state = hashStringToUint32(seedSource) || 0x9e3779b9;
+        return () => {
+            state = (state + 0x6d2b79f5) >>> 0;
+            let hash = Math.imul(state ^ (state >>> 15), 1 | state);
+            hash ^= hash + Math.imul(hash ^ (hash >>> 7), 61 | hash);
+            return ((hash ^ (hash >>> 14)) >>> 0) / 4294967296;
+        };
+    }
+    /**
+     * Creates a deterministic random factory scoped to the avatar definition.
+     *
+     * @param avatarDefinition Stable avatar definition.
+     * @returns Random factory that can be re-seeded per visual part.
+     *
+     * @private utility of the avatar rendering system
+     */
+    function createAvatarRandomFactory(avatarDefinition) {
+        const normalizedAvatarDefinition = normalizeAvatarDefinition(avatarDefinition);
+        const seedBase = `${normalizedAvatarDefinition.agentName}|${normalizedAvatarDefinition.agentHash}|${normalizedAvatarDefinition.colors.join('|')}`;
+        return (salt) => createSeededRandom(`${seedBase}|${salt}`);
+    }
+    /**
+     * Clears and scales the canvas for crisp avatar rendering on high DPI displays.
+     *
+     * @param canvas Canvas element to prepare.
+     * @param context Canvas 2D context.
+     * @param size Canvas size in CSS pixels.
+     * @param devicePixelRatio Device pixel ratio.
+     *
+     * @private utility of the avatar rendering system
+     */
+    function prepareAvatarCanvas(canvas, context, size, devicePixelRatio) {
+        const normalizedDevicePixelRatio = Math.max(1, Math.round(devicePixelRatio * 100) / 100);
+        const nextCanvasWidth = Math.round(size * normalizedDevicePixelRatio);
+        const nextCanvasHeight = Math.round(size * normalizedDevicePixelRatio);
+        const nextCanvasStyleWidth = `${size}px`;
+        const nextCanvasStyleHeight = `${size}px`;
+        if (canvas.width !== nextCanvasWidth) {
+            canvas.width = nextCanvasWidth;
+        }
+        if (canvas.height !== nextCanvasHeight) {
+            canvas.height = nextCanvasHeight;
+        }
+        if (canvas.style.width !== nextCanvasStyleWidth) {
+            canvas.style.width = nextCanvasStyleWidth;
+        }
+        if (canvas.style.height !== nextCanvasStyleHeight) {
+            canvas.style.height = nextCanvasStyleHeight;
+        }
+        context.setTransform(normalizedDevicePixelRatio, 0, 0, normalizedDevicePixelRatio, 0, 0);
+        context.clearRect(0, 0, size, size);
+    }
     /**
      * Picks one deterministic element from a non-empty collection.
      *
@@ -9903,6 +10122,37 @@
     function pickRandomItem(items, random) {
         return items[Math.floor(random() * items.length)];
     }
+    /**
+     * Creates a readable ink color from the given base color.
+     *
+     * @param color Base color.
+     * @returns High-contrast ink color.
+     *
+     * @private utility of the avatar rendering system
+     */
+    function createInkColor(color) {
+        const perceivedBrightness = color.red * 0.299 + color.green * 0.587 + color.blue * 0.114;
+        if (perceivedBrightness > 150) {
+            return '#172033';
+        }
+        return '#f8fbff';
+    }
+    /**
+     * Hashes an arbitrary string into a 32-bit unsigned integer.
+     *
+     * @param value Arbitrary input.
+     * @returns 32-bit unsigned integer hash.
+     *
+     * @private utility of the avatar rendering system
+     */
+    function hashStringToUint32(value) {
+        let hash = 2166136261;
+        for (const character of value) {
+            hash ^= character.charCodeAt(0);
+            hash = Math.imul(hash, 16777619);
+        }
+        return hash >>> 0;
+    }
 
     /* eslint-disable no-magic-numbers */
     /**
@@ -14418,7 +14668,7 @@
         isAnimated: true,
         supportsPointerTracking: true,
         render({ context, size, palette, createRandom, timeMs, interaction }) {
-            const { morphologyProfile, animationPhase, leftEyePhaseOffset, rightEyePhaseOffset, tentacleProfiles, skinSpots } = getOctopus3d4StableState(createRandom);
+            const { morphologyProfile, animationPhase, leftEyePhaseOffset, rightEyePhaseOffset, tentacleProfiles, skinSpots, } = getOctopus3d4StableState(createRandom);
             const sceneCenterX = size * 0.5;
             const sceneCenterY = size * 0.535;
             const bob = Math.sin(timeMs / 980 + animationPhase) * size * 0.013;
@@ -14766,10 +15016,7 @@
             Math.max(0, Math.cos(effectiveLongitude)) * 0.12 +
             lowerBlend * tentacleInfluence.core * (0.12 + tentacleInfluence.depthScale * 0.07) -
             Math.max(0, -Math.cos(effectiveLongitude)) * 0.05;
-        const tentacleTubeRadius = lowerBlend *
-            tentacleInfluence.core *
-            (0.12 + tipBlend * 0.07 + tentacleInfluence.widthScale * 0.028) *
-            radiusX;
+        const tentacleTubeRadius = lowerBlend * tentacleInfluence.core * (0.12 + tipBlend * 0.07 + tentacleInfluence.widthScale * 0.028) * radiusX;
         const planarRadiusX = cosineLatitude * radiusX * horizontalScale + tentacleTubeRadius;
         const planarRadiusZ = cosineLatitude * radiusZ * depthScale + tentacleTubeRadius * 0.74;
         const lowerDrop = lowerBlend *
@@ -14781,9 +15028,7 @@
                         (morphologyProfile.tentacles.flowLengthScale - 1) * 0.1));
         const combinedTentacleSway = (primaryTentacleWave + secondaryTentacleWave) * radiusX * (0.06 + tipBlend * 0.06);
         return {
-            x: Math.sin(effectiveLongitude) * planarRadiusX +
-                combinedTentacleSway +
-                tentacleCurl * radiusX * 0.18,
+            x: Math.sin(effectiveLongitude) * planarRadiusX + combinedTentacleSway + tentacleCurl * radiusX * 0.18,
             y: Math.sin(latitude) * radiusY * (1 + upperBlend * 0.14) -
                 upperBlend * radiusY * 0.12 +
                 lowerDrop +
@@ -15890,6 +16135,21 @@
             .toLowerCase()
             .replace(/[^a-z0-9]+/g, '');
     }
+    /**
+     * Returns one avatar visual by its identifier.
+     *
+     * @param visualId Requested visual identifier.
+     * @returns Matching visual definition.
+     *
+     * @private shared registry for the avatar rendering system
+     */
+    function getAvatarVisualById(visualId) {
+        const avatarVisual = AVATAR_VISUALS.find((candidateAvatarVisual) => candidateAvatarVisual.id === visualId);
+        if (!avatarVisual) {
+            throw new Error(`Unknown avatar visual "${visualId}".`);
+        }
+        return avatarVisual;
+    }
     /**
      * Resolves a user-facing avatar visual value to a supported built-in visual id.
      *
@@ -18027,10 +18287,10 @@
      *
      * @private
      */
-    const TEAM_SYSTEM_MESSAGE_GUIDANCE_LINES = [
-        '-   If a teammate is relevant to the request, consult that teammate using the matching tool.',
-        '-   Do not ask the user for information that a listed teammate can provide directly.',
-    ];
+    const TEAM_SYSTEM_MESSAGE_GUIDANCE = _spaceTrim.spaceTrim(`
+    -   If a teammate is relevant to the request, consult that teammate using the matching tool.
+    -   Do not ask the user for information that a listed teammate can provide directly.
+`);
     /**
      * Constant for remote agents by Url.
      */
@@ -18212,7 +18472,7 @@
             `);
         });
         return _spaceTrim.spaceTrim((block) => `
-            ${block(TEAM_SYSTEM_MESSAGE_GUIDANCE_LINES.join('\n'))}
+            ${block(TEAM_SYSTEM_MESSAGE_GUIDANCE)}
 
             ${block(teammateSections.join('\n\n'))}
         `);
@@ -28470,7 +28730,7 @@
         const MODEL_ARGUMENT = options.model ? ` --model ${options.model}` : '';
         const THINKING_LEVEL_ARGUMENT = options.thinkingLevel ? ` --effort ${options.thinkingLevel}` : '';
         return spaceTrim((block) => `
-            claude --allowedTools "Bash,Read,Edit,Write"${MODEL_ARGUMENT}${THINKING_LEVEL_ARGUMENT} --output-format json --print <<'${CLAUDE_PROMPT_DELIMITER}'
+            claude --allowedTools "Bash,Read,Edit,Write"${MODEL_ARGUMENT}${THINKING_LEVEL_ARGUMENT} --output-format stream-json --verbose --include-partial-messages --print <<'${CLAUDE_PROMPT_DELIMITER}'
 
             ${block(options.prompt)}
 
@@ -40030,6 +40290,30 @@
     }
     // Note: [🟡] Code for repository script [RefactorCandidateLevel](scripts/find-refactor-candidates/RefactorCandidateLevel.ts) should never be published outside of `@promptbook/cli`
 
+    /**
+     * Creates a Commander argument parser that accepts only positive integers.
+     *
+     * The returned parser is meant to be passed as the coercion callback of `command.option(...)`.
+     * It throws a branded `NotAllowed` error with a clear message referencing the given option name
+     * when the provided value is not a positive integer.
+     *
+     * @private internal utility of `promptbookCli`
+     */
+    function createPositiveIntegerOptionParser(optionName) {
+        return (value) => {
+            const parsedValue = Number(value);
+            if (!Number.isInteger(parsedValue) || parsedValue <= 0) {
+                throw new NotAllowed(_spaceTrim.spaceTrim(`
+                    Invalid value for \`${optionName}\`: \`${value}\`.
+
+                    Use a positive integer.
+                `));
+            }
+            return parsedValue;
+        };
+    }
+    // Note: [🟡] Code for CLI option parser [createPositiveIntegerOptionParser](src/cli/cli-commands/common/createPositiveIntegerOptionParser.ts) should never be published outside of `@promptbook/cli`
+
     /**
      * Initializes `coder find-refactor-candidates` command for Promptbook CLI utilities
      *
@@ -40050,12 +40334,13 @@
         command.addOption(new commander.Option('--level <level>', `Set scan aggressiveness (${REFACTOR_CANDIDATE_LEVEL_VALUES.join(', ')})`)
             .choices([...REFACTOR_CANDIDATE_LEVEL_VALUES])
             .default(DEFAULT_REFACTOR_CANDIDATE_LEVEL));
+        command.option('--limit <candidate-count>', 'Create at most this many refactor prompts, keeping the most important candidates', createPositiveIntegerOptionParser('--limit'));
         command.action(handleActionErrors(async (cliOptions) => {
-            const { level = DEFAULT_REFACTOR_CANDIDATE_LEVEL } = cliOptions;
+            const { level = DEFAULT_REFACTOR_CANDIDATE_LEVEL, limit } = cliOptions;
             // Note: Import the function dynamically to avoid loading heavy dependencies until needed
             const { findRefactorCandidates } = await Promise.resolve().then(function () { return findRefactorCandidates$1; });
             try {
-                await findRefactorCandidates({ level });
+                await findRefactorCandidates({ level, limit });
             }
             catch (error) {
                 assertsError(error);
@@ -40139,26 +40424,26 @@
             id: 'common',
             relativeFilePath: path.join(PROMPTS_TEMPLATES_DIRECTORY_PATH, 'common.md'),
             slugPrefix: null,
-            content: buildCoderPromptTemplateContent([
-                '-   @@@',
-                "-   Keep in mind the DRY _(don't repeat yourself)_ principle.",
-                '-   Do a proper analysis of the current functionality before you start implementing.',
-                '-   Add the changes into the [changelog](changelog/_current-preversion.md)',
-            ]),
+            content: _spaceTrim.spaceTrim(`
+            -   @@@
+            -   Keep in mind the DRY _(don't repeat yourself)_ principle.
+            -   Do a proper analysis of the current functionality before you start implementing.
+            -   Add the changes into the [changelog](changelog/_current-preversion.md)
+        `),
             isDefaultProjectTemplate: true,
         },
         {
             id: 'agents-server',
             relativeFilePath: path.join(PROMPTS_TEMPLATES_DIRECTORY_PATH, 'agents-server.md'),
             slugPrefix: 'agents-server',
-            content: buildCoderPromptTemplateContent([
-                '-   @@@',
-                "-   Keep in mind the DRY _(don't repeat yourself)_ principle.",
-                '-   Do a proper analysis of the current functionality before you start implementing.',
-                '-   You are working with the [Agents Server](apps/agents-server)',
-                '-   If you need to do the database migration, do it',
-                '-   Add the changes into the [changelog](changelog/_current-preversion.md)',
-            ]),
+            content: _spaceTrim.spaceTrim(`
+            -   @@@
+            -   Keep in mind the DRY _(don't repeat yourself)_ principle.
+            -   Do a proper analysis of the current functionality before you start implementing.
+            -   You are working with the [Agents Server](apps/agents-server)
+            -   If you need to do the database migration, do it
+            -   Add the changes into the [changelog](changelog/_current-preversion.md)
+        `),
             isDefaultProjectTemplate: false,
         },
     ];
@@ -40278,12 +40563,6 @@
     function getDefaultCoderPromptTemplateDefinitionOrUndefined(template) {
         return DEFAULT_CODER_PROMPT_TEMPLATE_DEFINITIONS.find((definition) => definition.id === template);
     }
-    /**
-     * Builds stable markdown content for one coder prompt template without indentation drift.
-     */
-    function buildCoderPromptTemplateContent(lines) {
-        return lines.join('\n');
-    }
     /**
      * Creates a fully resolved template payload from one built-in definition.
      */
@@ -41210,7 +41489,7 @@
         command.option('--preserve-logs', 'Keep generated temp prompt/log artifacts after successful rounds for debugging and analytics', false);
         addPromptRunnerExecutionOptions(command);
         command.option('--priority <minimum-priority>', 'Filter prompts by minimum priority level', parseIntOption$1, 0);
-        command.option('--limit <run-count>', 'Stop after processing this many prompt runs', parsePositiveIntegerOption);
+        command.option('--limit <run-count>', 'Stop after processing this many prompt runs', createPositiveIntegerOptionParser('--limit'));
         command.option('--wait-after-prompt <duration>', _spaceTrim.spaceTrim(`
             Wait this long after each prompt has been implemented, verified and committed before starting the next prompt.
             Accepts durations like 1h, 30m, 5s. Defaults to 0 (no wait).
@@ -41297,22 +41576,6 @@
         }
         return parsed;
     }
-    /**
-     * Parses a positive integer option value.
-     *
-     * @private internal utility of `coder run` command
-     */
-    function parsePositiveIntegerOption(value) {
-        const parsed = Number(value);
-        if (!Number.isInteger(parsed) || parsed <= 0) {
-            throw new NotAllowed(_spaceTrim.spaceTrim(`
-                Invalid value for \`--limit\`: \`${value}\`.
-
-                Use a positive integer.
-            `));
-        }
-        return parsed;
-    }
     /**
      * Joins one Commander option that may be parsed either as a single string or a variadic token array.
      *
@@ -69585,23 +69848,28 @@
         const extension = path.extname(filePath).toLowerCase();
         const relativePath = normalizeRefactorCandidatePath(path.relative(rootDir, filePath));
         const reasons = [];
+        let severityScore = 0;
         if (!lineCountExemptPaths.has(normalizedAbsolutePath)) {
             const lineCount = countLines(content);
             const maxLines = getMaxLinesForExtension(extension, heuristics);
             if (lineCount > maxLines) {
                 reasons.push(`lines ${lineCount}/${maxLines}`);
+                severityScore += lineCount / maxLines;
             }
         }
         if (STRUCTURAL_ANALYSIS_EXTENSIONS.includes(extension)) {
             const structureSummary = summarizeSourceFileStructure(content, extension, filePath);
             if (structureSummary.entityCount > heuristics.maxEntityCountPerFile) {
                 reasons.push(`entities ${structureSummary.entityCount}/${heuristics.maxEntityCountPerFile}`);
+                severityScore += structureSummary.entityCount / heuristics.maxEntityCountPerFile;
             }
             if (structureSummary.functionCount > heuristics.maxFunctionCountPerFile) {
                 reasons.push(`functions ${structureSummary.functionCount}/${heuristics.maxFunctionCountPerFile}`);
+                severityScore += structureSummary.functionCount / heuristics.maxFunctionCountPerFile;
             }
             if (structureSummary.maxFunctionComplexity > heuristics.maxFunctionComplexity) {
                 reasons.push(buildComplexityReason(structureSummary, heuristics.maxFunctionComplexity));
+                severityScore += structureSummary.maxFunctionComplexity / heuristics.maxFunctionComplexity;
             }
         }
         if (reasons.length === 0) {
@@ -69611,6 +69879,7 @@
             absolutePath: filePath,
             relativePath,
             reasons,
+            severityScore,
         };
     }
     /**
@@ -70070,6 +70339,37 @@
     }
     // Note: [🟡] Code for repository script [resolveRefactorCandidateProject](scripts/find-refactor-candidates/resolveRefactorCandidateProject.ts) should never be published outside of `@promptbook/cli`
 
+    /**
+     * Keeps at most `limit` refactor candidates, preferring the most important ones.
+     *
+     * When there are more candidates than `limit`, only the highest-severity candidates are kept
+     * (ties broken by relative path for determinism). When `limit` is `undefined` or there are fewer
+     * candidates than the limit, every candidate is returned. The original input order is preserved
+     * among the kept candidates, so `limit` acts purely as a filter and never reorders prompts.
+     *
+     * @private function of findRefactorCandidates
+     */
+    function selectMostImportantRefactorCandidates(candidates, limit) {
+        if (limit === undefined || candidates.length <= limit) {
+            return candidates;
+        }
+        const candidatesRankedByImportance = [...candidates].sort(compareRefactorCandidatesByImportance);
+        const keptRelativePaths = new Set(candidatesRankedByImportance.slice(0, limit).map((candidate) => candidate.relativePath));
+        return candidates.filter((candidate) => keptRelativePaths.has(candidate.relativePath));
+    }
+    /**
+     * Orders refactor candidates from most to least important.
+     *
+     * @private function of selectMostImportantRefactorCandidates
+     */
+    function compareRefactorCandidatesByImportance(candidateA, candidateB) {
+        if (candidateB.severityScore !== candidateA.severityScore) {
+            return candidateB.severityScore - candidateA.severityScore;
+        }
+        return candidateA.relativePath.localeCompare(candidateB.relativePath);
+    }
+    // Note: [🟡] Code for repository script [selectMostImportantRefactorCandidates](scripts/find-refactor-candidates/selectMostImportantRefactorCandidates.ts) should never be published outside of `@promptbook/cli`
+
     /**
      * Calculates the next available prompt numbering sequence for a month.
      */
@@ -70393,7 +70693,7 @@
      * @public exported from `@promptbook/cli`
      */
     async function findRefactorCandidates(options = {}) {
-        const { level = DEFAULT_REFACTOR_CANDIDATE_LEVEL } = options;
+        const { level = DEFAULT_REFACTOR_CANDIDATE_LEVEL, limit } = options;
         const heuristics = getRefactorCandidateLevelConfiguration(level);
         initializeFindRefactorCandidatesRun();
         console.info(colors__default["default"].cyan('⚡🏭 Find refactor candidates'));
@@ -70417,8 +70717,10 @@
             console.info(colors__default["default"].green('All candidates already have prompts.'));
             return;
         }
+        const selectedCandidatesToWrite = selectMostImportantRefactorCandidates(candidatesToWrite, limit);
+        const skippedByLimit = candidatesToWrite.length - selectedCandidatesToWrite.length;
         const createdPrompts = await writeRefactorCandidatePrompts({
-            candidates: candidatesToWrite,
+            candidates: selectedCandidatesToWrite,
             rootDir,
             promptsDir,
         });
@@ -70426,6 +70728,9 @@
         if (alreadyTracked > 0) {
             console.info(colors__default["default"].gray(`Skipped ${alreadyTracked} candidate(s) with existing prompts.`));
         }
+        if (skippedByLimit > 0) {
+            console.info(colors__default["default"].gray(`Skipped ${skippedByLimit} lower-priority candidate(s) because of \`--limit ${limit}\`.`));
+        }
     }
     /**
      * Prints discovered refactor candidates with their reasons.
@@ -71226,7 +71531,7 @@
      *
      * Returns `undefined` when no agent path is provided.
      */
-    async function resolveAgentSystemMessage(agentPath, currentWorkingDirectory) {
+    async function resolveCoderAgent(agentPath, currentWorkingDirectory) {
         if (!agentPath) {
             return undefined;
         }
@@ -71241,7 +71546,10 @@
             }
             throw error;
         });
-        return createAgentRunnerSystemMessage(agentSource);
+        return {
+            agentSource: agentSource,
+            systemMessage: await createAgentRunnerSystemMessage(agentSource),
+        };
     }
 
     /**
@@ -71439,6 +71747,497 @@
         await waitForEnter(colors__default["default"].bgWhite(`Press Enter to start the ${label}...`));
     }
 
+    /**
+     * 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;
+    }
+
+    /**
+     * 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 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;
+    /**
+     * 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;
+        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 canvas = options.createCanvas(DEFAULT_AVATAR_SIZE, DEFAULT_AVATAR_SIZE);
+        if (!canvas.style) {
+            // Note: `renderAvatarVisual` expects a browser canvas shape; Node.js canvases only need this tiny compatibility shim.
+            canvas.style = {};
+        }
+        renderAvatarVisual({
+            canvas,
+            avatarDefinition: options.avatarDefinition,
+            visualId: options.visualId,
+            size: DEFAULT_AVATAR_SIZE,
+            timeMs: (_c = options.timeMs) !== null && _c !== void 0 ? _c : STATIC_AVATAR_ASCII_ART_FRAME_TIME_MS,
+            devicePixelRatio: 1,
+        });
+        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.
+            `));
+        }
+        const imageData = context.getImageData(0, 0, DEFAULT_AVATAR_SIZE, DEFAULT_AVATAR_SIZE);
+        return convertImageDataToAsciiArt({
+            imageData,
+            columns,
+            rows,
+            colorDepth: options.colorDepth,
+        });
+    }
+
+    /**
+     * Default built-in avatar visual used when an agent does not define `META IMAGE`.
+     *
+     * @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.
+     *
+     * Prefers 24-bit true color when the environment advertises it (modern terminals such as
+     * Windows Terminal, ConEmu, VS Code, mintty, iTerm2, and WezTerm) and falls back to the
+     * portable 256-color palette otherwise.
+     *
+     * Note: `$` is used to indicate that this function is not a pure function - it reads the process environment
+     *
+     * @returns Color depth usable by `convertImageDataToAsciiArt`
+     *
+     * @private within the repository
+     */
+    function $detectTerminalAnsiColorDepth() {
+        if (typeof process === 'undefined' || !process.env) {
+            return 'ANSI_256';
+        }
+        const colorTerm = (process.env.COLORTERM || '').toLowerCase();
+        if (colorTerm.includes('truecolor') || colorTerm.includes('24bit')) {
+            return 'TRUE_COLOR';
+        }
+        if (process.env.WT_SESSION !== undefined) {
+            return 'TRUE_COLOR'; // <- Note: Windows Terminal always supports true color but does not set COLORTERM
+        }
+        if (process.env.ConEmuANSI === 'ON') {
+            return 'TRUE_COLOR';
+        }
+        const termProgram = process.env.TERM_PROGRAM || '';
+        if (['vscode', 'iTerm.app', 'WezTerm', 'ghostty', 'Hyper'].includes(termProgram)) {
+            return 'TRUE_COLOR';
+        }
+        const term = (process.env.TERM || '').toLowerCase();
+        if (term.includes('truecolor') || term.includes('24bit') || term.includes('direct')) {
+            return 'TRUE_COLOR';
+        }
+        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 = 24;
+    /**
+     * Output height of the coder-run agent visual in terminal character cells.
+     *
+     * Half of the columns keeps the square avatar visually square in a common terminal font.
+     *
+     * @private internal constant of coder run UI
+     */
+    const CODER_RUN_AGENT_VISUAL_ROWS = 12;
+    /**
+     * Builds the ANSI ASCII-art visual of the `--agent` book shown above the coder-run dashboard.
+     *
+     * The agent's avatar visual is resolved the same way as on the website - the `META AVATAR`
+     * commitment wins, then the `META VISUAL` commitment, then the shared default visual - and is
+     * rendered dynamically through the shared canvas avatar pipeline into terminal ASCII art.
+     *
+     * The visual is decorative, so any failure (for example when the optional `@napi-rs/canvas`
+     * module is not installed) returns `null` and the caller keeps the default brand banner.
+     *
+     * @param agentSource Source of the `--agent` book file.
+     * @returns ANSI-colored ASCII-art lines or `null` when the visual cannot be rendered.
+     */
+    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);
+            return renderAvatarVisualAsciiArt({
+                avatarDefinition,
+                visualId: avatarVisualId,
+                columns: CODER_RUN_AGENT_VISUAL_COLUMNS,
+                rows: CODER_RUN_AGENT_VISUAL_ROWS,
+                colorDepth: $detectTerminalAnsiColorDepth(),
+                createCanvas: (width, height) => createCanvas(width, height),
+            });
+        }
+        catch (error) {
+            return null;
+        }
+    }
+
     /**
      * Formats commit message lines for console display.
      */
@@ -73355,13 +74154,15 @@
         startPauseListenerIfNeeded(isRichUiEnabled);
         try {
             const resolvedCoderContext = await resolveCoderContext(options.context, process.cwd());
-            const resolvedAgentSystemMessage = await resolveAgentSystemMessage(options.agent, process.cwd());
+            const resolvedCoderAgent = await resolveCoderAgent(options.agent, process.cwd());
+            const resolvedAgentSystemMessage = resolvedCoderAgent === null || resolvedCoderAgent === void 0 ? void 0 : resolvedCoderAgent.systemMessage;
             if (await runDryRunIfRequested(options)) {
                 return;
             }
             const { runner, actualRunnerModel, runnerMetadata } = resolvePromptRunner(options);
             console.info(colors__default["default"].green(`Running prompts with ${runner.name}`));
             initializeRunUi(uiHandle, runner.name, actualRunnerModel, options);
+            await initializeRunUiAgentVisual(uiHandle, resolvedCoderAgent === null || resolvedCoderAgent === void 0 ? void 0 : resolvedCoderAgent.agentSource);
             await seedCachedAveragePromptDuration({
                 options,
                 actualRunnerModel,
@@ -73599,6 +74400,20 @@
         uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.setPhase('loading');
         uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.setStatusMessage(`Running prompts with ${runnerName}`);
     }
+    /**
+     * Renders the `--agent` book avatar as ASCII art and shows it instead of the default brand banner.
+     *
+     * Keeps the default banner when no agent is selected, the UI is disabled, or the visual cannot be rendered.
+     */
+    async function initializeRunUiAgentVisual(uiHandle, agentSource) {
+        if (!uiHandle || !agentSource) {
+            return;
+        }
+        const agentVisualLines = await buildCoderRunAgentVisual(agentSource);
+        if (agentVisualLines) {
+            uiHandle.state.setAgentVisualLines(agentVisualLines);
+        }
+    }
     /**
      * Loads prompt files, updates progress displays, and selects the next runnable prompt.
      */