@promptbook/cli 0.114.0-33 → 0.114.0-34

package/umd/index.umd.js

@@ -58,7 +58,7 @@
      * @generated
      * @see https://github.com/webgptorg/promptbook
      */
-    const PROMPTBOOK_ENGINE_VERSION = '0.114.0-33';
+    const PROMPTBOOK_ENGINE_VERSION = '0.114.0-34';
     /**
      * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
      * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -1718,6 +1718,35 @@
     // TODO: [🗽] Unite branding and make single place for it
     // Note: [💞] Ignore a discrepancy between file name and entity name
 
+    /**
+     * Message printed when one CLI command which only groups subcommands is run without picking any of them.
+     *
+     * @private internal constant of `$requireCliSubcommand`
+     */
+    const MISSING_CLI_SUBCOMMAND_MESSAGE = 'Please specify a subcommand.';
+    /**
+     * Makes one CLI command which only groups subcommands ask for a subcommand instead of doing anything on its own.
+     *
+     * Note: `$` is used to indicate that this function is not a pure function - it registers an action in the CLI
+     *
+     * @private utility of CLI
+     */
+    function $requireCliSubcommand(command) {
+        command.action(() => $reportMissingCliSubcommand(command));
+    }
+    /**
+     * Asks for a subcommand of one CLI command, prints its help and exits the process.
+     *
+     * Note: `$` is used to indicate that this function is not a pure function - it writes to the console and exits the process
+     *
+     * @private utility of CLI
+     */
+    function $reportMissingCliSubcommand(command) {
+        console.info(colors__default["default"].yellow(MISSING_CLI_SUBCOMMAND_MESSAGE));
+        console.info('');
+        return command.help();
+    }
+
     // Note: [💞] Ignore a discrepancy between file name and entity name
     /**
      * All CLI harness names supported by `CliAgent` and `ptbk agent exec`.
@@ -2113,11 +2142,7 @@
         `));
         $initializeAgentChatCommand(agentCommand);
         $initializeAgentExecCommand(agentCommand);
-        agentCommand.action(() => {
-            console.info(colors__default["default"].yellow('Please specify a subcommand.'));
-            console.info('');
-            agentCommand.help();
-        });
+        $requireCliSubcommand(agentCommand);
     }
     // Note: [🟡] Code for CLI command [agent](src/cli/cli-commands/agent.ts) should never be published outside of `@promptbook/cli`
     // Note: [💞] Ignore a discrepancy between file name and entity name
@@ -2275,6 +2300,23 @@
         }
         return 'unchanged';
     }
+    /**
+     * Checks whether a project-relative directory is missing or contains no entries.
+     *
+     * @private internal utility of `coder init` command
+     */
+    async function isDirectoryEmpty(projectPath, relativeDirectoryPath) {
+        const directoryPath = path.join(projectPath, relativeDirectoryPath);
+        try {
+            return (await promises.readdir(directoryPath)).length === 0;
+        }
+        catch (error) {
+            if (isNodeJsErrorWithCode$1(error, 'ENOENT')) {
+                return true;
+            }
+            throw error;
+        }
+    }
     /**
      * Checks whether a path exists and is a directory.
      */
@@ -2286,6 +2328,12 @@
             return false;
         }
     }
