@promptbook/cli 0.112.0-121 → 0.112.0-123

package/umd/index.umd.js

@@ -1,8 +1,8 @@
 (function (global, factory) {
-    typeof exports === 'object' && typeof module !== 'undefined' ? factory(exports, require('colors'), require('commander'), require('spacetrim'), require('fs/promises'), require('path'), require('child_process'), require('crypto'), require('fs'), require('dotenv'), require('moment'), require('waitasecond'), require('prompts'), require('crypto-js/enc-hex'), require('crypto-js/sha256'), require('socket.io-client'), require('jszip'), require('@mozilla/readability'), require('jsdom'), require('crypto-js'), require('showdown'), require('glob-promise'), require('http'), require('express'), require('socket.io'), require('express-openapi-validator'), require('swagger-ui-express'), require('react'), require('react-dom/server'), require('@anthropic-ai/sdk'), require('bottleneck'), require('@azure/openai'), require('rxjs'), require('mime-types'), require('papaparse'), require('@openai/agents'), require('openai'), require('typescript'), require('ignore'), require('readline'), require('url'), require('events'), require('pg'), require('@supabase/supabase-js')) :
-    typeof define === 'function' && define.amd ? define(['exports', 'colors', 'commander', 'spacetrim', 'fs/promises', 'path', 'child_process', 'crypto', 'fs', 'dotenv', 'moment', 'waitasecond', 'prompts', 'crypto-js/enc-hex', 'crypto-js/sha256', 'socket.io-client', 'jszip', '@mozilla/readability', 'jsdom', 'crypto-js', 'showdown', 'glob-promise', 'http', 'express', 'socket.io', 'express-openapi-validator', 'swagger-ui-express', 'react', 'react-dom/server', '@anthropic-ai/sdk', 'bottleneck', '@azure/openai', 'rxjs', 'mime-types', 'papaparse', '@openai/agents', 'openai', 'typescript', 'ignore', 'readline', 'url', 'events', 'pg', '@supabase/supabase-js'], factory) :
-    (global = typeof globalThis !== 'undefined' ? globalThis : global || self, factory(global["promptbook-cli"] = {}, global.colors, global.commander, global._spaceTrim, global.promises, global.path, global.child_process, global.crypto, global.fs, global.dotenv, global.moment, global.waitasecond, global.prompts, global.hexEncoder, global.sha256, global.socket_ioClient, global.JSZip, global.readability, global.jsdom, global.CryptoJS, global.showdown, global.glob, global.http, global.express, global.socket_io, global.OpenApiValidator, global.swaggerUi, global.react, global.server, global.Anthropic, global.Bottleneck, global.openai, global.rxjs, global.mimeTypes, global.papaparse, global.agents, global.OpenAI, global.ts, global.ignore, global.readline, global.url, global.events, global.pg));
-})(this, (function (exports, colors, commander, _spaceTrim, promises, path, child_process, crypto, fs, dotenv, moment, waitasecond, prompts, hexEncoder, sha256, socket_ioClient, JSZip, readability, jsdom, CryptoJS, showdown, glob, http, express, socket_io, OpenApiValidator, swaggerUi, react, server, Anthropic, Bottleneck, openai, rxjs, mimeTypes, papaparse, agents, OpenAI, ts, ignore, readline, url, events, pg) { 'use strict';
+    typeof exports === 'object' && typeof module !== 'undefined' ? factory(exports, require('colors'), require('commander'), require('spacetrim'), require('fs/promises'), require('path'), require('child_process'), require('crypto'), require('fs'), require('dotenv'), require('moment'), require('waitasecond'), require('prompts'), require('crypto-js/enc-hex'), require('crypto-js/sha256'), require('socket.io-client'), require('jszip'), require('@mozilla/readability'), require('jsdom'), require('crypto-js'), require('showdown'), require('glob-promise'), require('http'), require('express'), require('socket.io'), require('express-openapi-validator'), require('swagger-ui-express'), require('react'), require('react-dom/server'), require('@anthropic-ai/sdk'), require('bottleneck'), require('@azure/openai'), require('rxjs'), require('@openai/agents'), require('openai'), require('typescript'), require('ignore'), require('readline'), require('mime-types'), require('papaparse'), require('url'), require('events'), require('pg'), require('@supabase/supabase-js')) :
+    typeof define === 'function' && define.amd ? define(['exports', 'colors', 'commander', 'spacetrim', 'fs/promises', 'path', 'child_process', 'crypto', 'fs', 'dotenv', 'moment', 'waitasecond', 'prompts', 'crypto-js/enc-hex', 'crypto-js/sha256', 'socket.io-client', 'jszip', '@mozilla/readability', 'jsdom', 'crypto-js', 'showdown', 'glob-promise', 'http', 'express', 'socket.io', 'express-openapi-validator', 'swagger-ui-express', 'react', 'react-dom/server', '@anthropic-ai/sdk', 'bottleneck', '@azure/openai', 'rxjs', '@openai/agents', 'openai', 'typescript', 'ignore', 'readline', 'mime-types', 'papaparse', 'url', 'events', 'pg', '@supabase/supabase-js'], factory) :
+    (global = typeof globalThis !== 'undefined' ? globalThis : global || self, factory(global["promptbook-cli"] = {}, global.colors, global.commander, global._spaceTrim, global.promises, global.path, global.child_process, global.crypto, global.fs, global.dotenv, global.moment, global.waitasecond, global.prompts, global.hexEncoder, global.sha256, global.socket_ioClient, global.JSZip, global.readability, global.jsdom, global.CryptoJS, global.showdown, global.glob, global.http, global.express, global.socket_io, global.OpenApiValidator, global.swaggerUi, global.react, global.server, global.Anthropic, global.Bottleneck, global.openai, global.rxjs, global.agents, global.OpenAI, global.ts, global.ignore, global.readline, global.mimeTypes, global.papaparse, global.url, global.events, global.pg));
+})(this, (function (exports, colors, commander, _spaceTrim, promises, path, child_process, crypto, fs, dotenv, moment, waitasecond, prompts, hexEncoder, sha256, socket_ioClient, JSZip, readability, jsdom, CryptoJS, showdown, glob, http, express, socket_io, OpenApiValidator, swaggerUi, react, server, Anthropic, Bottleneck, openai, rxjs, agents, OpenAI, ts, ignore, readline, mimeTypes, papaparse, url, events, pg) { 'use strict';
 
     function _interopDefaultLegacy (e) { return e && typeof e === 'object' && 'default' in e ? e : { 'default': e }; }
 
@@ -43,11 +43,11 @@
     var swaggerUi__default = /*#__PURE__*/_interopDefaultLegacy(swaggerUi);
     var Anthropic__default = /*#__PURE__*/_interopDefaultLegacy(Anthropic);
     var Bottleneck__default = /*#__PURE__*/_interopDefaultLegacy(Bottleneck);
-    var papaparse__default = /*#__PURE__*/_interopDefaultLegacy(papaparse);
     var OpenAI__default = /*#__PURE__*/_interopDefaultLegacy(OpenAI);
     var ts__namespace = /*#__PURE__*/_interopNamespace(ts);
     var ignore__default = /*#__PURE__*/_interopDefaultLegacy(ignore);
     var readline__namespace = /*#__PURE__*/_interopNamespace(readline);
+    var papaparse__default = /*#__PURE__*/_interopDefaultLegacy(papaparse);
 
     // ⚠️ WARNING: This code has been generated so that any manual changes will be overwritten
     /**
@@ -63,7 +63,7 @@
      * @generated
      * @see https://github.com/webgptorg/promptbook
      */
-    const PROMPTBOOK_ENGINE_VERSION = '0.112.0-121';
+    const PROMPTBOOK_ENGINE_VERSION = '0.112.0-123';
     /**
      * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
      * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -4021,6 +4021,21 @@
     function resetPauseTargetLabel() {
         setPauseTargetLabel(DEFAULT_PAUSE_TARGET_LABEL);
     }
+    /**
+     * Requests a pause from an external controller (e.g. the Ink UI).
+     */
+    function requestPause() {
+        if (pauseState === 'RUNNING') {
+            setPauseState('PAUSING');
+        }
+    }
+    /**
+     * Resumes execution from an external controller after a pause.
+     */
+    function requestResume() {
+        setPauseState('RUNNING');
+        resetPauseTargetLabel();
+    }
 
     /**
      * Just says that the variable is not used but should be kept
@@ -38613,6 +38628,48 @@
     // Note: [🟡] Code for CLI command [find-refactor-candidates](src/cli/cli-commands/coder/find-refactor-candidates.ts) should never be published outside of `@promptbook/cli`
     // Note: [💞] Ignore a discrepancy between file name and entity name
 
+    /**
+     * Initializes `coder find-unwritten` command for Promptbook CLI utilities
+     *
+     * Note: `$` is used to indicate that this function is not a pure function - it registers a command in the CLI
+     *
+     * @private internal function of `promptbookCli`
+     */
+    function $initializeCoderFindUnwrittenCommand(program) {
+        const command = program.command('find-unwritten');
+        command.description('List all prompt sections that still need to be authored (contain @@@ placeholder)');
+        command.option('--priority <minimum-priority>', 'Filter prompts by minimum priority level', parseIntOption$2, 0);
+        command.action(handleActionErrors(async (cliOptions) => {
+            const { priority = 0 } = cliOptions;
+            // Note: Import the function dynamically to avoid loading heavy dependencies until needed
+            const { findUnwrittenPrompts } = await Promise.resolve().then(function () { return findUnwrittenPrompts$1; });
+            try {
+                await findUnwrittenPrompts({ priority });
+            }
+            catch (error) {
+                assertsError(error);
+                console.error(colors__default["default"].bgRed(`${error.name}`));
+                console.error(colors__default["default"].red(error.stack || error.message));
+                return process.exit(1);
+            }
+            return process.exit(0);
+        }));
+    }
+    /**
+     * Parses an integer option value
+     *
+     * @private internal utility of `coder find-unwritten` command
+     */
+    function parseIntOption$2(value) {
+        const parsed = parseInt(value, 10);
+        if (isNaN(parsed)) {
+            throw new Error(`Invalid number: ${value}`);
+        }
+        return parsed;
+    }
+    // Note: [🟡] Code for CLI command [find-unwritten](src/cli/cli-commands/coder/find-unwritten.ts) should never be published outside of `@promptbook/cli`
+    // Note: [💞] Ignore a discrepancy between file name and entity name
+
     /**
      * Relative path to the root prompts directory used by Promptbook coder utilities.
      *
@@ -39519,8 +39576,10 @@
             - CODING_AGENT_GIT_SIGNING_KEY
         `));
         command.action(handleActionErrors(async () => {
-            const summary = await initializeCoderProjectConfiguration(process.cwd());
+            const projectPath = process.cwd();
+            const summary = await initializeCoderProjectConfiguration(projectPath);
             printInitializationSummary(summary);
+            await generatePromptBoilerplate({ projectPath, filesCount: 5 });
         }));
     }
     /**
@@ -39612,11 +39671,12 @@
         `));
         command.option('--dry-run', 'Print unwritten prompts without executing', false);
         addPromptRunnerSelectionOptions(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');
         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, 0);
+        command.option('--priority <minimum-priority>', 'Filter prompts by minimum priority level', parseIntOption$1, 0);
         command.option('--wait [duration]', _spaceTrim.spaceTrim(`
             Wait between prompt rounds.
             Without a value (default): waits for user confirmation before each prompt (interactive mode).
@@ -39627,8 +39687,8 @@
         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, context, test, preserveLogs, priority, wait, autoMigrate, allowDestructiveAutoMigrate } = cliOptions;
-            const testCommand = normalizeCommandOptionValue(test);
+            const { dryRun, agent, context, test, preserveLogs, priority, wait, autoMigrate, allowDestructiveAutoMigrate, } = cliOptions;
+            const testCommand = normalizeCommandOptionValue$1(test);
             const runnerOptions = normalizePromptRunnerCliOptions(cliOptions, {
                 isAgentRequired: !dryRun,
             });
@@ -39653,6 +39713,7 @@
                 ignoreGitChanges: runnerOptions.ignoreGitChanges,
                 agentName: runnerOptions.agentName,
                 model: runnerOptions.model,
+                agent,
                 context,
                 testCommand,
                 preserveLogs,
@@ -39686,7 +39747,7 @@
      *
      * @private internal utility of `coder run` command
      */
-    function parseIntOption(value) {
+    function parseIntOption$1(value) {
         const parsed = parseInt(value, 10);
         if (isNaN(parsed)) {
             throw new Error(`Invalid number: ${value}`);
@@ -39698,7 +39759,7 @@
      *
      * @private internal utility of `coder run` command
      */
-    function normalizeCommandOptionValue(value) {
+    function normalizeCommandOptionValue$1(value) {
         if (value === undefined) {
             return undefined;
         }
@@ -39713,6 +39774,157 @@
     // Note: [🟡] Code for CLI command [run](src/cli/cli-commands/coder/run.ts) should never be published outside of `@promptbook/cli`
     // Note: [💞] Ignore a discrepancy between file name and entity name
 
+    /**
+     * Default port used by `ptbk coder server`.
+     *
+     * @private internal constant of `ptbk coder server`
+     */
+    const DEFAULT_CODER_SERVER_PORT = '4441';
+    /**
+     * Initializes `coder server` command for Promptbook CLI utilities.
+     *
+     * Runs the same prompt processing logic as `ptbk coder run` but keeps the process alive
+     * and serves a kanban web UI on the configured port.
+     *
+     * Note: `$` is used to indicate that this function is not a pure function - it registers a command in the CLI
+     *
+     * @private internal function of `promptbookCli`
+     */
+    function $initializeCoderServerCommand(program) {
+        const command = program.command('server');
+        command.description(_spaceTrim.spaceTrim(`
+            Start a coder server that watches for prompts and serves a kanban web UI
+
+            ${PROMPT_RUNNER_DESCRIPTION}
+
+            Features:
+            - Runs the same prompt processing as \`ptbk coder run\`
+            - 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)
+            - Play / pause button in the browser stays in sync with the CLI pause state
+            - Press "p" in the terminal to pause / resume (same as \`ptbk coder run\`)
+        `));
+        command.addOption(new commander.Option('--port <port>', 'Port to start the coder server on')
+            .env('PTBK_CODER_SERVER_PORT')
+            .default(DEFAULT_CODER_SERVER_PORT));
+        command.option('--dry-run', 'Print unwritten prompts without executing', false);
+        addPromptRunnerSelectionOptions(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');
+        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, 0);
+        command.option('--wait [duration]', _spaceTrim.spaceTrim(`
+            Wait between prompt rounds.
+            Without a value (default): waits for user confirmation before each prompt (interactive mode).
+            With a duration like 1h, 30m, 5s: waits that long between prompts to avoid hitting rate limits of the harness.
+        `), true);
+        command.option('--no-wait', 'Skip all waiting between prompts and run non-interactively');
+        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 { port: rawPort, dryRun, agent, context, test, preserveLogs, priority, wait, autoMigrate, allowDestructiveAutoMigrate, } = cliOptions;
+            const port = parseCoderServerPort(rawPort);
+            const testCommand = normalizeCommandOptionValue(test);
+            const runnerOptions = normalizePromptRunnerCliOptions(cliOptions, {
+                isAgentRequired: !dryRun,
+            });
+            // [1] Parse the --wait option (same logic as `coder run`)
+            let waitForUser = false;
+            let waitBetweenPrompts = 0;
+            if (wait === true) {
+                waitForUser = true;
+            }
+            else if (typeof wait === 'string' && wait !== '') {
+                waitBetweenPrompts = parseDuration(wait);
+            }
+            const runOptions = {
+                port,
+                dryRun,
+                waitForUser,
+                waitBetweenPrompts,
+                noCommit: runnerOptions.noCommit,
+                ignoreGitChanges: runnerOptions.ignoreGitChanges,
+                agentName: runnerOptions.agentName,
+                model: runnerOptions.model,
+                agent,
+                context,
+                testCommand,
+                preserveLogs,
+                noUi: runnerOptions.noUi,
+                thinkingLevel: runnerOptions.thinkingLevel,
+                priority,
+                normalizeLineEndings: runnerOptions.normalizeLineEndings,
+                allowCredits: runnerOptions.allowCredits,
+                autoMigrate,
+                allowDestructiveAutoMigrate,
+                autoPush: runnerOptions.autoPush,
+                autoPull: runnerOptions.autoPull,
+            };
+            // Note: Import dynamically to avoid loading heavy dependencies until needed
+            const { runCodexPromptsServer } = await Promise.resolve().then(function () { return runCodexPromptsServer$1; });
+            try {
+                await runCodexPromptsServer(runOptions);
+            }
+            catch (error) {
+                assertsError(error);
+                console.error(colors__default["default"].bgRed(`${error.name}`));
+                console.error(colors__default["default"].red(error.stack || error.message));
+                return process.exit(1);
+            }
+            return process.exit(0);
+        }));
+    }
+    /**
+     * Parses and validates the coder server port number.
+     *
+     * @private internal utility of `coder server` command
+     */
+    function parseCoderServerPort(rawPort) {
+        const port = Number.parseInt(rawPort, 10);
+        if (!Number.isInteger(port) || port <= 0 || port > NETWORK_LIMITS.MAX_PORT) {
+            throw new NotAllowed(_spaceTrim.spaceTrim(`
+                Invalid coder server port: \`${rawPort}\`.
+
+                Use \`--port\` or \`PTBK_CODER_SERVER_PORT\` with an integer between \`1\` and \`${NETWORK_LIMITS.MAX_PORT}\`.
+            `));
+        }
+        return port;
+    }
+    /**
+     * Parses an integer option value.
+     *
+     * @private internal utility of `coder server` command
+     */
+    function parseIntOption(value) {
+        const parsed = parseInt(value, 10);
+        if (isNaN(parsed)) {
+            throw new Error(`Invalid number: ${value}`);
+        }
+        return parsed;
+    }
+    /**
+     * Joins one Commander option that may be parsed either as a single string or a variadic token array.
+     *
+     * @private internal utility of `coder server` command
+     */
+    function normalizeCommandOptionValue(value) {
+        if (value === undefined) {
+            return undefined;
+        }
+        const parts = Array.isArray(value) ? value : [value];
+        const normalizedValue = parts
+            .map((part) => part.trim())
+            .filter(Boolean)
+            .join(' ')
+            .trim();
+        return normalizedValue === '' ? undefined : normalizedValue;
+    }
+    // Note: [🟡] Code for CLI command [server](src/cli/cli-commands/coder/server.ts) should never be published outside of `@promptbook/cli`
+    // Note: [💞] Ignore a discrepancy between file name and entity name
+
     /**
      * Initializes `coder verify` command for Promptbook CLI utilities
      *
@@ -39784,7 +39996,9 @@
             - init: Initialize coder configuration in current project
             - generate-boilerplates: Generate prompt boilerplate files
             - find-refactor-candidates: Find files that need refactoring
+            - find-unwritten: List prompt sections that still need to be authored
             - run: Run coding prompts with AI agents
+            - server: Start a long-running coder server with a kanban web UI
             - verify: Verify completed prompts
             - find-fresh-emoji-tags: Find unused emoji tags
         `));
@@ -39792,7 +40006,9 @@
         $initializeCoderInitCommand(coderCommand);
         $initializeCoderGenerateBoilerplatesCommand(coderCommand);
         $initializeCoderFindRefactorCandidatesCommand(coderCommand);
+        $initializeCoderFindUnwrittenCommand(coderCommand);
         $initializeCoderRunCommand(coderCommand);
+        $initializeCoderServerCommand(coderCommand);
         $initializeCoderVerifyCommand(coderCommand);
         $initializeCoderFindFreshEmojiTagCommand(coderCommand);
         // If no subcommand is provided, show help
@@ -68628,6 +68844,303 @@
         findRefactorCandidates: findRefactorCandidates
     });
 
+    /**
+     * Checks whether a prompt section meets the minimum priority threshold.
+     */
+    function hasSufficientPriority(section, minimumPriority) {
+        return section.priority >= minimumPriority;
+    }
+
+    /**
+     * Trims leading and trailing empty lines.
+     */
+    function trimEmptyEdges(lines) {
+        let start = 0;
+        while (start < lines.length) {
+            const startLine = lines[start];
+            if (startLine !== undefined && startLine.trim() !== '') {
+                break;
+            }
+            start += 1;
+        }
+        let end = lines.length - 1;
+        while (end >= start) {
+            const endLine = lines[end];
+            if (endLine !== undefined && endLine.trim() !== '') {
+                break;
+            }
+            end -= 1;
+        }
+        return lines.slice(start, end + 1);
+    }
+
+    /**
+     * Extracts prompt lines without the status marker.
+     */
+    function buildPromptLinesWithoutStatus(file, section) {
+        const lines = file.lines.slice(section.startLine, section.endLine + 1);
+        if (section.statusLineIndex !== undefined) {
+            const relativeIndex = section.statusLineIndex - section.startLine;
+            if (relativeIndex >= 0 && relativeIndex < lines.length) {
+                lines.splice(relativeIndex, 1);
+            }
+        }
+        return trimEmptyEdges(lines);
+    }
+
+    /**
+     * Builds the prompt text sent to the agent runner.
+     */
+    function buildCodexPrompt(file, section) {
+        const lines = buildPromptLinesWithoutStatus(file, section);
+        for (let i = 0; i < lines.length; i++) {
+            const line = lines[i];
+            if (line === undefined || line.trim() === '') {
+                continue;
+            }
+            lines[i] = line.replace(/^\[[^\]]+\]\s*/, '');
+            break;
+        }
+        return lines.join(file.eol);
+    }
+
+    /**
+     * Checks whether a prompt section still needs authoring (contains "@@@").
+     */
+    function isPromptToBeWritten(file, section) {
+        return buildCodexPrompt(file, section).includes('@@@');
+    }
+
+    /**
+     * Lists todo prompts across all files.
+     */
+    function listTodoPrompts(files) {
+        const prompts = [];
+        for (const file of files) {
+            for (const section of file.sections) {
+                if (section.status === 'todo') {
+                    prompts.push({ file, section });
+                }
+            }
+        }
+        return prompts;
+    }
+
+    /**
+     * Lists todo prompts that still contain authoring placeholders.
+     */
+    function listPromptsToBeWritten(files, minimumPriority = 0) {
+        return listTodoPrompts(files).filter((prompt) => isPromptToBeWritten(prompt.file, prompt.section) && hasSufficientPriority(prompt.section, minimumPriority));
+    }
+
+    /**
+     * Parses a prompt markdown file into sections and metadata.
+     */
+    function parsePromptFile(filePath, content) {
+        var _a, _b;
+        const eol = content.includes('\r\n') ? '\r\n' : '\n';
+        const hasFinalEol = content.endsWith('\n');
+        const lines = content.split(/\r?\n/);
+        const sections = [];
+        let startLine = 0;
+        let index = 0;
+        for (let i = 0; i <= lines.length; i++) {
+            const line = lines[i];
+            const isSeparator = i < lines.length && line !== undefined && line.trim() === '---';
+            const isEnd = i === lines.length;
+            if (!isSeparator && !isEnd) {
+                continue;
+            }
+            const endLine = i - 1;
+            const firstNonEmptyLine = findFirstNonEmptyLine(lines, startLine, endLine);
+            if (firstNonEmptyLine !== undefined) {
+                const statusLine = (lines[firstNonEmptyLine] || '').trim();
+                const parsedStatus = parseStatusLine(statusLine);
+                const status = (_a = parsedStatus === null || parsedStatus === void 0 ? void 0 : parsedStatus.status) !== null && _a !== void 0 ? _a : 'not-ready';
+                const priority = (_b = parsedStatus === null || parsedStatus === void 0 ? void 0 : parsedStatus.priority) !== null && _b !== void 0 ? _b : 0;
+                sections.push({
+                    index,
+                    startLine,
+                    endLine,
+                    status,
+                    priority,
+                    statusLineIndex: parsedStatus ? firstNonEmptyLine : undefined,
+                });
+                index += 1;
+            }
+            startLine = i + 1;
+        }
+        return {
+            path: filePath,
+            name: path.basename(filePath),
+            lines,
+            eol,
+            hasFinalEol,
+            sections,
+        };
+    }
+    /**
+     * Parses a status line like "[ ] !!" or "[-]" or "[x] ~$0.65 21 minutes..." into status and priority.
+     * For [x] done and [!] failed prompts, allow metadata after the status marker.
+     */
+    function parseStatusLine(line) {
+        var _a, _b, _c, _d, _e;
+        // For done prompts [x], allow any content after (for cost/time metadata)
+        const doneMatch = line.match(/^\[(?<status>[xX])\]/);
+        if (doneMatch) {
+            return { status: 'done', priority: 0 };
+        }
+        // For failed prompts [!], allow any content after (for failure metadata)
+        const failedMatch = line.match(/^\[(?<status>!)\]/);
+        if (failedMatch) {
+            return { status: 'failed', priority: 0 };
+        }
+        // For todo [ ] and not-ready [-], require clean end with optional priority markers
+        const match = line.match(/^\[(?<status>[ -])\]\s*(?<priority>!*)\s*$/);
+        if (!match) {
+            return undefined;
+        }
+        const statusChar = (_b = (_a = match.groups) === null || _a === void 0 ? void 0 : _a.status) === null || _b === void 0 ? void 0 : _b.toLowerCase();
+        let status;
+        if (statusChar === '-') {
+            status = 'not-ready';
+        }
+        else {
+            status = 'todo';
+        }
+        const priority = status === 'todo' ? (_e = (_d = (_c = match.groups) === null || _c === void 0 ? void 0 : _c.priority) === null || _d === void 0 ? void 0 : _d.length) !== null && _e !== void 0 ? _e : 0 : 0;
+        return { status, priority };
+    }
+    /**
+     * Finds the first non-empty line index between two bounds.
+     */
+    function findFirstNonEmptyLine(lines, startLine, endLine) {
+        for (let i = startLine; i <= endLine; i++) {
+            const line = lines[i];
+            if (line !== undefined && line.trim() !== '') {
+                return i;
+            }
+        }
+        return undefined;
+    }
+
+    /**
+     * Loads and parses prompt files from the prompts directory.
+     */
+    async function loadPromptFiles(promptsDir) {
+        const entries = await promises.readdir(promptsDir, { withFileTypes: true });
+        const files = entries
+            .filter((entry) => entry.isFile() && entry.name.toLowerCase().endsWith('.md'))
+            .map((entry) => path.join(promptsDir, entry.name))
+            .sort((a, b) => a.localeCompare(b));
+        const promptFiles = [];
+        for (const filePath of files) {
+            const content = await promises.readFile(filePath, 'utf-8');
+            promptFiles.push(parsePromptFile(filePath, content));
+        }
+        return promptFiles;
+    }
+
+    /**
+     * Builds a display label using the prompt line number for easier navigation.
+     */
+    function buildPromptLabelForDisplay(file, section) {
+        return `${path.relative(process.cwd(), file.path).replace(/\\/g, '/')}#${section.startLine + 1}`;
+    }
+
+    /**
+     * Extracts a short summary line from a prompt section.
+     */
+    function buildPromptSummary(file, section) {
+        const lines = buildCodexPrompt(file, section).split(/\r?\n/);
+        const firstLine = lines.find((line) => line.trim() !== '');
+        return (firstLine === null || firstLine === void 0 ? void 0 : firstLine.trim()) || '(empty prompt)';
+    }
+
+    /**
+     * Prints the list of prompts that still need to be written.
+     */
+    function printPromptsToBeWritten(files, minimumPriority = 0) {
+        const promptsToWrite = listPromptsToBeWritten(files, minimumPriority);
+        let i = 0;
+        for (const { file, section } of promptsToWrite) {
+            const label = buildPromptLabelForDisplay(file, section);
+            const summary = buildPromptSummary(file, section);
+            console.info(`  ${++i}) ${label}: ${summary}`);
+        }
+    }
+
+    /**
+     * Prints the summary stats line.
+     */
+    function printStats(stats, minimumPriority = 0) {
+        const priorityStats = minimumPriority > 0 ? ` | Priority <${minimumPriority}: ${stats.belowMinimumPriority}` : '';
+        console.info(colors__default["default"].cyan(`Done: ${stats.done} | For agent: ${stats.forAgent}${priorityStats} | To be written: ${stats.toBeWritten}`));
+    }
+
+    /**
+     * Summarizes prompt stats for the runner output.
+     */
+    function summarizePrompts(files, minimumPriority = 0) {
+        const stats = { done: 0, forAgent: 0, belowMinimumPriority: 0, toBeWritten: 0 };
+        for (const file of files) {
+            for (const section of file.sections) {
+                if (section.status === 'done') {
+                    stats.done += 1;
+                }
+                else if (section.status === 'todo') {
+                    const isAbovePriority = hasSufficientPriority(section, minimumPriority);
+                    if (isPromptToBeWritten(file, section)) {
+                        if (!isAbovePriority) {
+                            continue;
+                        }
+                        stats.toBeWritten += 1;
+                    }
+                    else if (isAbovePriority) {
+                        stats.forAgent += 1;
+                    }
+                    else {
+                        stats.belowMinimumPriority += 1;
+                    }
+                }
+            }
+        }
+        return stats;
+    }
+
+    /**
+     * Constant for prompts dir — mirrors the constant in `runCodexPrompts.ts`.
+     */
+    const PROMPTS_DIR$2 = path.join(process.cwd(), 'prompts');
+    /**
+     * Lists and prints all prompt sections that still need to be authored (contain `@@@` placeholder).
+     *
+     * Reuses the same filtering logic as `ptbk coder run --dry-run`.
+     *
+     * @returns the number of unwritten prompts found
+     * @public exported from `@promptbook/cli`
+     */
+    async function findUnwrittenPrompts(options = {}) {
+        const { priority = 0 } = options;
+        const promptFiles = await loadPromptFiles(PROMPTS_DIR$2);
+        const stats = summarizePrompts(promptFiles, priority);
+        printStats(stats, priority);
+        const unwrittenPrompts = listPromptsToBeWritten(promptFiles, priority);
+        if (unwrittenPrompts.length === 0) {
+            console.info(colors__default["default"].green('All prompts are written — nothing to do.'));
+        }
+        else {
+            console.info(colors__default["default"].yellow(`Found ${unwrittenPrompts.length} prompt(s) that need to be written:`));
+            printPromptsToBeWritten(promptFiles, priority);
+        }
+        return unwrittenPrompts.length;
+    }
+
+    var findUnwrittenPrompts$1 = /*#__PURE__*/Object.freeze({
+        __proto__: null,
+        findUnwrittenPrompts: findUnwrittenPrompts
+    });
+
     /**
      * CLI usage text for this script.
      */
@@ -68971,6 +69484,29 @@
         return `${count} prompt${count === 1 ? '' : 's'}`;
     }
 
+    /**
+     * Reads an optional agent `.book` file and compiles its system message for injection into coder prompts.
+     *
+     * Returns `undefined` when no agent path is provided.
+     */
+    async function resolveAgentSystemMessage(agentPath, currentWorkingDirectory) {
+        if (!agentPath) {
+            return undefined;
+        }
+        const resolvedAgentPath = path.resolve(currentWorkingDirectory, agentPath);
+        const agentSource = await promises.readFile(resolvedAgentPath, 'utf-8').catch((error) => {
+            if (error.code === 'ENOENT' || error.code === 'EISDIR') {
+                throw new NotFoundError(spaceTrim(`
+                    Agent book \`${agentPath}\` was not found or is not a file.
+
+                    Pass a path to a \`.book\` file in \`--agent\`.
+                `));
+            }
+            throw error;
+        });
+        return createAgentRunnerSystemMessage(agentSource);
+    }
+
     /**
      * Resolves optional coding context provided inline or via a file path.
      */
@@ -69013,104 +69549,6 @@
         }
     }
 
-    /**
-     * Builds a display label using the prompt line number for easier navigation.
-     */
-    function buildPromptLabelForDisplay(file, section) {
-        return `${path.relative(process.cwd(), file.path).replace(/\\/g, '/')}#${section.startLine + 1}`;
-    }
-
-    /**
-     * Trims leading and trailing empty lines.
-     */
-    function trimEmptyEdges(lines) {
-        let start = 0;
-        while (start < lines.length) {
-            const startLine = lines[start];
-            if (startLine !== undefined && startLine.trim() !== '') {
-                break;
-            }
-            start += 1;
-        }
-        let end = lines.length - 1;
-        while (end >= start) {
-            const endLine = lines[end];
-            if (endLine !== undefined && endLine.trim() !== '') {
-                break;
-            }
-            end -= 1;
-        }
-        return lines.slice(start, end + 1);
-    }
-
-    /**
-     * Extracts prompt lines without the status marker.
-     */
-    function buildPromptLinesWithoutStatus(file, section) {
-        const lines = file.lines.slice(section.startLine, section.endLine + 1);
-        if (section.statusLineIndex !== undefined) {
-            const relativeIndex = section.statusLineIndex - section.startLine;
-            if (relativeIndex >= 0 && relativeIndex < lines.length) {
-                lines.splice(relativeIndex, 1);
-            }
-        }
-        return trimEmptyEdges(lines);
-    }
-
-    /**
-     * Builds the prompt text sent to the agent runner.
-     */
-    function buildCodexPrompt(file, section) {
-        const lines = buildPromptLinesWithoutStatus(file, section);
-        for (let i = 0; i < lines.length; i++) {
-            const line = lines[i];
-            if (line === undefined || line.trim() === '') {
-                continue;
-            }
-            lines[i] = line.replace(/^\[[^\]]+\]\s*/, '');
-            break;
-        }
-        return lines.join(file.eol);
-    }
-
-    /**
-     * Extracts a short summary line from a prompt section.
-     */
-    function buildPromptSummary(file, section) {
-        const lines = buildCodexPrompt(file, section).split(/\r?\n/);
-        const firstLine = lines.find((line) => line.trim() !== '');
-        return (firstLine === null || firstLine === void 0 ? void 0 : firstLine.trim()) || '(empty prompt)';
-    }
-
-    /**
-     * Checks whether a prompt section meets the minimum priority threshold.
-     */
-    function hasSufficientPriority(section, minimumPriority) {
-        return section.priority >= minimumPriority;
-    }
-
-    /**
-     * Checks whether a prompt section still needs authoring (contains "@@@").
-     */
-    function isPromptToBeWritten(file, section) {
-        return buildCodexPrompt(file, section).includes('@@@');
-    }
-
-    /**
-     * Lists todo prompts across all files.
-     */
-    function listTodoPrompts(files) {
-        const prompts = [];
-        for (const file of files) {
-            for (const section of file.sections) {
-                if (section.status === 'todo') {
-                    prompts.push({ file, section });
-                }
-            }
-        }
-        return prompts;
-    }
-
     /**
      * Lists todo prompts that are ready to run (no authoring placeholders).
      */
@@ -69143,142 +69581,6 @@
         }));
     }
 
