@promptbook/cli 0.114.0-0 → 0.114.0-2

package/esm/index.es.js

@@ -1,7 +1,7 @@
 import colors from 'colors';
 import commander, { Option } from 'commander';
 import _spaceTrim, { spaceTrim as spaceTrim$1 } from 'spacetrim';
-import { writeFile, stat, mkdir, readFile, readdir, rm, cp, lstat, symlink, rename, unlink, appendFile, realpath, copyFile, access, constants, watch, rmdir } from 'fs/promises';
+import { writeFile, stat, mkdir, readFile, readdir, rm, cp, lstat, symlink, rename, unlink, appendFile, realpath, copyFile, access, constants, watch, rmdir, mkdtemp } from 'fs/promises';
 import { join, delimiter, relative, basename, resolve, dirname, isAbsolute, extname } from 'path';
 import { createHash, randomBytes } from 'crypto';
 import { spawn } from 'child_process';
@@ -9,10 +9,10 @@ import moment from 'moment';
 import * as fs from 'fs';
 import { createWriteStream, mkdirSync, writeFileSync, statSync, readFileSync, existsSync, promises } from 'fs';
 import * as dotenv from 'dotenv';
-import prompts from 'prompts';
 import * as readline from 'readline';
 import { emitKeypressEvents, clearLine, cursorTo, createInterface } from 'readline';
 import { forTime, forEver } from 'waitasecond';
+import prompts from 'prompts';
 import hexEncoder from 'crypto-js/enc-hex';
 import sha256 from 'crypto-js/sha256';
 import { io } from 'socket.io-client';
