@promptbook/cli 0.114.0-10 → 0.114.0-12

package/esm/index.es.js

@@ -4,7 +4,7 @@ import _spaceTrim, { spaceTrim as spaceTrim$1 } from 'spacetrim';
 import { writeFile, stat, mkdir, readFile, readdir, rm, cp, lstat, symlink, rename, unlink, appendFile, realpath, copyFile, access, constants, watch, rmdir } from 'fs/promises';
 import { join, delimiter, relative, basename, resolve, dirname, isAbsolute, extname } from 'path';
 import { createHash, randomBytes } from 'crypto';
-import { spawn } from 'child_process';
+import { spawn, spawnSync } from 'child_process';
 import moment from 'moment';
 import * as fs from 'fs';
 import { createWriteStream, mkdirSync, writeFileSync, statSync, readFileSync, existsSync, promises } from 'fs';
@@ -48,7 +48,7 @@ const BOOK_LANGUAGE_VERSION = '2.0.0';
  * @generated
  * @see https://github.com/webgptorg/promptbook
  */
-const PROMPTBOOK_ENGINE_VERSION = '0.114.0-10';
+const PROMPTBOOK_ENGINE_VERSION = '0.114.0-12';
 /**
  * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
  * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -20307,6 +20307,30 @@ const COMMITMENT_REGISTRY = [
 // 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.
  *
@@ -20364,13 +20388,15 @@ function parseAgentSourceWithCommitments(agentSource) {
         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;
@@ -20384,25 +20410,11 @@ function parseAgentSourceWithCommitments(agentSource) {
         // 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
@@ -20411,22 +20423,14 @@ function parseAgentSourceWithCommitments(agentSource) {
             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$1(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,
@@ -20436,52 +20440,90 @@ function parseAgentSourceWithCommitments(agentSource) {
                 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$1(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$1(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$1(currentCommitment.sourceLines.join('\n')),
+        });
+        return;
+    }
+    commitments.push({
+        type: currentCommitment.type,
+        content: spaceTrim$1(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:
@@ -24751,14 +24793,90 @@ const PTBK_CODER_LOG_FILE_ENV_NAME = 'PTBK_CODER_LOG_FILE';
  * 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$1(`
+              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$1(`
+    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
+
+    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"
+    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.
@@ -24814,6 +24932,38 @@ function describeTempScriptKind(scriptPath) {
     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 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.
  */
@@ -24836,12 +24986,12 @@ function printLiveScriptChunk(chunk, source, shouldPrintLiveOutput) {
 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 = 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;
@@ -24900,8 +25050,9 @@ async function runBashScriptWithOutput(options) {
             const failure = new Error(spaceTrim$1(output) || `Command "bash ${scriptPathPosix}" exited with code ${code}`);
             settleWithLog(`failed with exit code ${code !== null && code !== void 0 ? code : 'unknown'}`, () => reject(failure), failure);
         };
+        // 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);
@@ -25762,6 +25913,35 @@ function isGitHubCopilotArgumentLimitError(error) {
         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;
+    }
+    spawnSync('taskkill.exe', ['/PID', commandProcess.pid.toString(), '/T', '/F'], {
+        stdio: 'ignore',
+        windowsHide: true,
+    });
+}
+
 /**
  * Maximum number of output characters included in thrown error messages.
  */
