@promptbook/cli 0.114.0-5 → 0.114.0-8

package/umd/index.umd.js

@@ -58,7 +58,7 @@
      * @generated
      * @see https://github.com/webgptorg/promptbook
      */
-    const PROMPTBOOK_ENGINE_VERSION = '0.114.0-5';
+    const PROMPTBOOK_ENGINE_VERSION = '0.114.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
@@ -2593,7 +2593,10 @@
         if (currentGitignoreContent !== undefined && missingRules.length === 0) {
             return 'unchanged';
         }
-        const nextGitignoreContent = appendBlock(currentGitignoreContent || '', [blockHeader, ...missingRules].join('\n'));
+        const nextGitignoreContent = appendBlock(currentGitignoreContent || '', _spaceTrim.spaceTrim((block) => `
+                ${block(blockHeader)}
+                ${block(missingRules.join('\n'))}
+            `));
         await promises.writeFile(gitignorePath, nextGitignoreContent, 'utf-8');
         return currentGitignoreContent === undefined ? 'created' : 'updated';
     }
@@ -7463,6 +7466,15 @@
      * @private helper of `asciiOctopusAvatarVisual`
      */
     const ATMOSPHERE_GLYPHS = ['.', ':', "'", '`'];
+    /**
+     * Coordinate space the octopus layout is generated in when it is painted into a terminal.
+     *
+     * The terminal renderer has its own character grid, so the geometry only needs one stable
+     * square coordinate space which the grid is then sampled from.
+     *
+     * @private helper of `asciiOctopusAvatarVisual`
+     */
+    const TERMINAL_ASCII_OCTOPUS_LAYOUT_SIZE = DEFAULT_AVATAR_SIZE;
     /**
      * AsciiOctopus avatar visual.
      *
@@ -7479,41 +7491,115 @@
             const staticRandom = createRandom('ascii-octopus-static');
             const gridMetrics = createAsciiGridMetrics(size, gridRandom);
             const layout = createAsciiOctopusLayout(size, timeMs, createRandom, staticRandom, interaction);
+            const glyphGrid = createAsciiOctopusGlyphGrid({
+                sampleGrid: gridMetrics,
+                layout,
+                palette,
+                cellRandom: createRandom('ascii-octopus-cells'),
+                timeMs,
+            });
             drawAvatarFrame(context, size, palette);
             drawAsciiBackdrop(context, size, palette, layout, timeMs);
             context.save();
             context.font = `600 ${gridMetrics.fontSize}px monospace`;
             context.textAlign = 'center';
             context.textBaseline = 'middle';
-            // The ASCII renderer samples the morphing octopus field on a low-resolution grid so the shape stays organic
-            // while the glyph layout remains deterministic for the same avatar input.
-            const cellRandom = createRandom('ascii-octopus-cells');
             for (let rowIndex = 0; rowIndex < gridMetrics.rowCount; rowIndex++) {
                 for (let columnIndex = 0; columnIndex < gridMetrics.columnCount; columnIndex++) {
-                    const point = {
-                        x: gridMetrics.offsetX + columnIndex * gridMetrics.cellWidth,
-                        y: gridMetrics.offsetY + rowIndex * gridMetrics.cellHeight,
-                    };
-                    const noise = cellRandom();
-                    const glyphDescriptor = resolveAsciiGlyph({
-                        point,
-                        layout,
-                        palette,
-                        cellWidth: gridMetrics.cellWidth,
-                        cellHeight: gridMetrics.cellHeight,
-                        noise,
-                        timeMs,
-                    });
+                    const glyphDescriptor = glyphGrid[rowIndex][columnIndex];
                     if (!glyphDescriptor) {
                         continue;
                     }
+                    const point = resolveAsciiSampleGridPoint(gridMetrics, columnIndex, rowIndex);
                     context.fillStyle = glyphDescriptor.color;
                     context.fillText(glyphDescriptor.character, point.x, point.y);
                 }
             }
             context.restore();
         },
+        renderTerminalText({ columns, rows, palette, createRandom, timeMs, interaction }) {
+            const staticRandom = createRandom('ascii-octopus-static');
+            const layout = createAsciiOctopusLayout(TERMINAL_ASCII_OCTOPUS_LAYOUT_SIZE, timeMs, createRandom, staticRandom, interaction);
+            return createAsciiOctopusGlyphGrid({
+                sampleGrid: createAsciiTerminalSampleGrid(columns, rows),
+                layout,
+                palette,
+                cellRandom: createRandom('ascii-octopus-cells'),
+                timeMs,
+            });
+        },
     };
+    /**
+     * Resolves the geometry point sampled for one cell of the grid.
+     *
+     * @param sampleGrid Character-cell sampling grid.
+     * @param columnIndex Zero-based cell column.
+     * @param rowIndex Zero-based cell row.
+     * @returns Sampled point in the octopus coordinate space.
+     *
+     * @private helper of `asciiOctopusAvatarVisual`
+     */
+    function resolveAsciiSampleGridPoint(sampleGrid, columnIndex, rowIndex) {
+        return {
+            x: sampleGrid.offsetX + columnIndex * sampleGrid.cellWidth,
+            y: sampleGrid.offsetY + rowIndex * sampleGrid.cellHeight,
+        };
+    }
+    /**
+     * Builds the sampling grid used when the octopus is painted straight into terminal character cells.
+     *
+     * @param columns Available terminal columns.
+     * @param rows Available terminal rows.
+     * @returns Character-cell sampling grid covering the whole octopus coordinate space.
+     *
+     * @private helper of `asciiOctopusAvatarVisual`
+     */
+    function createAsciiTerminalSampleGrid(columns, rows) {
+        const cellWidth = TERMINAL_ASCII_OCTOPUS_LAYOUT_SIZE / columns;
+        const cellHeight = TERMINAL_ASCII_OCTOPUS_LAYOUT_SIZE / rows;
+        return {
+            cellWidth,
+            cellHeight,
+            columnCount: columns,
+            rowCount: rows,
+            offsetX: cellWidth / 2,
+            offsetY: cellHeight / 2,
+        };
+    }
+    /**
+     * Samples the morphing octopus field into one deterministic grid of ASCII glyphs.
+     *
+     * The field is sampled on a low-resolution grid so the shape stays organic while the glyph
+     * layout remains deterministic for the same avatar input. Both the canvas visual and the
+     * terminal visual share this single sampling pass so they always describe the same octopus.
+     *
+     * @param options Sampling grid, prepared octopus layout, palette, per-cell noise, and animation time.
+     * @returns Resolved glyph of every sampled cell, where `null` means an empty cell.
+     *
+     * @private helper of `asciiOctopusAvatarVisual`
+     */
+    function createAsciiOctopusGlyphGrid(options) {
+        const { sampleGrid, layout, palette, cellRandom, timeMs } = options;
+        const glyphGrid = [];
+        for (let rowIndex = 0; rowIndex < sampleGrid.rowCount; rowIndex++) {
+            const glyphRow = [];
+            for (let columnIndex = 0; columnIndex < sampleGrid.columnCount; columnIndex++) {
+                const point = resolveAsciiSampleGridPoint(sampleGrid, columnIndex, rowIndex);
+                const noise = cellRandom();
+                glyphRow.push(resolveAsciiGlyph({
+                    point,
+                    layout,
+                    palette,
+                    cellWidth: sampleGrid.cellWidth,
+                    cellHeight: sampleGrid.cellHeight,
+                    noise,
+                    timeMs,
+                }));
+            }
+            glyphGrid.push(glyphRow);
+        }
+        return glyphGrid;
+    }
     /**
      * Draws the dark terminal-like glow behind the ASCII octopus.
      *
@@ -21760,7 +21846,7 @@
             return agentBookStats.isFile();
         }
         catch (error) {
-            if (isFileNotFoundError$4(error)) {
+            if (isFileNotFoundError$6(error)) {
                 return false;
             }
             throw error;
@@ -21769,7 +21855,7 @@
     /**
      * Returns true when one filesystem error indicates a missing path.
      */
