@promptbook/cli 0.112.0-99 → 0.113.0-0

package/esm/scripts/run-agent-chat/executeAgentChatTurn.d.ts

@@ -0,0 +1,28 @@
+import type { AgentCliHistoryMessage, AgentCliRunOptions } from './AgentCliRunOptions';
+/**
+ * Result of one local agent CLI turn.
+ */
+export type AgentChatTurnResult = {
+    readonly answer: string;
+    readonly workspacePath: string;
+    readonly messageFilePath: string;
+    readonly agentPath: string;
+};
+/**
+ * Options for executing one local agent CLI turn.
+ */
+export type ExecuteAgentChatTurnOptions = AgentCliRunOptions & {
+    readonly messages: ReadonlyArray<AgentCliHistoryMessage>;
+    readonly workspacePath?: string;
+};
+/**
+ * Executes one user turn by asking the selected harness to append `MESSAGE @Agent` to a temporary thread book.
+ */
+export declare function executeAgentChatTurn(options: ExecuteAgentChatTurnOptions): Promise<AgentChatTurnResult>;
+/**
+ * Creates an isolated workspace path under the project-local Promptbook temporary directory.
+ */
+export declare function createAgentChatWorkspacePath(options: {
+    readonly currentWorkingDirectory: string;
+    readonly agentPath: string;
+}): string;

package/esm/scripts/run-agent-chat/runAgentChat.d.ts

@@ -0,0 +1,5 @@
+import type { AgentCliRunOptions } from './AgentCliRunOptions';
+/**
+ * Runs an interactive local CLI chat with an agent book.
+ */
+export declare function runAgentChat(options: AgentCliRunOptions): Promise<void>;

package/esm/scripts/run-agent-chat/runAgentExec.d.ts

@@ -0,0 +1,11 @@
+import type { AgentCliRunOptions } from './AgentCliRunOptions';
+/**
+ * Options for `ptbk agent exec`.
+ */
+export type RunAgentExecOptions = AgentCliRunOptions & {
+    readonly message: string;
+};
+/**
+ * Runs one non-interactive local agent turn and prints the final agent answer.
+ */
+export declare function runAgentExec(options: RunAgentExecOptions): Promise<string>;

package/esm/scripts/run-agent-messages/main/AgentMessageFailureTracker.d.ts

@@ -0,0 +1,27 @@
+import type { AgentMessageFile } from '../messages/AgentMessageFile';
+/**
+ * Result of recording one failed queued-message attempt.
+ */
+export type AgentMessageFailureTrackingResult = {
+    readonly failureCount: number;
+    readonly maxMessageProcessingFailures: number;
+    readonly isMessageMovedToFailed: boolean;
+};
+/**
+ * Tracks repeated watch-level failures for queued message files and stops retrying them after a configured cap.
+ */
+export declare class AgentMessageFailureTracker {
+    private readonly failuresByMessageKey;
+    private readonly maxMessageProcessingFailures;
+    constructor(options?: {
+        readonly maxMessageProcessingFailures?: number;
+    });
+    /**
+     * Clears the failure counter after a queued message is processed successfully.
+     */
+    clearMessageFailure(projectPath: string, messageFile: AgentMessageFile | undefined): void;
+    /**
+     * Records one queued-message failure and moves the message into `messages/failed` when the retry cap is reached.
+     */
+    recordFailure(error: unknown): Promise<AgentMessageFailureTrackingResult | null>;
+}

package/esm/scripts/run-agent-messages/main/handleAgentWatchError.d.ts

@@ -19,3 +19,7 @@ export declare function handleAgentWatchError(options: {
     readonly logDirectoryPath: string;
     readonly error: unknown;
 }): Promise<void>;
+/**
+ * Recovers previously attached watch-loop context from an error-like value.
+ */
+export declare function getAgentWatchErrorContext(error: unknown): AgentWatchErrorContext | undefined;

package/esm/scripts/run-agent-messages/main/runAgentMessages.d.ts

@@ -4,4 +4,5 @@ import type { AgentRunOptions } from '../AgentRunOptions';
  */
 export declare function runAgentMessages(options: AgentRunOptions, controls?: {
     readonly shouldContinue?: () => boolean;
+    readonly queuePollIntervalMs?: number;
 }): Promise<void>;

package/esm/scripts/run-agent-messages/main/runMultipleAgentMessages.d.ts

@@ -5,6 +5,7 @@ import type { AgentRunOptions } from '../AgentRunOptions';
  */
 export type RunMultipleAgentMessagesControls = {
     readonly shouldContinue?: () => boolean;
+    readonly queuePollIntervalMs?: number;
     readonly watchErrorLogDirectoryPath?: string;
     readonly onUiInitialized?: (uiHandle: CoderRunUiHandle | undefined) => void;
 };

package/esm/scripts/run-agent-messages/main/tickAgentMessages.d.ts