-    /**
-     * Parses a prompt markdown file into sections and metadata.
-     */
-    function parsePromptFile(filePath, content) {
-        var _a, _b;
-        const eol = content.includes('\r\n') ? '\r\n' : '\n';
-        const hasFinalEol = content.endsWith('\n');
-        const lines = content.split(/\r?\n/);
-        const sections = [];
-        let startLine = 0;
-        let index = 0;
-        for (let i = 0; i <= lines.length; i++) {
-            const line = lines[i];
-            const isSeparator = i < lines.length && line !== undefined && line.trim() === '---';
-            const isEnd = i === lines.length;
-            if (!isSeparator && !isEnd) {
-                continue;
-            }
-            const endLine = i - 1;
-            const firstNonEmptyLine = findFirstNonEmptyLine(lines, startLine, endLine);
-            if (firstNonEmptyLine !== undefined) {
-                const statusLine = (lines[firstNonEmptyLine] || '').trim();
-                const parsedStatus = parseStatusLine(statusLine);
-                const status = (_a = parsedStatus === null || parsedStatus === void 0 ? void 0 : parsedStatus.status) !== null && _a !== void 0 ? _a : 'not-ready';
-                const priority = (_b = parsedStatus === null || parsedStatus === void 0 ? void 0 : parsedStatus.priority) !== null && _b !== void 0 ? _b : 0;
-                sections.push({
-                    index,
-                    startLine,
-                    endLine,
-                    status,
-                    priority,
-                    statusLineIndex: parsedStatus ? firstNonEmptyLine : undefined,
-                });
-                index += 1;
-            }
-            startLine = i + 1;
-        }
-        return {
-            path: filePath,
-            name: path.basename(filePath),
-            lines,
-            eol,
-            hasFinalEol,
-            sections,
-        };
-    }
-    /**
-     * Parses a status line like "[ ] !!" or "[-]" or "[x] ~$0.65 21 minutes..." into status and priority.
-     * For [x] done and [!] failed prompts, allow metadata after the status marker.
-     */
-    function parseStatusLine(line) {
-        var _a, _b, _c, _d, _e;
-        // For done prompts [x], allow any content after (for cost/time metadata)
-        const doneMatch = line.match(/^\[(?<status>[xX])\]/);
-        if (doneMatch) {
-            return { status: 'done', priority: 0 };
-        }
-        // For failed prompts [!], allow any content after (for failure metadata)
-        const failedMatch = line.match(/^\[(?<status>!)\]/);
-        if (failedMatch) {
-            return { status: 'failed', priority: 0 };
-        }
-        // For todo [ ] and not-ready [-], require clean end with optional priority markers
-        const match = line.match(/^\[(?<status>[ -])\]\s*(?<priority>!*)\s*$/);
-        if (!match) {
-            return undefined;
-        }
-        const statusChar = (_b = (_a = match.groups) === null || _a === void 0 ? void 0 : _a.status) === null || _b === void 0 ? void 0 : _b.toLowerCase();
-        let status;
-        if (statusChar === '-') {
-            status = 'not-ready';
-        }
-        else {
-            status = 'todo';
-        }
-        const priority = status === 'todo' ? (_e = (_d = (_c = match.groups) === null || _c === void 0 ? void 0 : _c.priority) === null || _d === void 0 ? void 0 : _d.length) !== null && _e !== void 0 ? _e : 0 : 0;
-        return { status, priority };
-    }
-    /**
-     * Finds the first non-empty line index between two bounds.
-     */
-    function findFirstNonEmptyLine(lines, startLine, endLine) {
-        for (let i = startLine; i <= endLine; i++) {
-            const line = lines[i];
-            if (line !== undefined && line.trim() !== '') {
-                return i;
-            }
-        }
-        return undefined;
-    }
-
-    /**
-     * Loads and parses prompt files from the prompts directory.
-     */
-    async function loadPromptFiles(promptsDir) {
-        const entries = await promises.readdir(promptsDir, { withFileTypes: true });
-        const files = entries
-            .filter((entry) => entry.isFile() && entry.name.toLowerCase().endsWith('.md'))
-            .map((entry) => path.join(promptsDir, entry.name))
-            .sort((a, b) => a.localeCompare(b));
-        const promptFiles = [];
-        for (const filePath of files) {
-            const content = await promises.readFile(filePath, 'utf-8');
-            promptFiles.push(parsePromptFile(filePath, content));
-        }
-        return promptFiles;
-    }
-
-    /**
-     * Lists todo prompts that still contain authoring placeholders.
-     */
-    function listPromptsToBeWritten(files, minimumPriority = 0) {
-        return listTodoPrompts(files).filter((prompt) => isPromptToBeWritten(prompt.file, prompt.section) && hasSufficientPriority(prompt.section, minimumPriority));
-    }
-
-    /**
-     * Prints the list of prompts that still need to be written.
-     */
-    function printPromptsToBeWritten(files, minimumPriority = 0) {
-        const promptsToWrite = listPromptsToBeWritten(files, minimumPriority);
-        let i = 0;
-        for (const { file, section } of promptsToWrite) {
-            const label = buildPromptLabelForDisplay(file, section);
-            const summary = buildPromptSummary(file, section);
-            console.info(`  ${++i}) ${label}: ${summary}`);
-        }
-    }
-
-    /**
-     * Prints the summary stats line.
-     */
-    function printStats(stats, minimumPriority = 0) {
-        const priorityStats = minimumPriority > 0 ? ` | Priority <${minimumPriority}: ${stats.belowMinimumPriority}` : '';
-        console.info(colors__default["default"].cyan(`Done: ${stats.done} | For agent: ${stats.forAgent}${priorityStats} | To be written: ${stats.toBeWritten}`));
-    }
-
     /**
      * Groups upcoming tasks by priority, high to low.
      */