-    function isFileNotFoundError$4(error) {
+    function isFileNotFoundError$6(error) {
         return Boolean(error &&
             typeof error === 'object' &&
             'code' in error &&
@@ -21799,7 +21885,7 @@
             return await promises.readdir(queuedMessagesDirectoryPath, { withFileTypes: true });
         }
         catch (error) {
-            if (isFileNotFoundError$3(error)) {
+            if (isFileNotFoundError$5(error)) {
                 return [];
             }
             throw error;
@@ -21820,7 +21906,7 @@
     /**
      * Returns true when an error is a missing-path filesystem error.
      */
-    function isFileNotFoundError$3(error) {
+    function isFileNotFoundError$5(error) {
         return Boolean(error &&
             typeof error === 'object' &&
             'code' in error &&
@@ -22298,7 +22384,7 @@
                 lastIndexLockState = await readGitIndexLockState(cwd, options.env);
                 if ((lastIndexLockState === null || lastIndexLockState === void 0 ? void 0 : lastIndexLockState.isStale) && !isStaleIndexLockRemoved) {
                     await promises.unlink(lastIndexLockState.path).catch((unlinkError) => {
-                        if (isFileNotFoundError$2(unlinkError)) {
+                        if (isFileNotFoundError$4(unlinkError)) {
                             return;
                         }
                         throw unlinkError;
@@ -22359,7 +22445,7 @@
             };
         }
         catch (error) {
-            if (isFileNotFoundError$2(error)) {
+            if (isFileNotFoundError$4(error)) {
                 return undefined;
             }
             throw error;
@@ -22416,7 +22502,7 @@
     /**
      * Detects missing-file errors while inspecting the lock file.
      */
-    function isFileNotFoundError$2(error) {
+    function isFileNotFoundError$4(error) {
         return Boolean(error &&
             typeof error === 'object' &&
             'code' in error &&
@@ -27312,66 +27398,125 @@
         });
     }
 
+    // Note: [💞] Ignore a discrepancy between file name and entity name
     /**
-     * Default alpha channel value below which a half-cell is rendered as terminal background.
+     * ANSI escape sequence that resets all colors and attributes.
      *
      * @private within the repository
      */
-    const DEFAULT_ALPHA_THRESHOLD = 32;
+    const ANSI_RESET = '\u001b[0m';
     /**
-     * Number of channels per pixel in an RGBA buffer.
+     * Maximum spread between RGB channels for a color to be treated as (nearly) achromatic gray.
      *
      * @private within the repository
      */
-    const RGBA_CHANNEL_COUNT = 4;
+    const ANSI_256_ACHROMATIC_CHANNEL_SPREAD = 12;
     /**
-     * Upper half block character - foreground paints the top pixel, background paints the bottom pixel.
+     * Gray level above which an achromatic color maps to the pure white color-cube entry.
      *
      * @private within the repository
      */
-    const UPPER_HALF_BLOCK = '▀'; // <- ▀
+    const ANSI_256_NEAR_WHITE_GRAY_LEVEL = 246;
     /**
-     * Lower half block character - foreground paints the bottom pixel while the top pixel stays transparent.
+     * Index of pure white inside the 6×6×6 ANSI color cube.
      *
      * @private within the repository
      */
-    const LOWER_HALF_BLOCK = '▄'; // <- ▄
+    const ANSI_256_WHITE_INDEX = 231;
     /**
-     * ANSI escape sequence that resets all colors and attributes.
+     * Brightness of the lightest entry of the ANSI 256 grayscale ramp.
      *
      * @private within the repository
      */
-    const ANSI_RESET = '\u001b[0m';
+    const ANSI_256_GRAYSCALE_RAMP_MAX_LEVEL = 238;
     /**
-     * Maximum spread between RGB channels for a color to be treated as (nearly) achromatic gray.
+     * Number of grayscale ramp steps above its first entry (ANSI indexes 232-255).
      *
      * @private within the repository
      */
-    const ANSI_256_ACHROMATIC_CHANNEL_SPREAD = 12;
+    const ANSI_256_GRAYSCALE_RAMP_INDEX_SPAN = 23;
     /**
-     * Gray level above which an achromatic color maps to the pure white color-cube entry.
+     * Creates the ANSI escape code that sets the foreground color of following characters.
+     *
+     * @param color Color painted onto the characters.
+     * @param colorDepth Color depth supported by the target terminal.
+     * @returns ANSI escape sequence.
      *
      * @private within the repository
      */
-    const ANSI_256_NEAR_WHITE_GRAY_LEVEL = 246;
+    function createAnsiForegroundColorCode(color, colorDepth) {
+        if (colorDepth === 'TRUE_COLOR') {
+            return `\u001b[38;2;${color.red};${color.green};${color.blue}m`;
+        }
+        return `\u001b[38;5;${mapColorToAnsi256(color)}m`;
+    }
     /**
-     * Index of pure white inside the 6×6×6 ANSI color cube.
+     * Creates the ANSI escape code that sets the background color of following characters.
+     *
+     * @param color Color painted behind the characters.
+     * @param colorDepth Color depth supported by the target terminal.
+     * @returns ANSI escape sequence.
      *
      * @private within the repository
      */
-    const ANSI_256_WHITE_INDEX = 231;
+    function createAnsiBackgroundColorCode(color, colorDepth) {
+        if (colorDepth === 'TRUE_COLOR') {
+            return `\u001b[48;2;${color.red};${color.green};${color.blue}m`;
+        }
+        return `\u001b[48;5;${mapColorToAnsi256(color)}m`;
+    }
     /**
-     * Brightness of the lightest entry of the ANSI 256 grayscale ramp.
+     * 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 `createAnsiForegroundColorCode` and `createAnsiBackgroundColorCode`
+     */
+    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 alpha channel value below which a cell is rendered as terminal background.
      *
      * @private within the repository
      */
-    const ANSI_256_GRAYSCALE_RAMP_MAX_LEVEL = 238;
+    const DEFAULT_ALPHA_THRESHOLD = 32;
     /**
-     * Number of grayscale ramp steps above its first entry (ANSI indexes 232-255).
+     * Number of channels per pixel in an RGBA buffer.
      *
      * @private within the repository
      */
-    const ANSI_256_GRAYSCALE_RAMP_INDEX_SPAN = 23;
+    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 = '▄'; // <- ▄
     /**
      * Converts raw RGBA image pixels into colored ASCII art for ANSI terminals.
      *
@@ -27420,17 +27565,17 @@
                 let nextBackgroundCode;
                 if (topHalfColor.isOpaque && bottomHalfColor.isOpaque) {
                     character = UPPER_HALF_BLOCK;
-                    nextForegroundCode = createForegroundColorCode(topHalfColor, colorDepth);
-                    nextBackgroundCode = createBackgroundColorCode(bottomHalfColor, colorDepth);
+                    nextForegroundCode = createAnsiForegroundColorCode(topHalfColor, colorDepth);
+                    nextBackgroundCode = createAnsiBackgroundColorCode(bottomHalfColor, colorDepth);
                 }
                 else if (topHalfColor.isOpaque) {
                     character = UPPER_HALF_BLOCK;
-                    nextForegroundCode = createForegroundColorCode(topHalfColor, colorDepth);
+                    nextForegroundCode = createAnsiForegroundColorCode(topHalfColor, colorDepth);
                     nextBackgroundCode = undefined;
                 }
                 else if (bottomHalfColor.isOpaque) {
                     character = LOWER_HALF_BLOCK;
-                    nextForegroundCode = createForegroundColorCode(bottomHalfColor, colorDepth);
+                    nextForegroundCode = createAnsiForegroundColorCode(bottomHalfColor, colorDepth);
                     nextBackgroundCode = undefined;
                 }
                 else {
@@ -27505,55 +27650,6 @@
             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.
@@ -27683,6 +27779,143 @@
         `));
     }
 
+    // Note: [💞] Ignore a discrepancy between file name and entity name
+    /**
+     * Height of one terminal character cell relative to its width.
+     *
+     * Terminal fonts are roughly twice as tall as they are wide, so a square avatar needs
+     * twice as many columns as rows to keep its proportions.
+     *
+     * @private within the repository
+     */
+    const TERMINAL_CHARACTER_CELL_ASPECT_RATIO = 2;
+    /**
+     * Renders one frame of a character-based avatar visual straight into terminal character cells.
+     *
+     * Visuals which are themselves made of characters, for example `AsciiOctopus`, lose their identity
+     * when they are rasterized onto a canvas and converted back into half-block ASCII art - every glyph
+     * is averaged away into a colored blob. Such visuals expose `renderTerminalText`, which paints the
+     * terminal grid directly and is used instead of the raster pipeline.
+     *
+     * The square avatar is centered inside the requested grid the same way `renderAvatarVisualAsciiArt`
+     * centers the avatar canvas inside a wider terminal frame.
+     *
+     * @param options Avatar identity, visual selection, and output grid size.
+     * @returns Grid of `rows` rows of `columns` cells, or `null` when the visual has no terminal renderer.
+     *
+     * @private within the repository
+     */
+    function renderAvatarVisualTerminalTextGrid(options) {
+        const resolvedRenderDefinition = options.resolvedAvatarRenderDefinition ||
+            resolveAvatarRenderDefinition({
+                avatarDefinition: options.avatarDefinition,
+                visualId: options.visualId,
+                surface: options.surface,
+            });
+        const { renderTerminalText } = resolvedRenderDefinition.avatarVisual;
+        if (renderTerminalText === undefined) {
+            return null;
+        }
+        const avatarColumnCount = Math.min(options.columns, options.rows * TERMINAL_CHARACTER_CELL_ASPECT_RATIO);
+        const avatarRowCount = Math.min(options.rows, Math.round(options.columns / TERMINAL_CHARACTER_CELL_ASPECT_RATIO));
+        if (avatarColumnCount <= 0 || avatarRowCount <= 0) {
+            return null;
+        }
+        const avatarGrid = renderTerminalText({
+            columns: avatarColumnCount,
+            rows: avatarRowCount,
+            timeMs: options.timeMs,
+            avatarDefinition: resolvedRenderDefinition.avatarDefinition,
+            palette: resolvedRenderDefinition.palette,
+            createRandom: resolvedRenderDefinition.createRandom,
+            interaction: createIdleAvatarInteractionState(),
+        });
+        return centerAvatarVisualTerminalTextGrid(avatarGrid, options.columns, options.rows);
+    }
+    /**
+     * Renders one frame of a character-based avatar visual into ANSI-colored terminal lines.
+     *
+     * @param options Avatar identity, visual selection, output grid size, and ANSI color depth.
+     * @returns One ANSI-colored string per output row, or `null` when the visual has no terminal renderer.
+     *
+     * @private within the repository
+     */
+    function renderAvatarVisualTerminalTextLines(options) {
+        const terminalTextGrid = renderAvatarVisualTerminalTextGrid(options);
+        if (terminalTextGrid === null) {
+            return null;
+        }
+        return terminalTextGrid.map((terminalTextRow) => buildAvatarVisualTerminalTextLine(terminalTextRow, options.colorDepth || 'TRUE_COLOR'));
+    }
+    /**
+     * Converts one avatar cell color into the opaque terminal color it is painted with.
+     *
+     * Terminal cells cannot be blended, so the cell alpha is composited onto the dark terminal
+     * background and fully transparent cells keep the terminal background instead.
+     *
+     * @param color Cell color as a CSS color string, optionally with an alpha channel.
+     * @returns Opaque terminal color or `null` when the cell should stay empty.
+     *
+     * @private helper of `renderAvatarVisualTerminalTextLines`
+     */
+    function resolveAvatarVisualTerminalTextColor(color) {
+        const parsedColor = Color.fromSafe(color);
+        if (parsedColor.alpha < DEFAULT_ALPHA_THRESHOLD) {
+            return null;
+        }
+        const opacity = parsedColor.alpha / 255;
+        return {
+            red: Math.round(parsedColor.red * opacity),
+            green: Math.round(parsedColor.green * opacity),
+            blue: Math.round(parsedColor.blue * opacity),
+        };
+    }
+    /**
+     * Places the square avatar grid into the center of the requested terminal grid.
+     *
+     * @private helper of `renderAvatarVisualTerminalTextGrid`
+     */
+    function centerAvatarVisualTerminalTextGrid(avatarGrid, columns, rows) {
+        var _a;
+        const avatarRowCount = avatarGrid.length;
+        const avatarColumnCount = ((_a = avatarGrid[0]) === null || _a === void 0 ? void 0 : _a.length) || 0;
+        const leftCellCount = Math.floor((columns - avatarColumnCount) / 2);
+        const topRowCount = Math.floor((rows - avatarRowCount) / 2);
+        return Array.from({ length: rows }, (_, rowIndex) => {
+            const avatarRow = avatarGrid[rowIndex - topRowCount];
+            return Array.from({ length: columns }, (__, columnIndex) => (avatarRow === null || avatarRow === void 0 ? void 0 : avatarRow[columnIndex - leftCellCount]) || null);
+        });
+    }
+    /**
+     * Builds one ANSI-colored terminal line from resolved character cells.
+     *
+     * @private helper of `renderAvatarVisualTerminalTextLines`
+     */
+    function buildAvatarVisualTerminalTextLine(terminalTextRow, colorDepth) {
+        let line = '';
+        let currentForegroundCode = undefined;
+        for (const terminalTextCell of terminalTextRow) {
+            const cellColor = terminalTextCell === null ? null : resolveAvatarVisualTerminalTextColor(terminalTextCell.color);
+            const nextForegroundCode = cellColor === null ? undefined : createAnsiForegroundColorCode(cellColor, colorDepth);
+            if (nextForegroundCode !== currentForegroundCode) {
+                // Note: A reset is required whenever a previously set color must be cleared,
+                //       otherwise a stale color would bleed into the following empty cells.
+                if (nextForegroundCode === undefined) {
+                    line += ANSI_RESET;
+                }
+                else {
+                    line += nextForegroundCode;
+                }
+                currentForegroundCode = nextForegroundCode;
+            }
+            line += cellColor === null || terminalTextCell === null ? ' ' : terminalTextCell.character;
+        }
+        if (currentForegroundCode !== undefined) {
+            line += ANSI_RESET;
+        }
+        return line;
+    }
+
     /**
      * Default built-in avatar visual used when an agent does not define `META IMAGE`, `META AVATAR`, or `META VISUAL`.
      *
@@ -27801,9 +28034,30 @@
     /**
      * Renders one terminal avatar frame through the shared avatar-to-ASCII pipeline.
      *
+     * Visuals which are made of characters themselves, for example `AsciiOctopus`, paint the terminal
+     * character grid directly, because rasterizing them into half-block ASCII art averages every glyph
+     * away and makes them indistinguishable from the other blob-shaped visuals.
+     *
      * @private shared helper for terminal avatar rendering
      */
     function renderTerminalAgentAvatarVisualFrame(options) {
+        const terminalTextLines = renderAvatarVisualTerminalTextLines({
+            avatarDefinition: options.avatarDefinition,
+            visualId: options.avatarVisualId,
+            surface: 'transparent',
+            columns: TERMINAL_AGENT_AVATAR_VISUAL_COLUMNS,
+            rows: TERMINAL_AGENT_AVATAR_VISUAL_ROWS,
+            colorDepth: options.colorDepth,
+            timeMs: options.animationTimeMs,
+            resolvedAvatarRenderDefinition: options.resolvedAvatarRenderDefinition,
+        });
+        if (terminalTextLines !== null) {
+            return terminalTextLines;
+        }
+        if (options.createCanvas === undefined) {
+            // Note: A pixel-based visual cannot be rasterized without a canvas, so the caller keeps its default banner
+            return [];
+        }
         return renderAvatarVisualAsciiArt({
             avatarDefinition: options.avatarDefinition,
             visualId: options.avatarVisualId,
@@ -28056,6 +28310,134 @@
         return `${count} prompt run${count === 1 ? '' : 's'}`;
     }
 
+    /**
+     * ANSI sequence that clears the current terminal row.
+     *
+     * @private internal constant of coder run UI
+     */
+    const CLEAR_CURRENT_LINE = '\x1b[2K';
+    /**
+     * ANSI control character that moves the cursor to the start of its current row.
+     *
+     * @private internal constant of coder run UI
+     */
+    const MOVE_CURSOR_TO_LINE_START = '\r';
+    /**
+     * Builds one atomic ANSI update that changes the displayed coder-run terminal frame.
+     *
+     * A change in frame height requires a full rewrite to reserve or clear rows correctly. Frames with
+     * the same height only rewrite contiguous groups of changed rows, returning to the frame bottom
+     * between groups so each group can be assembled into the same output payload safely.
+     *
+     * @returns One terminal output payload, or `undefined` when the frame is already up to date.
+     *
+     * @private internal utility of coder run UI
+     */
+    function buildCoderRunUiTerminalFrameUpdate(options) {
+        const { previousFrameLines, nextFrameLines } = options;
+        if (previousFrameLines.length === 0 && nextFrameLines.length === 0) {
+            return undefined;
+        }
+        if (previousFrameLines.length === 0 || previousFrameLines.length !== nextFrameLines.length) {
+            return buildFullCoderRunUiTerminalFrameUpdate(previousFrameLines, nextFrameLines);
+        }
+        return buildChangedCoderRunUiTerminalFrameUpdate(previousFrameLines, nextFrameLines);
+    }
+    /**
+     * Builds an ANSI update which completely rewrites the reserved terminal frame area.
+     *
+     * @private helper of `buildCoderRunUiTerminalFrameUpdate`
+     */
+    function buildFullCoderRunUiTerminalFrameUpdate(previousFrameLines, nextFrameLines) {
+        var _a;
+        const previousFrameLineCount = previousFrameLines.length;
+        const lineCountToRewrite = Math.max(previousFrameLineCount, nextFrameLines.length);
+        const outputParts = [];
+        if (previousFrameLineCount > 1) {
+            outputParts.push(moveCursorUp(previousFrameLineCount - 1));
+        }
+        for (let lineIndex = 0; lineIndex < lineCountToRewrite; lineIndex++) {
+            outputParts.push(CLEAR_CURRENT_LINE, MOVE_CURSOR_TO_LINE_START, (_a = nextFrameLines[lineIndex]) !== null && _a !== void 0 ? _a : '');
+            if (lineIndex < lineCountToRewrite - 1) {
+                outputParts.push('\n');
+            }
+        }
+        const clearedTrailingLineCount = lineCountToRewrite - nextFrameLines.length;
+        if (clearedTrailingLineCount > 0) {
+            outputParts.push(moveCursorUp(clearedTrailingLineCount));
+        }
+        outputParts.push(MOVE_CURSOR_TO_LINE_START);
+        return outputParts.join('');
+    }
+    /**
+     * Builds an ANSI update that rewrites only contiguous groups of rows which changed.
+     *
+     * @private helper of `buildCoderRunUiTerminalFrameUpdate`
+     */
+    function buildChangedCoderRunUiTerminalFrameUpdate(previousFrameLines, nextFrameLines) {
+        const outputParts = [];
+        let lineIndex = 0;
+        while (lineIndex < nextFrameLines.length) {
+            if (previousFrameLines[lineIndex] === nextFrameLines[lineIndex]) {
+                lineIndex++;
+                continue;
+            }
+            const changedRangeStartLineIndex = lineIndex;
+            while (lineIndex + 1 < nextFrameLines.length &&
+                previousFrameLines[lineIndex + 1] !== nextFrameLines[lineIndex + 1]) {
+                lineIndex++;
+            }
+            appendChangedCoderRunUiTerminalFrameRange({
+                outputParts,
+                frameLineCount: nextFrameLines.length,
+                changedRangeStartLineIndex,
+                changedRangeEndLineIndex: lineIndex,
+                nextFrameLines,
+            });
+            lineIndex++;
+        }
+        return outputParts.length === 0 ? undefined : outputParts.join('');
+    }
+    /**
+     * Appends the cursor movements and row rewrites for one contiguous changed frame range.
+     *
+     * @private helper of `buildChangedCoderRunUiTerminalFrameUpdate`
+     */
+    function appendChangedCoderRunUiTerminalFrameRange(options) {
+        const { outputParts, frameLineCount, changedRangeStartLineIndex, changedRangeEndLineIndex, nextFrameLines } = options;
+        const linesUpFromFrameBottom = frameLineCount - 1 - changedRangeStartLineIndex;
+        if (linesUpFromFrameBottom > 0) {
+            outputParts.push(moveCursorUp(linesUpFromFrameBottom));
+        }
+        for (let lineIndex = changedRangeStartLineIndex; lineIndex <= changedRangeEndLineIndex; lineIndex++) {
+            outputParts.push(CLEAR_CURRENT_LINE, MOVE_CURSOR_TO_LINE_START, nextFrameLines[lineIndex]);
+            if (lineIndex < changedRangeEndLineIndex) {
+                outputParts.push('\n');
+            }
+        }
+        const linesDownToFrameBottom = frameLineCount - 1 - changedRangeEndLineIndex;
+        if (linesDownToFrameBottom > 0) {
+            outputParts.push(moveCursorDown(linesDownToFrameBottom));
+        }
+        outputParts.push(MOVE_CURSOR_TO_LINE_START);
+    }
+    /**
+     * Builds an ANSI sequence which moves the terminal cursor up by a positive number of rows.
+     *
+     * @private helper of `buildCoderRunUiTerminalFrameUpdate`
+     */
+    function moveCursorUp(lineCount) {
+        return `\x1b[${lineCount}A`;
+    }
+    /**
+     * Builds an ANSI sequence which moves the terminal cursor down by a positive number of rows.
+     *
+     * @private helper of `buildCoderRunUiTerminalFrameUpdate`
+     */
+    function moveCursorDown(lineCount) {
+        return `\x1b[${lineCount}B`;
+    }
+
     /**
      * Calendar formats used when displaying the estimated completion time.
      *
@@ -28540,58 +28922,6 @@
                 scheduleRender();
             }, autoRefreshInterval);
         }
-        /**
-         * Moves the cursor relative to the bottom of the current frame and rewrites one line in place.
-         */
-        function rewriteFrameLine(frameLineCount, lineIndex, line) {
-            const linesUpFromBottom = Math.max(0, frameLineCount - 1 - lineIndex);
-            if (linesUpFromBottom > 0) {
-                process.stdout.write(`\x1b[${linesUpFromBottom}A`);
-            }
-            readline.clearLine(process.stdout, 0);
-            readline.cursorTo(process.stdout, 0);
-            process.stdout.write(line);
-            readline.cursorTo(process.stdout, 0);
-            if (linesUpFromBottom > 0) {
-                process.stdout.write(`\x1b[${linesUpFromBottom}B`);
-                readline.cursorTo(process.stdout, 0);
-            }
-        }
-        /**
-         * Fully rewrites the reserved frame area.
-         */
-        function renderFullFrame(lines) {
-            var _a;
-            const previousFrameLineCount = previousFrameLines.length;
-            const linesToRewriteCount = Math.max(previousFrameLineCount, lines.length);
-            if (previousFrameLineCount > 1) {
-                process.stdout.write(`\x1b[${previousFrameLineCount - 1}A`);
-            }
-            for (let i = 0; i < linesToRewriteCount; i++) {
-                readline.clearLine(process.stdout, 0);
-                readline.cursorTo(process.stdout, 0);
-                process.stdout.write((_a = lines[i]) !== null && _a !== void 0 ? _a : '');
-                if (i < linesToRewriteCount - 1) {
-                    process.stdout.write('\n');
-                }
-            }
-            const clearedTrailingLines = linesToRewriteCount - lines.length;
-            if (clearedTrailingLines > 0) {
-                process.stdout.write(`\x1b[${clearedTrailingLines}A`);
-            }
-            readline.cursorTo(process.stdout, 0);
-        }
-        /**
-         * Updates only the frame rows whose visible content changed.
-         */
-        function renderChangedLines(lines) {
-            for (let i = 0; i < lines.length; i++) {
-                if (previousFrameLines[i] === lines[i]) {
-                    continue;
-                }
-                rewriteFrameLine(lines.length, i, lines[i]);
-            }
-        }
         /**
          * Builds the current frame snapshot from the latest state.
          */
@@ -28633,11 +28963,12 @@
             isRendering = true;
             try {
                 const lines = buildFrameLines();
-                if (previousFrameLines.length === 0 || previousFrameLines.length !== lines.length) {
-                    renderFullFrame(lines);
-                }
-                else {
-                    renderChangedLines(lines);
+                const terminalFrameUpdate = buildCoderRunUiTerminalFrameUpdate({
+                    previousFrameLines,
+                    nextFrameLines: lines,
+                });
+                if (terminalFrameUpdate !== undefined) {
+                    process.stdout.write(terminalFrameUpdate);
                 }
                 previousFrameLines = [...lines];
                 spinnerFrame = (spinnerFrame + 1) % SPINNER_FRAMES.length;
@@ -29028,12 +29359,102 @@
 
     /**
      * Git commands used to list changed and untracked files in the working tree.
+     *
+     * Note: None of them ever lists a file ignored by `.gitignore`, so a path taken from here can always be staged.
+     * Note: `--no-renames` is used because a detected rename would be reported as its destination path only, which
+     *       would leave the source path of a moved file out of the commit.
      */
     const GIT_CHANGED_FILE_COMMANDS = [
-        'git diff --name-only --',
-        'git diff --name-only --cached --',
+        'git diff --name-only --no-renames --',
+        'git diff --name-only --no-renames --cached --',
         'git ls-files --others --exclude-standard',
     ];
+    /**
+     * Captures hashes for files that are dirty before one operation starts.
+     */
+    async function captureWorkingTreeChangesSnapshot(projectPath) {
+        const changedFiles = await listWorkingTreeChangedFiles(projectPath);
+        const changedFileHashes = new Map();
+        for (const relativePath of changedFiles) {
+            changedFileHashes.set(relativePath, await readWorkingTreeFileHash(projectPath, relativePath));
+        }
+        return { changedFileHashes };
+    }
+    /**
+     * Lists the repository-relative paths which really changed since the snapshot was taken.
+     *
+     * A file which was already dirty before and was not touched afterwards is not listed, so the result contains
+     * exactly the files changed by the operation which the snapshot wraps.
+     */
+    async function listFilesChangedSinceSnapshot(projectPath, snapshot) {
+        const changedFiles = await listWorkingTreeChangedFiles(projectPath);
+        const changedFilesSinceSnapshot = [];
+        for (const relativePath of changedFiles) {
+            const currentFileHash = await readWorkingTreeFileHash(projectPath, relativePath);
+            const hashBeforeOperation = snapshot.changedFileHashes.get(relativePath);
+            const wasDirtyBeforeOperation = snapshot.changedFileHashes.has(relativePath);
+            if (wasDirtyBeforeOperation && hashBeforeOperation === currentFileHash) {
+                continue;
+            }
+            changedFilesSinceSnapshot.push(relativePath);
+        }
+        return changedFilesSinceSnapshot;
+    }
+    /**
+     * Lists dirty tracked files and untracked files in the working tree.
+     */
+    async function listWorkingTreeChangedFiles(projectPath) {
+        const changedFiles = new Set();
+        for (const command of GIT_CHANGED_FILE_COMMANDS) {
+            const output = await $execCommand({
+                command,
+                cwd: projectPath,
+                isVerbose: false,
+            });
+            for (const filePath of output.split('\n').map(normalizeGitFilePath).filter(Boolean)) {
+                changedFiles.add(filePath);
+            }
+        }
+        return [...changedFiles.values()];
+    }
+    /**
+     * Reads the content hash of one repository-relative working tree file.
+     *
+     * @returns Hash of a regular file, otherwise `null` for a deleted or non-regular file.
+     */
+    async function readWorkingTreeFileHash(projectPath, relativePath) {
+        try {
+            const absolutePath = path.resolve(projectPath, relativePath);
+            const fileStats = await promises.stat(absolutePath);
+            if (!fileStats.isFile()) {
+                return null;
+            }
+            const content = await promises.readFile(absolutePath);
+            return crypto.createHash('sha1').update(content).digest('hex');
+        }
+        catch (error) {
+            if (isFileNotFoundError$3(error)) {
+                return null;
+            }
+            throw error;
+        }
+    }
+    /**
+     * Normalizes Git output paths for internal matching.
+     */
+    function normalizeGitFilePath(filePath) {
+        return filePath.trim().replace(/\\/g, '/');
+    }
+    /**
+     * Returns true when an error is a missing-file filesystem error.
+     */
+    function isFileNotFoundError$3(error) {
+        return Boolean(error &&
+            typeof error === 'object' &&
+            'code' in error &&
+            (error.code === 'ENOENT' || error.code === 'ENOTDIR'));
+    }
+
     /**
      * File extensions that should always be treated as binary.
      */
@@ -29081,34 +29502,20 @@
      * Captures hashes for files that are dirty before a coding round starts.
      */
     async function captureChangedFilesSnapshot(projectPath) {
-        const changedFiles = await listWorkingTreeChangedFiles(projectPath);
-        const changedFileHashes = new Map();
-        for (const relativePath of changedFiles) {
-            const absolutePath = resolveProjectPath(projectPath, relativePath);
-            const fileHash = await readFileHashIfRegularFile(absolutePath);
-            if (fileHash) {
-                changedFileHashes.set(relativePath, fileHash);
-            }
-        }
-        return { changedFileHashes };
+        return captureWorkingTreeChangesSnapshot(projectPath);
     }
     /**
      * Normalizes CRLF to LF only in files that changed since the captured snapshot.
      */
     async function normalizeLineEndingsInFilesChangedSinceSnapshot(options) {
-        const changedFiles = await listWorkingTreeChangedFiles(options.projectPath);
+        const changedFiles = await listFilesChangedSinceSnapshot(options.projectPath, options.snapshot);
         let scannedFiles = 0;
         let normalizedFiles = 0;
         let skippedBinaryFiles = 0;
         for (const relativePath of changedFiles) {
             const absolutePath = resolveProjectPath(options.projectPath, relativePath);
-            const currentFileHash = await readFileHashIfRegularFile(absolutePath);
-            if (!currentFileHash) {
-                continue;
-            }
-            const hashBeforeRound = options.snapshot.changedFileHashes.get(relativePath);
-            const hasChangedInRound = hashBeforeRound === undefined || hashBeforeRound !== currentFileHash;
-            if (!hasChangedInRound) {
+            // Note: A file deleted or replaced by a directory during the round has no content to normalize
+            if (!(await isRegularFile(absolutePath))) {
                 continue;
             }
             scannedFiles++;
@@ -29134,29 +29541,6 @@
             skippedBinaryFiles,
         };
     }
-    /**
-     * Lists dirty tracked files and untracked files in the working tree.
-     */
-    async function listWorkingTreeChangedFiles(projectPath) {
-        const changedFiles = new Set();
-        for (const command of GIT_CHANGED_FILE_COMMANDS) {
-            const output = await $execCommand({
-                command,
-                cwd: projectPath,
-                isVerbose: false,
-            });
-            for (const filePath of output.split('\n').map(normalizeGitFilePath).filter(Boolean)) {
-                changedFiles.add(filePath);
-            }
-        }
-        return [...changedFiles.values()];
-    }
-    /**
-     * Normalizes Git output paths for internal matching.
-     */
-    function normalizeGitFilePath(filePath) {
-        return filePath.trim().replace(/\\/g, '/');
-    }
     /**
      * Resolves a repository-relative file path to an absolute path.
      */
@@ -29164,33 +29548,16 @@
         return path.resolve(projectPath, relativePath);
     }
     /**
-     * Reads file hash for a regular file and returns undefined for non-files/missing files.
+     * Checks whether a path exists and is a regular file.
      */
-    async function readFileHashIfRegularFile(path) {
+    async function isRegularFile(path) {
         try {
-            const fileStats = await promises.stat(path);
-            if (!fileStats.isFile()) {
-                return undefined;
-            }
-            const content = await promises.readFile(path);
-            return crypto.createHash('sha1').update(content).digest('hex');
+            return (await promises.stat(path)).isFile();
         }
-        catch (error) {
-            if (isFileNotFoundError$1(error)) {
-                return undefined;
-            }
-            throw error;
+        catch (_a) {
+            return false;
         }
     }
-    /**
-     * Returns true when an error is a missing-file filesystem error.
-     */
-    function isFileNotFoundError$1(error) {
-        return Boolean(error &&
-            typeof error === 'object' &&
-            'code' in error &&
-            ((error.code === 'ENOENT') || error.code === 'ENOTDIR'));
-    }
     /**
      * Detects binary files from extension.
      */
@@ -29380,7 +29747,7 @@
     /**
      * Commits staged changes with the provided message using the dedicated coding-agent identity when configured,
      * otherwise falls back to the default Git configuration. Remote pushing is opt-in via `options.autoPush`,
-     * `options.includePaths` can restrict staging, `options.onlyPaths` can restrict the commit pathspec,
+     * `options.relevantPaths` restricts both the staging and the commit to the files of the current operation,
      * `options.excludePaths` can keep temporary artifacts out of the created commit and
      * `options.isEmptyCommitAllowed` keeps a round without any file change from failing.
      *
@@ -29396,15 +29763,19 @@
         try {
             const agentEnv = buildAgentGitEnv();
             const signingFlag = buildAgentGitSigningFlag();
-            await stageCommitChanges(projectPath, agentEnv, options === null || options === void 0 ? void 0 : options.includePaths, [
+            const excludedGitPaths = await normalizeExcludedGitPaths(projectPath, [
                 commitMessagePath,
                 ...((_a = options === null || options === void 0 ? void 0 : options.excludePaths) !== null && _a !== void 0 ? _a : []),
             ]);
+            // Note: An excluded path must be dropped from the relevant paths as well, because a commit restricted by
+            //       a pathspec commits the working tree content of those paths and would ignore unstaging them
+            const relevantPaths = excludeGitPaths(options === null || options === void 0 ? void 0 : options.relevantPaths, excludedGitPaths);
+            await stageCommitChanges(projectPath, agentEnv, relevantPaths, excludedGitPaths);
             await runGitCommand({
                 command: buildGitCommitCommand({
                     commitMessagePath,
                     signingFlag,
-                    onlyPaths: options === null || options === void 0 ? void 0 : options.onlyPaths,
+                    relevantPaths,
                     isEmptyCommitAllowed: options === null || options === void 0 ? void 0 : options.isEmptyCommitAllowed,
                 }),
                 cwd: projectPath,
@@ -29419,15 +29790,17 @@
         }
     }
     /**
-     * Stages repository changes and optionally unstages temporary files that should not end up inside the commit.
+     * Stages the relevant repository changes and unstages temporary files that should not end up inside the commit.
      */
-    async function stageCommitChanges(projectPath, agentEnv, includePaths, excludePaths) {
-        await runGitCommand({
-            command: buildGitAddCommand(includePaths),
-            cwd: projectPath,
-            env: agentEnv,
-        });
-        const excludedGitPaths = await normalizeExcludedGitPaths(projectPath, excludePaths);
+    async function stageCommitChanges(projectPath, agentEnv, relevantPaths, excludedGitPaths) {
+        // Note: An operation which changed nothing relevant has nothing to stage
+        if (relevantPaths === undefined || relevantPaths.length > 0) {
+            await runGitCommand({
+                command: buildGitAddCommand(relevantPaths),
+                cwd: projectPath,
+                env: agentEnv,
+            });
+        }
         if (excludedGitPaths.length === 0) {
             return;
         }
@@ -29439,13 +29812,29 @@
         });
     }
     /**
-     * Builds the git add command for either the whole tree or a focused set of paths.
+     * Builds the git add command for either the whole tree or the relevant paths of the current operation.
      */
-    function buildGitAddCommand(includePaths) {
-        if (!includePaths || includePaths.length === 0) {
+    function buildGitAddCommand(relevantPaths) {
+        if (!relevantPaths || relevantPaths.length === 0) {
             return 'git add .';
         }
-        return `git add --all -- ${includePaths.map(quoteShellPath$1).join(' ')}`;
+        return `git add --all -- ${relevantPaths.map(quoteShellPath$1).join(' ')}`;
+    }
+    /**
+     * Removes the excluded repository paths from the relevant paths of the current operation.
+     */
+    function excludeGitPaths(relevantPaths, excludedGitPaths) {
+        if (relevantPaths === undefined || excludedGitPaths.length === 0) {
+            return relevantPaths;
+        }
+        const excludedGitPathSet = new Set(excludedGitPaths);
+        return relevantPaths.filter((relevantPath) => !excludedGitPathSet.has(normalizeGitPathSeparators(relevantPath)));
+    }
+    /**
+     * Normalizes path separators so a relevant path can be matched against a repository-relative Git path.
+     */
+    function normalizeGitPathSeparators(path) {
+        return path.replace(/\\/gu, '/');
     }
     /**
      * Converts excluded filesystem paths into unique repository-relative Git paths.
@@ -29616,8 +30005,8 @@
             commandParts.push('--allow-empty');
         }
         commandParts.push(`--file "${options.commitMessagePath}"`);
-        if (options.onlyPaths && options.onlyPaths.length > 0) {
-            commandParts.push('--', ...options.onlyPaths.map(quoteShellPath$1));
+        if (options.relevantPaths && options.relevantPaths.length > 0) {
+            commandParts.push('--', ...options.relevantPaths.map(quoteShellPath$1));
         }
         return commandParts.join(' ');
     }
@@ -30107,6 +30496,140 @@
     `);
     }
 
+    // Note: [💞] This file defines the shared TEAM workspace convention rather than one standalone entity.
+    /**
+     * Relative directory for an active TEAM conversation workspace.
+     *
+     * @private internal convention shared by the Agents Server and agent-folder runner
+     */
+    const AGENT_TEAM_CONVERSATIONS_DIRECTORY_PATH = path.join(AGENT_MESSAGES_DIRECTORY_PATH, 'team');
+    /**
+     * Relative directory where completed TEAM conversation transcripts are retained.
+     *
+     * @private internal convention shared by the Agents Server and agent-folder runner
+     */
+    const AGENT_FINISHED_TEAM_CONVERSATIONS_DIRECTORY_PATH = path.join(AGENT_FINISHED_MESSAGES_DIRECTORY_PATH, 'team');
+    /**
+     * Name of the JSON manifest that describes one TEAM conversation workspace.
+     *
+     * @private internal convention shared by the Agents Server and agent-folder runner
+     */
+    const AGENT_TEAM_CONVERSATION_MANIFEST_FILE_NAME = 'team.json';
+    /**
+     * Name of the read-only teammate-source directory inside one TEAM workspace.
+     *
+     * @private internal convention shared by the Agents Server and agent-folder runner
+     */
+    const AGENT_TEAMMATE_SOURCES_DIRECTORY_NAME = 'teammates';
+    /**
+     * Creates the stable directory name that belongs to one queued `.book` message.
+     *
+     * @private internal convention shared by the Agents Server and agent-folder runner
+     */
+    function createAgentTeamConversationWorkspaceDirectoryName(messageFileName) {
+        const rawBaseName = path.basename(messageFileName).replace(/\.book$/iu, '');
+        const normalizedBaseName = rawBaseName.replace(/[^A-Za-z0-9._-]+/gu, '-').replace(/^[._-]+|[._-]+$/gu, '');
+        return normalizedBaseName || 'message';
+    }
+    /**
+     * Creates the relative active workspace path for one queued message.
+     *
+     * @private internal convention shared by the Agents Server and agent-folder runner
+     */
+    function createAgentTeamConversationWorkspacePath(messageFileName) {
+        return path.join(AGENT_TEAM_CONVERSATIONS_DIRECTORY_PATH, createAgentTeamConversationWorkspaceDirectoryName(messageFileName));
+    }
+    /**
+     * Creates the relative completed-workspace path for one queued message.
+     *
+     * @private internal convention shared by the Agents Server and agent-folder runner
+     */
+    function createFinishedAgentTeamConversationWorkspacePath(messageFileName) {
+        return path.join(AGENT_FINISHED_TEAM_CONVERSATIONS_DIRECTORY_PATH, createAgentTeamConversationWorkspaceDirectoryName(messageFileName));
+    }
+    /**
+     * Checks whether unknown JSON has the minimum shape required for a TEAM workspace manifest.
+     *
+     * @private internal convention shared by the Agents Server and agent-folder runner
+     */
+    function isAgentTeamConversationWorkspaceManifest(value) {
+        if (!value || typeof value !== 'object') {
+            return false;
+        }
+        const manifest = value;
+        if (manifest.version !== 1 ||
+            !isPrimaryAgent(manifest.primaryAgent) ||
+            !Array.isArray(manifest.teammates) ||
+            !manifest.teammates.every(isTeammate)) {
+            return false;
+        }
+        return true;
+    }
+    /**
+     * Checks the primary-agent part of an untrusted manifest.
+     *
+     * @private internal utility of `isAgentTeamConversationWorkspaceManifest`
+     */
+    function isPrimaryAgent(value) {
+        return Boolean(value &&
+            typeof value === 'object' &&
+            typeof value.permanentId === 'string' &&
+            typeof value.agentName === 'string');
+    }
+    /**
+     * Checks one teammate part of an untrusted manifest.
+     *
+     * @private internal utility of `isAgentTeamConversationWorkspaceManifest`
+     */
+    function isTeammate(value) {
+        return Boolean(value &&
+            typeof value === 'object' &&
+            typeof value.permanentId === 'string' &&
+            typeof value.agentName === 'string' &&
+            typeof value.url === 'string' &&
+            typeof value.instructions === 'string' &&
+            typeof value.sourceFileName === 'string');
+    }
+
+    /**
+     * Builds the optional single-run TEAM consultation instructions for a coding harness.
+     */
+    function buildAgentTeamPromptSection(workspace) {
+        if (!workspace || workspace.manifest.teammates.length === 0) {
+            return '';
+        }
+        const teammateSections = workspace.manifest.teammates.map((teammate) => {
+            const sourcePath = toPromptPath(path.join(workspace.relativeWorkspacePath, AGENT_TEAMMATE_SOURCES_DIRECTORY_NAME, teammate.sourceFileName));
+            const transcriptPath = toPromptPath(path.join(workspace.relativeWorkspacePath, `${teammate.permanentId}--01.book`));
+            const instructions = teammate.instructions.trim() || 'No additional TEAM instructions were provided.';
+            return _spaceTrim.spaceTrim(`
+            -   ${teammate.agentName}
+                -   TEAM instructions: ${instructions}
+                -   Read-only source: \`${sourcePath}\`
+                -   First transcript file: \`${transcriptPath}\`
+        `);
+        });
+        return _spaceTrim.spaceTrim((block) => `
+            ## Team consultations
+
+            The following teammates are available for this user turn:
+
+            ${block(teammateSections.join('\n'))}
+
+            -   The underlying coding harness is already executing this turn **exactly once**. Never start, queue, or invoke another coding harness, agent runner, or \`ptbk\` command to consult a teammate.
+            -   The primary agent remains responsible for the final user-facing \`MESSAGE @Agent\` answer.
+            -   Teammate source files are read-only context. When a teammate consultation occurs, record the actual exchange in a new top-level \`.book\` file in \`${toPromptPath(workspace.relativeWorkspacePath)}\`.
+            -   Name each transcript \`<teammate permanent id>--<sequence>.book\`, for example \`${workspace.manifest.teammates[0].permanentId}--01.book\`.
+            -   Every transcript must contain alternating \`MESSAGE @${workspace.manifest.primaryAgent.agentName}\` and \`MESSAGE @<teammate name>\` blocks. Do not create a transcript for a teammate that was not consulted.
+        `);
+    }
+    /**
+     * Converts a filesystem-relative path into the portable path notation used in prompts.
+     */
+    function toPromptPath(path) {
+        return path.replace(/\\/gu, '/');
+    }
+
     /**
      * Builds the prompt sent to the selected coding runner for one queued user-thread book.
      */
@@ -30116,7 +30639,7 @@
 
                 -   Read \`${messageRelativePath}\` and answer the most recent \`MESSAGE @User\`
                 -   Only change the queued message file by appending one new \`MESSAGE @Agent\` block
-                -   Do not modify any other file in the repository, except files inside your own \`${AGENT_PROJECTS_DIRECTORY_PATH}/\` directory
+                ${block(buildAllowedFileChangesPromptLine(options.teamWorkspace))}
 
                 ## Rules for the answering
 
@@ -30154,11 +30677,22 @@
 
                 ${block(buildAgentProjectsPromptSection(options))}
 
+                ${block(buildAgentTeamPromptSection(options.teamWorkspace))}
+
                 ## This is how you should behave
 
                 ${block(agentSystemMessage)}
             `);
     }
+    /**
+     * Explains the exact files that one coding harness may change for a user turn.
+     */
+    function buildAllowedFileChangesPromptLine(teamWorkspace) {
+        if (!teamWorkspace) {
+            return `-   Do not modify any other file in the repository, except files inside your own \`${AGENT_PROJECTS_DIRECTORY_PATH}/\` directory`;
+        }
+        return `-   Do not modify any other file in the repository, except files inside your own \`${AGENT_PROJECTS_DIRECTORY_PATH}/\` directory and new consultation transcripts inside \`${teamWorkspace.relativeWorkspacePath.replace(/\\/gu, '/')}\``;
+    }
 
     var PipelineCollection = [{title:"Prepare Knowledge from Markdown",pipelineUrl:"https://promptbook.studio/promptbook/prepare-knowledge-from-markdown.book",formfactorName:"GENERIC",parameters:[{name:"knowledgeContent",description:"Markdown document content",isInput:true,isOutput:false},{name:"knowledgePieces",description:"The knowledge JSON object",isInput:false,isOutput:true}],tasks:[{taskType:"PROMPT_TASK",name:"knowledge",title:"Knowledge",content:"You are experienced data researcher, extract the important knowledge from the document.\n\n# Rules\n\n-   Make pieces of information concise, clear, and easy to understand\n-   One piece of information should be approximately 1 paragraph\n-   Divide the paragraphs by markdown horizontal lines ---\n-   Omit irrelevant information\n-   Group redundant information\n-   Write just extracted information, nothing else\n\n# The document\n\nTake information from this document:\n\n> {knowledgeContent}",resultingParameterName:"knowledgePieces",dependentParameterNames:["knowledgeContent"]}],personas:[],preparations:[],knowledgeSources:[],knowledgePieces:[],sources:[{type:"BOOK",path:null,content:"# Prepare Knowledge from Markdown\n\n-   PIPELINE URL `https://promptbook.studio/promptbook/prepare-knowledge-from-markdown.book`\n-   INPUT PARAMETER `{knowledgeContent}` Markdown document content\n-   OUTPUT PARAMETER `{knowledgePieces}` The knowledge JSON object\n\n## Knowledge\n\n<!-- TODO: [🍆] -FORMAT JSON -->\n\n```markdown\nYou are experienced data researcher, extract the important knowledge from the document.\n\n# Rules\n\n-   Make pieces of information concise, clear, and easy to understand\n-   One piece of information should be approximately 1 paragraph\n-   Divide the paragraphs by markdown horizontal lines ---\n-   Omit irrelevant information\n-   Group redundant information\n-   Write just extracted information, nothing else\n\n# The document\n\nTake information from this document:\n\n> {knowledgeContent}\n```\n\n`-> {knowledgePieces}`\n"}],sourceFile:"./books/prepare-knowledge-from-markdown.book"},{title:"Prepare Keywords",pipelineUrl:"https://promptbook.studio/promptbook/prepare-knowledge-keywords.book",formfactorName:"GENERIC",parameters:[{name:"knowledgePieceContent",description:"The content",isInput:true,isOutput:false},{name:"keywords",description:"Keywords separated by comma",isInput:false,isOutput:true}],tasks:[{taskType:"PROMPT_TASK",name:"knowledge",title:"Knowledge",content:"You are experienced data researcher, detect the important keywords in the document.\n\n# Rules\n\n-   Write just keywords separated by comma\n\n# The document\n\nTake information from this document:\n\n> {knowledgePieceContent}",resultingParameterName:"keywords",dependentParameterNames:["knowledgePieceContent"]}],personas:[],preparations:[],knowledgeSources:[],knowledgePieces:[],sources:[{type:"BOOK",path:null,content:"# Prepare Keywords\n\n-   PIPELINE URL `https://promptbook.studio/promptbook/prepare-knowledge-keywords.book`\n-   INPUT PARAMETER `{knowledgePieceContent}` The content\n-   OUTPUT PARAMETER `{keywords}` Keywords separated by comma\n\n## Knowledge\n\n<!-- TODO: [🍆] -FORMAT JSON -->\n\n```markdown\nYou are experienced data researcher, detect the important keywords in the document.\n\n# Rules\n\n-   Write just keywords separated by comma\n\n# The document\n\nTake information from this document:\n\n> {knowledgePieceContent}\n```\n\n`-> {keywords}`\n"}],sourceFile:"./books/prepare-knowledge-keywords.book"},{title:"Prepare Knowledge-piece Title",pipelineUrl:"https://promptbook.studio/promptbook/prepare-knowledge-title.book",formfactorName:"GENERIC",parameters:[{name:"knowledgePieceContent",description:"The content",isInput:true,isOutput:false},{name:"title",description:"The title of the document",isInput:false,isOutput:true}],tasks:[{taskType:"PROMPT_TASK",name:"knowledge",title:"Knowledge",content:"You are experienced content creator, write best title for the document.\n\n# Rules\n\n-   Write just title, nothing else\n-   Write maximum 5 words for the title\n\n# The document\n\n> {knowledgePieceContent}",resultingParameterName:"title",expectations:{words:{min:1,max:8}},dependentParameterNames:["knowledgePieceContent"]}],personas:[],preparations:[],knowledgeSources:[],knowledgePieces:[],sources:[{type:"BOOK",path:null,content:"# Prepare Knowledge-piece Title\n\n-   PIPELINE URL `https://promptbook.studio/promptbook/prepare-knowledge-title.book`\n-   INPUT PARAMETER `{knowledgePieceContent}` The content\n-   OUTPUT PARAMETER `{title}` The title of the document\n\n## Knowledge\n\n-   EXPECT MIN 1 WORD\n-   EXPECT MAX 8 WORDS\n\n```markdown\nYou are experienced content creator, write best title for the document.\n\n# Rules\n\n-   Write just title, nothing else\n-   Write maximum 5 words for the title\n\n# The document\n\n> {knowledgePieceContent}\n```\n\n`-> {title}`\n"}],sourceFile:"./books/prepare-knowledge-title.book"},{title:"Prepare Persona",pipelineUrl:"https://promptbook.studio/promptbook/prepare-persona.book",formfactorName:"GENERIC",parameters:[{name:"availableModels",description:"List of available model names together with their descriptions as JSON",isInput:true,isOutput:false},{name:"personaDescription",description:"Description of the persona",isInput:true,isOutput:false},{name:"modelsRequirements",description:"Specific requirements for the model",isInput:false,isOutput:true}],tasks:[{taskType:"PROMPT_TASK",name:"make-model-requirements",title:"Make modelRequirements",content:"You are an experienced AI engineer, you need to find the best models for virtual assistants:\n\n## Example\n\n```json\n[\n  {\n  \"modelName\": \"gpt-4o\",\n  \"systemMessage\": \"You are experienced AI engineer and helpful assistant.\",\n  \"temperature\": 0.7\n  },\n  {\n    \"modelName\": \"claude-3-5-sonnet\",\n    \"systemMessage\": \"You are a friendly and knowledgeable chatbot.\",\n    \"temperature\": 0.5\n  }\n]\n```\n\n## Instructions\n\n-   Your output format is JSON array\n-   Sort best-fitting models first\n-   Omit any models that are not suitable\n-   Write just the JSON, no other text should be present\n-   Array contain items with following keys:\n    -   `modelName`: The name of the model to use\n    -   `systemMessage`: The system message to provide context to the model\n    -   `temperature`: The sampling temperature to use\n\n### Key `modelName`\n\nHere are the available models:\n\n```json\n{availableModels}\n```\n\n### Key `systemMessage`\n\nThe system message is used to communicate instructions or provide context to the model at the beginning of a conversation. It is displayed in a different format compared to user messages, helping the model understand its role in the conversation. The system message typically guides the model's behavior, sets the tone, or specifies desired output from the model. By utilizing the system message effectively, users can steer the model towards generating more accurate and relevant responses.\n\nFor example:\n\n> You are an experienced AI engineer and helpful assistant.\n\n> You are a friendly and knowledgeable chatbot.\n\n### Key `temperature`\n\nThe sampling temperature, between 0 and 1. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. If set to 0, the model will use log probability to automatically increase the temperature until certain thresholds are hit.\n\nYou can pick a value between 0 and 2. For example:\n\n-   `0.1`: Low temperature, extremely conservative and deterministic\n-   `0.5`: Medium temperature, balanced between conservative and creative\n-   `1.0`: High temperature, creative and bit random\n-   `1.5`: Very high temperature, extremely creative and often chaotic and unpredictable\n-   `2.0`: Maximum temperature, completely random and unpredictable, for some extreme creative use cases\n\n# The assistant\n\nTake this description of the persona:\n\n> {personaDescription}",resultingParameterName:"modelsRequirements",format:"JSON",dependentParameterNames:["availableModels","personaDescription"]}],personas:[],preparations:[],knowledgeSources:[],knowledgePieces:[],sources:[{type:"BOOK",path:null,content:"# Prepare Persona\n\n-   PIPELINE URL `https://promptbook.studio/promptbook/prepare-persona.book`\n-   INPUT PARAMETER `{availableModels}` List of available model names together with their descriptions as JSON\n-   INPUT PARAMETER `{personaDescription}` Description of the persona\n-   OUTPUT PARAMETER `{modelsRequirements}` Specific requirements for the model\n\n## Make modelRequirements\n\n-   FORMAT JSON\n\n```markdown\nYou are an experienced AI engineer, you need to find the best models for virtual assistants:\n\n## Example\n\n\\`\\`\\`json\n[\n  {\n  \"modelName\": \"gpt-4o\",\n  \"systemMessage\": \"You are experienced AI engineer and helpful assistant.\",\n  \"temperature\": 0.7\n  },\n  {\n    \"modelName\": \"claude-3-5-sonnet\",\n    \"systemMessage\": \"You are a friendly and knowledgeable chatbot.\",\n    \"temperature\": 0.5\n  }\n]\n\\`\\`\\`\n\n## Instructions\n\n-   Your output format is JSON array\n-   Sort best-fitting models first\n-   Omit any models that are not suitable\n-   Write just the JSON, no other text should be present\n-   Array contain items with following keys:\n    -   `modelName`: The name of the model to use\n    -   `systemMessage`: The system message to provide context to the model\n    -   `temperature`: The sampling temperature to use\n\n### Key `modelName`\n\nHere are the available models:\n\n\\`\\`\\`json\n{availableModels}\n\\`\\`\\`\n\n### Key `systemMessage`\n\nThe system message is used to communicate instructions or provide context to the model at the beginning of a conversation. It is displayed in a different format compared to user messages, helping the model understand its role in the conversation. The system message typically guides the model's behavior, sets the tone, or specifies desired output from the model. By utilizing the system message effectively, users can steer the model towards generating more accurate and relevant responses.\n\nFor example:\n\n> You are an experienced AI engineer and helpful assistant.\n\n> You are a friendly and knowledgeable chatbot.\n\n### Key `temperature`\n\nThe sampling temperature, between 0 and 1. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. If set to 0, the model will use log probability to automatically increase the temperature until certain thresholds are hit.\n\nYou can pick a value between 0 and 2. For example:\n\n-   `0.1`: Low temperature, extremely conservative and deterministic\n-   `0.5`: Medium temperature, balanced between conservative and creative\n-   `1.0`: High temperature, creative and bit random\n-   `1.5`: Very high temperature, extremely creative and often chaotic and unpredictable\n-   `2.0`: Maximum temperature, completely random and unpredictable, for some extreme creative use cases\n\n# The assistant\n\nTake this description of the persona:\n\n> {personaDescription}\n```\n\n`-> {modelsRequirements}`\n"}],sourceFile:"./books/prepare-persona.book"},{title:"Prepare Title",pipelineUrl:"https://promptbook.studio/promptbook/prepare-title.book",formfactorName:"GENERIC",parameters:[{name:"book",description:"The book to prepare the title for",isInput:true,isOutput:false},{name:"title",description:"Best title for the book",isInput:false,isOutput:true}],tasks:[{taskType:"PROMPT_TASK",name:"make-title",title:"Make title",content:"Make best title for given text which describes the workflow:\n\n## Rules\n\n-   Write just title, nothing else\n-   Title should be concise and clear - Write maximum ideally 2 words, maximum 5 words\n-   Title starts with emoticon\n-   Title should not mention the input and output of the workflow but the main purpose of the workflow\n    _For example, not \"✍ Convert Knowledge-piece to title\" but \"✍ Title\"_\n\n## The workflow\n\n> {book}",resultingParameterName:"title",expectations:{words:{min:1,max:8},lines:{min:1,max:1}},dependentParameterNames:["book"]}],personas:[],preparations:[],knowledgeSources:[],knowledgePieces:[],sources:[{type:"BOOK",path:null,content:"# Prepare Title\n\n-   PIPELINE URL `https://promptbook.studio/promptbook/prepare-title.book`\n-   INPUT PARAMETER `{book}` The book to prepare the title for\n-   OUTPUT PARAMETER `{title}` Best title for the book\n\n## Make title\n\n-   EXPECT MIN 1 Word\n-   EXPECT MAX 8 Words\n-   EXPECT EXACTLY 1 Line\n\n```markdown\nMake best title for given text which describes the workflow:\n\n## Rules\n\n-   Write just title, nothing else\n-   Title should be concise and clear - Write maximum ideally 2 words, maximum 5 words\n-   Title starts with emoticon\n-   Title should not mention the input and output of the workflow but the main purpose of the workflow\n    _For example, not \"✍ Convert Knowledge-piece to title\" but \"✍ Title\"_\n\n## The workflow\n\n> {book}\n```\n\n`-> {title}`\n"}],sourceFile:"./books/prepare-title.book"}];
 
@@ -36858,6 +37392,148 @@
             .join('\n\n');
     }
 
+    /**
+     * Moves harness-created TEAM conversation transcripts into the finished-message history.
+     */
+    async function finalizeAgentTeamConversationWorkspace(options) {
+        if (!options.workspace) {
+            return null;
+        }
+        const activeWorkspacePath = path.join(options.projectPath, createAgentTeamConversationWorkspacePath(options.queuedMessage.fileName));
+        const activeManifestPath = path.join(activeWorkspacePath, AGENT_TEAM_CONVERSATION_MANIFEST_FILE_NAME);
+        const transcriptFileNames = await listAgentTeamTranscriptFileNames(activeWorkspacePath);
+        if (!(await isExistingPath$1(activeManifestPath))) {
+            return null;
+        }
+        if (transcriptFileNames.length === 0) {
+            await promises.rm(activeWorkspacePath, { recursive: true, force: true });
+            return null;
+        }
+        const finishedRelativeWorkspacePath = createFinishedAgentTeamConversationWorkspacePath(options.queuedMessage.fileName);
+        const finishedWorkspacePath = path.join(options.projectPath, finishedRelativeWorkspacePath);
+        await promises.rm(finishedWorkspacePath, { recursive: true, force: true });
+        await promises.mkdir(finishedWorkspacePath, { recursive: true });
+        const relativePaths = [
+            toPortablePath$1(path.join(finishedRelativeWorkspacePath, AGENT_TEAM_CONVERSATION_MANIFEST_FILE_NAME)),
+        ];
+        await promises.rename(activeManifestPath, path.join(finishedWorkspacePath, AGENT_TEAM_CONVERSATION_MANIFEST_FILE_NAME));
+        for (const transcriptFileName of transcriptFileNames) {
+            await promises.rename(path.join(activeWorkspacePath, transcriptFileName), path.join(finishedWorkspacePath, transcriptFileName));
+            relativePaths.push(toPortablePath$1(path.join(finishedRelativeWorkspacePath, transcriptFileName)));
+        }
+        await promises.rm(activeWorkspacePath, { recursive: true, force: true });
+        return { relativePaths };
+    }
+    /**
+     * Lists only direct transcript `.book` files and deliberately excludes read-only teammate sources.
+     */
+    async function listAgentTeamTranscriptFileNames(activeWorkspacePath) {
+        try {
+            const entries = await promises.readdir(activeWorkspacePath, { withFileTypes: true });
+            return entries
+                .filter((entry) => entry.isFile() && entry.name.toLowerCase().endsWith('.book'))
+                .map((entry) => entry.name)
+                .sort((firstFileName, secondFileName) => firstFileName.localeCompare(secondFileName));
+        }
+        catch (error) {
+            if (isFileNotFoundError$2(error)) {
+                return [];
+            }
+            throw error;
+        }
+    }
+    /**
+     * Checks whether one fixed workspace path exists.
+     */
+    async function isExistingPath$1(path) {
+        try {
+            await promises.stat(path);
+            return true;
+        }
+        catch (error) {
+            if (isFileNotFoundError$2(error)) {
+                return false;
+            }
+            throw error;
+        }
+    }
+    /**
+     * Converts a filesystem-relative path into a portable Git path.
+     */
+    function toPortablePath$1(path) {
+        return path.replace(/\\/gu, '/');
+    }
+    /**
+     * Returns true when one filesystem error indicates a missing path.
+     */
+    function isFileNotFoundError$2(error) {
+        return Boolean(error &&
+            typeof error === 'object' &&
+            'code' in error &&
+            (error.code === 'ENOENT' || error.code === 'ENOTDIR'));
+    }
+
+    /**
+     * Loads the optional TEAM roster snapshot for one queued message.
+     */
+    async function loadAgentTeamConversationWorkspace(projectPath, queuedMessage) {
+        const relativeWorkspacePath = createAgentTeamConversationWorkspacePath(queuedMessage.fileName);
+        const manifestPath = path.join(projectPath, relativeWorkspacePath, AGENT_TEAM_CONVERSATION_MANIFEST_FILE_NAME);
+        const manifestContent = await readOptionalTextFile(manifestPath);
+        if (manifestContent === null) {
+            return null;
+        }
+        const manifest = parseAgentTeamConversationWorkspaceManifest(manifestContent);
+        if (!manifest || manifest.teammates.length === 0) {
+            return null;
+        }
+        return {
+            relativeWorkspacePath: toPortablePath(relativeWorkspacePath),
+            manifest,
+        };
+    }
+    /**
+     * Parses one untrusted TEAM workspace manifest without making a queued message fail for stale sidecar data.
+     */
+    function parseAgentTeamConversationWorkspaceManifest(manifestContent) {
+        try {
+            const parsedManifest = JSON.parse(manifestContent);
+            return isAgentTeamConversationWorkspaceManifest(parsedManifest) ? parsedManifest : null;
+        }
+        catch (_a) {
+            return null;
+        }
+    }
+    /**
+     * Reads one text file and treats a missing team workspace as absent.
+     */
+    async function readOptionalTextFile(path) {
+        try {
+            return await promises.readFile(path, 'utf-8');
+        }
+        catch (error) {
+            if (isFileNotFoundError$1(error)) {
+                return null;
+            }
+            throw error;
+        }
+    }
+    /**
+     * Converts a filesystem-relative path to the portable form used by prompts and Git.
+     */
+    function toPortablePath(path) {
+        return path.replace(/\\/gu, '/');
+    }
+    /**
+     * Returns true when one filesystem error indicates a missing path.
+     */
+    function isFileNotFoundError$1(error) {
+        return Boolean(error &&
+            typeof error === 'object' &&
+            'code' in error &&
+            (error.code === 'ENOENT' || error.code === 'ENOTDIR'));
+    }
+
     /**
      * Resolves project-runtime prompt API details for one local agent runner folder.
      *
@@ -37174,11 +37850,13 @@
      * Runs the selected coding runner for one message and finalizes the answered file.
      */
     async function runQueuedAgentMessage(options) {
-        const { projectPath, options: runOptions, runner, actualRunnerModel, queuedMessage, uiHandle, isSharedDashboard } = options;
+        const { projectPath, options: runOptions, runner, actualRunnerModel, queuedMessage, uiHandle, isSharedDashboard, } = options;
         const agentSystemMessage = await loadLocalAgentSystemMessage(projectPath);
+        const teamWorkspace = await loadAgentTeamConversationWorkspace(projectPath, queuedMessage);
         const prompt = buildAgentMessagePrompt(queuedMessage.relativePath, agentSystemMessage, {
             projectRuntimeApi: resolveAgentProjectRuntimePromptApi(projectPath),
             projectsUrlPath: resolveAgentProjectsUrlPath(projectPath),
+            teamWorkspace: teamWorkspace || undefined,
         });
         const scriptPath = buildAgentMessageScriptPath(projectPath, queuedMessage);
         const runtimeLogPath = buildScriptLogPath(scriptPath);
@@ -37226,6 +37904,13 @@
             uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.stopCapturingAgentOutput();
         }
         await normalizeLineEndingsForAgentRound(projectPath, runOptions, roundChangedFilesSnapshot);
+        const finishedTeamWorkspace = await finalizeAgentTeamConversationWorkspace({
+            projectPath,
+            queuedMessage,
+            workspace: teamWorkspace,
+        });
+        // Note: The Agents Server observes the primary finished `.book` as its completion signal.
+        //       Retain TEAM transcripts first so that observer can parse every consultation atomically.
         const finishedMessage = await moveAgentMessageToFinished(projectPath, queuedMessage);
         const writtenRunReport = await writeAgentMessageRunReport({
             finishedMessageAbsolutePath: finishedMessage.absolutePath,
@@ -37242,6 +37927,7 @@
             options: runOptions,
             queuedMessage,
             finishedMessage,
+            finishedTeamWorkspace,
             writtenRunReport,
             isQueuedMessageTracked,
             uiHandle,
@@ -37313,7 +37999,7 @@
      * Commits the answered message move unless `--no-commit` was requested.
      */
     async function commitAnsweredMessageIfEnabled(options) {
-        const { options: runOptions, queuedMessage, finishedMessage, writtenRunReport, isQueuedMessageTracked, uiHandle, isSharedDashboard, projectPath, } = options;
+        const { options: runOptions, queuedMessage, finishedMessage, finishedTeamWorkspace, writtenRunReport, isQueuedMessageTracked, uiHandle, isSharedDashboard, projectPath, } = options;
         if (runOptions.noCommit) {
             if (!isSharedDashboard) {
                 uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.setStatusMessage('Leaving changes uncommitted');
@@ -37325,21 +38011,24 @@
         }
         await commitChanges(buildAgentMessageCommitMessage(queuedMessage), {
             autoPush: runOptions.autoPush,
-            includePaths: buildCommitIncludePaths(queuedMessage, finishedMessage, writtenRunReport, isQueuedMessageTracked),
+            relevantPaths: buildCommitRelevantPaths(queuedMessage, finishedMessage, writtenRunReport, isQueuedMessageTracked, finishedTeamWorkspace),
             projectPath,
         });
     }
     /**
      * Builds the focused git path list for the answered-message commit.
      */
-    function buildCommitIncludePaths(queuedMessage, finishedMessage, writtenRunReport, isQueuedMessageTracked) {
-        const includePaths = isQueuedMessageTracked
+    function buildCommitRelevantPaths(queuedMessage, finishedMessage, writtenRunReport, isQueuedMessageTracked, finishedTeamWorkspace) {
+        const relevantPaths = isQueuedMessageTracked
             ? [queuedMessage.relativePath, finishedMessage.relativePath]
             : [finishedMessage.relativePath];
         if (writtenRunReport) {
-            includePaths.push(writtenRunReport.relativePath);
+            relevantPaths.push(writtenRunReport.relativePath);
+        }
+        if (finishedTeamWorkspace) {
+            relevantPaths.push(...finishedTeamWorkspace.relativePaths);
         }
-        return includePaths;
+        return relevantPaths;
     }
     /**
      * Normalizes line endings in files changed during the current agent round.
@@ -38851,7 +39540,7 @@
     const CODER_GIT_SYNC_DESCRIPTION = _spaceTrim.spaceTrim(`
     Git synchronization:
     - --auto-pull pulls the latest changes before this command changes anything
-    - --commit commits the changes made by this command
+    - --commit commits only the files this command has changed, unrelated changes stay in the working tree
     - --auto-push pushes the created commit to the remote repository
 `);
     /**
@@ -38863,7 +39552,7 @@
      * @private internal utility of `promptbookCli`
      */
     function addCoderGitSyncOptions(command) {
-        command.option('--commit', 'Commit the changes made by this command with the coding-agent git identity', false);
+        command.option('--commit', 'Commit the files changed by this command with the coding-agent git identity, leaving unrelated changes uncommitted', false);
         command.option('--auto-push', 'Automatically git push the created commit, requires --commit', false);
         command.option('--auto-pull', 'Automatically git pull the latest changes before this command changes anything', false);
     }
@@ -39172,8 +39861,8 @@
             const projectPath = process.cwd();
             const description = await resolveCoderPromptDescription(descriptionArgument);
             // Note: Import the git synchronization dynamically to keep the CLI fast for runs without `--commit`
-            const { $commitCoderChanges, $pullCoderChanges } = await Promise.resolve().then(function () { return coderGitSync; });
-            await $pullCoderChanges({ gitSync, projectPath });
+            const { $commitCoderChanges, $startCoderGitSync } = await Promise.resolve().then(function () { return coderGitSync; });
+            const commitScope = await $startCoderGitSync({ gitSync, projectPath });
             const { /* filePath,*/ emojiTag } = await addCoderPrompt({
                 projectPath,
                 description,
@@ -39182,7 +39871,7 @@
             });
             await $commitCoderChanges({
                 gitSync,
-                projectPath,
+                commitScope,
                 commitMessage: `${emojiTag} Add prompt`,
             });
         }));
@@ -39776,7 +40465,7 @@
     function $initializeCoderGenerateBoilerplatesCommand(program) {
         const command = program.command('generate-boilerplates');
         command.description(_spaceTrim.spaceTrim((block) => `
-                Generate prompt boilerplate files with unique emoji tags
+                Generate prompt boilerplate files with one unique emoji tag per file
 
                 ${block(CODER_GIT_SYNC_DESCRIPTION)}
             `));
@@ -39795,8 +40484,8 @@
             const gitSync = normalizeCoderGitSyncCliOptions(cliOptions);
             const projectPath = process.cwd();
             // Note: Import the git synchronization dynamically to keep the CLI fast for runs without `--commit`
-            const { $commitCoderChanges, $pullCoderChanges } = await Promise.resolve().then(function () { return coderGitSync; });
-            await $pullCoderChanges({ gitSync, projectPath });
+            const { $commitCoderChanges, $startCoderGitSync } = await Promise.resolve().then(function () { return coderGitSync; });
+            const commitScope = await $startCoderGitSync({ gitSync, projectPath });
             await generatePromptBoilerplate({
                 projectPath,
                 boilerplateCount,
@@ -39804,14 +40493,14 @@
             });
             await $commitCoderChanges({
                 gitSync,
-                projectPath,
+                commitScope,
                 commitMessage: `Prompts ${formatBoilerplateCount(boilerplateCount)}`,
             });
             return process.exit(0);
         }));
     }
     /**
-     * Generates boilerplate prompt files with unique emoji tags.
+     * Generates boilerplate prompt files with one unique emoji tag per file.
      *
      * @private internal function of `generatePromptBoilerplate` command
      */
@@ -39831,10 +40520,10 @@
         const highestNumber = promptNumbering.startNumber === 0 ? 0 : promptNumbering.startNumber - promptNumbering.step;
         const highestNumberFormatted = Math.max(0, highestNumber).toString().padStart(4, '0');
         console.info(colors__default["default"].blue(`Highest existing number for ${promptNumbering.datePrefix} found: ${highestNumberFormatted}`));
-        // Note: Every single generated prompt is one separate coding task, so each of them reserves its own fresh emoji tag
         const promptsCount = filesCount * promptsPerFileCount;
         const { availableCount, selectedEmojis } = await getFreshPromptEmojiTags({
-            count: promptsCount,
+            // Note: Each generated file reserves one fresh emoji tag shared by all of its prompt sections
+            count: filesCount,
             rootDir: projectPath,
         });
         console.info(colors__default["default"].green(`Found ${availableCount} available fresh emojis`));
@@ -39846,14 +40535,13 @@
         for (let i = 0; i < filesCount; i++) {
             const number = promptNumbering.startNumber + i * promptNumbering.step;
             const title = titles[i % titles.length];
-            const emojiTags = selectedEmojis
-                .slice(i * promptsPerFileCount, (i + 1) * promptsPerFileCount)
-                .map((emoji) => formatPromptEmojiTag(emoji));
+            const emojiTag = formatPromptEmojiTag(selectedEmojis[i]);
             const filename = buildPromptFilename(promptNumbering.datePrefix, number, buildPromptSlug$1(promptTemplate.slugPrefix, title));
             const filepath = path.join(PROMPTS_DIRECTORY_PATH, filename);
             const absoluteFilepath = path.join(projectPath, filepath);
             const content = buildBoilerplatePromptFileContent({
-                emojiTags,
+                emojiTag,
+                promptsPerFileCount,
                 title,
                 body: promptTemplate.content,
             });
@@ -39862,7 +40550,7 @@
                 absoluteFilepath,
                 filename,
                 content,
-                emojiTags,
+                emojiTag,
                 number,
             });
         }
@@ -39870,26 +40558,25 @@
         console.info(colors__default["default"].yellow(`Creating ${filesToCreate.length} files:`));
         for (const file of filesToCreate) {
             fs.writeFileSync(file.absoluteFilepath, file.content, 'utf-8');
-            console.info(colors__default["default"].green(`✓ Created: ${file.filename} with ${file.emojiTags.join(' ')}`));
+            console.info(colors__default["default"].green(`✓ Created: ${file.filename} with ${file.emojiTag}`));
         }
         console.info(colors__default["default"].bgGreen(` Successfully created ${promptsCount} prompts in ${filesToCreate.length} prompt boilerplate files! `));
     }
     /**
-     * Builds the markdown content of one generated prompt file with one prompt section per emoji tag.
+     * Builds the markdown content of one generated prompt file with one prompt section per prompt.
      *
-     * Multiple prompts in one file are separated by the `---` separator, exactly like the prompt runner expects them.
+     * Multiple prompts in one file share the file emoji tag and are separated by the `---` separator,
+     * exactly like the prompt runner expects them.
      *
      * @private internal utility of `generatePromptBoilerplate` command
      */
-    function buildBoilerplatePromptFileContent({ emojiTags, title, body, }) {
-        return emojiTags
-            .map((emojiTag) => buildCoderPromptSection({
+    function buildBoilerplatePromptFileContent({ emojiTag, promptsPerFileCount, title, body, }) {
+        return Array.from({ length: promptsPerFileCount }, () => buildCoderPromptSection({
             statusLine: '[-]',
             emojiTag,
             title,
             body,
-        }))
-            .join('\n\n---\n\n');
+        })).join('\n\n---\n\n');
     }
     /**
      * Builds filename slug from template and placeholder title.
@@ -39906,14 +40593,14 @@
     // Note: [💞] Ignore a discrepancy between file name and entity name
 
     /**
-     * Asks the user in the terminal whether the harness should be installed or updated right now.
+     * Asks the user in the terminal whether an npm package should be installed or updated now.
      *
      * Note: `$` is used to indicate that this function is not a pure function - it reads the answer from stdin
      *
      * @returns `true` when the user confirms, `false` when the user declines or the terminal is not interactive
      * @private internal utility of `promptbookCli`
      */
-    async function $askForHarnessInstallationApproval(question) {
+    async function $askForNpmPackageInstallationApproval(question) {
         if (!process.stdin.isTTY) {
             // Note: In non-interactive environments like CI there is nobody who could confirm the installation
             return false;
@@ -39929,7 +40616,7 @@
             readlineInterface.close();
         }
     }
-    // Note: [🟡] Code for CLI harness installation approval [$askForHarnessInstallationApproval](src/cli/cli-commands/common/harness/$askForHarnessInstallationApproval.ts) should never be published outside of `@promptbook/cli`
+    // Note: [🟡] Code for CLI npm package installation approval [$askForNpmPackageInstallationApproval](src/cli/cli-commands/common/npm/$askForNpmPackageInstallationApproval.ts) should never be published outside of `@promptbook/cli`
 
     /**
      * Builds the shell command which installs or updates one CLI coding harness globally.
@@ -40024,7 +40711,7 @@
             return;
         }
         console.warn(colors__default["default"].yellow(formatHarnessInstallationWarning(status)));
-        const isInstallationApproved = await $askForHarnessInstallationApproval(installationState === 'not-installed'
+        const isInstallationApproved = await $askForNpmPackageInstallationApproval(installationState === 'not-installed'
             ? `Install ${definition.label} globally now?`
             : `Update ${definition.label} to ${latestVersion} now?`);
         if (!isInstallationApproved) {
@@ -40036,30 +40723,25 @@
     // Note: [🟡] Code for CLI harness installation handling [$applyHarnessInstallationStatus](src/cli/cli-commands/common/harness/$applyHarnessInstallationStatus.ts) should never be published outside of `@promptbook/cli`
 
     /**
-     * Pattern matching one `major.minor.patch` version anywhere in the output of a harness version command.
+     * Pattern matching one `major.minor.patch` version anywhere in npm or CLI command output.
      */
-    const HARNESS_VERSION_PATTERN = /\b(\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?)/u;
+    const NPM_PACKAGE_VERSION_PATTERN = /\b(\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?)/gu;
     /**
-     * Extracts the version from the raw output of a harness `--version` command.
+     * Extracts an npm package version from raw command output.
      *
-     * Harness CLIs print their version in many shapes, for example `2.1.199 (Claude Code)`,
-     * `codex-cli 0.144.4`, `GitHub Copilot CLI 1.0.61.` or after unrelated deprecation warning lines,
-     * so the first version-looking token of the first matching line wins.
+     * Both npm and CLI commands may emit unrelated warnings before the version. CLI commands use the first matching token;
+     * npm registry commands can opt into the last matching token because npm warnings commonly precede their JSON output.
      *
      * @returns The parsed version or `null` when the output contains no version
      * @private internal utility of `promptbookCli`
      */
-    function extractHarnessVersionFromOutput(output) {
+    function extractNpmPackageVersionFromOutput(output, { isLastMatchPreferred = false } = {}) {
         var _a;
-        for (const line of output.split('\n')) {
-            const versionMatch = HARNESS_VERSION_PATTERN.exec(line);
-            if (versionMatch !== null) {
-                return (_a = versionMatch[1]) !== null && _a !== void 0 ? _a : null;
-            }
-        }
-        return null;
+        const versionMatches = Array.from(output.matchAll(NPM_PACKAGE_VERSION_PATTERN));
+        const versionMatch = isLastMatchPreferred ? versionMatches[versionMatches.length - 1] : versionMatches[0];
+        return (_a = versionMatch === null || versionMatch === void 0 ? void 0 : versionMatch[1]) !== null && _a !== void 0 ? _a : null;
     }
-    // Note: [🟡] Code for CLI harness version parsing [extractHarnessVersionFromOutput](src/cli/cli-commands/common/harness/extractHarnessVersionFromOutput.ts) should never be published outside of `@promptbook/cli`
+    // Note: [🟡] Code for CLI npm package version parsing [extractNpmPackageVersionFromOutput](src/cli/cli-commands/common/npm/extractNpmPackageVersionFromOutput.ts) should never be published outside of `@promptbook/cli`
 
     /**
      * Time limit for asking the globally installed harness command for its version.
@@ -40080,46 +40762,60 @@
             timeout: HARNESS_VERSION_COMMAND_TIMEOUT_MS,
             isVerbose: false,
         }).catch(() => '');
-        return extractHarnessVersionFromOutput(output);
+        return extractNpmPackageVersionFromOutput(output);
     }
     // Note: [🟡] Code for CLI harness version detection [$resolveInstalledHarnessVersion](src/cli/cli-commands/common/harness/$resolveInstalledHarnessVersion.ts) should never be published outside of `@promptbook/cli`
 
     /**
-     * Time limit for the whole `npm view` lookup of the newest published harness version.
+     * Time limit for the whole `npm view` lookup of the newest published package version.
      */
-    const HARNESS_LATEST_VERSION_COMMAND_TIMEOUT_MS = 60 * 1000;
+    const NPM_PACKAGE_LATEST_VERSION_COMMAND_TIMEOUT_MS = 60 * 1000;
     /**
      * Time limit for one npm registry request, so an unreachable registry never blocks the command.
      */
     const NPM_REGISTRY_FETCH_TIMEOUT_MS = 20 * 1000;
     /**
-     * Reads the newest version of the harness published to npm.
+     * Pattern matching npm's JSON-encoded package version result.
+     */
+    const NPM_VIEW_JSON_VERSION_PATTERN = /"(\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?)/u;
+    /**
+     * Reads the newest version of one npm package.
      *
      * Note: `$` is used to indicate that this function is not a pure function - it queries the npm registry
      *
      * @returns The newest published version or `null` when the registry could not be reached
      * @private internal utility of `promptbookCli`
      */
-    async function $resolveLatestHarnessVersion(definition) {
+    async function $resolveLatestNpmPackageVersion(npmPackageName) {
         const output = await $execCommand({
-            command: `npm view ${definition.npmPackageName} version --fetch-timeout=${NPM_REGISTRY_FETCH_TIMEOUT_MS} --fetch-retries=1`,
+            command: `npm view ${npmPackageName} version --json --loglevel=error --fetch-timeout=${NPM_REGISTRY_FETCH_TIMEOUT_MS} --fetch-retries=1`,
             crashOnError: true,
-            timeout: HARNESS_LATEST_VERSION_COMMAND_TIMEOUT_MS,
+            timeout: NPM_PACKAGE_LATEST_VERSION_COMMAND_TIMEOUT_MS,
             isVerbose: false,
         }).catch(() => '');
-        return extractHarnessVersionFromOutput(output);
+        return extractLatestNpmPackageVersionFromNpmViewOutput(output);
+    }
+    /**
+     * Extracts the version from npm's JSON result while tolerating warnings emitted before or after that result.
+     *
+     * @private internal utility of `$resolveLatestNpmPackageVersion`
+     */
+    function extractLatestNpmPackageVersionFromNpmViewOutput(output) {
+        var _a;
+        const jsonVersionMatch = NPM_VIEW_JSON_VERSION_PATTERN.exec(output);
+        return (_a = jsonVersionMatch === null || jsonVersionMatch === void 0 ? void 0 : jsonVersionMatch[1]) !== null && _a !== void 0 ? _a : extractNpmPackageVersionFromOutput(output, { isLastMatchPreferred: true });
     }
-    // Note: [🟡] Code for CLI harness registry lookup [$resolveLatestHarnessVersion](src/cli/cli-commands/common/harness/$resolveLatestHarnessVersion.ts) should never be published outside of `@promptbook/cli`
+    // Note: [🟡] Code for CLI npm package registry lookup [$resolveLatestNpmPackageVersion](src/cli/cli-commands/common/npm/$resolveLatestNpmPackageVersion.ts) should never be published outside of `@promptbook/cli`
 
     /**
-     * Compares the installed harness version with the newest version published to npm.
+     * Compares an installed npm package version with the newest published version.
      *
      * Only the numeric `major.minor.patch` segments are compared and pre-release suffixes are ignored,
-     * so a harness installed from a pre-release build of the newest version is not reported as outdated.
+     * so a package installed from a pre-release build of the newest version is not reported as outdated.
      *
      * @private internal utility of `promptbookCli`
      */
-    function isHarnessVersionOutdated(installedVersion, latestVersion) {
+    function isNpmPackageVersionOutdated(installedVersion, latestVersion) {
         var _a, _b;
         const installedSegments = parseVersionSegments(installedVersion);
         const latestSegments = parseVersionSegments(latestVersion);
@@ -40135,6 +40831,8 @@
     }
     /**
      * Splits one version into its numeric segments, dropping the pre-release and build suffix.
+     *
+     * @private internal utility of `isNpmPackageVersionOutdated`
      */
     function parseVersionSegments(version) {
         const [numericVersion = ''] = version.trim().split(/[-+]/u);
@@ -40143,7 +40841,7 @@
             return Number.isNaN(segmentNumber) ? 0 : segmentNumber;
         });
     }
-    // Note: [🟡] Code for CLI harness version comparison [isHarnessVersionOutdated](src/cli/cli-commands/common/harness/isHarnessVersionOutdated.ts) should never be published outside of `@promptbook/cli`
+    // Note: [🟡] Code for CLI npm package version comparison [isNpmPackageVersionOutdated](src/cli/cli-commands/common/npm/isNpmPackageVersionOutdated.ts) should never be published outside of `@promptbook/cli`
 
     /**
      * Detects whether one CLI coding harness is installed globally and whether it is up to date.
@@ -40155,7 +40853,7 @@
     async function $checkHarnessInstallation(definition) {
         const [installedVersion, latestVersion] = await Promise.all([
             $resolveInstalledHarnessVersion(definition),
-            $resolveLatestHarnessVersion(definition),
+            $resolveLatestNpmPackageVersion(definition.npmPackageName),
         ]);
         return {
             definition,
@@ -40174,7 +40872,7 @@
         if (latestVersion === null) {
             return 'unknown';
         }
-        return isHarnessVersionOutdated(installedVersion, latestVersion) ? 'outdated' : 'up-to-date';
+        return isNpmPackageVersionOutdated(installedVersion, latestVersion) ? 'outdated' : 'up-to-date';
     }
     // Note: [🟡] Code for CLI harness installation check [$checkHarnessInstallation](src/cli/cli-commands/common/harness/$checkHarnessInstallation.ts) should never be published outside of `@promptbook/cli`
 
@@ -40406,11 +41104,12 @@
      * Default npm scripts initialized by `ptbk coder init`.
      */
     const DEFAULT_CODER_PACKAGE_JSON_SCRIPTS = {
-        'coder:generate-boilerplates': `ptbk coder generate-boilerplates --count ${DEFAULT_BOILERPLATE_COUNT_OPTION_VALUE} --template ./prompts/templates/common.md`,
-        'coder:add': 'ptbk coder add --template ./prompts/templates/common.md',
-        'coder:run': 'ptbk coder run --harness openai-codex --model gpt-5.6-terra --thinking-level max --agent agents/developer.book --context AGENTS.md --test-before yes-and-fix',
+        // Note: Using NPX because `ptbk` can be installed globally or locally, and NPX will resolve it correctly in either case.
+        'coder:generate-boilerplates': `npx ptbk coder generate-boilerplates --count ${DEFAULT_BOILERPLATE_COUNT_OPTION_VALUE} --template ./prompts/templates/common.md`,
+        'coder:add': 'npx ptbk coder add --template ./prompts/templates/common.md',
+        'coder:run': 'npx ptbk coder run --harness openai-codex --model gpt-5.6-terra --thinking-level max --agent agents/developer.book --context AGENTS.md --test-before yes-and-fix',
         // 'coder:find-refactor-candidates': 'npx ptbk coder find-refactor-candidates',
-        'coder:verify': 'ptbk coder verify',
+        'coder:verify': 'npx ptbk coder verify',
     };
     /**
      * Lists the default npm scripts initialized by `ptbk coder init`.
@@ -40780,14 +41479,14 @@
             const gitSync = normalizeCoderGitSyncCliOptions(cliOptions);
             const projectPath = process.cwd();
             // Note: Import the git synchronization dynamically to keep the CLI fast for runs without `--commit`
-            const { $commitCoderChanges, $pullCoderChanges } = await Promise.resolve().then(function () { return coderGitSync; });
-            await $pullCoderChanges({ gitSync, projectPath });
+            const { $commitCoderChanges, $startCoderGitSync } = await Promise.resolve().then(function () { return coderGitSync; });
+            const commitScope = await $startCoderGitSync({ gitSync, projectPath });
             const summary = await initializeCoderProjectConfiguration(projectPath);
             printInitializationSummary(summary);
             await generatePromptBoilerplate({ projectPath, boilerplateCount: DEFAULT_BOILERPLATE_COUNT });
             await $commitCoderChanges({
                 gitSync,
-                projectPath,
+                commitScope,
                 commitMessage: 'Initialize Promptbook Coder',
             });
             await $ensureHarnessInstallations(CODER_INIT_CHECKED_HARNESS_NAMES);
@@ -40876,6 +41575,370 @@
     }
     // Note: [🟡] Code for CLI option parser [createNonNegativeIntegerOptionParser](src/cli/cli-commands/common/createNonNegativeIntegerOptionParser.ts) should never be published outside of `@promptbook/cli`
 
+    /**
+     * Npm packages which provide an executable Promptbook CLI.
+     *
+     * `ptbk` is the preferred package and forwards to `@promptbook/cli`; the latter can also be installed directly.
+     *
+     * @private internal utility of `promptbookCli`
+     */
+    const PROMPTBOOK_CLI_NPM_PACKAGE_NAMES = ['ptbk', '@promptbook/cli'];
+    // Note: [🟡] Code for Promptbook CLI installation definitions [PromptbookCliInstallation](src/cli/cli-commands/common/promptbook-cli/PromptbookCliInstallation.ts) should never be published outside of `@promptbook/cli`
+
+    /**
+     * Time limit for resolving npm's global `node_modules` directory.
+     */
+    const NPM_GLOBAL_NODE_MODULES_PATH_COMMAND_TIMEOUT_MS = 30 * 1000;
+    /**
+     * Finds every locally or globally installed Promptbook CLI package which can be updated.
+     *
+     * A local package must be declared directly in the current project's `package.json`; transitive packages are not
+     * updated because this command must not change dependencies chosen by another package.
+     *
+     * Note: `$` is used to indicate that this function is not a pure function - it reads package manifests and runs npm
+     *
+     * @private internal utility of `promptbookCli`
+     */
+    async function $resolvePromptbookCliInstallations() {
+        const [localInstallations, globalInstallations] = await Promise.all([
+            $resolveLocalPromptbookCliInstallations(),
+            $resolveGlobalPromptbookCliInstallations(),
+        ]);
+        return [...localInstallations, ...globalInstallations];
+    }
+    /**
+     * Finds Promptbook CLI packages installed directly in the current project's dependencies.
+     *
+     * @private internal utility of `$resolvePromptbookCliInstallations`
+     */
+    async function $resolveLocalPromptbookCliInstallations() {
+        const projectPath = process.cwd();
+        const projectPackageJson = await $readJsonObject(path.join(projectPath, 'package.json'));
+        if (projectPackageJson === null) {
+            return [];
+        }
+        const installations = await Promise.all(PROMPTBOOK_CLI_NPM_PACKAGE_NAMES.map(async (npmPackageName) => {
+            const installationLocation = resolveLocalPromptbookCliInstallationLocation(projectPackageJson, npmPackageName);
+            if (installationLocation === undefined) {
+                return undefined;
+            }
+            const installedVersion = await $resolveInstalledNpmPackageVersion(path.join(projectPath, 'node_modules'), npmPackageName);
+            if (installedVersion === undefined) {
+                return undefined;
+            }
+            return { npmPackageName, installedVersion, installationLocation };
+        }));
+        return installations.filter(isDefined);
+    }
+    /**
+     * Finds Promptbook CLI packages installed in npm's global `node_modules` directory.
+     *
+     * @private internal utility of `$resolvePromptbookCliInstallations`
+     */
+    async function $resolveGlobalPromptbookCliInstallations() {
+        const globalNodeModulesPath = await $resolveNpmGlobalNodeModulesPath();
+        if (globalNodeModulesPath === null) {
+            return [];
+        }
+        const installations = await Promise.all(PROMPTBOOK_CLI_NPM_PACKAGE_NAMES.map(async (npmPackageName) => {
+            const installedVersion = await $resolveInstalledNpmPackageVersion(globalNodeModulesPath, npmPackageName);
+            if (installedVersion === undefined) {
+                return undefined;
+            }
+            return {
+                npmPackageName,
+                installedVersion,
+                installationLocation: 'global',
+            };
+        }));
+        return installations.filter(isDefined);
+    }
+    /**
+     * Resolves the current project's manifest section that declares a Promptbook CLI package.
+     *
+     * @private internal utility of `$resolvePromptbookCliInstallations`
+     */
+    function resolveLocalPromptbookCliInstallationLocation(packageJson, npmPackageName) {
+        if (readNestedStringProperty(packageJson, 'dependencies', npmPackageName) !== undefined) {
+            return 'local-dependency';
+        }
+        if (readNestedStringProperty(packageJson, 'devDependencies', npmPackageName) !== undefined) {
+            return 'local-development-dependency';
+        }
+        return undefined;
+    }
+    /**
+     * Reads an installed npm package version from a `node_modules` directory.
+     *
+     * @private internal utility of `$resolvePromptbookCliInstallations`
+     */
+    async function $resolveInstalledNpmPackageVersion(nodeModulesPath, npmPackageName) {
+        const installedPackageJson = await $readJsonObject(path.join(nodeModulesPath, npmPackageName, 'package.json'));
+        return installedPackageJson === null ? undefined : readStringProperty(installedPackageJson, 'version');
+    }
+    /**
+     * Resolves npm's global `node_modules` directory without querying the registry.
+     *
+     * @private internal utility of `$resolvePromptbookCliInstallations`
+     */
+    async function $resolveNpmGlobalNodeModulesPath() {
+        const output = await $execCommand({
+            command: 'npm root --global',
+            crashOnError: true,
+            timeout: NPM_GLOBAL_NODE_MODULES_PATH_COMMAND_TIMEOUT_MS,
+            isVerbose: false,
+        }).catch(() => '');
+        const globalNodeModulesPath = output.trim();
+        return globalNodeModulesPath === '' ? null : globalNodeModulesPath;
+    }
+    /**
+     * Reads a JSON object, returning `null` for missing or malformed files because update checks must stay advisory.
+     *
+     * @private internal utility of `$resolvePromptbookCliInstallations`
+     */
+    async function $readJsonObject(filePath) {
+        try {
+            const parsedValue = JSON.parse(await promises.readFile(filePath, 'utf8'));
+            return isJsonObject(parsedValue) ? parsedValue : null;
+        }
+        catch (_a) {
+            return null;
+        }
+    }
+    /**
+     * Checks whether an unknown value can be read as a JSON object.
+     *
+     * @private internal utility of `$resolvePromptbookCliInstallations`
+     */
+    function isJsonObject(value) {
+        return typeof value === 'object' && value !== null && !Array.isArray(value);
+    }
+    /**
+     * Reads one string property from a JSON object.
+     *
+     * @private internal utility of `$resolvePromptbookCliInstallations`
+     */
+    function readStringProperty(jsonObject, propertyName) {
+        const value = jsonObject[propertyName];
+        return typeof value === 'string' ? value : undefined;
+    }
+    /**
+     * Reads one string property nested under another JSON object property.
+     *
+     * @private internal utility of `$resolvePromptbookCliInstallations`
+     */
+    function readNestedStringProperty(jsonObject, parentPropertyName, propertyName) {
+        const nestedValue = jsonObject[parentPropertyName];
+        return isJsonObject(nestedValue) ? readStringProperty(nestedValue, propertyName) : undefined;
+    }
+    /**
+     * Narrows an array after `undefined` values were removed.
+     *
+     * @private internal utility of `$resolvePromptbookCliInstallations`
+     */
+    function isDefined(value) {
+        return value !== undefined;
+    }
+    // Note: [🟡] Code for Promptbook CLI installation detection [$resolvePromptbookCliInstallations](src/cli/cli-commands/common/promptbook-cli/$resolvePromptbookCliInstallations.ts) should never be published outside of `@promptbook/cli`
+
+    /**
+     * Checks every local and global Promptbook CLI installation against the newest npm version.
+     *
+     * Note: `$` is used to indicate that this function is not a pure function - it reads installed packages and queries npm
+     *
+     * @private internal utility of `promptbookCli`
+     */
+    async function $checkPromptbookCliInstallations() {
+        const installations = await $resolvePromptbookCliInstallations();
+        if (installations.length === 0) {
+            return [];
+        }
+        const latestVersionsByNpmPackageName = await $resolveLatestVersionsByNpmPackageName(installations);
+        return installations.map((installation) => {
+            var _a;
+            const latestVersion = (_a = latestVersionsByNpmPackageName.get(installation.npmPackageName)) !== null && _a !== void 0 ? _a : null;
+            return {
+                installation,
+                installationState: resolvePromptbookCliInstallationState(installation.installedVersion, latestVersion),
+                latestVersion,
+            };
+        });
+    }
+    /**
+     * Resolves each package's newest version once, even when it is installed locally and globally.
+     *
+     * @private internal utility of `$checkPromptbookCliInstallations`
+     */
+    async function $resolveLatestVersionsByNpmPackageName(installations) {
+        const npmPackageNames = Array.from(new Set(installations.map(({ npmPackageName }) => npmPackageName)));
+        const latestVersionEntries = await Promise.all(npmPackageNames.map(async (npmPackageName) => {
+            const latestVersion = await $resolveLatestNpmPackageVersion(npmPackageName);
+            return [npmPackageName, latestVersion];
+        }));
+        return new Map(latestVersionEntries);
+    }
+    /**
+     * Derives the update state of one installed Promptbook CLI package.
+     *
+     * @private internal utility of `$checkPromptbookCliInstallations`
+     */
+    function resolvePromptbookCliInstallationState(installedVersion, latestVersion) {
+        if (latestVersion === null) {
+            return 'unknown';
+        }
+        return isNpmPackageVersionOutdated(installedVersion, latestVersion) ? 'outdated' : 'up-to-date';
+    }
+    // Note: [🟡] Code for Promptbook CLI installation check [$checkPromptbookCliInstallations](src/cli/cli-commands/common/promptbook-cli/$checkPromptbookCliInstallations.ts) should never be published outside of `@promptbook/cli`
+
+    /**
+     * Builds the npm command that updates one existing Promptbook CLI installation.
+     *
+     * @private internal utility of `promptbookCli`
+     */
+    function buildPromptbookCliInstallCommand(installation) {
+        const { npmPackageName, installationLocation } = installation;
+        if (installationLocation === 'global') {
+            return `npm install --global ${npmPackageName}@latest`;
+        }
+        if (installationLocation === 'local-development-dependency') {
+            return `npm install --save-dev ${npmPackageName}@latest`;
+        }
+        return `npm install --save ${npmPackageName}@latest`;
+    }
+    // Note: [🟡] Code for Promptbook CLI installation command [buildPromptbookCliInstallCommand](src/cli/cli-commands/common/promptbook-cli/buildPromptbookCliInstallCommand.ts) should never be published outside of `@promptbook/cli`
+
+    /**
+     * Updates one Promptbook CLI package in its existing local or global location.
+     *
+     * Note: `$` is used to indicate that this function is not a pure function - it installs an npm package
+     *
+     * @returns `true` when the package update succeeds, `false` when it fails
+     * @private internal utility of `promptbookCli`
+     */
+    async function $updatePromptbookCliInstallation(status) {
+        const { npmPackageName } = status.installation;
+        const installCommand = buildPromptbookCliInstallCommand(status.installation);
+        console.info(colors__default["default"].cyan(`Updating Promptbook CLI package \`${npmPackageName}\` with \`${installCommand}\`...`));
+        try {
+            await $execCommand({
+                command: installCommand,
+                crashOnError: true,
+                isVerbose: true,
+            });
+        }
+        catch (error) {
+            assertsError(error);
+            const updateErrorMessage = error.message;
+            console.error(colors__default["default"].red(_spaceTrim.spaceTrim((block) => `
+                        Could not update **Promptbook CLI** package \`${npmPackageName}\`.
+
+                        Update it manually with \`${installCommand}\` and run the command again.
+
+                        ${block(updateErrorMessage)}
+                    `)));
+            return false;
+        }
+        console.info(colors__default["default"].green(`Promptbook CLI package \`${npmPackageName}\` has been updated.`));
+        return true;
+    }
+    // Note: [🟡] Code for Promptbook CLI installation update [$updatePromptbookCliInstallation](src/cli/cli-commands/common/promptbook-cli/$updatePromptbookCliInstallation.ts) should never be published outside of `@promptbook/cli`
+
+    /**
+     * Formats the warning shown when one or more Promptbook CLI installations are outdated.
+     *
+     * @private internal utility of `promptbookCli`
+     */
+    function formatPromptbookCliInstallationWarning(statuses) {
+        const statusLines = statuses.map((status) => {
+            const { npmPackageName, installedVersion, installationLocation } = status.installation;
+            return `- ${formatPromptbookCliInstallationLocation(installationLocation)} \`${npmPackageName}\`: installed \`${installedVersion}\`, newest \`${status.latestVersion}\``;
+        });
+        return _spaceTrim.spaceTrim((block) => `
+            **Promptbook CLI** is outdated.
+
+            ${block(statusLines.join('\n'))}
+        `);
+    }
+    /**
+     * Describes an installation location in text suitable for an update warning.
+     *
+     * @private internal utility of `formatPromptbookCliInstallationWarning`
+     */
+    function formatPromptbookCliInstallationLocation(installationLocation) {
+        if (installationLocation === 'global') {
+            return 'Globally installed';
+        }
+        if (installationLocation === 'local-development-dependency') {
+            return 'Locally in `devDependencies`';
+        }
+        return 'Locally in `dependencies`';
+    }
+    // Note: [🟡] Code for Promptbook CLI installation warning [formatPromptbookCliInstallationWarning](src/cli/cli-commands/common/promptbook-cli/formatPromptbookCliInstallationWarning.ts) should never be published outside of `@promptbook/cli`
+
+    /**
+     * Checks local and global Promptbook CLI installations before an interactive coder run and offers to update them.
+     *
+     * Once an update is approved, the caller must stop the current run and let the user start a fresh process. A local
+     * npm update can modify `package.json` and a lockfile, which would make the coder's working-tree preflight fail;
+     * more importantly, this Node.js process has already loaded the old CLI implementation.
+     *
+     * Note: `$` is used to indicate that this function is not a pure function - it reads package manifests, queries npm,
+     * asks the user, and may install npm packages
+     *
+     * @returns `true` when an update was approved and the current coder run should stop
+     * @private internal utility of `promptbookCli`
+     */
+    async function $ensurePromptbookCliInstallations() {
+        if (!process.stdin.isTTY) {
+            // Note: Non-interactive runs cannot approve an update and should not wait for registry checks.
+            return false;
+        }
+        const statuses = await $checkPromptbookCliInstallations();
+        const outdatedStatuses = statuses.filter(({ installationState }) => installationState === 'outdated');
+        if (outdatedStatuses.length === 0) {
+            reportPromptbookCliInstallationStatuses(statuses);
+            return false;
+        }
+        console.warn(colors__default["default"].yellow(formatPromptbookCliInstallationWarning(outdatedStatuses)));
+        const isUpdateApproved = await $askForNpmPackageInstallationApproval('Update Promptbook CLI now?');
+        if (!isUpdateApproved) {
+            const manualInstallCommands = outdatedStatuses
+                .map((status) => `- \`${buildPromptbookCliInstallCommand(status.installation)}\``)
+                .join('\n');
+            console.info(colors__default["default"].gray(_spaceTrim.spaceTrim((block) => `
+                        Skipped updating Promptbook CLI.
+
+                        Run one of these commands manually:
+
+                        ${block(manualInstallCommands)}
+                    `)));
+            return false;
+        }
+        for (const status of outdatedStatuses) {
+            await $updatePromptbookCliInstallation(status);
+        }
+        console.info(colors__default["default"].green('Promptbook CLI update is complete. Run the command again to use the new version.'));
+        return true;
+    }
+    /**
+     * Reports successful and unverifiable Promptbook CLI checks when no update is required.
+     *
+     * @private internal utility of `$ensurePromptbookCliInstallations`
+     */
+    function reportPromptbookCliInstallationStatuses(statuses) {
+        for (const status of statuses) {
+            const { npmPackageName, installedVersion } = status.installation;
+            if (status.installationState === 'up-to-date') {
+                console.info(colors__default["default"].gray(`✔ Promptbook CLI \`${npmPackageName}\` ${installedVersion} is up to date.`));
+                continue;
+            }
+            if (status.installationState === 'unknown') {
+                console.info(colors__default["default"].gray(`✔ Promptbook CLI \`${npmPackageName}\` ${installedVersion} is installed; the newest version could not be checked.`));
+            }
+        }
+    }
+    // Note: [🟡] Code for Promptbook CLI installation orchestration [$ensurePromptbookCliInstallations](src/cli/cli-commands/common/promptbook-cli/$ensurePromptbookCliInstallations.ts) should never be published outside of `@promptbook/cli`
+
     /**
      * Modes supported by `ptbk coder run --test-before`.
      */
@@ -40928,12 +41991,14 @@
 
             Features:
             - Automatically stages and commits changes with agent identity unless --no-commit is used
+            - Commits only the prompt file and the files the coding agent has changed, leaving unrelated changes alone
             - Optional post-commit git push with explicit --auto-push opt-in
             - Optional pre-prompt git pull with explicit --auto-pull opt-in
             - Optional --isolate runs every prompt in its own temporary git worktree and merges it back when verified
             - Optional --preserve-logs keeps temp prompt/log artifacts after successful rounds
             - Optional --no-ui keeps plain streaming console output for logging and debugging
             - Checks that the selected harness is installed globally and up to date before the first prompt
+            - In interactive mode, checks local and global Promptbook CLI installations and offers to update them
             - Supports GPG signing of commits
             - Optional pre-coding test run that can stop or repair pre-existing failures
             - Optional post-prompt verification with test-feedback retries
@@ -40983,7 +42048,6 @@
             const runnerOptions = normalizePromptRunnerCliOptions(cliOptions, {
                 isAgentRequired: !dryRun,
             });
-            await $ensureHarnessInstallations([runnerOptions.agentName]);
             // [1] Parse the wait options and --no-auto:
             //   default: run automatically through the queue (no waiting between prompts)
             //   --no-auto: wait for user confirmation before each prompt (interactive mode)
@@ -40991,6 +42055,10 @@
             //   --wait-between-prompts: pace from start of one prompt to start of next
             //   --wait-after-error: wait before retrying after an error (default 10m)
             const waitForUser = !auto;
+            if (waitForUser && (await $ensurePromptbookCliInstallations())) {
+                return process.exit(0);
+            }
+            await $ensureHarnessInstallations([runnerOptions.agentName]);
             const waitAfterPrompt = parseOptionalWaitDuration(waitAfterPromptValue, 0);
             const waitBetweenPrompts = parseOptionalWaitDuration(waitBetweenPromptsValue, 0);
             const waitAfterError = parseOptionalWaitDuration(waitAfterErrorValue, DEFAULT_WAIT_AFTER_ERROR_MS$1);
@@ -44067,8 +45135,8 @@
          */
         $applyToTaskJson(command, $taskJson) {
             if ($taskJson.format !== undefined && command.format !== $taskJson.format) {
-                throw new ParseError(`Format format is already defined to "${$taskJson.format}".
-                Now you try to redefine it by "${command.format}"`);
+                throw new ParseError(_spaceTrim.spaceTrim(`Format format is already defined to "${$taskJson.format}".
+                Now you try to redefine it by "${command.format}"`));
             }
             $taskJson.format = command.format;
         },
@@ -56911,28 +57979,28 @@
      */
     function buildToolInvocationScript(options) {
         const { functionName, functionArgsExpression } = options;
-        return `
-        const args = ${functionArgsExpression};
-        const runtimeContextRaw =
-            typeof ${TOOL_RUNTIME_CONTEXT_PARAMETER} === 'undefined'
-                ? undefined
-                : ${TOOL_RUNTIME_CONTEXT_PARAMETER};
+        return _spaceTrim.spaceTrim((block) => `
+            const args = ${block(functionArgsExpression)};
+            const runtimeContextRaw =
+                typeof ${TOOL_RUNTIME_CONTEXT_PARAMETER} === 'undefined'
+                    ? undefined
+                    : ${TOOL_RUNTIME_CONTEXT_PARAMETER};
 
-        if (runtimeContextRaw !== undefined && args && typeof args === 'object' && !Array.isArray(args)) {
-            args.${TOOL_RUNTIME_CONTEXT_ARGUMENT} = runtimeContextRaw;
-        }
+            if (runtimeContextRaw !== undefined && args && typeof args === 'object' && !Array.isArray(args)) {
+                args.${TOOL_RUNTIME_CONTEXT_ARGUMENT} = runtimeContextRaw;
+            }
 
-        const toolProgressTokenRaw =
-            typeof ${TOOL_PROGRESS_TOKEN_PARAMETER} === 'undefined'
-                ? undefined
-                : ${TOOL_PROGRESS_TOKEN_PARAMETER};
+            const toolProgressTokenRaw =
+                typeof ${TOOL_PROGRESS_TOKEN_PARAMETER} === 'undefined'
+                    ? undefined
+                    : ${TOOL_PROGRESS_TOKEN_PARAMETER};
 
-        if (toolProgressTokenRaw !== undefined && args && typeof args === 'object' && !Array.isArray(args)) {
-            args.${TOOL_PROGRESS_TOKEN_ARGUMENT} = toolProgressTokenRaw;
-        }
+            if (toolProgressTokenRaw !== undefined && args && typeof args === 'object' && !Array.isArray(args)) {
+                args.${TOOL_PROGRESS_TOKEN_ARGUMENT} = toolProgressTokenRaw;
+            }
 
-        return await ${functionName}(args);
-    `;
+            return await ${functionName}(args);
+        `);
     }
 
     /**
@@ -68878,6 +69946,28 @@
         RemoteAgent: RemoteAgent
     });
 
+    /**
+     * Captures the working tree state before one `ptbk coder` operation changes anything.
+     *
+     * The captured scope is passed to the commit of the very same operation, which then commits exactly the files
+     * this operation has created, changed, moved or deleted.
+     */
+    async function captureCoderCommitScope(projectPath) {
+        return {
+            projectPath,
+            snapshotBeforeOperation: await captureWorkingTreeChangesSnapshot(projectPath),
+        };
+    }
+    /**
+     * Resolves the repository-relative paths which one `ptbk coder` operation has really changed.
+     *
+     * Files which were already changed before the operation started and which the operation did not touch are
+     * never part of the result, so they stay in the working tree instead of being swept into the commit.
+     */
+    async function resolveCoderCommitScopePaths(scope) {
+        return listFilesChangedSinceSnapshot(scope.projectPath, scope.snapshotBeforeOperation);
+    }
+
     /**
      * Git synchronization which leaves the repository completely untouched.
      *
@@ -68888,6 +69978,24 @@
         isAutoPushEnabled: false,
         isAutoPullEnabled: false,
     });
+    /**
+     * Pulls the latest repository changes and captures the working tree state before a `ptbk coder` command
+     * changes the project.
+     *
+     * The returned scope is handed over to `$commitCoderChanges` of the very same command, which then commits
+     * exactly the files this command has changed.
+     */
+    async function $startCoderGitSync(options) {
+        const { gitSync, projectPath = process.cwd() } = options;
+        await $pullCoderChanges({ gitSync, projectPath });
+        if (!gitSync.isCommitEnabled) {
+            // Note: A command which does not commit must not touch git at all, so that it also works in a project
+            //       which is not a git repository
+            return { projectPath, snapshotBeforeOperation: { changedFileHashes: new Map() } };
+        }
+        // Note: The scope is captured after pulling, so files brought in by the pull are not committed again
+        return captureCoderCommitScope(projectPath);
+    }
     /**
      * Pulls the latest repository changes before a `ptbk coder` command changes the project.
      */
@@ -68902,38 +70010,31 @@
     /**
      * Commits - and when requested also pushes - the changes one `ptbk coder` command has just made.
      *
-     * Note: A repository without any change is left alone instead of creating an empty commit.
+     * Note: Only the files this very command has changed are committed, everything else is left in the working tree.
+     * Note: A command which changed nothing is left alone instead of creating an empty commit.
      */
     async function $commitCoderChanges(options) {
-        const { gitSync, commitMessage, projectPath = process.cwd() } = options;
+        const { gitSync, commitMessage, commitScope } = options;
         if (!gitSync.isCommitEnabled) {
             return;
         }
-        if (!(await hasChangesToCommit(projectPath))) {
-            console.info(colors__default["default"].gray('Nothing to commit, the working tree is clean'));
+        const relevantPaths = await resolveCoderCommitScopePaths(commitScope);
+        if (relevantPaths.length === 0) {
+            console.info(colors__default["default"].gray('Nothing to commit, this command has not changed any file'));
             return;
         }
         await commitChanges(commitMessage, {
-            projectPath,
+            projectPath: commitScope.projectPath,
+            relevantPaths,
             autoPush: gitSync.isAutoPushEnabled,
         });
         console.info(colors__default["default"].green(`✓ ${gitSync.isAutoPushEnabled ? 'Committed and pushed' : 'Committed'}: ${commitMessage}`));
     }
-    /**
-     * Checks whether the repository holds any change which can be committed.
-     */
-    async function hasChangesToCommit(projectPath) {
-        const gitStatus = await runGitCommand({
-            command: 'git status --porcelain',
-            cwd: projectPath,
-            isVerbose: false,
-        });
-        return gitStatus.trim() !== '';
-    }
 
     var coderGitSync = /*#__PURE__*/Object.freeze({
         __proto__: null,
         DISABLED_CODER_GIT_SYNC_OPTIONS: DISABLED_CODER_GIT_SYNC_OPTIONS,
+        $startCoderGitSync: $startCoderGitSync,
         $pullCoderChanges: $pullCoderChanges,
         $commitCoderChanges: $commitCoderChanges
     });
@@ -72271,34 +73372,34 @@
      * @private function of runDatabaseMigrations
      */
     async function ensureMigrationsTableSchema(options) {
-        await options.client.query(`
+        await options.client.query(_spaceTrim.spaceTrim(`
         CREATE TABLE IF NOT EXISTS ${options.migrationsTableIdentifier} (
             "filename" TEXT PRIMARY KEY,
             "appliedAt" TIMESTAMP WITH TIME ZONE DEFAULT now(),
             "appliedBy" TEXT NOT NULL DEFAULT '${options.manualAppliedByDefault}'
         );
-    `);
-        await options.client.query(`
+    `));
+        await options.client.query(_spaceTrim.spaceTrim(`
         ALTER TABLE ${options.migrationsTableIdentifier}
         ADD COLUMN IF NOT EXISTS "appliedBy" TEXT;
-    `);
-        await options.client.query(`
+    `));
+        await options.client.query(_spaceTrim.spaceTrim(`
         UPDATE ${options.migrationsTableIdentifier}
         SET "appliedBy" = $1
         WHERE "appliedBy" IS NULL;
-        `, [options.manualAppliedByDefault]);
-        await options.client.query(`
+        `), [options.manualAppliedByDefault]);
+        await options.client.query(_spaceTrim.spaceTrim(`
         ALTER TABLE ${options.migrationsTableIdentifier}
         ALTER COLUMN "appliedBy" SET DEFAULT '${options.manualAppliedByDefault}';
-    `);
-        await options.client.query(`
+    `));
+        await options.client.query(_spaceTrim.spaceTrim(`
         ALTER TABLE ${options.migrationsTableIdentifier}
         ALTER COLUMN "appliedBy" SET NOT NULL;
-    `);
-        await options.client.query(`
+    `));
+        await options.client.query(_spaceTrim.spaceTrim(`
         ALTER TABLE ${options.migrationsTableIdentifier}
         ENABLE ROW LEVEL SECURITY;
-    `);
+    `));
     }
     /**
      * Rolls back an opened transaction and logs failures without masking original errors.
@@ -73256,9 +74357,9 @@
         });
         const promptExecutionStartedDate = moment__default["default"]();
         let attemptCount = 1;
-        const roundChangedFilesSnapshot = options.normalizeLineEndings
-            ? await captureChangedFilesSnapshot(roundProjectPath)
-            : undefined;
+        // Note: The very same snapshot tells which files this round has changed, both for normalizing their line
+        //       endings and for committing only them instead of everything which is changed in the project
+        const roundCommitScope = await captureRoundCommitScopeIfNeeded(options, roundProjectPath);
         await withPromptRuntimeLog(scriptPath, async (logPath) => {
             let lastError;
             for (let errorRetryAttempt = 0; errorRetryAttempt <= MAX_RETRY_ATTEMPTS_AFTER_ERROR; errorRetryAttempt++) {
@@ -73294,7 +74395,7 @@
                         result,
                         commitMessage,
                         logPath,
-                        roundChangedFilesSnapshot,
+                        roundCommitScope,
                         isRichUiEnabled,
                         progressDisplay,
                         uiHandle,
@@ -73327,7 +74428,7 @@
                 attemptCount,
                 error: lastError,
                 options,
-                roundChangedFilesSnapshot,
+                roundCommitScope,
                 uiHandle,
                 waitForRequestedPause,
                 roundProjectPath,
@@ -73408,7 +74509,7 @@
      * Finalizes a successful prompt round, including prompt bookkeeping and commit flow.
      */
     async function finalizeSuccessfulPromptRound(options) {
-        const { options: runOptions, nextPrompt, runnerMetadata, promptExecutionStartedDate, result, commitMessage, logPath, roundChangedFilesSnapshot, isRichUiEnabled, progressDisplay, uiHandle, waitForRequestedPause, roundProjectPath, } = options;
+        const { options: runOptions, nextPrompt, runnerMetadata, promptExecutionStartedDate, result, commitMessage, logPath, roundCommitScope, isRichUiEnabled, progressDisplay, uiHandle, waitForRequestedPause, roundProjectPath, } = options;
         uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.stopCapturingAgentOutput();
         await waitForRequestedPause({
             checkpointLabel: 'recording the successful prompt result',
@@ -73419,7 +74520,7 @@
         // Note: The prompt status is always written into the original project, an isolated round transports
         //       its own changes back through the merge instead
         await writePromptFile(nextPrompt.file);
-        await normalizeLineEndingsForCurrentRound(runOptions, roundProjectPath, roundChangedFilesSnapshot);
+        await normalizeLineEndingsForCurrentRound(runOptions, roundProjectPath, roundCommitScope);
         await recordPromptDurationInEstimateCache({
             options: runOptions,
             runnerMetadata,
@@ -73440,6 +74541,9 @@
             });
             await commitChanges(commitMessage, {
                 autoPush: runOptions.autoPush,
+                // Note: Only the prompt file and the files the coding agent has changed belong to this round,
+                //       everything which was already changed before the round started stays in the working tree
+                relevantPaths: roundCommitScope && (await resolveCoderCommitScopePaths(roundCommitScope)),
                 // Keep the live runtime log out of default commits because it is deleted after a successful round.
                 excludePaths: runOptions.preserveLogs ? undefined : [logPath],
                 projectPath: roundProjectPath,
@@ -73463,7 +74567,7 @@
      * Finalizes a failed prompt round, persisting prompt failure metadata before rethrowing.
      */
     async function finalizeFailedPromptRound(options) {
-        const { nextPrompt, runnerMetadata, promptExecutionStartedDate, attemptCount, error, options: runOptions, roundChangedFilesSnapshot, uiHandle, waitForRequestedPause, roundProjectPath, } = options;
+        const { nextPrompt, runnerMetadata, promptExecutionStartedDate, attemptCount, error, options: runOptions, roundCommitScope, uiHandle, waitForRequestedPause, roundProjectPath, } = options;
         uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.stopCapturingAgentOutput();
         uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.setPhase('error');
         uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.addError(error instanceof Error ? error.message : String(error));
@@ -73481,7 +74585,7 @@
             modelName: runnerMetadata.modelName,
             error,
         });
-        await normalizeLineEndingsForCurrentRound(runOptions, roundProjectPath, roundChangedFilesSnapshot);
+        await normalizeLineEndingsForCurrentRound(runOptions, roundProjectPath, roundCommitScope);
     }
     /**
      * Waits for the optional user confirmation immediately before creating the commit.
@@ -73547,17 +74651,29 @@
             thinkingLevel: runOptions.thinkingLevel,
         }, promptDurationMs);
     }
+    /**
+     * Captures which files are already changed before the round starts, when the round needs to know it later.
+     *
+     * The scope is needed to commit only the files of this round and to normalize the line endings of exactly
+     * those files, so a round which does neither of them does not pay for hashing the working tree.
+     */
+    async function captureRoundCommitScopeIfNeeded(options, roundProjectPath) {
+        if (options.noCommit && !options.normalizeLineEndings) {
+            return undefined;
+        }
+        return captureCoderCommitScope(roundProjectPath);
+    }
     /**
      * Normalizes line endings in files modified during the current coding round.
      */
-    async function normalizeLineEndingsForCurrentRound(options, roundProjectPath, roundChangedFilesSnapshot) {
-        if (!options.normalizeLineEndings || !roundChangedFilesSnapshot) {
+    async function normalizeLineEndingsForCurrentRound(options, roundProjectPath, roundCommitScope) {
+        if (!options.normalizeLineEndings || !roundCommitScope) {
             return;
         }
         try {
             const result = await normalizeLineEndingsInFilesChangedSinceSnapshot({
                 projectPath: roundProjectPath,
-                snapshot: roundChangedFilesSnapshot,
+                snapshot: roundCommitScope.snapshotBeforeOperation,
             });
             if (result.normalizedFiles > 0) {
                 console.info(colors__default["default"].gray(`Normalized line endings to LF in ${result.normalizedFiles} changed file(s).`));
@@ -73618,11 +74734,11 @@
      * Builds the markdown list of commands which merge one isolated task manually and clean it up.
      */
     function buildManualRecoveryHints(worktree) {
-        return [
-            `- \`git merge ${worktree.branchName}\` and resolve the conflicts`,
-            `- \`git worktree remove ${worktree.worktreeDisplayPath}\``,
-            `- \`git branch -d ${worktree.branchName}\``,
-        ].join('\n');
+        return _spaceTrim.spaceTrim(`
+        - \`git merge ${worktree.branchName}\` and resolve the conflicts
+        - \`git worktree remove ${worktree.worktreeDisplayPath}\`
+        - \`git branch -d ${worktree.branchName}\`
+    `);
     }
 
     /**
@@ -74078,6 +75194,9 @@
         var _a;
         const { nextPrompt, promptLabel, isRichUiEnabled, uiHandle, waitForRequestedPause } = options;
         const projectPath = (_a = options.projectPath) !== null && _a !== void 0 ? _a : process.cwd();
+        // Note: The original project is left untouched by the isolated round itself, so its scope covers exactly
+        //       the prompt status update and the changes the merge brings back from the worktree
+        const originalProjectCommitScope = await captureCoderCommitScope(projectPath);
         const worktree = await createCoderIsolationWorktree({
             projectPath,
             taskName: buildCoderIsolationTaskName(nextPrompt.file, nextPrompt.section),
@@ -74109,6 +75228,7 @@
         // Note: The merge only stages the isolated changes, so this commit joins them with the prompt status update
         await commitChanges(buildCommitMessage(nextPrompt.file, nextPrompt.section), {
             autoPush: options.options.autoPush,
+            relevantPaths: await resolveCoderCommitScopePaths(originalProjectCommitScope),
             projectPath,
         });
         await removeCoderIsolationWorktree(worktree);
@@ -74132,7 +75252,7 @@
         await commitChanges(buildCoderIsolationMergeFailureCommitMessage(worktree), {
             autoPush: options.options.autoPush,
             projectPath: worktree.projectPath,
-            includePaths: [nextPrompt.file.path, errorLogPath].map((path) => toProjectRelativeGitPath(worktree.projectPath, path)),
+            relevantPaths: [nextPrompt.file.path, errorLogPath].map((path) => toProjectRelativeGitPath(worktree.projectPath, path)),
         });
         uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.addError(mergeFailureError.message);
         uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.setStatusMessage(`Merging \`${worktree.taskName}\` failed, worktree kept for a manual merge`);
@@ -74287,26 +75407,22 @@
      * 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 terminal variant uses a transparent horizontal canvas instead of the website's framed 1:1 surface.
+     * commitment wins, then the `META VISUAL` commitment, then the shared default visual.
+     * Character-based visuals such as `AsciiOctopus` paint the terminal grid directly, while pixel-based
+     * visuals are rendered through the shared canvas avatar pipeline into terminal ASCII art, using a
+     * transparent horizontal canvas instead of the website's framed 1:1 surface.
      *
-     * 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.
+     * The visual is decorative, so any failure returns `null` and the caller keeps the default brand banner.
      *
      * @param agentSource Source of the `--agent` book file.
      * @returns ANSI-colored ASCII-art renderer 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 colorDepth = $detectTerminalAnsiColorDepth();
-            const createCanvasForAsciiArt = (width, height) => createCanvas(width, height);
             const agentVisual = createTerminalAgentAvatarVisual({
                 agentSource,
-                colorDepth,
-                createCanvas: createCanvasForAsciiArt,
+                colorDepth: $detectTerminalAnsiColorDepth(),
+                createCanvas: await createOptionalNodeCanvasFactory(),
             });
             return {
                 isAnimated: agentVisual.isAnimated,
@@ -74325,6 +75441,23 @@
             return null;
         }
     }
+    /**
+     * Loads the optional Node.js canvas factory which rasterizes pixel-based avatar visuals.
+     *
+     * @returns Canvas factory or `undefined` when the optional native module is not installed.
+     *
+     * @private helper of `buildCoderRunAgentVisual`
+     */
+    async function createOptionalNodeCanvasFactory() {
+        try {
+            // Note: `@napi-rs/canvas` is an optional native module, so it is imported dynamically and lazily
+            const { createCanvas } = await import('@napi-rs/canvas');
+            return (width, height) => createCanvas(width, height);
+        }
+        catch (error) {
+            return undefined;
+        }
+    }
 
     /**
      * Creates the one queue prompt used to repair a pre-existing test failure.
@@ -75303,7 +76436,7 @@
      *
      * @private internal constant of `ptbk coder server`
      */
-    const CODER_SERVER_HTML = `<!DOCTYPE html>
+    const CODER_SERVER_HTML = _spaceTrim.spaceTrim(`<!DOCTYPE html>
 <html lang="en">
 <head>
   <meta charset="UTF-8">
@@ -75989,7 +77122,7 @@
   </script>
 </body>
 </html>
-`;
+`);
     // Note: [🟡] Code for CLI command [coder server](scripts/run-codex-prompts/server/coderServerHtml.ts) should never be published outside of `@promptbook/cli`
     // Note: Keep in sync with apps/coder-server/index.html
 
@@ -76181,8 +77314,7 @@
     async function commitPromptEdit(promptFilePath, sectionIndex) {
         const relativePromptFilePath = path.relative(process.cwd(), promptFilePath).replace(/\\/gu, '/');
         await commitChanges(`Edit coder prompt ${relativePromptFilePath}#${sectionIndex + 1}`, {
-            includePaths: [relativePromptFilePath],
-            onlyPaths: [relativePromptFilePath],
+            relevantPaths: [relativePromptFilePath],
         });
     }
     /**
@@ -76327,8 +77459,9 @@
         let promptFiles = initialFiles;
         const skippedFiles = new Set();
         while (true) {
-            // Note: The git synchronization is applied around each single verification, not once per whole run
-            await $pullCoderChanges({ gitSync: normalizedOptions.gitSync });
+            // Note: The git synchronization is applied around each single verification, not once per whole run,
+            //       so each verification commits only the prompt file it has archived or repaired
+            const commitScope = await $startCoderGitSync({ gitSync: normalizedOptions.gitSync });
             if (normalizedOptions.gitSync.isAutoPullEnabled) {
                 // Note: The pull can bring in prompt file changes, so the queue is reloaded before it is used
                 promptFiles = (await loadPromptFilesForVerification(normalizedOptions)).promptFiles;
@@ -76341,7 +77474,7 @@
                 if (outcome.wasSkipped) {
                     skippedFiles.add(fileWithAllDone.path);
                 }
-                await $commitVerificationOutcome(normalizedOptions.gitSync, outcome);
+                await $commitVerificationOutcome(normalizedOptions.gitSync, commitScope, outcome);
                 promptFiles = (await loadPromptFilesForVerification(normalizedOptions)).promptFiles;
                 continue;
             }
@@ -76352,18 +77485,18 @@
                 break;
             }
             const outcome = await resolvePrompt(nextPrompt);
-            await $commitVerificationOutcome(normalizedOptions.gitSync, outcome);
+            await $commitVerificationOutcome(normalizedOptions.gitSync, commitScope, outcome);
             promptFiles = (await loadPromptFilesForVerification(normalizedOptions)).promptFiles;
         }
     }
     /**
      * Commits and pushes one applied verification when the git synchronization is enabled.
      */
-    async function $commitVerificationOutcome(gitSync, outcome) {
+    async function $commitVerificationOutcome(gitSync, commitScope, outcome) {
         if (outcome.commitMessage === null) {
             return;
         }
-        await $commitCoderChanges({ gitSync, commitMessage: outcome.commitMessage });
+        await $commitCoderChanges({ gitSync, commitScope, commitMessage: outcome.commitMessage });
     }
     /**
      * Parses supported command-line arguments for the standalone verification script.