@promptbook/cli 0.112.0 → 0.113.0-1

package/esm/index.es.js

@@ -59,7 +59,7 @@ const BOOK_LANGUAGE_VERSION = '2.0.0';
  * @generated
  * @see https://github.com/webgptorg/promptbook
  */
-const PROMPTBOOK_ENGINE_VERSION = '0.112.0';
+const PROMPTBOOK_ENGINE_VERSION = '0.113.0-1';
 /**
  * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
  * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -3299,6 +3299,28 @@ const DEFAULT_AGENTS_SERVER_NEXT_DIST_DIRECTORY_NAME = '.next';
  * @private internal constant of `ptbk agents-server`
  */
 const AGENTS_SERVER_BUILD_MAX_OLD_SPACE_MIB = 4096;
+/**
+ * Conservative Next.js build worker count used by CLI-owned Agents Server production builds.
+ *
+ * Standalone VPS self-updates build the replacement server while the current pm2 process is
+ * still serving traffic. Keeping Next's static workers serial avoids CPU-count-based memory
+ * spikes that can make the OS kill the build child with no normal exit code.
+ *
+ * @private internal constant of `ptbk agents-server`
+ */
+const AGENTS_SERVER_BUILD_WORKER_COUNT = 1;
+/**
+ * Maximum attempts for a Next.js build that was killed by the operating system.
+ *
+ * @private internal constant of `ptbk agents-server`
+ */
+const AGENTS_SERVER_BUILD_MAX_ATTEMPTS = 2;
+/**
+ * Signals that indicate the Next.js build may have been terminated by resource pressure.
+ *
+ * @private internal constant of `ptbk agents-server`
+ */
+const RETRYABLE_NEXT_BUILD_SIGNALS = new Set(['SIGKILL', null]);
 /**
  * Environment variable passed to the bundled Next app so webpack can resolve dependencies
  * installed beside `ptbk` even when the app sources are materialized into a project cache.
@@ -3306,6 +3328,12 @@ const AGENTS_SERVER_BUILD_MAX_OLD_SPACE_MIB = 4096;
  * @private internal constant of `ptbk agents-server`
  */
 const PTBK_AGENTS_SERVER_NODE_MODULES_PATH_ENV = 'PTBK_AGENTS_SERVER_NODE_MODULES_PATH';
