@promptbook/cli 0.114.0-33 → 0.114.0-34

package/src/cli/cli-commands/coder/mergeStringRecordJsonFile.ts

@@ -30,6 +30,23 @@ type MergeStringRecordJsonFileOptions = {
     readonly ensureParentDirectoryPath?: string;
 };
 
+/**
+ * Result of one additive string-record merge into a JSON file.
+ *
+ * @private internal utility of `coder init` command
+ */
+export type MergedStringRecordJsonFile = {
+    /**
+     * Status describing whether the JSON file had to be created or updated.
+     */
+    readonly status: InitializationStatus;
+
+    /**
+     * Keys which were missing in the JSON file and therefore added by the merge.
+     */
+    readonly addedEntryKeys: ReadonlyArray<string>;
+};
+
 /**
  * Default indentation used when creating new JSON configuration files.
  */
@@ -43,6 +60,9 @@ const DEFAULT_JSON_FILE_NEWLINE = '\n';
 /**
  * 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`
  */
 export async function mergeStringRecordJsonFile({
@@ -51,7 +71,7 @@ export async function mergeStringRecordJsonFile({
     fieldPath,
     nextEntries,
     ensureParentDirectoryPath,
-}: MergeStringRecordJsonFileOptions): Promise<InitializationStatus> {
+}: MergeStringRecordJsonFileOptions): Promise<MergedStringRecordJsonFile> {
     if (ensureParentDirectoryPath) {
         await mkdir(join(projectPath, ensureParentDirectoryPath), { recursive: true });
     }
@@ -62,23 +82,27 @@ export async function mergeStringRecordJsonFile({
     const jsonObject = fileContent === undefined ? {} : await parseJsonObjectFile(relativeFilePath, fileContent);
     const existingEntries = getStringRecordOrDefault(jsonObject[fieldPath], relativeFilePath, fieldPath);
 
-    let hasChanges = fileContent === undefined;
+    const addedEntryKeys: Array<string> = [];
     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 = { ...jsonObject };
     nextJsonObject[fieldPath] = mergedEntries;
     await writeFile(absoluteFilePath, serializeJsonObject(nextJsonObject, formatting), 'utf-8');
-    return fileContent === undefined ? 'created' : 'updated';
+    return { status: fileContent === undefined ? 'created' : 'updated', addedEntryKeys };
 }
 
 /**

package/src/cli/cli-commands/coder/ping.ts

@@ -6,10 +6,11 @@ import type { $side_effect } from '../../../utils/organization/$side_effect';
 import { handleActionErrors } from '../common/handleActionErrors';
 import { $ensureHarnessInstallations } from '../common/harness/$ensureHarnessInstallations';
 import {
-    addHarnessUpdateOption,
-    normalizeHarnessUpdateCliOptions,
-    type HarnessUpdateCliOptions,
-} from '../common/harnessUpdateCliOptions';
+    addQuestionsOption,
+    normalizeQuestionsCliOptions,
+    QUESTIONS_DESCRIPTION,
+    type QuestionsCliOptions,
+} from '../common/questionsCliOptions';
 import type { PromptRunnerSelectionCliOptions } from '../common/promptRunnerCliOptions';
 import {
     addPromptRunnerRuntimeOptions,
@@ -30,24 +31,28 @@ import { $ensureCoderHarnessGitignoreRules } from './$ensureCoderHarnessGitignor
 export function $initializeCoderPingCommand(program: Program): $side_effect {
     const command = program.command('ping');
     command.description(
-        spaceTrim(`
-            Send one tiny dummy prompt to a harness and model to measure and warm them up
+        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>',
@@ -67,15 +72,13 @@ export function $initializeCoderPingCommand(program: Program): $side_effect {
                 cliOptions as PromptRunnerSelectionCliOptions,
                 { isAgentRequired: true },
             );
-            const { isHarnessUpdateCheckEnabled } = normalizeHarnessUpdateCliOptions(
-                cliOptions as HarnessUpdateCliOptions,
-            );
+            const questionsOptions = normalizeQuestionsCliOptions(cliOptions as QuestionsCliOptions);
 
             // 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,

package/src/cli/cli-commands/coder/printCoderRunFailure.ts

@@ -0,0 +1,14 @@
+import colors from 'colors';
+import { formatUnknownErrorDetails } from '../../../../scripts/run-codex-prompts/common/formatUnknownErrorDetails';
+
+/**
+ * Prints why a coder run has ended to the terminal.
+ *
+ * @private internal utility of `coder run` and `coder server` commands
+ */
+export function printCoderRunFailure(error: Error): void {
+    console.error(colors.bgRed(`${error.name}`));
+    console.error(colors.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`

package/src/cli/cli-commands/coder/printInitializationSummary.ts

@@ -1,8 +1,6 @@
 import colors from 'colors';
-import { AGENT_CODING_FILE_PATH } from './agentCodingFile';
-import { AGENTS_FILE_PATH } from './agentsFile';
 import type { InitializationStatus } from './boilerplateTemplates';
-import { CODER_DEVELOPER_AGENT_FILE_PATH } from './ensureCoderDeveloperAgentFile';
+import type { CoderReferencedArtifactStatus } from './coderReferencedArtifacts';
 import { formatDisplayPath } from './formatDisplayPath';
 import type { CoderInitializationSummary } from './initializeCoderProjectConfiguration';
 
@@ -16,23 +14,25 @@ export function printInitializationSummary(summary: CoderInitializationSummary):
     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.cyan);
+    } else {
+        printInitializationNote('All Promptbook coder npm scripts are already present.', colors.gray);
+    }
+
     if (summary.initializedEnvVariableNames.length > 0) {
         printInitializationNote(`Added env variables: ${summary.initializedEnvVariableNames.join(', ')}`, colors.cyan);
     } else {
@@ -43,7 +43,7 @@ export function printInitializationSummary(summary: CoderInitializationSummary):
 /**
  * Formats one initialization status into a human-readable label.
  */
-function formatInitializationStatus(status: InitializationStatus): string {
+function formatInitializationStatus(status: InitializationStatus | CoderReferencedArtifactStatus): string {
     if (status === 'created') {
         return 'created';
     }
@@ -52,13 +52,20 @@ function formatInitializationStatus(status: InitializationStatus): string {
         return 'updated';
     }
 
+    if (status === 'not-referenced') {
+        return 'not referenced by the added scripts, kept as is';
+    }
+
     return 'unchanged';
 }
 
 /**
  * Prints one checked initialization-status line.
  */
-function printInitializationStatusLine(relativePath: string, status: InitializationStatus): void {
+function printInitializationStatusLine(
+    relativePath: string,
+    status: InitializationStatus | CoderReferencedArtifactStatus,
+): void {
     console.info(colors.gray(`✔ ${relativePath}: ${formatInitializationStatus(status)}`));
 }
 

package/src/cli/cli-commands/coder/run.ts

@@ -1,4 +1,3 @@
-import colors from 'colors';
 import {
     Command as Program /* <- Note: [🔸] Using Program because Command is misleading name */,
     Option,
@@ -7,13 +6,16 @@ import { spaceTrim } from 'spacetrim';
 import { assertsError } from '../../../errors/assertsError';
 import type { $side_effect } from '../../../utils/organization/$side_effect';
 import { createPositiveIntegerOptionParser } from '../common/createPositiveIntegerOptionParser';
+import { $assertSufficientFreeDiskSpace } from '../common/disk-space/$assertSufficientFreeDiskSpace';
 import { handleActionErrors } from '../common/handleActionErrors';
 import { $ensureHarnessInstallations } from '../common/harness/$ensureHarnessInstallations';
 import {
-    addHarnessUpdateOption,
-    normalizeHarnessUpdateCliOptions,
-    type HarnessUpdateCliOptions,
-} from '../common/harnessUpdateCliOptions';
+    addQuestionsOption,
+    assertUserConfirmationIsAllowed,
+    normalizeQuestionsCliOptions,
+    QUESTIONS_DESCRIPTION,
+    type QuestionsCliOptions,
+} from '../common/questionsCliOptions';
 import { $ensurePromptbookCliInstallations } from '../common/promptbook-cli/$ensurePromptbookCliInstallations';
 import type { PromptRunnerCliOptions } from '../common/promptRunnerCliOptions';
 import {
@@ -30,6 +32,8 @@ import {
 } from '../../../../scripts/run-codex-prompts/testing/TestBeforeMode';
 import { DEFAULT_WAIT_AFTER_ERROR_MS, parseOptionalWaitDuration } from './waitOptions';
 import { $ensureCoderHarnessGitignoreRules } from './$ensureCoderHarnessGitignoreRules';
+import { addCoderAgentOption, type CoderAgentCliOptions } from './agentCliOptions';
+import { printCoderRunFailure } from './printCoderRunFailure';
 
 /**
  * Initializes `coder run` command for Promptbook CLI utilities
@@ -41,10 +45,13 @@ import { $ensureCoderHarnessGitignoreRules } from './$ensureCoderHarnessGitignor
 export function $initializeCoderRunCommand(program: Program): $side_effect {
     const command = program.command('run');
     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
@@ -54,9 +61,11 @@ export function $initializeCoderRunCommand(program: Program): $side_effect {
             - 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
@@ -64,16 +73,14 @@ export function $initializeCoderRunCommand(program: Program): $side_effect {
             - Optional post-prompt verification with test-feedback retries
             - Progress tracking and interactive P/S/X terminal controls
             - Dry-run mode to preview prompts
-        `),
+        `,
+        ),
     );
 
     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',
@@ -187,16 +194,14 @@ export function $initializeCoderRunCommand(program: Program): $side_effect {
                 readonly auto: boolean;
                 readonly autoMigrate: boolean;
                 readonly allowDestructiveAutoMigrate: boolean;
-            } & PromptRunnerCliOptions;
+            } & PromptRunnerCliOptions & CoderAgentCliOptions;
 
             const configuredTestCommand = normalizeCommandOptionValue(test);
             const testCommand = configuredTestCommand ?? (testBefore === 'no' ? undefined : DEFAULT_CODER_TEST_COMMAND);
             const runnerOptions = normalizePromptRunnerCliOptions(cliOptions as PromptRunnerCliOptions, {
                 isAgentRequired: !dryRun,
             });
-            const { isHarnessUpdateCheckEnabled } = normalizeHarnessUpdateCliOptions(
-                cliOptions as HarnessUpdateCliOptions,
-            );
+            const questionsOptions = normalizeQuestionsCliOptions(cliOptions as QuestionsCliOptions);
 
             // [1] Parse the wait options and --no-auto:
             //   default: run automatically through the queue (no waiting between prompts)
@@ -206,12 +211,18 @@ export function $initializeCoderRunCommand(program: Program): $side_effect {
             //   --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);
@@ -246,6 +257,7 @@ export function $initializeCoderRunCommand(program: Program): $side_effect {
                 allowDestructiveAutoMigrate,
                 autoPush: runnerOptions.autoPush,
                 autoPull: runnerOptions.autoPull,
+                isAskingQuestionsEnabled: questionsOptions.isAskingQuestionsEnabled,
             };
 
             // Note: Import the function dynamically to avoid loading heavy dependencies until needed
@@ -256,8 +268,7 @@ export function $initializeCoderRunCommand(program: Program): $side_effect {
                 await runCodexPrompts(runOptions);
             } catch (error) {
                 assertsError(error);
-                console.error(colors.bgRed(`${error.name}`));
-                console.error(colors.red(error.stack || error.message));
+                printCoderRunFailure(error);
                 return process.exit(1);
             }
 

package/src/cli/cli-commands/coder/server.ts

@@ -1,4 +1,3 @@
-import colors from 'colors';
 import {
     Command as Program /* <- Note: [🔸] Using Program because Command is misleading name */,
     Option,
@@ -9,13 +8,16 @@ import { assertsError } from '../../../errors/assertsError';
 import { NotAllowed } from '../../../errors/NotAllowed';
 import type { number_port } from '../../../types/number_positive';
 import type { $side_effect } from '../../../utils/organization/$side_effect';
+import { $assertSufficientFreeDiskSpace } from '../common/disk-space/$assertSufficientFreeDiskSpace';
 import { handleActionErrors } from '../common/handleActionErrors';
 import { $ensureHarnessInstallations } from '../common/harness/$ensureHarnessInstallations';
 import {
-    addHarnessUpdateOption,
-    normalizeHarnessUpdateCliOptions,
-    type HarnessUpdateCliOptions,
-} from '../common/harnessUpdateCliOptions';
+    addQuestionsOption,
+    assertUserConfirmationIsAllowed,
+    normalizeQuestionsCliOptions,
+    QUESTIONS_DESCRIPTION,
+    type QuestionsCliOptions,
+} from '../common/questionsCliOptions';
 import type { PromptRunnerCliOptions } from '../common/promptRunnerCliOptions';
 import {
     addPromptRunnerExecutionOptions,
@@ -26,6 +28,8 @@ import {
 import { addPromptPriorityOptions } from '../common/promptPriorityCliOptions';
 import { DEFAULT_WAIT_AFTER_ERROR_MS, parseOptionalWaitDuration } from './waitOptions';
 import { $ensureCoderHarnessGitignoreRules } from './$ensureCoderHarnessGitignoreRules';
+import { addCoderAgentOption, type CoderAgentCliOptions } from './agentCliOptions';
+import { printCoderRunFailure } from './printCoderRunFailure';
 
 /**
  * Default port used by `ptbk coder server`.
@@ -47,21 +51,26 @@ const DEFAULT_CODER_SERVER_PORT = '4441';
 export function $initializeCoderServerCommand(program: Program): $side_effect {
     const command = program.command('server');
     command.description(
-        spaceTrim(`
-            Start a coder server that watches for prompts and serves a kanban web UI
+        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(
@@ -71,11 +80,8 @@ export function $initializeCoderServerCommand(program: Program): $side_effect {
     );
     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',
@@ -160,22 +166,27 @@ export function $initializeCoderServerCommand(program: Program): $side_effect {
                 readonly auto: boolean;
                 readonly autoMigrate: boolean;
                 readonly allowDestructiveAutoMigrate: boolean;
-            } & PromptRunnerCliOptions;
+            } & PromptRunnerCliOptions & CoderAgentCliOptions;
 
             const port = parseCoderServerPort(rawPort);
             const testCommand = normalizeCommandOptionValue(test);
             const runnerOptions = normalizePromptRunnerCliOptions(cliOptions as PromptRunnerCliOptions, {
                 isAgentRequired: !dryRun,
             });
-            const { isHarnessUpdateCheckEnabled } = normalizeHarnessUpdateCliOptions(
-                cliOptions as HarnessUpdateCliOptions,
-            );
-
-            await $ensureHarnessInstallations([runnerOptions.agentName], isHarnessUpdateCheckEnabled);
-            await $ensureCoderHarnessGitignoreRules(process.cwd(), runnerOptions.agentName);
+            const questionsOptions = normalizeQuestionsCliOptions(cliOptions as QuestionsCliOptions);
 
             // [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);
@@ -206,6 +217,7 @@ export function $initializeCoderServerCommand(program: Program): $side_effect {
                 allowDestructiveAutoMigrate,
                 autoPush: runnerOptions.autoPush,
                 autoPull: runnerOptions.autoPull,
+                isAskingQuestionsEnabled: questionsOptions.isAskingQuestionsEnabled,
             };
 
             // Note: Import dynamically to avoid loading heavy dependencies until needed
@@ -217,8 +229,7 @@ export function $initializeCoderServerCommand(program: Program): $side_effect {
                 await runCodexPromptsServer(runOptions);
             } catch (error) {
                 assertsError(error);
-                console.error(colors.bgRed(`${error.name}`));
-                console.error(colors.red(error.stack || error.message));
+                printCoderRunFailure(error);
                 return process.exit(1);
             }
 

package/src/cli/cli-commands/coder.ts

@@ -1,9 +1,9 @@
-import colors from 'colors';
 import type {
     Command as Program /* <- Note: [🔸] Using Program because Command is misleading name */,
 } from 'commander';
 import { spaceTrim } from 'spacetrim';
 import type { $side_effect } from '../../utils/organization/$side_effect';
+import { $requireCliSubcommand } from '../common/$requireCliSubcommand';
 import { $initializeCoderAddCommand } from './coder/add';
 import { $initializeCoderFindFreshEmojiTagCommand } from './coder/find-fresh-emoji-tags';
 import { $initializeCoderFindRefactorCandidatesCommand } from './coder/find-refactor-candidates';
@@ -69,11 +69,7 @@ export function $initializeCoderCommand(program: Program): $side_effect {
     $initializeCoderFindFreshEmojiTagCommand(coderCommand);
 
     // If no subcommand is provided, show help
-    coderCommand.action(() => {
-        console.info(colors.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`

package/src/cli/cli-commands/common/$askForConfirmation.ts

@@ -1,15 +1,25 @@
 import colors from 'colors';
 import { createInterface } from 'readline';
+import type { NormalizedQuestionsCliOptions } from './questionsCliOptions';
 
 /**
  * Asks the user in the terminal to confirm one optional change.
  *
  * 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`
  */
-export async function $askForConfirmation(question: string): Promise<boolean> {
+export async function $askForConfirmation(
+    question: string,
+    { isAskingQuestionsEnabled }: NormalizedQuestionsCliOptions,
+): Promise<boolean> {
+    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;

package/src/cli/cli-commands/common/disk-space/$assertSufficientFreeDiskSpace.ts

@@ -0,0 +1,35 @@
+import { spaceTrim } from 'spacetrim';
+import { LimitReachedError } from '../../../../errors/LimitReachedError';
+import { $readFreeDiskSpaceStatus } from './$readFreeDiskSpaceStatus';
+import { formatLowFreeDiskSpaceWarning } from './formatLowFreeDiskSpaceWarning';
+
+/**
+ * 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`
+ */
+export async function $assertSufficientFreeDiskSpace(inspectedPath: string): Promise<void> {
+    const freeDiskSpaceStatus = await $readFreeDiskSpaceStatus(inspectedPath);
+
+    if (freeDiskSpaceStatus === null || freeDiskSpaceStatus.level === 'sufficient') {
+        return;
+    }
+
+    throw new LimitReachedError(
+        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`