+    /**
+     * Checks whether a caught value is a Node.js error with the given error code.
+     */
+    function isNodeJsErrorWithCode$1(error, code) {
+        return typeof error === 'object' && error !== null && 'code' in error && error.code === code;
+    }
     // Note: [🟡] Code for coder init directory creation [ensureDirectory](src/cli/cli-commands/coder/ensureDirectory.ts) should never be published outside of `@promptbook/cli`
 
     /**
@@ -2573,11 +2621,7 @@
         $initializeAgentTickCommand(agentFolderCommand);
         $initializeAgentRunCommand(agentFolderCommand);
         $initializeAgentRunMultipleCommand(agentFolderCommand);
-        agentFolderCommand.action(() => {
-            console.info(colors__default["default"].yellow('Please specify a subcommand.'));
-            console.info('');
-            agentFolderCommand.help();
-        });
+        $requireCliSubcommand(agentFolderCommand);
     }
     // Note: [🟡] Code for CLI command [agent-folder](src/cli/cli-commands/agent-folder.ts) should never be published outside of `@promptbook/cli`
     // Note: [💞] Ignore a discrepancy between file name and entity name
@@ -21428,10 +21472,30 @@
         return relativePath.replace(/\\/gu, '/');
     }
 
+    /**
+     * AuthenticationError is thrown from login function which is dependency of remote server
+     *
+     * @public exported from `@promptbook/core`
+     */
+    class AuthenticationError extends Error {
+        constructor(message) {
+            super(message);
+            this.name = 'AuthenticationError';
+            Object.setPrototypeOf(this, AuthenticationError.prototype);
+        }
+    }
+
     /**
      * Formats one unknown error-like value into readable text for logs and feedback.
+     *
+     * An `AuthenticationError` is reported without its stack, because its message is written for the user - it
+     * says which harness has to be signed in again and how - and the frames of a failure nobody can debug would
+     * only push those instructions out of sight.
      */
     function formatUnknownErrorDetails(error) {
+        if (error instanceof AuthenticationError) {
+            return error.message;
+        }
         if (error instanceof Error) {
             return error.stack || error.message;
         }
@@ -24148,6 +24212,7 @@
             commandName: 'codex',
             npmPackageName: '@openai/codex',
             projectGitignoreRules: ['.codex'],
+            authenticationMethod: { command: 'codex login' },
             // Note: The official standalone installer keeps its package in `~/.codex` and links it onto the `PATH`
             standaloneInstallation: {
                 directoryNames: ['.codex'],
@@ -24160,6 +24225,7 @@
             commandName: 'copilot',
             npmPackageName: '@github/copilot',
             projectGitignoreRules: ['.github/copilot/settings.local.json'],
+            authenticationMethod: { command: 'copilot', interactiveStep: 'running the `/login` command inside it' },
             // Note: The GitHub Copilot CLI downloads its native binary in a postinstall script
             npmInstallEnvironment: { npm_config_ignore_scripts: 'false' },
         },
@@ -24169,6 +24235,7 @@
             commandName: 'cline',
             npmPackageName: 'cline',
             projectGitignoreRules: ['.cline'],
+            authenticationMethod: { command: 'cline', interactiveStep: 'signing in to the provider inside it' },
         },
         'claude-code': {
             harnessName: 'claude-code',
@@ -24176,6 +24243,7 @@
             commandName: 'claude',
             npmPackageName: '@anthropic-ai/claude-code',
             projectGitignoreRules: ['.claude'],
+            authenticationMethod: { command: 'claude', interactiveStep: 'running the `/login` command inside it' },
         },
         opencode: {
             harnessName: 'opencode',
@@ -24183,6 +24251,7 @@
             commandName: 'opencode',
             npmPackageName: 'opencode-ai',
             projectGitignoreRules: ['.opencode'],
+            authenticationMethod: { command: 'opencode auth login' },
         },
         gemini: {
             harnessName: 'gemini',
@@ -24190,6 +24259,7 @@
             commandName: 'gemini',
             npmPackageName: '@google/gemini-cli',
             projectGitignoreRules: ['.gemini'],
+            authenticationMethod: { command: 'gemini', interactiveStep: 'running the `/auth` command inside it' },
         },
         'qwen-code': {
             harnessName: 'qwen-code',
@@ -24197,6 +24267,7 @@
             commandName: 'qwen',
             npmPackageName: '@qwen-code/qwen-code',
             projectGitignoreRules: ['.qwen'],
+            authenticationMethod: { command: 'qwen', interactiveStep: 'running the `/auth` command inside it' },
         },
     };
     /**
@@ -26230,6 +26301,183 @@
         return `${sessionId.slice(0, 8)}...`;
     }
 
+    /**
+     * Formats one unknown error-like value into its readable message without the stack trace.
+     *
+     * Use this instead of `formatUnknownErrorDetails` whenever the text is shown to the user, for example
+     * inside a branded error, where the stack of the wrapped error would only bury the actual cause.
+     */
+    function formatUnknownErrorMessage(error) {
+        if (error instanceof Error) {
+            return error.message;
+        }
+        if (typeof error === 'string') {
+            return error;
+        }
+        const serializedError = JSON.stringify(error, null, 2);
+        return serializedError !== null && serializedError !== void 0 ? serializedError : String(error);
+    }
+
+    /**
+     * Builds the branded error which tells the user that the selected harness has to be signed in again.
+     */
+    function buildHarnessAuthenticationError(options) {
+        const { harnessName, reason } = options;
+        const { label, authenticationMethod } = getHarnessDefinition(harnessName);
+        return new AuthenticationError(spaceTrim((block) => `
+                The **${label}** harness is not authenticated, so the prompt was not run.
+
+                ${label} reported:
+                > ${reason}
+
+                ${block(buildSignInInstruction(authenticationMethod))}
+
+                Once you are signed in, start the very same \`ptbk coder\` command again.
+            `));
+    }
+    /**
+     * Builds the sentence which tells the user how to sign in to one harness again.
+     */
+    function buildSignInInstruction(authenticationMethod) {
+        const { command, interactiveStep } = authenticationMethod;
+        if (interactiveStep === undefined) {
+            return `Sign in again by running \`${command}\`.`;
+        }
+        return `Sign in again by running \`${command}\` and then ${interactiveStep}.`;
+    }
+
+    /**
+     * Maximum length of the harness reason quoted back to the user.
+     */
+    const MAXIMUM_AUTHENTICATION_FAILURE_REASON_LENGTH = 300;
+    /**
+     * Keys of machine-readable harness output whose string value carries the human-readable failure reason.
+     *
+     * Harnesses which stream JSON events - like Claude Code with its `stream-json` output - report the reason only
+     * inside such a value, surrounded by hundreds of characters of session metadata which must never be shown to
+     * the user. The keys are ordered from the most to the least conclusive one.
+     */
+    const HARNESS_FAILURE_MESSAGE_KEYS = ['result', 'error_message', 'message', 'text'];
+    /**
+     * Patterns which extract one JSON string value reported under a harness failure message key.
+     */
+    const HARNESS_FAILURE_MESSAGE_PATTERNS = HARNESS_FAILURE_MESSAGE_KEYS.map((messageKey) => new RegExp(`"${messageKey}"\\s*:\\s*("(?:[^"\\\\]|\\\\.)*")`, 'g'));
+    /**
+     * Signatures which mean that the harness refused to work because it is not logged in.
+     *
+     * They are deliberately narrow phrases instead of single words like `login`, because the output of a harness
+     * routinely mentions its own `/login` command among the commands it offers, and such a mention must never be
+     * read as a failed login.
+     */
+    const AUTHENTICATION_FAILURE_PATTERNS = [
+        /\bauthentication[ _-]?failed\b/i,
+        /\bfailed to authenticate\b/i,
+        /\bnot authenticated\b/i,
+        /\bnot logged[ -]?in\b/i,
+        /\bnot signed[ -]?in\b/i,
+        /\bno authentication information found\b/i,
+        /\bauthentication (?:is )?required\b/i,
+        /\blogin (?:is )?required\b/i,
+        /\bplease (?:log|sign) in\b/i,
+        /\bunauthorized\b/i,
+        /\b(?:oauth|session|token|credentials?|login)\b[^.]{0,60}?\bexpired\b/i,
+        /\bexpired\b[^.]{0,60}?\b(?:oauth|session|token|credentials?|login)\b/i,
+        /\binvalid api[ _-]?key\b/i,
+        /\bmissing api[ _-]?key\b/i,
+        /\binvalid credentials?\b/i,
+    ];
+    /**
+     * Reads the reason why a harness refused to work because it is not logged in, from its raw CLI output.
+     *
+     * Messages the harness reports in machine-readable output are preferred over its raw output lines, so the
+     * reason is the sentence the harness wrote for a human and not the JSON event which transported it.
+     *
+     * @returns One short single-line reason, or `undefined` when the failure was not caused by authentication.
+     */
+    function extractHarnessAuthenticationFailureReason(harnessOutput) {
+        const reportedMessages = [...extractHarnessReportedMessages(harnessOutput), ...harnessOutput.split(/\r?\n/)];
+        for (const reportedMessage of reportedMessages) {
+            const reason = reportedMessage.replace(/\s+/g, ' ').trim();
+            if (isAuthenticationFailureReason(reason)) {
+                return limitAuthenticationFailureReason(reason);
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Lists the human-readable messages a harness reported in its machine-readable output.
+     */
+    function extractHarnessReportedMessages(harnessOutput) {
+        const reportedMessages = [];
+        for (const messagePattern of HARNESS_FAILURE_MESSAGE_PATTERNS) {
+            for (const match of harnessOutput.matchAll(messagePattern)) {
+                const reportedMessage = parseSerializedJsonString(match[1]);
+                if (reportedMessage !== undefined) {
+                    reportedMessages.push(reportedMessage);
+                }
+            }
+        }
+        return reportedMessages;
+    }
+    /**
+     * Reads one JSON string literal back into plain text, tolerating output which only looks like JSON.
+     */
+    function parseSerializedJsonString(serializedString) {
+        if (serializedString === undefined) {
+            return undefined;
+        }
+        try {
+            const parsedString = JSON.parse(serializedString);
+            return typeof parsedString === 'string' ? parsedString : undefined;
+        }
+        catch (_a) {
+            return undefined;
+        }
+    }
+    /**
+     * Returns true when one message of the harness says that it is not logged in.
+     */
+    function isAuthenticationFailureReason(reportedMessage) {
+        return AUTHENTICATION_FAILURE_PATTERNS.some((pattern) => pattern.test(reportedMessage));
+    }
+    /**
+     * Shortens a very long reason, so the guidance which follows it stays visible in the terminal.
+     */
+    function limitAuthenticationFailureReason(reason) {
+        if (reason.length <= MAXIMUM_AUTHENTICATION_FAILURE_REASON_LENGTH) {
+            return reason;
+        }
+        return `${reason.slice(0, MAXIMUM_AUTHENTICATION_FAILURE_REASON_LENGTH)}...`;
+    }
+
+    /**
+     * Wraps one prompt runner so a failure caused by a missing or expired harness login is reported as a branded
+     * `AuthenticationError` which tells the user how to sign in again.
+     *
+     * Each harness reports its own failures differently, but all of them report them by failing `runPrompt` with
+     * the raw CLI output as the message. Translating the failure here therefore keeps exactly one place which has
+     * to recognize an unauthenticated harness, for every harness and for every command which runs prompts.
+     */
+    function createAuthenticationAwarePromptRunner(runner, harnessName) {
+        var _a;
+        return {
+            name: runner.name,
+            runPrompt: async (options) => {
+                try {
+                    return await runner.runPrompt(options);
+                }
+                catch (error) {
+                    const reason = extractHarnessAuthenticationFailureReason(formatUnknownErrorMessage(error));
+                    if (reason === undefined) {
+                        throw error;
+                    }
+                    throw buildHarnessAuthenticationError({ harnessName, reason });
+                }
+            },
+            getSubscriptionUsage: (_a = runner.getSubscriptionUsage) === null || _a === void 0 ? void 0 : _a.bind(runner),
+        };
+    }
+
     /**
      * Creates a temporary script file, runs it, and cleans it up unless preservation is requested or the run fails.
      */
@@ -27969,6 +28217,18 @@
         if (!agentName) {
             throw new Error('Missing --harness in non-dry run mode');
         }
+        const resolution = resolveHarnessPromptRunner(agentName, options);
+        return {
+            ...resolution,
+            // Note: Every harness is wrapped here, so a harness which is not logged in is reported the same clear
+            //       way no matter which harness it is and which command has resolved the runner
+            runner: createAuthenticationAwarePromptRunner(resolution.runner, agentName),
+        };
+    }
+    /**
+     * Creates the runner of one selected harness together with its status-line metadata.
+     */
+    function resolveHarnessPromptRunner(agentName, options) {
         if (agentName === 'openai-codex') {
             return createOpenAiCodexRunnerResolution(options);
         }
@@ -28436,11 +28696,19 @@
      * Maximum width used for the rich coder-run frame.
      */
     const MAX_FRAME_WIDTH = 96;
+    /**
+     * Number of terminal columns deliberately left unused by the rich coder-run frame.
+     *
+     * A row which fills the final physical terminal column can auto-wrap. The incremental terminal
+     * updater moves by logical rows, so an auto-wrapped row would put its cursor out of sync with the
+     * frame and let a later animated avatar redraw overwrite dashboard content.
+     */
+    const TERMINAL_AUTO_WRAP_RESERVED_COLUMNS = 1;
     /**
      * Builds the complete boxed terminal frame for the rich `ptbk coder run` UI.
      */
     function buildCoderRunUiFrame(options) {
-        const totalWidth = Math.max(MIN_FRAME_WIDTH, Math.min(options.terminalWidth, MAX_FRAME_WIDTH));
+        const totalWidth = resolveCoderRunUiFrameWidth(options.terminalWidth);
         const isPromptActive = options.phase === 'running' || options.phase === 'verifying' || options.phase === 'loading';
         const promptStatusPrefix = isPromptActive ? `${colors__default["default"].yellow(`${options.spinner} `)}` : '';
         const pausePresentation = buildPausePresentation(options.phase, options.pauseState, options.pauseTargetLabel, options.statusMessage);
@@ -28477,6 +28745,16 @@
         frame.push(...renderBox('Controls', controlsBoxLines, totalWidth, colors__default["default"].white.bold));
         return frame;
     }
+    /**
+     * Resolves the safe width of the rich terminal frame from the available physical terminal columns.
+     *
+     * The reserved trailing column keeps every boxed row from auto-wrapping, which makes the frame's
+     * logical row count match its physical terminal row count during animated incremental redraws.
+     */
+    function resolveCoderRunUiFrameWidth(terminalWidth) {
+        const availableFrameWidth = terminalWidth - TERMINAL_AUTO_WRAP_RESERVED_COLUMNS;
+        return Math.max(MIN_FRAME_WIDTH, Math.min(availableFrameWidth, MAX_FRAME_WIDTH));
+    }
     /**
      * Builds the header visual above the dashboard boxes.
      *
@@ -29953,16 +30231,14 @@
      */
     const DEFAULT_TERMINAL_WIDTH = 80;
     /**
-     * Maximum terminal width supported by the boxed runner UI.
-     */
-    const MAX_TERMINAL_WIDTH = 96;
-    /**
-     * Returns the usable terminal width, capped at 96.
+     * Returns the number of columns reported by the current terminal.
+     *
+     * The frame builder owns clamping and reserves its trailing auto-wrap safety column.
      *
      * @private internal utility of coder run UI
      */
-    function getTerminalWidth() {
-        return Math.min(process.stdout.columns || DEFAULT_TERMINAL_WIDTH, MAX_TERMINAL_WIDTH);
+    function getTerminalColumnCount() {
+        return process.stdout.columns || DEFAULT_TERMINAL_WIDTH;
     }
     /**
      * Boots the ANSI terminal UI for `ptbk coder run`.
@@ -30069,7 +30345,7 @@
          */
         function buildFrameLines() {
             return buildFrameLinesFromState({
-                terminalWidth: getTerminalWidth(),
+                terminalWidth: getTerminalColumnCount(),
                 animationFrame: spinnerFrame,
                 animationTimeMs: Date.now() - animationStartTimeMs,
                 spinner: SPINNER_FRAMES[spinnerFrame],
@@ -33800,19 +34076,6 @@
         }
     }
 
-    /**
-     * AuthenticationError is thrown from login function which is dependency of remote server
-     *
-     * @public exported from `@promptbook/core`
-     */
-    class AuthenticationError extends Error {
-        constructor(message) {
-            super(message);
-            this.name = 'AuthenticationError';
-            Object.setPrototypeOf(this, AuthenticationError.prototype);
-        }
-    }
-
     /**
      * This error indicates that the pipeline collection cannot be properly loaded
      *
@@ -42041,11 +42304,7 @@
         $initializeAgentsServerDevCommand(agentsServerCommand);
         $initializeAgentsServerInitCommand(agentsServerCommand);
         $initializeAgentsServerStartCommand(agentsServerCommand);
-        agentsServerCommand.action(() => {
-            console.info(colors__default["default"].yellow('Please specify a subcommand.'));
-            console.info('');
-            agentsServerCommand.help();
-        });
+        $requireCliSubcommand(agentsServerCommand);
     }
     // Note: [🟡] Code for CLI command [agents-server](src/cli/cli-commands/agents-server.ts) should never be published outside of `@promptbook/cli`
     // Note: [💞] Ignore a discrepancy between file name and entity name
@@ -42135,6 +42394,58 @@
     // Note: [🟡] Code for CLI git synchronization options [coderGitSyncCliOptions](src/cli/cli-commands/common/coderGitSyncCliOptions.ts) should never be published outside of `@promptbook/cli`
     // Note: [💞] Ignore a discrepancy between file name and exported helper names
 
+    /**
+     * Description block shared by the `ptbk coder` commands which can ask interactive questions.
+     *
+     * @private internal utility of `promptbookCli`
+     */
+    const QUESTIONS_DESCRIPTION = _spaceTrim.spaceTrim(`
+    Interactive questions:
+    - Steps which need an answer to continue are asked in the terminal
+    - --no-questions never asks: an optional step is skipped with a note how to do it manually, a required one fails right away
+`);
+    /**
+     * Registers the shared `--no-questions` option on a `ptbk coder` command which can ask interactive questions.
+     *
+     * @private internal utility of `promptbookCli`
+     */
+    function addQuestionsOption(command) {
+        command.option('--no-questions', 'Never ask an interactive question and skip every optional step which needs an answer to continue');
+    }
+    /**
+     * Converts the Commander questions flag into the normalized interactive-questions option.
+     *
+     * @private internal utility of `promptbookCli`
+     */
+    function normalizeQuestionsCliOptions(cliOptions) {
+        return {
+            isAskingQuestionsEnabled: cliOptions.questions,
+        };
+    }
+    /**
+     * Asserts that a command which waits for a user confirmation before each prompt is allowed to ask for it.
+     *
+     * @throws {NotAllowed} when `--no-auto` is combined with `--no-questions`
+     * @private internal utility of `promptbookCli`
+     */
+    function assertUserConfirmationIsAllowed(options) {
+        const { isAskingQuestionsEnabled, isWaitingForUser } = options;
+        if (!isWaitingForUser || isAskingQuestionsEnabled) {
+            return;
+        }
+        throw new NotAllowed(_spaceTrim.spaceTrim(`
+            Flag \`--no-auto\` can not be used together with \`--no-questions\`.
+
+            **There is nobody who could confirm each prompt when no question may be asked.**
+
+            Actionable hints:
+            - Keep \`--no-auto\` for a supervised run, for example \`ptbk coder run --harness claude-code --no-auto\`.
+            - Keep \`--no-questions\` for an unattended run, for example \`ptbk coder run --harness claude-code --no-questions\`.
+        `));
+    }
+    // Note: [🟡] Code for CLI interactive questions options [questionsCliOptions](src/cli/cli-commands/common/questionsCliOptions.ts) should never be published outside of `@promptbook/cli`
+    // Note: [💞] Ignore a discrepancy between file name and exported helper names
+
     /**
      * Relative path to the root prompts directory used by Promptbook coder utilities.
      *
@@ -42153,6 +42464,12 @@
      * @private internal utility of `ptbk coder`
      */
     const PROMPTS_TEMPLATES_DIRECTORY_PATH = path.join(PROMPTS_DIRECTORY_PATH$1, 'templates');
+    /**
+     * Relative path to the project-agnostic `common` boilerplate template referenced by the default coder scripts.
+     *
+     * @private internal utility of `ptbk coder`
+     */
+    const COMMON_PROMPT_TEMPLATE_FILE_PATH = path.join(PROMPTS_TEMPLATES_DIRECTORY_PATH, 'common.md');
     /**
      * Built-in boilerplate templates available to `coder generate-boilerplates`.
      *
@@ -42161,7 +42478,7 @@
     const DEFAULT_CODER_PROMPT_TEMPLATE_DEFINITIONS = [
         {
             id: 'common',
-            relativeFilePath: path.join(PROMPTS_TEMPLATES_DIRECTORY_PATH, 'common.md'),
+            relativeFilePath: COMMON_PROMPT_TEMPLATE_FILE_PATH,
             slugPrefix: null,
             content: _spaceTrim.spaceTrim(`
             -   @@@
@@ -42207,30 +42524,17 @@
         return definition;
     }
     /**
-     * Ensures the default project-owned coder template files exist without overwriting user customizations.
+     * Ensures one project-owned coder template file exists without overwriting user customizations.
      *
      * @private internal utility of `ptbk coder`
      */
-    async function ensureDefaultCoderPromptTemplateFiles(projectPath) {
-        const ensuredTemplateFiles = [];
-        for (const definition of DEFAULT_CODER_PROJECT_PROMPT_TEMPLATE_DEFINITIONS) {
-            const absoluteTemplatePath = path.join(projectPath, definition.relativeFilePath);
-            if (await isExistingFile$3(absoluteTemplatePath)) {
-                ensuredTemplateFiles.push({
-                    id: definition.id,
-                    relativeFilePath: definition.relativeFilePath,
-                    status: 'unchanged',
-                });
-                continue;
-            }
-            await promises.writeFile(absoluteTemplatePath, `${definition.content}\n`, 'utf-8');
-            ensuredTemplateFiles.push({
-                id: definition.id,
-                relativeFilePath: definition.relativeFilePath,
-                status: 'created',
-            });
+    async function ensureDefaultCoderPromptTemplateFile(projectPath, definition) {
+        const absoluteTemplatePath = path.join(projectPath, definition.relativeFilePath);
+        if (await isExistingFile$3(absoluteTemplatePath)) {
+            return 'unchanged';
         }
-        return ensuredTemplateFiles;
+        await promises.writeFile(absoluteTemplatePath, `${definition.content}\n`, 'utf-8');
+        return 'created';
     }
     /**
      * Resolves the template requested by `coder generate-boilerplates`.
@@ -42386,6 +42690,8 @@
                 - \`ptbk coder add\`
 
                 ${block(CODER_GIT_SYNC_DESCRIPTION)}
+
+                ${block(QUESTIONS_DESCRIPTION)}
             `));
         command.argument('[description]', 'Plain-language description of the feature or task to implement');
         command.option('--priority <priority>', 'Priority of the new prompt — higher priorities run first (rendered as trailing `!` markers)', parsePriorityOption, 0);
@@ -42397,11 +42703,13 @@
         .join(', ')}) or a markdown file path relative to the current project root.
         `));
         addCoderGitSyncOptions(command);
+        addQuestionsOption(command);
         command.action(handleActionErrors(async (descriptionArgument, cliOptions) => {
             const { priority, template: templateOption } = cliOptions;
             const gitSync = normalizeCoderGitSyncCliOptions(cliOptions);
+            const questionsOptions = normalizeQuestionsCliOptions(cliOptions);
             const projectPath = process.cwd();
-            const description = await resolveCoderPromptDescription(descriptionArgument);
+            const description = await resolveCoderPromptDescription(descriptionArgument, questionsOptions);
             // Note: Import the git synchronization dynamically to keep the CLI fast for runs without `--commit`
             const { $commitCoderChanges, $startCoderGitSync } = await Promise.resolve().then(function () { return coderGitSync; });
             const commitScope = await $startCoderGitSync({ gitSync, projectPath });
@@ -42471,7 +42779,7 @@
      *
      * @private internal utility of `coder add` command
      */
-    async function resolveCoderPromptDescription(descriptionArgument) {
+    async function resolveCoderPromptDescription(descriptionArgument, { isAskingQuestionsEnabled }) {
         if (descriptionArgument !== undefined && descriptionArgument.trim() !== '') {
             return descriptionArgument.trim();
         }
@@ -42489,6 +42797,14 @@
             }
             return standardInputDescription;
         }
+        if (!isAskingQuestionsEnabled) {
+            throw new ParseError(_spaceTrim.spaceTrim(`
+                Cannot add a prompt without a description.
+
+                The description can not be typed interactively because \`--no-questions\` is used — provide it as an argument or pipe it through stdin instead:
+                - \`ptbk coder add --no-questions "some new feature"\`
+            `));
+        }
         const { default: prompts } = await loadPromptsModule();
         const response = await prompts({
             type: 'text',
@@ -43139,10 +43455,15 @@
      *
      * 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.
+     * @returns `true` when the user confirms, `false` when the user declines, the terminal is not interactive
+     *          or the questions are disabled by `--no-questions`.
      * @private internal utility of `promptbookCli`
      */
-    async function $askForConfirmation(question) {
+    async function $askForConfirmation(question, { isAskingQuestionsEnabled }) {
+        if (!isAskingQuestionsEnabled) {
+            // Note: `--no-questions` forbids asking, so the optional change is declined without blocking the run.
+            return false;
+        }
         if (!process.stdin.isTTY) {
             // Note: In non-interactive environments like CI there is nobody who could confirm the change.
             return false;
@@ -43165,11 +43486,12 @@
      *
      * 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
+     * @returns `true` when the user confirms, `false` when the user declines, the terminal is not interactive
+     *          or the questions are disabled by `--no-questions`
      * @private internal utility of `promptbookCli`
      */
-    async function $askForNpmPackageInstallationApproval(question) {
-        return $askForConfirmation(question);
+    async function $askForNpmPackageInstallationApproval(question, questionsOptions) {
+        return $askForConfirmation(question, questionsOptions);
     }
     // 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`
 
@@ -43359,7 +43681,7 @@
      *
      * @private internal utility of `promptbookCli`
      */
-    async function $applyHarnessInstallationStatus(status) {
+    async function $applyHarnessInstallationStatus(status, questionsOptions) {
         const { definition, installationState, installedVersion } = status;
         if (installationState === 'up-to-date') {
             console.info(colors__default["default"].gray(`✔ ${definition.label} ${installedVersion} is up to date.`));
@@ -43375,17 +43697,17 @@
         }
         console.warn(colors__default["default"].yellow(formatHarnessInstallationWarning(status)));
         if (installationState === 'not-installed') {
-            await $applyMissingHarnessInstallation(definition);
+            await $applyMissingHarnessInstallation(definition, questionsOptions);
             return;
         }
-        await $applyOutdatedHarnessInstallation(status);
+        await $applyOutdatedHarnessInstallation(status, questionsOptions);
     }
     /**
      * Offers to install a missing harness globally through npm.
      */
-    async function $applyMissingHarnessInstallation(definition) {
+    async function $applyMissingHarnessInstallation(definition, questionsOptions) {
         const installCommand = buildHarnessInstallCommand(definition);
-        const isInstallationApproved = await $askForNpmPackageInstallationApproval(`Install ${definition.label} globally now?`);
+        const isInstallationApproved = await $askForNpmPackageInstallationApproval(`Install ${definition.label} globally now?`, questionsOptions);
         if (!isInstallationApproved) {
             console.info(colors__default["default"].gray(`Skipped, run \`${installCommand}\` to do it manually.`));
             return;
@@ -43400,14 +43722,14 @@
     /**
      * Offers to update an outdated harness exactly where it is installed.
      */
-    async function $applyOutdatedHarnessInstallation(status) {
+    async function $applyOutdatedHarnessInstallation(status, questionsOptions) {
         const { definition, latestVersion, installationOrigin } = status;
         const updatePlan = resolveHarnessUpdatePlan(definition, installationOrigin.installationMethod);
         if (updatePlan.command === null || !updatePlan.isRunnableByPromptbook) {
             console.info(colors__default["default"].gray(formatHarnessManualUpdateInstruction(status, updatePlan)));
             return;
         }
-        const isUpdateApproved = await $askForNpmPackageInstallationApproval(`Update ${definition.label} to ${latestVersion} with \`${updatePlan.command}\` now?`);
+        const isUpdateApproved = await $askForNpmPackageInstallationApproval(`Update ${definition.label} to ${latestVersion} with \`${updatePlan.command}\` now?`, questionsOptions);
         if (!isUpdateApproved) {
             console.info(colors__default["default"].gray(`Skipped, run \`${updatePlan.command}\` to do it manually.`));
             return;
@@ -43843,7 +44165,7 @@
     // Note: [🟡] Code for CLI harness installation check [$checkHarnessInstallation](src/cli/cli-commands/common/harness/$checkHarnessInstallation.ts) should never be published outside of `@promptbook/cli`
 
     /**
-     * Checks that every given CLI coding harness is installed globally and, when enabled, up to date.
+     * Checks that every given CLI coding harness is installed globally and, when the questions are enabled, up to date.
      * Offers to install missing harnesses and update outdated ones.
      *
      * Harness names which are `undefined`, for example when no `--harness` is selected in a dry run,
@@ -43853,15 +44175,18 @@
      *
      * @private internal utility of `promptbookCli`
      */
-    async function $ensureHarnessInstallations(harnessNames, isHarnessUpdateCheckEnabled = true) {
+    async function $ensureHarnessInstallations(harnessNames, questionsOptions) {
         const definitions = resolveCheckedHarnessDefinitions(harnessNames);
         if (definitions.length === 0) {
             return;
         }
+        // Note: An outdated harness can be updated only after the user confirms it, so `--no-questions`
+        //       skips the slower npm registry lookup entirely and only reports what is installed.
+        const isHarnessUpdateCheckEnabled = questionsOptions.isAskingQuestionsEnabled;
         // Note: Detection of all harnesses runs in parallel, the questions have to be asked one by one
         const statuses = await Promise.all(definitions.map((definition) => $checkHarnessInstallation(definition, isHarnessUpdateCheckEnabled)));
         for (const status of statuses) {
-            await $applyHarnessInstallationStatus(status);
+            await $applyHarnessInstallationStatus(status, questionsOptions);
         }
     }
     /**
@@ -43873,48 +44198,6 @@
     }
     // Note: [🟡] Code for CLI harness installation orchestration [$ensureHarnessInstallations](src/cli/cli-commands/common/harness/$ensureHarnessInstallations.ts) should never be published outside of `@promptbook/cli`
 
-    /**
-     * Registers the shared `--no-harness-update` option on a `ptbk coder` command that uses a coding harness.
-     *
-     * @private internal utility of `promptbookCli`
-     */
-    function addHarnessUpdateOption(command) {
-        command.option('--no-harness-update', 'Skip checking whether the installed coding harnesses are up to date');
-    }
-    /**
-     * Converts the Commander harness-update flag into the normalized harness-check option.
-     *
-     * @private internal utility of `promptbookCli`
-     */
-    function normalizeHarnessUpdateCliOptions(cliOptions) {
-        return {
-            isHarnessUpdateCheckEnabled: cliOptions.harnessUpdate,
-        };
-    }
-    // Note: [🟡] Code for CLI harness update options [harnessUpdateCliOptions](src/cli/cli-commands/common/harnessUpdateCliOptions.ts) should never be published outside of `@promptbook/cli`
-    // Note: [💞] Ignore a discrepancy between file name and exported helper names
-
-    /**
-     * Relative path to the Promptbook Coder quick-reference file initialized in project roots.
-     *
-     * @private internal utility of `ptbk coder`
-     */
-    const AGENT_CODING_FILE_PATH = 'AGENT_CODING.md';
-    /**
-     * Returns the default coder `AGENT_CODING.md` quick-reference content.
-     *
-     * @private internal utility of `ptbk coder`
-     */
-    function getDefaultCoderAgentCodingFileContent() {
-        return _spaceTrim.spaceTrim(`
-        # ✨ Promptbook Coder agent coding
-
-        This project is using [Promptbook Coder](https://coder.ptbk.io) or run \`ptbk coder\`!
-    `);
-    }
-    // Note: [🟡] Code for coder AGENT_CODING file boilerplate [agentCodingFile](src/cli/cli-commands/coder/agentCodingFile.ts) should never be published outside of `@promptbook/cli`
-    // Note: [💞] Ignore a discrepancy between file name and exported helper names
-
     /**
      * Relative path to the shared coder context file initialized in project roots.
      *
@@ -44016,6 +44299,51 @@
     }
     // Note: [🟡] Code for coder path formatting [formatDisplayPath](src/cli/cli-commands/coder/formatDisplayPath.ts) should never be published outside of `@promptbook/cli`
 
+    /**
+     * Creates the artifact definition of one project-owned coder prompt template.
+     */
+    function createCoderPromptTemplateArtifactDefinition(definition) {
+        return {
+            relativeFilePath: definition.relativeFilePath,
+            ensureArtifactFile: (projectPath) => ensureDefaultCoderPromptTemplateFile(projectPath, definition),
+        };
+    }
+    /**
+     * Every artifact which the default coder scripts can reference.
+     */
+    const CODER_REFERENCED_ARTIFACT_DEFINITIONS = [
+        {
+            relativeFilePath: CODER_DEVELOPER_AGENT_FILE_PATH,
+            ensureArtifactFile: ensureCoderDeveloperAgentFile,
+        },
+        {
+            relativeFilePath: AGENTS_FILE_PATH,
+            ensureArtifactFile: (projectPath) => ensureCoderMarkdownFile(projectPath, AGENTS_FILE_PATH, getDefaultCoderAgentsFileContent()),
+        },
+        ...getDefaultCoderProjectPromptTemplateDefinitions().map(createCoderPromptTemplateArtifactDefinition),
+    ];
+    /**
+     * Creates only those referenced artifacts which the freshly added coder scripts point at.
+     *
+     * An artifact of a script which the project already defines is intentionally **not** created - the project-owned
+     * script is kept as is, so it does not reference the default artifact in the first place.
+     *
+     * @private function of `initializeCoderProjectConfiguration`
+     */
+    async function ensureCoderReferencedArtifacts(projectPath, referencedArtifactPaths) {
+        const ensuredArtifacts = [];
+        for (const { relativeFilePath, ensureArtifactFile } of CODER_REFERENCED_ARTIFACT_DEFINITIONS) {
+            if (!referencedArtifactPaths.has(relativeFilePath)) {
+                ensuredArtifacts.push({ relativeFilePath, status: 'not-referenced' });
+                continue;
+            }
+            ensuredArtifacts.push({ relativeFilePath, status: await ensureArtifactFile(projectPath) });
+        }
+        return ensuredArtifacts;
+    }
+    // Note: [🟡] Code for coder init referenced artifacts [coderReferencedArtifacts](src/cli/cli-commands/coder/coderReferencedArtifacts.ts) should never be published outside of `@promptbook/cli`
+    // Note: [💞] Ignore a discrepancy between file name and exported helper names
+
     /**
      * Fallback `.env` content used when no required variables need to be appended.
      */
@@ -44110,26 +44438,79 @@
     }
     // Note: [🟡] Code for coder init gitignore bootstrapping [ensureCoderGitignoreFile](src/cli/cli-commands/coder/ensureCoderGitignoreFile.ts) should never be published outside of `@promptbook/cli`
 
+    /**
+     * Name of the npm script which `ptbk coder run` uses to verify the project.
+     */
+    const CODER_TEST_SCRIPT_NAME = 'test-for-ptbk-coder';
     /**
      * Default npm scripts initialized by `ptbk coder init`.
+     *
+     * Note: Using NPX because `ptbk` can be installed globally or locally, and NPX will resolve it correctly in either case.
      */
-    const DEFAULT_CODER_PACKAGE_JSON_SCRIPTS = {
-        // 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': 'npx ptbk coder verify',
-    };
+    const DEFAULT_CODER_PACKAGE_JSON_SCRIPT_DEFINITIONS = [
+        {
+            scriptName: 'coder:generate-boilerplates',
+            scriptCommand: `npx ptbk coder generate-boilerplates --count ${DEFAULT_BOILERPLATE_COUNT_OPTION_VALUE} --template ${formatCoderScriptFilePath(COMMON_PROMPT_TEMPLATE_FILE_PATH)}`,
+            referencedArtifactPaths: [COMMON_PROMPT_TEMPLATE_FILE_PATH],
+        },
+        {
+            scriptName: 'coder:add',
+            scriptCommand: `npx ptbk coder add --template ${formatCoderScriptFilePath(COMMON_PROMPT_TEMPLATE_FILE_PATH)}`,
+            referencedArtifactPaths: [COMMON_PROMPT_TEMPLATE_FILE_PATH],
+        },
+        {
+            scriptName: 'coder:run',
+            scriptCommand: [
+                'npx ptbk coder run --harness openai-codex --model gpt-5.6-terra --thinking-level max',
+                `--agent ${formatDisplayPath(CODER_DEVELOPER_AGENT_FILE_PATH)}`,
+                `--context ${formatDisplayPath(AGENTS_FILE_PATH)}`,
+                `--test "npm run ${CODER_TEST_SCRIPT_NAME}" --test-before yes-and-fix`,
+            ].join(' '),
+            referencedArtifactPaths: [CODER_DEVELOPER_AGENT_FILE_PATH, AGENTS_FILE_PATH],
+        },
+        // { scriptName: 'coder:find-refactor-candidates', scriptCommand: 'npx ptbk coder find-refactor-candidates', referencedArtifactPaths: [] },
+        {
+            scriptName: 'coder:verify',
+            scriptCommand: 'npx ptbk coder verify',
+            referencedArtifactPaths: [],
+        },
+        {
+            // Note: The verification command of `coder:run` is a project-owned script, so every project can decide
+            //       what "verified" means without touching the `coder:run` script itself
+            scriptName: CODER_TEST_SCRIPT_NAME,
+            scriptCommand: 'npm test',
+            referencedArtifactPaths: [],
+        },
+    ];
     /**
      * Lists the default npm scripts initialized by `ptbk coder init`.
      *
      * @private internal utility of `coder init` command
      */
     function getDefaultCoderPackageJsonScripts() {
-        return DEFAULT_CODER_PACKAGE_JSON_SCRIPTS;
+        return Object.fromEntries(DEFAULT_CODER_PACKAGE_JSON_SCRIPT_DEFINITIONS.map(({ scriptName, scriptCommand }) => [
+            scriptName,
+            scriptCommand,
+        ]));
+    }
+    /**
+     * Collects the project-relative artifact paths referenced by the given default coder scripts.
+     *
+     * @private internal utility of `coder init` command
+     */
+    function resolveCoderPackageJsonScriptReferencedArtifactPaths(scriptNames) {
+        return new Set(DEFAULT_CODER_PACKAGE_JSON_SCRIPT_DEFINITIONS.filter(({ scriptName }) => scriptNames.includes(scriptName))
+            .map(({ referencedArtifactPaths }) => referencedArtifactPaths)
+            .flat());
+    }
+    /**
+     * Formats one project-relative path as an explicitly project-rooted path usable inside a shell command.
+     */
+    function formatCoderScriptFilePath(relativeFilePath) {
+        return `./${formatDisplayPath(relativeFilePath)}`;
     }
     // Note: [🟡] Code for coder init package scripts [getDefaultCoderPackageJsonScripts](src/cli/cli-commands/coder/getDefaultCoderPackageJsonScripts.ts) should never be published outside of `@promptbook/cli`
+    // Note: [💞] Ignore a discrepancy between file name and exported helper names
 
     /**
      * Loads the TypeScript runtime used for parsing JSONC-style project files.
@@ -44162,6 +44543,9 @@
     /**
      * Ensures one JSON object field contains the provided string-record entries.
      *
+     * Entries which the project already defines are **never** overridden - only missing keys are added,
+     * so hand-tuned scripts and settings survive every repeated `ptbk coder init`.
+     *
      * @private function of `initializeCoderProjectConfiguration`
      */
     async function mergeStringRecordJsonFile({ projectPath, relativeFilePath, fieldPath, nextEntries, ensureParentDirectoryPath, }) {
@@ -44173,21 +44557,24 @@
         const formatting = detectJsonFileFormatting(fileContent);
         const jsonObject = fileContent === undefined ? {} : await parseJsonObjectFile(relativeFilePath, fileContent);
         const existingEntries = getStringRecordOrDefault(jsonObject[fieldPath], relativeFilePath, fieldPath);
-        let hasChanges = fileContent === undefined;
+        const addedEntryKeys = [];
         const mergedEntries = { ...existingEntries };
         for (const [entryKey, entryValue] of Object.entries(nextEntries)) {
-            if (mergedEntries[entryKey] !== entryValue) {
-                mergedEntries[entryKey] = entryValue;
-                hasChanges = true;
+            if (Object.prototype.hasOwnProperty.call(mergedEntries, entryKey)) {
+                // Note: The project already defines this entry, keep its own value untouched
+                continue;
             }
+            mergedEntries[entryKey] = entryValue;
+            addedEntryKeys.push(entryKey);
         }
+        const hasChanges = fileContent === undefined || addedEntryKeys.length > 0;
         if (!hasChanges) {
-            return 'unchanged';
+            return { status: 'unchanged', addedEntryKeys };
         }
         const nextJsonObject = { ...jsonObject };
         nextJsonObject[fieldPath] = mergedEntries;
         await promises.writeFile(absoluteFilePath, serializeJsonObject(nextJsonObject, formatting), 'utf-8');
-        return fileContent === undefined ? 'created' : 'updated';
+        return { status: fileContent === undefined ? 'created' : 'updated', addedEntryKeys };
     }
     /**
      * Parses one JSON object file while accepting VS Code style comments and trailing commas.
@@ -44276,6 +44663,8 @@
     /**
      * Ensures `package.json` contains the standalone Promptbook coder helper scripts.
      *
+     * Scripts which the project already defines are kept as they are, only missing ones are added.
+     *
      * @private function of `initializeCoderProjectConfiguration`
      */
     async function ensureCoderPackageJsonFile(projectPath) {
@@ -44329,17 +44718,20 @@
     /**
      * Ensures VS Code routes pasted prompt images into `prompts/screenshots`.
      *
+     * Settings which the project already defines are kept as they are, only missing ones are added.
+     *
      * @private function of `initializeCoderProjectConfiguration`
      */
     async function ensureCoderVscodeSettingsFile(projectPath) {
         const [fieldPath, nextEntries] = resolveDefaultCoderVscodeSettingsEntry();
-        return mergeStringRecordJsonFile({
+        const { status } = await mergeStringRecordJsonFile({
             projectPath,
             relativeFilePath: VSCODE_SETTINGS_FILE_PATH,
             fieldPath,
             nextEntries,
             ensureParentDirectoryPath: VSCODE_DIRECTORY_PATH,
         });
+        return status;
     }
     /**
      * Resolves the default string-record entry that `coder init` merges into VS Code settings.
@@ -44356,34 +44748,32 @@
     /**
      * Creates or updates all coder configuration artifacts required in the current project.
      *
+     * Nothing the project already owns is ever overwritten - existing scripts, settings and files are kept as they are,
+     * and the artifacts they would reference are created only together with the scripts which actually reference them.
+     *
      * @private internal utility of `coder init` command
      */
     async function initializeCoderProjectConfiguration(projectPath) {
         const promptsDirectoryStatus = await ensureDirectory(projectPath, PROMPTS_DIRECTORY_PATH$1);
         const promptsDoneDirectoryStatus = await ensureDirectory(projectPath, PROMPTS_DONE_DIRECTORY_PATH);
         const promptsTemplatesDirectoryStatus = await ensureDirectory(projectPath, PROMPTS_TEMPLATES_DIRECTORY_PATH);
-        const promptTemplateFileStatuses = await ensureDefaultCoderPromptTemplateFiles(projectPath);
         const agentsDirectoryStatus = await ensureDirectory(projectPath, CODER_AGENTS_DIRECTORY_PATH);
-        const developerAgentFileStatus = await ensureCoderDeveloperAgentFile(projectPath);
-        const agentsFileStatus = await ensureCoderMarkdownFile(projectPath, AGENTS_FILE_PATH, getDefaultCoderAgentsFileContent());
-        const agentCodingFileStatus = await ensureCoderMarkdownFile(projectPath, AGENT_CODING_FILE_PATH, getDefaultCoderAgentCodingFileContent());
         const { envFileStatus, initializedEnvVariableNames } = await ensureCoderEnvFile(projectPath);
         const gitignoreFileStatus = await ensureCoderGitignoreFile(projectPath);
-        const packageJsonFileStatus = await ensureCoderPackageJsonFile(projectPath);
+        const { status: packageJsonFileStatus, addedEntryKeys: addedPackageJsonScriptNames } = await ensureCoderPackageJsonFile(projectPath);
         const vscodeSettingsFileStatus = await ensureCoderVscodeSettingsFile(projectPath);
+        const referencedArtifactStatuses = await ensureCoderReferencedArtifacts(projectPath, resolveCoderPackageJsonScriptReferencedArtifactPaths(addedPackageJsonScriptNames));
         return {
             promptsDirectoryStatus,
             promptsDoneDirectoryStatus,
             promptsTemplatesDirectoryStatus,
-            promptTemplateFileStatuses,
             agentsDirectoryStatus,
-            developerAgentFileStatus,
-            agentsFileStatus,
-            agentCodingFileStatus,
             envFileStatus,
             gitignoreFileStatus,
             packageJsonFileStatus,
             vscodeSettingsFileStatus,
+            addedPackageJsonScriptNames,
+            referencedArtifactStatuses,
             initializedEnvVariableNames,
         };
     }
@@ -44399,17 +44789,20 @@
         printInitializationStatusLine('prompts/', summary.promptsDirectoryStatus);
         printInitializationStatusLine('prompts/done/', summary.promptsDoneDirectoryStatus);
         printInitializationStatusLine('prompts/templates/', summary.promptsTemplatesDirectoryStatus);
-        for (const templateFileStatus of summary.promptTemplateFileStatuses) {
-            printInitializationStatusLine(formatDisplayPath(templateFileStatus.relativeFilePath), templateFileStatus.status);
-        }
         printInitializationStatusLine('agents/', summary.agentsDirectoryStatus);
-        printInitializationStatusLine(CODER_DEVELOPER_AGENT_FILE_PATH, summary.developerAgentFileStatus);
-        printInitializationStatusLine(AGENTS_FILE_PATH, summary.agentsFileStatus);
-        printInitializationStatusLine(AGENT_CODING_FILE_PATH, summary.agentCodingFileStatus);
         printInitializationStatusLine('.env', summary.envFileStatus);
         printInitializationStatusLine('.gitignore', summary.gitignoreFileStatus);
         printInitializationStatusLine('package.json', summary.packageJsonFileStatus);
         printInitializationStatusLine('.vscode/settings.json', summary.vscodeSettingsFileStatus);
+        for (const referencedArtifactStatus of summary.referencedArtifactStatuses) {
+            printInitializationStatusLine(formatDisplayPath(referencedArtifactStatus.relativeFilePath), referencedArtifactStatus.status);
+        }
+        if (summary.addedPackageJsonScriptNames.length > 0) {
+            printInitializationNote(`Added npm scripts: ${summary.addedPackageJsonScriptNames.join(', ')}`, colors__default["default"].cyan);
+        }
+        else {
+            printInitializationNote('All Promptbook coder npm scripts are already present.', colors__default["default"].gray);
+        }
         if (summary.initializedEnvVariableNames.length > 0) {
             printInitializationNote(`Added env variables: ${summary.initializedEnvVariableNames.join(', ')}`, colors__default["default"].cyan);
         }
@@ -44427,6 +44820,9 @@
         if (status === 'updated') {
             return 'updated';
         }
+        if (status === 'not-referenced') {
+            return 'not referenced by the added scripts, kept as is';
+        }
         return 'unchanged';
     }
     /**
@@ -44469,39 +44865,48 @@
                 ${block(listDefaultCoderProjectPromptTemplateDisplayPaths())}
                 - ${CODER_DEVELOPER_AGENT_FILE_PATH}
                 - ${AGENTS_FILE_PATH}
-                - ${AGENT_CODING_FILE_PATH}
                 - .gitignore with local artifacts from every supported harness
                 - package.json
                 - .vscode/settings.json
 
+                Never overwrites what the project already owns:
+                - Existing package.json scripts and .vscode/settings.json settings are kept, only missing ones are added
+                - Files referenced by a script, like the agent and context of coder:run, are created only together
+                  with the script which references them
+
                 Ensures required coding-agent environment variables in .env:
                 - CODING_AGENT_GIT_NAME
                 - CODING_AGENT_GIT_EMAIL
                 - CODING_AGENT_GIT_SIGNING_KEY
 
-                Checks that the coding harnesses are installed and up to date unless \`--no-harness-update\` is used:
+                Checks that the coding harnesses are installed and up to date unless \`--no-questions\` is used:
                 ${block(listCheckedHarnessLabels())}
 
                 ${block(CODER_GIT_SYNC_DESCRIPTION)}
+
+                ${block(QUESTIONS_DESCRIPTION)}
             `));
         addCoderGitSyncOptions(command);
-        addHarnessUpdateOption(command);
+        addQuestionsOption(command);
         command.action(handleActionErrors(async (cliOptions) => {
             const gitSync = normalizeCoderGitSyncCliOptions(cliOptions);
-            const { isHarnessUpdateCheckEnabled } = normalizeHarnessUpdateCliOptions(cliOptions);
+            const questionsOptions = normalizeQuestionsCliOptions(cliOptions);
             const projectPath = process.cwd();
             // Note: Import the git synchronization dynamically to keep the CLI fast for runs without `--commit`
             const { $commitCoderChanges, $startCoderGitSync } = await Promise.resolve().then(function () { return coderGitSync; });
             const commitScope = await $startCoderGitSync({ gitSync, projectPath });
+            const isPromptsDirectoryEmpty = await isDirectoryEmpty(projectPath, PROMPTS_DIRECTORY_PATH$1);
             const summary = await initializeCoderProjectConfiguration(projectPath);
             printInitializationSummary(summary);
-            await generatePromptBoilerplate({ projectPath, boilerplateCount: DEFAULT_BOILERPLATE_COUNT });
+            if (isPromptsDirectoryEmpty) {
+                await generatePromptBoilerplate({ projectPath, boilerplateCount: DEFAULT_BOILERPLATE_COUNT });
+            }
             await $commitCoderChanges({
                 gitSync,
                 commitScope,
                 commitMessage: 'Initialize Promptbook Coder',
             });
-            await $ensureHarnessInstallations(CODER_INIT_CHECKED_HARNESS_NAMES, isHarnessUpdateCheckEnabled);
+            await $ensureHarnessInstallations(CODER_INIT_CHECKED_HARNESS_NAMES, questionsOptions);
         }));
     }
     /**
@@ -44558,6 +44963,23 @@
     // Note: [🟡] Code for CLI prompt priority options [promptPriorityCliOptions](src/cli/cli-commands/common/promptPriorityCliOptions.ts) should never be published outside of `@promptbook/cli`
     // Note: [💞] Ignore a discrepancy between file name and exported helper names
 
+    /**
+     * Description shared by coder commands which accept an agent Book.
+     *
+     * @private internal utility of `ptbk coder`
+     */
+    const CODER_AGENT_OPTION_DESCRIPTION = 'Path to a .book file used to personalize coding prompts and select agent-specific tasks';
+    /**
+     * Registers the shared `--agent` option for coder commands.
+     *
+     * @private internal utility of `ptbk coder`
+     */
+    function addCoderAgentOption(command) {
+        command.option('--agent <agent-book-path>', CODER_AGENT_OPTION_DESCRIPTION);
+    }
+    // Note: [🟡] Code for CLI coder agent options should never be published outside of `@promptbook/cli`
+    // Note: [💞] Ignore a discrepancy between file name and exported helper names
+
     /**
      * Initializes `coder list` command for Promptbook CLI utilities.
      *
@@ -44575,19 +44997,27 @@
             Features:
             - Lists only ready, fully authored prompts
             - Groups prompts from highest to lowest priority
-            - Optional --harness and --model filters show only prompts compatible with that runner
+            - Optional --harness, --model and --agent filters show only prompts compatible with that selection
             - Does not start a coding harness or modify prompt files
         `));
         addPromptRunnerSelectionOptions(command);
+        addCoderAgentOption(command);
         addPromptPriorityOptions(command);
         command.action(handleActionErrors(async (cliOptions) => {
-            const { priority, minPriority: minimumPriority, maxPriority: maximumPriority, } = cliOptions;
+            const { agent, priority, minPriority: minimumPriority, maxPriority: maximumPriority, } = cliOptions;
             const runnerOptions = normalizePromptRunnerSelectionCliOptions(cliOptions, { isAgentRequired: false });
-            const promptRunnerIdentity = runnerOptions.agentName === undefined && runnerOptions.model === undefined
+            const resolvedCoderAgentBook = agent === undefined
+                ? undefined
+                : await (await Promise.resolve().then(function () { return resolveCoderAgent$1; }))
+                    .resolveCoderAgentBook(agent, process.cwd());
+            const promptRunnerIdentity = runnerOptions.agentName === undefined &&
+                runnerOptions.model === undefined &&
+                resolvedCoderAgentBook === undefined
                 ? undefined
                 : {
                     harnessName: runnerOptions.agentName,
                     modelName: runnerOptions.model,
+                    agentReferences: resolvedCoderAgentBook === null || resolvedCoderAgentBook === void 0 ? void 0 : resolvedCoderAgentBook.agentReferences,
                 };
             // Note: Import dynamically to avoid loading prompt parsing dependencies until this command is used.
             const { listCoderPrompts } = await Promise.resolve().then(function () { return listCoderPrompts$1; });
@@ -44655,7 +45085,7 @@
      *
      * @private internal utility of `ptbk coder`
      */
-    async function $ensureCoderHarnessGitignoreRules(projectPath, harnessName) {
+    async function $ensureCoderHarnessGitignoreRules(projectPath, harnessName, questionsOptions) {
         if (harnessName === undefined) {
             return;
         }
@@ -44666,7 +45096,7 @@
         const { label } = getHarnessDefinition(harnessName);
         const formattedRules = formatGitignoreRules(missingRules);
         const entryLabel = missingRules.length === 1 ? 'entry' : 'entries';
-        const isAdditionApproved = await $askForConfirmation(`Add the missing ${label} ignore ${entryLabel} ${formattedRules} to \`.gitignore\` now?`);
+        const isAdditionApproved = await $askForConfirmation(`Add the missing ${label} ignore ${entryLabel} ${formattedRules} to \`.gitignore\` now?`, questionsOptions);
         if (!isAdditionApproved) {
             console.info(colors__default["default"].gray(`Skipped, add ${formattedRules} to \`.gitignore\` manually.`));
             return;
@@ -44691,22 +45121,24 @@
      */
     function $initializeCoderPingCommand(program) {
         const command = program.command('ping');
-        command.description(_spaceTrim.spaceTrim(`
-            Send one tiny dummy prompt to a harness and model to measure and warm them up
+        command.description(_spaceTrim.spaceTrim((block) => `
+                Send one tiny dummy prompt to a harness and model to measure and warm them up
 
-            ${PROMPT_RUNNER_DESCRIPTION}
+                ${block(PROMPT_RUNNER_DESCRIPTION)}
 
-            Features:
-            - Verifies that the selected harness, model, thinking level and authentication really work
-            - Reports the answer of the harness, the response time and the reported usage
-            - Starts the hourly/weekly quota window before you need it, so it is already refreshing when you do
-            - Optional --period keeps the quota window refreshing by pinging once per period until stopped
-            - Makes no coding changes or commits; if the selected harness has missing local ignore rules, offers to add them to .gitignore
-            - Checks that the selected harness is installed and up to date unless --no-harness-update is used
-            - Use --no-ui to stream the raw harness output instead of only the compact result
-        `));
+                ${block(QUESTIONS_DESCRIPTION)}
+
+                Features:
+                - Verifies that the selected harness, model, thinking level and authentication really work
+                - Reports the answer of the harness, the response time and the reported usage
+                - Starts the hourly/weekly quota window before you need it, so it is already refreshing when you do
+                - Optional --period keeps the quota window refreshing by pinging once per period until stopped
+                - Makes no coding changes or commits; if the selected harness has missing local ignore rules, offers to add them to .gitignore
+                - Checks that the selected harness is installed and up to date unless --no-questions is used
+                - Use --no-ui to stream the raw harness output instead of only the compact result
+            `));
         addPromptRunnerSelectionOptions(command);
-        addHarnessUpdateOption(command);
+        addQuestionsOption(command);
         addPromptRunnerRuntimeOptions(command);
         command.option('--period <duration>', _spaceTrim.spaceTrim(`
             Keep pinging once per period instead of pinging only once.
@@ -44715,11 +45147,11 @@
         command.action(handleActionErrors(async (cliOptions) => {
             const { period: periodValue } = cliOptions;
             const runnerOptions = normalizePromptRunnerSelectionCliOptions(cliOptions, { isAgentRequired: true });
-            const { isHarnessUpdateCheckEnabled } = normalizeHarnessUpdateCliOptions(cliOptions);
+            const questionsOptions = normalizeQuestionsCliOptions(cliOptions);
             // Note: The period is validated before the harness installation check, so a mistyped duration fails fast
             const periodMs = parseOptionalPeriodDuration('--period', periodValue);
-            await $ensureHarnessInstallations([runnerOptions.agentName], isHarnessUpdateCheckEnabled);
-            await $ensureCoderHarnessGitignoreRules(process.cwd(), runnerOptions.agentName);
+            await $ensureHarnessInstallations([runnerOptions.agentName], questionsOptions);
+            await $ensureCoderHarnessGitignoreRules(process.cwd(), runnerOptions.agentName, questionsOptions);
             const pingOptions = {
                 agentName: runnerOptions.agentName,
                 model: runnerOptions.model,
@@ -44742,6 +45174,159 @@
     // Note: [🟡] Code for CLI command [ping](src/cli/cli-commands/coder/ping.ts) should never be published outside of `@promptbook/cli`
     // Note: [💞] Ignore a discrepancy between file name and entity name
 
+    /**
+     * Free disk space below which `ptbk coder` refuses to start a new run.
+     *
+     * A coding round writes prompt and log artifacts, lets the harness rewrite the project, may install npm packages,
+     * may create a git worktree for `--isolate` and usually runs a build, so a run started with less than this
+     * would very likely die somewhere in the middle with a filesystem error.
+     *
+     * @private internal utility of `promptbookCli`
+     */
+    const LOW_FREE_DISK_SPACE_BYTES = 2 * 1024 * 1024 * 1024;
+    /**
+     * Free disk space below which a started `ptbk coder` run stops at its next checkpoint and waits until space is freed.
+     *
+     * This limit is lower than `LOW_FREE_DISK_SPACE_BYTES`, because interrupting a run which is already in progress
+     * is more expensive than not starting one at all.
+     *
+     * @private internal utility of `promptbookCli`
+     */
+    const CRITICALLY_LOW_FREE_DISK_SPACE_BYTES = 1 * 1024 * 1024 * 1024;
+    /**
+     * How long one free disk space measurement is reused before the filesystem is measured again during a run.
+     *
+     * Pause checkpoints are passed very often - for example on every tick of a timed wait - so without this
+     * interval the filesystem would be measured many times per second.
+     *
+     * @private internal utility of `promptbookCli`
+     */
+    const FREE_DISK_SPACE_RECHECK_INTERVAL_MS = 60 * 1000;
+    // Note: [🟡] Code for CLI free disk space handling [freeDiskSpaceConstants](src/cli/cli-commands/common/disk-space/freeDiskSpaceConstants.ts) should never be published outside of `@promptbook/cli`
+    // Note: [💞] Ignore a discrepancy between file name and entity name
+
+    /**
+     * Classifies one measured amount of free disk space against the `ptbk coder` free disk space limits.
+     *
+     * @private internal utility of `promptbookCli`
+     */
+    function resolveFreeDiskSpaceLevel(availableBytes) {
+        if (availableBytes < CRITICALLY_LOW_FREE_DISK_SPACE_BYTES) {
+            return 'critical';
+        }
+        if (availableBytes < LOW_FREE_DISK_SPACE_BYTES) {
+            return 'low';
+        }
+        return 'sufficient';
+    }
+    // Note: [🟡] Code for CLI free disk space handling [resolveFreeDiskSpaceLevel](src/cli/cli-commands/common/disk-space/resolveFreeDiskSpaceLevel.ts) should never be published outside of `@promptbook/cli`
+
+    /**
+     * Measures the free disk space on the filesystem which hosts the given path.
+     *
+     * Note: `$` is used to indicate that this function is not a pure function - it reads the state of the filesystem
+     *
+     * @returns the measurement, or `null` when the filesystem can not be measured, for example on a platform which
+     *          does not report filesystem statistics - a run is never stopped by a measurement which could not be taken
+     * @private internal utility of `promptbookCli`
+     */
+    async function $readFreeDiskSpaceStatus(inspectedPath) {
+        try {
+            const fileSystemStats = await promises.statfs(inspectedPath);
+            const blockSizeBytes = fileSystemStats.bsize;
+            const availableBytes = fileSystemStats.bavail * blockSizeBytes;
+            const totalBytes = fileSystemStats.blocks * blockSizeBytes;
+            if (!Number.isFinite(availableBytes) || availableBytes < 0) {
+                return null;
+            }
+            return {
+                inspectedPath,
+                availableBytes,
+                totalBytes,
+                level: resolveFreeDiskSpaceLevel(availableBytes),
+            };
+        }
+        catch (_a) {
+            // Note: A path or a platform which can not report its free disk space must not stop `ptbk coder` from running
+            return null;
+        }
+    }
+    // Note: [🟡] Code for CLI free disk space handling [$readFreeDiskSpaceStatus](src/cli/cli-commands/common/disk-space/$readFreeDiskSpaceStatus.ts) should never be published outside of `@promptbook/cli`
+
+    /**
+     * Byte units used when one amount of disk space is written for a human.
+     */
+    const FREE_DISK_SPACE_BYTE_UNITS = ['B', 'KB', 'MB', 'GB', 'TB', 'PB'];
+    /**
+     * Writes one byte count as a compact human-readable amount of disk space, for example `812 MB` or `1.5 GB`.
+     *
+     * @private internal utility of `promptbookCli`
+     */
+    function formatFreeDiskSpaceBytes(bytes) {
+        if (!Number.isFinite(bytes) || bytes <= 0) {
+            return '0 B';
+        }
+        const unitIndex = Math.min(FREE_DISK_SPACE_BYTE_UNITS.length - 1, Math.floor(Math.log(bytes) / Math.log(1024)));
+        const value = bytes / Math.pow(1024, unitIndex);
+        // Note: One decimal place only matters for small values, `476 GB` is more readable than `476.3 GB`
+        const decimalPlaceCount = value >= 10 || unitIndex === 0 ? 0 : 1;
+        // Note: An empty decimal place only adds noise, `2 GB` is more readable than `2.0 GB`
+        const displayedValue = value.toFixed(decimalPlaceCount).replace(/\.0$/, '');
+        return `${displayedValue} ${FREE_DISK_SPACE_BYTE_UNITS[unitIndex]}`;
+    }
+    // Note: [🟡] Code for CLI free disk space handling [formatFreeDiskSpaceBytes](src/cli/cli-commands/common/disk-space/formatFreeDiskSpaceBytes.ts) should never be published outside of `@promptbook/cli`
+
+    /**
+     * Writes the shared warning which explains one low free disk space measurement and how to get out of it.
+     *
+     * The very same wording is used by the check which refuses to start a run and by the check which pauses
+     * a run that ran out of disk space while it was working.
+     *
+     * @private internal utility of `promptbookCli`
+     */
+    function formatLowFreeDiskSpaceWarning(freeDiskSpaceStatus) {
+        const { inspectedPath } = freeDiskSpaceStatus;
+        const availableSpace = formatFreeDiskSpaceBytes(freeDiskSpaceStatus.availableBytes);
+        const totalSpace = formatFreeDiskSpaceBytes(freeDiskSpaceStatus.totalBytes);
+        const requiredSpaceToStart = formatFreeDiskSpaceBytes(LOW_FREE_DISK_SPACE_BYTES);
+        const requiredSpaceToContinue = formatFreeDiskSpaceBytes(CRITICALLY_LOW_FREE_DISK_SPACE_BYTES);
+        return _spaceTrim.spaceTrim(`
+        Only **${availableSpace}** of ${totalSpace} is left on the disk which hosts \`${inspectedPath}\`.
+
+        **\`ptbk coder\` needs at least ${requiredSpaceToStart} of free disk space to start a run and at least ${requiredSpaceToContinue} to keep one running.**
+
+        Actionable hints:
+        - Free up disk space on the drive which hosts \`${inspectedPath}\`.
+        - Remove build artifacts, package caches and \`node_modules\` folders of projects you are not working on.
+        - Remove the temporary worktrees which earlier \`--isolate\` runs left behind.
+    `);
+    }
+    // Note: [🟡] Code for CLI free disk space handling [formatLowFreeDiskSpaceWarning](src/cli/cli-commands/common/disk-space/formatLowFreeDiskSpaceWarning.ts) should never be published outside of `@promptbook/cli`
+
+    /**
+     * Refuses to start one `ptbk coder` command when the disk which hosts the project is nearly full.
+     *
+     * A run which starts without enough free disk space fails somewhere in the middle, after the coding agent has
+     * already rewritten a part of the project, so it is stopped before it writes anything at all.
+     *
+     * Note: `$` is used to indicate that this function is not a pure function - it reads the state of the filesystem
+     *
+     * @throws {LimitReachedError} when there is not enough free disk space left to start
+     * @private internal utility of `promptbookCli`
+     */
+    async function $assertSufficientFreeDiskSpace(inspectedPath) {
+        const freeDiskSpaceStatus = await $readFreeDiskSpaceStatus(inspectedPath);
+        if (freeDiskSpaceStatus === null || freeDiskSpaceStatus.level === 'sufficient') {
+            return;
+        }
+        throw new LimitReachedError(_spaceTrim.spaceTrim((block) => `
+                There is not enough free disk space to run \`ptbk coder\`.
+
+                ${block(formatLowFreeDiskSpaceWarning(freeDiskSpaceStatus))}
+            `));
+    }
+    // Note: [🟡] Code for CLI free disk space handling [$assertSufficientFreeDiskSpace](src/cli/cli-commands/common/disk-space/$assertSufficientFreeDiskSpace.ts) should never be published outside of `@promptbook/cli`
+
     /**
      * Npm packages which directly provide the `ptbk` executable.
      *
@@ -45070,7 +45655,11 @@
      * @returns `true` when at least one installation was updated and the current coder run should stop
      * @private internal utility of `promptbookCli`
      */
-    async function $ensurePromptbookCliInstallations() {
+    async function $ensurePromptbookCliInstallations(questionsOptions) {
+        if (!questionsOptions.isAskingQuestionsEnabled) {
+            // Note: `--no-questions` forbids asking for the approval, so the registry checks would be useless
+            return false;
+        }
         if (!process.stdin.isTTY) {
             // Note: Non-interactive runs cannot approve an update and should not wait for registry checks
             return false;
@@ -45082,7 +45671,7 @@
             return false;
         }
         console.warn(colors__default["default"].yellow(formatPromptbookCliInstallationWarning(outdatedStatuses)));
-        const isUpdateApproved = await $askForNpmPackageInstallationApproval('Update Promptbook CLI now?');
+        const isUpdateApproved = await $askForNpmPackageInstallationApproval('Update Promptbook CLI now?', questionsOptions);
         if (!isUpdateApproved) {
             reportManualPromptbookCliUpdateCommands(outdatedStatuses);
             return false;
@@ -45149,6 +45738,17 @@
         return TEST_BEFORE_MODE_VALUES.includes(value);
     }
 
+    /**
+     * Prints why a coder run has ended to the terminal.
+     *
+     * @private internal utility of `coder run` and `coder server` commands
+     */
+    function printCoderRunFailure(error) {
+        console.error(colors__default["default"].bgRed(`${error.name}`));
+        console.error(colors__default["default"].red(formatUnknownErrorDetails(error)));
+    }
+    // Note: [🟡] Code for coder failure reporting [printCoderRunFailure](src/cli/cli-commands/coder/printCoderRunFailure.ts) should never be published outside of `@promptbook/cli`
+
     /**
      * Initializes `coder run` command for Promptbook CLI utilities
      *
@@ -45158,10 +45758,12 @@
      */
     function $initializeCoderRunCommand(program) {
         const command = program.command('run');
-        command.description(_spaceTrim.spaceTrim(`
+        command.description(_spaceTrim.spaceTrim((block) => `
             Execute coding prompts through selected AI agent
 
-            ${PROMPT_RUNNER_DESCRIPTION}
+            ${block(PROMPT_RUNNER_DESCRIPTION)}
+
+            ${block(QUESTIONS_DESCRIPTION)}
 
             Features:
             - Automatically stages and commits changes with agent identity unless --no-commit is used
@@ -45171,9 +45773,11 @@
             - 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
+            - Saves the run trace of every round into prompts/traces/, named after its prompt file
             - 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 and up to date before the first prompt unless --no-harness-update is used
+            - Refuses to start on a nearly full disk and pauses the run when the free disk space becomes critical, unless --no-questions is used
+            - Checks that the selected harness is installed and up to date before the first prompt unless --no-questions is used
             - Offers to add missing project-local ignore rules for the selected harness
             - In interactive mode, checks local and global Promptbook CLI installations and offers to update them
             - Supports GPG signing of commits
@@ -45184,8 +45788,8 @@
         `));
         command.option('--dry-run', 'Print unwritten prompts without executing', false);
         addPromptRunnerSelectionOptions(command);
-        addHarnessUpdateOption(command);
-        command.option('--agent <agent-book-path>', 'Path to a .book file whose compiled system message is prepended to each coding prompt');
+        addQuestionsOption(command);
+        addCoderAgentOption(command);
         command.option('--context <context-or-file>', 'Append extra instructions either inline or from a file path relative to the current project');
         command.option('--test <test-command...>', 'Run a verification command after each prompt; quote it when the command itself contains top-level flags');
         command.addOption(new commander.Option('--test-before <mode>', `Run tests before coding: ${TEST_BEFORE_MODE_VALUES.join(', ')} (defaults to no; uses npm test when --test is omitted)`)
@@ -45224,7 +45828,7 @@
             const runnerOptions = normalizePromptRunnerCliOptions(cliOptions, {
                 isAgentRequired: !dryRun,
             });
-            const { isHarnessUpdateCheckEnabled } = normalizeHarnessUpdateCliOptions(cliOptions);
+            const questionsOptions = normalizeQuestionsCliOptions(cliOptions);
             // [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)
@@ -45232,11 +45836,15 @@
             //   --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 (await $ensurePromptbookCliInstallations()) {
+            assertUserConfirmationIsAllowed({ ...questionsOptions, isWaitingForUser: waitForUser });
+            // Note: Checked before anything is installed or written, because installing a harness, updating the
+            //       Promptbook CLI and coding itself all need the disk space which is missing
+            await $assertSufficientFreeDiskSpace(process.cwd());
+            if (await $ensurePromptbookCliInstallations(questionsOptions)) {
                 return process.exit(0);
             }
-            await $ensureHarnessInstallations([runnerOptions.agentName], isHarnessUpdateCheckEnabled);
-            await $ensureCoderHarnessGitignoreRules(process.cwd(), runnerOptions.agentName);
+            await $ensureHarnessInstallations([runnerOptions.agentName], questionsOptions);
+            await $ensureCoderHarnessGitignoreRules(process.cwd(), runnerOptions.agentName, questionsOptions);
             const waitAfterPrompt = parseOptionalWaitDuration(waitAfterPromptValue, 0);
             const waitBetweenPrompts = parseOptionalWaitDuration(waitBetweenPromptsValue, 0);
             const waitAfterError = parseOptionalWaitDuration(waitAfterErrorValue, DEFAULT_WAIT_AFTER_ERROR_MS$1);
@@ -45269,6 +45877,7 @@
                 allowDestructiveAutoMigrate,
                 autoPush: runnerOptions.autoPush,
                 autoPull: runnerOptions.autoPull,
+                isAskingQuestionsEnabled: questionsOptions.isAskingQuestionsEnabled,
             };
             // Note: Import the function dynamically to avoid loading heavy dependencies until needed
             const { runCodexPrompts } = await Promise.resolve().then(function () { return runCodexPrompts$1; });
@@ -45278,8 +45887,7 @@
             }
             catch (error) {
                 assertsError(error);
-                console.error(colors__default["default"].bgRed(`${error.name}`));
-                console.error(colors__default["default"].red(error.stack || error.message));
+                printCoderRunFailure(error);
                 return process.exit(1);
             }
             return process.exit(0);
@@ -45323,28 +45931,31 @@
      */
     function $initializeCoderServerCommand(program) {
         const command = program.command('server');
-        command.description(_spaceTrim.spaceTrim(`
-            Start a coder server that watches for prompts and serves a kanban web UI
+        command.description(_spaceTrim.spaceTrim((block) => `
+                Start a coder server that watches for prompts and serves a kanban web UI
 
-            ${PROMPT_RUNNER_DESCRIPTION}
+                ${block(PROMPT_RUNNER_DESCRIPTION)}
 
-            Features:
-            - Runs the same prompt processing as \`ptbk coder run\`
-            - Checks that the selected harness is installed and up to date on startup unless --no-harness-update is used
-            - Offers to add missing project-local ignore rules for the selected harness
-            - Does not exit when all prompts are done; polls for new prompt files instead
-            - Serves a kanban board at http://localhost:<port> for visual progress tracking
-            - Allows editing prompt files directly from the browser (Trello-style)
-            - Play / pause button in the browser stays in sync with the CLI pause state
-            - Terminal controls match \`ptbk coder run\`: P pause/resume, S skip waiting, X end after current prompt
-        `));
+                ${block(QUESTIONS_DESCRIPTION)}
+
+                Features:
+                - Runs the same prompt processing as \`ptbk coder run\`
+                - Refuses to start on a nearly full disk and pauses the run when the free disk space becomes critical, unless --no-questions is used
+                - Checks that the selected harness is installed and up to date on startup unless --no-questions is used
+                - Offers to add missing project-local ignore rules for the selected harness
+                - Does not exit when all prompts are done; polls for new prompt files instead
+                - Serves a kanban board at http://localhost:<port> for visual progress tracking
+                - Allows editing prompt files directly from the browser (Trello-style)
+                - Play / pause button in the browser stays in sync with the CLI pause state
+                - Terminal controls match \`ptbk coder run\`: P pause/resume, S skip waiting, X end after current prompt
+            `));
         command.addOption(new commander.Option('--port <port>', 'Port to start the coder server on')
             .env('PTBK_CODER_SERVER_PORT')
             .default(DEFAULT_CODER_SERVER_PORT));
         command.option('--dry-run', 'Print unwritten prompts without executing', false);
         addPromptRunnerSelectionOptions(command);
-        addHarnessUpdateOption(command);
-        command.option('--agent <agent-book-path>', 'Path to a .book file whose compiled system message is prepended to each coding prompt');
+        addQuestionsOption(command);
+        addCoderAgentOption(command);
         command.option('--context <context-or-file>', 'Append extra instructions either inline or from a file path relative to the current project');
         command.option('--test <test-command...>', 'Run a verification command after each prompt; quote it when the command itself contains top-level flags');
         command.option('--preserve-logs', 'Keep generated temp prompt/log artifacts after successful rounds for debugging and analytics', false);
@@ -45373,11 +45984,15 @@
             const runnerOptions = normalizePromptRunnerCliOptions(cliOptions, {
                 isAgentRequired: !dryRun,
             });
-            const { isHarnessUpdateCheckEnabled } = normalizeHarnessUpdateCliOptions(cliOptions);
-            await $ensureHarnessInstallations([runnerOptions.agentName], isHarnessUpdateCheckEnabled);
-            await $ensureCoderHarnessGitignoreRules(process.cwd(), runnerOptions.agentName);
+            const questionsOptions = normalizeQuestionsCliOptions(cliOptions);
             // [1] Parse the wait options and --no-auto (same logic as `coder run`)
             const waitForUser = !auto;
+            assertUserConfirmationIsAllowed({ ...questionsOptions, isWaitingForUser: waitForUser });
+            // Note: Checked before anything is installed or written, because installing a harness and coding
+            //       itself both need the disk space which is missing
+            await $assertSufficientFreeDiskSpace(process.cwd());
+            await $ensureHarnessInstallations([runnerOptions.agentName], questionsOptions);
+            await $ensureCoderHarnessGitignoreRules(process.cwd(), runnerOptions.agentName, questionsOptions);
             const waitAfterPrompt = parseOptionalWaitDuration(waitAfterPromptValue, 0);
             const waitBetweenPrompts = parseOptionalWaitDuration(waitBetweenPromptsValue, 0);
             const waitAfterError = parseOptionalWaitDuration(waitAfterErrorValue, DEFAULT_WAIT_AFTER_ERROR_MS$1);
@@ -45407,6 +46022,7 @@
                 allowDestructiveAutoMigrate,
                 autoPush: runnerOptions.autoPush,
                 autoPull: runnerOptions.autoPull,
+                isAskingQuestionsEnabled: questionsOptions.isAskingQuestionsEnabled,
             };
             // Note: Import dynamically to avoid loading heavy dependencies until needed
             const { runCodexPromptsServer } = await Promise.resolve().then(function () { return runCodexPromptsServer$1; });
@@ -45415,8 +46031,7 @@
             }
             catch (error) {
                 assertsError(error);
-                console.error(colors__default["default"].bgRed(`${error.name}`));
-                console.error(colors__default["default"].red(error.stack || error.message));
+                printCoderRunFailure(error);
                 return process.exit(1);
             }
             return process.exit(0);
@@ -45605,11 +46220,7 @@
         $initializeCoderVerifyCommand(coderCommand);
         $initializeCoderFindFreshEmojiTagCommand(coderCommand);
         // If no subcommand is provided, show help
-        coderCommand.action(() => {
-            console.info(colors__default["default"].yellow('Please specify a subcommand.'));
-            console.info('');
-            coderCommand.help();
-        });
+        $requireCliSubcommand(coderCommand);
     }
     // Note: [🟡] Code for CLI command [coder](src/cli/cli-commands/coder.ts) should never be published outside of `@promptbook/cli`
     // Note: [💞] Ignore a discrepancy between file name and entity name
@@ -56199,7 +56810,9 @@
      * @private internal function of `promptbookCli`
      */
     function $initializeRunCommand(program) {
-        const runCommand = program.command('run', { isDefault: true });
+        // Note: `run` is deprecated, so it is intentionally NOT the default command of `ptbk`
+        //       and it must be asked for explicitly
+        const runCommand = program.command('run');
         configureRunCommand(runCommand);
         runCommand.action(handleActionErrors((pipelineSource, cliOptions) => runCommandAction(pipelineSource, cliOptions)));
     }
@@ -58038,9 +58651,24 @@
         command.option('--remote-server-url <url>', `URL of remote server to use when `, DEFAULT_REMOTE_SERVER_URL);
     }
 
+    /**
+     * Keeps one already registered CLI command out of the help of its parent command while the command itself stays
+     * fully usable - it can still be run, it still has its own help and it is still reachable through `ptbk help <command>`.
+     *
+     * Note: `$` is used to indicate that this function is not a pure function - it changes how the CLI renders its help
+     *
+     * @private utility of CLI
+     */
+    function $hideCliCommandFromHelp(command) {
+        command._hidden = true;
+    }
+
     /**
      * Marks one CLI command as deprecated while keeping it available for existing callers.
      *
+     * Deprecated commands are not advertised anymore - they are hidden from the list of commands in the help of their
+     * parent command, they warn when they are used and they explain the deprecation in their own help.
+     *
      * @private utility of CLI
      */
     function $deprecateCliCommand(command, deprecationMessage) {
@@ -58052,6 +58680,7 @@
         command.hook('preAction', () => {
             console.warn(colors__default["default"].yellow(createDeprecatedCliCommandWarning(command, deprecationMessage)));
         });
+        $hideCliCommandFromHelp(command);
     }
     /**
      * Creates the runtime warning printed before a deprecated CLI command action starts.
@@ -58119,10 +58748,17 @@
         program.version(PROMPTBOOK_ENGINE_VERSION);
         program.description(CLAIM);
         // Note: These options are valid for all commands
+        // Note: Commands are listed in the help in the order they are registered,
+        //       `coder` is the most used one so it goes first and the deprecated ones,
+        //       which `$deprecateTopLevelCommands` hides from the help entirely, go last
+        $initializeCoderCommand(program);
+        $initializeAgentCommand(program);
+        $initializeAgentFolderCommand(program);
+        $initializeAgentsServerCommand(program);
         $initializeAboutCommand(program);
+        $initializeHelloCommand(program);
         $initializeRunCommand(program);
         $initializeLoginCommand(program);
-        $initializeHelloCommand(program);
         $initializeMakeCommand(program);
         $initializePrettifyCommand(program);
         $initializeTestCommand(program);
@@ -58130,16 +58766,13 @@
         $initializeListScrapersCommand(program);
         $initializeStartAgentsServerCommand(program);
         $initializeStartPipelinesServerCommand(program);
-        $initializeAgentCommand(program);
-        $initializeAgentFolderCommand(program);
-        $initializeAgentsServerCommand(program);
-        $initializeCoderCommand(program);
         $deprecateTopLevelCommands(program);
         // TODO: [🧠] Should it be here or not> $addGlobalOptionsToCommand(program);
         program.commands.forEach($addGlobalOptionsToCommand);
+        // Note: There is no default command, so `ptbk` without a subcommand asks for one
+        //       instead of running the deprecated `ptbk run`
         if (commandLineArguments.length === 0) {
-            program.outputHelp();
-            return process.exit(0);
+            return $reportMissingCliSubcommand(program);
         }
         program.parse(process.argv);
     }
@@ -58153,7 +58786,7 @@
         return firstCommandLineArgument !== undefined && VERSION_OPTION_ARGUMENTS.has(firstCommandLineArgument);
     }
     /**
-     * Adds one deprecation notice to each configured top-level legacy command.
+     * Marks each configured top-level legacy command as deprecated, which keeps it usable but takes it out of the help.
      */
     function $deprecateTopLevelCommands(program) {
         for (const command of program.commands) {
@@ -58164,7 +58797,6 @@
         }
     }
     // Note: [🟡] Code for CLI program [promptbookCli](src/cli/promptbookCli.ts) should never be published outside of `@promptbook/cli`
-    // TODO: [🧠] Maybe `run` command the default, instead of `ptbk run ./foo.book` -> `ptbk ./foo.book`
     // TODO: [🥠] Do not export, its just for CLI script
     // TODO: [🕌] When more functionalities, rename
     // Note: 11:11
@@ -59276,7 +59908,9 @@
      */
     function createExecutionToolsFromVercelProvider(options) {
         let { title, description } = options;
-        const { vercelProvider, availableModels, userId, additionalChatSettings = {} } = options;
+        const { vercelProvider, availableModels, additionalChatSettings = {} } = options;
+        // <- Note: `userId` is not forwarded, because Vercel AI SDK moved provider-specific settings like `user` from
+        //          `vercelProvider.chat(modelName, settings)` into `providerOptions` which are keyed by the provider
         if (!/Vercel/i.test(title)) {
             title = `${title} (through Vercel)`;
             // <- TODO: [🧈] Maybe standartize the suffix
@@ -59317,10 +59951,7 @@
 
                     `));
                 }
-                const model = await vercelProvider.chat(modelName, {
-                    user: (userId === null || userId === void 0 ? void 0 : userId.toString()) || undefined,
-                    ...additionalChatSettings,
-                });
+                const model = await vercelProvider.chat(modelName);
                 const rawPromptContent = templateParameters(content, { ...parameters, modelName });
                 // Support for passing a chat thread (multi-message conversation)
                 let promptMessages;
@@ -59358,14 +59989,9 @@
                 }
                 const rawRequest = {
                     // <- TODO: [☂]
-                    inputFormat: 'messages',
-                    mode: {
-                        type: 'regular',
-                        tools: [
-                        /* <- TODO: Pass the tools */
-                        ],
-                    },
                     prompt: promptMessages,
+                    // <- TODO: Pass the tools via `tools`
+                    ...additionalChatSettings,
                 };
                 const start = $getCurrentDate();
                 if (options.isVerbose) {
@@ -59382,28 +60008,31 @@
                 if (options.isVerbose) {
                     console.info(colors__default["default"].bgWhite('rawResponse'), JSON.stringify(rawResponse, null, 4));
                 }
-                if (rawResponse.text === undefined) {
+                // Note: Vercel AI SDK returns ordered content parts, the chat message is made only of the text parts
+                const responseTextParts = rawResponse.content.flatMap((contentPart) => contentPart.type === 'text' ? [contentPart.text] : []);
+                if (responseTextParts.length === 0) {
                     throw new PipelineExecutionError('No response message');
                 }
+                const responseText = responseTextParts.join('');
                 const complete = $getCurrentDate();
                 const duration = uncertainNumber((new Date(complete).getTime() - new Date(start).getTime()) / 1000);
                 const usage = {
                     price: UNCERTAIN_ZERO_VALUE,
                     duration,
                     input: {
-                        tokensCount: uncertainNumber(rawResponse.usage.promptTokens),
+                        tokensCount: uncertainNumber(rawResponse.usage.inputTokens),
                         ...computeUsageCounts(rawPromptContent),
                     },
                     output: {
-                        tokensCount: uncertainNumber(rawResponse.usage.completionTokens),
-                        ...computeUsageCounts(rawResponse.text),
+                        tokensCount: uncertainNumber(rawResponse.usage.outputTokens),
+                        ...computeUsageCounts(responseText),
                     },
                 };
                 return exportJson({
                     name: 'promptResult',
                     message: `Result of \`createExecutionToolsFromVercelProvider.callChatModel\``,
                     value: {
-                        content: rawResponse.text,
+                        content: responseText,
                         modelName,
                         timing: {
                             start,
@@ -74708,13 +75337,15 @@
     }
 
     /**
-     * Checks whether a prompt is unrestricted or matches the selected harness/model.
+     * Checks whether a prompt is unrestricted or matches the selected harness, model or Book agent.
      *
-     * A prompt status line can contain one or more backtick-delimited model or harness
-     * names. Matching is intentionally based on normalized substrings so a token such as
-     * `gpt` selects any `gpt-*` model and `opus` selects a `claude-opus-*` model.
+     * A prompt status line can contain one or more backtick-delimited model, harness or agent
+     * references. Matching is intentionally based on normalized substrings so a token such as
+     * `gpt` selects any `gpt-*` model, `developer` selects an agent Book named `developer.book`,
+     * and `opus` selects a `claude-opus-*` model.
      */
     function isPromptCompatibleWithRunner(file, section, promptRunnerIdentity) {
+        var _a;
         if (promptRunnerIdentity === undefined) {
             return true;
         }
@@ -74723,7 +75354,11 @@
         if (requiredRunnerTokens.length === 0) {
             return true;
         }
-        const normalizedRunnerNames = [promptRunnerIdentity.harnessName, promptRunnerIdentity.modelName]
+        const normalizedRunnerNames = [
+            promptRunnerIdentity.harnessName,
+            promptRunnerIdentity.modelName,
+            ...((_a = promptRunnerIdentity.agentReferences) !== null && _a !== void 0 ? _a : []),
+        ]
             .filter((name) => name !== undefined && name.trim() !== '')
             .map((name) => normalizeToKebabCase(name))
             .filter((name) => name !== '');
@@ -74734,7 +75369,7 @@
         });
     }
     /**
-     * Extracts model and harness tokens from a prompt status line.
+     * Extracts model, harness and Book-agent tokens from a prompt status line.
      */
     function extractPromptRunnerTokens(statusLine) {
         return Array.from(statusLine.matchAll(/`([^`]+)`/gu))
@@ -74749,7 +75384,7 @@
      *
      * @private internal constant of `parsePromptFile`
      */
-    const PROMPT_STATUS_MARKER_PATTERN = /^\[(?: |-|[xX]|\^|!)\]/u;
+    const PROMPT_STATUS_LINE_PATTERN = /^\[(?<marker> |-|\.|[xX]|\^|!)\](?<details>.*)$/u;
     /**
      * Parses a prompt markdown file into sections and metadata.
      */
@@ -74773,7 +75408,7 @@
             if (firstNonEmptyLine !== undefined) {
                 const statusLine = (lines[firstNonEmptyLine] || '').trim();
                 const parsedStatus = parseStatusLine(statusLine);
-                const status = (_a = parsedStatus === null || parsedStatus === void 0 ? void 0 : parsedStatus.status) !== null && _a !== void 0 ? _a : (hasPromptStatusMarker(statusLine) ? 'not-ready' : 'todo');
+                const status = (_a = parsedStatus === null || parsedStatus === void 0 ? void 0 : parsedStatus.status) !== null && _a !== void 0 ? _a : (PROMPT_STATUS_LINE_PATTERN.test(statusLine) ? 'not-ready' : 'todo');
                 const priority = (_b = parsedStatus === null || parsedStatus === void 0 ? void 0 : parsedStatus.priority) !== null && _b !== void 0 ? _b : 0;
                 sections.push({
                     index,
@@ -74801,51 +75436,47 @@
      * For [x] done, [!] failed and [^] in-progress prompts, allow metadata after the status marker.
      */
     function parseStatusLine(line) {
-        var _a, _b, _c, _d;
-        // For done prompts [x], allow any content after (for cost/time metadata)
-        const doneMatch = line.match(/^\[(?<status>[xX])\]/);
-        if (doneMatch) {
+        var _a, _b, _c, _d, _e;
+        const statusLineMatch = line.match(PROMPT_STATUS_LINE_PATTERN);
+        const marker = (_a = statusLineMatch === null || statusLineMatch === void 0 ? void 0 : statusLineMatch.groups) === null || _a === void 0 ? void 0 : _a.marker;
+        const details = (_c = (_b = statusLineMatch === null || statusLineMatch === void 0 ? void 0 : statusLineMatch.groups) === null || _b === void 0 ? void 0 : _b.details) !== null && _c !== void 0 ? _c : '';
+        if (marker === 'x' || marker === 'X') {
+            // For done prompts [x], allow any content after (for cost/time metadata).
             return { status: 'done', priority: 0 };
         }
-        // For failed prompts [!], allow any content after (for failure metadata)
-        const failedMatch = line.match(/^\[(?<status>!)\]/);
-        if (failedMatch) {
+        if (marker === '!') {
+            // For failed prompts [!], allow any content after (for failure metadata).
             return { status: 'failed', priority: 0 };
         }
-        // For in-progress prompts [^], allow any content after (for the steps recorded so far)
-        const inProgressMatch = line.match(/^\[(?<status>\^)\]/);
-        if (inProgressMatch) {
+        if (marker === '^') {
+            // For in-progress prompts [^], allow any content after (for the steps recorded so far).
             return { status: 'in-progress', priority: 0 };
         }
-        // For not-ready [-], keep the historical clean-line syntax.
-        if (/^\[-\]\s*!*\s*$/u.test(line)) {
+        // Treat [.] as the alternative spelling of not-ready [-], preserving the historical clean-line syntax.
+        if ((marker === '-' || marker === '.') && /^[!\s]*$/u.test(details)) {
             return { status: 'not-ready', priority: 0 };
         }
-        // Todo [ ] may contain backtick-delimited model/harness tokens and priority markers
-        // before or after those tokens. Other trailing text remains an invalid status line.
-        const todoMatch = line.match(/^\[ \](?<details>.*)$/u);
-        if (!todoMatch) {
+        if (marker !== ' ') {
             return undefined;
         }
-        const details = (_b = (_a = todoMatch.groups) === null || _a === void 0 ? void 0 : _a.details) !== null && _b !== void 0 ? _b : '';
+        // Todo [ ] may contain backtick-delimited model/harness tokens and priority markers
+        // before or after those tokens. Other trailing text remains an invalid status line.
         const isPriorityOnly = /^[!\s]*$/u.test(details);
         const hasPromptRunnerTokens = extractPromptRunnerTokens(line).length > 0;
         if (details.trim() !== '' && !isPriorityOnly && !hasPromptRunnerTokens) {
             return undefined;
         }
-        return { status: 'todo', priority: (_d = (_c = details.match(/!/gu)) === null || _c === void 0 ? void 0 : _c.length) !== null && _d !== void 0 ? _d : 0 };
+        return { status: 'todo', priority: (_e = (_d = details.match(/!/gu)) === null || _d === void 0 ? void 0 : _d.length) !== null && _e !== void 0 ? _e : 0 };
     }
+
     /**
-     * Checks whether a line starts with one of the supported prompt status markers.
+     * HTML comment which excludes a Markdown file from all `ptbk coder` queues.
      *
-     * @private internal utility of `parsePromptFile`
+     * @private internal constant of `loadPromptFiles`
      */
-    function hasPromptStatusMarker(line) {
-        return PROMPT_STATUS_MARKER_PATTERN.test(line);
-    }
-
+    const PTBK_CODER_IGNORE_MARKER = '<!--ptbk-coder-ignore-->';
     /**
-     * Loads and parses prompt files from the prompts directory.
+     * Loads and parses prompt files from the prompts directory, excluding files marked for `ptbk coder` to ignore.
      */
     async function loadPromptFiles(promptsDir) {
         const entries = await promises.readdir(promptsDir, { withFileTypes: true });
@@ -74856,6 +75487,9 @@
         const promptFiles = [];
         for (const filePath of files) {
             const content = await promises.readFile(filePath, 'utf-8');
+            if (content.includes(PTBK_CODER_IGNORE_MARKER)) {
+                continue;
+            }
             promptFiles.push(parsePromptFile(filePath, content));
         }
         return promptFiles;
@@ -74965,6 +75599,77 @@
         findUnwrittenPrompts: findUnwrittenPrompts
     });
 
+    /**
+     * Reads an optional agent `.book` file and prepares the references that route prompts to it.
+     *
+     * Returns `undefined` when no agent path is provided.
+     */
+    async function resolveCoderAgentBook(agentBookReference, currentWorkingDirectory) {
+        const normalizedAgentBookReference = agentBookReference === null || agentBookReference === void 0 ? void 0 : agentBookReference.trim();
+        if (!normalizedAgentBookReference) {
+            return undefined;
+        }
+        const resolvedAgentBookPath = path.resolve(currentWorkingDirectory, normalizedAgentBookReference);
+        const agentSource = (await promises.readFile(resolvedAgentBookPath, 'utf-8').catch((error) => {
+            if (error.code === 'ENOENT' || error.code === 'EISDIR') {
+                throw new NotFoundError(spaceTrim(`
+                    Agent book \`${normalizedAgentBookReference}\` was not found or is not a file.
+
+                    Pass a path to a \`.book\` file in \`--agent\`.
+                `));
+            }
+            throw error;
+        }));
+        return {
+            agentSource,
+            agentReferences: createCoderAgentReferences({
+                agentBookReference: normalizedAgentBookReference,
+                resolvedAgentBookPath,
+                currentWorkingDirectory,
+                agentSource,
+            }),
+        };
+    }
+    /**
+     * Reads an optional agent `.book` file and compiles its system message for injection into coder prompts.
+     *
+     * Returns `undefined` when no agent path is provided.
+     */
+    async function resolveCoderAgent(agentBookReference, currentWorkingDirectory) {
+        const resolvedAgentBook = await resolveCoderAgentBook(agentBookReference, currentWorkingDirectory);
+        if (resolvedAgentBook === undefined) {
+            return undefined;
+        }
+        return {
+            ...resolvedAgentBook,
+            systemMessage: await createAgentRunnerSystemMessage(resolvedAgentBook.agentSource),
+        };
+    }
+    /**
+     * Creates the path and Book-title aliases which a prompt can use to target one selected agent.
+     *
+     * @private internal utility of `resolveCoderAgentBook`
+     */
+    function createCoderAgentReferences(options) {
+        const relativeAgentBookPath = path.relative(options.currentWorkingDirectory, options.resolvedAgentBookPath).replaceAll('\\', '/');
+        const agentBookFileName = path.basename(options.resolvedAgentBookPath);
+        const agentBookName = path.basename(options.resolvedAgentBookPath, path.extname(options.resolvedAgentBookPath));
+        const agentNameFromBook = parseAgentSource(options.agentSource).agentName;
+        return Array.from(new Set([
+            options.agentBookReference,
+            relativeAgentBookPath,
+            agentBookFileName,
+            agentBookName,
+            agentNameFromBook,
+        ].filter((agentReference) => agentReference.trim() !== '')));
+    }
+
+    var resolveCoderAgent$1 = /*#__PURE__*/Object.freeze({
+        __proto__: null,
+        resolveCoderAgentBook: resolveCoderAgentBook,
+        resolveCoderAgent: resolveCoderAgent
+    });
+
     /**
      * Lists todo prompts that are ready to run (no authoring placeholders).
      */
@@ -75047,23 +75752,6 @@
         listCoderPrompts: listCoderPrompts
     });
 
-    /**
-     * Formats one unknown error-like value into its readable message without the stack trace.
-     *
-     * Use this instead of `formatUnknownErrorDetails` whenever the text is shown to the user, for example
-     * inside a branded error, where the stack of the wrapped error would only bury the actual cause.
-     */
-    function formatUnknownErrorMessage(error) {
-        if (error instanceof Error) {
-            return error.message;
-        }
-        if (typeof error === 'string') {
-            return error;
-        }
-        const serializedError = JSON.stringify(error, null, 2);
-        return serializedError !== null && serializedError !== void 0 ? serializedError : String(error);
-    }
-
     /**
      * Builds a normalized temporary shell script path for prompt runners.
      */
@@ -75362,7 +76050,7 @@
     /**
      * CLI usage text for this script.
      */
-    const USAGE = 'Usage: run-codex-prompts [--dry-run] [--harness <harness-name>] [--model <model>] [--context <context-or-file>] [--test <test-command...>] [--test-before <no|yes-and-fail|yes-and-fix>] [--preserve-logs] [--isolate] [--no-ui] [--thinking-level <thinking-level>] [--priority <minimum-priority>] [--min-priority <minimum-priority>] [--max-priority <maximum-priority>] [--limit <run-count>] [--allow-credits] [--auto-migrate] [--allow-destructive-auto-migrate] [--wait-after-prompt <duration>] [--wait-between-prompts <duration>] [--wait-after-error <duration>] [--no-auto] [--no-commit] [--git-changes <fail|ignore|continue>] [--no-normalize-line-endings] [--auto-push] [--auto-pull]';
+    const USAGE = 'Usage: run-codex-prompts [--dry-run] [--harness <harness-name>] [--model <model>] [--agent <agent-book-path>] [--context <context-or-file>] [--test <test-command...>] [--test-before <no|yes-and-fail|yes-and-fix>] [--preserve-logs] [--isolate] [--no-ui] [--thinking-level <thinking-level>] [--priority <minimum-priority>] [--min-priority <minimum-priority>] [--max-priority <maximum-priority>] [--limit <run-count>] [--allow-credits] [--auto-migrate] [--allow-destructive-auto-migrate] [--wait-after-prompt <duration>] [--wait-between-prompts <duration>] [--wait-after-error <duration>] [--no-auto] [--no-commit] [--git-changes <fail|ignore|continue>] [--no-normalize-line-endings] [--auto-push] [--auto-pull]';
     /**
      * Top-level flags supported by this command.
      */
@@ -75370,6 +76058,7 @@
         '--dry-run',
         '--harness',
         '--model',
+        '--agent',
         '--context',
         '--test',
         '--test-before',
@@ -75408,6 +76097,7 @@
             }
         }
         const model = readOptionValue(args, '--model');
+        const agent = readOptionValue(args, '--agent');
         const context = readOptionValue(args, '--context');
         const hasTestCommandFlag = args.includes('--test');
         const testCommand = readVariadicOptionValue(args, '--test');
@@ -75484,6 +76174,7 @@
             noUi,
             agentName,
             model,
+            agent,
             context,
             testCommand,
             testBefore,
@@ -75918,30 +76609,43 @@
     // Note: [🟡] Code in this file is only used from `@promptbook/cli` orchestration scripts and is not shipped to other consumers.
 
     /**
-     * Reads an optional agent `.book` file and compiles its system message for injection into coder prompts.
+     * Creates the guard which watches the free disk space while one `ptbk coder` run is in progress.
      *
-     * Returns `undefined` when no agent path is provided.
+     * The guard runs at every pause checkpoint of the run. When the disk became critically full it reports the
+     * warning and requests a pause, so the run stops at that checkpoint instead of failing in the middle of a
+     * coding round, and continues once the user has freed some space and pressed `P`.
+     *
+     * @private internal utility of `ptbk coder` free disk space handling
      */
-    async function resolveCoderAgent(agentPath, currentWorkingDirectory) {
-        if (!agentPath) {
-            return undefined;
-        }
-        const resolvedAgentPath = path.resolve(currentWorkingDirectory, agentPath);
-        const agentSource = await promises.readFile(resolvedAgentPath, 'utf-8').catch((error) => {
-            if (error.code === 'ENOENT' || error.code === 'EISDIR') {
-                throw new NotFoundError(spaceTrim(`
-                    Agent book \`${agentPath}\` was not found or is not a file.
+    function createFreeDiskSpaceGuard(options) {
+        const { inspectedPath, isAskingQuestionsEnabled } = options;
+        let lastMeasurementTimeMs;
+        return async () => {
+            if (lastMeasurementTimeMs !== undefined &&
+                Date.now() - lastMeasurementTimeMs < FREE_DISK_SPACE_RECHECK_INTERVAL_MS) {
+                return;
+            }
+            lastMeasurementTimeMs = Date.now();
+            const freeDiskSpaceStatus = await $readFreeDiskSpaceStatus(inspectedPath);
+            if (freeDiskSpaceStatus === null || freeDiskSpaceStatus.level !== 'critical') {
+                return;
+            }
+            console.warn(colors__default["default"].yellow(_spaceTrim.spaceTrim((block) => `
+                        The disk is running out of space while \`ptbk coder\` is working.
 
-                    Pass a path to a \`.book\` file in \`--agent\`.
-                `));
+                        ${block(formatLowFreeDiskSpaceWarning(freeDiskSpaceStatus))}
+                        - Press \`P\` to continue once the disk space is freed, or start the run with \`--no-questions\` to never pause on a full disk.
+                    `)));
+            if (!isAskingQuestionsEnabled) {
+                // Note: `--no-questions` forbids stopping and waiting for somebody who would free the disk space,
+                //       so the run keeps going and the warning above is the only thing which is reported
+                return;
             }
-            throw error;
-        });
-        return {
-            agentSource: agentSource,
-            systemMessage: await createAgentRunnerSystemMessage(agentSource),
+            announcePauseTargetLabel(`continuing with only ${formatFreeDiskSpaceBytes(freeDiskSpaceStatus.availableBytes)} of free disk space left`);
+            requestPause();
         };
     }
+    // Note: [🟡] Code for `ptbk coder` free disk space handling [createFreeDiskSpaceGuard](scripts/run-codex-prompts/common/createFreeDiskSpaceGuard.ts) should never be published outside of `@promptbook/cli`
 
     /**
      * Refresh interval used by the countdown display while waiting.
@@ -77912,6 +78616,169 @@
         await promises.writeFile(file.path, content, 'utf-8');
     }
 
+    /**
+     * Creates a safe markdown fenced code block even when content contains backticks.
+     *
+     * @param content - Raw code content.
+     * @param language - Optional info-string language label.
+     * @returns Fenced code block.
+     *
+     * @private internal utility of `createStandaloneBookLanguageMarkdown` and of the `ptbk coder` run traces
+     */
+    function getSafeCodeBlock(content, language = 'markdown') {
+        const maxBacktickCount = Math.max(0, ...(content.match(/`+/g) || []).map((match) => match.length));
+        const fence = '`'.repeat(Math.max(3, maxBacktickCount + 1));
+        return `${fence}${language}\n${content}\n${fence}`;
+    }
+
+    /**
+     * Renders the markdown run trace of one finished or failed prompt round.
+     *
+     * The trace pairs the metadata of the round - which harness, model and thinking level ran it, how long each of
+     * its steps took and what it cost - with the untouched runtime log, so a finished round can still be analyzed
+     * after its temporary artifacts are cleaned up.
+     */
+    function buildPromptRunTraceContent(options) {
+        const sections = [
+            buildPromptRunTraceSummarySection(options),
+            buildPromptRunTraceFailureSection(options.outcome),
+            buildPromptRunTraceRuntimeLogSection(options.runtimeLog),
+        ].filter((section) => section !== undefined);
+        return `${sections.join('\n\n')}\n`;
+    }
+    /**
+     * Renders the heading and the metadata bullet list of one run trace.
+     */
+    function buildPromptRunTraceSummarySection(options) {
+        const { file, section, outcome } = options;
+        const runnerSignature = formatRunnerSignature(options.runnerName, options.modelName, options.thinkingLevel);
+        const loginMethodLabel = outcome.kind === 'succeeded' ? formatCodexLoginMethod(outcome.loginMethod) : undefined;
+        const loginMethodSuffix = loginMethodLabel ? ` (${loginMethodLabel})` : '';
+        const detailLines = [
+            `-   **Prompt:** ${buildPromptSummary(file, section)}`,
+            ...buildPromptRunTraceSectionLines(file, section),
+            `-   **Outcome:** ${formatPromptRunTraceOutcomeLabel(outcome)}`,
+            `-   **Runner:** ${runnerSignature}${loginMethodSuffix}`,
+            `-   **Attempts:** ${options.attemptCount}`,
+            ...buildPromptRunTraceStepsLines(outcome),
+            ...buildPromptRunTraceTestCommandLines(options.testCommand),
+            `-   **Started:** ${options.startedDate.toISOString()}`,
+            `-   **Finished:** ${options.finishedDate.toISOString()}`,
+            `-   **Duration:** ${moment__default["default"].duration(options.finishedDate.diff(options.startedDate)).humanize()}`,
+        ];
+        return _spaceTrim.spaceTrim((block) => `
+            # Run trace of \`${buildPromptLabelForDisplay(file, section)}\`
+
+            ${block(detailLines.join('\n'))}
+        `);
+    }
+    /**
+     * Renders which section of its prompt file the round implemented.
+     *
+     * A prompt file holding exactly one section says nothing by naming it, exactly like the section suffix of its
+     * generated artifact names, so only a file with more than one section reports the section it traced.
+     */
+    function buildPromptRunTraceSectionLines(file, section) {
+        if (file.sections.length <= 1) {
+            return [];
+        }
+        return [`-   **Prompt section:** ${section.index + 1} of ${file.sections.length}`];
+    }
+    /**
+     * Renders the per-step usage breakdown of a successful round, omitted for a round which never finished one.
+     */
+    function buildPromptRunTraceStepsLines(outcome) {
+        if (outcome.kind !== 'succeeded') {
+            return [];
+        }
+        const stepsSummary = formatCoderRunSteps(outcome.steps);
+        if (stepsSummary === '') {
+            return [];
+        }
+        return [`-   **Steps:** ${stepsSummary}`];
+    }
+    /**
+     * Renders the verification command of the round, omitted when the round ran without one.
+     */
+    function buildPromptRunTraceTestCommandLines(testCommand) {
+        if (!testCommand) {
+            return [];
+        }
+        return [`-   **Verification command:** \`${testCommand}\``];
+    }
+    /**
+     * Renders the failure details of a failed round, omitted for a successful one.
+     */
+    function buildPromptRunTraceFailureSection(outcome) {
+        if (outcome.kind !== 'failed') {
+            return undefined;
+        }
+        return `## Failure\n\n${getSafeCodeBlock(formatUnknownErrorDetails(outcome.error), 'text')}`;
+    }
+    /**
+     * Renders the untouched runtime log of the round, or says that the round produced none.
+     */
+    function buildPromptRunTraceRuntimeLogSection(runtimeLog) {
+        if (runtimeLog.trim() === '') {
+            return '## Runtime log\n\n_This round has produced no readable runtime log._';
+        }
+        return `## Runtime log\n\n${getSafeCodeBlock(runtimeLog.replace(/\r\n/gu, '\n').trimEnd(), 'text')}`;
+    }
+    /**
+     * Formats the outcome of the round as the human-readable label of its trace.
+     */
+    function formatPromptRunTraceOutcomeLabel(outcome) {
+        return outcome.kind === 'succeeded' ? 'Succeeded' : 'Failed';
+    }
+
+    /**
+     * Name of the directory which keeps the run traces inside the prompts directory.
+     */
+    const PROMPT_RUN_TRACES_DIRECTORY_NAME = 'traces';
+    /**
+     * Builds the path of the run trace which belongs to one prompt section.
+     *
+     * The trace is stored in the `traces` directory of the very same prompts directory the prompt itself lives in,
+     * and it carries the name of its prompt file. A prompt file holding more than one section appends the section
+     * suffix, exactly like the temporary scripts and the isolation worktrees of the same section do.
+     */
+    function buildPromptRunTracePath(file, section) {
+        const promptFileBaseName = file.name.replace(/\.[^.]+$/u, '');
+        const traceFileName = `${promptFileBaseName}${buildPromptSectionSuffix(file, section)}.md`;
+        return path.join(path.dirname(file.path), PROMPT_RUN_TRACES_DIRECTORY_NAME, traceFileName);
+    }
+
+    /**
+     * Writes the run trace of one prompt round into the `traces` directory of the prompts directory.
+     *
+     * Returns the path of the written trace so callers can include it in a commit.
+     */
+    async function writePromptRunTrace(options) {
+        const { logPath, ...contentOptions } = options;
+        const tracePath = buildPromptRunTracePath(options.file, options.section);
+        const runtimeLog = await readPromptRuntimeLog(logPath);
+        await promises.mkdir(path.dirname(tracePath), { recursive: true });
+        await promises.writeFile(tracePath, buildPromptRunTraceContent({ ...contentOptions, runtimeLog }), 'utf-8');
+        return tracePath;
+    }
+    /**
+     * Reads the live runtime log of one round.
+     *
+     * A round which never produced a readable log still gets its trace, because the metadata of the round is worth
+     * keeping on its own - so a missing log is reported as empty instead of failing the round which has just passed.
+     */
+    async function readPromptRuntimeLog(logPath) {
+        if (!logPath) {
+            return '';
+        }
+        try {
+            return await promises.readFile(logPath, 'utf-8');
+        }
+        catch (_a) {
+            return '';
+        }
+    }
+
     /**
      * Refreshes optional harness subscription usage in the shared coder-run UI state.
      *
@@ -78034,7 +78901,9 @@
                 catch (error) {
                     uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.stopCapturingAgentOutput();
                     lastError = error;
-                    if (errorRetryAttempt >= MAX_RETRY_ATTEMPTS_AFTER_ERROR) {
+                    // Note: A harness which is not logged in answers every retry the same way, so the user gets
+                    //       the sign-in instructions right away instead of after every retry has waited its delay
+                    if (error instanceof AuthenticationError || errorRetryAttempt >= MAX_RETRY_ATTEMPTS_AFTER_ERROR) {
                         break;
                     }
                     await waitAfterErrorBeforeRetry({
@@ -78056,6 +78925,7 @@
                 attemptCount,
                 error: lastError,
                 options,
+                logPath,
                 roundCommitScope,
                 uiHandle,
                 waitForRequestedPause,
@@ -78172,6 +79042,17 @@
         // 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);
+        // Note: Written before the round is committed, so the trace of the round lands in the very same commit
+        //       as the prompt it describes, and before the live runtime log it is built from is deleted
+        await recordPromptRoundTrace({
+            options: runOptions,
+            nextPrompt,
+            runnerMetadata,
+            promptExecutionStartedDate,
+            attemptCount: result.attemptCount,
+            logPath,
+            outcome: { kind: 'succeeded', steps: result.steps, loginMethod: result.loginMethod },
+        });
         await normalizeLineEndingsForCurrentRound(runOptions, roundProjectPath, roundCommitScope);
         await recordPromptDurationInEstimateCache({
             options: runOptions,
@@ -78219,7 +79100,7 @@
      * Finalizes a failed prompt round, persisting prompt failure metadata before rethrowing.
      */
     async function finalizeFailedPromptRound(options) {
-        const { nextPrompt, runnerMetadata, previousRunnerSignatures, promptExecutionStartedDate, attemptCount, error, options: runOptions, roundCommitScope, uiHandle, waitForRequestedPause, roundProjectPath, } = options;
+        const { nextPrompt, runnerMetadata, previousRunnerSignatures, promptExecutionStartedDate, attemptCount, error, options: runOptions, logPath, 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));
@@ -78245,8 +79126,42 @@
             modelName: runnerMetadata.modelName,
             error,
         });
+        // Note: A failed round is exactly the round whose trace is worth reading, so it is written before the live
+        //       runtime log it is built from is deleted
+        await recordPromptRoundTrace({
+            options: runOptions,
+            nextPrompt,
+            runnerMetadata,
+            promptExecutionStartedDate,
+            attemptCount,
+            logPath,
+            outcome: { kind: 'failed', error },
+        });
         await normalizeLineEndingsForCurrentRound(runOptions, roundProjectPath, roundCommitScope);
     }
+    /**
+     * Persists the run trace of one prompt round, so the round can still be analyzed after its temporary
+     * artifacts are gone.
+     *
+     * This is the single place where both the successful and the failed round record what they did, which harness,
+     * model and thinking level did it and everything that harness has written while doing it.
+     */
+    async function recordPromptRoundTrace(options) {
+        const { options: runOptions, nextPrompt, runnerMetadata, promptExecutionStartedDate, attemptCount, logPath, outcome, } = options;
+        await writePromptRunTrace({
+            file: nextPrompt.file,
+            section: nextPrompt.section,
+            runnerName: runnerMetadata.runnerName,
+            modelName: runnerMetadata.modelName,
+            thinkingLevel: runOptions.thinkingLevel,
+            testCommand: runOptions.testCommand,
+            attemptCount,
+            startedDate: promptExecutionStartedDate,
+            finishedDate: moment__default["default"](),
+            outcome,
+            logPath,
+        });
+    }
     /**
      * Waits for the optional user confirmation immediately before creating the commit.
      */
@@ -78895,7 +79810,13 @@
         await commitChanges(buildCoderIsolationMergeFailureCommitMessage(worktree), {
             autoPush: options.options.autoPush,
             projectPath: worktree.projectPath,
-            relevantPaths: [nextPrompt.file.path, errorLogPath].map((path) => toProjectRelativeGitPath(worktree.projectPath, path)),
+            // Note: The round itself has already succeeded, so it has left its run trace in the original project.
+            //       It belongs to this commit, which is the only one this task still gets.
+            relevantPaths: [
+                nextPrompt.file.path,
+                errorLogPath,
+                buildPromptRunTracePath(nextPrompt.file, nextPrompt.section),
+            ].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`);
@@ -79170,12 +80091,23 @@
      * @public exported from `@promptbook/cli`
      */
     async function runCodexPrompts(providedOptions) {
+        var _a;
         const options = normalizeRunOptions(providedOptions !== null && providedOptions !== void 0 ? providedOptions : parseRunOptions(process.argv.slice(2)));
         validateRunCodexPromptOptions(options);
         resetCoderRunControls();
         const runStartDate = moment__default["default"]();
         const { isRichUiEnabled, progressDisplay, uiHandle } = createRunDisplays(options, runStartDate);
-        const waitForRequestedPause = createPauseWaiter({ isRichUiEnabled, progressDisplay, uiHandle });
+        const waitForRequestedPause = createPauseWaiter({
+            isRichUiEnabled,
+            progressDisplay,
+            uiHandle,
+            // Note: Every pause checkpoint of the whole run goes through this one waiter, so watching the free disk
+            //       space here covers each round, each verification and each runner without repeating the check
+            guardFreeDiskSpace: createFreeDiskSpaceGuard({
+                inspectedPath: process.cwd(),
+                isAskingQuestionsEnabled: (_a = options.isAskingQuestionsEnabled) !== null && _a !== void 0 ? _a : true,
+            }),
+        });
         startPauseListenerIfNeeded(isRichUiEnabled);
         try {
             const resolvedCoderContext = await resolveCoderContext(options.context, process.cwd());
@@ -79188,6 +80120,7 @@
             const promptRunnerIdentity = {
                 harnessName: options.agentName,
                 modelName: actualRunnerModel,
+                agentReferences: resolvedCoderAgent === null || resolvedCoderAgent === void 0 ? void 0 : resolvedCoderAgent.agentReferences,
             };
             console.info(colors__default["default"].green(`Running prompts with ${runner.name}`));
             initializeRunUi(uiHandle, runner.name, actualRunnerModel, options);
@@ -79624,11 +80557,14 @@
      * Creates a pause waiter that keeps the progress display and rich UI in sync.
      */
     function createPauseWaiter(options) {
-        const { isRichUiEnabled, progressDisplay, uiHandle } = options;
+        const { isRichUiEnabled, progressDisplay, uiHandle, guardFreeDiskSpace } = options;
         return async (checkpoint) => {
             uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.setPhase(checkpoint.phase);
             uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.setStatusMessage(checkpoint.statusMessage);
             announcePauseTargetLabel(checkpoint.checkpointLabel);
+            // Note: Runs after the checkpoint label is announced, so a pause requested because of a full disk
+            //       replaces that label and says why the run is standing still
+            await guardFreeDiskSpace();
             await checkPause({
                 silent: isRichUiEnabled,
                 onPaused: () => {
@@ -79747,7 +80683,7 @@
             return false;
         }
         if (promptQueueSnapshot.stats.forAgent > 0) {
-            announceRunCompletion('No prompts match the selected harness or model.', colors__default["default"].yellow, isRichUiEnabled, uiHandle);
+            announceRunCompletion('No prompts match the selected harness, model or agent.', colors__default["default"].yellow, isRichUiEnabled, uiHandle);
         }
         else if (promptQueueSnapshot.stats.toBeWritten > 0) {
             announceRunCompletion('No prompts ready for agent.', colors__default["default"].yellow, isRichUiEnabled, uiHandle);
@@ -79792,7 +80728,7 @@
     function announceKeepAliveStatus(promptQueueSnapshot, isRichUiEnabled, uiHandle) {
         let message;
         if (promptQueueSnapshot.stats.forAgent > 0) {
-            message = 'No prompts match the selected harness or model. Watching for changes...';
+            message = 'No prompts match the selected harness, model or agent. Watching for changes...';
         }
         else if (promptQueueSnapshot.stats.toBeWritten > 0) {
             message = 'No prompts ready for agent. Watching for changes...';