@promptbook/cli 0.112.0-43 → 0.112.0-44

package/umd/index.umd.js

@@ -60,7 +60,7 @@
      * @generated
      * @see https://github.com/webgptorg/promptbook
      */
-    const PROMPTBOOK_ENGINE_VERSION = '0.112.0-43';
+    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
@@ -3027,12 +3027,13 @@
         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('--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, test, thinkingLevel, priority, wait, ignoreGitChanges, allowCredits, normalizeLineEndings, autoMigrate, allowDestructiveAutoMigrate, autoPush, } = 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;
@@ -3067,6 +3068,7 @@
                 priority,
                 normalizeLineEndings,
                 allowCredits,
+                preserveLogs,
                 autoMigrate,
                 allowDestructiveAutoMigrate,
                 autoPush,
@@ -18951,7 +18953,7 @@
          * 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.
@@ -18966,12 +18968,14 @@
             return _spaceTrim.spaceTrim(`
             # ${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.
 
@@ -18984,9 +18988,7 @@
             \`\`\`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
             \`\`\`
@@ -18994,9 +18996,7 @@
             \`\`\`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
             \`\`\`
@@ -19004,9 +19004,7 @@
             \`\`\`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
             \`\`\`
@@ -21865,7 +21863,16 @@
          * 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.
@@ -21880,16 +21887,24 @@
             return _spaceTrim.spaceTrim(`
             # ${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
@@ -22654,7 +22669,7 @@
             \`\`\`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.
             \`\`\`
         `);
@@ -41400,6 +41415,15 @@
      * @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.
      *
@@ -41450,7 +41474,7 @@
      */
     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);
@@ -41461,6 +41485,35 @@
         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.
      *
@@ -42103,7 +42156,7 @@
     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);
@@ -42207,25 +42260,33 @@
      */
     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 = '';
+            if (commitment.type === 'PERSONA' || commitment.type === 'PERSONAE') {
+                personaDescription = commitment.content;
+                hasPersonaDescription = true;
             }
-            else {
-                personaDescription += `\n\n${personaDescription}`;
-            }
-            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.
@@ -42712,7 +42773,7 @@
      * 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
      *
@@ -42720,9 +42781,9 @@
      */
     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
@@ -44184,7 +44245,7 @@
     /**
      * CLI usage text for this script.
      */
-    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] [--auto-migrate] [--allow-destructive-auto-migrate] [--no-wait] [--ignore-git-changes] [--no-normalize-line-endings] [--auto-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.
      */
@@ -44197,6 +44258,7 @@
         '--thinking-level',
         '--priority',
         '--allow-credits',
+        '--preserve-logs',
         '--auto-migrate',
         '--allow-destructive-auto-migrate',
         '--no-wait',
@@ -44233,6 +44295,7 @@
         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 autoPush = args.includes('--auto-push');
@@ -44258,6 +44321,7 @@
             ignoreGitChanges,
             normalizeLineEndings,
             allowCredits,
+            preserveLogs,
             autoMigrate,
             allowDestructiveAutoMigrate,
             autoPush,
@@ -44751,6 +44815,91 @@
         return promises.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 promises.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 promises.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 promises.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.
      */
@@ -47054,25 +47203,186 @@
     }
 
     /**
-     * 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 promises.mkdir(path.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 promises.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 promises.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 = child_process.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.spaceTrim(output)));
+                    return;
+                }
+                const failure = new Error(_spaceTrim.spaceTrim(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 promises.mkdir(posix.dirname(scriptPath), { recursive: true });
         await promises.writeFile(scriptPath, scriptContent, 'utf-8');
-        const result = await handler(scriptPath);
-        await promises.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 promises.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,
             });
         });
     }
@@ -47168,6 +47478,8 @@
             const output = await $runGoScriptWithOutput({
                 scriptPath: options.scriptPath,
                 scriptContent,
+                logPath: options.logPath,
+                promptRoundArtifacts: options.promptRoundArtifacts,
             });
             const usage = parseClaudeCodeJsonOutput(output);
             return { usage };
@@ -47175,13 +47487,13 @@
     }
 
     /**
-     * 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,
             });
         });
     }
@@ -47230,6 +47542,8 @@
                 await $runGoScript({
                     scriptPath: options.scriptPath,
                     scriptContent,
+                    logPath: options.logPath,
+                    promptRoundArtifacts: options.promptRoundArtifacts,
                 });
                 return { usage: UNCERTAIN_USAGE };
             }
@@ -47353,6 +47667,8 @@
             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 };
@@ -47408,6 +47724,8 @@
             await $runGoScript({
                 scriptPath: options.scriptPath,
                 scriptContent,
+                logPath: options.logPath,
+                promptRoundArtifacts: options.promptRoundArtifacts,
             });
             return { usage: UNCERTAIN_USAGE };
         }
@@ -47444,14 +47762,30 @@
     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 = child_process.spawn('bash', [scriptPathPosix], { env: process.env });
+            const commandProcess = child_process.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.
              */