@@ -19,6 +19,7 @@ export type AgentTickResult = {
 export type TickAgentMessagesOptions = {
     readonly isQuietWhenIdle?: boolean;
     readonly projectPath?: string;
+    readonly queuedMessage?: AgentMessageFile;
     readonly uiHandle?: CoderRunUiHandle;
     readonly uiPresentation?: AgentTickUiPresentation;
 };

package/esm/scripts/run-agent-messages/messages/createAgentRunnerSystemMessage.d.ts

@@ -0,0 +1,10 @@
+import type { AgentModelRequirements } from '../../../src/book-2.0/agent-source/AgentModelRequirements';
+import type { string_book } from '../../../src/book-2.0/agent-source/string_book';
+/**
+ * Compiles agent source into the behavior text passed to CLI harness runners.
+ */
+export declare function createAgentRunnerSystemMessage(agentSource: string_book): Promise<string>;
+/**
+ * Formats prepared model requirements for a text-only CLI harness prompt.
+ */
+export declare function formatAgentModelRequirementsForRunner(modelRequirements: AgentModelRequirements): string;

package/esm/scripts/run-agent-messages/messages/moveAgentMessageToFailed.d.ts

@@ -0,0 +1,17 @@
+import type { AgentMessageFile } from './AgentMessageFile';
+/**
+ * Result of moving one abandoned queued message into the failed queue.
+ */
+export type FailedAgentMessageFile = {
+    readonly absolutePath: string;
+    readonly relativePath: string;
+    readonly fileName: string;
+};
+/**
+ * Moves one repeatedly failing queued message to `messages/failed` with a visible agent failure reply.
+ */
+export declare function moveAgentMessageToFailed(options: {
+    readonly projectPath: string;
+    readonly messageFile: AgentMessageFile;
+    readonly failureReason: string;
+}): Promise<FailedAgentMessageFile>;

package/esm/scripts/run-codex-prompts/common/buildCoderRunProgressSnapshot.d.ts

@@ -19,5 +19,9 @@ export type CoderRunProgressSnapshot = {
 };
 /**
  * Builds a session-scoped progress snapshot from prompt stats and elapsed active time.
+ *
+ * When the current session has not finished any prompt yet but a `cachedAveragePromptDurationMs` is
+ * provided (loaded from the per-config estimate cache stored in the temp folder), the snapshot uses
+ * that historical average to project the remaining work instead of waiting for the first completion.
  */
-export declare function buildCoderRunProgressSnapshot(stats: PromptStats, elapsedDuration: moment.Duration, initialDone: number): CoderRunProgressSnapshot;
+export declare function buildCoderRunProgressSnapshot(stats: PromptStats, elapsedDuration: moment.Duration, initialDone: number, cachedAveragePromptDurationMs?: number): CoderRunProgressSnapshot;

package/esm/scripts/run-codex-prompts/common/cliProgressDisplay.d.ts

@@ -15,10 +15,17 @@ export declare class CliProgressDisplay {
     private readonly timer;
     private isHeaderReserved;
     private interval;
+    private cachedAveragePromptDurationMs;
     /**
      * Creates a new display that uses the provided start time when computing estimates.
      */
     constructor(startTime: moment.Moment, minimumPriority: number);
+    /**
+     * Sets the cached average prompt duration (in milliseconds) loaded from the temp-folder estimate cache.
+     *
+     * Used to project completion estimates before the first prompt of the current session finishes.
+     */
+    setCachedAveragePromptDurationMs(cachedAveragePromptDurationMs: number | undefined): void;
     /**
      * Updates the progress statistics shown in the header.
      */

package/esm/scripts/run-codex-prompts/common/coderRunEstimateCache.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Cache key used to uniquely identify the average prompt duration for a given runner configuration.
+ *
+ * @private internal type of `coderRunEstimateCache`
+ */
+export type CoderRunEstimateCacheKey = {
+    readonly harness: string;
+    readonly model?: string;
+    readonly thinkingLevel?: string;
+};
+/**
+ * Loads the cached average prompt duration for the given runner configuration.
+ *
+ * Returns `undefined` when no usable cache entry exists. Cache failures must never break the run, so this
+ * function swallows IO and parsing errors instead of throwing.
+ *
+ * @public exported for use by the coder run progress displays
+ */
+export declare function loadCachedAveragePromptDurationMs(key: CoderRunEstimateCacheKey): Promise<number | undefined>;
+/**
+ * Records a new prompt-duration sample for the given runner configuration into the temp folder cache.
+ *
+ * Updates a running average so future `ptbk coder run` / `ptbk coder server` invocations can show
+ * meaningful estimates immediately, before the first prompt of the new session has completed.
+ *
+ * Cache failures are swallowed because the next-run estimate is best-effort and must not affect the
+ * current run.
+ *
+ * @public exported for use by the prompt round finalizer
+ */
+export declare function recordPromptDurationSample(key: CoderRunEstimateCacheKey, promptDurationMs: number): Promise<void>;

package/esm/scripts/run-codex-prompts/common/parseDuration.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Parses a human-readable duration string into milliseconds.
+ *
+ * Supported formats: `Xh`, `Xm`, `Xs`, and combinations like `1h30m`, `1h30m5s`.
+ *
+ * @returns Duration in milliseconds
+ * @throws When the string does not match any supported format
+ *
+ * @private internal utility of `ptbk coder run`
+ */
+export declare function parseDuration(durationString: string): number;
+/**
+ * Formats a duration in milliseconds into a compact human-readable string.
+ *
+ * Examples: `3600000` → `"1h"`, `90000` → `"1m 30s"`, `5000` → `"5s"`.
+ *
+ * @private internal utility of `ptbk coder run`
+ */
+export declare function formatDurationMs(ms: number): string;

package/esm/scripts/run-codex-prompts/common/progressFormatting.d.ts

@@ -1,6 +1,8 @@
 import moment from 'moment';
 /**
  * Calendar formats used when displaying the estimated completion time.
+ *
+ * Uses 24-hour format (`HH:mm`) so estimates are unambiguous (for example `17:30` instead of `5:30`).
  */
 export declare const ESTIMATED_DONE_CALENDAR_FORMATS: {
     sameDay: string;

package/esm/scripts/run-codex-prompts/common/resolveAgentSystemMessage.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Reads an optional agent `.book` file and compiles its system message for injection into coder prompts.
+ *
+ * Returns `undefined` when no agent path is provided.
+ */
+export declare function resolveAgentSystemMessage(agentPath: string | undefined, currentWorkingDirectory: string): Promise<string | undefined>;

package/esm/scripts/run-codex-prompts/common/resolveInlineOrFileText.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Options for resolving a CLI value that can be either inline text or a file path.
+ */
+type ResolveInlineOrFileTextOptions = {
+    readonly textReference: string | undefined;
+    readonly currentWorkingDirectory: string;
+    readonly contextLabel: string;
+    readonly optionName: string;
+};
+/**
+ * Resolves optional CLI text provided inline or via a file path.
+ */
+export declare function resolveInlineOrFileText(options: ResolveInlineOrFileTextOptions): Promise<string | undefined>;
+export {};

package/esm/scripts/run-codex-prompts/common/runGoScript/printLiveScriptChunk.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Prints one live shell output chunk to the terminal when console mirroring is enabled.
+ */
+export declare function printLiveScriptChunk(chunk: string, source: 'stdout' | 'stderr', shouldPrintLiveOutput: boolean): void;

package/esm/scripts/run-codex-prompts/common/sleepWithCountdown.d.ts

@@ -0,0 +1,27 @@
+import type { CoderRunUiHandle } from '../ui/renderCoderRunUi';
+/**
+ * Distinct kinds of wait shown by the run loop so the UI can label them clearly.
+ *
+ * @public exported from `@promptbook/cli`
+ */
+export type CoderRunWaitKind = 'after-prompt' | 'between-prompts' | 'after-error';
+/**
+ * Returns the human-readable status message used for one wait kind.
+ *
+ * @private internal utility of `sleepWithCountdown`
+ */
+export declare function describeCoderRunWait(waitKind: CoderRunWaitKind, remainingMs: number, totalMs?: number): string;
+/**
+ * Sleeps the requested duration while refreshing the status message on a UI handle and the plain console.
+ *
+ * The wait kind is shown in the UI status so the user can distinguish `--wait-after-prompt`,
+ * `--wait-between-prompts`, and `--wait-after-error` waits at a glance.
+ *
+ * @public exported from `@promptbook/cli`
+ */
+export declare function sleepWithCountdown(options: {
+    durationMs: number;
+    waitKind: CoderRunWaitKind;
+    isRichUiEnabled: boolean;
+    uiHandle?: CoderRunUiHandle;
+}): Promise<void>;

package/esm/scripts/run-codex-prompts/common/waitForPause.d.ts

@@ -30,6 +30,18 @@ export declare function checkPause(options?: {
  * Returns the current pause state for external consumers such as the terminal UI.
  */
 export declare function getPauseState(): CoderRunPauseState;
+/**
+ * Returns the label of the next checkpoint where pausing will take effect.
+ */
+export declare function getPauseTargetLabel(): string;
+/**
+ * Updates the label of the next pause checkpoint.
+ */
+export declare function announcePauseTargetLabel(nextPauseTargetLabel: string): void;
+/**
+ * Restores the default generic pause target label.
+ */
+export declare function resetPauseTargetLabel(): void;
 /**
  * Requests a pause from an external controller (e.g. the Ink UI).
  */

package/esm/scripts/run-codex-prompts/git/commitChanges.d.ts

@@ -1,11 +1,13 @@
 /**
  * Commits staged changes with the provided message using the dedicated coding-agent identity when configured,
  * otherwise falls back to the default Git configuration. Remote pushing is opt-in via `options.autoPush`,
- * `options.includePaths` can restrict staging, and `options.excludePaths` can keep temporary artifacts out of the created commit.
+ * `options.includePaths` can restrict staging, `options.onlyPaths` can restrict the commit pathspec,
+ * and `options.excludePaths` can keep temporary artifacts out of the created commit.
  */
 export declare function commitChanges(message: string, options?: {
     autoPush?: boolean;
     includePaths?: ReadonlyArray<string>;
+    onlyPaths?: ReadonlyArray<string>;
     excludePaths?: ReadonlyArray<string>;
     projectPath?: string;
 }): Promise<void>;

package/esm/scripts/run-codex-prompts/main/findUnwrittenPrompts.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Options for `findUnwrittenPrompts`.
+ */
+export type FindUnwrittenPromptsOptions = {
+    /**
+     * Minimum priority level — sections below this threshold are excluded.
+     * @default 0
+     */
+    readonly priority?: number;
+};
+/**
+ * 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`
+ */
+export declare function findUnwrittenPrompts(options?: FindUnwrittenPromptsOptions): Promise<number>;

package/esm/scripts/run-codex-prompts/main/runCodexPromptsServer.d.ts

@@ -0,0 +1,27 @@
+import type { number_port } from '../../../src/types/number_positive';
+import type { RunOptions } from '../cli/RunOptions';
+/**
+ * Options for `ptbk coder server` combining the standard run options with a server port.
+ *
+ * @private internal type of `ptbk coder server`
+ */
+export type CoderServerRunOptions = RunOptions & {
+    /**
+     * TCP port on which the kanban HTTP server will listen.
+     */
+    port: number_port;
+};
+/**
+ * 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`
+ */
+export declare function runCodexPromptsServer(options: CoderServerRunOptions): Promise<void>;

package/esm/scripts/run-codex-prompts/main/runPromptRound.d.ts

@@ -1,5 +1,6 @@
-import type { CliProgressDisplay } from '../common/cliProgressDisplay';
 import type { RunOptions } from '../cli/RunOptions';
+import type { CliProgressDisplay } from '../common/cliProgressDisplay';
+import type { WaitForCoderRunPauseCheckpoint } from '../common/CoderRunPauseCheckpoint';
 import type { PromptSelection } from '../prompts/types/PromptSelection';
 import type { PromptRunner } from '../runners/types/PromptRunner';
 import type { CoderRunUiHandle } from '../ui/renderCoderRunUi';
@@ -16,15 +17,16 @@ type RunPromptRoundOptions = {
     nextPrompt: PromptSelection;
     promptLabel: string;
     resolvedCoderContext?: string;
+    resolvedAgentSystemMessage?: string;
     isRichUiEnabled: boolean;
     progressDisplay?: CliProgressDisplay;
     uiHandle?: CoderRunUiHandle;
-    waitForRequestedPause(): Promise<void>;
+    waitForRequestedPause: WaitForCoderRunPauseCheckpoint;
 };
 /**
  * Runs one prompt round from prompt construction through commit or failure logging.
  *
  * @private function of runCodexPrompts
  */
-export declare function runPromptRound({ options, runner, runnerMetadata, nextPrompt, promptLabel, resolvedCoderContext, isRichUiEnabled, progressDisplay, uiHandle, waitForRequestedPause, }: RunPromptRoundOptions): Promise<void>;
+export declare function runPromptRound({ options, runner, runnerMetadata, nextPrompt, promptLabel, resolvedCoderContext, resolvedAgentSystemMessage, isRichUiEnabled, progressDisplay, uiHandle, waitForRequestedPause, }: RunPromptRoundOptions): Promise<void>;
 export {};

package/esm/scripts/run-codex-prompts/runners/claude-code/ClaudeCodeRunner.d.ts

@@ -1,15 +1,17 @@
 import type { PromptRunOptions } from '../types/PromptRunOptions';
 import type { PromptRunResult } from '../types/PromptRunResult';
 import type { PromptRunner } from '../types/PromptRunner';
+import type { ClaudeCodeRunnerOptions } from './ClaudeCodeRunnerOptions';
 /**
  * Runs prompts via the Claude Code CLI.
  */
 export declare class ClaudeCodeRunner implements PromptRunner {
+    private readonly options;
     readonly name = "claude-code";
     /**
      * Creates a new Claude Code runner.
      */
-    constructor();
+    constructor(options?: ClaudeCodeRunnerOptions);
     /**
      * Runs the prompt using Claude Code and parses usage output.
      */

package/esm/scripts/run-codex-prompts/server/buildCoderServerPromptResponse.d.ts

@@ -0,0 +1,50 @@
+import type { PromptFile } from '../prompts/types/PromptFile';
+import type { PromptStatus } from '../prompts/types/PromptStatus';
+import type { CoderRunUiState } from '../ui/CoderRunUiState';
+/**
+ * Browser board columns used by `ptbk coder server`.
+ */
+export type CoderServerBoardColumn = 'backlog' | 'low-priority' | 'todo' | 'in-progress' | 'done' | 'errors' | 'finished';
+/**
+ * UI tag attached to one prompt card.
+ */
+export type CoderServerPromptTag = {
+    readonly id: 'not-ready' | 'unwritten' | 'implementing' | 'verifying';
+    readonly label: string;
+};
+/**
+ * One prompt section as returned from `GET /api/prompts`.
+ */
+export type CoderServerPromptSectionResponse = {
+    readonly index: number;
+    readonly status: PromptStatus;
+    readonly column: CoderServerBoardColumn;
+    readonly priority: number;
+    readonly summary: string;
+    readonly content: string;
+    readonly label: string;
+    readonly tags: readonly CoderServerPromptTag[];
+};
+/**
+ * One prompt file as returned from `GET /api/prompts`.
+ */
+export type CoderServerPromptFileResponse = {
+    readonly filePath: string;
+    readonly fileName: string;
+    readonly relativeFilePath: string;
+    readonly isFinished: boolean;
+    readonly sections: readonly CoderServerPromptSectionResponse[];
+};
+/**
+ * Input for converting parsed prompt files into the browser API shape.
+ */
+export type BuildCoderServerPromptFileResponsesOptions = {
+    readonly promptFiles: readonly PromptFile[];
+    readonly finishedPromptFiles: readonly PromptFile[];
+    readonly minimumPriority: number;
+    readonly uiState?: CoderRunUiState;
+};
+/**
+ * Converts parsed prompt files into a web-board response with derived columns and tags.
+ */
+export declare function buildCoderServerPromptFileResponses(options: BuildCoderServerPromptFileResponsesOptions): CoderServerPromptFileResponse[];

package/esm/scripts/run-codex-prompts/server/buildCoderServerRunState.d.ts

@@ -0,0 +1,23 @@
+import type { CoderRunConfig, CoderRunPhase, CoderRunProgressSnapshot, CoderRunUiState } from '../ui/CoderRunUiState';
+import type { AgentRunStatusTableRow } from '../ui/buildCoderRunUiFrame';
+/**
+ * Snapshot of the active coder runner exposed to the browser UI.
+ */
+export type CoderServerRunState = {
+    readonly config: CoderRunConfig;
+    readonly phase: CoderRunPhase;
+    readonly currentPromptLabel: string;
+    readonly currentAttempt: number;
+    readonly maxAttempts: number;
+    readonly statusMessage: string;
+    readonly detailLines: readonly string[];
+    readonly agentStatusLines: readonly string[];
+    readonly agentStatusTableRows: readonly AgentRunStatusTableRow[];
+    readonly agentOutputLines: readonly string[];
+    readonly errors: readonly string[];
+    readonly progress: CoderRunProgressSnapshot;
+};
+/**
+ * Builds a plain JSON-safe snapshot from the shared terminal UI state.
+ */
+export declare function buildCoderServerRunState(uiState: CoderRunUiState): CoderServerRunState;

package/esm/scripts/run-codex-prompts/server/coderServerHtml.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 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`
+ */
+export declare const CODER_SERVER_HTML = "<!DOCTYPE html>\n<html lang=\"en\">\n<head>\n  <meta charset=\"UTF-8\">\n  <meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\">\n  <title>Ptbk Coder Server</title>\n  <style>\n    * { box-sizing: border-box; margin: 0; padding: 0; }\n    body {\n      font-family: -apple-system, BlinkMacSystemFont, \"Segoe UI\", Roboto, sans-serif;\n      background: #f6f7f9;\n      color: #1f2933;\n      min-height: 100vh;\n    }\n\n    header {\n      background: #22313f;\n      color: white;\n      padding: 12px 18px;\n      display: flex;\n      align-items: center;\n      gap: 12px;\n      position: sticky;\n      top: 0;\n      z-index: 10;\n      box-shadow: 0 2px 10px rgba(15,23,42,0.22);\n    }\n    header h1 { font-size: 17px; font-weight: 700; flex-shrink: 0; letter-spacing: 0; }\n\n    .status-badge {\n      padding: 3px 10px;\n      border-radius: 999px;\n      font-size: 11px;\n      font-weight: 700;\n      text-transform: uppercase;\n      flex-shrink: 0;\n    }\n    .status-RUNNING { background: #0b875b; color: white; }\n    .status-PAUSING { background: #d97904; color: white; }\n    .status-PAUSED { background: #b42318; color: white; }\n\n    #pause-label {\n      font-size: 12px;\n      color: rgba(255,255,255,0.75);\n      flex: 1;\n      min-width: 0;\n      overflow: hidden;\n      text-overflow: ellipsis;\n      white-space: nowrap;\n    }\n\n    .btn {\n      padding: 6px 12px;\n      border: 0;\n      border-radius: 4px;\n      cursor: pointer;\n      font-size: 13px;\n      font-weight: 700;\n      transition: background 0.15s, opacity 0.15s;\n      flex-shrink: 0;\n    }\n    .btn:disabled { opacity: 0.55; cursor: default; }\n    .btn-pause { background: #ffd166; color: #1f2933; }\n    .btn-resume { background: #0b875b; color: white; }\n    .btn-save { background: #2563eb; color: white; }\n    .btn-cancel { background: #edf0f4; color: #1f2933; }\n\n    .run-strip {\n      background: white;\n      border-bottom: 1px solid #d8dee8;\n      padding: 12px 18px;\n      display: grid;\n      grid-template-columns: minmax(220px, 1.2fr) minmax(240px, 1fr) minmax(260px, 1.4fr);\n      gap: 14px;\n      align-items: center;\n    }\n    .run-title {\n      font-size: 14px;\n      font-weight: 700;\n      overflow: hidden;\n      text-overflow: ellipsis;\n      white-space: nowrap;\n    }\n    .run-subtitle,\n    .run-current,\n    .run-output {\n      color: #64748b;\n      font-size: 12px;\n      line-height: 1.45;\n      overflow: hidden;\n    }\n    .run-current,\n    .run-output {\n      display: -webkit-box;\n      -webkit-box-orient: vertical;\n      -webkit-line-clamp: 2;\n    }\n    .progress-shell {\n      display: grid;\n      grid-template-columns: 1fr auto;\n      gap: 8px;\n      align-items: center;\n    }\n    .progress-track {\n      height: 10px;\n      background: #e4e9f0;\n      border-radius: 999px;\n      overflow: hidden;\n    }\n    .progress-fill {\n      display: block;\n      height: 100%;\n      width: 0;\n      background: linear-gradient(90deg, #0b875b, #2563eb);\n      transition: width 0.2s;\n    }\n    .progress-label {\n      color: #475569;\n      font-size: 12px;\n      font-weight: 700;\n      min-width: 72px;\n      text-align: right;\n    }\n\n    .board {\n      display: flex;\n      gap: 14px;\n      padding: 16px;\n      overflow-x: auto;\n      min-height: calc(100vh - 119px);\n      align-items: flex-start;\n    }\n\n    .column {\n      background: #e9edf3;\n      border-top: 4px solid #94a3b8;\n      border-radius: 6px;\n      padding: 10px;\n      min-width: 250px;\n      width: 270px;\n      flex-shrink: 0;\n    }\n    .column-backlog { border-top-color: #64748b; }\n    .column-low-priority { border-top-color: #d97904; }\n    .column-todo { border-top-color: #2563eb; }\n    .column-in-progress { border-top-color: #7c3aed; }\n    .column-done { border-top-color: #0b875b; }\n    .column-errors { border-top-color: #b42318; }\n    .column-finished { border-top-color: #0891b2; }\n\n    .column-header {\n      font-size: 12px;\n      font-weight: 800;\n      text-transform: uppercase;\n      color: #475569;\n      margin-bottom: 10px;\n      display: flex;\n      align-items: center;\n      justify-content: space-between;\n      gap: 8px;\n    }\n    .column-count {\n      background: rgba(255,255,255,0.72);\n      border-radius: 999px;\n      padding: 2px 8px;\n      font-size: 11px;\n      color: #475569;\n    }\n    .column-cards { min-height: 40px; }\n\n    .card {\n      background: white;\n      border-radius: 6px;\n      padding: 10px 12px;\n      margin-bottom: 8px;\n      box-shadow: 0 1px 3px rgba(15,23,42,0.12);\n      cursor: pointer;\n      border-left: 3px solid #94a3b8;\n    }\n    .card:hover { box-shadow: 0 4px 12px rgba(15,23,42,0.16); }\n    .card-backlog { border-left-color: #64748b; }\n    .card-low-priority { border-left-color: #d97904; }\n    .card-todo { border-left-color: #2563eb; }\n    .card-in-progress { border-left-color: #7c3aed; }\n    .card-done { border-left-color: #0b875b; }\n    .card-errors { border-left-color: #b42318; }\n    .card-finished { border-left-color: #0891b2; }\n\n    .card-file {\n      font-size: 10px;\n      color: #7b8794;\n      margin-bottom: 6px;\n      font-weight: 600;\n      overflow: hidden;\n      text-overflow: ellipsis;\n      white-space: nowrap;\n    }\n    .card-summary {\n      font-size: 13px;\n      line-height: 1.45;\n      color: #1f2933;\n      word-break: break-word;\n      white-space: pre-wrap;\n      max-height: 76px;\n      overflow: hidden;\n      display: -webkit-box;\n      -webkit-line-clamp: 4;\n      -webkit-box-orient: vertical;\n    }\n    .card-tags {\n      display: flex;\n      flex-wrap: wrap;\n      gap: 5px;\n      margin-top: 8px;\n    }\n    .card-tag {\n      border-radius: 999px;\n      padding: 2px 7px;\n      font-size: 10px;\n      font-weight: 800;\n      line-height: 1.35;\n    }\n    .tag-not-ready { background: #e2e8f0; color: #475569; }\n    .tag-unwritten { background: #fff4cc; color: #8a5a00; }\n    .tag-implementing { background: #ede9fe; color: #5b21b6; }\n    .tag-verifying { background: #fae8ff; color: #86198f; }\n    .tag-priority { background: #ffedd5; color: #9a3412; }\n\n    .empty-column {\n      color: #94a3b8;\n      font-size: 12px;\n      padding: 10px 4px;\n      text-align: center;\n    }\n\n    .modal-overlay {\n      position: fixed;\n      inset: 0;\n      background: rgba(15,23,42,0.58);\n      display: flex;\n      align-items: flex-start;\n      justify-content: center;\n      padding: 56px 16px 16px;\n      z-index: 100;\n    }\n    .modal-overlay.hidden { display: none; }\n\n    .modal {\n      background: white;\n      border-radius: 8px;\n      width: 100%;\n      max-width: 720px;\n      padding: 18px;\n      box-shadow: 0 14px 40px rgba(15,23,42,0.28);\n    }\n    .modal-header {\n      display: flex;\n      align-items: flex-start;\n      justify-content: space-between;\n      margin-bottom: 14px;\n      gap: 12px;\n    }\n    .modal-meta { flex: 1; min-width: 0; }\n    .modal-file {\n      font-size: 11px;\n      color: #7b8794;\n      margin-bottom: 4px;\n      overflow: hidden;\n      text-overflow: ellipsis;\n      white-space: nowrap;\n    }\n    .modal-section-label { font-size: 14px; font-weight: 700; color: #1f2933; }\n    .modal-status {\n      font-size: 11px;\n      font-weight: 800;\n      padding: 3px 8px;\n      border-radius: 999px;\n      text-transform: uppercase;\n      flex-shrink: 0;\n    }\n    .status-backlog { background: #e2e8f0; color: #475569; }\n    .status-low-priority { background: #ffedd5; color: #9a3412; }\n    .status-todo { background: #dbeafe; color: #1d4ed8; }\n    .status-in-progress { background: #ede9fe; color: #5b21b6; }\n    .status-done { background: #dcfce7; color: #166534; }\n    .status-errors { background: #fee2e2; color: #991b1b; }\n    .status-finished { background: #cffafe; color: #155e75; }\n    .modal-close {\n      background: transparent;\n      border: 0;\n      color: #64748b;\n      cursor: pointer;\n      font-size: 20px;\n      padding: 0 4px;\n      line-height: 1;\n    }\n    .modal-close:hover { color: #1f2933; }\n\n    textarea {\n      width: 100%;\n      min-height: 300px;\n      font-family: \"SFMono-Regular\", Consolas, \"Courier New\", monospace;\n      font-size: 13px;\n      border: 2px solid #d8dee8;\n      border-radius: 4px;\n      padding: 10px 12px;\n      resize: vertical;\n      line-height: 1.6;\n      color: #1f2933;\n    }\n    textarea:focus {\n      outline: none;\n      border-color: #2563eb;\n      box-shadow: 0 0 0 3px rgba(37,99,235,0.12);\n    }\n    .modal-actions {\n      display: flex;\n      gap: 8px;\n      margin-top: 14px;\n      justify-content: flex-end;\n    }\n\n    .error-banner {\n      background: #fee2e2;\n      border-bottom: 2px solid #b42318;\n      color: #991b1b;\n      padding: 8px 18px;\n      font-size: 13px;\n      font-weight: 700;\n    }\n    .error-banner.hidden { display: none; }\n\n    @media (max-width: 860px) {\n      header { flex-wrap: wrap; }\n      #pause-label { order: 4; flex-basis: 100%; }\n      .run-strip { grid-template-columns: 1fr; }\n      .board { min-height: calc(100vh - 212px); }\n    }\n  </style>\n</head>\n<body>\n  <div id=\"error-banner\" class=\"error-banner hidden\"></div>\n\n  <header>\n    <h1>Ptbk Coder Server</h1>\n    <span id=\"status-badge\" class=\"status-badge status-RUNNING\">RUNNING</span>\n    <span id=\"pause-label\"></span>\n    <button id=\"toggle-btn\" class=\"btn btn-pause\">Pause</button>\n  </header>\n\n  <section class=\"run-strip\">\n    <div>\n      <div class=\"run-title\" id=\"run-title\">Initializing...</div>\n      <div class=\"run-subtitle\" id=\"run-subtitle\">Loading runner state</div>\n    </div>\n    <div class=\"progress-shell\">\n      <div class=\"progress-track\"><span class=\"progress-fill\" id=\"progress-fill\"></span></div>\n      <div class=\"progress-label\" id=\"progress-label\">0%</div>\n    </div>\n    <div>\n      <div class=\"run-current\" id=\"run-current\">No active prompt</div>\n      <div class=\"run-output\" id=\"run-output\"></div>\n    </div>\n  </section>\n\n  <div class=\"board\" id=\"board\"></div>\n\n  <div class=\"modal-overlay hidden\" id=\"modal-overlay\">\n    <div class=\"modal\">\n      <div class=\"modal-header\">\n        <div class=\"modal-meta\">\n          <div class=\"modal-file\" id=\"modal-file\"></div>\n          <div class=\"modal-section-label\" id=\"modal-section-label\"></div>\n        </div>\n        <span class=\"modal-status\" id=\"modal-status-badge\"></span>\n        <button class=\"modal-close\" id=\"modal-close\" title=\"Close\">&times;</button>\n      </div>\n\n      <textarea id=\"modal-content\" placeholder=\"Prompt content\"></textarea>\n\n      <div class=\"modal-actions\">\n        <button class=\"btn btn-cancel\" id=\"cancel-button\">Cancel</button>\n        <button class=\"btn btn-save\" id=\"save-button\">Save</button>\n      </div>\n    </div>\n  </div>\n\n  <script>\n    \"use strict\";\n\n    const BOARD_COLUMNS = [\n      { id: \"backlog\", title: \"Backlog\" },\n      { id: \"low-priority\", title: \"Low priority\" },\n      { id: \"todo\", title: \"To do\" },\n      { id: \"in-progress\", title: \"In progress\" },\n      { id: \"done\", title: \"Done\" },\n      { id: \"errors\", title: \"Errors\" },\n      { id: \"finished\", title: \"Finished\" },\n    ];\n\n    let modalState = null;\n    let lastPauseState = \"RUNNING\";\n\n    function getColumnTitle(columnId) {\n      const column = BOARD_COLUMNS.find((columnCandidate) => columnCandidate.id === columnId);\n      return column ? column.title : columnId;\n    }\n\n    function showError(message) {\n      const banner = document.getElementById(\"error-banner\");\n      banner.textContent = message;\n      banner.classList.remove(\"hidden\");\n      clearTimeout(banner.timer);\n      banner.timer = setTimeout(() => banner.classList.add(\"hidden\"), 6000);\n    }\n\n    function escapeHtml(value) {\n      const element = document.createElement(\"div\");\n      element.textContent = String(value);\n      return element.innerHTML;\n    }\n\n    function renderBoardSkeleton() {\n      const board = document.getElementById(\"board\");\n      board.innerHTML = \"\";\n\n      for (const column of BOARD_COLUMNS) {\n        const columnElement = document.createElement(\"section\");\n        columnElement.className = \"column column-\" + column.id;\n        columnElement.innerHTML =\n          '<div class=\"column-header\">' +\n            '<span>' + escapeHtml(column.title) + '</span>' +\n            '<span class=\"column-count\" id=\"count-' + column.id + '\">0</span>' +\n          '</div>' +\n          '<div class=\"column-cards\" id=\"cards-' + column.id + '\">' +\n            '<div class=\"empty-column\">Loading</div>' +\n          '</div>';\n        board.appendChild(columnElement);\n      }\n    }\n\n    async function fetchStatus() {\n      try {\n        const response = await fetch(\"/api/status\");\n        if (!response.ok) {\n          showError(\"Status API error: \" + response.status);\n          return;\n        }\n\n        const status = await response.json();\n        renderPauseState(status);\n        renderRunState(status.runState);\n      } catch (error) {\n        showError(\"Could not reach coder server: \" + error.message);\n      }\n    }\n\n    function renderPauseState(status) {\n      lastPauseState = status.pauseState;\n\n      const badge = document.getElementById(\"status-badge\");\n      badge.textContent = status.pauseState;\n      badge.className = \"status-badge status-\" + status.pauseState;\n\n      const toggleButton = document.getElementById(\"toggle-btn\");\n      const pauseLabel = document.getElementById(\"pause-label\");\n\n      if (status.pauseState === \"RUNNING\") {\n        toggleButton.textContent = \"Pause\";\n        toggleButton.className = \"btn btn-pause\";\n        pauseLabel.textContent = \"\";\n        return;\n      }\n\n      toggleButton.textContent = \"Resume\";\n      toggleButton.className = \"btn btn-resume\";\n      pauseLabel.textContent =\n        (status.pauseState === \"PAUSING\" ? \"Pausing before: \" : \"Paused before: \") +\n        (status.pauseTargetLabel || \"next checkpoint\");\n    }\n\n    function renderRunState(runState) {\n      if (!runState) {\n        document.getElementById(\"run-title\").textContent = \"Waiting for runner state\";\n        document.getElementById(\"run-subtitle\").textContent = \"\";\n        return;\n      }\n\n      const progress = runState.progress || {};\n      const percentage = Number(progress.percentage || 0);\n      const runnerParts = [runState.config.agentName, runState.config.modelName, runState.config.thinkingLevel]\n        .filter(Boolean);\n\n      document.getElementById(\"run-title\").textContent = runState.statusMessage || runState.phase;\n      document.getElementById(\"run-subtitle\").textContent = runnerParts.join(\" / \");\n      document.getElementById(\"progress-fill\").style.width = Math.max(0, Math.min(100, percentage)) + \"%\";\n      document.getElementById(\"progress-label\").textContent =\n        percentage + \"% \" + (progress.sessionDone || 0) + \"/\" + (progress.sessionTotal || 0);\n      document.getElementById(\"run-current\").textContent = runState.currentPromptLabel\n        ? runState.currentPromptLabel + \" - attempt \" + runState.currentAttempt + \"/\" + runState.maxAttempts\n        : \"No active prompt\";\n\n      renderRunOutput(runState);\n    }\n\n    function renderRunOutput(runState) {\n      const statusLines = (runState.agentStatusTableRows || []).map((row) =>\n        row.status + \" - \" + row.agentName + (row.url ? \" - \" + row.url : \"\")\n      );\n      const outputLines = [\n        ...(runState.agentStatusLines || []),\n        ...statusLines,\n        ...(runState.agentOutputLines || []),\n        ...(runState.errors || []).map((errorLine) => \"Error: \" + errorLine),\n      ].slice(-3);\n\n      document.getElementById(\"run-output\").textContent = outputLines.join(\"\\n\");\n    }\n\n    async function fetchPrompts() {\n      try {\n        const response = await fetch(\"/api/prompts\");\n        if (!response.ok) {\n          showError(\"Prompts API error: \" + response.status);\n          return;\n        }\n\n        renderBoard(await response.json());\n      } catch (error) {\n        showError(\"Could not load prompts: \" + error.message);\n      }\n    }\n\n    function renderBoard(promptFiles) {\n      const columns = Object.fromEntries(BOARD_COLUMNS.map((column) => [column.id, []]));\n\n      for (const file of promptFiles) {\n        for (const section of file.sections) {\n          if (columns[section.column]) {\n            columns[section.column].push({ file, section });\n          }\n        }\n      }\n\n      for (const column of BOARD_COLUMNS) {\n        renderColumn(column.id, columns[column.id]);\n      }\n    }\n\n    function renderColumn(columnId, cards) {\n      const container = document.getElementById(\"cards-\" + columnId);\n      const countElement = document.getElementById(\"count-\" + columnId);\n\n      countElement.textContent = cards.length;\n      container.innerHTML = \"\";\n\n      if (cards.length === 0) {\n        container.innerHTML = '<div class=\"empty-column\">Empty</div>';\n        return;\n      }\n\n      for (const cardData of cards) {\n        container.appendChild(createPromptCard(cardData.file, cardData.section));\n      }\n    }\n\n    function createPromptCard(file, section) {\n      const card = document.createElement(\"article\");\n      card.className = \"card card-\" + section.column;\n      card.innerHTML =\n        '<div class=\"card-file\">' + escapeHtml(file.relativeFilePath || file.fileName) + \" #\" + (section.index + 1) + '</div>' +\n        '<div class=\"card-summary\">' + escapeHtml(section.summary) + '</div>' +\n        renderTags(section);\n      card.onclick = () => openModal(file, section);\n      return card;\n    }\n\n    function renderTags(section) {\n      const tags = [...(section.tags || [])];\n      if (section.priority > 0) {\n        tags.push({ id: \"priority\", label: \"P\" + section.priority });\n      }\n\n      if (tags.length === 0) {\n        return \"\";\n      }\n\n      return '<div class=\"card-tags\">' + tags.map((tag) =>\n        '<span class=\"card-tag tag-' + escapeHtml(tag.id) + '\">' + escapeHtml(tag.label) + '</span>'\n      ).join(\"\") + '</div>';\n    }\n\n    function openModal(file, section) {\n      modalState = { filePath: file.filePath, sectionIndex: section.index };\n\n      document.getElementById(\"modal-file\").textContent = file.relativeFilePath || file.fileName;\n      document.getElementById(\"modal-section-label\").textContent = \"Section \" + (section.index + 1);\n\n      const statusBadge = document.getElementById(\"modal-status-badge\");\n      statusBadge.textContent = getColumnTitle(section.column);\n      statusBadge.className = \"modal-status status-\" + section.column;\n\n      document.getElementById(\"modal-content\").value = section.content;\n      document.getElementById(\"modal-overlay\").classList.remove(\"hidden\");\n      setTimeout(() => document.getElementById(\"modal-content\").focus(), 50);\n    }\n\n    function closeModal() {\n      document.getElementById(\"modal-overlay\").classList.add(\"hidden\");\n      modalState = null;\n    }\n\n    async function saveModal() {\n      if (!modalState) {\n        return;\n      }\n\n      const content = document.getElementById(\"modal-content\").value;\n      const saveButton = document.getElementById(\"save-button\");\n      saveButton.disabled = true;\n      saveButton.textContent = \"Saving...\";\n\n      try {\n        const response = await fetch(\"/api/prompts/update\", {\n          method: \"PUT\",\n          headers: { \"Content-Type\": \"application/json\" },\n          body: JSON.stringify({\n            filePath: modalState.filePath,\n            sectionIndex: modalState.sectionIndex,\n            content,\n          }),\n        });\n\n        if (!response.ok) {\n          throw new Error(\"HTTP \" + response.status);\n        }\n\n        closeModal();\n        await fetchPrompts();\n      } catch (error) {\n        showError(\"Save failed: \" + error.message);\n      } finally {\n        saveButton.disabled = false;\n        saveButton.textContent = \"Save\";\n      }\n    }\n\n    document.getElementById(\"toggle-btn\").onclick = async () => {\n      try {\n        const endpoint = lastPauseState === \"RUNNING\" ? \"/api/pause\" : \"/api/resume\";\n        await fetch(endpoint, { method: \"POST\" });\n        await fetchStatus();\n      } catch (error) {\n        showError(\"Toggle failed: \" + error.message);\n      }\n    };\n\n    document.getElementById(\"modal-close\").onclick = closeModal;\n    document.getElementById(\"cancel-button\").onclick = closeModal;\n    document.getElementById(\"save-button\").onclick = saveModal;\n\n    document.addEventListener(\"keydown\", (event) => {\n      if (event.key === \"Escape\") {\n        closeModal();\n        return;\n      }\n      if ((event.ctrlKey || event.metaKey) && event.key === \"Enter\") {\n        saveModal();\n      }\n    });\n\n    document.getElementById(\"modal-overlay\").addEventListener(\"click\", (event) => {\n      if (event.target === document.getElementById(\"modal-overlay\")) {\n        closeModal();\n      }\n    });\n\n    renderBoardSkeleton();\n    fetchStatus();\n    fetchPrompts();\n    setInterval(fetchStatus, 2000);\n    setInterval(fetchPrompts, 5000);\n  </script>\n</body>\n</html>\n";

package/esm/scripts/run-codex-prompts/server/runCoderHttpServer.d.ts

@@ -0,0 +1,35 @@
+import type { number_port } from '../../../src/types/number_positive';
+import type { CoderRunUiState } from '../ui/CoderRunUiState';
+/**
+ * Handle returned by the running coder HTTP server.
+ *
+ * @private internal type of `ptbk coder server`
+ */
+export type CoderHttpServerHandle = {
+    close: () => void;
+};
+/**
+ * Options for the coder HTTP server.
+ *
+ * @private internal type of `ptbk coder server`
+ */
+export type StartCoderHttpServerOptions = {
+    readonly port: number_port;
+    readonly minimumPriority: number;
+    readonly serverUrl: string;
+    readonly uiState?: CoderRunUiState;
+};
+/**
+ * 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`
+ */
+export declare function startCoderHttpServer(options: StartCoderHttpServerOptions): CoderHttpServerHandle;

package/esm/scripts/run-codex-prompts/server/updatePromptSection.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 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`
+ */
+export declare function updatePromptSection(filePath: string, sectionIndex: number, newContent: string): Promise<boolean>;

package/esm/scripts/run-codex-prompts/ui/CoderRunUiState.d.ts

@@ -21,6 +21,7 @@ export type CoderRunConfig = {
     readonly modelName?: string;
     readonly thinkingLevel?: string;
     readonly context?: string;
+    readonly serverUrl?: string;
     readonly priority: number;
     readonly testCommand?: string;
 };
@@ -57,6 +58,7 @@ export declare class CoderRunUiState extends EventEmitter {
     private stats;
     private readonly timer;
     private initialDone;
+    private cachedAveragePromptDurationMs;
     constructor(startTime: moment.Moment);
     /**
      * Pauses the elapsed timer (e.g. while waiting for user input or paused state).
@@ -74,6 +76,12 @@ export declare class CoderRunUiState extends EventEmitter {
      * Feeds new prompt statistics from the main loop so the progress bar updates.
      */
     updateProgress(stats: PromptStats): void;
+    /**
+     * Sets the cached average prompt duration (in milliseconds) loaded from the temp-folder estimate cache.
+     *
+     * Used to project completion estimates before the first prompt of the current session finishes.
+     */
+    setCachedAveragePromptDurationMs(cachedAveragePromptDurationMs: number | undefined): void;
     /**
      * Computes a progress snapshot on demand so elapsed time ticks with periodic re-renders.
      */