+/**
+ * Environment variable consumed by `apps/agents-server/next.config.ts` to throttle build workers.
+ *
+ * @private internal constant of `ptbk agents-server`
+ */
+const PTBK_AGENTS_SERVER_BUILD_WORKER_COUNT_ENV = 'PTBK_AGENTS_SERVER_BUILD_WORKER_COUNT';
 /**
  * Environment variable used only by the CLI-owned production build.
  *
@@ -3506,6 +3534,7 @@ function createAgentsServerRuntimeEnvironment(environment, nodeModulesPath, opti
         ...environment,
         NODE_PATH: mergeNodePath(nodeModulesPath, environment.NODE_PATH),
         [PTBK_AGENTS_SERVER_NODE_MODULES_PATH_ENV]: nodeModulesPath,
+        [PTBK_AGENTS_SERVER_BUILD_WORKER_COUNT_ENV]: environment[PTBK_AGENTS_SERVER_BUILD_WORKER_COUNT_ENV] || String(AGENTS_SERVER_BUILD_WORKER_COUNT),
         ...(options.isNextValidationIgnored
             ? {
                 [PTBK_AGENTS_SERVER_IGNORE_NEXT_VALIDATION_ENV]: 'true',
@@ -3692,14 +3721,27 @@ async function writeAgentsServerMaterializedRuntimeCache(materializedRuntimeRoot
  * Runs the finite Next production build used by local Agents Server commands.
  */
 async function runNextBuild(options) {
-    await new Promise((resolveBuild, rejectBuild) => {
+    for (let attempt = 1; attempt <= AGENTS_SERVER_BUILD_MAX_ATTEMPTS; attempt++) {
+        const exitStatus = await runNextBuildAttempt(options);
+        if (exitStatus.code === 0) {
+            return;
+        }
+        if (attempt < AGENTS_SERVER_BUILD_MAX_ATTEMPTS && isNextBuildTerminationRetryable(exitStatus)) {
+            forwardBuildOutput(createNextBuildRetryMessage(exitStatus, attempt + 1), options.onBuildOutput);
+            continue;
+        }
+        throw createNextBuildExitError(exitStatus, attempt);
+    }
+}
+/**
+ * Runs one Next.js production build attempt and returns its exit status.
+ */
+async function runNextBuildAttempt(options) {
+    return await new Promise((resolveBuild, rejectBuild) => {
         var _a, _b;
         const buildProcess = spawn(process.execPath, [options.nextCliPath, 'build'], {
             cwd: options.appPath,
-            env: {
-                ...options.environment,
-                NODE_OPTIONS: mergeNodeOptionsWithHeapSize(options.environment.NODE_OPTIONS, AGENTS_SERVER_BUILD_MAX_OLD_SPACE_MIB),
-            },
+            env: createNextBuildProcessEnvironment(options.environment),
             stdio: ['ignore', 'pipe', 'pipe'],
         });
         (_a = buildProcess.stdout) === null || _a === void 0 ? void 0 : _a.on('data', (chunk) => {
@@ -3708,16 +3750,70 @@ async function runNextBuild(options) {
         (_b = buildProcess.stderr) === null || _b === void 0 ? void 0 : _b.on('data', (chunk) => {
             forwardBuildOutput(chunk.toString(), options.onBuildOutput);
         });
-        buildProcess.once('error', rejectBuild);
-        buildProcess.once('exit', (code) => {
-            if (code === 0) {
-                resolveBuild();
-                return;
-            }
-            rejectBuild(new Error(`next-build exited with code ${String(code)}.`));
+        buildProcess.once('error', (error) => {
+            rejectBuild(createNextBuildSpawnError(error));
+        });
+        buildProcess.once('close', (code, signal) => {
+            resolveBuild({ code, signal });
         });
     });
 }
+/**
+ * Creates the environment passed to the spawned Next.js build process.
+ */
+function createNextBuildProcessEnvironment(environment) {
+    return {
+        ...environment,
+        NODE_OPTIONS: mergeNodeOptionsWithHeapSize(environment.NODE_OPTIONS, AGENTS_SERVER_BUILD_MAX_OLD_SPACE_MIB),
+    };
+}
+/**
+ * Returns true when one failed build attempt is worth retrying.
+ */
+function isNextBuildTerminationRetryable(exitStatus) {
+    return exitStatus.code === null && RETRYABLE_NEXT_BUILD_SIGNALS.has(exitStatus.signal);
+}
+/**
+ * Creates one visible retry message for a killed Next.js build attempt.
+ */
+function createNextBuildRetryMessage(exitStatus, nextAttempt) {
+    return `\nAgents Server Next build was terminated by ${describeNextBuildExitStatus(exitStatus)}. Retrying attempt ${nextAttempt}/${AGENTS_SERVER_BUILD_MAX_ATTEMPTS}.\n`;
+}
+/**
+ * Creates a branded error for a failed Next.js build child process.
+ */
+function createNextBuildExitError(exitStatus, attemptCount) {
+    const lowMemoryHint = isNextBuildTerminationRetryable(exitStatus)
+        ? '\n\nThe build process was terminated by the operating system. On standalone VPS self-updates this usually means the host ran out of memory while Next.js was compiling or prerendering the app.'
+        : '';
+    return new NotAllowed(spaceTrim$1(`
+            Agents Server Next production build failed.
+
+            - Exit code: \`${String(exitStatus.code)}\`
+            - Signal: \`${String(exitStatus.signal)}\`
+            - Attempts: \`${String(attemptCount)}\`
+            ${lowMemoryHint}
+        `));
+}
+/**
+ * Creates a branded error for failures to start the Next.js build child process.
+ */
+function createNextBuildSpawnError(error) {
+    return new NotAllowed(spaceTrim$1(`
+            Cannot start the Agents Server Next production build.
+
+            ${error.message}
+        `));
+}
+/**
+ * Formats one Next.js build exit status for foreground logs.
+ */
+function describeNextBuildExitStatus(exitStatus) {
+    if (exitStatus.signal) {
+        return `signal \`${exitStatus.signal}\``;
+    }
+    return `exit code \`${String(exitStatus.code)}\``;
+}
 /**
  * Prepends `--max-old-space-size=<mib>` to `NODE_OPTIONS` unless the caller already set one.
  */
@@ -16448,6 +16544,70 @@ class MetaLinkCommitmentDefinition extends BaseCommitmentDefinition {
 }
 // Note: [💞] Ignore a discrepancy between file name and entity name
 
+/**
+ * META VISIBILITY commitment definition.
+ *
+ * The `META VISIBILITY` commitment stores whether an agent is public, private, or unlisted.
+ * Agents Server mirrors this value into the database for efficient filtering, but the book
+ * commitment remains the editable source of truth.
+ *
+ * @private Metadata-only commitment used by Agents Server.
+ */
+class MetaVisibilityCommitmentDefinition extends BaseCommitmentDefinition {
+    constructor() {
+        super('META VISIBILITY');
+    }
+    /**
+     * Short one-line description of META VISIBILITY.
+     */
+    get description() {
+        return 'Set whether the agent is private, unlisted, or public.';
+    }
+    /**
+     * Icon for this commitment.
+     */
+    get icon() {
+        return '👁️';
+    }
+    /**
+     * Markdown documentation for META VISIBILITY commitment.
+     */
+    get documentation() {
+        return spaceTrim$1(`
+            # META VISIBILITY
+
+            Sets the agent visibility used by Agents Server.
+
+            ## Allowed values
+
+            - \`PRIVATE\` - accessible only to signed-in users with access.
+            - \`UNLISTED\` - accessible by direct link but hidden from public listings.
+            - \`PUBLIC\` - visible in public listings and accessible by anyone.
+
+            ## Key aspects
+
+            - Does not modify the agent's behavior, system message, or tools.
+            - Whitespace and letter case are normalized when persisted.
+            - If multiple \`META VISIBILITY\` commitments are present, persistence keeps one normalized value.
+            - Agents Server mirrors the value into the database for filtering, but the book is the source of truth.
+
+            ## Example
+
+            \`\`\`book
+            Helpful Assistant
+
+            GOAL Be helpful and friendly.
+            META VISIBILITY PUBLIC
+            \`\`\`
+        `);
+    }
+    applyToAgentModelRequirements(requirements, content) {
+        // META VISIBILITY is metadata only and does not alter model requirements.
+        return requirements;
+    }
+}
+// Note: [💞] Ignore a discrepancy between file name and entity name
+
 /**
  * META VOICE commitment definition
  *
@@ -22943,31 +23103,65 @@ class UseSearchEngineCommitmentDefinition extends BaseCommitmentDefinition {
 // Note: [💞] Ignore a discrepancy between file name and entity name
 
 /**
- * This error type indicates that some limit was reached
+ * This error indicates that the promptbook in a markdown format cannot be parsed into a valid promptbook object
  *
  * @public exported from `@promptbook/core`
  */
-class LimitReachedError extends Error {
+class ParseError extends Error {
     constructor(message) {
         super(message);
-        this.name = 'LimitReachedError';
-        Object.setPrototypeOf(this, LimitReachedError.prototype);
+        this.name = 'ParseError';
+        Object.setPrototypeOf(this, ParseError.prototype);
     }
 }
+// TODO: Maybe split `ParseError` and `ApplyError`
 
 /**
- * This error indicates that the promptbook in a markdown format cannot be parsed into a valid promptbook object
+ * Supported visibility states for persisted agents.
  *
  * @public exported from `@promptbook/core`
  */
-class ParseError extends Error {
+const AGENT_VISIBILITY_VALUES = ['PRIVATE', 'UNLISTED', 'PUBLIC'];
+/**
+ * Returns `true` when the value is one of supported visibility states.
+ *
+ * @param value - Raw value to validate.
+ * @returns Whether the value is a valid `AgentVisibility`.
+ *
+ * @public exported from `@promptbook/core`
+ */
+function isAgentVisibility(value) {
+    return typeof value === 'string' && AGENT_VISIBILITY_VALUES.includes(value);
+}
+/**
+ * Normalizes raw visibility text into a supported value.
+ *
+ * @param value - Raw visibility value.
+ * @returns Normalized visibility, or `null` when invalid.
+ *
+ * @public exported from `@promptbook/core`
+ */
+function normalizeAgentVisibility(value) {
+    if (typeof value !== 'string') {
+        return null;
+    }
+    const normalized = value.trim().toUpperCase();
+    return isAgentVisibility(normalized) ? normalized : null;
+}
+// Note: [💞] Ignore a discrepancy between file name and entity name
+
+/**
+ * This error type indicates that some limit was reached
+ *
+ * @public exported from `@promptbook/core`
+ */
+class LimitReachedError extends Error {
     constructor(message) {
         super(message);
-        this.name = 'ParseError';
-        Object.setPrototypeOf(this, ParseError.prototype);
+        this.name = 'LimitReachedError';
+        Object.setPrototypeOf(this, LimitReachedError.prototype);
     }
 }
-// TODO: Maybe split `ParseError` and `ApplyError`
 
 /**
  * Maximum allowed source length for create-agent payloads.
@@ -25302,6 +25496,7 @@ const COMMITMENT_REGISTRY = [
     new MetaDomainCommitmentDefinition(),
     new MetaDisclaimerCommitmentDefinition(),
     new MetaInputPlaceholderCommitmentDefinition(),
+    new MetaVisibilityCommitmentDefinition(),
     new MetaCommitmentDefinition(),
     new MetaVoiceCommitmentDefinition(),
     new NoteCommitmentDefinition('NOTE'),
@@ -25753,6 +25948,7 @@ const META_COMMITMENT_APPLIERS = {
     'META COLOR': applyMetaColorContent,
     'META FONT': applyMetaFontContent,
     'META VOICE': applyMetaVoiceContent,
+    'META VISIBILITY': applyMetaVisibilityContent,
 };
 /**
  * Applies META-style commitments that mutate parsed profile metadata.
@@ -25782,6 +25978,10 @@ function applyGenericMetaCommitment(state, content) {
         applyMetaAvatarContent(state, metaValue);
         return;
     }
+    if (metaTypeRaw.toUpperCase() === 'VISIBILITY') {
+        applyMetaVisibilityContent(state, metaValue);
+        return;
+    }
     const metaType = normalizeTo_camelCase(metaTypeRaw);
     state.meta[metaType] = metaValue;
 }
@@ -25858,6 +26058,15 @@ function applyMetaFontContent(state, content) {
 function applyMetaVoiceContent(state, content) {
     state.meta.voice = spaceTrim$1(content);
 }
+/**
+ * Applies META VISIBILITY content into the normalized `meta.visibility` field.
+ */
+function applyMetaVisibilityContent(state, content) {
+    const visibility = normalizeAgentVisibility(content);
+    if (visibility) {
+        state.meta.visibility = visibility;
+    }
+}
 /**
  * Normalizes the separator in the content
  *
@@ -37430,7 +37639,7 @@ async function tickAgentMessages(options, tickOptions = {}) {
     validateAgentRunOptions(options);
     const projectPath = tickOptions.projectPath || process.cwd();
     let queueSnapshot = await loadAgentMessageQueueSnapshot(projectPath);
-    let queuedMessage = queueSnapshot.queuedMessages[0];
+    let queuedMessage = resolveSelectedQueuedMessage(queueSnapshot, tickOptions.queuedMessage);
     if (!queuedMessage) {
         announceNoQueuedMessages(tickOptions);
         return { isMessageProcessed: false };
@@ -37445,7 +37654,7 @@ async function tickAgentMessages(options, tickOptions = {}) {
     });
     if (autoPullTimestamp !== undefined) {
         queueSnapshot = await loadAgentMessageQueueSnapshot(projectPath);
-        queuedMessage = queueSnapshot.queuedMessages[0];
+        queuedMessage = resolveSelectedQueuedMessage(queueSnapshot, tickOptions.queuedMessage);
         if (!queuedMessage) {
             if (tickOptions.uiHandle && !((_b = tickOptions.uiPresentation) === null || _b === void 0 ? void 0 : _b.isSharedDashboard)) {
                 updateAgentRunUiForWatching(tickOptions.uiHandle, queueSnapshot);
@@ -37471,7 +37680,7 @@ async function tickAgentMessages(options, tickOptions = {}) {
             uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.updateProgress(((_e = tickOptions.uiPresentation) === null || _e === void 0 ? void 0 : _e.completedProgressStats) ||
                 createAgentQueueProgressSnapshot({
                     finishedMessageCount: queueSnapshot.finishedMessageCount + 1,
-                    queuedMessages: queueSnapshot.queuedMessages.slice(1),
+                    queuedMessages: removeQueuedMessageFromSnapshot(queueSnapshot, queuedMessage),
                 }));
             if ((_f = tickOptions.uiPresentation) === null || _f === void 0 ? void 0 : _f.completedAgentStatusLines) {
                 uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.setAgentStatusLines([...tickOptions.uiPresentation.completedAgentStatusLines]);
@@ -37483,7 +37692,9 @@ async function tickAgentMessages(options, tickOptions = {}) {
                 uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.setMessagePreviewLines([...tickOptions.uiPresentation.completedMessagePreviewLines]);
             }
             if ((_j = tickOptions.uiPresentation) === null || _j === void 0 ? void 0 : _j.completedMessagePreviewSections) {
-                uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.setMessagePreviewSections([...tickOptions.uiPresentation.completedMessagePreviewSections]);
+                uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.setMessagePreviewSections([
+                    ...tickOptions.uiPresentation.completedMessagePreviewSections,
+                ]);
             }
             uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.setStatusMessage('Message answered');
             uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.setPhase('done');
@@ -37511,6 +37722,21 @@ async function tickAgentMessages(options, tickOptions = {}) {
         printAgentGitIdentityTipAtProcessExitIfNeeded();
     }
 }
+/**
+ * Resolves either the explicitly selected queued message or the first available queue item.
+ */
+function resolveSelectedQueuedMessage(queueSnapshot, selectedQueuedMessage) {
+    if (!selectedQueuedMessage) {
+        return queueSnapshot.queuedMessages[0];
+    }
+    return queueSnapshot.queuedMessages.find((queuedMessage) => queuedMessage.relativePath === selectedQueuedMessage.relativePath);
+}
+/**
+ * Creates a progress queue list with the processed message removed from its original snapshot.
+ */
+function removeQueuedMessageFromSnapshot(queueSnapshot, processedQueuedMessage) {
+    return queueSnapshot.queuedMessages.filter((queuedMessage) => queuedMessage.relativePath !== processedQueuedMessage.relativePath);
+}
 /**
  * Runs the selected coding runner for one message and finalizes the answered file.
  */
@@ -37631,7 +37857,9 @@ function seedAgentRunUiHandle(uiHandle, options, runner, actualRunnerModel, queu
         return;
     }
     uiHandle.state.setCurrentPrompt(queuedMessage.relativePath);
-    uiHandle.state.setMessagePreviewLines([...((uiPresentation === null || uiPresentation === void 0 ? void 0 : uiPresentation.messagePreviewLines) || agentUiMetadata.latestUserMessageLines)]);
+    uiHandle.state.setMessagePreviewLines([
+        ...((uiPresentation === null || uiPresentation === void 0 ? void 0 : uiPresentation.messagePreviewLines) || agentUiMetadata.latestUserMessageLines),
+    ]);
     uiHandle.state.setPhase('loading');
     uiHandle.state.setStatusMessage('Preparing message');
 }
@@ -37910,12 +38138,16 @@ const LEGACY_STATUS_WIDTH = 9;
  * Watches all direct child agent repositories from the current directory in one shared session.
  */
 async function runMultipleAgentMessages(options, controls = {}) {
-    var _a;
+    var _a, _b;
     validateAgentRunOptions(options);
     validateAgentWatchOptions('ptbk agent-folder run-multiple', options);
     const rootPath = process.cwd();
     const shouldContinue = controls.shouldContinue || (() => just(true));
+    const queuePollIntervalMs = (_a = controls.queuePollIntervalMs) !== null && _a !== void 0 ? _a : MULTI_AGENT_QUEUE_POLL_INTERVAL_MS;
     const ignoreMatcher = createAgentIgnoreMatcher(options.ignorePatterns);
+    const isParallelMessageLimitConfigured = options.maxParallelMessages !== undefined;
+    const maxParallelMessageCount = normalizeMaxParallelMessageCount(options.maxParallelMessages);
+    const activeMessageTasksByKey = new Map();
     let githubSynchronizationTimestamp;
     let githubIgnoredRepositoryCount = 0;
     const autoPullTimestampsByProjectPath = new Map();
@@ -37930,7 +38162,7 @@ async function runMultipleAgentMessages(options, controls = {}) {
             if (!isWatchSessionInitialized) {
                 uiHandle = await initializeMultipleAgentRunUi(options);
                 isWatchSessionInitialized = true;
-                (_a = controls.onUiInitialized) === null || _a === void 0 ? void 0 : _a.call(controls, uiHandle);
+                (_b = controls.onUiInitialized) === null || _b === void 0 ? void 0 : _b.call(controls, uiHandle);
                 if (!uiHandle) {
                     console.info(colors.green('Watching direct child agent repositories for queued messages.'));
                 }
@@ -37953,14 +38185,19 @@ async function runMultipleAgentMessages(options, controls = {}) {
             let projectSummaries = projectSummariesResult.projectSummaries;
             lastObservedProjectCount = projectSummaries.length;
             let ignoredAgentCount = projectSummariesResult.ignoredProjectCount + githubIgnoredRepositoryCount;
-            const autoPullResult = await pullLatestChangesForLocalAgentRunnerProjectsIfNeeded({
-                rootPath,
-                runOptions: options,
-                uiHandle,
-                projectSummaries,
-                ignoredAgentCount,
-                autoPullTimestampsByProjectPath,
-            });
+            const autoPullResult = activeMessageTasksByKey.size === 0
+                ? await pullLatestChangesForLocalAgentRunnerProjectsIfNeeded({
+                    rootPath,
+                    runOptions: options,
+                    uiHandle,
+                    projectSummaries,
+                    ignoredAgentCount,
+                    autoPullTimestampsByProjectPath,
+                })
+                : {
+                    isAnyRepositoryPulled: false,
+                    pulledProjectPaths: new Set(),
+                };
             if (autoPullResult.isAnyRepositoryPulled) {
                 projectSummariesResult = await loadLocalAgentRunnerProjectSummaries(rootPath, {
                     includeMessagePreviews: Boolean(uiHandle),
@@ -37970,61 +38207,49 @@ async function runMultipleAgentMessages(options, controls = {}) {
                 lastObservedProjectCount = projectSummaries.length;
                 ignoredAgentCount = projectSummariesResult.ignoredProjectCount + githubIgnoredRepositoryCount;
             }
-            const queuedProjects = projectSummaries.filter((projectSummary) => projectSummary.queuedMessageCount > 0);
-            if (queuedProjects.length === 0) {
+            const availableParallelMessageSlots = Math.max(0, maxParallelMessageCount - activeMessageTasksByKey.size);
+            const queuedWorkItems = availableParallelMessageSlots > 0
+                ? selectQueuedWorkItems({
+                    projectSummaries,
+                    activeMessageTasksByKey,
+                    availableParallelMessageSlots,
+                    isParallelMessageLimitConfigured,
+                })
+                : [];
+            const answeringProjectPaths = createAnsweringProjectPaths(activeMessageTasksByKey, queuedWorkItems);
+            if (queuedWorkItems.length === 0 && activeMessageTasksByKey.size === 0) {
                 updateMultipleAgentRunUiForWatching(uiHandle, options, rootPath, projectSummaries, ignoredAgentCount);
-                await wait$3(MULTI_AGENT_QUEUE_POLL_INTERVAL_MS);
+                await wait$3(queuePollIntervalMs);
+                continue;
+            }
+            if (queuedWorkItems.length === 0) {
+                updateMultipleAgentRunUiForAnswering(uiHandle, options, rootPath, projectSummaries, answeringProjectPaths, ignoredAgentCount, activeMessageTasksByKey.size);
+                await waitForNextSchedulerTurn(activeMessageTasksByKey, queuePollIntervalMs);
                 continue;
             }
             if (!uiHandle) {
-                for (const queuedProject of queuedProjects) {
-                    console.info(colors.blue(`Processing ${formatProjectPath(rootPath, queuedProject.project.projectPath)} with ${queuedProject.localAgentName}.`));
+                for (const queuedWorkItem of queuedWorkItems) {
+                    console.info(colors.blue(`Processing ${formatProjectPath(rootPath, queuedWorkItem.projectSummary.project.projectPath)}/${queuedWorkItem.queuedMessage.relativePath} with ${queuedWorkItem.projectSummary.localAgentName}.`));
                 }
             }
-            const answeringProjectPaths = new Set(queuedProjects.map((queuedProject) => queuedProject.project.projectPath));
-            if (uiHandle) {
-                updateMultipleAgentRunUiForAnswering(uiHandle, options, rootPath, projectSummaries, answeringProjectPaths, ignoredAgentCount);
-            }
-            const tickResults = await Promise.allSettled(queuedProjects.map(async (queuedProject) => {
-                const tickRunOptions = createAgentRunOptionsForQueuedProjectTick({
-                    runOptions: options,
-                    isProjectPulledInCurrentIteration: autoPullResult.pulledProjectPaths.has(queuedProject.project.projectPath),
-                });
-                const tickResult = await tickAgentMessages(tickRunOptions, {
-                    isQuietWhenIdle: true,
-                    projectPath: queuedProject.project.projectPath,
+            updateMultipleAgentRunUiForAnswering(uiHandle, options, rootPath, projectSummaries, answeringProjectPaths, ignoredAgentCount, activeMessageTasksByKey.size + queuedWorkItems.length);
+            for (const queuedWorkItem of queuedWorkItems) {
+                startActiveAgentMessageTask({
+                    rootPath,
+                    options,
+                    queuedWorkItem,
+                    projectSummaries,
+                    answeringProjectPaths,
+                    ignoredAgentCount,
+                    autoPullResult,
+                    autoPullTimestampsByProjectPath,
+                    activeMessageTasksByKey,
+                    messageFailureTracker,
                     uiHandle,
-                    uiPresentation: uiHandle
-                        ? buildMultiAgentTickUiPresentation({
-                            rootPath,
-                            projectSummaries,
-                            answeringProjectPaths,
-                            ignoredAgentCount,
-                        })
-                        : undefined,
-                });
-                return {
-                    projectPath: queuedProject.project.projectPath,
-                    tickResult,
-                };
-            }));
-            for (const tickResult of tickResults) {
-                if (tickResult.status === 'fulfilled') {
-                    if (tickResult.value.tickResult.autoPullTimestamp !== undefined) {
-                        autoPullTimestampsByProjectPath.set(tickResult.value.projectPath, tickResult.value.tickResult.autoPullTimestamp);
-                    }
-                    if (tickResult.value.tickResult.isMessageProcessed) {
-                        messageFailureTracker.clearMessageFailure(tickResult.value.projectPath, tickResult.value.tickResult.queuedMessage);
-                    }
-                    continue;
-                }
-                await handleAgentWatchError({
-                    commandDisplayName: 'ptbk agent-folder run-multiple',
-                    logDirectoryPath: controls.watchErrorLogDirectoryPath || rootPath,
-                    error: tickResult.reason,
+                    watchErrorLogDirectoryPath: controls.watchErrorLogDirectoryPath || rootPath,
                 });
-                await messageFailureTracker.recordFailure(tickResult.reason);
             }
+            await waitForNextSchedulerTurn(activeMessageTasksByKey, queuePollIntervalMs);
         }
         catch (error) {
             await handleAgentWatchError({
@@ -38033,9 +38258,167 @@ async function runMultipleAgentMessages(options, controls = {}) {
                 error,
             });
             await messageFailureTracker.recordFailure(error);
-            await wait$3(MULTI_AGENT_QUEUE_POLL_INTERVAL_MS);
+            await wait$3(queuePollIntervalMs);
+        }
+    }
+    await waitForActiveMessageTasksToSettle(activeMessageTasksByKey);
+}
+/**
+ * Starts one selected queued-message harness task and records it until it settles.
+ */
+function startActiveAgentMessageTask(options) {
+    const { queuedWorkItem } = options;
+    const projectPath = queuedWorkItem.projectSummary.project.projectPath;
+    const messageKey = createAgentMessageTaskKey(projectPath, queuedWorkItem.queuedMessage);
+    const promise = runActiveAgentMessageTask({
+        rootPath: options.rootPath,
+        options: options.options,
+        queuedWorkItem,
+        projectSummaries: options.projectSummaries,
+        answeringProjectPaths: options.answeringProjectPaths,
+        ignoredAgentCount: options.ignoredAgentCount,
+        autoPullResult: options.autoPullResult,
+        autoPullTimestampsByProjectPath: options.autoPullTimestampsByProjectPath,
+        messageFailureTracker: options.messageFailureTracker,
+        uiHandle: options.uiHandle,
+        watchErrorLogDirectoryPath: options.watchErrorLogDirectoryPath,
+    }).finally(() => {
+        options.activeMessageTasksByKey.delete(messageKey);
+    });
+    options.activeMessageTasksByKey.set(messageKey, {
+        projectPath,
+        queuedMessage: queuedWorkItem.queuedMessage,
+        promise,
+    });
+}
+/**
+ * Runs one queued-message tick and folds its result back into shared watcher state.
+ */
+async function runActiveAgentMessageTask(options) {
+    const projectPath = options.queuedWorkItem.projectSummary.project.projectPath;
+    try {
+        const tickRunOptions = createAgentRunOptionsForQueuedProjectTick({
+            runOptions: options.options,
+            isProjectPulledInCurrentIteration: options.autoPullResult.pulledProjectPaths.has(projectPath),
+        });
+        const tickResult = await tickAgentMessages(tickRunOptions, {
+            isQuietWhenIdle: true,
+            projectPath,
+            queuedMessage: options.queuedWorkItem.queuedMessage,
+            uiHandle: options.uiHandle,
+            uiPresentation: options.uiHandle
+                ? buildMultiAgentTickUiPresentation({
+                    rootPath: options.rootPath,
+                    projectSummaries: options.projectSummaries,
+                    answeringProjectPaths: options.answeringProjectPaths,
+                    ignoredAgentCount: options.ignoredAgentCount,
+                })
+                : undefined,
+        });
+        if (tickResult.autoPullTimestamp !== undefined) {
+            options.autoPullTimestampsByProjectPath.set(projectPath, tickResult.autoPullTimestamp);
+        }
+        if (tickResult.isMessageProcessed) {
+            options.messageFailureTracker.clearMessageFailure(projectPath, tickResult.queuedMessage);
+        }
+    }
+    catch (error) {
+        await handleAgentWatchError({
+            commandDisplayName: 'ptbk agent-folder run-multiple',
+            logDirectoryPath: options.watchErrorLogDirectoryPath,
+            error,
+        });
+        await options.messageFailureTracker.recordFailure(error);
+    }
+}
+/**
+ * Selects the next queued messages that can be started without exceeding active harness capacity.
+ */
+function selectQueuedWorkItems(options) {
+    const activeProjectPaths = new Set(Array.from(options.activeMessageTasksByKey.values()).map((activeMessageTask) => activeMessageTask.projectPath));
+    const queuedProjectSummaries = options.projectSummaries.filter((projectSummary) => {
+        if (projectSummary.queuedMessageCount === 0) {
+            return false;
+        }
+        return options.isParallelMessageLimitConfigured || !activeProjectPaths.has(projectSummary.project.projectPath);
+    });
+    if (!options.isParallelMessageLimitConfigured) {
+        return queuedProjectSummaries
+            .map((projectSummary) => selectFirstInactiveQueuedWorkItem(projectSummary, options.activeMessageTasksByKey))
+            .filter((workItem) => workItem !== null);
+    }
+    const workItems = [];
+    for (let messageIndex = 0; workItems.length < options.availableParallelMessageSlots; messageIndex++) {
+        let isAnyMessageAtIndex = false;
+        for (const projectSummary of queuedProjectSummaries) {
+            const queuedMessage = projectSummary.queuedMessages[messageIndex];
+            if (!queuedMessage) {
+                continue;
+            }
+            isAnyMessageAtIndex = true;
+            if (options.activeMessageTasksByKey.has(createAgentMessageTaskKey(projectSummary.project.projectPath, queuedMessage))) {
+                continue;
+            }
+            workItems.push({ projectSummary, queuedMessage });
+            if (workItems.length >= options.availableParallelMessageSlots) {
+                return workItems;
+            }
+        }
+        if (!isAnyMessageAtIndex) {
+            return workItems;
         }
     }
+    return workItems;
+}
+/**
+ * Selects the first inactive queued message from a project while preserving legacy one-message-per-project behavior.
+ */
+function selectFirstInactiveQueuedWorkItem(projectSummary, activeMessageTasksByKey) {
+    const queuedMessage = projectSummary.queuedMessages.find((message) => !activeMessageTasksByKey.has(createAgentMessageTaskKey(projectSummary.project.projectPath, message)));
+    return queuedMessage ? { projectSummary, queuedMessage } : null;
+}
+/**
+ * Builds the set of project paths currently represented by active or newly scheduled harness tasks.
+ */
+function createAnsweringProjectPaths(activeMessageTasksByKey, queuedWorkItems) {
+    return new Set([
+        ...Array.from(activeMessageTasksByKey.values()).map((activeMessageTask) => activeMessageTask.projectPath),
+        ...queuedWorkItems.map((queuedWorkItem) => queuedWorkItem.projectSummary.project.projectPath),
+    ]);
+}
+/**
+ * Creates a stable scheduler key for one queued message file.
+ */
+function createAgentMessageTaskKey(projectPath, queuedMessage) {
+    return `${projectPath}\0${queuedMessage.relativePath}`;
+}
+/**
+ * Normalizes the maximum number of parallel queued-message tasks.
+ */
+function normalizeMaxParallelMessageCount(rawValue) {
+    const parsedValue = Number(rawValue);
+    if (!Number.isFinite(parsedValue) || parsedValue <= 0) {
+        return Number.POSITIVE_INFINITY;
+    }
+    return Math.floor(parsedValue);
+}
+/**
+ * Waits for either one active task to finish or the next queue polling interval.
+ */
+async function waitForNextSchedulerTurn(activeMessageTasksByKey, queuePollIntervalMs) {
+    if (activeMessageTasksByKey.size === 0) {
+        return;
+    }
+    await Promise.race([
+        ...Array.from(activeMessageTasksByKey.values()).map((activeMessageTask) => activeMessageTask.promise),
+        wait$3(queuePollIntervalMs),
+    ]);
+}
+/**
+ * Preserves previous shutdown behavior by letting active harness tasks finish before returning.
+ */
+async function waitForActiveMessageTasksToSettle(activeMessageTasksByKey) {
+    await Promise.allSettled(Array.from(activeMessageTasksByKey.values()).map((activeMessageTask) => activeMessageTask.promise));
 }
 /**
  * Creates the shared multi-agent rich UI when the terminal supports it.
@@ -38181,6 +38564,7 @@ async function loadLocalAgentRunnerProjectSummaries(rootPath, options) {
             project,
             localAgentName: localAgentIdentity.localAgentName,
             localAgentUrl: localAgentIdentity.localAgentUrl || formatProjectPath(rootPath, project.projectPath),
+            queuedMessages: queueSnapshot.queuedMessages,
             queuedMessageCount: queueSnapshot.queuedMessages.length,
             finishedMessageCount: queueSnapshot.finishedMessageCount,
             ...(queuedMessagePreview ? { queuedMessagePreview } : {}),
@@ -38212,14 +38596,16 @@ function updateMultipleAgentRunUiForWatching(uiHandle, options, rootPath, projec
 /**
  * Updates the shared UI while one or more child repositories are answering queued messages.
  */
-function updateMultipleAgentRunUiForAnswering(uiHandle, options, rootPath, projectSummaries, answeringProjectPaths, ignoredAgentCount) {
-    const activeProjectCount = projectSummaries.filter((projectSummary) => answeringProjectPaths.has(projectSummary.project.projectPath)).length;
+function updateMultipleAgentRunUiForAnswering(uiHandle, options, rootPath, projectSummaries, answeringProjectPaths, ignoredAgentCount, activeMessageCount) {
+    if (!uiHandle) {
+        return;
+    }
     setMultipleAgentRunUiConfig(uiHandle, options, projectSummaries.length, ignoredAgentCount);
     uiHandle.state.updateProgress(createMultiAgentQueueProgressSnapshot(projectSummaries));
     uiHandle.state.setCurrentPrompt('');
     uiHandle.state.setCurrentScriptPaths(buildMultiAgentScriptPaths(projectSummaries, answeringProjectPaths));
     uiHandle.state.setPhase('running');
-    uiHandle.state.setStatusMessage(`Answering ${activeProjectCount} queued message${activeProjectCount === 1 ? '' : 's'}`);
+    uiHandle.state.setStatusMessage(`Answering ${activeMessageCount} queued message${activeMessageCount === 1 ? '' : 's'}`);
     uiHandle.state.setDetailLines(buildMultiAgentAnsweringDetailLines(rootPath, projectSummaries, answeringProjectPaths));
     uiHandle.state.setAgentStatusLines(buildMultiAgentStatusLines(rootPath, projectSummaries, answeringProjectPaths));
     uiHandle.state.setAgentStatusTableRows(buildMultiAgentStatusTableRows(projectSummaries, answeringProjectPaths));
@@ -38521,6 +38907,12 @@ const DEFAULT_SPAWN_AGENT_RATE_LIMIT_WINDOW_MS = 10 * 60 * 1000;
  * @private shared Agents Server constant
  */
 const DEFAULT_LOCAL_AGENT_RUNNER_MAX_FAILED_ATTEMPTS = 3;
+/**
+ * Default maximum number of local runner harness instances allowed to answer queued messages at once.
+ *
+ * @private shared Agents Server constant
+ */
+const DEFAULT_LOCAL_AGENT_RUNNER_MAX_PARALLEL_MESSAGES = 3;
 /**
  * Stable keys used by the dedicated server-limits table.
  *
@@ -38535,6 +38927,7 @@ const SERVER_LIMIT_KEYS = {
     SPAWN_AGENT_RATE_LIMIT_MAX: 'SPAWN_AGENT_RATE_LIMIT_MAX',
     SPAWN_AGENT_RATE_LIMIT_WINDOW_MS: 'SPAWN_AGENT_RATE_LIMIT_WINDOW_MS',
     LOCAL_AGENT_RUNNER_MAX_FAILED_ATTEMPTS: 'LOCAL_AGENT_RUNNER_MAX_FAILED_ATTEMPTS',
+    LOCAL_AGENT_RUNNER_MAX_PARALLEL_MESSAGES: 'LOCAL_AGENT_RUNNER_MAX_PARALLEL_MESSAGES',
 };
 /**
  * Shared metadata for all server limits exposed in the admin UI and runtime loaders.
@@ -38630,6 +39023,17 @@ const SERVER_LIMIT_DEFINITIONS = [
         step: 1,
         legacyMetadataKeys: [],
     },
+    {
+        key: SERVER_LIMIT_KEYS.LOCAL_AGENT_RUNNER_MAX_PARALLEL_MESSAGES,
+        category: 'Local agent runner',
+        title: 'Max parallel harness instances',
+        description: 'Caps how many queued chat messages the local coding-agent harness may answer at the same time.',
+        unit: 'count',
+        defaultValue: DEFAULT_LOCAL_AGENT_RUNNER_MAX_PARALLEL_MESSAGES,
+        minimumValue: 1,
+        step: 1,
+        legacyMetadataKeys: [],
+    },
 ];
 /**
  * Fast lookup map used by server-limit validators and UI helpers.
@@ -38991,6 +39395,7 @@ function createLocalAgentRunOptions(options, localAgentRunnerLimits) {
         autoPull: false,
         autoClone: false,
         maxMessageProcessingFailures: localAgentRunnerLimits.maxFailedAttempts,
+        maxParallelMessages: localAgentRunnerLimits.maxParallelMessages,
     };
 }
 /**
@@ -39002,7 +39407,7 @@ async function waitForLocalAgentRunnerLimits(options) {
     while (options.state.isContinuing && Date.now() - startedAt < INTERNAL_SERVER_LIMITS_STARTUP_TIMEOUT_MS) {
         try {
             const limits = await fetchLocalAgentRunnerLimits(options);
-            logRunnerEvent(options.logStreams.runner, `Local agent runner max failed attempts: ${limits.maxFailedAttempts}.`);
+            logRunnerEvent(options.logStreams.runner, `Local agent runner limits: ${limits.maxFailedAttempts} failed attempt(s), ${limits.maxParallelMessages} parallel message(s).`);
             return limits;
         }
         catch (error) {
@@ -39013,6 +39418,7 @@ async function waitForLocalAgentRunnerLimits(options) {
     if (!options.state.isContinuing) {
         return {
             maxFailedAttempts: DEFAULT_LOCAL_AGENT_RUNNER_MAX_FAILED_ATTEMPTS,
+            maxParallelMessages: DEFAULT_LOCAL_AGENT_RUNNER_MAX_PARALLEL_MESSAGES,
         };
     }
     throw new NotAllowed(spaceTrim$1(`
@@ -39039,6 +39445,7 @@ async function fetchLocalAgentRunnerLimits(options) {
     const payload = (await response.json());
     return {
         maxFailedAttempts: normalizeLocalAgentRunnerMaxFailedAttempts(payload.maxFailedAttempts),
+        maxParallelMessages: normalizeLocalAgentRunnerMaxParallelMessages(payload.maxParallelMessages),
     };
 }
 /**
@@ -39051,6 +39458,16 @@ function normalizeLocalAgentRunnerMaxFailedAttempts(rawValue) {
     }
     return Math.floor(parsedValue);
 }
+/**
+ * Normalizes the local runner parallel message cap returned by the internal server route.
+ */
+function normalizeLocalAgentRunnerMaxParallelMessages(rawValue) {
+    const parsedValue = Number(rawValue);
+    if (!Number.isFinite(parsedValue) || parsedValue <= 0) {
+        return DEFAULT_LOCAL_AGENT_RUNNER_MAX_PARALLEL_MESSAGES;
+    }
+    return Math.floor(parsedValue);
+}
 /**
  * Starts periodic internal worker calls that queue and reconcile local message-folder jobs.
  */
@@ -40305,7 +40722,7 @@ async function ensureCoderGitignoreFile(projectPath) {
  */
 const DEFAULT_CODER_PACKAGE_JSON_SCRIPTS = {
     'coder:generate-boilerplates': 'ptbk coder generate-boilerplates --template ./prompts/templates/common.md',
-    'coder:run': 'ptbk coder run --harness openai-codex --model gpt-5.4 --thinking-level xhigh --agent agents/developer.book --context AGENTS.md',
+    'coder:run': 'ptbk coder run --harness openai-codex --model gpt-5.5 --thinking-level xhigh --agent agents/developer.book --context AGENTS.md',
     // 'coder:find-refactor-candidates': 'ptbk coder find-refactor-candidates',
     'coder:verify': 'ptbk coder verify',
 };
@@ -40785,6 +41202,7 @@ function $initializeCoderRunCommand(program) {
     command.option('--preserve-logs', 'Keep generated temp prompt/log artifacts after successful rounds for debugging and analytics', false);
     addPromptRunnerExecutionOptions(command);
     command.option('--priority <minimum-priority>', 'Filter prompts by minimum priority level', parseIntOption$1, 0);
+    command.option('--limit <run-count>', 'Stop after processing this many prompt runs', parsePositiveIntegerOption);
     command.option('--wait-after-prompt <duration>', spaceTrim$1(`
             Wait this long after each prompt has been implemented, verified and committed before starting the next prompt.
             Accepts durations like 1h, 30m, 5s. Defaults to 0 (no wait).
@@ -40803,7 +41221,7 @@ function $initializeCoderRunCommand(program) {
     command.option('--auto-migrate', 'Run testing-server database migrations automatically after each successfully processed prompt');
     command.option('--allow-destructive-auto-migrate', 'Allow auto-migrate even when heuristic SQL safety check flags destructive pending migrations');
     command.action(handleActionErrors(async (cliOptions) => {
-        const { dryRun, agent, context, test, preserveLogs, priority, waitAfterPrompt: waitAfterPromptValue, waitBetweenPrompts: waitBetweenPromptsValue, waitAfterError: waitAfterErrorValue, auto, autoMigrate, allowDestructiveAutoMigrate, } = cliOptions;
+        const { dryRun, agent, context, test, preserveLogs, priority, limit, waitAfterPrompt: waitAfterPromptValue, waitBetweenPrompts: waitBetweenPromptsValue, waitAfterError: waitAfterErrorValue, auto, autoMigrate, allowDestructiveAutoMigrate, } = cliOptions;
         const testCommand = normalizeCommandOptionValue$1(test);
         const runnerOptions = normalizePromptRunnerCliOptions(cliOptions, {
             isAgentRequired: !dryRun,
@@ -40836,6 +41254,7 @@ function $initializeCoderRunCommand(program) {
             noUi: runnerOptions.noUi,
             thinkingLevel: runnerOptions.thinkingLevel,
             priority,
+            limit,
             normalizeLineEndings: runnerOptions.normalizeLineEndings,
             allowCredits: runnerOptions.allowCredits,
             autoMigrate,
@@ -40870,6 +41289,22 @@ function parseIntOption$1(value) {
     }
     return parsed;
 }
+/**
+ * Parses a positive integer option value.
+ *
+ * @private internal utility of `coder run` command
+ */
+function parsePositiveIntegerOption(value) {
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed <= 0) {
+        throw new NotAllowed(spaceTrim$1(`
+                Invalid value for \`--limit\`: \`${value}\`.
+
+                Use a positive integer.
+            `));
+    }
+    return parsed;
+}
 /**
  * Joins one Commander option that may be parsed either as a single string or a variadic token array.
  *
@@ -70285,7 +70720,7 @@ const DEFAULT_WAIT_AFTER_ERROR_MS = 10 * 60 * 1000;
 /**
  * CLI usage text for this script.
  */
-const USAGE = 'Usage: run-codex-prompts [--dry-run] [--harness <harness-name>] [--model <model>] [--context <context-or-file>] [--test <test-command...>] [--preserve-logs] [--no-ui] [--thinking-level <thinking-level>] [--priority <minimum-priority>] [--allow-credits] [--auto-migrate] [--allow-destructive-auto-migrate] [--wait-after-prompt <duration>] [--wait-between-prompts <duration>] [--wait-after-error <duration>] [--no-auto] [--no-commit] [--ignore-git-changes] [--no-normalize-line-endings] [--auto-push] [--auto-pull]';
+const USAGE = 'Usage: run-codex-prompts [--dry-run] [--harness <harness-name>] [--model <model>] [--context <context-or-file>] [--test <test-command...>] [--preserve-logs] [--no-ui] [--thinking-level <thinking-level>] [--priority <minimum-priority>] [--limit <run-count>] [--allow-credits] [--auto-migrate] [--allow-destructive-auto-migrate] [--wait-after-prompt <duration>] [--wait-between-prompts <duration>] [--wait-after-error <duration>] [--no-auto] [--no-commit] [--ignore-git-changes] [--no-normalize-line-endings] [--auto-push] [--auto-pull]';
 /**
  * Top-level flags supported by this command.
  */
@@ -70299,6 +70734,7 @@ const KNOWN_OPTION_FLAGS = new Set([
     '--no-ui',
     '--thinking-level',
     '--priority',
+    '--limit',
     '--allow-credits',
     '--auto-migrate',
     '--allow-destructive-auto-migrate',
@@ -70335,6 +70771,8 @@ function parseRunOptions(args) {
     const thinkingLevelValue = readOptionValue(args, '--thinking-level');
     const hasPriorityFlag = args.includes('--priority');
     const priority = parsePriority(readOptionValue(args, '--priority'), hasPriorityFlag);
+    const hasLimitFlag = args.includes('--limit');
+    const limit = parseLimit(readOptionValue(args, '--limit'), hasLimitFlag);
     const noCommit = args.includes('--no-commit');
     const ignoreGitChanges = args.includes('--ignore-git-changes');
     const normalizeLineEndings = !args.includes('--no-normalize-line-endings');
@@ -70389,6 +70827,7 @@ function parseRunOptions(args) {
         testCommand,
         thinkingLevel,
         priority,
+        limit,
     };
 }
 /**
@@ -70452,6 +70891,22 @@ function parsePriority(priorityValue, hasPriorityFlag) {
     }
     return priority;
 }
+/**
+ * Parses and validates the optional successful prompt-run limit.
+ */
+function parseLimit(limitValue, hasLimitFlag) {
+    if (limitValue === undefined) {
+        if (hasLimitFlag) {
+            exitWithUsageError('Missing value for --limit. Use a positive integer.');
+        }
+        return undefined;
+    }
+    const limit = Number(limitValue);
+    if (!Number.isInteger(limit) || limit <= 0) {
+        exitWithUsageError(`Invalid value for --limit: "${limitValue}". Use a positive integer.`);
+    }
+    return limit;
+}
 /**
  * Prints an argument error with usage and exits the process.
  */
@@ -72561,11 +73016,12 @@ async function runPromptRound({ options, runner, runnerMetadata, nextPrompt, pro
     // Prepend agent system message before the task so the harness sees agent instructions first
     const promptWithAgent = resolvedAgentSystemMessage
         ? spaceTrim$1((block) => `
-                  ${block(resolvedAgentSystemMessage.trim())}
-
+                  
                   ## Your Task
 
                   ${block(taskPrompt)}
+
+                  ${block(resolvedAgentSystemMessage.trim())}
               `)
         : taskPrompt;
     const codexPrompt = appendCoderContext(promptWithAgent, resolvedCoderContext);
@@ -72888,6 +73344,7 @@ async function runCodexPrompts(providedOptions) {
         let hasWaitedForStart = false;
         let previousRoundStartTime;
         let previousRoundEndTime;
+        let completedRunCount = 0;
         while (just(true)) {
             if (options.autoPull && !options.dryRun) {
                 await waitForRequestedPause({
@@ -72973,6 +73430,15 @@ async function runCodexPrompts(providedOptions) {
             });
             previousRoundStartTime = currentRoundStartTime;
             previousRoundEndTime = Date.now();
+            completedRunCount += 1;
+            if (isRunLimitReached({ completedRunCount, limit: options.limit })) {
+                finishWhenRunLimitIsReached({
+                    completedRunCount,
+                    isRichUiEnabled,
+                    uiHandle,
+                });
+                return;
+            }
         }
     }
     finally {
@@ -73002,6 +73468,13 @@ function validateRunCodexPromptOptions(options) {
                 Auto-pull keeps the repository up to date between prompt rounds, which requires each successful round to end with a clean committed working tree.
             `));
     }
+    if (options.limit !== undefined && (!Number.isInteger(options.limit) || options.limit <= 0)) {
+        throw new NotAllowed(spaceTrim$1(`
+                Flag \`--limit\` expects a positive integer.
+
+                Received: \`${options.limit}\`
+            `));
+    }
 }
 /**
  * Pulls the latest repository state before loading prompts when the feature is enabled.
@@ -73148,6 +73621,21 @@ function finishWhenNoPromptIsAvailable(promptQueueSnapshot, isRichUiEnabled, uiH
     }
     return true;
 }
+/**
+ * Checks whether the configured successful prompt-run limit has been reached.
+ */
+function isRunLimitReached(options) {
+    const { completedRunCount, limit } = options;
+    return limit !== undefined && completedRunCount >= limit;
+}
+/**
+ * Updates UI and console output when a user-configured run limit stops the loop.
+ */
+function finishWhenRunLimitIsReached(options) {
+    const { completedRunCount, isRichUiEnabled, uiHandle } = options;
+    const runCountLabel = completedRunCount === 1 ? '1 prompt run' : `${completedRunCount} prompt runs`;
+    announceRunCompletion(`Run limit reached after ${runCountLabel}.`, colors.green, isRichUiEnabled, uiHandle);
+}
 /**
  * Updates the UI status message while waiting for new prompts in keepAlive server mode.
  */