@promptbook/cli 0.112.0-42 → 0.112.0-44

package/esm/index.es.js

@@ -4,7 +4,7 @@ import _spaceTrim, { spaceTrim as spaceTrim$1 } from 'spacetrim';
 import * as fs from 'fs';
 import { mkdirSync, writeFileSync, readFileSync, existsSync } from 'fs';
 import { join, basename, dirname, isAbsolute, relative, extname, resolve } from 'path';
-import { readFile, writeFile, stat, mkdir, access, constants, readdir, watch, unlink, rm, rename, rmdir } from 'fs/promises';
+import { readFile, writeFile, stat, mkdir, access, constants, readdir, watch, unlink, rm, rename, rmdir, appendFile } from 'fs/promises';
 import { forTime, forEver } from 'waitasecond';
 import prompts from 'prompts';
 import * as dotenv from 'dotenv';
@@ -37,6 +37,7 @@ import { spawn } from 'child_process';
 import { Client } from 'pg';
 import '@supabase/supabase-js';
 import { dirname as dirname$1 } from 'path/posix';
+import { EventEmitter } from 'events';
 import { Subject, BehaviorSubject } from 'rxjs';
 import { lookup, extension } from 'mime-types';
 import { parse, unparse } from 'papaparse';
@@ -57,7 +58,7 @@ const BOOK_LANGUAGE_VERSION = '2.0.0';
  * @generated
  * @see https://github.com/webgptorg/promptbook
  */
-const PROMPTBOOK_ENGINE_VERSION = '0.112.0-42';
+const PROMPTBOOK_ENGINE_VERSION = '0.112.0-44';
 /**
  * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
  * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -2320,7 +2321,7 @@ function getDefaultCoderAgentCodingFileContent({ packageJsonScripts, }) {
         '',
         '## 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 `--priority`, `--ignore-git-changes`, `--dry-run`, `--allow-credits`, or `--auto-migrate`.',
+        '-   Use direct CLI commands when you need one-off flags such as `--priority`, `--ignore-git-changes`, `--dry-run`, `--test`, `--allow-credits`, or `--auto-migrate`.',
         '-   Use `npx ptbk coder --help` and `npx ptbk coder <command> --help` for the full CLI reference.',
     ].join('\n');
 }
@@ -2580,6 +2581,26 @@ class ParseError extends Error {
 }
 // TODO: Maybe split `ParseError` and `ApplyError`
 
+/**
+ * Loads the TypeScript runtime used for parsing JSONC-style project files.
+ *
+ * @private internal utility of `coder init`
+ */
+async function getTypescriptModule() {
+    return normalizeImportedTypescriptModule((await import('typescript')));
+}
+/**
+ * Normalizes CommonJS-via-`default` and direct namespace imports of TypeScript.
+ *
+ * @private internal utility of `getTypescriptModule`
+ */
+function normalizeImportedTypescriptModule(importedTypescriptModule) {
+    return 'parseConfigFileTextToJson' in importedTypescriptModule
+        ? importedTypescriptModule
+        : importedTypescriptModule.default;
+}
+// Note: [🟡] Code for coder init TypeScript loading [getTypescriptModule](src/cli/cli-commands/coder/getTypescriptModule.ts) should never be published outside of `@promptbook/cli`
+
 /**
  * Default indentation used when creating new JSON configuration files.
  */