@@ -25804,15 +25984,16 @@ async function runScriptUntilMarkerIdle(options) {
     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 = 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;
@@ -25854,15 +26035,16 @@ async function runScriptUntilMarkerIdle(options) {
             });
         };
         /**
-         * 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.
             }
         };
         /**
@@ -25921,7 +26103,11 @@ async function runScriptUntilMarkerIdle(options) {
             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);
@@ -25930,8 +26116,9 @@ async function runScriptUntilMarkerIdle(options) {
                 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);
@@ -36801,7 +36988,8 @@ async function augmentAgentModelRequirementsFromSource(requirements, parseResult
     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.
@@ -36923,6 +37111,36 @@ function appendNonCommitmentContent(requirements, parseResult) {
     }
     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.
  *
@@ -39663,24 +39881,12 @@ const DEFAULT_CODER_PROMPT_TEMPLATE_DEFINITIONS = [
             -   @@@
             -   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: join(PROMPTS_TEMPLATES_DIRECTORY_PATH, 'agents-server.md'),
-        slugPrefix: 'agents-server',
-        content: spaceTrim$1(`
-            -   @@@
-            -   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.
@@ -40772,6 +40978,10 @@ async function $applyHarnessInstallationStatus(status) {
         console.info(colors.gray(`✔ ${definition.label} ${installedVersion} is up to date.`));
         return;
     }
+    if (installationState === 'installed') {
+        console.info(colors.gray(`✔ ${definition.label} ${installedVersion} is installed. Skipped checking for updates.`));
+        return;
+    }
     if (installationState === 'unknown') {
         console.info(colors.gray(`✔ ${definition.label} ${installedVersion} is installed, the newest version could not be checked.`));
         return;
@@ -40985,20 +41195,20 @@ function comparePrereleaseIdentifier(firstIdentifier, secondIdentifier) {
 // 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,
     };
@@ -41006,10 +41216,13 @@ async function $checkHarnessInstallation(definition) {
 /**
  * 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';
     }
@@ -41020,8 +41233,8 @@ function resolveHarnessInstallationState(installedVersion, latestVersion) {
 // 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.
@@ -41030,13 +41243,13 @@ function resolveHarnessInstallationState(installedVersion, latestVersion) {
  *
  * @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);
     }
@@ -41050,6 +41263,27 @@ function resolveCheckedHarnessDefinitions(harnessNames) {
 }
 // Note: [🟡] Code for CLI harness installation orchestration [$ensureHarnessInstallations](src/cli/cli-commands/common/harness/$ensureHarnessInstallations.ts) should never be published outside of `@promptbook/cli`
 
+/**
+ * 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.
  *
@@ -41612,14 +41846,16 @@ function $initializeCoderInitCommand(program) {
                 - 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; });
@@ -41632,7 +41868,7 @@ function $initializeCoderInitCommand(program) {
             commitScope,
             commitMessage: 'Initialize Promptbook Coder',
         });
-        await $ensureHarnessInstallations(CODER_INIT_CHECKED_HARNESS_NAMES);
+        await $ensureHarnessInstallations(CODER_INIT_CHECKED_HARNESS_NAMES, isHarnessUpdateCheckEnabled);
     }));
 }
 /**
@@ -41671,13 +41907,16 @@ function $initializeCoderPingCommand(program) {
             - 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; });
@@ -42168,7 +42407,7 @@ function $initializeCoderRunCommand(program) {
             - 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
@@ -42178,6 +42417,7 @@ function $initializeCoderRunCommand(program) {
         `));
     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');
@@ -42219,6 +42459,7 @@ function $initializeCoderRunCommand(program) {
         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)
@@ -42229,7 +42470,7 @@ function $initializeCoderRunCommand(program) {
         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);
@@ -42323,7 +42564,7 @@ function $initializeCoderServerCommand(program) {
 
             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)
@@ -42335,6 +42576,7 @@ function $initializeCoderServerCommand(program) {
         .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');
@@ -42366,7 +42608,8 @@ function $initializeCoderServerCommand(program) {
         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);
@@ -44290,23 +44533,27 @@ async function locateAppOnMacOs({ macOsName, }) {
 // 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(delimiter)
+            .filter(Boolean)
+            .map((pathPrefix) => join(pathPrefix, EXECUTABLE_FILENAME));
+        const INSTALLATION_EXECUTABLE_PATHS = [
             process.env.LOCALAPPDATA,
             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.`);
@@ -75699,6 +75946,10 @@ async function runTestBefore(options) {
  * Constant for prompts dir.
  */
 const PROMPTS_DIR$1 = 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.
  *
@@ -76022,6 +76273,7 @@ async function runTestBeforeIfNeeded(options) {
         });
         await ensureWorkingTreeClean();
     }
+    const testBeforeCommitScope = await captureTestBeforeCommitScopeIfNeeded(runOptions);
     uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.startCapturingAgentOutput();
     const testBeforeResult = await runTestBefore({
         testCommand: runOptions.testCommand,
@@ -76030,6 +76282,11 @@ async function runTestBeforeIfNeeded(options) {
     }).finally(() => {
         uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.stopCapturingAgentOutput();
     });
+    await commitTestBeforeChangesIfNeeded({
+        runOptions,
+        testBeforeCommitScope,
+        waitForRequestedPause,
+    });
     if (testBeforeResult.isPassed) {
         return hasWaitedForStart;
     }
@@ -76078,6 +76335,38 @@ async function runTestBeforeIfNeeded(options) {
     });
     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.
  */