@@ -47466,6 +47800,18 @@
                 }
                 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.
              */
@@ -47475,7 +47821,7 @@
                 }
                 idleTimer = setTimeout(() => {
                     commandProcess.kill();
-                    settleOnce(() => resolve(fullOutput));
+                    settleWithLog('completed after idle timeout', () => resolve(fullOutput));
                 }, idleTimeoutMs);
             };
             /**
@@ -47529,41 +47875,43 @@
              * 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,
             });
         });
     }
@@ -47941,6 +48289,8 @@
                         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) };
@@ -48074,6 +48424,8 @@
                 output = await $runGoScriptWithOutput({
                     scriptPath: options.scriptPath,
                     scriptContent,
+                    logPath: options.logPath,
+                    promptRoundArtifacts: options.promptRoundArtifacts,
                 });
             }
             catch (error) {
@@ -48100,6 +48452,7 @@
             cd "${projectPath}"
             ${options.command}
         `),
+            logPath: options.logPath,
         });
     }
 
@@ -48123,6 +48476,8 @@
                 prompt: options.prompt,
                 scriptPath: options.scriptPath,
                 projectPath: options.projectPath,
+                logPath: options.logPath,
+                promptRoundArtifacts: options.promptRoundArtifacts,
             });
             return { ...result, attemptCount: 1 };
         }
@@ -48134,6 +48489,8 @@
                 prompt: promptForCurrentAttempt,
                 scriptPath: options.scriptPath,
                 projectPath: options.projectPath,
+                logPath: options.logPath,
+                promptRoundArtifacts: options.promptRoundArtifacts,
             });
             console.info(colors__default["default"].gray(`Running verification command after attempt #${attemptCount}: ${normalizedTestCommand}`));
             try {
@@ -48141,6 +48498,7 @@
                     command: normalizedTestCommand,
                     projectPath: options.projectPath,
                     scriptPath: buildPromptTestScriptPath(options.scriptPath),
+                    logPath: options.logPath,
                 });
                 return { ...result, attemptCount };
             }
@@ -48978,6 +49336,7 @@
                 const codexPrompt = appendCoderContext(buildCodexPrompt(nextPrompt.file, nextPrompt.section), resolvedCoderContext);
                 const scriptPath = buildScriptPath(nextPrompt.file, nextPrompt.section);
                 const promptLabel = buildPromptLabelForDisplay(nextPrompt.file, nextPrompt.section);
+                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');
@@ -48988,57 +49347,68 @@
                 }
                 const promptExecutionStartedDate = moment__default["default"]();
                 let attemptCount = 1;
+                let promptRoundOutcome = 'failure';
                 const roundChangedFilesSnapshot = options.normalizeLineEndings
                     ? await captureChangedFilesSnapshot(process.cwd())
                     : undefined;
                 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,
-                        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');
+                    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__default["default"].bgWhite('Press Enter to commit and continue...'));
+                                uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.resumeTimer();
                             }
-                        },
-                    });
-                    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__default["default"].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);
+                            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) {
-                    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;
+                finally {
+                    await promptRoundArtifacts.cleanup(promptRoundOutcome);
                 }
             }
         }