@@ -37,8 +37,8 @@ import { fileSearchTool, tool, Agent as Agent$1, webSearchTool, run, setDefaultO
 import OpenAI from 'openai';
 import * as ts from 'typescript';
 import ignore from 'ignore';
-import { EventEmitter } from 'events';
 import { tmpdir } from 'os';
+import { EventEmitter } from 'events';
 import { lookup, extension } from 'mime-types';
 import papaparse from 'papaparse';
 import { Client } from 'pg';
@@ -59,7 +59,7 @@ const BOOK_LANGUAGE_VERSION = '2.0.0';
  * @generated
  * @see https://github.com/webgptorg/promptbook
  */
-const PROMPTBOOK_ENGINE_VERSION = '0.114.0-0';
+const PROMPTBOOK_ENGINE_VERSION = '0.114.0-2';
 /**
  * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
  * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -26966,12 +26966,12 @@ function buildControlPills(options) {
  * Builds the coder-run control pills shown in the footer box.
  */
 function buildCoderRunControlPills(options) {
-    const { pauseControl, pendingEnterLabel, isEndAfterCurrentPromptRequested, sessionTotal } = options;
+    const { phase, pauseControl, pendingEnterLabel, isEndAfterCurrentPromptRequested, sessionTotal } = options;
     return buildControlPills({
         pauseControl,
         pendingEnterLabel,
         additionalControls: [
-            buildSkipCurrentWaitControl(),
+            ...(phase === 'waiting' ? [buildSkipCurrentWaitControl()] : []),
             buildEndAfterCurrentPromptControl(isEndAfterCurrentPromptRequested, sessionTotal),
         ],
     });
@@ -29552,6 +29552,7 @@ function buildCodexScript(options) {
         `    -c model_reasoning_effort="${thinkingLevel}" \\`,
         `    --ask-for-approval ${options.askForApproval} \\`,
         `    exec --model ${options.model} \\`,
+        ...(options.isMachineReadableProgressEnabled ? ['    --json \\'] : []),
         '    --local-provider none \\',
         `    --sandbox ${options.sandbox} \\`,
         `    -C ${projectPath} \\`,
@@ -29868,6 +29869,10 @@ function matchesAnyPattern(text, patterns) {
  * Output line that marks finished Codex usage summary.
  */
 const CODEX_COMPLETION_LINE = /^\s*tokens used\b/i;
+/**
+ * Output line that marks the completed Codex turn in JSONL output mode.
+ */
+const CODEX_JSON_COMPLETION_LINE = /^\s*\{"type":"turn\.(?:completed|failed)"/u;
 /**
  * Idle timeout after completion marker to capture trailing output.
  */
@@ -29944,6 +29949,7 @@ class OpenAiCodexRunner {
             sandbox: this.options.sandbox,
             askForApproval: this.options.askForApproval,
             allowCredits: this.options.allowCredits,
+            isMachineReadableProgressEnabled: this.options.isMachineReadableProgressEnabled,
             codexCommand: this.options.codexCommand,
         });
         for (let retryIndex = 0;; retryIndex++) {
@@ -29958,7 +29964,9 @@ class OpenAiCodexRunner {
                 const output = await $runGoScriptUntilMarkerIdle({
                     scriptPath: options.scriptPath,
                     scriptContent,
-                    completionLineMatcher: CODEX_COMPLETION_LINE,
+                    completionLineMatcher: this.options.isMachineReadableProgressEnabled
+                        ? CODEX_JSON_COMPLETION_LINE
+                        : CODEX_COMPLETION_LINE,
                     idleTimeoutMs: CODEX_COMPLETION_IDLE_MS,
                     logPath: options.logPath,
                     shouldPrintLiveOutput: options.shouldPrintLiveOutput,
@@ -30208,6 +30216,7 @@ function createOpenAiCodexRunnerResolution(options) {
         sandbox: 'danger-full-access',
         askForApproval: 'never',
         allowCredits: options.allowCredits,
+        isMachineReadableProgressEnabled: options.isMachineReadableProgressEnabled,
     });
     if (!options.allowCredits && options.isVerbose === true) {
         console.info(colors.gray('OpenAI Codex credit spending is disabled. Use `--allow-credits` to explicitly opt in.'));
@@ -31443,6 +31452,7 @@ function buildCoderRunUiFrame(options) {
         : [options.statusMessage, ...options.detailLines.map((detailLine) => `• ${detailLine}`)];
     const visibleOutputLines = buildVisibleOutputLines(options.agentOutputLines);
     const controls = buildCoderRunControlPills({
+        phase: options.phase,
         pauseControl: pausePresentation.pauseControl,
         pendingEnterLabel: options.pendingEnterLabel,
         isEndAfterCurrentPromptRequested: options.isEndAfterCurrentPromptRequested,
@@ -32306,6 +32316,7 @@ function createCoderRunOptionsForAgent(options) {
         autoPull: options.autoPull,
         agentName: options.agentName,
         model: options.model,
+        isMachineReadableProgressEnabled: options.isMachineReadableProgressEnabled,
         priority: 0,
     };
 }
@@ -33295,6 +33306,21 @@ function appendCoderContext(prompt, context) {
         `);
 }
 
+/**
+ * Maximum amount of test output embedded into an agent prompt.
+ */
+const MAX_TEST_OUTPUT_CHARS = 12000;
+/**
+ * Limits test output while keeping the end of the output, where test runners usually print the failure summary.
+ */
+function limitTestOutput(testOutput) {
+    const normalizedTestOutput = testOutput.trim();
+    if (normalizedTestOutput.length <= MAX_TEST_OUTPUT_CHARS) {
+        return normalizedTestOutput;
+    }
+    return `[..., test output truncated to the last ${MAX_TEST_OUTPUT_CHARS} characters...]\n${normalizedTestOutput.slice(-MAX_TEST_OUTPUT_CHARS)}`;
+}
+
 /**
  * Runs the configured verification command inside the project root and returns its output.
  */
@@ -33315,10 +33341,6 @@ async function runPromptTestCommand(options) {
  * Maximum number of coding attempts allowed for the same prompt when verification keeps failing.
  */
 const MAX_PROMPT_TEST_ATTEMPTS = 3;
-/**
- * Maximum amount of verification output sent back to the coding agent as retry feedback.
- */
-const MAX_TEST_FEEDBACK_OUTPUT_CHARS = 12000;
 /**
  * File extension used by generated shell scripts.
  */
@@ -33364,7 +33386,7 @@ async function runPromptWithTestFeedback(options) {
             return { ...result, attemptCount, steps };
         }
         const fullVerificationOutput = formatUnknownErrorDetails(failedVerification.error);
-        const feedbackVerificationOutput = limitVerificationOutputForFeedback(fullVerificationOutput);
+        const feedbackVerificationOutput = limitTestOutput(fullVerificationOutput);
         if (attemptCount >= MAX_PROMPT_TEST_ATTEMPTS) {
             console.error(colors.red(`Verification failed for ${options.promptLabel} after ${attemptCount} attempts.`));
             throw new Error(buildFinalVerificationFailureMessage({
@@ -33494,19 +33516,6 @@ function buildFinalVerificationFailureMessage({ promptLabel, testCommand, attemp
             \`\`\`
         `);
 }
-/**
- * Limits verification output before it is embedded back into the next coding prompt.
- */
-function limitVerificationOutputForFeedback(verificationOutput) {
-    const normalizedVerificationOutput = verificationOutput.trim();
-    if (normalizedVerificationOutput.length <= MAX_TEST_FEEDBACK_OUTPUT_CHARS) {
-        return normalizedVerificationOutput;
-    }
-    return spaceTrim(`
-        [...verification output truncated to the last ${MAX_TEST_FEEDBACK_OUTPUT_CHARS} characters...]
-        ${normalizedVerificationOutput.slice(-MAX_TEST_FEEDBACK_OUTPUT_CHARS)}
-    `);
-}
 /**
  * Derives a dedicated temp-script path for verification commands.
  */
@@ -41367,6 +41376,7 @@ function createLocalAgentRunOptions(options, localAgentRunnerLimits) {
         autoClone: false,
         maxMessageProcessingFailures: localAgentRunnerLimits.maxFailedAttempts,
         maxParallelMessages: localAgentRunnerLimits.maxParallelMessages,
+        isMachineReadableProgressEnabled: true,
     };
 }
 
@@ -43481,6 +43491,27 @@ function resolveCheckedHarnessDefinitions(harnessNames) {
 }
 // Note: [🟡] Code for CLI harness installation orchestration [$ensureHarnessInstallations](src/cli/cli-commands/common/harness/$ensureHarnessInstallations.ts) should never be published outside of `@promptbook/cli`
 
+/**
+ * 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$1(`
+        # ✨ 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.
  *
@@ -43508,106 +43539,6 @@ function getDefaultCoderAgentsFileContent() {
 // Note: [🟡] Code for coder AGENTS file boilerplate [agentsFile](src/cli/cli-commands/coder/agentsFile.ts) should never be published outside of `@promptbook/cli`
 // Note: [💞] Ignore a discrepancy between file name and exported helper names
 
-/**
- * Normalizes one project-relative path for human-readable CLI output and markdown.
- *
- * @private internal utility of `ptbk coder`
- */
-function formatDisplayPath(relativePath) {
-    return relativePath.replace(/\\/gu, '/');
-}
-// Note: [🟡] Code for coder path formatting [formatDisplayPath](src/cli/cli-commands/coder/formatDisplayPath.ts) should never be published outside of `@promptbook/cli`
-
-/**
- * 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({ packageJsonScripts, }) {
-    return spaceTrim$1((block) => `
-            # Promptbook Coder quick reference
-
-            This project is prepared for the \`ptbk coder\` workflow. Promptbook Coder does not create a new model on its own; it orchestrates coding agents such as GitHub Copilot, OpenAI Codex, Claude Code, Opencode, Cline, and Gemini CLI through prompt files in \`${formatDisplayPath(PROMPTS_DIRECTORY_PATH)}/\`.
-
-            ## Workflow
-            1. Put repository-wide coding rules into \`${AGENTS_FILE_PATH}\`. The default \`npm run coder:run\` script already passes \`--context ${AGENTS_FILE_PATH}\`.
-            2. Create or customize prompt templates in \`${formatDisplayPath(PROMPTS_TEMPLATES_DIRECTORY_PATH)}/\`. ${buildStarterTemplateSentence()}
-            3. Generate prompt files with \`npm run coder:generate-boilerplates\` or \`ptbk coder generate-boilerplates --template <template> --count <count>\`. To append a single ready-to-run prompt straight from a description, use \`npm run coder:add\` or \`ptbk coder add "some new feature"\`.
-            4. Replace every \`@@@\`, keep drafts as \`[-]\`, and switch prompts to \`[ ]\` when they are ready to run. Completed prompts are marked \`[x]\`.
-            5. Run \`npm run coder:run\` to execute the next ready prompt with the configured coding agent.
-            6. Use \`npm run coder:verify\` to archive finished prompts into \`${formatDisplayPath(PROMPTS_DONE_DIRECTORY_PATH)}/\` and append repair follow-up prompts when more work is needed.
-            7. Use \`ptbk coder find-refactor-candidates\` when you want Promptbook to suggest refactor prompts automatically.
-
-            ## Templates
-            -   Project-owned templates created by \`ptbk coder init\`: ${formatInlineCodeList(getDefaultCoderProjectPromptTemplateDefinitions().map(({ relativeFilePath }) => formatDisplayPath(relativeFilePath)))}
-            -   Built-in \`--template\` aliases: ${formatInlineCodeList(getDefaultCoderPromptTemplateDefinitions().map(({ id }) => id))}
-            -   To add a custom template, create a markdown file such as \`${formatDisplayPath(PROMPTS_TEMPLATES_DIRECTORY_PATH)}/backend.md\`.
-            -   To use a project template, run \`ptbk coder generate-boilerplates --template ${formatDisplayPath(PROMPTS_TEMPLATES_DIRECTORY_PATH)}/backend.md\`.
-            -   Keep shared repository rules in \`${AGENTS_FILE_PATH}\` and recurring task-family rules in template files so individual prompt files stay focused on the actual task.
-
-            ## Created npm scripts
-            | Script | Purpose |
-            | --- | --- |
-            ${block(buildPackageJsonScriptTableLines(packageJsonScripts).join('\n'))}
-
-            ## Customizing the workflow
-            -   Edit \`package.json\` if you want \`npm run coder:run\` to use another coding agent, model, thinking level, context file, or wait mode.
-            -   Use direct CLI commands when you need one-off flags such as \`--min-priority\`, \`--max-priority\`, \`--ignore-git-changes\`, \`--no-commit\`, \`--dry-run\`, \`--test\`, \`--allow-credits\`, or \`--auto-migrate\`.
-            -   Use \`ptbk coder --help\` and \`ptbk coder <command> --help\` for the full CLI reference.
-        `);
-}
-/**
- * Builds the sentence describing the starter templates created during initialization.
- */
-function buildStarterTemplateSentence() {
-    const starterTemplatePaths = getDefaultCoderProjectPromptTemplateDefinitions().map(({ relativeFilePath }) => formatDisplayPath(relativeFilePath));
-    if (starterTemplatePaths.length === 1) {
-        return `The starter project template created by \`ptbk coder init\` is \`${starterTemplatePaths[0]}\`.`;
-    }
-    return `The starter project templates created by \`ptbk coder init\` are ${formatInlineCodeList(starterTemplatePaths)}.`;
-}
-/**
- * Builds the markdown table rows describing the initialized npm scripts.
- */
-function buildPackageJsonScriptTableLines(packageJsonScripts) {
-    return Object.entries(packageJsonScripts).map(([scriptName, scriptCommand]) => `| \`npm run ${scriptName}\` | ${describeDefaultCoderPackageJsonScript(scriptName, scriptCommand)} |`);
-}
-/**
- * Describes one initialized npm script in human-readable terms.
- */
-function describeDefaultCoderPackageJsonScript(scriptName, scriptCommand) {
-    if (scriptName === 'coder:generate-boilerplates') {
-        return `Runs \`${scriptCommand}\` to create new prompt files in \`${formatDisplayPath(PROMPTS_DIRECTORY_PATH)}/\`.`;
-    }
-    if (scriptName === 'coder:add') {
-        return `Runs \`${scriptCommand}\` to add one ready-to-run prompt file to \`${formatDisplayPath(PROMPTS_DIRECTORY_PATH)}/\` from a plain-language description.`;
-    }
-    if (scriptName === 'coder:run') {
-        return `Runs \`${scriptCommand}\` to execute the next ready prompt with shared repository context from \`${AGENTS_FILE_PATH}\`.`;
-    }
-    if (scriptName === 'coder:find-refactor-candidates') {
-        return `Runs \`${scriptCommand}\` to generate prompt candidates for large or crowded files.`;
-    }
-    if (scriptName === 'coder:verify') {
-        return `Runs \`${scriptCommand}\` to archive verified prompts into \`${formatDisplayPath(PROMPTS_DONE_DIRECTORY_PATH)}/\` and append repair prompts when needed.`;
-    }
-    return `Runs \`${scriptCommand}\`.`;
-}
-/**
- * Formats one inline code list for human-readable markdown.
- */
-function formatInlineCodeList(values) {
-    return values.map((value) => `\`${value}\``).join(', ');
-}
-// 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 directory path for agents initialized by `ptbk coder init`.
  *
@@ -43672,6 +43603,16 @@ async function isExistingFile$2(path) {
 }
 // Note: [🟡] Code for coder init developer agent bootstrapping [ensureCoderDeveloperAgentFile](src/cli/cli-commands/coder/ensureCoderDeveloperAgentFile.ts) should never be published outside of `@promptbook/cli`
 
+/**
+ * Normalizes one project-relative path for human-readable CLI output and markdown.
+ *
+ * @private internal utility of `ptbk coder`
+ */
+function formatDisplayPath(relativePath) {
+    return relativePath.replace(/\\/gu, '/');
+}
+// Note: [🟡] Code for coder path formatting [formatDisplayPath](src/cli/cli-commands/coder/formatDisplayPath.ts) should never be published outside of `@promptbook/cli`
+
 /**
  * Fallback `.env` content used when no required variables need to be appended.
  */
@@ -43749,7 +43690,7 @@ async function ensureCoderGitignoreFile(projectPath) {
 const DEFAULT_CODER_PACKAGE_JSON_SCRIPTS = {
     'coder:generate-boilerplates': 'ptbk coder generate-boilerplates --template ./prompts/templates/common.md',
     'coder:add': 'ptbk coder add --template ./prompts/templates/common.md',
-    'coder:run': 'ptbk coder run --harness openai-codex --model gpt-5.5 --thinking-level xhigh --agent agents/developer.book --context AGENTS.md',
+    'coder:run': 'ptbk coder run --harness openai-codex --model gpt-5.6-terra --thinking-level max --agent agents/developer.book --context AGENTS.md --test-before yes-and-fix',
     // 'coder:find-refactor-candidates': 'npx ptbk coder find-refactor-candidates',
     'coder:verify': 'ptbk coder verify',
 };
@@ -43998,9 +43939,7 @@ async function initializeCoderProjectConfiguration(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({
-        packageJsonScripts: getDefaultCoderPackageJsonScripts(),
-    }));
+    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);
@@ -44141,6 +44080,66 @@ function listDefaultCoderProjectPromptTemplateDisplayPaths() {
 // Note: [🟡] Code for CLI command [init](src/cli/cli-commands/coder/init.ts) should never be published outside of `@promptbook/cli`
 // Note: [💞] Ignore a discrepancy between file name and entity name
 
+/**
+ * Initializes `coder ping` command for Promptbook CLI utilities.
+ *
+ * The command makes one small, isolated harness/model call, prints its result
+ * and reports how long the harness/model turn took.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it registers a command in the CLI.
+ *
+ * @private internal function of `promptbookCli`
+ */
+function $initializeCoderPingCommand(program) {
+    const command = program.command('ping');
+    command.description(spaceTrim$1(`
+            Test one harness and model connection with a small disposable task
+
+            ${PROMPT_RUNNER_DESCRIPTION}
+
+            Features:
+            - Runs the dummy task in a temporary directory outside the current project
+            - Prints the result returned by the selected harness and model
+            - Reports the elapsed harness/model response time in milliseconds
+            - Can be used to start consuming an applicable harness/model quota before a longer run
+        `));
+    addPromptRunnerSelectionOptions(command);
+    addPromptRunnerRuntimeOptions(command);
+    command.action(handleActionErrors(async (cliOptions) => {
+        const normalizedOptions = normalizePromptRunnerSelectionCliOptions(cliOptions, { isAgentRequired: true });
+        const agentName = normalizedOptions.agentName;
+        if (!agentName) {
+            throw new NotAllowed(spaceTrim$1(`
+                        A harness is required for \`ptbk coder ping\`.
+
+                        Pass one with \`--harness <harness-name>\`.
+                    `));
+        }
+        await $ensureHarnessInstallations([agentName]);
+        // Note: Import the runner-backed implementation dynamically to avoid loading heavy dependencies until needed.
+        const { runCoderPing } = await Promise.resolve().then(function () { return runCoderPing$1; });
+        const pingResult = await runCoderPing({
+            agentName,
+            model: normalizedOptions.model,
+            thinkingLevel: normalizedOptions.thinkingLevel,
+            isUiDisabled: normalizedOptions.noUi,
+            isCreditsAllowed: normalizedOptions.allowCredits,
+        });
+        printCoderPingResult(pingResult);
+    }));
+}
+/**
+ * Prints the result and duration of one completed coder ping.
+ */
+function printCoderPingResult(pingResult) {
+    console.info(spaceTrim$1(`
+            Result: ${pingResult.result}
+            Time: ${pingResult.elapsedTimeMs.toFixed(0)} ms
+        `));
+}
+// 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
+
 /**
  * Creates a Commander argument parser that accepts only non-negative integers.
  *
@@ -44165,6 +44164,21 @@ function createNonNegativeIntegerOptionParser(optionName) {
 }
 // Note: [🟡] Code for CLI option parser [createNonNegativeIntegerOptionParser](src/cli/cli-commands/common/createNonNegativeIntegerOptionParser.ts) should never be published outside of `@promptbook/cli`
 
+/**
+ * Modes supported by `ptbk coder run --test-before`.
+ */
+const TEST_BEFORE_MODE_VALUES = ['no', 'yes-and-fail', 'yes-and-fix'];
+/**
+ * Default verification command used when a pre-coding mode is enabled without an explicit `--test` command.
+ */
+const DEFAULT_CODER_TEST_COMMAND = 'npm test';
+/**
+ * Checks whether a value is a supported `--test-before` mode.
+ */
+function isTestBeforeMode(value) {
+    return TEST_BEFORE_MODE_VALUES.includes(value);
+}
+
 /**
  * Default wait duration applied before retrying a prompt round after an error (10 minutes).
  *
@@ -44209,6 +44223,7 @@ function $initializeCoderRunCommand(program) {
             - Optional --no-ui keeps plain streaming console output for logging and debugging
             - Checks that the selected harness is installed globally and up to date before the first prompt
             - Supports GPG signing of commits
+            - Optional pre-coding test run that can stop or repair pre-existing failures
             - Optional post-prompt verification with test-feedback retries
             - Progress tracking and interactive P/S/X terminal controls
             - Dry-run mode to preview prompts
@@ -44218,6 +44233,9 @@ function $initializeCoderRunCommand(program) {
     command.option('--agent <agent-book-path>', 'Path to a .book file whose compiled system message is prepended to each coding prompt');
     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 Option('--test-before <mode>', `Run tests before coding: ${TEST_BEFORE_MODE_VALUES.join(', ')} (defaults to no; uses npm test when --test is omitted)`)
+        .choices([...TEST_BEFORE_MODE_VALUES])
+        .default('no'));
     command.option('--preserve-logs', 'Keep generated temp prompt/log artifacts after successful rounds for debugging and analytics', false);
     addPromptRunnerExecutionOptions(command);
     command.option('--isolate', spaceTrim$1(`
@@ -44247,8 +44265,9 @@ function $initializeCoderRunCommand(program) {
     command.option('--auto-migrate', 'Run testing-server database migrations automatically after each successfully processed prompt');
     command.option('--allow-destructive-auto-migrate', 'Allow auto-migrate even when heuristic SQL safety check flags destructive pending migrations');
     command.action(handleActionErrors(async (cliOptions) => {
-        const { dryRun, agent, context, test, preserveLogs, isolate: isIsolated, priority, minPriority: minimumPriority, maxPriority: maximumPriority, limit, waitAfterPrompt: waitAfterPromptValue, waitBetweenPrompts: waitBetweenPromptsValue, waitAfterError: waitAfterErrorValue, auto, autoMigrate, allowDestructiveAutoMigrate, } = cliOptions;
-        const testCommand = normalizeCommandOptionValue$1(test);
+        const { dryRun, agent, context, test, testBefore, preserveLogs, isolate: isIsolated, priority, minPriority: minimumPriority, maxPriority: maximumPriority, limit, waitAfterPrompt: waitAfterPromptValue, waitBetweenPrompts: waitBetweenPromptsValue, waitAfterError: waitAfterErrorValue, auto, autoMigrate, allowDestructiveAutoMigrate, } = cliOptions;
+        const configuredTestCommand = normalizeCommandOptionValue$1(test);
+        const testCommand = configuredTestCommand !== null && configuredTestCommand !== void 0 ? configuredTestCommand : (testBefore === 'no' ? undefined : DEFAULT_CODER_TEST_COMMAND);
         const runnerOptions = normalizePromptRunnerCliOptions(cliOptions, {
             isAgentRequired: !dryRun,
         });
@@ -44277,6 +44296,7 @@ function $initializeCoderRunCommand(program) {
             agent,
             context,
             testCommand,
+            testBefore,
             preserveLogs,
             isIsolated,
             noUi: runnerOptions.noUi,
@@ -44533,6 +44553,7 @@ function collectStringOption(value, previousValues) {
  * - add: Add one ready-to-run prompt file to the queue
  * - generate-boilerplates: Generate prompt boilerplate files
  * - find-refactor-candidates: Find files that need refactoring
+ * - ping: Test one harness and model connection with a disposable task
  * - run: Run coding prompts with AI agents
  * - verify: Verify completed prompts
  * - find-fresh-emoji-tags: Find unused emoji tags
@@ -44552,6 +44573,7 @@ function $initializeCoderCommand(program) {
             - generate-boilerplates: Generate prompt boilerplate files
             - find-refactor-candidates: Find files that need refactoring
             - find-unwritten: List prompt sections that still need to be authored
+            - ping: Test one harness and model connection with a disposable task
             - run: Run coding prompts with AI agents
             - server: Start a long-running coder server with a kanban web UI
             - verify: Verify completed prompts
@@ -44563,6 +44585,7 @@ function $initializeCoderCommand(program) {
     $initializeCoderGenerateBoilerplatesCommand(coderCommand);
     $initializeCoderFindRefactorCandidatesCommand(coderCommand);
     $initializeCoderFindUnwrittenCommand(coderCommand);
+    $initializeCoderPingCommand(coderCommand);
     $initializeCoderRunCommand(coderCommand);
     $initializeCoderServerCommand(coderCommand);
     $initializeCoderVerifyCommand(coderCommand);
@@ -73589,6 +73612,41 @@ function listPromptsToBeWritten(files, priorityFilter = {}) {
         isPromptInPriorityFilter(prompt.section, priorityFilter));
 }
 
+/**
+ * Checks whether a prompt is unrestricted or matches the selected harness/model.
+ *
+ * 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.
+ */
+function isPromptCompatibleWithRunner(file, section, promptRunnerIdentity) {
+    if (promptRunnerIdentity === undefined) {
+        return true;
+    }
+    const statusLine = section.statusLineIndex === undefined ? undefined : file.lines[section.statusLineIndex];
+    const requiredRunnerTokens = statusLine === undefined ? [] : extractPromptRunnerTokens(statusLine);
+    if (requiredRunnerTokens.length === 0) {
+        return true;
+    }
+    const normalizedRunnerNames = [promptRunnerIdentity.harnessName, promptRunnerIdentity.modelName]
+        .filter((name) => name !== undefined && name.trim() !== '')
+        .map((name) => normalizeToKebabCase(name))
+        .filter((name) => name !== '');
+    return requiredRunnerTokens.some((requiredRunnerToken) => {
+        const normalizedRequiredRunnerToken = normalizeToKebabCase(requiredRunnerToken);
+        return (normalizedRequiredRunnerToken !== '' &&
+            normalizedRunnerNames.some((normalizedRunnerName) => normalizedRunnerName.includes(normalizedRequiredRunnerToken)));
+    });
+}
+/**
+ * Extracts model and harness tokens from a prompt status line.
+ */
+function extractPromptRunnerTokens(statusLine) {
+    return Array.from(statusLine.matchAll(/`([^`]+)`/gu))
+        .map((match) => { var _a, _b; return (_b = (_a = match[1]) === null || _a === void 0 ? void 0 : _a.trim()) !== null && _b !== void 0 ? _b : ''; })
+        .filter((token) => token !== '');
+}
+
 /**
  * Parses a prompt markdown file into sections and metadata.
  */
@@ -73636,11 +73694,11 @@ function parsePromptFile(filePath, content) {
     };
 }
 /**
- * Parses a status line like "[ ] !!" or "[-]" or "[x] ~$0.65 21 minutes..." into status and priority.
+ * Parses a status line like "[ ] !!", "[ ] use `gpt` !!!!!" or "[-]" into status and priority.
  * For [x] done and [!] failed prompts, allow metadata after the status marker.
  */
 function parseStatusLine(line) {
-    var _a, _b, _c, _d, _e;
+    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) {
@@ -73651,21 +73709,23 @@ function parseStatusLine(line) {
     if (failedMatch) {
         return { status: 'failed', priority: 0 };
     }
-    // For todo [ ] and not-ready [-], require clean end with optional priority markers
-    const match = line.match(/^\[(?<status>[ -])\]\s*(?<priority>!*)\s*$/);
-    if (!match) {
-        return undefined;
+    // For not-ready [-], keep the historical clean-line syntax.
+    if (/^\[-\]\s*!*\s*$/u.test(line)) {
+        return { status: 'not-ready', priority: 0 };
     }
-    const statusChar = (_b = (_a = match.groups) === null || _a === void 0 ? void 0 : _a.status) === null || _b === void 0 ? void 0 : _b.toLowerCase();
-    let status;
-    if (statusChar === '-') {
-        status = 'not-ready';
+    // 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) {
+        return undefined;
     }
-    else {
-        status = 'todo';
+    const details = (_b = (_a = todoMatch.groups) === null || _a === void 0 ? void 0 : _a.details) !== null && _b !== void 0 ? _b : '';
+    const isPriorityOnly = /^[!\s]*$/u.test(details);
+    const hasPromptRunnerTokens = extractPromptRunnerTokens(line).length > 0;
+    if (details.trim() !== '' && !isPriorityOnly && !hasPromptRunnerTokens) {
+        return undefined;
     }
-    const priority = status === 'todo' ? (_e = (_d = (_c = match.groups) === null || _c === void 0 ? void 0 : _c.priority) === null || _d === void 0 ? void 0 : _d.length) !== null && _e !== void 0 ? _e : 0 : 0;
-    return { status, priority };
+    return { status: 'todo', priority: (_d = (_c = details.match(/!/gu)) === null || _c === void 0 ? void 0 : _c.length) !== null && _d !== void 0 ? _d : 0 };
 }
 /**
  * Finds the first non-empty line index between two bounds.
@@ -73801,6 +73861,66 @@ var findUnwrittenPrompts$1 = /*#__PURE__*/Object.freeze({
     findUnwrittenPrompts: findUnwrittenPrompts
 });
 
+/**
+ * Agent source used by `ptbk coder ping` for its disposable connectivity turn.
+ */
+const PING_AGENT_SOURCE = spaceTrim$1(`
+    Promptbook Coder Ping Agent
+
+    PERSONA You are a connectivity test agent. Perform only the tiny task requested by the user and answer concisely.
+`);
+/**
+ * User message used by `ptbk coder ping` to produce a deterministic response.
+ */
+const PING_MESSAGE = 'Reply with exactly the single word PONG and nothing else.';
+/**
+ * Runs one small harness/model turn in a disposable temporary project.
+ *
+ * The temporary project is outside the caller's repository, so even a harness
+ * that writes files cannot change the project from which `ptbk coder ping` was
+ * started.
+ */
+async function runCoderPing(options) {
+    const temporaryProjectPath = await mkdtemp(join(tmpdir(), 'promptbook-coder-ping-'));
+    const originalWorkingDirectory = process.cwd();
+    try {
+        const agentPath = join(temporaryProjectPath, 'ping.book');
+        await writeFile(agentPath, `${PING_AGENT_SOURCE}\n`, 'utf-8');
+        // Note: Some supported CLI wrappers inherit the Node process working directory instead of using projectPath.
+        process.chdir(temporaryProjectPath);
+        const startedAt = performance.now();
+        const result = await executeAgentChatTurn({
+            agentPath,
+            currentWorkingDirectory: temporaryProjectPath,
+            agentName: options.agentName,
+            model: options.model,
+            isVerbose: false,
+            noUi: options.isUiDisabled,
+            thinkingLevel: options.thinkingLevel,
+            allowCredits: options.isCreditsAllowed,
+            messages: [
+                {
+                    sender: 'USER',
+                    content: PING_MESSAGE,
+                },
+            ],
+        });
+        return {
+            result: result.answer,
+            elapsedTimeMs: performance.now() - startedAt,
+        };
+    }
+    finally {
+        process.chdir(originalWorkingDirectory);
+        await rm(temporaryProjectPath, { recursive: true, force: true });
+    }
+}
+
+var runCoderPing$1 = /*#__PURE__*/Object.freeze({
+    __proto__: null,
+    runCoderPing: runCoderPing
+});
+
 /**
  * Default wait duration applied before retrying a failed prompt round.
  */
@@ -73808,7 +73928,7 @@ const DEFAULT_WAIT_AFTER_ERROR_MS = 10 * 60 * 1000;
 /**
  * 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...>] [--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] [--ignore-git-changes] [--no-normalize-line-endings] [--auto-push] [--auto-pull]';
+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] [--ignore-git-changes] [--no-normalize-line-endings] [--auto-push] [--auto-pull]';
 /**
  * Top-level flags supported by this command.
  */
@@ -73818,6 +73938,7 @@ const KNOWN_OPTION_FLAGS = new Set([
     '--model',
     '--context',
     '--test',
+    '--test-before',
     '--preserve-logs',
     '--isolate',
     '--no-ui',
@@ -73856,6 +73977,8 @@ function parseRunOptions(args) {
     const context = readOptionValue(args, '--context');
     const hasTestCommandFlag = args.includes('--test');
     const testCommand = readVariadicOptionValue(args, '--test');
+    const hasTestBeforeFlag = args.includes('--test-before');
+    const testBefore = parseTestBeforeOption(readOptionValue(args, '--test-before'), hasTestBeforeFlag);
     const preserveLogs = args.includes('--preserve-logs');
     const isIsolated = args.includes('--isolate');
     const noUi = args.includes('--no-ui');
@@ -73928,6 +74051,7 @@ function parseRunOptions(args) {
         model,
         context,
         testCommand,
+        testBefore,
         thinkingLevel,
         priority: minimumPriority !== null && minimumPriority !== void 0 ? minimumPriority : 0,
         minimumPriority,
@@ -73936,6 +74060,21 @@ function parseRunOptions(args) {
         limit,
     };
 }
+/**
+ * Parses and validates the optional pre-coding verification mode.
+ */
+function parseTestBeforeOption(value, hasTestBeforeFlag) {
+    if (value === undefined) {
+        if (hasTestBeforeFlag) {
+            exitWithUsageError(`Missing value for --test-before. Use one of: ${TEST_BEFORE_MODE_VALUES.join(', ')}.`);
+        }
+        return 'no';
+    }
+    if (!isTestBeforeMode(value)) {
+        exitWithUsageError(`Invalid value for --test-before: "${value}". Use one of: ${TEST_BEFORE_MODE_VALUES.join(', ')}.`);
+    }
+    return value;
+}
 /**
  * Reads a duration-typed CLI flag, applying the provided default when the flag is absent.
  */
@@ -76050,6 +76189,16 @@ function formatRunnerSignature(runnerName, modelName, thinkingLevel) {
     return `${runnerLabel} \`${normalizedModel}\`${thinkingLevelSuffix}`;
 }
 
+/**
+ * Replaces the complete todo status line while preserving its indentation.
+ *
+ * The complete line is replaced because a todo status can contain a required
+ * model/harness token in addition to priority markers.
+ */
+function replacePromptTodoStatusLine(line, replacementStatusLine) {
+    return line.replace(/^(?<indentation>\s*)\[\s*\].*$/u, `$<indentation>${replacementStatusLine}`);
+}
+
 /**
  * Marks a prompt section as done and records the per-step usage pricing and runner details.
  */
@@ -76067,8 +76216,8 @@ function markPromptDone(file, section, steps, runnerName, modelName, attemptCoun
     const loginMethodSuffix = loginMethodLabel ? ` (${loginMethodLabel})` : '';
     const stepsSummary = formatCoderRunSteps(steps);
     const stepsSuffix = stepsSummary === '' ? '' : ` - ${stepsSummary}`;
-    // Replace "[ ]" or "[ ] !!..." with "[x] by runner model thinking level (login method) - Step $price duration; ..."
-    file.lines[section.statusLineIndex] = line.replace(/\[\s*\]\s*!*\s*$/, `[x] ${attemptMetadata}by ${runnerSignature}${loginMethodSuffix}${stepsSuffix}`);
+    // Replace the complete todo status, including any required model/harness token.
+    file.lines[section.statusLineIndex] = replacePromptTodoStatusLine(line, `[x] ${attemptMetadata}by ${runnerSignature}${loginMethodSuffix}${stepsSuffix}`);
 }
 
 /**
@@ -76086,8 +76235,10 @@ function markPromptFailed(file, section, runnerName, modelName, promptExecutionS
     const attemptMetadata = formatPromptAttemptMetadata('failed', attemptCount);
     const duration = moment().diff(promptExecutionStartedDate);
     const durationString = moment.duration(duration).humanize();
-    const failureDetails = attemptMetadata === '' ? `failed after ${durationString} by ${runnerSignature}` : `${attemptMetadata}${durationString} by ${runnerSignature}`;
-    file.lines[section.statusLineIndex] = line.replace(/\[\s*\]\s*!*\s*$/, `[!] ${failureDetails}`);
+    const failureDetails = attemptMetadata === ''
+        ? `failed after ${durationString} by ${runnerSignature}`
+        : `${attemptMetadata}${durationString} by ${runnerSignature}`;
+    file.lines[section.statusLineIndex] = replacePromptTodoStatusLine(line, `[!] ${failureDetails}`);
 }
 
 /**
@@ -77057,17 +77208,18 @@ function toProjectRelativeGitPath(projectPath, path) {
 /**
  * Lists todo prompts that are ready to run (no authoring placeholders).
  */
-function listRunnablePrompts(files, priorityFilter = {}) {
+function listRunnablePrompts(files, priorityFilter = {}, promptRunnerIdentity) {
     return listTodoPrompts(files).filter((prompt) => !isPromptToBeWritten(prompt.file, prompt.section) &&
-        isPromptInPriorityFilter(prompt.section, priorityFilter));
+        isPromptInPriorityFilter(prompt.section, priorityFilter) &&
+        isPromptCompatibleWithRunner(prompt.file, prompt.section, promptRunnerIdentity));
 }
 
 /**
  * Selects the next runnable prompt based on priority.
  */
-function findNextTodoPrompt(files, priorityFilter = {}) {
+function findNextTodoPrompt(files, priorityFilter = {}, promptRunnerIdentity) {
     let nextPrompt;
-    for (const prompt of listRunnablePrompts(files, priorityFilter)) {
+    for (const prompt of listRunnablePrompts(files, priorityFilter, promptRunnerIdentity)) {
         if (!nextPrompt || prompt.section.priority > nextPrompt.section.priority) {
             nextPrompt = prompt;
         }
@@ -77078,8 +77230,8 @@ function findNextTodoPrompt(files, priorityFilter = {}) {
 /**
  * Lists upcoming tasks that are ready to run (no authoring placeholders).
  */
-function listUpcomingTasks(files, priorityFilter = {}) {
-    return listRunnablePrompts(files, priorityFilter).map(({ file, section }) => ({
+function listUpcomingTasks(files, priorityFilter = {}, promptRunnerIdentity) {
+    return listRunnablePrompts(files, priorityFilter, promptRunnerIdentity).map(({ file, section }) => ({
         label: buildPromptLabelForDisplay(file, section),
         summary: buildPromptSummary(file, section),
         priority: section.priority,
@@ -77223,6 +77375,71 @@ async function buildCoderRunAgentVisual(agentSource) {
     }
 }
 
+/**
+ * Creates the one queue prompt used to repair a pre-existing test failure.
+ */
+async function createTestBeforeRepairPrompt(options) {
+    const description = spaceTrim((block) => `
+            Fix the existing test failures before implementing any queued coding tasks.
+
+            The verification command \`${options.testCommand}\` failed before coding started. Fix the underlying failure without weakening or removing the tests, and leave the project ready for the remaining coding prompts.
+
+            ## Verification output
+
+            \`\`\`
+            ${block(limitTestOutput(options.testOutput))}
+            \`\`\`
+        `);
+    const createdPrompt = await addCoderPrompt({
+        projectPath: options.projectPath,
+        description,
+        priority: 0,
+    });
+    const promptPath = join(options.projectPath, createdPrompt.filePath);
+    const promptFile = parsePromptFile(promptPath, await readFile(promptPath, 'utf-8'));
+    const section = promptFile.sections[0];
+    if (!section) {
+        throw new UnexpectedError(spaceTrim(`
+                The pre-coding test repair prompt was created at \`${createdPrompt.filePath}\` without a runnable section.
+            `));
+    }
+    return { file: promptFile, section };
+}
+
+/**
+ * Runs the configured verification command before the first coding prompt.
+ */
+async function runTestBefore(options) {
+    var _a, _b;
+    const runPromptTestCommandExecutor = (_a = options.runPromptTestCommandExecutor) !== null && _a !== void 0 ? _a : runPromptTestCommand;
+    const initialTestStatusMessage = `Running initial tests before the agent coding starts: ${options.testCommand}`;
+    await ((_b = options.waitForPauseCheckpoint) === null || _b === void 0 ? void 0 : _b.call(options, {
+        checkpointLabel: 'running initial tests before the agent coding starts',
+        phase: 'verifying',
+        statusMessage: initialTestStatusMessage,
+    }));
+    console.info(colors.gray(initialTestStatusMessage));
+    try {
+        const testOutput = await runPromptTestCommandExecutor({
+            command: options.testCommand,
+            projectPath: options.projectPath,
+            scriptPath: buildTemporaryPromptScriptPath({
+                projectPath: options.projectPath,
+                scriptDirectoryName: 'coder-prompts',
+                sourceFileName: 'test-before',
+            }),
+        });
+        console.info(colors.green('Pre-coding tests passed.'));
+        return { isPassed: true, testOutput };
+    }
+    catch (error) {
+        const testOutput = formatUnknownErrorMessage(error);
+        console.error(colors.red('Pre-coding tests failed.'));
+        console.error(testOutput);
+        return { isPassed: false, testOutput };
+    }
+}
+
 /**
  * Constant for prompts dir.
  */
@@ -77250,6 +77467,10 @@ async function runCodexPrompts(providedOptions) {
             return;
         }
         const { runner, actualRunnerModel, runnerMetadata } = resolvePromptRunner(options);
+        const promptRunnerIdentity = {
+            harnessName: options.agentName,
+            modelName: actualRunnerModel,
+        };
         console.info(colors.green(`Running prompts with ${runner.name}`));
         initializeRunUi(uiHandle, runner.name, actualRunnerModel, options);
         await initializeRunUiAgentVisual(uiHandle, resolvedCoderAgent === null || resolvedCoderAgent === void 0 ? void 0 : resolvedCoderAgent.agentSource);
@@ -77264,6 +77485,7 @@ async function runCodexPrompts(providedOptions) {
         let previousRoundStartTime;
         let previousRoundEndTime;
         let completedRunCount = 0;
+        let hasRunTestBefore = false;
         while (just(true)) {
             if (options.autoPull && !options.dryRun) {
                 await waitForRequestedPause({
@@ -77276,6 +77498,35 @@ async function runCodexPrompts(providedOptions) {
                 options,
                 isRichUiEnabled,
             });
+            if (!hasRunTestBefore && options.testBefore !== 'no') {
+                await waitForRequestedPause({
+                    checkpointLabel: 'loading prompts before running initial tests',
+                    phase: 'loading',
+                    statusMessage: 'Loading prompts before running initial tests...',
+                });
+                await loadPromptQueueSnapshot({
+                    options,
+                    isRichUiEnabled,
+                    progressDisplay,
+                    uiHandle,
+                    promptRunnerIdentity,
+                });
+            }
+            if (!hasRunTestBefore) {
+                hasWaitedForStart = await runTestBeforeIfNeeded({
+                    options,
+                    runner,
+                    runnerMetadata,
+                    resolvedCoderContext,
+                    resolvedAgentSystemMessage,
+                    isRichUiEnabled,
+                    progressDisplay,
+                    uiHandle,
+                    waitForRequestedPause,
+                    hasWaitedForStart,
+                });
+                hasRunTestBefore = true;
+            }
             await waitForRequestedPause({
                 checkpointLabel: 'loading prompts',
                 phase: 'loading',
@@ -77286,6 +77537,7 @@ async function runCodexPrompts(providedOptions) {
                 isRichUiEnabled,
                 progressDisplay,
                 uiHandle,
+                promptRunnerIdentity,
             });
             hasShownUpcomingTasks || (hasShownUpcomingTasks = showUpcomingTasksOnce({
                 hasShownUpcomingTasks,
@@ -77293,6 +77545,7 @@ async function runCodexPrompts(providedOptions) {
                 stats: promptQueueSnapshot.stats,
                 priorityFilter: options.priorityFilter,
                 isRichUiEnabled,
+                promptRunnerIdentity,
             }));
             if (!promptQueueSnapshot.nextPrompt) {
                 if (isEndAfterCurrentPromptRequested(completedRunCount)) {
@@ -77395,6 +77648,14 @@ async function runCodexPrompts(providedOptions) {
  * Validates cross-flag constraints before the run starts.
  */
 function validateRunCodexPromptOptions(options) {
+    var _a;
+    if (!isTestBeforeMode((_a = options.testBefore) !== null && _a !== void 0 ? _a : 'no')) {
+        throw new NotAllowed(spaceTrim$1(`
+                Invalid ${'`--test-before`'} mode: \`${String(options.testBefore)}\`.
+
+                Use one of: \`no\`, \`yes-and-fail\`, \`yes-and-fix\`.
+            `));
+    }
     if (options.allowDestructiveAutoMigrate && !options.autoMigrate) {
         throw new DatabaseError(spaceTrim$1(`
                 Flag \`--allow-destructive-auto-migrate\` requires \`--auto-migrate\`.
@@ -77465,20 +77726,103 @@ function createRunDisplays(options, runStartDate) {
  * Normalizes legacy and current priority options into one validated run option shape.
  */
 function normalizeRunOptions(options) {
-    var _a, _b, _c, _d, _e;
+    var _a, _b, _c, _d, _e, _f, _g;
+    const testBefore = (_a = options.testBefore) !== null && _a !== void 0 ? _a : 'no';
+    const normalizedTestCommand = (_b = options.testCommand) === null || _b === void 0 ? void 0 : _b.trim();
     const priorityFilter = normalizePriorityFilter({
         priority: options.priority,
-        minimumPriority: (_a = options.minimumPriority) !== null && _a !== void 0 ? _a : (_b = options.priorityFilter) === null || _b === void 0 ? void 0 : _b.minimumPriority,
-        maximumPriority: (_c = options.maximumPriority) !== null && _c !== void 0 ? _c : (_d = options.priorityFilter) === null || _d === void 0 ? void 0 : _d.maximumPriority,
+        minimumPriority: (_c = options.minimumPriority) !== null && _c !== void 0 ? _c : (_d = options.priorityFilter) === null || _d === void 0 ? void 0 : _d.minimumPriority,
+        maximumPriority: (_e = options.maximumPriority) !== null && _e !== void 0 ? _e : (_f = options.priorityFilter) === null || _f === void 0 ? void 0 : _f.maximumPriority,
     });
     return {
         ...options,
-        priority: (_e = priorityFilter.minimumPriority) !== null && _e !== void 0 ? _e : 0,
+        testBefore,
+        testCommand: normalizedTestCommand || (testBefore === 'no' ? undefined : DEFAULT_CODER_TEST_COMMAND),
+        priority: (_g = priorityFilter.minimumPriority) !== null && _g !== void 0 ? _g : 0,
         minimumPriority: priorityFilter.minimumPriority,
         maximumPriority: priorityFilter.maximumPriority,
         priorityFilter,
     };
 }
+/**
+ * Runs the optional pre-coding verification and, when requested, its one repair prompt.
+ */
+async function runTestBeforeIfNeeded(options) {
+    const { options: runOptions, runner, runnerMetadata, resolvedCoderContext, resolvedAgentSystemMessage, isRichUiEnabled, progressDisplay, uiHandle, waitForRequestedPause, hasWaitedForStart, } = options;
+    if (runOptions.testBefore === 'no') {
+        return hasWaitedForStart;
+    }
+    if (!runOptions.testCommand) {
+        throw new NotAllowed(spaceTrim$1(`
+                ${'`--test-before ' + runOptions.testBefore + '`'} requires a verification command.
+
+                Pass one with ${'`--test <test-command>`'} or use the default ${'`npm test`'} command by providing the mode through the CLI.
+            `));
+    }
+    if (!runOptions.ignoreGitChanges) {
+        await waitForRequestedPause({
+            checkpointLabel: 'checking the git working tree before testing',
+            phase: 'loading',
+            statusMessage: 'Checking the working tree before testing...',
+        });
+        await ensureWorkingTreeClean();
+    }
+    uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.startCapturingAgentOutput();
+    const testBeforeResult = await runTestBefore({
+        testCommand: runOptions.testCommand,
+        projectPath: process.cwd(),
+        waitForPauseCheckpoint: waitForRequestedPause,
+    }).finally(() => {
+        uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.stopCapturingAgentOutput();
+    });
+    if (testBeforeResult.isPassed) {
+        return hasWaitedForStart;
+    }
+    const testOutput = limitTestOutput(testBeforeResult.testOutput);
+    if (runOptions.testBefore === 'yes-and-fail') {
+        throw new NotAllowed(spaceTrim$1((block) => `
+                    Pre-coding verification command \`${runOptions.testCommand}\` failed.
+
+                    The coding agent was not started because the project was already failing before the first queued prompt.
+
+                    ### Test results
+                    ${'```'}
+                    ${block(testOutput)}
+                    ${'```'}
+                `));
+    }
+    const repairPrompt = await createTestBeforeRepairPrompt({
+        projectPath: process.cwd(),
+        testCommand: runOptions.testCommand,
+        testOutput,
+    });
+    const repairPromptLabel = buildPromptLabelForDisplay(repairPrompt.file, repairPrompt.section);
+    const updatedHasWaitedForStart = await waitForPromptConfirmationIfNeeded({
+        options: runOptions,
+        nextPrompt: repairPrompt,
+        promptLabel: repairPromptLabel,
+        hasWaitedForStart,
+        isRichUiEnabled,
+        progressDisplay,
+        uiHandle,
+    });
+    // The repair prompt is created in the current worktree so it can be recorded and committed with the repair.
+    // It therefore intentionally uses the regular round here even when the queue itself uses --isolate.
+    await runPromptRound({
+        options: runOptions,
+        runner,
+        runnerMetadata,
+        nextPrompt: repairPrompt,
+        promptLabel: repairPromptLabel,
+        resolvedCoderContext,
+        resolvedAgentSystemMessage,
+        isRichUiEnabled,
+        progressDisplay,
+        uiHandle,
+        waitForRequestedPause,
+    });
+    return updatedHasWaitedForStart;
+}
 /**
  * Creates a pause waiter that keeps the progress display and rich UI in sync.
  */
@@ -77563,7 +77907,7 @@ async function initializeRunUiAgentVisual(uiHandle, agentSource) {
  * Loads prompt files, updates progress displays, and selects the next runnable prompt.
  */
 async function loadPromptQueueSnapshot(options) {
-    const { options: runOptions, isRichUiEnabled, progressDisplay, uiHandle } = options;
+    const { options: runOptions, isRichUiEnabled, progressDisplay, uiHandle, promptRunnerIdentity } = options;
     uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.setCurrentScriptPath(undefined);
     const promptFiles = await loadPromptFiles(PROMPTS_DIR$1);
     const stats = summarizePrompts(promptFiles, runOptions.priorityFilter);
@@ -77575,14 +77919,14 @@ async function loadPromptQueueSnapshot(options) {
     return {
         promptFiles,
         stats,
-        nextPrompt: findNextTodoPrompt(promptFiles, runOptions.priorityFilter),
+        nextPrompt: findNextTodoPrompt(promptFiles, runOptions.priorityFilter, promptRunnerIdentity),
     };
 }
 /**
  * Prints upcoming tasks only on the first loop iteration in plain-console mode.
  */
 function showUpcomingTasksOnce(options) {
-    const { hasShownUpcomingTasks, promptFiles, stats, priorityFilter, isRichUiEnabled } = options;
+    const { hasShownUpcomingTasks, promptFiles, stats, priorityFilter, isRichUiEnabled, promptRunnerIdentity } = options;
     if (hasShownUpcomingTasks || isRichUiEnabled) {
         return true;
     }
@@ -77591,7 +77935,7 @@ function showUpcomingTasksOnce(options) {
         printPromptsToBeWritten(promptFiles, priorityFilter);
         console.info('');
     }
-    printUpcomingTasks(listUpcomingTasks(promptFiles, priorityFilter));
+    printUpcomingTasks(listUpcomingTasks(promptFiles, priorityFilter, promptRunnerIdentity));
     return true;
 }
 /**
@@ -77601,7 +77945,10 @@ function finishWhenNoPromptIsAvailable(promptQueueSnapshot, isRichUiEnabled, uiH
     if (promptQueueSnapshot.nextPrompt) {
         return false;
     }
-    if (promptQueueSnapshot.stats.toBeWritten > 0) {
+    if (promptQueueSnapshot.stats.forAgent > 0) {
+        announceRunCompletion('No prompts match the selected harness or model.', colors.yellow, isRichUiEnabled, uiHandle);
+    }
+    else if (promptQueueSnapshot.stats.toBeWritten > 0) {
         announceRunCompletion('No prompts ready for agent.', colors.yellow, isRichUiEnabled, uiHandle);
     }
     else {
@@ -77642,9 +77989,16 @@ function finishWhenEndAfterCurrentPromptIsRequested(options) {
  * Updates the UI status message while waiting for new prompts in keepAlive server mode.
  */
 function announceKeepAliveStatus(promptQueueSnapshot, isRichUiEnabled, uiHandle) {
-    const message = promptQueueSnapshot.stats.toBeWritten > 0
-        ? 'No prompts ready for agent. Watching for changes...'
-        : 'All prompts are done. Watching for changes...';
+    let message;
+    if (promptQueueSnapshot.stats.forAgent > 0) {
+        message = 'No prompts match the selected harness or model. Watching for changes...';
+    }
+    else if (promptQueueSnapshot.stats.toBeWritten > 0) {
+        message = 'No prompts ready for agent. Watching for changes...';
+    }
+    else {
+        message = 'All prompts are done. Watching for changes...';
+    }
     uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.setStatusMessage(message);
     uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.setPhase('waiting');
     if (!isRichUiEnabled) {
@@ -77666,7 +78020,7 @@ function announceRunCompletion(message, colorize, isRichUiEnabled, uiHandle) {
  * Waits for the optional user confirmation before starting the selected prompt.
  */
 async function waitForPromptConfirmationIfNeeded(options) {
-    const { options: runOptions, nextPrompt, promptLabel, hasWaitedForStart, isRichUiEnabled, progressDisplay, uiHandle } = options;
+    const { options: runOptions, nextPrompt, promptLabel, hasWaitedForStart, isRichUiEnabled, progressDisplay, uiHandle, } = options;
     if (!runOptions.waitForUser) {
         return hasWaitedForStart;
     }