@@ -2625,7 +2646,7 @@ async function parseJsonObjectFile(relativeFilePath, fileContent) {
     if (fileContent.trim() === '') {
         return {};
     }
-    const typescript = await import('typescript');
+    const typescript = await getTypescriptModule();
     const parsedFile = typescript.parseConfigFileTextToJson(relativeFilePath, fileContent);
     if (parsedFile.error) {
         throw new ParseError(spaceTrim$1(`
@@ -2983,7 +3004,9 @@ function $initializeCoderRunCommand(program) {
 
             Features:
             - Automatically stages and commits changes with agent identity
+            - Optional post-commit git push with explicit --auto-push opt-in
             - Supports GPG signing of commits
+            - Optional post-prompt verification with test-feedback retries
             - Progress tracking and interactive controls
             - Dry-run mode to preview prompts
         `));
@@ -2996,17 +3019,20 @@ function $initializeCoderRunCommand(program) {
             Gemini examples: gemini-3-flash-preview, default
         `));
     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('--thinking-level <thinking-level>', `Set reasoning effort for supported runners (${THINKING_LEVEL_VALUES.join(', ')})`).choices([...THINKING_LEVEL_VALUES]));
     command.option('--priority <minimum-priority>', 'Filter prompts by minimum priority level', parseIntOption, 0);
     command.option('--no-wait', 'Skip user prompts between processing');
     command.option('--ignore-git-changes', 'Skip clean working tree check before running prompts', false);
     command.option('--allow-credits', 'Allow OpenAI Codex runner to spend credits when rate limits are exhausted', false);
+    command.option('--preserve-logs', 'Keep generated runner shells and runtime logs after successful prompt rounds; failures keep them automatically', false);
     command.option('--no-normalize-line-endings', 'Disable automatic LF normalization for files changed in each coding round');
-    command.option('--no-push', 'Disable automatic git push after each commit');
+    command.option('--auto-push', 'Automatically git push after each commit', false);
     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, model, context, thinkingLevel, priority, wait, ignoreGitChanges, allowCredits, normalizeLineEndings, autoMigrate, allowDestructiveAutoMigrate, push, } = cliOptions;
+        const { dryRun, agent, model, context, test, thinkingLevel, priority, wait, ignoreGitChanges, allowCredits, preserveLogs, normalizeLineEndings, autoMigrate, allowDestructiveAutoMigrate, autoPush, } = cliOptions;
+        const testCommand = normalizeCommandOptionValue(test);
         // Validate agent
         let agentName = undefined;
         if (agent) {
@@ -3035,13 +3061,15 @@ function $initializeCoderRunCommand(program) {
             agentName,
             model,
             context,
+            testCommand,
             thinkingLevel,
             priority,
             normalizeLineEndings,
             allowCredits,
+            preserveLogs,
             autoMigrate,
             allowDestructiveAutoMigrate,
-            noPush: !push,
+            autoPush,
         };
         // Note: Import the function dynamically to avoid loading heavy dependencies until needed
         const { runCodexPrompts } = await Promise.resolve().then(function () { return runCodexPrompts$1; });
@@ -3070,6 +3098,19 @@ function parseIntOption(value) {
     }
     return parsed;
 }
+/**
+ * Joins one Commander option that may be parsed either as a single string or a variadic token array.
+ *
+ * @private internal utility of `coder run` command
+ */
+function normalizeCommandOptionValue(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    const parts = Array.isArray(value) ? value : [value];
+    const normalizedValue = parts.map((part) => part.trim()).filter(Boolean).join(' ').trim();
+    return normalizedValue === '' ? undefined : normalizedValue;
+}
 // Note: [🟡] Code for CLI command [run](src/cli/cli-commands/coder/run.ts) should never be published outside of `@promptbook/cli`
 // Note: [💞] Ignore a discrepancy between file name and entity name
 
@@ -18910,7 +18951,7 @@ class GoalCommitmentDefinition extends BaseCommitmentDefinition {
      * Short one-line description of GOAL.
      */
     get description() {
-        return 'Define main **goals** the AI assistant should achieve, with later goals having higher priority.';
+        return 'Define the effective agent **goal**; when multiple goals exist, only the last one stays effective.';
     }
     /**
      * Icon for this commitment.
@@ -18925,12 +18966,14 @@ class GoalCommitmentDefinition extends BaseCommitmentDefinition {
         return spaceTrim$1(`
             # ${this.type}
 
-            Defines the main goal which should be achieved by the AI assistant. There can be multiple goals, and later goals are more important than earlier goals.
+            Defines the main goal which should be achieved by the AI assistant.
+            There can be multiple goals in source, but after inheritance/source rewriting only the last \`GOAL\` /\`GOALS\` remains effective.
 
             ## Key aspects
 
             - Both terms work identically and can be used interchangeably.
-            - Later goals have higher priority and can override earlier goals.
+            - Later goals overwrite earlier goals.
+            - The public agent profile text is derived from the last goal.
             - Goals provide clear direction and purpose for the agent's responses.
             - Goals influence decision-making and response prioritization.
 
@@ -18943,9 +18986,7 @@ class GoalCommitmentDefinition extends BaseCommitmentDefinition {
             \`\`\`book
             Customer Support Agent
 
-            PERSONA You are a helpful customer support representative
             GOAL Resolve customer issues quickly and efficiently
-            GOAL Maintain high customer satisfaction scores
             GOAL Always follow company policies and procedures
             RULE Be polite and professional at all times
             \`\`\`
@@ -18953,9 +18994,7 @@ class GoalCommitmentDefinition extends BaseCommitmentDefinition {
             \`\`\`book
             Educational Assistant
 
-            PERSONA You are an educational assistant specializing in mathematics
             GOAL Help students understand mathematical concepts clearly
-            GOAL Encourage critical thinking and problem-solving skills
             GOAL Ensure all explanations are age-appropriate and accessible
             STYLE Use simple language and provide step-by-step explanations
             \`\`\`
@@ -18963,9 +19002,7 @@ class GoalCommitmentDefinition extends BaseCommitmentDefinition {
             \`\`\`book
             Safety-First Assistant
 
-            PERSONA You are a general-purpose AI assistant
             GOAL Be helpful and informative in all interactions
-            GOAL Provide accurate and reliable information
             GOAL Always prioritize user safety and ethical guidelines
             RULE Never provide harmful or dangerous advice
             \`\`\`
@@ -21824,7 +21861,16 @@ class PersonaCommitmentDefinition extends BaseCommitmentDefinition {
      * Short one-line description of PERSONA.
      */
     get description() {
-        return 'Define who the agent is: background, expertise, and personality.';
+        return 'Deprecated legacy profile commitment. Prefer `GOAL` for agent profile text and inheritance-safe rewrites.';
+    }
+    /**
+     * Optional UI/docs-only deprecation metadata.
+     */
+    get deprecation() {
+        return {
+            message: 'Use `GOAL` for agent profile text and inheritance-safe rewrites.',
+            replacedBy: ['GOAL'],
+        };
     }
     /**
      * Icon for this commitment.
@@ -21839,16 +21885,24 @@ class PersonaCommitmentDefinition extends BaseCommitmentDefinition {
         return spaceTrim$1(`
             # ${this.type}
 
-            Defines who the agent is, their background, expertise, and personality traits.
+            Deprecated legacy commitment that defines who the agent is, their background, expertise, and personality traits.
 
-            ## Key aspects
+            ## Migration
 
-            - Multiple \`PERSONA\` and \`PERSONAE\` commitments are merged together.
-            - Both terms work identically and can be used interchangeably.
-            - If they are in conflict, the last one takes precedence.
-            - You can write persona content in multiple lines.
+            - Existing \`${this.type}\` books still parse and compile.
+            - New books should prefer \`GOAL\`.
+            - Agent profile rendering now prefers the last \`GOAL\` and only falls back to \`${this.type}\` when no goal exists.
+            - Runtime compilation keeps the legacy multi-\`PERSONA\` merge behavior for backward compatibility.
 
-            ## Examples
+            ## Preferred replacement
+
+            \`\`\`book
+            Programming Assistant
+
+            GOAL Help the user solve programming problems with practical TypeScript and React guidance.
+            \`\`\`
+
+            ## Legacy compatibility example
 
             \`\`\`book
             Programming Assistant
@@ -22556,6 +22610,15 @@ const teamToolFunctions = {};
  * Map of team tool titles.
  */
 const teamToolTitles = {};
+/**
+ * Shared TEAM usage rules appended ahead of teammate listings.
+ *
+ * @private
+ */
+const TEAM_SYSTEM_MESSAGE_GUIDANCE_LINES = [
+    '- If a teammate is relevant to the request, consult that teammate using the matching tool.',
+    '- Do not ask the user for information that a listed teammate can provide directly.',
+];
 /**
  * Constant for remote agents by Url.
  */
@@ -22604,7 +22667,7 @@ class TeamCommitmentDefinition extends BaseCommitmentDefinition {
             \`\`\`book
             Legal Assistant
 
-            PERSONA An expert software developer
+            GOAL Get expert software-development advice from the teammate when legal discussion needs technical context.
             TEAM You can talk with http://localhost:4440/agents/GMw67JN8TXxN7y to discuss the legal aspects.
             \`\`\`
         `);
@@ -22645,12 +22708,9 @@ class TeamCommitmentDefinition extends BaseCommitmentDefinition {
             if (updatedTools.some((tool) => tool.name === entry.toolName)) {
                 continue;
             }
-            const toolDescription = entry.description
-                ? `Consult teammate ${entry.teammate.label}\n${entry.description}`
-                : `Consult teammate ${entry.teammate.label}`;
             updatedTools.push({
                 name: entry.toolName,
-                description: toolDescription,
+                description: buildTeamToolDescription(entry),
                 parameters: {
                     type: 'object',
                     properties: {
@@ -22719,22 +22779,72 @@ function resolveTeamTeammateLabels(teamContent, teammates) {
 /**
  * Builds the textual TEAM section body for the final system message.
  *
- * Each teammate is listed with its tool name and, when available, a one-line description.
- * Uses `spaceTrim` to ensure consistent whitespace and indentation.
+ * Each teammate is listed with its tool name, TEAM instructions, and optional profile hints.
  */
 function buildTeamSystemMessageBody(teamEntries) {
-    const lines = teamEntries.map((entry, index) => {
-        const toolLine = `${index + 1}) ${entry.teammate.label} tool \`${entry.toolName}\``;
-        if (!entry.description) {
-            return toolLine;
-        }
-        return spaceTrim$1(`
-            ${toolLine}
-               ${entry.description}
-        `);
-    });
+    const lines = [
+        ...TEAM_SYSTEM_MESSAGE_GUIDANCE_LINES,
+        '',
+        ...teamEntries.map((entry, index) => {
+            const toolLine = `${index + 1}) ${entry.teammate.label} tool \`${entry.toolName}\``;
+            const detailLines = collectTeamEntryDetails(entry).map(formatTeamEntryDetailLine);
+            return [toolLine, ...detailLines].join('\n');
+        }),
+    ];
     return lines.join('\n');
 }
+/**
+ * Builds the model-visible description for one teammate tool.
+ *
+ * @private
+ */
+function buildTeamToolDescription(entry) {
+    const detailLines = collectTeamEntryDetails(entry).map(({ label, content }) => `${label}: ${content}`);
+    return [`Consult teammate ${entry.teammate.label}`, ...detailLines].join('\n');
+}
+/**
+ * Collects structured teammate details that should stay visible to the model.
+ *
+ * @private
+ */
+function collectTeamEntryDetails(entry) {
+    var _a;
+    const details = [];
+    const instructions = entry.teammate.instructions.trim();
+    const description = ((_a = entry.description) === null || _a === void 0 ? void 0 : _a.trim()) || '';
+    if (instructions) {
+        details.push({
+            label: 'TEAM instructions',
+            content: instructions,
+        });
+    }
+    if (description) {
+        details.push({
+            label: 'Profile',
+            content: description,
+        });
+    }
+    return details;
+}
+/**
+ * Formats one teammate detail line for the TEAM system-message section.
+ *
+ * @private
+ */
+function formatTeamEntryDetailLine(detail) {
+    return indentMultilineText(`${detail.label}: ${detail.content}`, '   ');
+}
+/**
+ * Indents all lines of one potentially multi-line text block.
+ *
+ * @private
+ */
+function indentMultilineText(text, prefix) {
+    return text
+        .split('\n')
+        .map((line) => `${prefix}${line}`)
+        .join('\n');
+}
 /**
  * Registers tool function and title for a teammate tool.
  */
@@ -40907,7 +41017,7 @@ function createEmptyAgentModelRequirements() {
         systemMessage: '',
         promptSuffix: '',
         // modelName: 'gpt-5',
-        modelName: 'gemini-2.5-flash-lite',
+        modelName: 'gpt-5.4-mini',
         temperature: 0.7,
         topP: 0.9,
         topK: 50,
@@ -41303,6 +41413,15 @@ const COMMITMENTS_WITH_AGENT_REFERENCES = new Set(['FROM', 'IMPORT', 'IMPORTS',
  * @private internal constant of `createAgentModelRequirementsWithCommitments`
  */
 const DELETE_COMMITMENT_TYPES = new Set(['DELETE', 'CANCEL', 'DISCARD', 'REMOVE']);
+/**
+ * Commitments whose earlier occurrences are overwritten by the last occurrence in source order.
+ *
+ * @private internal constant of `createAgentModelRequirementsWithCommitments`
+ */
+const OVERWRITTEN_COMMITMENT_GROUP_BY_TYPE = new Map([
+    ['GOAL', 'GOAL'],
+    ['GOALS', 'GOAL'],
+]);
 /**
  * Regex pattern matching markdown horizontal lines that should not be copied into the final system message.
  *
@@ -41353,7 +41472,7 @@ function getSafeReferenceCommitmentFallback(commitmentType, originalContent) {
  */
 async function createAgentModelRequirementsWithCommitments(agentSource, modelName, options) {
     const parseResult = parseAgentSourceWithCommitments(agentSource);
-    const filteredCommitments = filterDeletedCommitments(parseResult.commitments);
+    const filteredCommitments = filterOverwrittenCommitments(filterDeletedCommitments(parseResult.commitments));
     let requirements = createInitialAgentModelRequirements(parseResult.agentName, modelName);
     requirements = await applyCommitmentsToRequirements(requirements, filteredCommitments, options);
     requirements = aggregateUseCommitmentSystemMessages(requirements, filteredCommitments);
@@ -41364,6 +41483,35 @@ async function createAgentModelRequirementsWithCommitments(agentSource, modelNam
     requirements = await applyPendingInlineKnowledgeSources(requirements, options === null || options === void 0 ? void 0 : options.inlineKnowledgeSourceUploader);
     return finalizeRequirements(requirements);
 }
+/**
+ * Removes earlier commitments that are overwritten by later commitments of the same semantic group.
+ *
+ * This currently keeps only the last `GOAL` / `GOALS` commitment so inheritance rewrites
+ * and multi-goal sources expose one effective goal to the runtime.
+ *
+ * @param commitments - Parsed commitments after DELETE-like filtering.
+ * @returns Commitments with overwritten entries removed while preserving source order.
+ *
+ * @private internal utility of `createAgentModelRequirementsWithCommitments`
+ */
+function filterOverwrittenCommitments(commitments) {
+    const seenOverwriteGroups = new Set();
+    const keptCommitments = [];
+    for (let index = commitments.length - 1; index >= 0; index--) {
+        const commitment = commitments[index];
+        const overwriteGroup = OVERWRITTEN_COMMITMENT_GROUP_BY_TYPE.get(commitment.type);
+        if (!overwriteGroup) {
+            keptCommitments.push(commitment);
+            continue;
+        }
+        if (seenOverwriteGroups.has(overwriteGroup)) {
+            continue;
+        }
+        seenOverwriteGroups.add(overwriteGroup);
+        keptCommitments.push(commitment);
+    }
+    return keptCommitments.reverse();
+}
 /**
  * Creates the initial requirements object with the parsed agent name stored in metadata and an optional model override.
  *
@@ -42006,7 +42154,7 @@ function createDefaultAgentName(agentSource) {
 function parseAgentSource(agentSource) {
     const parseResult = parseAgentSourceWithCommitments(agentSource);
     const resolvedAgentName = parseResult.agentName || createDefaultAgentName(agentSource);
-    const personaDescription = extractPersonaDescription(parseResult.commitments);
+    const personaDescription = extractAgentProfileText(parseResult.commitments);
     const initialMessage = extractInitialMessage(parseResult.commitments);
     const parsedProfile = extractParsedAgentProfile(parseResult.commitments);
     ensureMetaFullname(parsedProfile.meta, resolvedAgentName);
@@ -42110,25 +42258,33 @@ const META_COMMITMENT_APPLIERS = {
  */
 const LOCAL_AGENT_REFERENCE_PREFIXES = ['./', '../', '/'];
 /**
- * Builds the combined persona description from PERSONA commitments.
+ * Resolves the public agent profile text from the last GOAL/GOALS commitment,
+ * falling back to the deprecated PERSONA/PERSONAE commitments when no goal exists.
  *
  * @private internal utility of `parseAgentSource`
  */
-function extractPersonaDescription(commitments) {
-    let personaDescription = null;
+function extractAgentProfileText(commitments) {
+    let goalDescription = '';
+    let hasGoalDescription = false;
+    let personaDescription = '';
+    let hasPersonaDescription = false;
     for (const commitment of commitments) {
-        if (commitment.type !== 'PERSONA') {
-            continue;
+        if (commitment.type === 'GOAL' || commitment.type === 'GOALS') {
+            goalDescription = commitment.content;
+            hasGoalDescription = true;
         }
-        if (personaDescription === null) {
-            personaDescription = '';
-        }
-        else {
-            personaDescription += `\n\n${personaDescription}`;
+        if (commitment.type === 'PERSONA' || commitment.type === 'PERSONAE') {
+            personaDescription = commitment.content;
+            hasPersonaDescription = true;
         }
-        personaDescription += commitment.content;
     }
-    return personaDescription;
+    if (hasGoalDescription) {
+        return goalDescription;
+    }
+    if (hasPersonaDescription) {
+        return personaDescription;
+    }
+    return null;
 }
 /**
  * Resolves the last INITIAL MESSAGE commitment, which is the public initial-message value.
@@ -42615,7 +42771,7 @@ async function createAgentModelRequirements(agentSource, modelName, availableMod
  * Selects the best model using the preparePersona function
  * This directly uses preparePersona to ensure DRY principle
  *
- * @param agentSource The agent source to derive persona description from
+ * @param agentSource The agent source to derive effective profile text from
  * @param llmTools LLM tools for preparing persona
  * @returns The name of the best selected model
  *
@@ -42623,9 +42779,9 @@ async function createAgentModelRequirements(agentSource, modelName, availableMod
  */
 async function selectBestModelUsingPersona(agentSource, llmTools) {
     var _a;
-    // Parse agent source to get persona description
+    // Parse agent source to get the effective profile description
     const { agentName, personaDescription } = parseAgentSource(agentSource);
-    // Use agent name as fallback if no persona description is available
+    // Use agent name as fallback if no profile description is available
     const description = personaDescription || agentName || 'AI Agent';
     try {
         // Use preparePersona directly
@@ -44087,7 +44243,27 @@ var findRefactorCandidates$1 = /*#__PURE__*/Object.freeze({
 /**
  * CLI usage text for this script.
  */
-const USAGE = 'Usage: run-codex-prompts [--dry-run] [--agent <agent-name>] [--model <model>] [--context <context-or-file>] [--thinking-level <thinking-level>] [--priority <minimum-priority>] [--allow-credits] [--auto-migrate] [--allow-destructive-auto-migrate] [--no-wait] [--ignore-git-changes] [--no-normalize-line-endings] [--no-push]';
+const USAGE = 'Usage: run-codex-prompts [--dry-run] [--agent <agent-name>] [--model <model>] [--context <context-or-file>] [--test <test-command...>] [--thinking-level <thinking-level>] [--priority <minimum-priority>] [--allow-credits] [--preserve-logs] [--auto-migrate] [--allow-destructive-auto-migrate] [--no-wait] [--ignore-git-changes] [--no-normalize-line-endings] [--auto-push]';
+/**
+ * Top-level flags supported by this command.
+ */
+const KNOWN_OPTION_FLAGS = new Set([
+    '--dry-run',
+    '--agent',
+    '--model',
+    '--context',
+    '--test',
+    '--thinking-level',
+    '--priority',
+    '--allow-credits',
+    '--preserve-logs',
+    '--auto-migrate',
+    '--allow-destructive-auto-migrate',
+    '--no-wait',
+    '--ignore-git-changes',
+    '--no-normalize-line-endings',
+    '--auto-push',
+]);
 /**
  * Parses CLI arguments into runner options.
  */
@@ -44108,6 +44284,8 @@ function parseRunOptions(args) {
     }
     const model = readOptionValue(args, '--model');
     const context = readOptionValue(args, '--context');
+    const hasTestCommandFlag = args.includes('--test');
+    const testCommand = readVariadicOptionValue(args, '--test');
     const hasThinkingLevelFlag = args.includes('--thinking-level');
     const thinkingLevelValue = readOptionValue(args, '--thinking-level');
     const hasPriorityFlag = args.includes('--priority');
@@ -44115,10 +44293,14 @@ function parseRunOptions(args) {
     const ignoreGitChanges = args.includes('--ignore-git-changes');
     const normalizeLineEndings = !args.includes('--no-normalize-line-endings');
     const allowCredits = args.includes('--allow-credits');
+    const preserveLogs = args.includes('--preserve-logs');
     const autoMigrate = args.includes('--auto-migrate');
     const allowDestructiveAutoMigrate = args.includes('--allow-destructive-auto-migrate');
-    const noPush = args.includes('--no-push');
+    const autoPush = args.includes('--auto-push');
     let thinkingLevel;
+    if (hasTestCommandFlag && testCommand === undefined) {
+        exitWithUsageError('Missing value for --test. Use a shell command such as `npm run test` and quote it when it contains top-level CLI flags.');
+    }
     if (hasThinkingLevelFlag && thinkingLevelValue === undefined) {
         exitWithUsageError(`Missing value for --thinking-level. Use one of: ${THINKING_LEVEL_VALUES.join(', ')}.`);
     }
@@ -44137,12 +44319,14 @@ function parseRunOptions(args) {
         ignoreGitChanges,
         normalizeLineEndings,
         allowCredits,
+        preserveLogs,
         autoMigrate,
         allowDestructiveAutoMigrate,
-        noPush,
+        autoPush,
         agentName,
         model,
         context,
+        testCommand,
         thinkingLevel,
         priority,
     };
@@ -44157,6 +44341,28 @@ function readOptionValue(args, flag) {
     const index = args.indexOf(flag);
     return args[index + 1];
 }
+/**
+ * Reads a multi-token shell command value that follows a given flag.
+ */
+function readVariadicOptionValue(args, flag) {
+    if (!args.includes(flag)) {
+        return undefined;
+    }
+    const index = args.indexOf(flag);
+    const valueParts = [];
+    for (let i = index + 1; i < args.length; i++) {
+        const valuePart = args[i];
+        if (valuePart === undefined) {
+            continue;
+        }
+        if (KNOWN_OPTION_FLAGS.has(valuePart)) {
+            break;
+        }
+        valueParts.push(valuePart);
+    }
+    const normalizedValue = valueParts.join(' ').trim();
+    return normalizedValue === '' ? undefined : normalizedValue;
+}
 /**
  * Parses and validates the minimum prompt priority.
  */
@@ -44182,6 +44388,21 @@ function exitWithUsageError(message) {
     process.exit(1);
 }
 
+/**
+ * Appends optional coding context to a runner prompt.
+ */
+function appendCoderContext(prompt, context) {
+    const normalizedContext = context === null || context === void 0 ? void 0 : context.trim();
+    if (!normalizedContext) {
+        return prompt;
+    }
+    const normalizedPrompt = prompt.trimEnd();
+    if (normalizedPrompt === '') {
+        return normalizedContext;
+    }
+    return `${normalizedPrompt}\n\n${normalizedContext}`;
+}
+
 /**
  * Refresh interval for the progress header in milliseconds.
  */
@@ -44193,7 +44414,7 @@ const PROGRESS_HEADER_RESERVED_LINES = 1;
 /**
  * Calendar formats used when displaying the estimated completion time.
  */
-const ESTIMATED_DONE_CALENDAR_FORMATS = {
+const ESTIMATED_DONE_CALENDAR_FORMATS$1 = {
     sameDay: '[Today] h:mm',
     nextDay: '[Tomorrow] h:mm',
     nextWeek: 'dddd h:mm',
@@ -44292,15 +44513,15 @@ function buildProgressSnapshot(stats, startTime, initialDone) {
     const sessionTotal = sessionDone + stats.forAgent;
     const percentage = totalPrompts > 0 ? Math.round((completedPrompts / totalPrompts) * 100) : 0;
     const elapsedDuration = moment.duration(moment().diff(startTime));
-    const elapsedText = formatDurationBrief(elapsedDuration);
+    const elapsedText = formatDurationBrief$1(elapsedDuration);
     let estimatedTotalText = '—';
     let estimatedLabel = 'unknown';
     if (totalPrompts > 0 && completedPrompts > 0) {
         const estimatedTotalMs = (elapsedDuration.asMilliseconds() * totalPrompts) / completedPrompts;
         const estimatedTotalDuration = moment.duration(estimatedTotalMs);
         const estimatedCompletion = startTime.clone().add(estimatedTotalDuration);
-        estimatedTotalText = formatDurationBrief(estimatedTotalDuration);
-        estimatedLabel = estimatedCompletion.calendar(null, ESTIMATED_DONE_CALENDAR_FORMATS);
+        estimatedTotalText = formatDurationBrief$1(estimatedTotalDuration);
+        estimatedLabel = estimatedCompletion.calendar(null, ESTIMATED_DONE_CALENDAR_FORMATS$1);
     }
     return {
         totalPrompts,
@@ -44316,7 +44537,7 @@ function buildProgressSnapshot(stats, startTime, initialDone) {
 /**
  * Formats a duration into a compact string such as "3h 12m" or "45s".
  */
-function formatDurationBrief(duration) {
+function formatDurationBrief$1(duration) {
     const totalSeconds = Math.max(0, Math.round(duration.asSeconds()));
     const hours = Math.floor(totalSeconds / 3600);
     const minutes = Math.floor((totalSeconds % 3600) / 60);
@@ -44337,21 +44558,6 @@ function formatDurationBrief(duration) {
     return parts.join(' ');
 }
 
-/**
- * Appends optional coding context to a runner prompt.
- */
-function appendCoderContext(prompt, context) {
-    const normalizedContext = context === null || context === void 0 ? void 0 : context.trim();
-    if (!normalizedContext) {
-        return prompt;
-    }
-    const normalizedPrompt = prompt.trimEnd();
-    if (normalizedPrompt === '') {
-        return normalizedContext;
-    }
-    return `${normalizedPrompt}\n\n${normalizedContext}`;
-}
-
 /**
  * Git commands used to list changed and untracked files in the working tree.
  */
@@ -44607,6 +44813,91 @@ async function resolveCoderContext(contextReference, currentWorkingDirectory) {
     return readFile(contextPath, 'utf-8');
 }
 
+/**
+ * Builds the temporary live runtime log path for one prompt script and its sibling test script.
+ */
+function buildScriptLogPath(scriptPath) {
+    const basePath = scriptPath.replace(/\.test\.sh$/iu, '').replace(/\.sh$/iu, '');
+    return `${basePath}.log.txt`;
+}
+
+/**
+ * Runs one prompt-processing round with a dedicated temporary runtime log file and optionally defers cleanup to the round tracker.
+ */
+async function withPromptRuntimeLog(scriptPath, handler, promptRoundArtifacts) {
+    const logPath = buildScriptLogPath(scriptPath);
+    await unlink(logPath).catch(() => undefined);
+    promptRoundArtifacts === null || promptRoundArtifacts === void 0 ? void 0 : promptRoundArtifacts.track(logPath, 'runtime-log');
+    try {
+        return await handler(logPath);
+    }
+    finally {
+        if (!promptRoundArtifacts) {
+            await unlink(logPath).catch(() => undefined);
+        }
+    }
+}
+
+/**
+ * Shared artifact kinds preserved for debugging when a prompt round fails.
+ */
+const FAILURE_PRESERVED_ARTIFACT_KINDS = new Set(['runner-script', 'runtime-log']);
+/**
+ * Shared artifact kinds preserved after a successful prompt round when explicitly requested.
+ */
+const SUCCESS_PRESERVED_ARTIFACT_KINDS = new Set(['runner-script', 'runtime-log']);
+/**
+ * Empty preserved-artifact set used for successful rounds without `--preserve-logs`.
+ */
+const NO_PRESERVED_ARTIFACT_KINDS = new Set();
+/**
+ * Tracks temporary prompt-round artifacts and deletes only those not preserved for the final round outcome.
+ */
+class PromptRoundArtifacts {
+    /**
+     * Creates a new prompt-round artifact tracker.
+     */
+    constructor(preservedArtifactKindsByOutcome) {
+        this.preservedArtifactKindsByOutcome = preservedArtifactKindsByOutcome;
+        this.trackedArtifacts = new Map();
+    }
+    /**
+     * Registers one temporary artifact for round-final cleanup.
+     */
+    track(path, kind) {
+        this.trackedArtifacts.set(path, kind);
+    }
+    /**
+     * Cleans up all tracked artifacts that should not survive the final round outcome.
+     */
+    async cleanup(outcome) {
+        const preservedArtifactKinds = this.preservedArtifactKindsByOutcome[outcome];
+        const trackedArtifacts = [...this.trackedArtifacts.entries()];
+        this.trackedArtifacts.clear();
+        await Promise.all(trackedArtifacts.map(async ([path, kind]) => {
+            if (preservedArtifactKinds.has(kind)) {
+                return;
+            }
+            await unlink(path).catch(() => undefined);
+        }));
+    }
+}
+/**
+ * Creates the default artifact-retention policy used by `ptbk coder run`.
+ */
+function createCoderRunPromptRoundArtifacts(isPreserveLogs) {
+    return new PromptRoundArtifacts({
+        success: isPreserveLogs ? SUCCESS_PRESERVED_ARTIFACT_KINDS : NO_PRESERVED_ARTIFACT_KINDS,
+        failure: FAILURE_PRESERVED_ARTIFACT_KINDS,
+    });
+}
+/**
+ * Derives the tracked artifact kind from one temporary shell path.
+ */
+function getPromptRoundArtifactKindFromScriptPath(scriptPath) {
+    return scriptPath.toLowerCase().endsWith('.test.sh') ? 'test-script' : 'runner-script';
+}
+
 /**
  * Waits for the user to press Enter before continuing.
  */
@@ -44621,7 +44912,7 @@ async function waitForEnter(prompt) {
 }
 
 /**
- * Constant for pause state.
+ * Current pause state.
  */
 let pauseState = 'RUNNING';
 /**
@@ -44658,17 +44949,48 @@ function listenForPause() {
 }
 /**
  * If the execution is paused, it will wait until it is resumed.
+ *
+ * @param options.silent - When `true`, suppresses console output (used when the terminal UI handles display).
+ * @param options.onPaused - Callback invoked when entering the PAUSED state.
+ * @param options.onResumed - Callback invoked when leaving the PAUSED state.
  */
-async function checkPause() {
+async function checkPause(options) {
+    var _a, _b;
     if (pauseState === 'PAUSING') {
         pauseState = 'PAUSED';
-        console.log(colors.bgWhite.black('Paused') + colors.gray(' (Press "p" to resume)'));
+        if (!(options === null || options === void 0 ? void 0 : options.silent)) {
+            console.log(colors.bgWhite.black('Paused') + colors.gray(' (Press "p" to resume)'));
+        }
+        (_a = options === null || options === void 0 ? void 0 : options.onPaused) === null || _a === void 0 ? void 0 : _a.call(options);
         while (pauseState === 'PAUSED') {
             await new Promise((resolve) => setTimeout(resolve, 100));
         }
-        console.log(colors.green('Resuming...'));
+        (_b = options === null || options === void 0 ? void 0 : options.onResumed) === null || _b === void 0 ? void 0 : _b.call(options);
+        if (!(options === null || options === void 0 ? void 0 : options.silent)) {
+            console.log(colors.green('Resuming...'));
+        }
     }
 }
+/**
+ * Returns the current pause state for external consumers such as the terminal UI.
+ */
+function getPauseState() {
+    return pauseState;
+}
+/**
+ * Requests a pause from an external controller (e.g. the Ink UI).
+ */
+function requestPause() {
+    if (pauseState === 'RUNNING') {
+        pauseState = 'PAUSING';
+    }
+}
+/**
+ * Resumes execution from an external controller after a pause.
+ */
+function requestResume() {
+    pauseState = 'RUNNING';
+}
 
 /**
  * Environment variable that configures the name used for agent commits.
@@ -45013,7 +45335,7 @@ function stringifyUnknownError$1(error) {
 
 /**
  * Commits staged changes with the provided message using the dedicated coding-agent identity when configured,
- * otherwise falls back to the default Git configuration.
+ * otherwise falls back to the default Git configuration. Remote pushing is opt-in via `options.autoPush`.
  */
 async function commitChanges(message, options) {
     const projectPath = process.cwd();
@@ -45033,7 +45355,7 @@ async function commitChanges(message, options) {
             cwd: projectPath,
             env: agentEnv,
         });
-        if (!(options === null || options === void 0 ? void 0 : options.noPush)) {
+        if (options === null || options === void 0 ? void 0 : options.autoPush) {
             await pushCommittedChanges(projectPath, agentEnv);
         }
     }
@@ -46626,6 +46948,19 @@ function formatUsagePrice(usage) {
     return `${prefix}$${price.toFixed(2)}`;
 }
 
+/**
+ * Formats optional attempt metadata stored in prompt status lines.
+ */
+function formatPromptAttemptMetadata(status, attemptCount) {
+    if (attemptCount <= 1) {
+        return '';
+    }
+    if (status === 'done') {
+        return `(${attemptCount} attempts) `;
+    }
+    return `(failed after ${attemptCount} attempts) `;
+}
+
 /**
  * Formats runner details for prompt status lines.
  */
@@ -46645,7 +46980,7 @@ function formatRunnerSignature(runnerName, modelName) {
 /**
  * Marks a prompt section as done and records usage pricing and runner details.
  */
-function markPromptDone(file, section, usage, runnerName, modelName, promptExecutionStartedDate) {
+function markPromptDone(file, section, usage, runnerName, modelName, promptExecutionStartedDate, attemptCount = 1) {
     if (section.statusLineIndex === undefined) {
         throw new Error(`Prompt ${section.index + 1} in ${file.name} does not have a status line.`);
     }
@@ -46655,16 +46990,17 @@ function markPromptDone(file, section, usage, runnerName, modelName, promptExecu
     }
     const priceString = formatUsagePrice(usage);
     const runnerSignature = formatRunnerSignature(runnerName, modelName);
+    const attemptMetadata = formatPromptAttemptMetadata('done', attemptCount);
     const duration = moment().diff(promptExecutionStartedDate);
     const durationString = moment.duration(duration).humanize();
     // Replace "[ ]" or "[ ] !!..." with "[x] $price duration by runner"
-    file.lines[section.statusLineIndex] = line.replace(/\[\s*\]\s*!*\s*$/, `[x] ${priceString} ${durationString} by ${runnerSignature}`);
+    file.lines[section.statusLineIndex] = line.replace(/\[\s*\]\s*!*\s*$/, `[x] ${attemptMetadata}${priceString} ${durationString} by ${runnerSignature}`);
 }
 
 /**
  * Marks a prompt section as failed and records runner details.
  */
-function markPromptFailed(file, section, runnerName, modelName, promptExecutionStartedDate) {
+function markPromptFailed(file, section, runnerName, modelName, promptExecutionStartedDate, attemptCount = 1) {
     if (section.statusLineIndex === undefined) {
         throw new Error(`Prompt ${section.index + 1} in ${file.name} does not have a status line.`);
     }
@@ -46673,9 +47009,11 @@ function markPromptFailed(file, section, runnerName, modelName, promptExecutionS
         throw new Error(`Prompt ${section.index + 1} in ${file.name} points to a missing status line.`);
     }
     const runnerSignature = formatRunnerSignature(runnerName, modelName);
+    const attemptMetadata = formatPromptAttemptMetadata('failed', attemptCount);
     const duration = moment().diff(promptExecutionStartedDate);
     const durationString = moment.duration(duration).humanize();
-    file.lines[section.statusLineIndex] = line.replace(/\[\s*\]\s*!*\s*$/, `[!] failed after ${durationString} by ${runnerSignature}`);
+    const failureDetails = attemptMetadata === '' ? `failed after ${durationString} by ${runnerSignature}` : `${attemptMetadata}${durationString} by ${runnerSignature}`;
+    file.lines[section.statusLineIndex] = line.replace(/\[\s*\]\s*!*\s*$/, `[!] ${failureDetails}`);
 }
 
 /**
@@ -46792,6 +47130,20 @@ async function waitForPromptStart(file, section, isFirstPrompt) {
     await waitForEnter(colors.bgWhite(`Press Enter to start the ${label}...`));
 }
 
+/**
+ * Formats one unknown error-like value into readable text for logs and feedback.
+ */
+function formatUnknownErrorDetails(error) {
+    if (error instanceof Error) {
+        return error.stack || error.message;
+    }
+    if (typeof error === 'string') {
+        return error;
+    }
+    const serializedError = JSON.stringify(error, null, 2);
+    return serializedError !== null && serializedError !== void 0 ? serializedError : String(error);
+}
+
 /**
  * Writes the failure details for a single prompt run next to the prompt markdown file.
  */
@@ -46799,7 +47151,7 @@ async function writePromptErrorLog(options) {
     const logPath = buildPromptErrorLogPath(options.file.path);
     const label = buildPromptLabelForDisplay(options.file, options.section);
     const summary = buildPromptSummary(options.file, options.section);
-    const details = buildErrorDetails(options.error);
+    const details = formatUnknownErrorDetails(options.error);
     const modelSuffix = options.modelName ? ` (${options.modelName})` : '';
     const runnerLabel = `${options.runnerName || 'unknown'}${modelSuffix}`;
     const log = [
@@ -46826,18 +47178,6 @@ function buildPromptErrorLogPath(promptPath) {
     }
     return `${promptPath}.error.log`;
 }
-/**
- * Formats unknown error values into a readable log payload.
- */
-function buildErrorDetails(error) {
-    if (error instanceof Error) {
-        return error.stack || error.message;
-    }
-    if (typeof error === 'string') {
-        return error;
-    }
-    return JSON.stringify(error, null, 2);
-}
 
 /**
  * Writes updated prompt file content to disk.
@@ -46861,25 +47201,186 @@ function toPosixPath(filePath) {
 }
 
 /**
- * Creates a temporary script file, runs a handler, and ensures cleanup.
+ * Environment variable read by the shell wrapper to tee live output into the temporary runtime log file.
+ */
+const PTBK_CODER_LOG_FILE_ENV_NAME = 'PTBK_CODER_LOG_FILE';
+/**
+ * Small bash wrapper that preserves stdout/stderr streams while teeing both into the runtime log file.
+ */
+const LOGGED_BASH_WRAPPER_COMMAND = `
+if [ -n "\${${PTBK_CODER_LOG_FILE_ENV_NAME}:-}" ]; then
+    exec > >(tee -a "\$${PTBK_CODER_LOG_FILE_ENV_NAME}") 2> >(tee -a "\$${PTBK_CODER_LOG_FILE_ENV_NAME}" >&2)
+fi
+bash "$1"
+`.trim();
+/**
+ * Shapes one bash invocation that optionally mirrors live script output into a temporary log file.
+ */
+function buildLoggedBashExecution(scriptPath, logPath) {
+    return {
+        args: ['-lc', LOGGED_BASH_WRAPPER_COMMAND, 'ptbk-coder-temp-script', toPosixPath(scriptPath)],
+        env: logPath ? { [PTBK_CODER_LOG_FILE_ENV_NAME]: toPosixPath(logPath) } : undefined,
+    };
+}
+/**
+ * Appends one execution-start section with the raw script input before the shell begins producing output.
+ */
+async function appendScriptExecutionLogStart({ scriptPath, scriptContent, logPath, }) {
+    if (!logPath) {
+        return;
+    }
+    await mkdir(dirname(logPath), { recursive: true });
+    const scriptKind = describeTempScriptKind(scriptPath);
+    const normalizedInput = scriptContent.replace(/\r\n/g, '\n').trimEnd();
+    const logSection = [
+        `=== ${scriptKind} started at ${new Date().toISOString()} ===`,
+        `Script path: ${toPosixPath(scriptPath)}`,
+        '',
+        '--- raw input ---',
+        normalizedInput,
+        '',
+        '--- raw output ---',
+        '',
+    ].join('\n');
+    await appendFile(logPath, `${logSection}\n`, 'utf-8');
+}
+/**
+ * Appends one execution-finish section after the shell settles.
+ */
+async function appendScriptExecutionLogFinish({ scriptPath, logPath, status, details, }) {
+    if (!logPath) {
+        return;
+    }
+    const scriptKind = describeTempScriptKind(scriptPath);
+    const logLines = [
+        '',
+        `=== ${scriptKind} finished at ${new Date().toISOString()} ===`,
+        `Status: ${status}`,
+    ];
+    if (details !== undefined) {
+        logLines.push('');
+        logLines.push('--- details ---');
+        logLines.push(formatUnknownErrorDetails(details));
+    }
+    logLines.push('');
+    await appendFile(logPath, `${logLines.join('\n')}\n`, 'utf-8');
+}
+/**
+ * Distinguishes prompt-runner and verification temp shells in the shared runtime log.
+ */
+function describeTempScriptKind(scriptPath) {
+    return scriptPath.toLowerCase().endsWith('.test.sh') ? 'test shell' : 'runner shell';
+}
+
+/**
+ * Runs one temporary bash script, optionally mirroring its raw input/output into a live runtime log file.
+ */
+async function runBashScriptWithOutput(options) {
+    await appendScriptExecutionLogStart(options);
+    const bashExecution = buildLoggedBashExecution(options.scriptPath, options.logPath);
+    const scriptPathPosix = toPosixPath(options.scriptPath);
+    return await new Promise((resolve, reject) => {
+        const commandProcess = spawn('bash', bashExecution.args, {
+            env: bashExecution.env ? { ...process.env, ...bashExecution.env } : process.env,
+        });
+        let output = '';
+        let settled = false;
+        let isSettling = false;
+        /**
+         * Appends the final log footer before settling.
+         */
+        const finishLog = async (status, details) => {
+            await appendScriptExecutionLogFinish({
+                scriptPath: options.scriptPath,
+                logPath: options.logPath,
+                status,
+                details,
+            });
+        };
+        /**
+         * Ensures the promise settles only once.
+         */
+        const settleOnce = (handler) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            handler();
+        };
+        /**
+         * Appends the final log footer and settles the promise exactly once.
+         */
+        const settleWithLog = (status, handler, details) => {
+            if (isSettling || settled) {
+                return;
+            }
+            isSettling = true;
+            void finishLog(status, details).finally(() => {
+                settleOnce(handler);
+            });
+        };
+        commandProcess.stdout.on('data', (stdout) => {
+            const chunk = stdout.toString();
+            output += chunk;
+            console.info(chunk);
+        });
+        commandProcess.stderr.on('data', (stderr) => {
+            const chunk = stderr.toString();
+            output += chunk;
+            if (chunk.trim()) {
+                console.warn(chunk);
+            }
+        });
+        /**
+         * Handles process exit and resolves or rejects accordingly.
+         */
+        const handleExit = (code) => {
+            if (code === 0) {
+                settleWithLog('succeeded', () => resolve(spaceTrim$1(output)));
+                return;
+            }
+            const failure = new Error(spaceTrim$1(output) || `Command "bash ${scriptPathPosix}" exited with code ${code}`);
+            settleWithLog(`failed with exit code ${code !== null && code !== void 0 ? code : 'unknown'}`, () => reject(failure), failure);
+        };
+        commandProcess.on('close', handleExit);
+        commandProcess.on('exit', handleExit);
+        commandProcess.on('disconnect', () => {
+            const failure = new Error(`Command "bash ${scriptPathPosix}" disconnected`);
+            settleWithLog('failed after disconnect', () => reject(failure), failure);
+        });
+        commandProcess.on('error', (error) => {
+            const failure = new Error(`Command "bash ${scriptPathPosix}" failed: ${error.message}`);
+            settleWithLog('failed before completion', () => reject(failure), failure);
+        });
+    });
+}
+
+/**
+ * Creates a temporary script file, runs a handler, and either cleans it up immediately or defers cleanup to the round tracker.
  */
 async function withTempScript(options, handler) {
-    const { scriptPath, scriptContent } = options;
+    const { scriptPath, scriptContent, promptRoundArtifacts } = options;
     await mkdir(dirname$1(scriptPath), { recursive: true });
     await writeFile(scriptPath, scriptContent, 'utf-8');
-    const result = await handler(scriptPath);
-    await unlink(scriptPath).catch(() => undefined);
-    return result;
+    promptRoundArtifacts === null || promptRoundArtifacts === void 0 ? void 0 : promptRoundArtifacts.track(scriptPath, getPromptRoundArtifactKindFromScriptPath(scriptPath));
+    try {
+        return await handler(scriptPath);
+    }
+    finally {
+        if (!promptRoundArtifacts) {
+            await unlink(scriptPath).catch(() => undefined);
+        }
+    }
 }
 
 /**
- * Creates a temporary script file, runs it, captures output, and then deletes it.
+ * Creates a temporary script file, runs it, captures output, and cleans it up immediately unless a round tracker defers that cleanup.
  */
 async function $runGoScriptWithOutput(options) {
     return await withTempScript(options, async (scriptPath) => {
-        return await $execCommand({
-            command: `bash "${toPosixPath(scriptPath)}"`,
-            isVerbose: true, // <- Note: Proxy the raw command output to the console
+        return await runBashScriptWithOutput({
+            ...options,
+            scriptPath,
         });
     });
 }
@@ -46975,6 +47476,8 @@ class ClaudeCodeRunner {
         const output = await $runGoScriptWithOutput({
             scriptPath: options.scriptPath,
             scriptContent,
+            logPath: options.logPath,
+            promptRoundArtifacts: options.promptRoundArtifacts,
         });
         const usage = parseClaudeCodeJsonOutput(output);
         return { usage };
@@ -46982,13 +47485,13 @@ class ClaudeCodeRunner {
 }
 
 /**
- * Creates a temporary script file, runs it, and then deletes it.
+ * Creates a temporary script file, runs it, and cleans it up immediately unless a round tracker defers that cleanup.
  */
 async function $runGoScript(options) {
     await withTempScript(options, async (scriptPath) => {
-        await $execCommand({
-            command: `bash "${toPosixPath(scriptPath)}"`,
-            isVerbose: true, // <- Note: Proxy the raw command output to the console
+        await runBashScriptWithOutput({
+            ...options,
+            scriptPath,
         });
     });
 }
@@ -47037,6 +47540,8 @@ class ClineRunner {
             await $runGoScript({
                 scriptPath: options.scriptPath,
                 scriptContent,
+                logPath: options.logPath,
+                promptRoundArtifacts: options.promptRoundArtifacts,
             });
             return { usage: UNCERTAIN_USAGE };
         }
@@ -47160,6 +47665,8 @@ class GeminiRunner {
         const output = await $runGoScriptWithOutput({
             scriptPath: options.scriptPath,
             scriptContent,
+            logPath: options.logPath,
+            promptRoundArtifacts: options.promptRoundArtifacts,
         });
         const usage = parseGeminiUsageFromOutput(output, options.prompt, this.options.model);
         return { usage };
@@ -47215,6 +47722,8 @@ class GitHubCopilotRunner {
         await $runGoScript({
             scriptPath: options.scriptPath,
             scriptContent,
+            logPath: options.logPath,
+            promptRoundArtifacts: options.promptRoundArtifacts,
         });
         return { usage: UNCERTAIN_USAGE };
     }
@@ -47251,14 +47760,30 @@ function buildCommandFailureMessage(scriptPathPosix, code, fullOutput) {
 async function runScriptUntilMarkerIdle(options) {
     const { scriptPath, completionLineMatcher, idleTimeoutMs } = options;
     const scriptPathPosix = toPosixPath(scriptPath);
+    await appendScriptExecutionLogStart(options);
+    const bashExecution = buildLoggedBashExecution(scriptPath, options.logPath);
     return await new Promise((resolve, reject) => {
-        const commandProcess = spawn('bash', [scriptPathPosix], { env: process.env });
+        const commandProcess = spawn('bash', bashExecution.args, {
+            env: bashExecution.env ? { ...process.env, ...bashExecution.env } : process.env,
+        });
         let stdoutBuffer = '';
         let stderrBuffer = '';
         let fullOutput = '';
         let markerSeen = false;
         let idleTimer;
         let settled = false;
+        let isSettling = false;
+        /**
+         * Appends the final log footer before settling.
+         */
+        const finishLog = async (status, details) => {
+            await appendScriptExecutionLogFinish({
+                scriptPath,
+                logPath: options.logPath,
+                status,
+                details,
+            });
+        };
         /**
          * Ensures the promise settles only once.
          */
@@ -47273,6 +47798,18 @@ async function runScriptUntilMarkerIdle(options) {
             }
             handler();
         };
+        /**
+         * Appends the final log footer and settles the promise exactly once.
+         */
+        const settleWithLog = (status, handler, details) => {
+            if (isSettling || settled) {
+                return;
+            }
+            isSettling = true;
+            void finishLog(status, details).finally(() => {
+                settleOnce(handler);
+            });
+        };
         /**
          * Resets the idle timer that triggers termination after inactivity.
          */
@@ -47282,7 +47819,7 @@ async function runScriptUntilMarkerIdle(options) {
             }
             idleTimer = setTimeout(() => {
                 commandProcess.kill();
-                settleOnce(() => resolve(fullOutput));
+                settleWithLog('completed after idle timeout', () => resolve(fullOutput));
             }, idleTimeoutMs);
         };
         /**
@@ -47336,41 +47873,43 @@ async function runScriptUntilMarkerIdle(options) {
          * Handles process exit and resolves or rejects accordingly.
          */
         const handleExit = (code) => {
-            settleOnce(() => {
-                if (code === 0 || markerSeen) {
+            const failure = code === 0 || markerSeen ? undefined : new Error(buildCommandFailureMessage(scriptPathPosix, code, fullOutput));
+            const status = failure ? `failed with exit code ${code !== null && code !== void 0 ? code : 'unknown'}` : 'succeeded';
+            settleWithLog(status, () => {
+                if (!failure) {
                     resolve(fullOutput);
                     return;
                 }
-                reject(new Error(buildCommandFailureMessage(scriptPathPosix, code, fullOutput)));
+                reject(failure);
             });
         };
         commandProcess.on('close', handleExit);
         commandProcess.on('exit', handleExit);
         commandProcess.on('disconnect', () => {
-            settleOnce(() => {
-                reject(new Error(buildCommandFailureMessage(scriptPathPosix, null, fullOutput)));
-            });
+            const failure = new Error(buildCommandFailureMessage(scriptPathPosix, null, fullOutput));
+            settleWithLog('failed after disconnect', () => reject(failure), failure);
         });
         commandProcess.on('error', (error) => {
-            settleOnce(() => {
-                const outputSnippet = createOutputSnippet(fullOutput);
-                const details = outputSnippet ? `\n\n${outputSnippet}` : '';
-                reject(new Error(`Command "bash ${scriptPathPosix}" failed: ${error.message}${details}`));
-            });
+            const outputSnippet = createOutputSnippet(fullOutput);
+            const details = outputSnippet ? `\n\n${outputSnippet}` : '';
+            const failure = new Error(`Command "bash ${scriptPathPosix}" failed: ${error.message}${details}`);
+            settleWithLog('failed before completion', () => reject(failure), failure);
         });
     });
 }
 
 /**
- * Creates a temporary script file, runs it, waits for a completion marker and idle time, and then deletes it.
+ * Creates a temporary script file, runs it, waits for a completion marker and idle time, and defers cleanup when a round tracker is provided.
  * Returns the captured output for post-processing.
  */
 async function $runGoScriptUntilMarkerIdle(options) {
     return await withTempScript(options, async (scriptPath) => {
         return await runScriptUntilMarkerIdle({
             scriptPath,
+            scriptContent: options.scriptContent,
             completionLineMatcher: options.completionLineMatcher,
             idleTimeoutMs: options.idleTimeoutMs,
+            logPath: options.logPath,
         });
     });
 }
@@ -47748,6 +48287,8 @@ class OpenAiCodexRunner {
                     scriptContent,
                     completionLineMatcher: CODEX_COMPLETION_LINE,
                     idleTimeoutMs: CODEX_COMPLETION_IDLE_MS,
+                    logPath: options.logPath,
+                    promptRoundArtifacts: options.promptRoundArtifacts,
                 });
                 this.rateLimitBackoff.reset();
                 return { usage: buildCodexUsageFromOutput(output, this.options.model) };
@@ -47881,6 +48422,8 @@ class OpencodeRunner {
             output = await $runGoScriptWithOutput({
                 scriptPath: options.scriptPath,
                 scriptContent,
+                logPath: options.logPath,
+                promptRoundArtifacts: options.promptRoundArtifacts,
             });
         }
         catch (error) {
@@ -47896,6 +48439,653 @@ class OpencodeRunner {
     }
 }
 
+/**
+ * Runs the configured verification command inside the project root and returns its output.
+ */
+async function runPromptTestCommand(options) {
+    const projectPath = toPosixPath(options.projectPath);
+    return await $runGoScriptWithOutput({
+        scriptPath: options.scriptPath,
+        scriptContent: spaceTrim(`
+            cd "${projectPath}"
+            ${options.command}
+        `),
+        logPath: options.logPath,
+    });
+}
+
+/**
+ * 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;
+/**
+ * Runs one coding prompt and, when configured, verifies it with a shell command that can feed failures back.
+ */
+async function runPromptWithTestFeedback(options) {
+    var _a, _b, _c, _d;
+    const normalizedTestCommand = (_a = options.testCommand) === null || _a === void 0 ? void 0 : _a.trim();
+    if (!normalizedTestCommand) {
+        (_b = options.onAttemptStarted) === null || _b === void 0 ? void 0 : _b.call(options, 1);
+        const result = await options.runner.runPrompt({
+            prompt: options.prompt,
+            scriptPath: options.scriptPath,
+            projectPath: options.projectPath,
+            logPath: options.logPath,
+            promptRoundArtifacts: options.promptRoundArtifacts,
+        });
+        return { ...result, attemptCount: 1 };
+    }
+    const runPromptTestCommandExecutor = (_c = options.runPromptTestCommandExecutor) !== null && _c !== void 0 ? _c : runPromptTestCommand;
+    let promptForCurrentAttempt = options.prompt;
+    for (let attemptCount = 1; attemptCount <= MAX_PROMPT_TEST_ATTEMPTS; attemptCount++) {
+        (_d = options.onAttemptStarted) === null || _d === void 0 ? void 0 : _d.call(options, attemptCount);
+        const result = await options.runner.runPrompt({
+            prompt: promptForCurrentAttempt,
+            scriptPath: options.scriptPath,
+            projectPath: options.projectPath,
+            logPath: options.logPath,
+            promptRoundArtifacts: options.promptRoundArtifacts,
+        });
+        console.info(colors.gray(`Running verification command after attempt #${attemptCount}: ${normalizedTestCommand}`));
+        try {
+            await runPromptTestCommandExecutor({
+                command: normalizedTestCommand,
+                projectPath: options.projectPath,
+                scriptPath: buildPromptTestScriptPath(options.scriptPath),
+                logPath: options.logPath,
+            });
+            return { ...result, attemptCount };
+        }
+        catch (error) {
+            const fullVerificationOutput = formatUnknownErrorDetails(error);
+            const feedbackVerificationOutput = limitVerificationOutputForFeedback(fullVerificationOutput);
+            if (attemptCount >= MAX_PROMPT_TEST_ATTEMPTS) {
+                console.error(colors.red(`Verification failed for ${options.promptLabel} after ${attemptCount} attempts.`));
+                throw new Error(buildFinalVerificationFailureMessage({
+                    promptLabel: options.promptLabel,
+                    testCommand: normalizedTestCommand,
+                    attemptCount,
+                    verificationOutput: fullVerificationOutput,
+                }));
+            }
+            console.warn(colors.yellow(`Verification failed for ${options.promptLabel} on attempt #${attemptCount}. Sending feedback to ${options.runner.name} and retrying...`));
+            promptForCurrentAttempt = appendCoderContext(options.prompt, buildVerificationFeedback({
+                testCommand: normalizedTestCommand,
+                failedAttemptCount: attemptCount,
+                verificationOutput: feedbackVerificationOutput,
+            }));
+        }
+    }
+    throw new Error('Unexpected prompt verification state.');
+}
+/**
+ * Builds one feedback block appended to the next coding attempt after tests fail.
+ */
+function buildVerificationFeedback({ testCommand, failedAttemptCount, verificationOutput, }) {
+    const nextAttemptCount = failedAttemptCount + 1;
+    return spaceTrim((block) => `
+            The previous implementation did not pass the required verification command.
+
+            ## Automated verification feedback
+            - Retry attempt: ${nextAttemptCount} of ${MAX_PROMPT_TEST_ATTEMPTS}
+            - Verification command: \`${testCommand}\`
+            - Update the current implementation so the verification command passes without breaking the original task requirements.
+
+            ### Verification output
+            \`\`\`
+            ${block(verificationOutput)}
+            \`\`\`
+        `);
+}
+/**
+ * Builds the final error message written when verification still fails after all retries.
+ */
+function buildFinalVerificationFailureMessage({ promptLabel, testCommand, attemptCount, verificationOutput, }) {
+    return spaceTrim((block) => `
+            Verification command \`${testCommand}\` failed for \`${promptLabel}\` after ${attemptCount} attempts.
+
+            ### Verification output
+            \`\`\`
+            ${block(verificationOutput)}
+            \`\`\`
+        `);
+}
+/**
+ * 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.
+ */
+function buildPromptTestScriptPath(scriptPath) {
+    if (scriptPath.toLowerCase().endsWith('.sh')) {
+        return `${scriptPath.slice(0, -3)}.test.sh`;
+    }
+    return `${scriptPath}.test.sh`;
+}
+
+/**
+ * Maximum number of agent output lines kept in the scrolling output area.
+ *
+ * @private internal constant of coder run UI
+ */
+const MAX_AGENT_OUTPUT_LINES = 12;
+/**
+ * Calendar formats used when displaying the estimated completion time.
+ *
+ * @private internal constant of coder run UI
+ */
+const ESTIMATED_DONE_CALENDAR_FORMATS = {
+    sameDay: '[Today] h:mm',
+    nextDay: '[Tomorrow] h:mm',
+    nextWeek: 'dddd h:mm',
+    lastDay: '[Yesterday] h:mm',
+    lastWeek: 'dddd h:mm',
+    sameElse: 'MMM D h:mm',
+};
+/**
+ * Reactive state manager for the coder run terminal UI.
+ *
+ * Holds all data the Ink components need and emits `'change'` events
+ * whenever any property is updated so the UI can re-render.
+ *
+ * @private internal utility of coder run UI
+ */
+class CoderRunUiState extends EventEmitter {
+    constructor(startTime) {
+        super();
+        this.config = { agentName: '', priority: 0 };
+        this.currentPromptLabel = '';
+        this.currentAttempt = 1;
+        this.maxAttempts = 3;
+        this.agentOutputLines = [];
+        this.phase = 'initializing';
+        this.statusMessage = 'Initializing...';
+        this.errors = [];
+        this.stats = { done: 0, forAgent: 0, belowMinimumPriority: 0, toBeWritten: 0 };
+        /**
+         * Total milliseconds the timer was paused/waiting (excluded from elapsed display).
+         */
+        this.pausedMs = 0;
+        this.startTime = startTime;
+        // Timer starts paused — callers call `resumeTimer()` when actual work begins.
+        this.pausedSince = startTime.clone();
+    }
+    /**
+     * Pauses the elapsed timer (e.g. while waiting for user input or paused state).
+     */
+    pauseTimer() {
+        if (this.pausedSince === undefined) {
+            this.pausedSince = moment();
+        }
+    }
+    /**
+     * Resumes the elapsed timer after a pause.
+     */
+    resumeTimer() {
+        if (this.pausedSince !== undefined) {
+            this.pausedMs += moment().diff(this.pausedSince);
+            this.pausedSince = undefined;
+        }
+    }
+    /**
+     * Replaces the configuration shown in the UI header.
+     */
+    setConfig(config) {
+        this.config = config;
+        this.emitChange();
+    }
+    /**
+     * Feeds new prompt statistics from the main loop so the progress bar updates.
+     */
+    updateProgress(stats) {
+        if (this.initialDone === undefined && (stats.done > 0 || stats.forAgent > 0 || stats.toBeWritten > 0)) {
+            this.initialDone = stats.done;
+        }
+        this.stats = stats;
+        this.emitChange();
+    }
+    /**
+     * Computes a progress snapshot on demand so elapsed time ticks with periodic re-renders.
+     */
+    getProgress() {
+        var _a;
+        const stats = this.stats;
+        const totalPrompts = stats.done + stats.forAgent + stats.toBeWritten;
+        const sessionDone = Math.max(0, stats.done - ((_a = this.initialDone) !== null && _a !== void 0 ? _a : stats.done));
+        const sessionTotal = sessionDone + stats.forAgent;
+        const percentage = totalPrompts > 0 ? Math.round((stats.done / totalPrompts) * 100) : 0;
+        const wallMs = moment().diff(this.startTime);
+        const currentPauseMs = this.pausedSince !== undefined ? moment().diff(this.pausedSince) : 0;
+        const activeMs = Math.max(0, wallMs - this.pausedMs - currentPauseMs);
+        const elapsedDuration = moment.duration(activeMs);
+        const elapsedText = formatDurationBrief(elapsedDuration);
+        let estimatedTotalText = '\u2014';
+        let estimatedLabel = 'unknown';
+        if (totalPrompts > 0 && stats.done > 0) {
+            const estimatedTotalMs = (elapsedDuration.asMilliseconds() * totalPrompts) / stats.done;
+            const estimatedRemainingMs = estimatedTotalMs - elapsedDuration.asMilliseconds();
+            const estimatedTotalDuration = moment.duration(estimatedTotalMs);
+            const estimatedCompletion = moment().add(estimatedRemainingMs, 'milliseconds');
+            estimatedTotalText = formatDurationBrief(estimatedTotalDuration);
+            estimatedLabel = estimatedCompletion.calendar(null, ESTIMATED_DONE_CALENDAR_FORMATS);
+        }
+        return {
+            totalPrompts,
+            sessionDone,
+            sessionTotal,
+            percentage,
+            elapsedText,
+            estimatedTotalText,
+            estimatedLabel,
+        };
+    }
+    /**
+     * Sets the label of the prompt currently being processed and resets per-prompt state.
+     */
+    setCurrentPrompt(label) {
+        this.currentPromptLabel = label;
+        this.agentOutputLines = [];
+        this.currentAttempt = 1;
+        this.emitChange();
+    }
+    /**
+     * Updates the current retry attempt number.
+     */
+    setAttempt(attempt) {
+        this.currentAttempt = attempt;
+        this.emitChange();
+    }
+    /**
+     * Appends raw agent output text, keeping only the last `MAX_AGENT_OUTPUT_LINES`.
+     */
+    addAgentOutput(text) {
+        const lines = text.split(/\r?\n/).filter((line) => line.trim() !== '');
+        if (lines.length === 0) {
+            return;
+        }
+        this.agentOutputLines.push(...lines);
+        if (this.agentOutputLines.length > MAX_AGENT_OUTPUT_LINES) {
+            this.agentOutputLines = this.agentOutputLines.slice(-MAX_AGENT_OUTPUT_LINES);
+        }
+        this.emitChange();
+    }
+    /**
+     * Transitions the execution phase shown in the UI.
+     */
+    setPhase(phase) {
+        this.phase = phase;
+        this.emitChange();
+    }
+    /**
+     * Updates the status message line beneath the current prompt label.
+     */
+    setStatusMessage(message) {
+        this.statusMessage = message;
+        this.emitChange();
+    }
+    /**
+     * Appends an error message to the error list shown in the UI.
+     */
+    addError(errorMessage) {
+        this.errors.push(errorMessage);
+        this.emitChange();
+    }
+    emitChange() {
+        this.emit('change');
+    }
+}
+/**
+ * Formats a duration into a compact string such as "3h 12m" or "45s".
+ *
+ * @private internal utility of coder run UI
+ */
+function formatDurationBrief(duration) {
+    const totalSeconds = Math.max(0, Math.round(duration.asSeconds()));
+    const hours = Math.floor(totalSeconds / 3600);
+    const minutes = Math.floor((totalSeconds % 3600) / 60);
+    const seconds = totalSeconds % 60;
+    const parts = [];
+    if (hours > 0) {
+        parts.push(`${hours}h`);
+    }
+    if (minutes > 0) {
+        parts.push(`${minutes}m`);
+    }
+    if (!parts.length && seconds > 0) {
+        parts.push(`${seconds}s`);
+    }
+    if (!parts.length) {
+        parts.push('0s');
+    }
+    return parts.join(' ');
+}
+
+/**
+ * Refresh interval for the terminal UI in milliseconds.
+ *
+ * @private internal constant of coder run UI
+ */
+const UI_REFRESH_INTERVAL_MS = 200;
+/**
+ * Character width used for the text progress bar.
+ *
+ * @private internal constant of coder run UI
+ */
+const PROGRESS_BAR_WIDTH = 40;
+/**
+ * Maximum number of output lines reserved for agent output in the UI.
+ *
+ * @private internal constant of coder run UI
+ */
+const MAX_VISIBLE_OUTPUT_LINES = 8;
+/**
+ * Spinner animation frames.
+ *
+ * @private internal constant of coder run UI
+ */
+const SPINNER_FRAMES = [
+    '\u280B',
+    '\u2819',
+    '\u2839',
+    '\u2838',
+    '\u283C',
+    '\u2834',
+    '\u2826',
+    '\u2827',
+    '\u2807',
+    '\u280F',
+];
+/**
+ * Strips ANSI escape codes from a string.
+ *
+ * @private internal utility of coder run UI
+ */
+function stripAnsi(text) {
+    // eslint-disable-next-line no-control-regex
+    return text.replace(/\x1b\[[0-9;]*[a-zA-Z]/g, '');
+}
+/**
+ * Returns the usable terminal width, capped at 80.
+ *
+ * @private internal utility of coder run UI
+ */
+function getTerminalWidth() {
+    return Math.min(process.stdout.columns || 80, 80);
+}
+/**
+ * Builds a text progress bar string from a percentage.
+ *
+ * @private internal utility of coder run UI
+ */
+function buildProgressBar(percentage) {
+    const filled = Math.round((percentage / 100) * PROGRESS_BAR_WIDTH);
+    const empty = PROGRESS_BAR_WIDTH - filled;
+    return colors.green('\u2588'.repeat(filled)) + colors.gray('\u2591'.repeat(empty)) + ` ${percentage}%`;
+}
+/**
+ * Boots the ANSI terminal UI for `ptbk coder run`.
+ *
+ * The UI reserves a fixed number of terminal lines and repaints them periodically.
+ * Between repaints, any console output from runners is captured and fed into the
+ * scrolling agent-output area.
+ *
+ * On non-interactive (non-TTY) terminals the UI is skipped entirely and
+ * only the state object is provided.
+ *
+ * @private internal entry point of coder run UI
+ */
+function renderCoderRunUi(startTime) {
+    const state = new CoderRunUiState(startTime);
+    if (!process.stdout.isTTY) {
+        return {
+            state,
+            startCapturingAgentOutput: () => { },
+            stopCapturingAgentOutput: () => { },
+            cleanup: () => { },
+        };
+    }
+    // --- Console interception ---
+    const originalConsoleInfo = console.info;
+    const originalConsoleWarn = console.warn;
+    const originalConsoleError = console.error;
+    const originalConsoleLog = console.log;
+    let isCapturing = false;
+    console.info = (...args) => {
+        if (isCapturing) {
+            state.addAgentOutput(args.map(String).join(' '));
+        }
+        // In UI mode, non-captured output is intentionally suppressed
+        // so it does not interfere with the repainted frame.
+    };
+    console.warn = (...args) => {
+        if (isCapturing) {
+            state.addAgentOutput(args.map(String).join(' '));
+        }
+    };
+    console.error = (...args) => {
+        if (isCapturing) {
+            state.addError(args.map(String).join(' '));
+        }
+    };
+    console.log = (...args) => {
+        if (isCapturing) {
+            state.addAgentOutput(args.map(String).join(' '));
+        }
+    };
+    // --- Keyboard input (pause) ---
+    const readline = require('readline');
+    readline.emitKeypressEvents(process.stdin);
+    if (process.stdin.isTTY) {
+        process.stdin.setRawMode(true);
+    }
+    const keypressHandler = (_str, key) => {
+        if (key.ctrl && key.name === 'c') {
+            cleanup();
+            process.exit(0);
+        }
+        if (key.name === 'p') {
+            const current = getPauseState();
+            if (current === 'RUNNING') {
+                requestPause();
+            }
+            else {
+                requestResume();
+            }
+        }
+    };
+    process.stdin.on('keypress', keypressHandler);
+    // --- Rendering ---
+    let spinnerFrame = 0;
+    let previousFrameLineCount = 0;
+    let isRendering = false;
+    let renderScheduled = false;
+    /**
+     * Schedules a render on the next tick if one isn't already pending.
+     * Prevents overlapping renders that cause cursor desync.
+     */
+    function scheduleRender() {
+        if (renderScheduled) {
+            return;
+        }
+        renderScheduled = true;
+        setImmediate(() => {
+            renderScheduled = false;
+            render();
+        });
+    }
+    /**
+     * Clears previously rendered lines and writes a new frame.
+     */
+    function render() {
+        if (isRendering) {
+            return;
+        }
+        isRendering = true;
+        try {
+            const lines = buildFrame();
+            // Move cursor up to clear the previous frame.
+            if (previousFrameLineCount > 0) {
+                process.stdout.write(`\x1b[${previousFrameLineCount}A`);
+            }
+            for (let i = 0; i < lines.length; i++) {
+                clearLine(process.stdout, 0);
+                cursorTo(process.stdout, 0);
+                process.stdout.write(lines[i]);
+                if (i < lines.length - 1) {
+                    process.stdout.write('\n');
+                }
+            }
+            // Clear any leftover lines from a previous longer frame.
+            if (lines.length < previousFrameLineCount) {
+                for (let i = lines.length; i < previousFrameLineCount; i++) {
+                    process.stdout.write('\n');
+                    clearLine(process.stdout, 0);
+                    cursorTo(process.stdout, 0);
+                }
+                // Move back up to the end of the current frame.
+                const overshoot = previousFrameLineCount - lines.length;
+                if (overshoot > 0) {
+                    process.stdout.write(`\x1b[${overshoot}A`);
+                }
+            }
+            previousFrameLineCount = lines.length;
+            spinnerFrame = (spinnerFrame + 1) % SPINNER_FRAMES.length;
+        }
+        finally {
+            isRendering = false;
+        }
+    }
+    /**
+     * Builds the complete frame as an array of terminal lines.
+     */
+    function buildFrame() {
+        const w = getTerminalWidth();
+        const sep = colors.gray('\u2500'.repeat(w - 2));
+        const spinner = SPINNER_FRAMES[spinnerFrame];
+        const { config, phase, currentPromptLabel, currentAttempt, maxAttempts, statusMessage, agentOutputLines, errors, } = state;
+        const progress = state.getProgress();
+        const isPaused = getPauseState() !== 'RUNNING';
+        const isActive = phase === 'running' || phase === 'verifying' || phase === 'loading';
+        const lines = [];
+        // --- Branding ---
+        lines.push(colors.bold.cyan('\u2728 Promptbook Coder'));
+        // --- Config ---
+        let configLine1 = `Agent: ${colors.bold.green(config.agentName)}`;
+        if (config.modelName) {
+            configLine1 += `  \u2502  Model: ${colors.bold(config.modelName)}`;
+        }
+        if (config.thinkingLevel) {
+            configLine1 += `  \u2502  Thinking: ${colors.bold(config.thinkingLevel)}`;
+        }
+        lines.push(configLine1);
+        let configLine2 = '';
+        if (config.context) {
+            configLine2 += `Context: ${colors.yellow(config.context)}  \u2502  `;
+        }
+        configLine2 += `Priority: \u2265${config.priority}`;
+        if (config.testCommand) {
+            configLine2 += `  \u2502  Test: ${colors.gray(config.testCommand)}`;
+        }
+        lines.push(configLine2);
+        // --- Separator ---
+        lines.push(sep);
+        // --- Progress ---
+        const progressSummary = [
+            `${progress.sessionDone}/${progress.sessionTotal} Prompts (${progress.totalPrompts} total)`,
+            `${progress.elapsedText}/${progress.estimatedTotalText}`,
+            `Est. done ${progress.estimatedLabel}`,
+        ].join(' \u2502 ');
+        lines.push(progressSummary);
+        lines.push(buildProgressBar(progress.percentage));
+        // --- Separator ---
+        lines.push(sep);
+        // --- Current prompt ---
+        if (currentPromptLabel) {
+            const spinnerPrefix = isActive ? colors.yellow(`${spinner} `) : '  ';
+            lines.push(spinnerPrefix + colors.bold(currentPromptLabel));
+            lines.push(colors.gray(`Attempt ${currentAttempt}/${maxAttempts} \u2502 ${statusMessage}`));
+        }
+        else {
+            lines.push(colors.gray(statusMessage));
+        }
+        // --- Agent output ---
+        if (agentOutputLines.length > 0) {
+            lines.push('');
+            lines.push(colors.gray.bold('Agent output:'));
+            const visibleLines = agentOutputLines.slice(-MAX_VISIBLE_OUTPUT_LINES);
+            for (const line of visibleLines) {
+                const cleanLine = stripAnsi(line);
+                // Truncate to terminal width.
+                const truncated = cleanLine.length > w - 2 ? cleanLine.slice(0, w - 5) + '...' : cleanLine;
+                lines.push(colors.gray(truncated));
+            }
+        }
+        // --- Errors ---
+        if (errors.length > 0) {
+            lines.push('');
+            for (const err of errors) {
+                lines.push(colors.red(`\u2717 ${err}`));
+            }
+        }
+        // --- Separator ---
+        lines.push(sep);
+        // --- Controls ---
+        const pauseLabel = isPaused
+            ? colors.bgYellow.black(' PAUSED ') + colors.gray(' [P] Resume  \u2502  Ctrl+C Exit')
+            : colors.gray('[P] Pause  \u2502  Ctrl+C Exit');
+        lines.push(pauseLabel);
+        return lines;
+    }
+    // Initial render.
+    process.stdout.write('\n');
+    render();
+    const interval = setInterval(scheduleRender, UI_REFRESH_INTERVAL_MS);
+    // Listen for state changes and schedule a re-render (debounced).
+    state.on('change', scheduleRender);
+    // --- Cleanup ---
+    function cleanup() {
+        clearInterval(interval);
+        state.off('change', scheduleRender);
+        process.stdin.off('keypress', keypressHandler);
+        if (process.stdin.isTTY) {
+            process.stdin.setRawMode(false);
+        }
+        isCapturing = false;
+        console.info = originalConsoleInfo;
+        console.warn = originalConsoleWarn;
+        console.error = originalConsoleError;
+        console.log = originalConsoleLog;
+        // Render one final frame so the user sees the last state.
+        render();
+        process.stdout.write('\n');
+    }
+    return {
+        state,
+        startCapturingAgentOutput() {
+            isCapturing = true;
+        },
+        stopCapturingAgentOutput() {
+            isCapturing = false;
+        },
+        cleanup,
+    };
+}
+// Note: [💞] Ignore a discrepancy between file name and entity name
+
 /**
  * Constant for prompts dir.
  */
@@ -47958,8 +49148,13 @@ async function runCodexPrompts(providedOptions) {
             `));
     }
     const runStartDate = moment();
-    const progressDisplay = options.dryRun ? undefined : new CliProgressDisplay(runStartDate);
-    listenForPause();
+    const isUiMode = !options.dryRun && Boolean(process.stdout.isTTY);
+    const progressDisplay = options.dryRun || isUiMode ? undefined : new CliProgressDisplay(runStartDate);
+    const uiHandle = isUiMode ? renderCoderRunUi(runStartDate) : undefined;
+    // When the Ink UI is active it handles keyboard input itself, so skip the raw stdin listener.
+    if (!isUiMode) {
+        listenForPause();
+    }
     try {
         const resolvedCoderContext = await resolveCoderContext(options.context, process.cwd());
         if (options.dryRun) {
@@ -48058,35 +49253,78 @@ async function runCodexPrompts(providedOptions) {
         }
         console.info(colors.green(`Running prompts with ${runner.name}`));
         const runnerMetadata = getRunnerMetadata(options, actualRunnerModel);
+        // Feed configuration into the terminal UI
+        uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.setConfig({
+            agentName: runner.name,
+            modelName: actualRunnerModel,
+            thinkingLevel: options.thinkingLevel,
+            context: options.context,
+            priority: options.priority,
+            testCommand: options.testCommand,
+        });
+        uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.setPhase('loading');
+        uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.setStatusMessage(`Running prompts with ${runner.name}`);
         let hasShownUpcomingTasks = false;
         let hasWaitedForStart = false;
         while (just(true)) {
-            await checkPause();
+            await checkPause({
+                silent: isUiMode,
+                onPaused: () => {
+                    uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.pauseTimer();
+                    uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.setPhase('paused');
+                    uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.setStatusMessage('Paused');
+                },
+                onResumed: () => {
+                    uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.resumeTimer();
+                },
+            });
+            if (isUiMode) {
+                uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.setPhase('loading');
+                uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.setStatusMessage('Loading prompts...');
+            }
             const promptFiles = await loadPromptFiles(PROMPTS_DIR$1);
             const stats = summarizePrompts(promptFiles, options.priority);
             progressDisplay === null || progressDisplay === void 0 ? void 0 : progressDisplay.update(stats);
-            printStats(stats, options.priority);
+            uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.updateProgress(stats);
+            if (!isUiMode) {
+                printStats(stats, options.priority);
+            }
             const nextPrompt = findNextTodoPrompt(promptFiles, options.priority);
             if (!hasShownUpcomingTasks) {
-                if (stats.toBeWritten > 0) {
+                if (stats.toBeWritten > 0 && !isUiMode) {
                     console.info(colors.yellow('Following prompts need to be written:'));
                     printPromptsToBeWritten(promptFiles, options.priority);
                     console.info('');
                 }
-                printUpcomingTasks(listUpcomingTasks(promptFiles, options.priority));
+                if (!isUiMode) {
+                    printUpcomingTasks(listUpcomingTasks(promptFiles, options.priority));
+                }
                 hasShownUpcomingTasks = true;
             }
             if (!nextPrompt) {
                 if (stats.toBeWritten > 0) {
-                    console.info(colors.yellow('No prompts ready for agent.'));
+                    const message = 'No prompts ready for agent.';
+                    uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.setStatusMessage(message);
+                    uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.setPhase('done');
+                    if (!isUiMode) {
+                        console.info(colors.yellow(message));
+                    }
                 }
                 else {
-                    console.info(colors.green('All prompts are done.'));
+                    const message = 'All prompts are done.';
+                    uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.setStatusMessage(message);
+                    uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.setPhase('done');
+                    if (!isUiMode) {
+                        console.info(colors.green(message));
+                    }
                 }
                 return;
             }
             if (options.waitForUser) {
+                uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.pauseTimer();
+                uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.setStatusMessage(hasWaitedForStart ? 'Waiting... Press Enter to continue' : 'Waiting... Press Enter to start');
                 await waitForPromptStart(nextPrompt.file, nextPrompt.section, !hasWaitedForStart);
+                uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.resumeTimer();
                 hasWaitedForStart = true;
             }
             if (!options.ignoreGitChanges) {
@@ -48096,44 +49334,85 @@ async function runCodexPrompts(providedOptions) {
             const codexPrompt = appendCoderContext(buildCodexPrompt(nextPrompt.file, nextPrompt.section), resolvedCoderContext);
             const scriptPath = buildScriptPath(nextPrompt.file, nextPrompt.section);
             const promptLabel = buildPromptLabelForDisplay(nextPrompt.file, nextPrompt.section);
-            console.info(colors.blue(`Processing ${promptLabel}`));
+            const promptRoundArtifacts = createCoderRunPromptRoundArtifacts(options.preserveLogs);
+            if (isUiMode) {
+                uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.setCurrentPrompt(promptLabel);
+                uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.setPhase('running');
+                uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.setStatusMessage('Running');
+            }
+            else {
+                console.info(colors.blue(`Processing ${promptLabel}`));
+            }
             const promptExecutionStartedDate = moment();
+            let attemptCount = 1;
+            let promptRoundOutcome = 'failure';
             const roundChangedFilesSnapshot = options.normalizeLineEndings
                 ? await captureChangedFilesSnapshot(process.cwd())
                 : undefined;
             try {
-                const result = await runner.runPrompt({
-                    prompt: codexPrompt,
-                    scriptPath,
-                    projectPath: process.cwd(),
-                });
-                markPromptDone(nextPrompt.file, nextPrompt.section, result.usage, runnerMetadata.runnerName, runnerMetadata.modelName, promptExecutionStartedDate);
-                await writePromptFile(nextPrompt.file);
-                await normalizeLineEndingsForCurrentRound(options, roundChangedFilesSnapshot);
-                if (options.waitForUser) {
-                    printCommitMessage(commitMessage);
-                    await waitForEnter(colors.bgWhite('Press Enter to commit and continue...'));
-                }
-                await commitChanges(commitMessage, { noPush: options.noPush });
-                await runPostPromptAutoMigrationIfEnabled(options);
+                await withPromptRuntimeLog(scriptPath, async (logPath) => {
+                    try {
+                        uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.startCapturingAgentOutput();
+                        const result = await runPromptWithTestFeedback({
+                            runner,
+                            prompt: codexPrompt,
+                            scriptPath,
+                            projectPath: process.cwd(),
+                            promptLabel,
+                            testCommand: options.testCommand,
+                            logPath,
+                            promptRoundArtifacts,
+                            onAttemptStarted: (nextAttemptCount) => {
+                                attemptCount = nextAttemptCount;
+                                uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.setAttempt(nextAttemptCount);
+                                if (nextAttemptCount > 1) {
+                                    uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.setStatusMessage(`Retrying (attempt ${nextAttemptCount})`);
+                                    uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.setPhase('verifying');
+                                }
+                            },
+                        });
+                        uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.stopCapturingAgentOutput();
+                        uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.setStatusMessage('Committing changes');
+                        markPromptDone(nextPrompt.file, nextPrompt.section, result.usage, runnerMetadata.runnerName, runnerMetadata.modelName, promptExecutionStartedDate, result.attemptCount);
+                        await writePromptFile(nextPrompt.file);
+                        await normalizeLineEndingsForCurrentRound(options, roundChangedFilesSnapshot);
+                        if (options.waitForUser) {
+                            uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.pauseTimer();
+                            uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.setStatusMessage('Waiting... Press Enter to commit');
+                            printCommitMessage(commitMessage);
+                            await waitForEnter(colors.bgWhite('Press Enter to commit and continue...'));
+                            uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.resumeTimer();
+                        }
+                        await commitChanges(commitMessage, { autoPush: options.autoPush });
+                        await runPostPromptAutoMigrationIfEnabled(options);
+                        promptRoundOutcome = 'success';
+                    }
+                    catch (error) {
+                        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));
+                        markPromptFailed(nextPrompt.file, nextPrompt.section, runnerMetadata.runnerName, runnerMetadata.modelName, promptExecutionStartedDate, attemptCount);
+                        await writePromptFile(nextPrompt.file);
+                        await writePromptErrorLog({
+                            file: nextPrompt.file,
+                            section: nextPrompt.section,
+                            runnerName: runnerMetadata.runnerName,
+                            modelName: runnerMetadata.modelName,
+                            error,
+                        });
+                        await normalizeLineEndingsForCurrentRound(options, roundChangedFilesSnapshot);
+                        throw error;
+                    }
+                }, promptRoundArtifacts);
             }
-            catch (error) {
-                markPromptFailed(nextPrompt.file, nextPrompt.section, runnerMetadata.runnerName, runnerMetadata.modelName, promptExecutionStartedDate);
-                await writePromptFile(nextPrompt.file);
-                await writePromptErrorLog({
-                    file: nextPrompt.file,
-                    section: nextPrompt.section,
-                    runnerName: runnerMetadata.runnerName,
-                    modelName: runnerMetadata.modelName,
-                    error,
-                });
-                await normalizeLineEndingsForCurrentRound(options, roundChangedFilesSnapshot);
-                throw error;
+            finally {
+                await promptRoundArtifacts.cleanup(promptRoundOutcome);
             }
         }
     }
     finally {
         progressDisplay === null || progressDisplay === void 0 ? void 0 : progressDisplay.stop();
+        uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.cleanup();
         if (!options.dryRun) {
             printAgentGitIdentityTipIfNeeded();
         }
@@ -49756,7 +51035,7 @@ function promptbookifyAiText(text) {
 /**
  * Constant for default agent kit model name.
  */
-const DEFAULT_AGENT_KIT_MODEL_NAME = 'gpt-5.4-nano';
+const DEFAULT_AGENT_KIT_MODEL_NAME = 'gpt-5.4-mini';
 /**
  * Creates one structured log entry for streamed tool-call updates.
  *
@@ -50806,6 +52085,7 @@ class AgentLlmExecutionTools {
      * @param agentSource The agent source string that defines the agent's behavior
      */
     constructor(options) {
+        var _a;
         this.options = options;
         /**
          * Cached model requirements to avoid re-parsing the agent source
@@ -50815,6 +52095,7 @@ class AgentLlmExecutionTools {
          * Cached parsed agent information
          */
         this._cachedAgentInfo = null;
+        this.precomputedModelRequirements = (_a = options.precomputedModelRequirements) !== null && _a !== void 0 ? _a : null;
     }
     /**
      * Updates the agent source and clears the cache
@@ -50822,9 +52103,13 @@ class AgentLlmExecutionTools {
      * @param agentSource The new agent source string
      */
     updateAgentSource(agentSource) {
+        if (this.options.agentSource === agentSource) {
+            return;
+        }
         this.options.agentSource = agentSource;
         this._cachedAgentInfo = null;
         this._cachedModelRequirements = null;
+        this.precomputedModelRequirements = null;
     }
     /**
      * Get cached or parse agent information
@@ -50841,6 +52126,16 @@ class AgentLlmExecutionTools {
      * Note: [🐤] This is names `getModelRequirements` *(not `getAgentModelRequirements`)* because in future these two will be united
      */
     async getModelRequirements() {
+        var _a, _b;
+        if (this.precomputedModelRequirements !== null) {
+            if (this.options.isVerbose) {
+                console.info('[🤰]', 'Using precomputed agent model requirements', {
+                    agent: this.title,
+                    toolCount: (_b = (_a = this.precomputedModelRequirements.tools) === null || _a === void 0 ? void 0 : _a.length) !== null && _b !== void 0 ? _b : 0,
+                });
+            }
+            return this.precomputedModelRequirements;
+        }
         if (this._cachedModelRequirements === null) {
             const preparationStartedAtMs = Date.now();
             if (this.options.isVerbose) {
@@ -50950,6 +52245,7 @@ class AgentLlmExecutionTools {
      * Resolves agent requirements, attachments, and runtime overrides into one forwarded chat prompt.
      */
     async prepareChatPrompt(prompt) {
+        var _a;
         const chatPrompt = this.requireChatPrompt(prompt);
         const { sanitizedRequirements, promptSuffix } = await this.getSanitizedAgentModelRequirements();
         const attachments = normalizeChatAttachments(chatPrompt.attachments);
@@ -50967,7 +52263,16 @@ class AgentLlmExecutionTools {
             mergedTools,
             knowledgeSourcesForAgent,
         });
-        console.log('!!!! promptWithAgentModelRequirements:', forwardedPrompt);
+        if (this.options.isVerbose) {
+            console.info('[🤰]', 'Prepared agent chat prompt', {
+                agent: this.title,
+                usedPrecomputedModelRequirements: this.precomputedModelRequirements !== null,
+                toolNames: mergedTools.map((tool) => tool.name),
+                knowledgeSourcesCount: (_a = knowledgeSourcesForAgent === null || knowledgeSourcesForAgent === void 0 ? void 0 : knowledgeSourcesForAgent.length) !== null && _a !== void 0 ? _a : 0,
+                promptSuffixLength: promptSuffix.length,
+                systemMessageLength: sanitizedRequirements.systemMessage.length,
+            });
+        }
         return {
             forwardedPrompt,
             sanitizedRequirements,
@@ -51154,6 +52459,7 @@ class AgentLlmExecutionTools {
      * Runs one prepared prompt through the deprecated OpenAI Assistant backend.
      */
     async callOpenAiAssistantChatModelStream(options) {
+        var _a, _b, _c, _d;
         const assistant = await this.getOrPrepareOpenAiAssistant({
             llmTools: options.llmTools,
             originalPrompt: options.originalPrompt,
@@ -51161,7 +52467,14 @@ class AgentLlmExecutionTools {
             onProgress: options.onProgress,
         });
         const promptWithAgentModelRequirementsForOpenAiAssistantExecutionTools = createOpenAiAssistantPrompt(options.preparedChatPrompt.forwardedPrompt);
-        console.log('!!!! promptWithAgentModelRequirementsForOpenAiAssistantExecutionTools:', promptWithAgentModelRequirementsForOpenAiAssistantExecutionTools);
+        if (this.options.isVerbose) {
+            console.info('[🤰]', 'Prepared OpenAI Assistant prompt', {
+                agent: this.title,
+                toolNames: (_b = (_a = promptWithAgentModelRequirementsForOpenAiAssistantExecutionTools.modelRequirements.tools) === null || _a === void 0 ? void 0 : _a.map((tool) => tool.name)) !== null && _b !== void 0 ? _b : [],
+                knowledgeSourcesCount: (_d = (_c = promptWithAgentModelRequirementsForOpenAiAssistantExecutionTools.modelRequirements
+                    .knowledgeSources) === null || _c === void 0 ? void 0 : _c.length) !== null && _d !== void 0 ? _d : 0,
+            });
+        }
         return assistant.callChatModelStream(promptWithAgentModelRequirementsForOpenAiAssistantExecutionTools, options.onProgress, options.streamOptions);
     }
     /**
@@ -51852,7 +53165,8 @@ class Agent extends AgentLlmExecutionTools {
             isVerbose: options.isVerbose,
             llmTools: getSingleLlmExecutionTools(options.executionTools.llm),
             assistantPreparationMode: options.assistantPreparationMode,
-            agentSource: agentSource.value, // <- TODO: [🐱‍🚀] Allow to pass BehaviorSubject<string_book> OR refresh llmExecutionTools.callChat on agentSource change
+            agentSource: agentSource.value,
+            precomputedModelRequirements: options.precomputedModelRequirements,
         });
         this._agentName = undefined;
         /**