@promptbook/cli 0.112.0-121 → 0.112.0-123

package/esm/index.es.js

@@ -20,7 +20,7 @@ import { JSDOM } from 'jsdom';
 import CryptoJS from 'crypto-js';
 import showdown from 'showdown';
 import glob from 'glob-promise';
-import http from 'http';
+import http, { createServer } from 'http';
 import express from 'express';
 import { Server } from 'socket.io';
 import * as OpenApiValidator from 'express-openapi-validator';
@@ -31,14 +31,14 @@ import Anthropic from '@anthropic-ai/sdk';
 import Bottleneck from 'bottleneck';
 import { OpenAIClient, AzureKeyCredential } from '@azure/openai';
 import { Subject, BehaviorSubject } from 'rxjs';
-import { lookup, extension } from 'mime-types';
-import papaparse from 'papaparse';
 import { fileSearchTool, tool, Agent as Agent$1, webSearchTool, run, setDefaultOpenAIClient, setDefaultOpenAIKey } from '@openai/agents';
 import OpenAI from 'openai';
 import * as ts from 'typescript';
 import ignore from 'ignore';
 import * as readline from 'readline';
 import { emitKeypressEvents, clearLine, cursorTo, createInterface } from 'readline';
+import { lookup, extension } from 'mime-types';
+import papaparse from 'papaparse';
 import { pathToFileURL } from 'url';
 import { EventEmitter } from 'events';
 import { Client } from 'pg';
@@ -58,7 +58,7 @@ const BOOK_LANGUAGE_VERSION = '2.0.0';
  * @generated
  * @see https://github.com/webgptorg/promptbook
  */
-const PROMPTBOOK_ENGINE_VERSION = '0.112.0-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
@@ -4016,6 +4016,21 @@ function announcePauseTargetLabel(nextPauseTargetLabel) {
 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
@@ -38608,6 +38623,48 @@ function $initializeCoderFindRefactorCandidatesCommand(program) {
 // 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.bgRed(`${error.name}`));
+            console.error(colors.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.
  *
@@ -39514,8 +39571,10 @@ function $initializeCoderInitCommand(program) {
             - 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 });
     }));
 }
 /**
@@ -39607,11 +39666,12 @@ function $initializeCoderRunCommand(program) {
         `));
     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$1(`
             Wait between prompt rounds.
             Without a value (default): waits for user confirmation before each prompt (interactive mode).
@@ -39622,8 +39682,8 @@ 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, 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,
         });
@@ -39648,6 +39708,7 @@ function $initializeCoderRunCommand(program) {
             ignoreGitChanges: runnerOptions.ignoreGitChanges,
             agentName: runnerOptions.agentName,
             model: runnerOptions.model,
+            agent,
             context,
             testCommand,
             preserveLogs,
@@ -39681,7 +39742,7 @@ function $initializeCoderRunCommand(program) {
  *
  * @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}`);
@@ -39693,7 +39754,7 @@ function parseIntOption(value) {
  *
  * @private internal utility of `coder run` command
  */