@@ -69316,36 +69618,6 @@
         }
     }
 
-    /**
-     * Summarizes prompt stats for the runner output.
-     */
-    function summarizePrompts(files, minimumPriority = 0) {
-        const stats = { done: 0, forAgent: 0, belowMinimumPriority: 0, toBeWritten: 0 };
-        for (const file of files) {
-            for (const section of file.sections) {
-                if (section.status === 'done') {
-                    stats.done += 1;
-                }
-                else if (section.status === 'todo') {
-                    const isAbovePriority = hasSufficientPriority(section, minimumPriority);
-                    if (isPromptToBeWritten(file, section)) {
-                        if (!isAbovePriority) {
-                            continue;
-                        }
-                        stats.toBeWritten += 1;
-                    }
-                    else if (isAbovePriority) {
-                        stats.forAgent += 1;
-                    }
-                    else {
-                        stats.belowMinimumPriority += 1;
-                    }
-                }
-            }
-        }
-        return stats;
-    }
-
     /**
      * Waits for the user to press Enter before continuing.
      */
@@ -70970,9 +71242,14 @@
      *
      * @private function of runCodexPrompts
      */
-    async function runPromptRound({ options, runner, runnerMetadata, nextPrompt, promptLabel, resolvedCoderContext, isRichUiEnabled, progressDisplay, uiHandle, waitForRequestedPause, }) {
+    async function runPromptRound({ options, runner, runnerMetadata, nextPrompt, promptLabel, resolvedCoderContext, resolvedAgentSystemMessage, isRichUiEnabled, progressDisplay, uiHandle, waitForRequestedPause, }) {
         const commitMessage = buildCommitMessage(nextPrompt.file, nextPrompt.section);
-        const codexPrompt = appendCoderContext(buildCodexPrompt(nextPrompt.file, nextPrompt.section), resolvedCoderContext);
+        const taskPrompt = buildCodexPrompt(nextPrompt.file, nextPrompt.section);
+        // Prepend agent system message before the task so the harness sees agent instructions first
+        const promptWithAgent = resolvedAgentSystemMessage
+            ? `${resolvedAgentSystemMessage.trim()}\n\n${taskPrompt}`
+            : taskPrompt;
+        const codexPrompt = appendCoderContext(promptWithAgent, resolvedCoderContext);
         const scriptPath = buildScriptPath(nextPrompt.file, nextPrompt.section);
         setPromptRoundRunningState({ isRichUiEnabled, promptLabel, scriptPath, uiHandle });
         await waitForRequestedPause({
@@ -71205,6 +71482,7 @@
         startPauseListenerIfNeeded(isRichUiEnabled);
         try {
             const resolvedCoderContext = await resolveCoderContext(options.context, process.cwd());
+            const resolvedAgentSystemMessage = await resolveAgentSystemMessage(options.agent, process.cwd());
             if (await runDryRunIfRequested(options)) {
                 return;
             }
@@ -71244,7 +71522,13 @@
                     minimumPriority: options.priority,
                     isRichUiEnabled,
                 }));
-                if (finishWhenNoPromptIsAvailable(promptQueueSnapshot, isRichUiEnabled, uiHandle)) {
+                if (!promptQueueSnapshot.nextPrompt) {
+                    if (options.keepAlive) {
+                        announceKeepAliveStatus(promptQueueSnapshot, isRichUiEnabled, uiHandle);
+                        await new Promise((resolve) => setTimeout(resolve, KEEP_ALIVE_POLL_INTERVAL_MS));
+                        continue;
+                    }
+                    finishWhenNoPromptIsAvailable(promptQueueSnapshot, isRichUiEnabled, uiHandle);
                     return;
                 }
                 const nextPrompt = promptQueueSnapshot.nextPrompt;
@@ -71283,6 +71567,7 @@
                     nextPrompt,
                     promptLabel,
                     resolvedCoderContext,
+                    resolvedAgentSystemMessage,
                     isRichUiEnabled,
                     progressDisplay,
                     uiHandle,
@@ -71458,6 +71743,19 @@
         }
         return true;
     }
+    /**
+     * Updates the UI status message while waiting for new prompts in keepAlive server mode.
+     */
+    function announceKeepAliveStatus(promptQueueSnapshot, isRichUiEnabled, uiHandle) {
+        const message = promptQueueSnapshot.stats.toBeWritten > 0
+            ? 'No prompts ready for agent. Watching for changes...'
+            : 'All prompts are done. Watching for changes...';
+        uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.setStatusMessage(message);
+        uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.setPhase('waiting');
+        if (!isRichUiEnabled) {
+            console.info(colors__default["default"].gray(message));
+        }
+    }
     /**
      * Updates UI state and plain-console output for the terminal completion message.
      */
@@ -71498,6 +71796,10 @@
      * Countdown update interval for the between-rounds wait display.
      */
     const WAIT_COUNTDOWN_UPDATE_INTERVAL_MS = 30000;
+    /**
+     * Polling interval when in keepAlive server mode and no runnable prompts are available.
+     */
+    const KEEP_ALIVE_POLL_INTERVAL_MS = 5000;
     /**
      * Waits the configured time between prompt rounds to avoid hitting harness rate limits.
      * Does nothing when `waitBetweenPrompts` is zero.
@@ -71543,6 +71845,780 @@
         runCodexPrompts: runCodexPrompts
     });
 
+    /**
+     * Overwrites the body of one prompt section with new content, preserving the status line.
+     *
+     * The `newContent` string is the prompt text without the status marker.
+     * The status line (`[ ]`, `[x]`, `[!]`, `[-]`) is kept intact.
+     *
+     * @private internal utility of `ptbk coder server`
+     */
+    async function updatePromptSection(filePath, sectionIndex, newContent) {
+        var _a;
+        const rawContent = await promises.readFile(filePath, 'utf-8');
+        const promptFile = parsePromptFile(filePath, rawContent);
+        const section = promptFile.sections.find((s) => s.index === sectionIndex);
+        if (!section) {
+            throw new Error(`Section ${sectionIndex} not found in file: ${filePath}`);
+        }
+        // Lines before the status line (usually empty lines at section start)
+        const linesBeforeStatus = section.statusLineIndex !== undefined
+            ? promptFile.lines.slice(section.startLine, section.statusLineIndex)
+            : [];
+        // The status line itself (preserved exactly)
+        const statusLineContent = section.statusLineIndex !== undefined ? [promptFile.lines[section.statusLineIndex]] : [];
+        // Split the new content and trim trailing blank lines
+        const newContentLines = newContent.split(/\r?\n/);
+        while (newContentLines.length > 0 && ((_a = newContentLines[newContentLines.length - 1]) === null || _a === void 0 ? void 0 : _a.trim()) === '') {
+            newContentLines.pop();
+        }
+        // Build the reconstructed section lines
+        const newSectionLines = [
+            ...linesBeforeStatus,
+            ...statusLineContent,
+            ...(statusLineContent.length > 0 ? [''] : []),
+            ...newContentLines,
+        ];
+        // Splice the new section lines into the full file line array
+        const updatedLines = [
+            ...promptFile.lines.slice(0, section.startLine),
+            ...newSectionLines,
+            ...promptFile.lines.slice(section.endLine + 1),
+        ];
+        const updatedContent = updatedLines.join(promptFile.eol) + (promptFile.hasFinalEol ? promptFile.eol : '');
+        await promises.writeFile(filePath, updatedContent, 'utf-8');
+    }
+    // Note: [🟡] Code for CLI command [coder server](scripts/run-codex-prompts/server/updatePromptSection.ts) should never be published outside of `@promptbook/cli`
+
+    /**
+     * HTML source for the coder server kanban UI.
+     *
+     * The canonical source lives in `apps/coder-server/index.html`.
+     * Keep both files in sync when updating the frontend.
+     *
+     * @private internal constant of `ptbk coder server`
+     */
+    const CODER_SERVER_HTML = `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Ptbk Coder Server</title>
+  <style>
+    * { box-sizing: border-box; margin: 0; padding: 0; }
+    body {
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+      background: #f4f5f7;
+      color: #172b4d;
+      min-height: 100vh;
+    }
+
+    header {
+      background: #0052cc;
+      color: white;
+      padding: 12px 20px;
+      display: flex;
+      align-items: center;
+      gap: 12px;
+      position: sticky;
+      top: 0;
+      z-index: 10;
+      box-shadow: 0 2px 8px rgba(0,0,0,0.2);
+    }
+    header h1 { font-size: 17px; font-weight: 700; flex-shrink: 0; }
+
+    .status-badge {
+      padding: 3px 10px;
+      border-radius: 12px;
+      font-size: 11px;
+      font-weight: 700;
+      letter-spacing: 0.5px;
+      text-transform: uppercase;
+      flex-shrink: 0;
+    }
+    .status-RUNNING  { background: #00875a; color: white; }
+    .status-PAUSING  { background: #ff8b00; color: white; }
+    .status-PAUSED   { background: #bf2600; color: white; }
+
+    #pause-label {
+      font-size: 12px;
+      color: rgba(255,255,255,0.75);
+      flex: 1;
+      min-width: 0;
+      overflow: hidden;
+      text-overflow: ellipsis;
+      white-space: nowrap;
+    }
+
+    .btn {
+      padding: 6px 14px;
+      border: none;
+      border-radius: 4px;
+      cursor: pointer;
+      font-size: 13px;
+      font-weight: 600;
+      transition: opacity 0.15s;
+      flex-shrink: 0;
+    }
+    .btn:hover { opacity: 0.85; }
+    .btn-pause  { background: #ffc400; color: #172b4d; }
+    .btn-resume { background: #00875a; color: white; }
+
+    .board {
+      display: flex;
+      gap: 14px;
+      padding: 16px;
+      overflow-x: auto;
+      min-height: calc(100vh - 52px);
+      align-items: flex-start;
+    }
+
+    .column {
+      background: #ebecf0;
+      border-radius: 8px;
+      padding: 10px;
+      min-width: 250px;
+      width: 270px;
+      flex-shrink: 0;
+    }
+
+    .column-header {
+      font-size: 12px;
+      font-weight: 700;
+      text-transform: uppercase;
+      letter-spacing: 0.6px;
+      color: #5e6c84;
+      margin-bottom: 10px;
+      display: flex;
+      align-items: center;
+      justify-content: space-between;
+    }
+
+    .column-count {
+      background: #dfe1e6;
+      border-radius: 10px;
+      padding: 1px 7px;
+      font-size: 11px;
+      color: #5e6c84;
+    }
+
+    .column-cards { min-height: 40px; }
+
+    .card {
+      background: white;
+      border-radius: 6px;
+      padding: 10px 12px;
+      margin-bottom: 8px;
+      box-shadow: 0 1px 3px rgba(0,0,0,0.08);
+      cursor: pointer;
+      transition: box-shadow 0.15s, transform 0.1s;
+      border-left: 3px solid transparent;
+    }
+    .card:hover {
+      box-shadow: 0 4px 10px rgba(0,0,0,0.14);
+      transform: translateY(-1px);
+    }
+    .card-todo      { border-left-color: #0052cc; }
+    .card-not-ready { border-left-color: #8993a4; }
+    .card-done      { border-left-color: #00875a; }
+    .card-failed    { border-left-color: #bf2600; }
+
+    .card-file {
+      font-size: 10px;
+      color: #8993a4;
+      margin-bottom: 5px;
+      font-weight: 500;
+    }
+
+    .card-summary {
+      font-size: 13px;
+      line-height: 1.5;
+      color: #172b4d;
+      word-break: break-word;
+      white-space: pre-wrap;
+      max-height: 78px;
+      overflow: hidden;
+      display: -webkit-box;
+      -webkit-line-clamp: 4;
+      -webkit-box-orient: vertical;
+    }
+
+    .card-priority {
+      margin-top: 6px;
+      color: #ff8b00;
+      font-size: 11px;
+      font-weight: 700;
+    }
+
+    .card-edit-hint {
+      font-size: 10px;
+      color: #c1c7d0;
+      margin-top: 6px;
+      display: none;
+    }
+    .card:hover .card-edit-hint { display: block; }
+
+    .empty-column {
+      color: #b3bac5;
+      font-size: 12px;
+      padding: 10px 4px;
+      text-align: center;
+    }
+
+    .modal-overlay {
+      position: fixed;
+      inset: 0;
+      background: rgba(9,30,66,0.54);
+      display: flex;
+      align-items: flex-start;
+      justify-content: center;
+      padding: 60px 16px 16px;
+      z-index: 100;
+      animation: fadeIn 0.1s ease;
+    }
+    .modal-overlay.hidden { display: none; }
+
+    @keyframes fadeIn { from { opacity: 0; } to { opacity: 1; } }
+
+    .modal {
+      background: white;
+      border-radius: 8px;
+      width: 100%;
+      max-width: 620px;
+      padding: 20px;
+      box-shadow: 0 8px 32px rgba(0,0,0,0.25);
+      animation: slideIn 0.15s ease;
+    }
+    @keyframes slideIn { from { transform: translateY(-8px); opacity: 0; } to { transform: none; opacity: 1; } }
+
+    .modal-header {
+      display: flex;
+      align-items: flex-start;
+      justify-content: space-between;
+      margin-bottom: 14px;
+      gap: 12px;
+    }
+
+    .modal-meta { flex: 1; min-width: 0; }
+    .modal-file { font-size: 11px; color: #8993a4; margin-bottom: 4px; }
+    .modal-section-label { font-size: 13px; font-weight: 600; color: #172b4d; }
+
+    .modal-status {
+      font-size: 11px;
+      font-weight: 700;
+      padding: 2px 8px;
+      border-radius: 10px;
+      text-transform: uppercase;
+      letter-spacing: 0.4px;
+      flex-shrink: 0;
+    }
+    .status-todo      { background: #deebff; color: #0052cc; }
+    .status-not-ready { background: #f4f5f7; color: #5e6c84; }
+    .status-done      { background: #e3fcef; color: #006644; }
+    .status-failed    { background: #ffebe6; color: #bf2600; }
+
+    .modal-close {
+      background: none;
+      border: none;
+      color: #8993a4;
+      cursor: pointer;
+      font-size: 18px;
+      padding: 0 4px;
+      line-height: 1;
+      flex-shrink: 0;
+    }
+    .modal-close:hover { color: #172b4d; }
+
+    textarea {
+      width: 100%;
+      min-height: 220px;
+      font-family: 'SFMono-Regular', 'Consolas', 'Courier New', monospace;
+      font-size: 13px;
+      border: 2px solid #dfe1e6;
+      border-radius: 4px;
+      padding: 10px 12px;
+      resize: vertical;
+      line-height: 1.65;
+      color: #172b4d;
+      transition: border-color 0.15s;
+    }
+    textarea:focus {
+      outline: none;
+      border-color: #0052cc;
+      box-shadow: 0 0 0 3px rgba(0,82,204,0.12);
+    }
+
+    .modal-hint {
+      font-size: 11px;
+      color: #8993a4;
+      margin-top: 6px;
+    }
+
+    .modal-actions {
+      display: flex;
+      gap: 8px;
+      margin-top: 14px;
+      justify-content: flex-end;
+    }
+
+    .btn-save   { background: #0052cc; color: white; }
+    .btn-cancel { background: #f4f5f7; color: #172b4d; }
+    .btn-cancel:hover { background: #ebecf0; opacity: 1; }
+
+    .error-banner {
+      background: #ffebe6;
+      border-bottom: 2px solid #bf2600;
+      color: #bf2600;
+      padding: 8px 20px;
+      font-size: 13px;
+      font-weight: 500;
+    }
+    .error-banner.hidden { display: none; }
+  </style>
+</head>
+<body>
+
+  <div id="error-banner" class="error-banner hidden"></div>
+
+  <header>
+    <h1>&#128295; Ptbk Coder Server</h1>
+    <span id="status-badge" class="status-badge status-RUNNING">RUNNING</span>
+    <span id="pause-label"></span>
+    <button id="toggle-btn" class="btn btn-pause">&#9646;&#9646; Pause</button>
+  </header>
+
+  <div class="board">
+    <div class="column">
+      <div class="column-header">
+        To Do
+        <span class="column-count" id="count-todo">0</span>
+      </div>
+      <div class="column-cards" id="cards-todo">
+        <div class="empty-column">Loading&hellip;</div>
+      </div>
+    </div>
+
+    <div class="column">
+      <div class="column-header">
+        Not Ready
+        <span class="column-count" id="count-not-ready">0</span>
+      </div>
+      <div class="column-cards" id="cards-not-ready"></div>
+    </div>
+
+    <div class="column">
+      <div class="column-header">
+        Done
+        <span class="column-count" id="count-done">0</span>
+      </div>
+      <div class="column-cards" id="cards-done"></div>
+    </div>
+
+    <div class="column">
+      <div class="column-header">
+        Failed
+        <span class="column-count" id="count-failed">0</span>
+      </div>
+      <div class="column-cards" id="cards-failed"></div>
+    </div>
+  </div>
+
+  <div class="modal-overlay hidden" id="modal-overlay">
+    <div class="modal">
+      <div class="modal-header">
+        <div class="modal-meta">
+          <div class="modal-file" id="modal-file"></div>
+          <div class="modal-section-label" id="modal-section-label"></div>
+        </div>
+        <span class="modal-status" id="modal-status-badge"></span>
+        <button class="modal-close" onclick="closeModal()" title="Close (Esc)">&#x2715;</button>
+      </div>
+
+      <textarea id="modal-content" placeholder="Prompt content&hellip;"></textarea>
+      <div class="modal-hint">Tip: press Ctrl+Enter to save, Esc to cancel.</div>
+
+      <div class="modal-actions">
+        <button class="btn btn-cancel" onclick="closeModal()">Cancel</button>
+        <button class="btn btn-save" onclick="saveModal()">Save</button>
+      </div>
+    </div>
+  </div>
+
+  <script>
+    'use strict';
+
+    let modalState = null;
+    let lastPauseState = 'RUNNING';
+
+    function showError(msg) {
+      const banner = document.getElementById('error-banner');
+      banner.textContent = '\\u26a0 ' + msg;
+      banner.classList.remove('hidden');
+      clearTimeout(banner._timer);
+      banner._timer = setTimeout(() => banner.classList.add('hidden'), 6000);
+    }
+
+    function escapeHtml(str) {
+      const d = document.createElement('div');
+      d.textContent = String(str);
+      return d.innerHTML;
+    }
+
+    async function fetchStatus() {
+      try {
+        const res = await fetch('/api/status');
+        if (!res.ok) { showError('Status API error: ' + res.status); return; }
+        const data = await res.json();
+
+        lastPauseState = data.pauseState;
+
+        const badge = document.getElementById('status-badge');
+        badge.textContent = data.pauseState;
+        badge.className = 'status-badge status-' + data.pauseState;
+
+        const btn   = document.getElementById('toggle-btn');
+        const label = document.getElementById('pause-label');
+
+        if (data.pauseState === 'RUNNING') {
+          btn.textContent = '\\u23f8 Pause';
+          btn.className   = 'btn btn-pause';
+          label.textContent = '';
+        } else if (data.pauseState === 'PAUSING') {
+          btn.textContent = '\\u23f5 Resume';
+          btn.className   = 'btn btn-resume';
+          label.textContent = 'Pausing before: ' + (data.pauseTargetLabel || '\\u2026');
+        } else {
+          btn.textContent = '\\u23f5 Resume';
+          btn.className   = 'btn btn-resume';
+          label.textContent = 'Paused before: ' + (data.pauseTargetLabel || '\\u2026');
+        }
+      } catch (e) {
+        showError('Could not reach coder server: ' + e.message);
+      }
+    }
+
+    async function fetchPrompts() {
+      try {
+        const res = await fetch('/api/prompts');
+        if (!res.ok) { showError('Prompts API error: ' + res.status); return; }
+        renderBoard(await res.json());
+      } catch (e) {
+        showError('Could not load prompts: ' + e.message);
+      }
+    }
+
+    function renderBoard(promptFiles) {
+      const columns = { 'todo': [], 'not-ready': [], 'done': [], 'failed': [] };
+
+      for (const file of promptFiles) {
+        for (const section of file.sections) {
+          const col = columns[section.status];
+          if (col) col.push({ file, section });
+        }
+      }
+
+      for (const [status, cards] of Object.entries(columns)) {
+        const container = document.getElementById('cards-' + status);
+        const countEl   = document.getElementById('count-' + status);
+        if (!container) continue;
+
+        countEl.textContent = cards.length;
+        container.innerHTML = '';
+
+        if (cards.length === 0) {
+          container.innerHTML = '<div class="empty-column">Empty</div>';
+          continue;
+        }
+
+        for (const { file, section } of cards) {
+          const card = document.createElement('div');
+          card.className = 'card card-' + section.status;
+          card.innerHTML =
+            '<div class="card-file">' + escapeHtml(file.fileName) + ' &bull; #' + (section.index + 1) + '</div>' +
+            '<div class="card-summary">' + escapeHtml(section.summary) + '</div>' +
+            (section.priority > 0
+              ? '<div class="card-priority">' + '!'.repeat(section.priority) + ' priority ' + section.priority + '</div>'
+              : '') +
+            '<div class="card-edit-hint">Click to edit</div>';
+          card.onclick = () => openModal(file, section);
+          container.appendChild(card);
+        }
+      }
+    }
+
+    function openModal(file, section) {
+      modalState = { filePath: file.filePath, sectionIndex: section.index };
+
+      document.getElementById('modal-file').textContent          = file.fileName;
+      document.getElementById('modal-section-label').textContent = 'Section ' + (section.index + 1);
+
+      const badge = document.getElementById('modal-status-badge');
+      badge.textContent = section.status.replace('-', '\\u2011');
+      badge.className   = 'modal-status status-' + section.status;
+
+      document.getElementById('modal-content').value = section.content;
+      document.getElementById('modal-overlay').classList.remove('hidden');
+      setTimeout(() => document.getElementById('modal-content').focus(), 50);
+    }
+
+    function closeModal() {
+      document.getElementById('modal-overlay').classList.add('hidden');
+      modalState = null;
+    }
+
+    async function saveModal() {
+      if (!modalState) return;
+
+      const content = document.getElementById('modal-content').value;
+      const saveBtn = document.querySelector('.btn-save');
+      saveBtn.disabled    = true;
+      saveBtn.textContent = 'Saving\\u2026';
+
+      try {
+        const res = await fetch('/api/prompts/update', {
+          method: 'PUT',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({
+            filePath:     modalState.filePath,
+            sectionIndex: modalState.sectionIndex,
+            content,
+          }),
+        });
+        if (!res.ok) throw new Error('HTTP ' + res.status);
+        closeModal();
+        fetchPrompts();
+      } catch (e) {
+        showError('Save failed: ' + e.message);
+      } finally {
+        saveBtn.disabled    = false;
+        saveBtn.textContent = 'Save';
+      }
+    }
+
+    document.getElementById('toggle-btn').onclick = async () => {
+      try {
+        const endpoint = lastPauseState === 'RUNNING' ? '/api/pause' : '/api/resume';
+        await fetch(endpoint, { method: 'POST' });
+        await fetchStatus();
+      } catch (e) {
+        showError('Toggle failed: ' + e.message);
+      }
+    };
+
+    document.addEventListener('keydown', (e) => {
+      if (e.key === 'Escape') { closeModal(); return; }
+      if ((e.ctrlKey || e.metaKey) && e.key === 'Enter') { saveModal(); return; }
+    });
+
+    document.getElementById('modal-overlay').addEventListener('click', (e) => {
+      if (e.target === document.getElementById('modal-overlay')) closeModal();
+    });
+
+    fetchStatus();
+    fetchPrompts();
+    setInterval(fetchStatus,  2000);
+    setInterval(fetchPrompts, 5000);
+  </script>
+</body>
+</html>`;
+    // Note: [🟡] Code for CLI command [coder server](scripts/run-codex-prompts/server/coderServerHtml.ts) should never be published outside of `@promptbook/cli`
+    // Note: Keep in sync with apps/coder-server/index.html
+
+    /**
+     * Directory from which prompt files are loaded, relative to the current working directory.
+     *
+     * @private internal constant of `ptbk coder server`
+     */
+    const PROMPTS_DIRECTORY_NAME = 'prompts';
+    /**
+     * Starts the lightweight HTTP server that serves the coder kanban UI and REST API.
+     *
+     * API endpoints:
+     * - `GET /`                    → HTML kanban page
+     * - `GET /api/prompts`         → JSON list of all prompt files and sections
+     * - `GET /api/status`          → JSON current pause state
+     * - `POST /api/pause`          → request pause
+     * - `POST /api/resume`         → request resume
+     * - `PUT /api/prompts/update`  → update prompt section content
+     *
+     * @private internal utility of `ptbk coder server`
+     */
+    function startCoderHttpServer(port) {
+        const promptsDir = path.join(process.cwd(), PROMPTS_DIRECTORY_NAME);
+        const server = http.createServer(async (req, res) => {
+            try {
+                await handleRequest(req, res, promptsDir);
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                console.error(colors__default["default"].red(`Coder server request error: ${message}`));
+                if (!res.headersSent) {
+                    res.writeHead(500, { 'Content-Type': 'text/plain; charset=utf-8' });
+                }
+                res.end('Internal server error');
+            }
+        });
+        server.listen(port, () => {
+            console.info(_spaceTrim.spaceTrim(`
+                Coder server running at ${colors__default["default"].cyan(`http://localhost:${port}`)}
+                Open the URL above in your browser to see the kanban board.
+                Press ${colors__default["default"].bold('p')} to pause / resume the agent runner.
+            `));
+        });
+        return {
+            close: () => {
+                server.close();
+            },
+        };
+    }
+    /**
+     * Routes one HTTP request to the appropriate handler.
+     */
+    async function handleRequest(req, res, promptsDir) {
+        const urlPath = new URL(req.url || '/', `http://localhost`).pathname;
+        const method = (req.method || 'GET').toUpperCase();
+        // Serve the kanban UI
+        if (urlPath === '/' && method === 'GET') {
+            res.writeHead(200, {
+                'Content-Type': 'text/html; charset=utf-8',
+                'Cache-Control': 'no-cache',
+            });
+            res.end(CODER_SERVER_HTML);
+            return;
+        }
+        // GET /api/status
+        if (urlPath === '/api/status' && method === 'GET') {
+            res.writeHead(200, jsonHeaders());
+            res.end(JSON.stringify({
+                pauseState: getPauseState(),
+                pauseTargetLabel: getPauseTargetLabel(),
+            }));
+            return;
+        }
+        // GET /api/prompts
+        if (urlPath === '/api/prompts' && method === 'GET') {
+            const promptData = await loadPromptsForApi(promptsDir);
+            res.writeHead(200, jsonHeaders());
+            res.end(JSON.stringify(promptData));
+            return;
+        }
+        // POST /api/pause
+        if (urlPath === '/api/pause' && method === 'POST') {
+            requestPause();
+            res.writeHead(200, jsonHeaders());
+            res.end(JSON.stringify({ pauseState: getPauseState() }));
+            return;
+        }
+        // POST /api/resume
+        if (urlPath === '/api/resume' && method === 'POST') {
+            requestResume();
+            res.writeHead(200, jsonHeaders());
+            res.end(JSON.stringify({ pauseState: getPauseState() }));
+            return;
+        }
+        // PUT /api/prompts/update
+        if (urlPath === '/api/prompts/update' && method === 'PUT') {
+            const body = await readRequestBody(req);
+            const parsed = JSON.parse(body);
+            if (typeof parsed.filePath !== 'string' ||
+                typeof parsed.sectionIndex !== 'number' ||
+                typeof parsed.content !== 'string') {
+                throw new NotAllowed(_spaceTrim.spaceTrim(`
+                    Invalid request body for \`PUT /api/prompts/update\`.
+
+                    Expected: \`{ filePath: string, sectionIndex: number, content: string }\`
+                `));
+            }
+            await updatePromptSection(parsed.filePath, parsed.sectionIndex, parsed.content);
+            res.writeHead(200, jsonHeaders());
+            res.end(JSON.stringify({ success: true }));
+            return;
+        }
+        res.writeHead(404, { 'Content-Type': 'text/plain; charset=utf-8' });
+        res.end('Not found');
+    }
+    /**
+     * Loads all prompt files and converts them to the API response shape.
+     */
+    async function loadPromptsForApi(promptsDir) {
+        try {
+            const promptFiles = await loadPromptFiles(promptsDir);
+            return promptFiles.map((file) => ({
+                filePath: file.path,
+                fileName: file.name,
+                sections: file.sections.map((section) => ({
+                    index: section.index,
+                    status: section.status,
+                    priority: section.priority,
+                    summary: buildPromptSummary(file, section),
+                    content: buildCodexPrompt(file, section),
+                })),
+            }));
+        }
+        catch (error) {
+            // Prompts directory may not exist yet; return empty list
+            if (error.code === 'ENOENT') {
+                return [];
+            }
+            throw error;
+        }
+    }
+    /**
+     * Reads the full request body as a UTF-8 string.
+     */
+    function readRequestBody(req) {
+        return new Promise((resolve, reject) => {
+            const chunks = [];
+            req.on('data', (chunk) => chunks.push(chunk));
+            req.on('end', () => resolve(Buffer.concat(chunks).toString('utf-8')));
+            req.on('error', reject);
+        });
+    }
+    /**
+     * Returns standard JSON response headers with no-cache directives.
+     */
+    function jsonHeaders() {
+        return {
+            'Content-Type': 'application/json; charset=utf-8',
+            'Cache-Control': 'no-cache',
+        };
+    }
+    // Note: [🟡] Code for CLI command [coder server](scripts/run-codex-prompts/server/runCoderHttpServer.ts) should never be published outside of `@promptbook/cli`
+
+    /**
+     * Starts the coder server: runs prompt processing in keepAlive mode while serving a
+     * kanban web UI and REST API on the given port.
+     *
+     * Differences from `runCodexPrompts`:
+     * - Does not exit when no runnable prompts are available; instead it polls every few seconds
+     *   and resumes processing as soon as a new prompt becomes ready.
+     * - Starts a lightweight HTTP server that serves a kanban board at `http://localhost:<port>`
+     *   and exposes REST endpoints for reading prompts, controlling pause state, and editing
+     *   prompt files directly from the browser.
+     *
+     * @private internal function of `ptbk coder server`
+     */
+    async function runCodexPromptsServer(options) {
+        const { port, ...runOptions } = options;
+        const serverHandle = startCoderHttpServer(port);
+        console.info(colors__default["default"].gray('Starting prompt runner in server (keep-alive) mode…'));
+        try {
+            await runCodexPrompts({
+                ...runOptions,
+                keepAlive: true,
+            });
+        }
+        finally {
+            serverHandle.close();
+        }
+    }
+    // Note: [🟡] Code for CLI command [coder server](scripts/run-codex-prompts/main/runCodexPromptsServer.ts) should never be published outside of `@promptbook/cli`
+
+    var runCodexPromptsServer$1 = /*#__PURE__*/Object.freeze({
+        __proto__: null,
+        runCodexPromptsServer: runCodexPromptsServer
+    });
+
     /**
      * Path to the directory that holds the prompt markdown files.
      */