@promptbook/cli 0.114.0-11 → 0.114.0-13

package/umd/index.umd.js

@@ -58,7 +58,7 @@
      * @generated
      * @see https://github.com/webgptorg/promptbook
      */
-    const PROMPTBOOK_ENGINE_VERSION = '0.114.0-11';
+    const PROMPTBOOK_ENGINE_VERSION = '0.114.0-13';
     /**
      * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
      * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -4098,10 +4098,6 @@
      * Environment variable containing the internal worker token for local agent runners.
      */
     const PTBK_AGENTS_SERVER_USER_CHAT_WORKER_TOKEN_ENV = 'PTBK_AGENTS_SERVER_USER_CHAT_WORKER_TOKEN';
-    /**
-     * Header used by internal local-runner routes.
-     */
-    const USER_CHAT_WORKER_TOKEN_HEADER = 'x-user-chat-worker-token';
 
     /**
      * Format either small or big number
@@ -20317,6 +20313,30 @@
     // TODO: [🧠] Maybe create through standardized $register
     // Note: [💞] Ignore a discrepancy between file name and entity name
 
+    /**
+     * Pattern shared by Book parsing and editor highlighting for a commitment-like line.
+     *
+     * A Book commitment keyword consists of one or more all-uppercase words with at least
+     * two characters each. This deliberately mirrors the Book editor syntax rule so an
+     * unknown keyword starts a new source block everywhere it is interpreted.
+     *
+     * @private internal constant of `getBookCommitmentLineType`
+     */
+    const BOOK_COMMITMENT_LINE_TYPE_REGEX = /^\s*(?<type>[A-Z][A-Z0-9]+(?:\s+[A-Z][A-Z0-9]+)*)(?=\s|$)/;
+    /**
+     * Extracts the uppercase commitment type from a Book line, including types not registered by Promptbook.
+     *
+     * @param line - One raw Book source line.
+     * @returns Matched commitment type or `null` when the line does not begin with commitment syntax.
+     *
+     * @private internal utility of Book parsing and `<BookEditor/>`
+     */
+    function getBookCommitmentLineType(line) {
+        var _a;
+        const match = BOOK_COMMITMENT_LINE_TYPE_REGEX.exec(line);
+        return ((_a = match === null || match === void 0 ? void 0 : match.groups) === null || _a === void 0 ? void 0 : _a.type) || null;
+    }
+
     /**
      * Consumes the agent-name prelude from raw source.
      *
@@ -20374,13 +20394,15 @@
             return {
                 agentName: null,
                 commitments: [],
+                unknownCommitments: [],
                 nonCommitmentLines: [],
             };
         }
         const { lines, agentName, agentNameLineIndex, agentNameLineNumber } = parseAgentSourcePrelude(agentSource);
         const commitments = [];
+        const unknownCommitments = [];
         const nonCommitmentLines = agentNameLineIndex >= 0 ? [lines[agentNameLineIndex]] : [];
-        // Parse commitments with multiline support
+        // Parse commitments with multiline support.
         let currentCommitment = null;
         // Process lines starting from after the agent name line
         const startIndex = agentNameLineIndex >= 0 ? agentNameLineIndex + 1 : 0;
@@ -20394,25 +20416,11 @@
             // Check if this line starts or ends a code block
             if (trimmedLine.startsWith('```')) {
                 isInsideCodeBlock = !isInsideCodeBlock;
-                if (currentCommitment) {
-                    // If we are inside a commitment, the code block is part of it
-                    currentCommitment.contentLines.push(line);
-                }
-                else {
-                    // If we are not inside a commitment, the code block is non-commitment
-                    nonCommitmentLines.push(line);
-                }
+                appendLineToCurrentCommitmentOrNonCommitmentLines(currentCommitment, line, nonCommitmentLines);
                 continue;
             }
             if (isInsideCodeBlock) {
-                if (currentCommitment) {
-                    // If we are inside a commitment and a code block, the line is part of the commitment
-                    currentCommitment.contentLines.push(line);
-                }
-                else {
-                    // If we are inside a code block but not a commitment, the line is non-commitment
-                    nonCommitmentLines.push(line);
-                }
+                appendLineToCurrentCommitmentOrNonCommitmentLines(currentCommitment, line, nonCommitmentLines);
                 continue;
             }
             // Check if this line starts a new commitment
@@ -20421,22 +20429,14 @@
                 const typeRegex = definition.createTypeRegex();
                 const match = typeRegex.exec(line.trim());
                 if (match && ((_a = match.groups) === null || _a === void 0 ? void 0 : _a.type)) {
-                    // Save the previous commitment if it exists
-                    if (currentCommitment) {
-                        const fullContent = currentCommitment.contentLines.join('\n');
-                        commitments.push({
-                            type: currentCommitment.type,
-                            content: _spaceTrim.spaceTrim(fullContent),
-                            originalLine: currentCommitment.originalStartLine,
-                            lineNumber: currentCommitment.startLineNumber,
-                        });
-                    }
+                    appendCurrentCommitment(currentCommitment, commitments, unknownCommitments);
                     // Extract the initial content from the commitment line
                     const fullRegex = definition.createRegex();
                     const fullMatch = fullRegex.exec(line.trim());
                     const initialContent = ((_b = fullMatch === null || fullMatch === void 0 ? void 0 : fullMatch.groups) === null || _b === void 0 ? void 0 : _b.contents) || '';
                     // Start a new commitment
                     currentCommitment = {
+                        kind: 'known',
                         type: definition.type,
                         startLineNumber: i + 1,
                         originalStartLine: line,
@@ -20446,52 +20446,90 @@
                     break;
                 }
             }
+            if (foundNewCommitment) {
+                continue;
+            }
+            const unknownCommitmentType = getBookCommitmentLineType(line);
+            if (unknownCommitmentType) {
+                appendCurrentCommitment(currentCommitment, commitments, unknownCommitments);
+                currentCommitment = {
+                    kind: 'unknown',
+                    type: unknownCommitmentType,
+                    startLineNumber: i + 1,
+                    originalStartLine: line,
+                    sourceLines: [line],
+                };
+                continue;
+            }
             // Check if this is a horizontal line (ends any current commitment)
             const isHorizontalLine = HORIZONTAL_LINE_PATTERN$1.test(line);
             if (isHorizontalLine) {
-                // Save the current commitment if it exists
-                if (currentCommitment) {
-                    const fullContent = currentCommitment.contentLines.join('\n');
-                    commitments.push({
-                        type: currentCommitment.type,
-                        content: _spaceTrim.spaceTrim(fullContent),
-                        originalLine: currentCommitment.originalStartLine,
-                        lineNumber: currentCommitment.startLineNumber,
-                    });
-                    currentCommitment = null;
-                }
+                appendCurrentCommitment(currentCommitment, commitments, unknownCommitments);
+                currentCommitment = null;
                 // Add horizontal line to non-commitment lines
                 nonCommitmentLines.push(line);
                 continue;
             }
-            if (!foundNewCommitment) {
-                if (currentCommitment) {
-                    // This line belongs to the current commitment
-                    currentCommitment.contentLines.push(line);
-                }
-                else {
-                    // This line is not part of any commitment
-                    nonCommitmentLines.push(line);
-                }
-            }
-        }
-        // Don't forget to save the last commitment if it exists
-        if (currentCommitment) {
-            const fullContent = currentCommitment.contentLines.join('\n');
-            commitments.push({
-                type: currentCommitment.type,
-                content: _spaceTrim.spaceTrim(fullContent),
-                originalLine: currentCommitment.originalStartLine,
-                lineNumber: currentCommitment.startLineNumber,
-            });
+            appendLineToCurrentCommitmentOrNonCommitmentLines(currentCommitment, line, nonCommitmentLines);
         }
+        appendCurrentCommitment(currentCommitment, commitments, unknownCommitments);
         return {
             agentName,
             agentNameLineNumber,
             commitments,
+            unknownCommitments,
             nonCommitmentLines,
         };
     }
+    /**
+     * Stores the current known or unknown commitment in its appropriate parsed collection.
+     *
+     * @param currentCommitment - Commitment-like block collected so far.
+     * @param commitments - Parsed registered commitments to append to.
+     * @param unknownCommitments - Parsed unregistered commitments to append to.
+     *
+     * @private internal utility of `parseAgentSourceWithCommitments`
+     */
+    function appendCurrentCommitment(currentCommitment, commitments, unknownCommitments) {
+        if (!currentCommitment) {
+            return;
+        }
+        if (currentCommitment.kind === 'unknown') {
+            unknownCommitments.push({
+                type: currentCommitment.type,
+                originalLine: currentCommitment.originalStartLine,
+                lineNumber: currentCommitment.startLineNumber,
+                source: _spaceTrim.spaceTrim(currentCommitment.sourceLines.join('\n')),
+            });
+            return;
+        }
+        commitments.push({
+            type: currentCommitment.type,
+            content: _spaceTrim.spaceTrim(currentCommitment.contentLines.join('\n')),
+            originalLine: currentCommitment.originalStartLine,
+            lineNumber: currentCommitment.startLineNumber,
+        });
+    }
+    /**
+     * Adds one source line to the active commitment-like block, or to plain source content when none is active.
+     *
+     * @param currentCommitment - Commitment-like block currently being collected.
+     * @param line - Source line to append.
+     * @param nonCommitmentLines - Plain source lines to append to when no block is active.
+     *
+     * @private internal utility of `parseAgentSourceWithCommitments`
+     */
+    function appendLineToCurrentCommitmentOrNonCommitmentLines(currentCommitment, line, nonCommitmentLines) {
+        if (!currentCommitment) {
+            nonCommitmentLines.push(line);
+            return;
+        }
+        if (currentCommitment.kind === 'unknown') {
+            currentCommitment.sourceLines.push(line);
+            return;
+        }
+        currentCommitment.contentLines.push(line);
+    }
 
     /**
      * Parses parameters from text using both supported notations:
@@ -21850,7 +21888,7 @@
             return agentBookStats.isFile();
         }
         catch (error) {
-            if (isFileNotFoundError$6(error)) {
+            if (isFileNotFoundError$7(error)) {
                 return false;
             }
             throw error;
@@ -21859,7 +21897,7 @@
     /**
      * Returns true when one filesystem error indicates a missing path.
      */