-function normalizeCommandOptionValue(value) {
+function normalizeCommandOptionValue$1(value) {
     if (value === undefined) {
         return undefined;
     }
@@ -39708,6 +39769,157 @@ function normalizeCommandOptionValue(value) {
 // 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$1(`
+            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 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$1(`
+            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.bgRed(`${error.name}`));
+            console.error(colors.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$1(`
+                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
  *
@@ -39779,7 +39991,9 @@ function $initializeCoderCommand(program) {
             - 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
         `));
@@ -39787,7 +40001,9 @@ function $initializeCoderCommand(program) {
     $initializeCoderInitCommand(coderCommand);
     $initializeCoderGenerateBoilerplatesCommand(coderCommand);
     $initializeCoderFindRefactorCandidatesCommand(coderCommand);
+    $initializeCoderFindUnwrittenCommand(coderCommand);
     $initializeCoderRunCommand(coderCommand);
+    $initializeCoderServerCommand(coderCommand);
     $initializeCoderVerifyCommand(coderCommand);
     $initializeCoderFindFreshEmojiTagCommand(coderCommand);
     // If no subcommand is provided, show help
@@ -68623,6 +68839,303 @@ var findRefactorCandidates$1 = /*#__PURE__*/Object.freeze({
     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: 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 readdir(promptsDir, { withFileTypes: true });
+    const files = entries
+        .filter((entry) => entry.isFile() && entry.name.toLowerCase().endsWith('.md'))
+        .map((entry) => join(promptsDir, entry.name))
+        .sort((a, b) => a.localeCompare(b));
+    const promptFiles = [];
+    for (const filePath of files) {
+        const content = await 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 `${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.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 = 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.green('All prompts are written — nothing to do.'));
+    }
+    else {
+        console.info(colors.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.
  */
@@ -68966,6 +69479,29 @@ function formatPromptCount(count) {
     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 = resolve(currentWorkingDirectory, agentPath);
+    const agentSource = await 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.
  */
@@ -69008,104 +69544,6 @@ async function ensureWorkingTreeClean() {
     }
 }
 
-/**
- * Builds a display label using the prompt line number for easier navigation.
- */
-function buildPromptLabelForDisplay(file, section) {
-    return `${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).
  */
@@ -69138,142 +69576,6 @@ function listUpcomingTasks(files, minimumPriority = 0) {
     }));
 }
 
-/**
- * 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: 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 readdir(promptsDir, { withFileTypes: true });
-    const files = entries
-        .filter((entry) => entry.isFile() && entry.name.toLowerCase().endsWith('.md'))
-        .map((entry) => join(promptsDir, entry.name))
-        .sort((a, b) => a.localeCompare(b));
-    const promptFiles = [];
-    for (const filePath of files) {
-        const content = await 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.cyan(`Done: ${stats.done} | For agent: ${stats.forAgent}${priorityStats} | To be written: ${stats.toBeWritten}`));
-}
-
 /**
  * Groups upcoming tasks by priority, high to low.
  */
@@ -69311,36 +69613,6 @@ function printUpcomingTasks(tasks) {
     }
 }
 
-/**
- * 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.
  */
@@ -70965,9 +71237,14 @@ async function writePromptFile(file) {
  *
  * @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({
@@ -71200,6 +71477,7 @@ async function runCodexPrompts(providedOptions) {
     startPauseListenerIfNeeded(isRichUiEnabled);
     try {
         const resolvedCoderContext = await resolveCoderContext(options.context, process.cwd());
+        const resolvedAgentSystemMessage = await resolveAgentSystemMessage(options.agent, process.cwd());
         if (await runDryRunIfRequested(options)) {
             return;
         }
@@ -71239,7 +71517,13 @@ async function runCodexPrompts(providedOptions) {
                 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;
@@ -71278,6 +71562,7 @@ async function runCodexPrompts(providedOptions) {
                 nextPrompt,
                 promptLabel,
                 resolvedCoderContext,
+                resolvedAgentSystemMessage,
                 isRichUiEnabled,
                 progressDisplay,
                 uiHandle,
@@ -71453,6 +71738,19 @@ function finishWhenNoPromptIsAvailable(promptQueueSnapshot, isRichUiEnabled, uiH
     }
     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.gray(message));
+    }
+}
 /**
  * Updates UI state and plain-console output for the terminal completion message.
  */
@@ -71493,6 +71791,10 @@ async function waitForPromptConfirmationIfNeeded(options) {
  * 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.
@@ -71538,6 +71840,780 @@ var runCodexPrompts$1 = /*#__PURE__*/Object.freeze({
     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 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 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 = join(process.cwd(), PROMPTS_DIRECTORY_NAME);
+    const server = createServer(async (req, res) => {
+        try {
+            await handleRequest(req, res, promptsDir);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            console.error(colors.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$1(`
+                Coder server running at ${colors.cyan(`http://localhost:${port}`)}
+                Open the URL above in your browser to see the kanban board.
+                Press ${colors.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$1(`
+                    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.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.
  */