@promptbook/cli 0.112.0-43 → 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';
@@ -58,7 +58,7 @@ const BOOK_LANGUAGE_VERSION = '2.0.0';
  * @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
@@ -3025,12 +3025,13 @@ function $initializeCoderRunCommand(program) {
     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;
@@ -3065,6 +3066,7 @@ function $initializeCoderRunCommand(program) {
             priority,
             normalizeLineEndings,
             allowCredits,
+            preserveLogs,
             autoMigrate,
             allowDestructiveAutoMigrate,
             autoPush,
@@ -18949,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.
@@ -18964,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.
 
@@ -18982,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
             \`\`\`
@@ -18992,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
             \`\`\`
@@ -19002,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
             \`\`\`
@@ -21863,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.
@@ -21878,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
@@ -22652,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.
             \`\`\`
         `);
@@ -41398,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.
  *
@@ -41448,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);
@@ -41459,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.
  *
@@ -42101,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);
@@ -42205,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 = '';
+        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.
@@ -42710,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
  *
@@ -42718,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
@@ -44182,7 +44243,7 @@ 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>] [--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.
  */
@@ -44195,6 +44256,7 @@ const KNOWN_OPTION_FLAGS = new Set([
     '--thinking-level',
     '--priority',
     '--allow-credits',
+    '--preserve-logs',
     '--auto-migrate',
     '--allow-destructive-auto-migrate',
     '--no-wait',
@@ -44231,6 +44293,7 @@ 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 autoPush = args.includes('--auto-push');
@@ -44256,6 +44319,7 @@ function parseRunOptions(args) {
         ignoreGitChanges,
         normalizeLineEndings,
         allowCredits,
+        preserveLogs,
         autoMigrate,
         allowDestructiveAutoMigrate,
         autoPush,
@@ -44749,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.
  */
@@ -47052,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,
         });
     });
 }
@@ -47166,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 };
@@ -47173,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,
         });
     });
 }
@@ -47228,6 +47540,8 @@ class ClineRunner {
             await $runGoScript({
                 scriptPath: options.scriptPath,
                 scriptContent,
+                logPath: options.logPath,
+                promptRoundArtifacts: options.promptRoundArtifacts,
             });
             return { usage: UNCERTAIN_USAGE };
         }
@@ -47351,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 };
@@ -47406,6 +47722,8 @@ class GitHubCopilotRunner {
         await $runGoScript({
             scriptPath: options.scriptPath,
             scriptContent,
+            logPath: options.logPath,
+            promptRoundArtifacts: options.promptRoundArtifacts,
         });
         return { usage: UNCERTAIN_USAGE };
     }
@@ -47442,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.
          */
@@ -47464,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.
          */
@@ -47473,7 +47819,7 @@ async function runScriptUntilMarkerIdle(options) {
             }
             idleTimer = setTimeout(() => {
                 commandProcess.kill();
-                settleOnce(() => resolve(fullOutput));
+                settleWithLog('completed after idle timeout', () => resolve(fullOutput));
             }, idleTimeoutMs);
         };
         /**
@@ -47527,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,
         });
     });
 }
@@ -47939,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) };
@@ -48072,6 +48422,8 @@ class OpencodeRunner {
             output = await $runGoScriptWithOutput({
                 scriptPath: options.scriptPath,
                 scriptContent,
+                logPath: options.logPath,
+                promptRoundArtifacts: options.promptRoundArtifacts,
             });
         }
         catch (error) {
@@ -48098,6 +48450,7 @@ async function runPromptTestCommand(options) {
             cd "${projectPath}"
             ${options.command}
         `),
+        logPath: options.logPath,
     });
 }
 
@@ -48121,6 +48474,8 @@ async function runPromptWithTestFeedback(options) {
             prompt: options.prompt,
             scriptPath: options.scriptPath,
             projectPath: options.projectPath,
+            logPath: options.logPath,
+            promptRoundArtifacts: options.promptRoundArtifacts,
         });
         return { ...result, attemptCount: 1 };
     }
@@ -48132,6 +48487,8 @@ async function runPromptWithTestFeedback(options) {
             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 {
@@ -48139,6 +48496,7 @@ async function runPromptWithTestFeedback(options) {
                 command: normalizedTestCommand,
                 projectPath: options.projectPath,
                 scriptPath: buildPromptTestScriptPath(options.scriptPath),
+                logPath: options.logPath,
             });
             return { ...result, attemptCount };
         }
@@ -48976,6 +49334,7 @@ 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);
+            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');
@@ -48986,57 +49345,68 @@ async function runCodexPrompts(providedOptions) {
             }
             const promptExecutionStartedDate = moment();
             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.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.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);
             }
         }
     }