-    function isFileNotFoundError$6(error) {
+    function isFileNotFoundError$7(error) {
         return Boolean(error &&
             typeof error === 'object' &&
             'code' in error &&
@@ -21889,7 +21927,7 @@
             return await promises.readdir(queuedMessagesDirectoryPath, { withFileTypes: true });
         }
         catch (error) {
-            if (isFileNotFoundError$5(error)) {
+            if (isFileNotFoundError$6(error)) {
                 return [];
             }
             throw error;
@@ -21910,7 +21948,7 @@
     /**
      * Returns true when an error is a missing-path filesystem error.
      */
-    function isFileNotFoundError$5(error) {
+    function isFileNotFoundError$6(error) {
         return Boolean(error &&
             typeof error === 'object' &&
             'code' in error &&
@@ -22388,7 +22426,7 @@
                 lastIndexLockState = await readGitIndexLockState(cwd, options.env);
                 if ((lastIndexLockState === null || lastIndexLockState === void 0 ? void 0 : lastIndexLockState.isStale) && !isStaleIndexLockRemoved) {
                     await promises.unlink(lastIndexLockState.path).catch((unlinkError) => {
-                        if (isFileNotFoundError$4(unlinkError)) {
+                        if (isFileNotFoundError$5(unlinkError)) {
                             return;
                         }
                         throw unlinkError;
@@ -22449,7 +22487,7 @@
             };
         }
         catch (error) {
-            if (isFileNotFoundError$4(error)) {
+            if (isFileNotFoundError$5(error)) {
                 return undefined;
             }
             throw error;
@@ -22506,7 +22544,7 @@
     /**
      * Detects missing-file errors while inspecting the lock file.
      */
-    function isFileNotFoundError$4(error) {
+    function isFileNotFoundError$5(error) {
         return Boolean(error &&
             typeof error === 'object' &&
             'code' in error &&
@@ -24761,14 +24799,90 @@
      * without the generated script and the prompt it embeds.
      */
     const SCRIPT_EXECUTION_LOG_RAW_OUTPUT_MARKER = '--- raw output ---';
+    /**
+     * Command which terminates the Bash process tree rooted at the running harness.
+     *
+     * Bash's POSIX process IDs differ from Windows process IDs in Git Bash, so the Windows branch resolves the native PID
+     * before delegating to `taskkill`. Unix harnesses run in a dedicated Bash job process group, which can be terminated
+     * with its negative process ID.
+     */
+    const TERMINATE_BASH_PROCESS_TREE_COMMAND = process.platform === 'win32'
+        ? _spaceTrim.spaceTrim(`
+              HARNESS_WINDOWS_PROCESS_ID="$(ps -l -p "$HARNESS_PROCESS_ID" | awk 'NR == 2 { print $4 }')"
+              if [ -n "$HARNESS_WINDOWS_PROCESS_ID" ]; then
+                  MSYS_NO_PATHCONV=1 taskkill.exe /PID "$HARNESS_WINDOWS_PROCESS_ID" /T /F > /dev/null 2>&1 || true
+              fi
+          `)
+        : 'kill -TERM -- "-$HARNESS_PROCESS_ID" 2>/dev/null || true';
+    /**
+     * Shell condition that detects whether the Node process which owns the harness is still running.
+     *
+     * Git Bash translates process IDs and command switches, so querying the native Windows PID needs both `tasklist` and
+     * disabled MSYS path conversion there. Unix can use the native `kill -0` process existence check.
+     */
+    const IS_PARENT_PROCESS_RUNNING_CONDITION = process.platform === 'win32'
+        ? 'MSYS_NO_PATHCONV=1 tasklist.exe /FI "PID eq $PARENT_CODER_PROCESS_ID" /NH | awk -v processId="$PARENT_CODER_PROCESS_ID" \'$2 == processId { isFound = 1 } END { exit isFound ? 0 : 1 }\''
+        : 'kill -0 "$PARENT_CODER_PROCESS_ID" 2>/dev/null';
+    /**
+     * Environment variable that identifies the Node process responsible for a temporary harness shell.
+     */
+    const PTBK_CODER_PARENT_PROCESS_ID_ENV_NAME = 'PTBK_CODER_PARENT_PROCESS_ID';
     /**
      * Small bash wrapper that preserves stdout/stderr streams while teeing both into the runtime log file.
+     *
+     * A watcher polls the owning Node process by its PID. If that process exits abruptly, the watcher stops the whole
+     * Bash and harness process tree instead of letting it continue as an orphan.
      */
     const LOGGED_BASH_WRAPPER_COMMAND = _spaceTrim.spaceTrim(`
+    PARENT_CODER_PROCESS_ID="\${${PTBK_CODER_PARENT_PROCESS_ID_ENV_NAME}}"
+    unset ${PTBK_CODER_PARENT_PROCESS_ID_ENV_NAME}
+
+    terminate_harness_process_tree() {
+        # Keep the EXIT cleanup intact so the wrapper can also stop its parent-process watcher.
+        trap - HUP INT TERM
+        ${TERMINATE_BASH_PROCESS_TREE_COMMAND}
+    }
+
+    is_parent_process_running() {
+        ${IS_PARENT_PROCESS_RUNNING_CONDITION}
+    }
+
     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)
+        exec > >(tee -a "$${PTBK_CODER_LOG_FILE_ENV_NAME}") 2> >(tee -a "$${PTBK_CODER_LOG_FILE_ENV_NAME}" >&2)
     fi
-    bash "$1"
+
+    watch_parent_process() {
+        trap 'exit 0' HUP INT TERM
+
+        while is_parent_process_running; do
+            sleep 1
+        done
+
+        terminate_harness_process_tree
+    }
+
+    # Background harness jobs need their own process group on Unix so termination cannot reach the parent coder.
+    set -m
+    if ! is_parent_process_running; then
+        exit 1
+    fi
+    bash "$1" &
+    HARNESS_PROCESS_ID=$!
+
+    cleanup_parent_process_watcher() {
+        kill "$PARENT_PROCESS_WATCHER_PID" 2>/dev/null || true
+        wait "$PARENT_PROCESS_WATCHER_PID" 2>/dev/null || true
+    }
+
+    watch_parent_process &
+    PARENT_PROCESS_WATCHER_PID=$!
+
+    trap cleanup_parent_process_watcher EXIT
+    trap terminate_harness_process_tree HUP INT TERM
+
+    wait "$HARNESS_PROCESS_ID"
+    SCRIPT_EXIT_CODE=$?
+    exit "$SCRIPT_EXIT_CODE"
 `);
     /**
      * Shapes one bash invocation that optionally mirrors live script output into a temporary log file.
@@ -24824,6 +24938,38 @@
         return scriptPath.toLowerCase().endsWith('.test.sh') ? 'test shell' : 'runner shell';
     }
 
+    /**
+     * Standard streams used by every temporary Bash runner.
+     */
+    const BASH_PROCESS_STDIO = ['pipe', 'pipe', 'pipe'];
+    /**
+     * Whether the current Node process is running on Windows.
+     */
+    const IS_WINDOWS$1 = process.platform === 'win32';
+    /**
+     * Starts one temporary Bash script in a process tree owned by the current Node process.
+     *
+     * The wrapper watches the supplied owning process ID. When that process exits abruptly, the wrapper terminates every
+     * nested shell and harness process instead of leaving it orphaned.
+     *
+     * @private internal utility of the coding prompt runner
+     */
+    function $spawnLoggedBashScript(options) {
+        var _a;
+        const bashExecution = buildLoggedBashExecution(options.scriptPath, options.logPath);
+        const parentProcessId = (_a = options.parentProcessId) !== null && _a !== void 0 ? _a : process.pid;
+        return child_process.spawn('bash', bashExecution.args, {
+            detached: !IS_WINDOWS$1,
+            env: {
+                ...process.env,
+                ...bashExecution.env,
+                [PTBK_CODER_PARENT_PROCESS_ID_ENV_NAME]: parentProcessId.toString(),
+            },
+            stdio: BASH_PROCESS_STDIO,
+            windowsHide: true,
+        });
+    }
+
     /**
      * Prints one live shell output chunk to the terminal when console mirroring is enabled.
      */
@@ -24846,12 +24992,12 @@
     async function runBashScriptWithOutput(options) {
         var _a;
         await appendScriptExecutionLogStart(options);
-        const bashExecution = buildLoggedBashExecution(options.scriptPath, options.logPath);
         const scriptPathPosix = toPosixPath(options.scriptPath);
         const shouldPrintLiveOutput = (_a = options.shouldPrintLiveOutput) !== null && _a !== void 0 ? _a : true;
         return await new Promise((resolve, reject) => {
-            const commandProcess = child_process.spawn('bash', bashExecution.args, {
-                env: bashExecution.env ? { ...process.env, ...bashExecution.env } : process.env,
+            const commandProcess = $spawnLoggedBashScript({
+                scriptPath: options.scriptPath,
+                logPath: options.logPath,
             });
             let output = '';
             let settled = false;
@@ -24910,8 +25056,9 @@
                 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);
             };
+            // Wait for `close`, not only `exit`, because the Bash wrapper can still be flushing its tee process
+            // substitutions after the direct shell exits.
             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);
@@ -25772,6 +25919,35 @@
             error.message.includes('bin/node'));
     }
 
+    /**
+     * Whether the current coder process runs on Windows.
+     */
+    const IS_WINDOWS = process.platform === 'win32';
+    /**
+     * Stops one active temporary Bash shell together with the harness process tree it owns.
+     *
+     * Unix sends `SIGTERM` to the wrapper so its shell trap terminates the separately grouped harness job. Windows does
+     * not reliably deliver that signal to Bash, so the native `taskkill` command terminates the direct shell tree instead.
+     *
+     * @private internal utility of the coding prompt runner
+     */
+    function $terminateLoggedBashProcessTree(commandProcess) {
+        if (commandProcess.exitCode !== null || commandProcess.signalCode !== null) {
+            return;
+        }
+        if (!IS_WINDOWS) {
+            commandProcess.kill('SIGTERM');
+            return;
+        }
+        if (!commandProcess.pid) {
+            return;
+        }
+        child_process.spawnSync('taskkill.exe', ['/PID', commandProcess.pid.toString(), '/T', '/F'], {
+            stdio: 'ignore',
+            windowsHide: true,
+        });
+    }
+
     /**
      * Maximum number of output characters included in thrown error messages.
      */
@@ -25814,15 +25990,16 @@
         const scriptPathPosix = toPosixPath(scriptPath);
         const shouldPrintLiveOutput = (_a = options.shouldPrintLiveOutput) !== null && _a !== void 0 ? _a : true;
         await appendScriptExecutionLogStart(options);
-        const bashExecution = buildLoggedBashExecution(scriptPath, options.logPath);
         return await new Promise((resolve, reject) => {
-            const commandProcess = child_process.spawn('bash', bashExecution.args, {
-                env: bashExecution.env ? { ...process.env, ...bashExecution.env } : process.env,
+            const commandProcess = $spawnLoggedBashScript({
+                scriptPath,
+                logPath: options.logPath,
             });
             let stdoutBuffer = '';
             let stderrBuffer = '';
             let fullOutput = '';
             let markerSeen = false;
+            let isCompletedAfterIdleTimeout = false;
             let idleTimer;
             let settled = false;
             let isSettling = false;
@@ -25864,15 +26041,16 @@
                 });
             };
             /**
-             * Finishes a marker-completed run and then asks bash to stop.
+             * Stops a marker-completed process tree after its trailing output becomes idle.
              */
             const finishAfterIdleTimeout = () => {
-                settleWithLog('completed after idle timeout', () => resolve(fullOutput));
+                isCompletedAfterIdleTimeout = true;
+                idleTimer = undefined;
                 try {
-                    commandProcess.kill();
+                    $terminateLoggedBashProcessTree(commandProcess);
                 }
                 catch (_a) {
-                    // Windows can report EPERM when bash exits before the idle timer fires.
+                    // The close handler below still settles normally when Bash already exited before the idle timer fired.
                 }
             };
             /**
@@ -25931,7 +26109,11 @@
                 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';
+                const status = isCompletedAfterIdleTimeout
+                    ? 'completed after idle timeout'
+                    : failure
+                        ? `failed with exit code ${code !== null && code !== void 0 ? code : 'unknown'}`
+                        : 'succeeded';
                 settleWithLog(status, () => {
                     if (!failure) {
                         resolve(fullOutput);
@@ -25940,8 +26122,9 @@
                     reject(failure);
                 });
             };
+            // Wait for `close`, not only `exit`, because the Bash wrapper can still be flushing its tee process
+            // substitutions after the direct shell exits.
             commandProcess.on('close', handleExit);
-            commandProcess.on('exit', handleExit);
             commandProcess.on('disconnect', () => {
                 const failure = new Error(buildCommandFailureMessage(scriptPathPosix, null, fullOutput));
                 settleWithLog('failed after disconnect', () => reject(failure), failure);
@@ -29437,7 +29620,7 @@
             return crypto.createHash('sha1').update(content).digest('hex');
         }
         catch (error) {
-            if (isFileNotFoundError$3(error)) {
+            if (isFileNotFoundError$4(error)) {
                 return null;
             }
             throw error;
@@ -29452,7 +29635,7 @@
     /**
      * Returns true when an error is a missing-file filesystem error.
      */
-    function isFileNotFoundError$3(error) {
+    function isFileNotFoundError$4(error) {
         return Boolean(error &&
             typeof error === 'object' &&
             'code' in error &&
@@ -30445,7 +30628,7 @@
             - You have 100% control over every project folder: create, read, modify, and delete files there, run scripts and commands inside it, and keep any persistent data you need between conversations.
             - When the user asks you to build something (for example a website) or to do longer-term work, create a new project folder \`${AGENT_PROJECTS_DIRECTORY_PATH}/<project-name>/\` (use a short kebab-case name) and do the work inside it. Modify an existing project when the user refers to work you already did.
             - A project can be a git repository — you can run \`git init\` inside a project folder and commit your work there.
-            - Do not touch anything outside the \`${AGENT_PROJECTS_DIRECTORY_PATH}/\` directory except the queued message file you are answering.
+            - Do not touch anything outside the \`${AGENT_PROJECTS_DIRECTORY_PATH}/\` directory beyond the file changes allowed at the top of this prompt.
 
             ${block(buildProjectReferenceInstructions(projectsUrlPath))}
             ${block(buildProjectRuntimeInstructions(options.projectRuntimeApi))}
@@ -30501,55 +30684,166 @@
     }
 
     /**
-     * Title stored on every agent goal chat.
+     * Milliseconds in one second.
+     *
+     * @private internal timeout-chat constant
+     */
+    const SECOND_IN_MILLISECONDS = 1000;
+    /**
+     * Seconds in one minute.
+     *
+     * @private internal timeout-chat constant
+     */
+    const MINUTE_IN_SECONDS = 60;
+    /**
+     * Seconds in one hour.
+     *
+     * @private internal timeout-chat constant
+     */
+    const HOUR_IN_SECONDS = 60 * MINUTE_IN_SECONDS;
+    /**
+     * Seconds in one day.
+     *
+     * @private internal timeout-chat constant
+     */
+    const HOURS_IN_DAY = 24;
+    /**
+     * Seconds in one day.
+     *
+     * @private internal timeout-chat constant
      */
+    const DAY_IN_SECONDS = HOURS_IN_DAY * HOUR_IN_SECONDS;
     /**
-     * Internal endpoint used by managed coding agents to plan goal-chat messages.
+     * Converts timeout duration into natural language sentence fragments.
+     *
+     * Shared by every timeout surface: the chat chips, the goal-chat planned messages of the Agents
+     * Server, and the planned-message prompt section of the agent-folder runner.
+     *
+     * @param milliseconds - Duration or repeat interval in milliseconds.
+     * @returns Label such as `5 minutes` or `1 hour 30 minutes`.
+     *
+     * @private internal utility of `<Chat/>` and the Agents Server planned messages
      */
-    const AGENT_GOAL_CHAT_PLANNED_MESSAGES_INTERNAL_API_PATH = '/api/internal/agent-goal-chat-planned-messages';
+    function formatTimeoutDurationHuman(milliseconds) {
+        const normalizedMilliseconds = Math.max(0, Math.floor(milliseconds));
+        const totalSeconds = Math.max(1, Math.floor(normalizedMilliseconds / SECOND_IN_MILLISECONDS));
+        if (totalSeconds < MINUTE_IN_SECONDS) {
+            return formatTimeoutUnit(totalSeconds, 'second');
+        }
+        if (totalSeconds < HOUR_IN_SECONDS) {
+            const roundedMinutes = Math.max(1, Math.round(totalSeconds / MINUTE_IN_SECONDS));
+            return formatTimeoutUnit(roundedMinutes, 'minute');
+        }
+        if (totalSeconds < DAY_IN_SECONDS) {
+            const hours = Math.floor(totalSeconds / HOUR_IN_SECONDS);
+            const minutes = Math.floor((totalSeconds % HOUR_IN_SECONDS) / MINUTE_IN_SECONDS);
+            if (minutes === 0) {
+                return formatTimeoutUnit(hours, 'hour');
+            }
+            return `${formatTimeoutUnit(hours, 'hour')} ${formatTimeoutUnit(minutes, 'minute')}`;
+        }
+        const days = Math.floor(totalSeconds / DAY_IN_SECONDS);
+        const hours = Math.floor((totalSeconds % DAY_IN_SECONDS) / HOUR_IN_SECONDS);
+        if (hours === 0) {
+            return formatTimeoutUnit(days, 'day');
+        }
+        return `${formatTimeoutUnit(days, 'day')} ${formatTimeoutUnit(hours, 'hour')}`;
+    }
+    /**
+     * Formats one pluralized timeout unit.
+     *
+     * @private internal timeout-chat helper
+     */
+    function formatTimeoutUnit(value, unit) {
+        return `${value} ${unit}${value === 1 ? '' : 's'}`;
+    }
+    // Note: [💞] Ignore a discrepancy between file name and entity name
 
     /**
      * Builds the planned-message instructions available to an Agents Server-managed coding agent.
      *
-     * Planned messages always target the agent's singleton goal chat, regardless of the chat in which
-     * the command is invoked.
+     * Planned messages always target the agent's singleton goal chat, regardless of the chat in which the
+     * wake-up is planned, and they repeat like `setInterval` until they are cancelled. The sidecar file is
+     * the only channel that changes them, so an answer that merely claims a follow-up was planned changes
+     * nothing — and an answer that changes nothing keeps the current plan running.
+     *
+     * @param sidecar - Sidecar prepared by the Agents Server for the answered message.
+     * @returns Prompt section, or an empty string outside Agents Server-managed runs.
      */
-    function buildAgentGoalChatPromptSection(runtimeApi) {
-        if (!runtimeApi) {
+    function buildAgentGoalChatPromptSection(sidecar) {
+        if (!sidecar) {
             return '';
         }
-        return _spaceTrim.spaceTrim(`
-        ## Planned goal-chat messages
+        return _spaceTrim.spaceTrim((block) => `
+            ## Planned goal-chat messages
 
-        You can plan a future message that wakes you in your singleton goal chat. These commands are available during every Agents Server-managed chat invocation, not only while answering inside the goal chat.
+            You can plan a message that repeatedly wakes you in your singleton goal chat. A planned message works like \`setInterval\`, not like \`setTimeout\`: once planned, it keeps waking you at its interval until you cancel it. This works during every Agents Server-managed chat invocation, not only while answering inside the goal chat.
 
-        - Use \`list_timeouts\` before planning follow-up work so you do not create duplicates.
-        - Use \`set_timeout\` when useful work should resume later. The delay is a positive number of milliseconds and the message should say exactly what your future invocation needs to do.
-        - Use \`cancel_timeout\` with the returned \`timeoutId\` when a planned message is no longer useful.
-        - A fired message appears in the goal chat and invokes you there. If more future work remains, plan the next useful message during that invocation.
+            ${block(buildCurrentPlannedMessagesLines(sidecar.currentPlannedMessages))}
 
-        Run the corresponding authenticated command:
+            Editing \`${sidecar.relativeSidecarPath}\` is the **only** way to change what wakes you. Writing in your answer that you scheduled something does not schedule anything.
 
-        \`\`\`bash
-        # list_timeouts
-        curl -sS -X POST "$${runtimeApi.serverUrlEnvironmentVariableName}${AGENT_GOAL_CHAT_PLANNED_MESSAGES_INTERNAL_API_PATH}" \\
-          -H "Content-Type: application/json" \\
-          -H "${USER_CHAT_WORKER_TOKEN_HEADER}: $${runtimeApi.tokenEnvironmentVariableName}" \\
-          -d '{"action":"list","agentPermanentId":"${runtimeApi.agentPermanentId}"}'
+            -   **Keeping your planned messages as they are is the default.** When the list above already matches your goal, leave \`commands\` empty — every listed message keeps repeating on its own, and re-planning it would only duplicate it.
+            -   When your goal needs a repeating wake-up that is not listed above, append \`{"action":"set","milliseconds":<repeat interval>,"message":"<what each future invocation must do>"}\` to the \`commands\` array of that file.
+            -   When a listed message no longer matches your goal (for example your goal now says every 10 minutes while the message repeats every 5 minutes), append \`{"action":"cancel","timeoutId":"<timeout id>"}\` and one \`set\` command with the interval your goal really requires.
+            -   When your goal no longer needs a listed message at all, cancel it without planning a replacement.
+            -   Never edit \`version\`, \`agentPermanentId\`, or \`currentPlannedMessages\`.
+            -   The Agents Server applies every command once your answer is finished, and each repetition appears in the goal chat and invokes you there.
+            -   Only mention a planned follow-up in your answer when it is really planned: either you appended the matching \`set\` command, or you kept one of the messages listed above.
+        `);
+    }
+    /**
+     * Renders the already planned messages so the agent can compare them with its goal.
+     *
+     * @param currentPlannedMessages - Planned messages prepared by the Agents Server.
+     * @returns Markdown list, or a sentence stating that nothing is planned yet.
+     *
+     * @private function of `buildAgentGoalChatPromptSection`
+     */
+    function buildCurrentPlannedMessagesLines(currentPlannedMessages) {
+        if (currentPlannedMessages.length === 0) {
+            return 'You currently have no planned messages waiting.';
+        }
+        const plannedMessageLines = currentPlannedMessages.map(createCurrentPlannedMessageLine);
+        return _spaceTrim.spaceTrim((block) => `
+            These planned messages are already waiting for you, so keep them unless they stopped matching your goal:
 
-        # set_timeout
-        curl -sS -X POST "$${runtimeApi.serverUrlEnvironmentVariableName}${AGENT_GOAL_CHAT_PLANNED_MESSAGES_INTERNAL_API_PATH}" \\
-          -H "Content-Type: application/json" \\
-          -H "${USER_CHAT_WORKER_TOKEN_HEADER}: $${runtimeApi.tokenEnvironmentVariableName}" \\
-          -d '{"action":"set","agentPermanentId":"${runtimeApi.agentPermanentId}","milliseconds":3600000,"message":"Continue the current goal and decide the next concrete action."}'
+            ${block(plannedMessageLines.join('\n'))}
+        `);
+    }
+    /**
+     * Renders one already planned message with the schedule the agent has to compare with its goal.
+     *
+     * @param plannedMessage - One planned message prepared by the Agents Server.
+     * @returns Markdown list item.
+     *
+     * @private function of `buildAgentGoalChatPromptSection`
+     */
+    function createCurrentPlannedMessageLine(plannedMessage) {
+        var _a;
+        const message = ((_a = plannedMessage.message) === null || _a === void 0 ? void 0 : _a.trim()) || 'Continue working towards the current goal.';
+        const schedule = plannedMessage.intervalMs
+            ? `repeats every ${formatTimeoutDurationHuman(plannedMessage.intervalMs)}`
+            : `wakes you once at ${plannedMessage.dueAt}`;
+        return `-   \`${plannedMessage.timeoutId}\` ${schedule}: ${message}`;
+    }
 
-        # cancel_timeout
-        curl -sS -X POST "$${runtimeApi.serverUrlEnvironmentVariableName}${AGENT_GOAL_CHAT_PLANNED_MESSAGES_INTERNAL_API_PATH}" \\
-          -H "Content-Type: application/json" \\
-          -H "${USER_CHAT_WORKER_TOKEN_HEADER}: $${runtimeApi.tokenEnvironmentVariableName}" \\
-          -d '{"action":"cancel","agentPermanentId":"${runtimeApi.agentPermanentId}","timeoutId":"<timeout-id>"}'
-        \`\`\`
-    `);
+    /**
+     * Creates the stable file-system safe base name that belongs to one queued `.book` message.
+     *
+     * Every sidecar the Agents Server prepares next to a queued message (TEAM workspaces, planned-message
+     * files, ...) derives its own name from this one normalization, so a sidecar can always be found again
+     * from the message file name alone.
+     *
+     * @param messageFileName - File name of the queued message, with or without directories.
+     * @returns Normalized base name usable as a directory or file name.
+     *
+     * @private internal convention shared by the Agents Server and agent-folder runner
+     */
+    function createAgentMessageSidecarBaseName(messageFileName) {
+        const rawBaseName = path.basename(messageFileName).replace(/\.book$/iu, '');
+        const normalizedBaseName = rawBaseName.replace(/[^A-Za-z0-9._-]+/gu, '-').replace(/^[._-]+|[._-]+$/gu, '');
+        return normalizedBaseName || 'message';
     }
 
     // Note: [💞] This file defines the shared TEAM workspace convention rather than one standalone entity.
@@ -30583,9 +30877,7 @@
      * @private internal convention shared by the Agents Server and agent-folder runner
      */
     function createAgentTeamConversationWorkspaceDirectoryName(messageFileName) {
-        const rawBaseName = path.basename(messageFileName).replace(/\.book$/iu, '');
-        const normalizedBaseName = rawBaseName.replace(/[^A-Za-z0-9._-]+/gu, '-').replace(/^[._-]+|[._-]+$/gu, '');
-        return normalizedBaseName || 'message';
+        return createAgentMessageSidecarBaseName(messageFileName);
     }
     /**
      * Creates the relative active workspace path for one queued message.
@@ -30655,8 +30947,8 @@
             return '';
         }
         const teammateSections = workspace.manifest.teammates.map((teammate) => {
-            const sourcePath = toPromptPath(path.join(workspace.relativeWorkspacePath, AGENT_TEAMMATE_SOURCES_DIRECTORY_NAME, teammate.sourceFileName));
-            const transcriptPath = toPromptPath(path.join(workspace.relativeWorkspacePath, `${teammate.permanentId}--01.book`));
+            const sourcePath = toPromptPath$1(path.join(workspace.relativeWorkspacePath, AGENT_TEAMMATE_SOURCES_DIRECTORY_NAME, teammate.sourceFileName));
+            const transcriptPath = toPromptPath$1(path.join(workspace.relativeWorkspacePath, `${teammate.permanentId}--01.book`));
             const instructions = teammate.instructions.trim() || 'No additional TEAM instructions were provided.';
             return _spaceTrim.spaceTrim(`
             -   ${teammate.agentName}
@@ -30674,7 +30966,7 @@
 
             -   The underlying coding harness is already executing this turn **exactly once**. Never start, queue, or invoke another coding harness, agent runner, or \`ptbk\` command to consult a teammate.
             -   The primary agent remains responsible for the final user-facing \`MESSAGE @Agent\` answer.
-            -   Teammate source files are read-only context. When a teammate consultation occurs, record the actual exchange in a new top-level \`.book\` file in \`${toPromptPath(workspace.relativeWorkspacePath)}\`.
+            -   Teammate source files are read-only context. When a teammate consultation occurs, record the actual exchange in a new top-level \`.book\` file in \`${toPromptPath$1(workspace.relativeWorkspacePath)}\`.
             -   Name each transcript \`<teammate permanent id>--<sequence>.book\`, for example \`${workspace.manifest.teammates[0].permanentId}--01.book\`.
             -   Every transcript must contain alternating \`MESSAGE @${workspace.manifest.primaryAgent.agentName}\` and \`MESSAGE @<teammate name>\` blocks. Do not create a transcript for a teammate that was not consulted.
         `);
@@ -30682,7 +30974,7 @@
     /**
      * Converts a filesystem-relative path into the portable path notation used in prompts.
      */
-    function toPromptPath(path) {
+    function toPromptPath$1(path) {
         return path.replace(/\\/gu, '/');
     }
 
@@ -30695,7 +30987,7 @@
 
                 -   Read \`${messageRelativePath}\` and answer the most recent \`MESSAGE\` block. In a normal chat it is from \`@User\`; in your internal goal chat it can be from \`@Agent\`.
                 -   Only change the queued message file by appending one new \`MESSAGE @Agent\` block
-                ${block(buildAllowedFileChangesPromptLine(options.teamWorkspace))}
+                ${block(buildAllowedFileChangesPromptLine(options))}
 
                 ## Rules for the answering
 
@@ -30731,7 +31023,7 @@
 
                 - You can use \`message\` for message that will be sent immediately after clicking the button, or \`messageDraft\` for message that will be prefilled in the input field for editing before sending.
 
-                ${block(buildAgentGoalChatPromptSection(options.goalChatRuntimeApi))}
+                ${block(buildAgentGoalChatPromptSection(options.plannedMessagesSidecar))}
 
                 ${block(buildAgentProjectsPromptSection(options))}
 
@@ -30745,11 +31037,30 @@
     /**
      * Explains the exact files that one coding harness may change for a user turn.
      */
-    function buildAllowedFileChangesPromptLine(teamWorkspace) {
-        if (!teamWorkspace) {
-            return `-   Do not modify any other file in the repository, except files inside your own \`${AGENT_PROJECTS_DIRECTORY_PATH}/\` directory`;
+    function buildAllowedFileChangesPromptLine(options) {
+        const allowedFileChanges = [`files inside your own \`${AGENT_PROJECTS_DIRECTORY_PATH}/\` directory`];
+        if (options.teamWorkspace) {
+            allowedFileChanges.push(`new consultation transcripts inside \`${toPromptPath(options.teamWorkspace.relativeWorkspacePath)}\``);
+        }
+        if (options.plannedMessagesSidecar) {
+            allowedFileChanges.push(`the \`commands\` array of \`${toPromptPath(options.plannedMessagesSidecar.relativeSidecarPath)}\``);
+        }
+        return `-   Do not modify any other file in the repository, except ${formatAllowedFileChanges(allowedFileChanges)}`;
+    }
+    /**
+     * Joins the allowed file-change phrases into one readable enumeration.
+     */
+    function formatAllowedFileChanges(allowedFileChanges) {
+        if (allowedFileChanges.length === 1) {
+            return allowedFileChanges[0];
         }
-        return `-   Do not modify any other file in the repository, except files inside your own \`${AGENT_PROJECTS_DIRECTORY_PATH}/\` directory and new consultation transcripts inside \`${teamWorkspace.relativeWorkspacePath.replace(/\\/gu, '/')}\``;
+        return `${allowedFileChanges.slice(0, -1).join(', ')} and ${allowedFileChanges[allowedFileChanges.length - 1]}`;
+    }
+    /**
+     * Converts a filesystem-relative path into the portable path notation used in prompts.
+     */
+    function toPromptPath(path) {
+        return path.replace(/\\/gu, '/');
     }
 
     var PipelineCollection = [{title:"Prepare Knowledge from Markdown",pipelineUrl:"https://promptbook.studio/promptbook/prepare-knowledge-from-markdown.book",formfactorName:"GENERIC",parameters:[{name:"knowledgeContent",description:"Markdown document content",isInput:true,isOutput:false},{name:"knowledgePieces",description:"The knowledge JSON object",isInput:false,isOutput:true}],tasks:[{taskType:"PROMPT_TASK",name:"knowledge",title:"Knowledge",content:"You are experienced data researcher, extract the important knowledge from the document.\n\n# Rules\n\n-   Make pieces of information concise, clear, and easy to understand\n-   One piece of information should be approximately 1 paragraph\n-   Divide the paragraphs by markdown horizontal lines ---\n-   Omit irrelevant information\n-   Group redundant information\n-   Write just extracted information, nothing else\n\n# The document\n\nTake information from this document:\n\n> {knowledgeContent}",resultingParameterName:"knowledgePieces",dependentParameterNames:["knowledgeContent"]}],personas:[],preparations:[],knowledgeSources:[],knowledgePieces:[],sources:[{type:"BOOK",path:null,content:"# Prepare Knowledge from Markdown\n\n-   PIPELINE URL `https://promptbook.studio/promptbook/prepare-knowledge-from-markdown.book`\n-   INPUT PARAMETER `{knowledgeContent}` Markdown document content\n-   OUTPUT PARAMETER `{knowledgePieces}` The knowledge JSON object\n\n## Knowledge\n\n<!-- TODO: [🍆] -FORMAT JSON -->\n\n```markdown\nYou are experienced data researcher, extract the important knowledge from the document.\n\n# Rules\n\n-   Make pieces of information concise, clear, and easy to understand\n-   One piece of information should be approximately 1 paragraph\n-   Divide the paragraphs by markdown horizontal lines ---\n-   Omit irrelevant information\n-   Group redundant information\n-   Write just extracted information, nothing else\n\n# The document\n\nTake information from this document:\n\n> {knowledgeContent}\n```\n\n`-> {knowledgePieces}`\n"}],sourceFile:"./books/prepare-knowledge-from-markdown.book"},{title:"Prepare Keywords",pipelineUrl:"https://promptbook.studio/promptbook/prepare-knowledge-keywords.book",formfactorName:"GENERIC",parameters:[{name:"knowledgePieceContent",description:"The content",isInput:true,isOutput:false},{name:"keywords",description:"Keywords separated by comma",isInput:false,isOutput:true}],tasks:[{taskType:"PROMPT_TASK",name:"knowledge",title:"Knowledge",content:"You are experienced data researcher, detect the important keywords in the document.\n\n# Rules\n\n-   Write just keywords separated by comma\n\n# The document\n\nTake information from this document:\n\n> {knowledgePieceContent}",resultingParameterName:"keywords",dependentParameterNames:["knowledgePieceContent"]}],personas:[],preparations:[],knowledgeSources:[],knowledgePieces:[],sources:[{type:"BOOK",path:null,content:"# Prepare Keywords\n\n-   PIPELINE URL `https://promptbook.studio/promptbook/prepare-knowledge-keywords.book`\n-   INPUT PARAMETER `{knowledgePieceContent}` The content\n-   OUTPUT PARAMETER `{keywords}` Keywords separated by comma\n\n## Knowledge\n\n<!-- TODO: [🍆] -FORMAT JSON -->\n\n```markdown\nYou are experienced data researcher, detect the important keywords in the document.\n\n# Rules\n\n-   Write just keywords separated by comma\n\n# The document\n\nTake information from this document:\n\n> {knowledgePieceContent}\n```\n\n`-> {keywords}`\n"}],sourceFile:"./books/prepare-knowledge-keywords.book"},{title:"Prepare Knowledge-piece Title",pipelineUrl:"https://promptbook.studio/promptbook/prepare-knowledge-title.book",formfactorName:"GENERIC",parameters:[{name:"knowledgePieceContent",description:"The content",isInput:true,isOutput:false},{name:"title",description:"The title of the document",isInput:false,isOutput:true}],tasks:[{taskType:"PROMPT_TASK",name:"knowledge",title:"Knowledge",content:"You are experienced content creator, write best title for the document.\n\n# Rules\n\n-   Write just title, nothing else\n-   Write maximum 5 words for the title\n\n# The document\n\n> {knowledgePieceContent}",resultingParameterName:"title",expectations:{words:{min:1,max:8}},dependentParameterNames:["knowledgePieceContent"]}],personas:[],preparations:[],knowledgeSources:[],knowledgePieces:[],sources:[{type:"BOOK",path:null,content:"# Prepare Knowledge-piece Title\n\n-   PIPELINE URL `https://promptbook.studio/promptbook/prepare-knowledge-title.book`\n-   INPUT PARAMETER `{knowledgePieceContent}` The content\n-   OUTPUT PARAMETER `{title}` The title of the document\n\n## Knowledge\n\n-   EXPECT MIN 1 WORD\n-   EXPECT MAX 8 WORDS\n\n```markdown\nYou are experienced content creator, write best title for the document.\n\n# Rules\n\n-   Write just title, nothing else\n-   Write maximum 5 words for the title\n\n# The document\n\n> {knowledgePieceContent}\n```\n\n`-> {title}`\n"}],sourceFile:"./books/prepare-knowledge-title.book"},{title:"Prepare Persona",pipelineUrl:"https://promptbook.studio/promptbook/prepare-persona.book",formfactorName:"GENERIC",parameters:[{name:"availableModels",description:"List of available model names together with their descriptions as JSON",isInput:true,isOutput:false},{name:"personaDescription",description:"Description of the persona",isInput:true,isOutput:false},{name:"modelsRequirements",description:"Specific requirements for the model",isInput:false,isOutput:true}],tasks:[{taskType:"PROMPT_TASK",name:"make-model-requirements",title:"Make modelRequirements",content:"You are an experienced AI engineer, you need to find the best models for virtual assistants:\n\n## Example\n\n```json\n[\n  {\n  \"modelName\": \"gpt-4o\",\n  \"systemMessage\": \"You are experienced AI engineer and helpful assistant.\",\n  \"temperature\": 0.7\n  },\n  {\n    \"modelName\": \"claude-3-5-sonnet\",\n    \"systemMessage\": \"You are a friendly and knowledgeable chatbot.\",\n    \"temperature\": 0.5\n  }\n]\n```\n\n## Instructions\n\n-   Your output format is JSON array\n-   Sort best-fitting models first\n-   Omit any models that are not suitable\n-   Write just the JSON, no other text should be present\n-   Array contain items with following keys:\n    -   `modelName`: The name of the model to use\n    -   `systemMessage`: The system message to provide context to the model\n    -   `temperature`: The sampling temperature to use\n\n### Key `modelName`\n\nHere are the available models:\n\n```json\n{availableModels}\n```\n\n### Key `systemMessage`\n\nThe system message is used to communicate instructions or provide context to the model at the beginning of a conversation. It is displayed in a different format compared to user messages, helping the model understand its role in the conversation. The system message typically guides the model's behavior, sets the tone, or specifies desired output from the model. By utilizing the system message effectively, users can steer the model towards generating more accurate and relevant responses.\n\nFor example:\n\n> You are an experienced AI engineer and helpful assistant.\n\n> You are a friendly and knowledgeable chatbot.\n\n### Key `temperature`\n\nThe sampling temperature, between 0 and 1. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. If set to 0, the model will use log probability to automatically increase the temperature until certain thresholds are hit.\n\nYou can pick a value between 0 and 2. For example:\n\n-   `0.1`: Low temperature, extremely conservative and deterministic\n-   `0.5`: Medium temperature, balanced between conservative and creative\n-   `1.0`: High temperature, creative and bit random\n-   `1.5`: Very high temperature, extremely creative and often chaotic and unpredictable\n-   `2.0`: Maximum temperature, completely random and unpredictable, for some extreme creative use cases\n\n# The assistant\n\nTake this description of the persona:\n\n> {personaDescription}",resultingParameterName:"modelsRequirements",format:"JSON",dependentParameterNames:["availableModels","personaDescription"]}],personas:[],preparations:[],knowledgeSources:[],knowledgePieces:[],sources:[{type:"BOOK",path:null,content:"# Prepare Persona\n\n-   PIPELINE URL `https://promptbook.studio/promptbook/prepare-persona.book`\n-   INPUT PARAMETER `{availableModels}` List of available model names together with their descriptions as JSON\n-   INPUT PARAMETER `{personaDescription}` Description of the persona\n-   OUTPUT PARAMETER `{modelsRequirements}` Specific requirements for the model\n\n## Make modelRequirements\n\n-   FORMAT JSON\n\n```markdown\nYou are an experienced AI engineer, you need to find the best models for virtual assistants:\n\n## Example\n\n\\`\\`\\`json\n[\n  {\n  \"modelName\": \"gpt-4o\",\n  \"systemMessage\": \"You are experienced AI engineer and helpful assistant.\",\n  \"temperature\": 0.7\n  },\n  {\n    \"modelName\": \"claude-3-5-sonnet\",\n    \"systemMessage\": \"You are a friendly and knowledgeable chatbot.\",\n    \"temperature\": 0.5\n  }\n]\n\\`\\`\\`\n\n## Instructions\n\n-   Your output format is JSON array\n-   Sort best-fitting models first\n-   Omit any models that are not suitable\n-   Write just the JSON, no other text should be present\n-   Array contain items with following keys:\n    -   `modelName`: The name of the model to use\n    -   `systemMessage`: The system message to provide context to the model\n    -   `temperature`: The sampling temperature to use\n\n### Key `modelName`\n\nHere are the available models:\n\n\\`\\`\\`json\n{availableModels}\n\\`\\`\\`\n\n### Key `systemMessage`\n\nThe system message is used to communicate instructions or provide context to the model at the beginning of a conversation. It is displayed in a different format compared to user messages, helping the model understand its role in the conversation. The system message typically guides the model's behavior, sets the tone, or specifies desired output from the model. By utilizing the system message effectively, users can steer the model towards generating more accurate and relevant responses.\n\nFor example:\n\n> You are an experienced AI engineer and helpful assistant.\n\n> You are a friendly and knowledgeable chatbot.\n\n### Key `temperature`\n\nThe sampling temperature, between 0 and 1. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. If set to 0, the model will use log probability to automatically increase the temperature until certain thresholds are hit.\n\nYou can pick a value between 0 and 2. For example:\n\n-   `0.1`: Low temperature, extremely conservative and deterministic\n-   `0.5`: Medium temperature, balanced between conservative and creative\n-   `1.0`: High temperature, creative and bit random\n-   `1.5`: Very high temperature, extremely creative and often chaotic and unpredictable\n-   `2.0`: Maximum temperature, completely random and unpredictable, for some extreme creative use cases\n\n# The assistant\n\nTake this description of the persona:\n\n> {personaDescription}\n```\n\n`-> {modelsRequirements}`\n"}],sourceFile:"./books/prepare-persona.book"},{title:"Prepare Title",pipelineUrl:"https://promptbook.studio/promptbook/prepare-title.book",formfactorName:"GENERIC",parameters:[{name:"book",description:"The book to prepare the title for",isInput:true,isOutput:false},{name:"title",description:"Best title for the book",isInput:false,isOutput:true}],tasks:[{taskType:"PROMPT_TASK",name:"make-title",title:"Make title",content:"Make best title for given text which describes the workflow:\n\n## Rules\n\n-   Write just title, nothing else\n-   Title should be concise and clear - Write maximum ideally 2 words, maximum 5 words\n-   Title starts with emoticon\n-   Title should not mention the input and output of the workflow but the main purpose of the workflow\n    _For example, not \"✍ Convert Knowledge-piece to title\" but \"✍ Title\"_\n\n## The workflow\n\n> {book}",resultingParameterName:"title",expectations:{words:{min:1,max:8},lines:{min:1,max:1}},dependentParameterNames:["book"]}],personas:[],preparations:[],knowledgeSources:[],knowledgePieces:[],sources:[{type:"BOOK",path:null,content:"# Prepare Title\n\n-   PIPELINE URL `https://promptbook.studio/promptbook/prepare-title.book`\n-   INPUT PARAMETER `{book}` The book to prepare the title for\n-   OUTPUT PARAMETER `{title}` Best title for the book\n\n## Make title\n\n-   EXPECT MIN 1 Word\n-   EXPECT MAX 8 Words\n-   EXPECT EXACTLY 1 Line\n\n```markdown\nMake best title for given text which describes the workflow:\n\n## Rules\n\n-   Write just title, nothing else\n-   Title should be concise and clear - Write maximum ideally 2 words, maximum 5 words\n-   Title starts with emoticon\n-   Title should not mention the input and output of the workflow but the main purpose of the workflow\n    _For example, not \"✍ Convert Knowledge-piece to title\" but \"✍ Title\"_\n\n## The workflow\n\n> {book}\n```\n\n`-> {title}`\n"}],sourceFile:"./books/prepare-title.book"}];
@@ -36811,7 +37122,8 @@
         requirements = await importReferencedFiles(requirements);
         requirements = appendMcpServers(requirements, agentSource);
         requirements = appendNonCommitmentContent(requirements, parseResult);
-        return appendExampleInteractions(requirements, parseResult);
+        requirements = appendExampleInteractions(requirements, parseResult);
+        return appendUnknownCommitmentContent(requirements, parseResult);
     }
     /**
      * Imports text files referenced by IMPORT commitments and appends their transformed content to the system message.
@@ -36933,6 +37245,36 @@
         }
         return appendSystemMessageSection(requirements, nonCommitmentContent);
     }
+    /**
+     * Appends unknown commitment blocks as final extra context without applying commitment side effects.
+     *
+     * @param requirements - Current requirements snapshot.
+     * @param parseResult - Parsed source including unknown commitment blocks.
+     * @returns Requirements with unknown commitment context appended at the end of the system message.
+     *
+     * @private internal utility of `augmentAgentModelRequirementsFromSource`
+     */
+    function appendUnknownCommitmentContent(requirements, parseResult) {
+        const unknownCommitmentContent = getUnknownCommitmentContent(parseResult);
+        if (!unknownCommitmentContent) {
+            return requirements;
+        }
+        return appendSystemMessageSection(requirements, unknownCommitmentContent);
+    }
+    /**
+     * Joins unknown commitment blocks into their final extra-context representation.
+     *
+     * @param parseResult - Parsed source including unknown commitment blocks.
+     * @returns Unknown commitment source blocks in their original order.
+     *
+     * @private internal utility of `appendUnknownCommitmentContent`
+     */
+    function getUnknownCommitmentContent(parseResult) {
+        return parseResult.unknownCommitments
+            .map((commitment) => commitment.source)
+            .filter(Boolean)
+            .join('\n\n');
+    }
     /**
      * Collects plain-text lines that were not parsed as commitments and should still become part of the final system message.
      *
@@ -37472,12 +37814,12 @@
         await promises.rm(finishedWorkspacePath, { recursive: true, force: true });
         await promises.mkdir(finishedWorkspacePath, { recursive: true });
         const relativePaths = [
-            toPortablePath$1(path.join(finishedRelativeWorkspacePath, AGENT_TEAM_CONVERSATION_MANIFEST_FILE_NAME)),
+            toPortablePath$2(path.join(finishedRelativeWorkspacePath, AGENT_TEAM_CONVERSATION_MANIFEST_FILE_NAME)),
         ];
         await promises.rename(activeManifestPath, path.join(finishedWorkspacePath, AGENT_TEAM_CONVERSATION_MANIFEST_FILE_NAME));
         for (const transcriptFileName of transcriptFileNames) {
             await promises.rename(path.join(activeWorkspacePath, transcriptFileName), path.join(finishedWorkspacePath, transcriptFileName));
-            relativePaths.push(toPortablePath$1(path.join(finishedRelativeWorkspacePath, transcriptFileName)));
+            relativePaths.push(toPortablePath$2(path.join(finishedRelativeWorkspacePath, transcriptFileName)));
         }
         await promises.rm(activeWorkspacePath, { recursive: true, force: true });
         return { relativePaths };
@@ -37494,7 +37836,7 @@
                 .sort((firstFileName, secondFileName) => firstFileName.localeCompare(secondFileName));
         }
         catch (error) {
-            if (isFileNotFoundError$2(error)) {
+            if (isFileNotFoundError$3(error)) {
                 return [];
             }
             throw error;
@@ -37509,7 +37851,7 @@
             return true;
         }
         catch (error) {
-            if (isFileNotFoundError$2(error)) {
+            if (isFileNotFoundError$3(error)) {
                 return false;
             }
             throw error;
@@ -37518,11 +37860,204 @@
     /**
      * Converts a filesystem-relative path into a portable Git path.
      */
+    function toPortablePath$2(path) {
+        return path.replace(/\\/gu, '/');
+    }
+    /**
+     * Returns true when one filesystem error indicates a missing path.
+     */
+    function isFileNotFoundError$3(error) {
+        return Boolean(error &&
+            typeof error === 'object' &&
+            'code' in error &&
+            (error.code === 'ENOENT' || error.code === 'ENOTDIR'));
+    }
+
+    // Note: [💞] This file defines the shared planned-message sidecar convention rather than one standalone entity.
+    /**
+     * Relative directory holding the planned-message sidecar of each queued message.
+     *
+     * @private internal convention shared by the Agents Server and agent-folder runner
+     */
+    const AGENT_PLANNED_MESSAGES_DIRECTORY_PATH = path.join(AGENT_MESSAGES_DIRECTORY_PATH, 'planned');
+    /**
+     * Command actions an agent can request from its planned-message sidecar.
+     *
+     * @private internal convention shared by the Agents Server and agent-folder runner
+     */
+    const AGENT_PLANNED_MESSAGE_COMMAND_ACTIONS = ['set', 'cancel'];
+    /**
+     * Creates the relative planned-message sidecar path of one queued message.
+     *
+     * @param messageFileName - File name of the queued `.book` message.
+     * @returns Relative path of the sidecar inside the agent folder.
+     *
+     * @private internal convention shared by the Agents Server and agent-folder runner
+     */
+    function createAgentPlannedMessagesSidecarPath(messageFileName) {
+        return path.join(AGENT_PLANNED_MESSAGES_DIRECTORY_PATH, `${createAgentMessageSidecarBaseName(messageFileName)}.json`);
+    }
+    /**
+     * Parses one untrusted planned-message sidecar written back by a coding harness.
+     *
+     * A malformed sidecar never fails the already answered chat, so this returns `null` instead of throwing.
+     *
+     * @param sidecarContent - Raw file content read from the agent folder.
+     * @returns Normalized sidecar, or `null` when it cannot be used.
+     *
+     * @private internal convention shared by the Agents Server and agent-folder runner
+     */
+    function parseAgentPlannedMessagesSidecar(sidecarContent) {
+        let parsedSidecar;
+        try {
+            parsedSidecar = JSON.parse(sidecarContent);
+        }
+        catch (_a) {
+            return null;
+        }
+        if (!parsedSidecar || typeof parsedSidecar !== 'object' || Array.isArray(parsedSidecar)) {
+            return null;
+        }
+        const sidecar = parsedSidecar;
+        if (sidecar.version !== 1 || typeof sidecar.agentPermanentId !== 'string') {
+            return null;
+        }
+        return {
+            version: 1,
+            agentPermanentId: sidecar.agentPermanentId,
+            currentPlannedMessages: normalizeAgentPlannedMessageSnapshots(sidecar.currentPlannedMessages),
+            commands: normalizeAgentPlannedMessageCommands(sidecar.commands),
+        };
+    }
+    /**
+     * Keeps only the commands whose action is understood by the planned-message actions.
+     *
+     * @param rawCommands - Untrusted `commands` value read from one sidecar.
+     * @returns Commands that can be dispatched, in their original order.
+     *
+     * @private internal utility of `parseAgentPlannedMessagesSidecar`
+     */
+    function normalizeAgentPlannedMessageCommands(rawCommands) {
+        if (!Array.isArray(rawCommands)) {
+            return [];
+        }
+        return rawCommands.filter(isAgentPlannedMessageCommand);
+    }
+    /**
+     * Checks whether one untrusted sidecar entry names a supported planned-message action.
+     *
+     * @param value - Untrusted command entry.
+     * @returns `true` when the entry can be dispatched.
+     *
+     * @private internal utility of `parseAgentPlannedMessagesSidecar`
+     */
+    function isAgentPlannedMessageCommand(value) {
+        if (!value || typeof value !== 'object' || Array.isArray(value)) {
+            return false;
+        }
+        const action = value.action;
+        return (typeof action === 'string' &&
+            AGENT_PLANNED_MESSAGE_COMMAND_ACTIONS.includes(action));
+    }
+    /**
+     * Keeps only the already planned messages that can be shown to the agent.
+     *
+     * @param rawSnapshots - Untrusted `currentPlannedMessages` value read from one sidecar.
+     * @returns Planned-message snapshots with the fields required for display and cancellation.
+     *
+     * @private internal utility of `parseAgentPlannedMessagesSidecar`
+     */
+    function normalizeAgentPlannedMessageSnapshots(rawSnapshots) {
+        if (!Array.isArray(rawSnapshots)) {
+            return [];
+        }
+        return rawSnapshots.filter(isAgentPlannedMessageSnapshot).map(createNormalizedAgentPlannedMessageSnapshot);
+    }
+    /**
+     * Normalizes the optional fields of one already planned message.
+     *
+     * @param snapshot - Planned-message entry with the required identity fields.
+     * @returns Snapshot with a usable repeat interval and message.
+     *
+     * @private internal utility of `parseAgentPlannedMessagesSidecar`
+     */
+    function createNormalizedAgentPlannedMessageSnapshot(snapshot) {
+        const intervalMs = Number(snapshot.intervalMs);
+        return {
+            timeoutId: snapshot.timeoutId,
+            dueAt: snapshot.dueAt,
+            message: typeof snapshot.message === 'string' ? snapshot.message : null,
+            intervalMs: Number.isFinite(intervalMs) && intervalMs > 0 ? Math.floor(intervalMs) : null,
+        };
+    }
+    /**
+     * Checks whether one untrusted sidecar entry describes an already planned message.
+     *
+     * @param value - Untrusted planned-message entry.
+     * @returns `true` when the entry can be shown and cancelled.
+     *
+     * @private internal utility of `parseAgentPlannedMessagesSidecar`
+     */
+    function isAgentPlannedMessageSnapshot(value) {
+        return Boolean(value &&
+            typeof value === 'object' &&
+            typeof value.timeoutId === 'string' &&
+            typeof value.dueAt === 'string');
+    }
+
+    /**
+     * Loads the planned-message sidecar the Agents Server prepared for one queued message.
+     *
+     * @param projectPath - Absolute path of the current agent runner folder.
+     * @param queuedMessage - Queued message currently being answered.
+     * @returns Sidecar details for the prompt, or `null` outside Agents Server-managed runs.
+     */
+    async function loadAgentPlannedMessagesSidecar(projectPath, queuedMessage) {
+        const relativeSidecarPath = createAgentPlannedMessagesSidecarPath(queuedMessage.fileName);
+        const sidecarContent = await readOptionalTextFile$2(path.join(projectPath, relativeSidecarPath));
+        if (sidecarContent === null) {
+            return null;
+        }
+        const sidecar = parseAgentPlannedMessagesSidecar(sidecarContent);
+        if (!sidecar) {
+            return null;
+        }
+        return {
+            relativeSidecarPath: toPortablePath$1(relativeSidecarPath),
+            currentPlannedMessages: sidecar.currentPlannedMessages,
+        };
+    }
+    /**
+     * Reads one text file and treats a missing planned-message sidecar as absent.
+     *
+     * @param path - Absolute sidecar path.
+     * @returns File content, or `null` when the sidecar does not exist.
+     */
+    async function readOptionalTextFile$2(path) {
+        try {
+            return await promises.readFile(path, 'utf-8');
+        }
+        catch (error) {
+            if (isFileNotFoundError$2(error)) {
+                return null;
+            }
+            throw error;
+        }
+    }
+    /**
+     * Converts a filesystem-relative path to the portable form used in prompts.
+     *
+     * @param path - Relative path inside the agent folder.
+     * @returns Path with forward slashes.
+     */
     function toPortablePath$1(path) {
         return path.replace(/\\/gu, '/');
     }
     /**
      * Returns true when one filesystem error indicates a missing path.
+     *
+     * @param error - Caught filesystem failure.
+     * @returns `true` for missing-path errors.
      */
     function isFileNotFoundError$2(error) {
         return Boolean(error &&
@@ -37537,7 +38072,7 @@
     async function loadAgentTeamConversationWorkspace(projectPath, queuedMessage) {
         const relativeWorkspacePath = createAgentTeamConversationWorkspacePath(queuedMessage.fileName);
         const manifestPath = path.join(projectPath, relativeWorkspacePath, AGENT_TEAM_CONVERSATION_MANIFEST_FILE_NAME);
-        const manifestContent = await readOptionalTextFile(manifestPath);
+        const manifestContent = await readOptionalTextFile$1(manifestPath);
         if (manifestContent === null) {
             return null;
         }
@@ -37565,7 +38100,7 @@
     /**
      * Reads one text file and treats a missing team workspace as absent.
      */
-    async function readOptionalTextFile(path) {
+    async function readOptionalTextFile$1(path) {
         try {
             return await promises.readFile(path, 'utf-8');
         }
@@ -37632,6 +38167,233 @@
         return `/agents/${encodeURIComponent(agentId)}/projects`;
     }
 
+    /**
+     * Parses every structured event out of one coding-harness runtime log.
+     *
+     * The local agent runner streams the answering harness output into a live runtime log file, one
+     * JSON event per line, optionally prefixed by shell noise. Lines without a usable JSON object are
+     * skipped so a partially written or interleaved log never breaks its consumers.
+     *
+     * @param logText - Raw runtime log content.
+     * @returns Structured events in the order they were streamed.
+     * @private internal utility of the agent-message runtime
+     */
+    function parseAgentMessageRuntimeLogEvents(logText) {
+        if (!logText) {
+            return [];
+        }
+        const events = [];
+        for (const line of logText.split(/\r?\n/u)) {
+            const event = parseAgentMessageRuntimeLogEvent(line);
+            if (event) {
+                events.push(event);
+            }
+        }
+        return events;
+    }
+    /**
+     * Parses one runtime log line into a structured event when it embeds JSON.
+     *
+     * @param line - One raw runtime log line.
+     * @returns Structured event, or `null` when the line carries no JSON object.
+     * @private internal helper of `parseAgentMessageRuntimeLogEvents`
+     */
+    function parseAgentMessageRuntimeLogEvent(line) {
+        const jsonStartIndex = line.indexOf('{');
+        if (jsonStartIndex === -1) {
+            return null;
+        }
+        try {
+            const parsedEvent = JSON.parse(line.slice(jsonStartIndex).trim());
+            if (typeof parsedEvent !== 'object' || parsedEvent === null || Array.isArray(parsedEvent)) {
+                return null;
+            }
+            return parsedEvent;
+        }
+        catch (_a) {
+            return null;
+        }
+    }
+
+    /**
+     * Matches one project directory name following the agent `projects/` folder in a file path or command.
+     *
+     * Both path separators are accepted because the local runner answers messages on Unix and Windows,
+     * and JSON-encoded payloads escape backslashes.
+     *
+     * @private internal constant of agent-message touched projects
+     */
+    const TOUCHED_PROJECT_PATH_REGEX = new RegExp(`${AGENT_PROJECTS_DIRECTORY_PATH}[\\\\/]+([^\\\\/"'\\s,;:]+)`, 'giu');
+    /**
+     * Resolves which projects one coding harness touched while answering a single message.
+     *
+     * The runtime log streams what the harness really did, so a project counts as touched when the
+     * harness named it in a tool invocation — reading, searching, running, or editing files inside
+     * `projects/<project-name>/`. Only tool payloads are inspected: tool results and assistant
+     * narration are ignored so a project merely mentioned in the conversation is never reported.
+     *
+     * Every candidate is matched against the projects that really exist, which both filters prompt
+     * placeholders such as `projects/<project-name>/` and keeps the reported names canonical.
+     *
+     * @param options - Raw runtime log content and the project directory names of the agent.
+     * @returns Touched project names in the canonical spelling, ordered by first appearance.
+     * @private internal utility of the agent-message runtime
+     */
+    function resolveAgentMessageTouchedProjectNames(options) {
+        const canonicalProjectNames = createCanonicalProjectNameLookup(options.knownProjectNames);
+        if (canonicalProjectNames.size === 0) {
+            return [];
+        }
+        const touchedProjectNames = new Set();
+        for (const event of parseAgentMessageRuntimeLogEvents(options.logText)) {
+            for (const toolInvocationText of resolveRuntimeLogEventToolInvocationTexts(event)) {
+                for (const candidateProjectName of resolveCandidateProjectNames(toolInvocationText)) {
+                    const canonicalProjectName = canonicalProjectNames.get(candidateProjectName.toLowerCase());
+                    if (canonicalProjectName !== undefined) {
+                        touchedProjectNames.add(canonicalProjectName);
+                    }
+                }
+            }
+        }
+        return Array.from(touchedProjectNames);
+    }
+    /**
+     * Indexes the existing project directory names by their lower-cased form.
+     *
+     * @param knownProjectNames - Project directory names of the agent.
+     * @returns Lookup from the lower-cased name to its canonical spelling.
+     * @private internal helper of `resolveAgentMessageTouchedProjectNames`
+     */
+    function createCanonicalProjectNameLookup(knownProjectNames) {
+        const canonicalProjectNames = new Map();
+        for (const knownProjectName of knownProjectNames) {
+            const normalizedProjectName = knownProjectName.trim();
+            if (normalizedProjectName.length > 0) {
+                canonicalProjectNames.set(normalizedProjectName.toLowerCase(), normalizedProjectName);
+            }
+        }
+        return canonicalProjectNames;
+    }
+    /**
+     * Collects the texts of every tool invocation described by one runtime log event.
+     *
+     * Claude Code reports tool invocations as `tool_use` content blocks, while Codex reports executed
+     * commands and file changes as items — both carry the paths the harness worked with.
+     *
+     * @param event - One structured runtime log event.
+     * @returns Texts that may contain project paths.
+     * @private internal helper of `resolveAgentMessageTouchedProjectNames`
+     */
+    function resolveRuntimeLogEventToolInvocationTexts(event) {
+        var _a, _b, _c;
+        const toolInvocationTexts = [];
+        for (const contentBlock of ((_a = event.message) === null || _a === void 0 ? void 0 : _a.content) || []) {
+            if (contentBlock.type === 'tool_use' && contentBlock.input) {
+                toolInvocationTexts.push(serializeToolInput(contentBlock.input));
+            }
+        }
+        if (typeof ((_b = event.item) === null || _b === void 0 ? void 0 : _b.command) === 'string') {
+            toolInvocationTexts.push(event.item.command);
+        }
+        for (const fileChange of ((_c = event.item) === null || _c === void 0 ? void 0 : _c.changes) || []) {
+            if (typeof fileChange.path === 'string') {
+                toolInvocationTexts.push(fileChange.path);
+            }
+        }
+        return toolInvocationTexts;
+    }
+    /**
+     * Serializes one tool input payload into scannable text.
+     *
+     * @param toolInput - Tool arguments of one harness tool invocation.
+     * @returns Serialized payload, or an empty string when it cannot be serialized.
+     * @private internal helper of `resolveAgentMessageTouchedProjectNames`
+     */
+    function serializeToolInput(toolInput) {
+        try {
+            return JSON.stringify(toolInput);
+        }
+        catch (_a) {
+            return '';
+        }
+    }
+    /**
+     * Extracts every project directory name mentioned right after the agent `projects/` folder.
+     *
+     * @param toolInvocationText - One tool payload, command, or changed path.
+     * @returns Candidate project directory names.
+     * @private internal helper of `resolveAgentMessageTouchedProjectNames`
+     */
+    function resolveCandidateProjectNames(toolInvocationText) {
+        const candidateProjectNames = [];
+        const projectPathRegex = new RegExp(TOUCHED_PROJECT_PATH_REGEX.source, TOUCHED_PROJECT_PATH_REGEX.flags);
+        let projectPathMatch = projectPathRegex.exec(toolInvocationText);
+        while (projectPathMatch !== null) {
+            const candidateProjectName = projectPathMatch[1];
+            if (candidateProjectName) {
+                candidateProjectNames.push(candidateProjectName);
+            }
+            projectPathMatch = projectPathRegex.exec(toolInvocationText);
+        }
+        return candidateProjectNames;
+    }
+
+    /**
+     * Resolves which agent projects one answered message viewed or edited.
+     *
+     * The runtime log is deleted as soon as the harness run finishes, so this must be called while
+     * the log still exists — the Agents Server later shows the reported projects as chips below the
+     * answer. Reporting touched projects is best-effort telemetry: an unreadable log or projects
+     * folder simply yields no projects instead of failing the already answered message.
+     *
+     * @param options - Agent folder path and the live runtime log path of the answered message.
+     * @returns Touched project directory names, ordered by first appearance in the run.
+     */
+    async function resolveTouchedAgentProjects(options) {
+        const [logText, knownProjectNames] = await Promise.all([
+            readOptionalTextFile(options.runtimeLogPath),
+            listAgentProjectDirectoryNames(options.projectPath),
+        ]);
+        return resolveAgentMessageTouchedProjectNames({ logText, knownProjectNames });
+    }
+    /**
+     * Lists the direct project directories of one agent folder.
+     *
+     * @param projectPath - Absolute path of the local agent folder.
+     * @returns Project directory names, or an empty list when the agent has no projects folder.
+     *
+     * @private helper of `resolveTouchedAgentProjects`
+     */
+    async function listAgentProjectDirectoryNames(projectPath) {
+        try {
+            const projectsRootEntries = await promises.readdir(path.join(projectPath, AGENT_PROJECTS_DIRECTORY_PATH), {
+                withFileTypes: true,
+            });
+            return projectsRootEntries
+                .filter((projectsRootEntry) => projectsRootEntry.isDirectory())
+                .map((projectDirectoryEntry) => projectDirectoryEntry.name);
+        }
+        catch (_a) {
+            return [];
+        }
+    }
+    /**
+     * Reads one text file and treats a missing runtime log as "nothing was recorded".
+     *
+     * @param filePath - Absolute path of the file to read.
+     * @returns File content, or `null` when it cannot be read.
+     *
+     * @private helper of `resolveTouchedAgentProjects`
+     */
+    async function readOptionalTextFile(filePath) {
+        try {
+            return await promises.readFile(filePath, 'utf-8');
+        }
+        catch (_a) {
+            return null;
+        }
+    }
+
     // Note: [💞] Ignore a discrepancy between file name and entity name
     /**
      * File suffix appended to one answered message book to store its run report sidecar.
@@ -37911,10 +38673,11 @@
         const { projectPath, options: runOptions, runner, actualRunnerModel, queuedMessage, uiHandle, isSharedDashboard, } = options;
         const agentSystemMessage = await loadLocalAgentSystemMessage(projectPath);
         const teamWorkspace = await loadAgentTeamConversationWorkspace(projectPath, queuedMessage);
+        const plannedMessagesSidecar = await loadAgentPlannedMessagesSidecar(projectPath, queuedMessage);
         const agentServerRuntimeApi = resolveAgentProjectRuntimePromptApi(projectPath);
         const prompt = buildAgentMessagePrompt(queuedMessage.relativePath, agentSystemMessage, {
             projectRuntimeApi: agentServerRuntimeApi,
-            goalChatRuntimeApi: agentServerRuntimeApi,
+            plannedMessagesSidecar: plannedMessagesSidecar || undefined,
             projectsUrlPath: resolveAgentProjectsUrlPath(projectPath),
             teamWorkspace: teamWorkspace || undefined,
         });
@@ -37935,21 +38698,29 @@
             uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.setCurrentScriptPath(scriptPath);
         }
         uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.startCapturingAgentOutput();
+        const executionStartedAt = new Date().toISOString();
         let promptRunResult;
+        let touchedProjectNames = [];
         try {
             try {
-                promptRunResult = await withPromptRuntimeLog(scriptPath, async (logPath) => await runPromptWithTestFeedback({
-                    runner,
-                    prompt,
-                    scriptPath,
-                    projectPath,
-                    promptLabel: queuedMessage.relativePath,
-                    logPath,
-                    preserveArtifactsOnSuccess: false,
-                    onAttemptStarted: (attemptCount) => {
-                        uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.setAttempt(attemptCount);
-                    },
-                }), { preserveArtifactsOnSuccess: false });
+                promptRunResult = await withPromptRuntimeLog(scriptPath, async (logPath) => {
+                    const runResult = await runPromptWithTestFeedback({
+                        runner,
+                        prompt,
+                        scriptPath,
+                        projectPath,
+                        promptLabel: queuedMessage.relativePath,
+                        logPath,
+                        preserveArtifactsOnSuccess: false,
+                        onAttemptStarted: (attemptCount) => {
+                            uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.setAttempt(attemptCount);
+                        },
+                    });
+                    // Note: The runtime log is deleted right after this handler, so the projects this
+                    //       answer worked with must be resolved while the log still exists.
+                    touchedProjectNames = await resolveTouchedAgentProjects({ projectPath, runtimeLogPath: logPath });
+                    return runResult;
+                }, { preserveArtifactsOnSuccess: false });
             }
             catch (error) {
                 throw withAgentWatchErrorContext(error, {
@@ -37963,6 +38734,7 @@
         finally {
             uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.stopCapturingAgentOutput();
         }
+        const executionFinishedAt = new Date().toISOString();
         await normalizeLineEndingsForAgentRound(projectPath, runOptions, roundChangedFilesSnapshot);
         const finishedTeamWorkspace = await finalizeAgentTeamConversationWorkspace({
             projectPath,
@@ -37981,6 +38753,11 @@
                 modelName: actualRunnerModel,
                 loginMethod: promptRunResult.loginMethod,
                 usage: promptRunResult.usage,
+                executionTiming: {
+                    startedAt: executionStartedAt,
+                    finishedAt: executionFinishedAt,
+                },
+                ...(touchedProjectNames.length === 0 ? {} : { touchedProjectNames }),
             },
         });
         await commitAnsweredMessageIfEnabled({
@@ -39673,24 +40450,12 @@
             -   @@@
             -   Keep in mind the DRY _(don't repeat yourself)_ principle.
             -   Do a proper analysis of the current functionality before you start implementing.
-            -   Add the changes into the [changelog](changelog/_current-preversion.md)
+            -   Add the changes into the [changelog](CHANGELOG.md)
+            -   Update the [README](README.md) if needed.
+            -   Update the [AGENTS.md](AGENTS.md) for the next job to be done if it makes sense.
         `),
             isDefaultProjectTemplate: true,
         },
-        {
-            id: 'agents-server',
-            relativeFilePath: path.join(PROMPTS_TEMPLATES_DIRECTORY_PATH, 'agents-server.md'),
-            slugPrefix: 'agents-server',
-            content: _spaceTrim.spaceTrim(`
-            -   @@@
-            -   Keep in mind the DRY _(don't repeat yourself)_ principle.
-            -   Do a proper analysis of the current functionality before you start implementing.
-            -   You are working with the [Agents Server](apps/agents-server)
-            -   If you need to do the database migration, do it
-            -   Add the changes into the [changelog](changelog/_current-preversion.md)
-        `),
-            isDefaultProjectTemplate: false,
-        },
     ];
     /**
      * Project-agnostic coder templates that `ptbk coder init` should materialize in any repository.
@@ -40782,6 +41547,10 @@
             console.info(colors__default["default"].gray(`✔ ${definition.label} ${installedVersion} is up to date.`));
             return;
         }
+        if (installationState === 'installed') {
+            console.info(colors__default["default"].gray(`✔ ${definition.label} ${installedVersion} is installed. Skipped checking for updates.`));
+            return;
+        }
         if (installationState === 'unknown') {
             console.info(colors__default["default"].gray(`✔ ${definition.label} ${installedVersion} is installed, the newest version could not be checked.`));
             return;
@@ -40995,20 +41764,20 @@
     // Note: [🟡] Code for CLI npm package version comparison [isNpmPackageVersionOutdated](src/cli/cli-commands/common/npm/isNpmPackageVersionOutdated.ts) should never be published outside of `@promptbook/cli`
 
     /**
-     * Detects whether one CLI coding harness is installed globally and whether it is up to date.
+     * Detects whether one CLI coding harness is installed globally and, when enabled, whether it is up to date.
      *
-     * Note: `$` is used to indicate that this function is not a pure function - it runs the harness command and queries npm
+     * Note: `$` is used to indicate that this function is not a pure function - it runs the harness command and may query npm
      *
      * @private internal utility of `promptbookCli`
      */
-    async function $checkHarnessInstallation(definition) {
+    async function $checkHarnessInstallation(definition, isHarnessUpdateCheckEnabled = true) {
         const [installedVersion, latestVersion] = await Promise.all([
             $resolveInstalledHarnessVersion(definition),
-            $resolveLatestNpmPackageVersion(definition.npmPackageName),
+            isHarnessUpdateCheckEnabled ? $resolveLatestNpmPackageVersion(definition.npmPackageName) : Promise.resolve(null),
         ]);
         return {
             definition,
-            installationState: resolveHarnessInstallationState(installedVersion, latestVersion),
+            installationState: resolveHarnessInstallationState(installedVersion, latestVersion, isHarnessUpdateCheckEnabled),
             installedVersion,
             latestVersion,
         };
@@ -41016,10 +41785,13 @@
     /**
      * Derives the installation state from the detected versions.
      */
-    function resolveHarnessInstallationState(installedVersion, latestVersion) {
+    function resolveHarnessInstallationState(installedVersion, latestVersion, isHarnessUpdateCheckEnabled) {
         if (installedVersion === null) {
             return 'not-installed';
         }
+        if (!isHarnessUpdateCheckEnabled) {
+            return 'installed';
+        }
         if (latestVersion === null) {
             return 'unknown';
         }
@@ -41030,8 +41802,8 @@
     // Note: [🟡] Code for CLI harness installation check [$checkHarnessInstallation](src/cli/cli-commands/common/harness/$checkHarnessInstallation.ts) should never be published outside of `@promptbook/cli`
 
     /**
-     * Checks that every given CLI coding harness is installed globally and up to date and offers to
-     * install or update the ones which are not.
+     * Checks that every given CLI coding harness is installed globally and, when enabled, up to date.
+     * Offers to install missing harnesses and update outdated ones.
      *
      * Harness names which are `undefined`, for example when no `--harness` is selected in a dry run,
      * are ignored so that every call site can pass its raw selection.
@@ -41040,13 +41812,13 @@
      *
      * @private internal utility of `promptbookCli`
      */
-    async function $ensureHarnessInstallations(harnessNames) {
+    async function $ensureHarnessInstallations(harnessNames, isHarnessUpdateCheckEnabled = true) {
         const definitions = resolveCheckedHarnessDefinitions(harnessNames);
         if (definitions.length === 0) {
             return;
         }
         // Note: Detection of all harnesses runs in parallel, the questions have to be asked one by one
-        const statuses = await Promise.all(definitions.map((definition) => $checkHarnessInstallation(definition)));
+        const statuses = await Promise.all(definitions.map((definition) => $checkHarnessInstallation(definition, isHarnessUpdateCheckEnabled)));
         for (const status of statuses) {
             await $applyHarnessInstallationStatus(status);
         }
@@ -41060,6 +41832,27 @@
     }
     // Note: [🟡] Code for CLI harness installation orchestration [$ensureHarnessInstallations](src/cli/cli-commands/common/harness/$ensureHarnessInstallations.ts) should never be published outside of `@promptbook/cli`
 
+    /**
+     * Registers the shared `--no-harness-update` option on a `ptbk coder` command that uses a coding harness.
+     *
+     * @private internal utility of `promptbookCli`
+     */
+    function addHarnessUpdateOption(command) {
+        command.option('--no-harness-update', 'Skip checking whether globally installed coding harnesses are up to date');
+    }
+    /**
+     * Converts the Commander harness-update flag into the normalized harness-check option.
+     *
+     * @private internal utility of `promptbookCli`
+     */
+    function normalizeHarnessUpdateCliOptions(cliOptions) {
+        return {
+            isHarnessUpdateCheckEnabled: cliOptions.harnessUpdate,
+        };
+    }
+    // Note: [🟡] Code for CLI harness update options [harnessUpdateCliOptions](src/cli/cli-commands/common/harnessUpdateCliOptions.ts) should never be published outside of `@promptbook/cli`
+    // Note: [💞] Ignore a discrepancy between file name and exported helper names
+
     /**
      * Relative path to the Promptbook Coder quick-reference file initialized in project roots.
      *
@@ -41622,14 +42415,16 @@
                 - CODING_AGENT_GIT_EMAIL
                 - CODING_AGENT_GIT_SIGNING_KEY
 
-                Checks that the coding harnesses are installed globally and up to date:
+                Checks that the coding harnesses are installed globally and up to date unless \`--no-harness-update\` is used:
                 ${block(listCheckedHarnessLabels())}
 
                 ${block(CODER_GIT_SYNC_DESCRIPTION)}
             `));
         addCoderGitSyncOptions(command);
+        addHarnessUpdateOption(command);
         command.action(handleActionErrors(async (cliOptions) => {
             const gitSync = normalizeCoderGitSyncCliOptions(cliOptions);
+            const { isHarnessUpdateCheckEnabled } = normalizeHarnessUpdateCliOptions(cliOptions);
             const projectPath = process.cwd();
             // Note: Import the git synchronization dynamically to keep the CLI fast for runs without `--commit`
             const { $commitCoderChanges, $startCoderGitSync } = await Promise.resolve().then(function () { return coderGitSync; });
@@ -41642,7 +42437,7 @@
                 commitScope,
                 commitMessage: 'Initialize Promptbook Coder',
             });
-            await $ensureHarnessInstallations(CODER_INIT_CHECKED_HARNESS_NAMES);
+            await $ensureHarnessInstallations(CODER_INIT_CHECKED_HARNESS_NAMES, isHarnessUpdateCheckEnabled);
         }));
     }
     /**
@@ -41681,13 +42476,16 @@
             - Reports the answer of the harness, the response time and the reported usage
             - Starts the hourly/weekly quota window before you need it, so it is already refreshing when you do
             - Leaves the project exactly as it was — nothing is read, written, changed or committed
+            - Checks that the selected harness is installed globally and up to date unless --no-harness-update is used
             - Use --no-ui to stream the raw harness output instead of only the compact result
         `));
         addPromptRunnerSelectionOptions(command);
+        addHarnessUpdateOption(command);
         addPromptRunnerRuntimeOptions(command);
         command.action(handleActionErrors(async (cliOptions) => {
             const runnerOptions = normalizePromptRunnerSelectionCliOptions(cliOptions, { isAgentRequired: true });
-            await $ensureHarnessInstallations([runnerOptions.agentName]);
+            const { isHarnessUpdateCheckEnabled } = normalizeHarnessUpdateCliOptions(cliOptions);
+            await $ensureHarnessInstallations([runnerOptions.agentName], isHarnessUpdateCheckEnabled);
             // Note: Import the ping dynamically to avoid loading heavy dependencies until needed
             const { pingCoderHarness } = await Promise.resolve().then(function () { return pingCoderHarness$1; });
             const { printCoderPingResult } = await Promise.resolve().then(function () { return printCoderPingResult$1; });
@@ -42178,7 +42976,7 @@
             - Optional --isolate runs every prompt in its own temporary git worktree and merges it back when verified
             - Optional --preserve-logs keeps temp prompt/log artifacts after successful rounds
             - Optional --no-ui keeps plain streaming console output for logging and debugging
-            - Checks that the selected harness is installed globally and up to date before the first prompt
+            - Checks that the selected harness is installed globally and up to date before the first prompt unless --no-harness-update is used
             - In interactive mode, checks local and global Promptbook CLI installations and offers to update them
             - Supports GPG signing of commits
             - Optional pre-coding test run that can stop or repair pre-existing failures
@@ -42188,6 +42986,7 @@
         `));
         command.option('--dry-run', 'Print unwritten prompts without executing', false);
         addPromptRunnerSelectionOptions(command);
+        addHarnessUpdateOption(command);
         command.option('--agent <agent-book-path>', 'Path to a .book file whose compiled system message is prepended to each coding prompt');
         command.option('--context <context-or-file>', 'Append extra instructions either inline or from a file path relative to the current project');
         command.option('--test <test-command...>', 'Run a verification command after each prompt; quote it when the command itself contains top-level flags');
@@ -42229,6 +43028,7 @@
             const runnerOptions = normalizePromptRunnerCliOptions(cliOptions, {
                 isAgentRequired: !dryRun,
             });
+            const { isHarnessUpdateCheckEnabled } = normalizeHarnessUpdateCliOptions(cliOptions);
             // [1] Parse the wait options and --no-auto:
             //   default: run automatically through the queue (no waiting between prompts)
             //   --no-auto: wait for user confirmation before each prompt (interactive mode)
@@ -42239,7 +43039,7 @@
             if (await $ensurePromptbookCliInstallations()) {
                 return process.exit(0);
             }
-            await $ensureHarnessInstallations([runnerOptions.agentName]);
+            await $ensureHarnessInstallations([runnerOptions.agentName], isHarnessUpdateCheckEnabled);
             const waitAfterPrompt = parseOptionalWaitDuration(waitAfterPromptValue, 0);
             const waitBetweenPrompts = parseOptionalWaitDuration(waitBetweenPromptsValue, 0);
             const waitAfterError = parseOptionalWaitDuration(waitAfterErrorValue, DEFAULT_WAIT_AFTER_ERROR_MS$1);
@@ -42333,7 +43133,7 @@
 
             Features:
             - Runs the same prompt processing as \`ptbk coder run\`
-            - Checks that the selected harness is installed globally and up to date on startup
+            - Checks that the selected harness is installed globally and up to date on startup unless --no-harness-update is used
             - Does not exit when all prompts are done; polls for new prompt files instead
             - Serves a kanban board at http://localhost:<port> for visual progress tracking
             - Allows editing prompt files directly from the browser (Trello-style)
@@ -42345,6 +43145,7 @@
             .default(DEFAULT_CODER_SERVER_PORT));
         command.option('--dry-run', 'Print unwritten prompts without executing', false);
         addPromptRunnerSelectionOptions(command);
+        addHarnessUpdateOption(command);
         command.option('--agent <agent-book-path>', 'Path to a .book file whose compiled system message is prepended to each coding prompt');
         command.option('--context <context-or-file>', 'Append extra instructions either inline or from a file path relative to the current project');
         command.option('--test <test-command...>', 'Run a verification command after each prompt; quote it when the command itself contains top-level flags');
@@ -42376,7 +43177,8 @@
             const runnerOptions = normalizePromptRunnerCliOptions(cliOptions, {
                 isAgentRequired: !dryRun,
             });
-            await $ensureHarnessInstallations([runnerOptions.agentName]);
+            const { isHarnessUpdateCheckEnabled } = normalizeHarnessUpdateCliOptions(cliOptions);
+            await $ensureHarnessInstallations([runnerOptions.agentName], isHarnessUpdateCheckEnabled);
             // [1] Parse the wait options and --no-auto (same logic as `coder run`)
             const waitForUser = !auto;
             const waitAfterPrompt = parseOptionalWaitDuration(waitAfterPromptValue, 0);
@@ -44300,23 +45102,27 @@
     // TODO: [🧠][♿] Maybe export through `@promptbook/node`
 
     /**
-     * Attempts to locate the specified application on a Windows system by searching common installation directories.
+     * Attempts to locate the specified application on a Windows system by searching PATH and common installation directories.
      * Returns the path to the executable if found, or null otherwise.
      *
      * @private within the repository
      */
     async function locateAppOnWindows({ appName, windowsSuffix, }) {
         try {
-            const prefixes = [
+            const EXECUTABLE_FILENAME = windowsSuffix.replace(/^.*[\\/]/, '');
+            const PATH_EXECUTABLE_PATHS = (process.env.PATH || '')
+                .split(path.delimiter)
+                .filter(Boolean)
+                .map((pathPrefix) => path.join(pathPrefix, EXECUTABLE_FILENAME));
+            const INSTALLATION_EXECUTABLE_PATHS = [
                 process.env.LOCALAPPDATA,
                 path.join(process.env.LOCALAPPDATA || '', 'Programs'),
                 process.env.PROGRAMFILES,
                 process.env['PROGRAMFILES(X86)'],
-            ];
-            for (const prefix of prefixes) {
-                const path = prefix + windowsSuffix;
-                if (await isExecutable(path, $provideFilesystemForNode())) {
-                    return path;
+            ].map((pathPrefix) => pathPrefix + windowsSuffix);
+            for (const executablePath of [...PATH_EXECUTABLE_PATHS, ...INSTALLATION_EXECUTABLE_PATHS]) {
+                if (await isExecutable(executablePath, $provideFilesystemForNode())) {
+                    return executablePath;
                 }
             }
             throw new Error(`Can not locate app ${appName} on Windows.`);
@@ -75709,6 +76515,10 @@
      * Constant for prompts dir.
      */
     const PROMPTS_DIR$1 = path.join(process.cwd(), 'prompts');
+    /**
+     * Commit message for files changed by a successful or failed pre-coding test in repair mode.
+     */
+    const PRE_CODING_TEST_CHANGES_COMMIT_MESSAGE = 'test: Apply changes made by pre-coding tests';
     /**
      * Main entry point for running prompts with the selected agent.
      *
@@ -76032,6 +76842,7 @@
             });
             await ensureWorkingTreeClean();
         }
+        const testBeforeCommitScope = await captureTestBeforeCommitScopeIfNeeded(runOptions);
         uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.startCapturingAgentOutput();
         const testBeforeResult = await runTestBefore({
             testCommand: runOptions.testCommand,
@@ -76040,6 +76851,11 @@
         }).finally(() => {
             uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.stopCapturingAgentOutput();
         });
+        await commitTestBeforeChangesIfNeeded({
+            runOptions,
+            testBeforeCommitScope,
+            waitForRequestedPause,
+        });
         if (testBeforeResult.isPassed) {
             return hasWaitedForStart;
         }
@@ -76088,6 +76904,38 @@
         });
         return updatedHasWaitedForStart;
     }
+    /**
+     * Captures the files present before a `yes-and-fix` pre-coding test, so only changes made by that test can be committed.
+     */
+    async function captureTestBeforeCommitScopeIfNeeded(runOptions) {
+        if (runOptions.testBefore !== 'yes-and-fix' || runOptions.noCommit) {
+            return undefined;
+        }
+        return captureCoderCommitScope(process.cwd());
+    }
+    /**
+     * Commits files changed by a `yes-and-fix` pre-coding test before the coder continues to a queued or repair prompt.
+     */
+    async function commitTestBeforeChangesIfNeeded(options) {
+        const { runOptions, testBeforeCommitScope, waitForRequestedPause } = options;
+        if (!testBeforeCommitScope) {
+            return;
+        }
+        const relevantPaths = await resolveCoderCommitScopePaths(testBeforeCommitScope);
+        if (relevantPaths.length === 0) {
+            return;
+        }
+        await waitForRequestedPause({
+            checkpointLabel: 'committing changes made by pre-coding tests',
+            phase: 'verifying',
+            statusMessage: 'Committing changes made by pre-coding tests...',
+        });
+        await commitChanges(PRE_CODING_TEST_CHANGES_COMMIT_MESSAGE, {
+            autoPush: runOptions.autoPush,
+            projectPath: testBeforeCommitScope.projectPath,
+            relevantPaths,
+        });
+    }
     /**
      * Creates a pause waiter that keeps the progress display and rich UI in sync.
      */