@promptbook/cli 0.113.0-8 → 0.114.0-0

package/umd/scripts/run-agent-messages/main/loadAgentMessageQueueSnapshot.d.ts

@@ -16,7 +16,7 @@ export declare function loadAgentMessageQueueSnapshot(projectPath: string): Prom
 export declare function createAgentQueueProgressSnapshot(queueSnapshot: AgentMessageQueueSnapshot): {
     done: number;
     forAgent: number;
-    belowMinimumPriority: number;
+    outsidePriorityRange: number;
     toBeWritten: number;
 };
 /**

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

@@ -0,0 +1,27 @@
+import type { AgentRunOptions } from '../../AgentRunOptions';
+import type { LocalAgentRunnerProjectSummary } from './LocalAgentRunnerProjectSummary';
+import type { MultiAgentAutoPullResult } from './MultiAgentAutoPullResult';
+import type { MultipleAgentRunUiPresenter } from './MultipleAgentRunUiPresenter';
+/**
+ * Owns periodic auto-pull state for watched local repositories.
+ *
+ * @private class of `runMultipleAgentMessages`
+ */
+export declare class MultipleAgentAutoPuller {
+    private readonly autoPullTimestampsByProjectPath;
+    /**
+     * Pulls latest changes for watched child repositories when their idle auto-pull interval elapsed.
+     */
+    pullIfNeeded(options: {
+        readonly rootPath: string;
+        readonly runOptions: AgentRunOptions;
+        readonly uiPresenter: MultipleAgentRunUiPresenter;
+        readonly projectSummaries: ReadonlyArray<LocalAgentRunnerProjectSummary>;
+        readonly ignoredAgentCount: number;
+    }): Promise<MultiAgentAutoPullResult>;
+    /**
+     * Records an auto-pull timestamp observed while a child runner processed one message.
+     */
+    recordAutoPullTimestamp(projectPath: string, autoPullTimestamp: number): void;
+    private pruneTimestampsForCurrentProjects;
+}

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

@@ -0,0 +1,26 @@
+import type { AgentRunOptions } from '../../AgentRunOptions';
+import type { AgentIgnoreMatcher } from '../agentIgnorePatterns';
+import type { MultipleAgentRunUiPresenter } from './MultipleAgentRunUiPresenter';
+/**
+ * Owns periodic GitHub repository synchronization state for `runMultipleAgentMessages`.
+ *
+ * @private class of `runMultipleAgentMessages`
+ */
+export declare class MultipleAgentGithubSynchronizer {
+    private synchronizationTimestamp;
+    private ignoredRepositoryCount;
+    /**
+     * Number of remote repositories ignored during the last synchronization round.
+     */
+    get ignoredAgentCount(): number;
+    /**
+     * Synchronizes missing local repositories from GitHub when the owner configuration is available.
+     */
+    synchronizeIfNeeded(options: {
+        readonly rootPath: string;
+        readonly runOptions: AgentRunOptions;
+        readonly ignoreMatcher: AgentIgnoreMatcher;
+        readonly uiPresenter: MultipleAgentRunUiPresenter;
+        readonly lastObservedProjectCount: number;
+    }): Promise<void>;
+}

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

@@ -0,0 +1,66 @@
+import type { AgentRunOptions } from '../../AgentRunOptions';
+import { type CoderRunUiHandle } from '../../../run-codex-prompts/ui/renderCoderRunUi';
+import type { AgentTickUiPresentation } from '../tickAgentMessages';
+import type { LocalAgentRunnerProjectSummary } from './LocalAgentRunnerProjectSummary';
+/**
+ * Owns all rich UI state projection for `runMultipleAgentMessages`.
+ *
+ * @private class of `runMultipleAgentMessages`
+ */
+export declare class MultipleAgentRunUiPresenter {
+    private readonly runOptions;
+    private readonly rootPath;
+    private readonly handle;
+    private constructor();
+    /**
+     * Creates the shared multi-agent rich UI when the terminal supports it.
+     */
+    static create(runOptions: AgentRunOptions, rootPath: string): MultipleAgentRunUiPresenter;
+    /**
+     * Rich terminal UI handle, when the current process can render one.
+     */
+    get uiHandle(): CoderRunUiHandle | undefined;
+    /**
+     * Updates the shared UI while GitHub repository synchronization is running.
+     */
+    updateForGithubSynchronization(lastObservedProjectCount: number): void;
+    /**
+     * Updates the shared UI while watched child repositories are being pulled.
+     */
+    updateForAutoPull(projectSummaries: ReadonlyArray<LocalAgentRunnerProjectSummary>, ignoredAgentCount: number, projectSummariesToPull: ReadonlyArray<LocalAgentRunnerProjectSummary>): void;
+    /**
+     * Updates the shared UI to the idle multi-agent watch state.
+     */
+    updateForWatching(projectSummaries: ReadonlyArray<LocalAgentRunnerProjectSummary>, ignoredAgentCount: number): void;
+    /**
+     * Updates the shared UI while one or more child repositories are answering queued messages.
+     */
+    updateForAnswering(options: {
+        readonly projectSummaries: ReadonlyArray<LocalAgentRunnerProjectSummary>;
+        readonly answeringProjectPaths: ReadonlySet<string>;
+        readonly ignoredAgentCount: number;
+        readonly activeMessageCount: number;
+    }): void;
+    /**
+     * Builds the multi-agent presentation passed into one active queued-message tick.
+     */
+    buildTickPresentation(options: {
+        readonly projectSummaries: ReadonlyArray<LocalAgentRunnerProjectSummary>;
+        readonly answeringProjectPaths: ReadonlySet<string>;
+        readonly ignoredAgentCount: number;
+    }): AgentTickUiPresentation;
+    private setConfig;
+    private buildScriptPaths;
+    private createQueueProgressSnapshot;
+    private createCompletedQueueProgressSnapshot;
+    private buildStatusLines;
+    private buildStatusTableRows;
+    private formatCurrentAgentMessage;
+    private buildUserMessageLines;
+    private buildMessagePreviewSections;
+    private buildAnsweringAgentMessageLines;
+    private buildAnsweringDetailLines;
+    private buildWatchingDetailLines;
+    private buildAutoPullDetailLines;
+    private formatAgentCount;
+}

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

@@ -0,0 +1,67 @@
+import type { AgentRunOptions } from '../../AgentRunOptions';
+import type { AgentMessageFailureTracker } from '../AgentMessageFailureTracker';
+import type { LocalAgentRunnerProjectSummary } from './LocalAgentRunnerProjectSummary';
+import type { LocalAgentRunnerWorkItem } from './LocalAgentRunnerWorkItem';
+import type { MultiAgentAutoPullResult } from './MultiAgentAutoPullResult';
+import type { MultipleAgentAutoPuller } from './MultipleAgentAutoPuller';
+import type { MultipleAgentRunUiPresenter } from './MultipleAgentRunUiPresenter';
+/**
+ * Task scheduler dependencies that are stable for one multi-agent watch session.
+ *
+ * @private type of `runMultipleAgentMessages`
+ */
+export type RunMultipleAgentMessageTaskSchedulerOptions = {
+    readonly runOptions: AgentRunOptions;
+    readonly messageFailureTracker: AgentMessageFailureTracker;
+    readonly autoPuller: MultipleAgentAutoPuller;
+    readonly uiPresenter: MultipleAgentRunUiPresenter;
+    readonly watchErrorLogDirectoryPath: string;
+};
+/**
+ * Owns active queued-message task selection, execution, and settling for `runMultipleAgentMessages`.
+ *
+ * @private class of `runMultipleAgentMessages`
+ */
+export declare class RunMultipleAgentMessageTaskScheduler {
+    private readonly options;
+    private readonly activeMessageTasksByKey;
+    private readonly isParallelMessageLimitConfigured;
+    private readonly maxParallelMessageCount;
+    constructor(options: RunMultipleAgentMessageTaskSchedulerOptions);
+    /**
+     * Number of currently running harness tasks.
+     */
+    get activeMessageCount(): number;
+    /**
+     * Selects the next queued messages that can be started without exceeding active harness capacity.
+     */
+    selectQueuedWorkItems(projectSummaries: ReadonlyArray<LocalAgentRunnerProjectSummary>): Array<LocalAgentRunnerWorkItem>;
+    /**
+     * Builds the set of project paths currently represented by active or newly scheduled harness tasks.
+     */
+    createAnsweringProjectPaths(queuedWorkItems: ReadonlyArray<LocalAgentRunnerWorkItem>): Set<string>;
+    /**
+     * Starts selected queued-message harness tasks and records them until they settle.
+     */
+    startQueuedWorkItems(options: {
+        readonly queuedWorkItems: ReadonlyArray<LocalAgentRunnerWorkItem>;
+        readonly projectSummaries: ReadonlyArray<LocalAgentRunnerProjectSummary>;
+        readonly answeringProjectPaths: ReadonlySet<string>;
+        readonly ignoredAgentCount: number;
+        readonly autoPullResult: MultiAgentAutoPullResult;
+    }): void;
+    /**
+     * Waits for either one active task to finish or the next queue polling interval.
+     */
+    waitForNextTurn(queuePollIntervalMs: number): Promise<void>;
+    /**
+     * Preserves previous shutdown behavior by letting active harness tasks finish before returning.
+     */
+    waitForActiveTasksToSettle(): Promise<void>;
+    private startQueuedWorkItem;
+    private runQueuedWorkItem;
+    private selectFirstInactiveQueuedWorkItem;
+    private createTaskKey;
+    private createRunOptionsForQueuedProjectTick;
+    private normalizeMaxParallelMessageCount;
+}

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

@@ -0,0 +1,6 @@
+/**
+ * Formats one child project path for stable console and UI output.
+ *
+ * @private function of `runMultipleAgentMessages`
+ */
+export declare function formatProjectPath(rootPath: string, projectPath: string): string;

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

@@ -0,0 +1,11 @@
+import { type AgentIgnoreMatcher } from '../agentIgnorePatterns';
+import type { LocalAgentRunnerProjectSummariesResult } from './LocalAgentRunnerProjectSummary';
+/**
+ * Loads current direct-child repository summaries used by the shared dashboard and queue routing.
+ *
+ * @private function of `runMultipleAgentMessages`
+ */
+export declare function loadLocalAgentRunnerProjectSummaries(rootPath: string, options: {
+    readonly includeMessagePreviews: boolean;
+    readonly ignoreMatcher: AgentIgnoreMatcher;
+}): Promise<LocalAgentRunnerProjectSummariesResult>;

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

@@ -0,0 +1,6 @@
+/**
+ * Waits for the next idle poll interval in multi-agent watch mode.
+ *
+ * @private function of `runMultipleAgentMessages`
+ */
+export declare function wait(delayMs: number): Promise<void>;

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

@@ -1,4 +1,4 @@
-import { type CoderRunUiHandle } from '../../run-codex-prompts/ui/renderCoderRunUi';
+import type { CoderRunUiHandle } from '../../run-codex-prompts/ui/renderCoderRunUi';
 import type { AgentRunOptions } from '../AgentRunOptions';
 /**
  * Optional integrations for callers that supervise the multi-agent watcher as one service.

package/umd/scripts/run-agent-messages/messages/buildAgentMessagePrompt.d.ts

@@ -1,4 +1,9 @@
+import { type AgentProjectsPromptSectionOptions } from './buildAgentProjectsPromptSection';
+/**
+ * Options adjusting the generated agent message prompt.
+ */
+export type BuildAgentMessagePromptOptions = AgentProjectsPromptSectionOptions;
 /**
  * Builds the prompt sent to the selected coding runner for one queued user-thread book.
  */
-export declare function buildAgentMessagePrompt(messageRelativePath: string, agentSystemMessage: string): string;
+export declare function buildAgentMessagePrompt(messageRelativePath: string, agentSystemMessage: string, options?: BuildAgentMessagePromptOptions): string;

package/umd/scripts/run-agent-messages/messages/buildAgentProjectsPromptSection.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Internal runtime API details available to Agents Server-managed local agents.
+ */
+export type AgentProjectRuntimePromptApi = {
+    /**
+     * Permanent id of the agent currently answering the message.
+     */
+    readonly agentPermanentId: string;
+    /**
+     * Environment variable containing the Agents Server origin.
+     */
+    readonly serverUrlEnvironmentVariableName: string;
+    /**
+     * Environment variable containing the internal worker token.
+     */
+    readonly tokenEnvironmentVariableName: string;
+};
+/**
+ * Options of the projects prompt section shared by every coding harness.
+ */
+export type AgentProjectsPromptSectionOptions = {
+    /**
+     * URL path of the agent projects file endpoint, for example `/agents/<agentId>/projects`.
+     *
+     * When known, the section teaches the agent how to link project files into the chat.
+     */
+    readonly projectsUrlPath?: string;
+    /**
+     * Internal runtime API details, when the agent is managed by Agents Server.
+     */
+    readonly projectRuntimeApi?: AgentProjectRuntimePromptApi;
+};
+/**
+ * Builds the `## Projects` prompt section explaining the agent-owned projects convention.
+ *
+ * The section is part of the prompt of every harness, so each coding agent knows it has its
+ * own isolated project folders it fully controls and how to reference them in the chat.
+ */
+export declare function buildAgentProjectsPromptSection(options?: AgentProjectsPromptSectionOptions): string;

package/umd/scripts/run-agent-messages/messages/resolveAgentProjectRuntimePromptApi.d.ts

@@ -0,0 +1,8 @@
+import type { AgentProjectRuntimePromptApi } from './buildAgentProjectsPromptSection';
+/**
+ * Resolves project-runtime prompt API details for one local agent runner folder.
+ *
+ * @param projectPath - Absolute path of the current agent runner folder.
+ * @returns Runtime prompt API details or `undefined` outside Agents Server-managed runs.
+ */
+export declare function resolveAgentProjectRuntimePromptApi(projectPath: string): AgentProjectRuntimePromptApi | undefined;

package/umd/scripts/run-agent-messages/messages/resolveAgentProjectsUrlPath.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Resolves the Agents Server projects URL path for one local agent runner folder.
+ *
+ * Agent runner folders managed by the Agents Server follow the `agent-<agentId>` naming
+ * convention, so the stable agent id can be derived from the folder name. For ad-hoc
+ * workspaces (for example `ptbk agent exec` sessions) no URL path is resolved and the
+ * prompt falls back to generic project references.
+ *
+ * @param projectPath - Absolute path of the agent runner folder.
+ * @returns Projects URL path like `/agents/<agentId>/projects`, or `undefined` when unknown.
+ */
+export declare function resolveAgentProjectsUrlPath(projectPath: string): string | undefined;

package/umd/scripts/run-agent-messages/messages/writeAgentMessageRunReport.d.ts

@@ -0,0 +1,22 @@
+import { type AgentMessageRunReport } from '../../../src/book-3.0/AgentMessageRunReport';
+/**
+ * Result of persisting one run report next to an answered message book.
+ */
+export type WrittenAgentMessageRunReport = {
+    readonly absolutePath: string;
+    readonly relativePath: string;
+};
+/**
+ * Writes the run report sidecar next to one answered message book.
+ *
+ * The report is best-effort telemetry — the answer itself is already persisted in the
+ * finished message book, so a failed report write only logs a warning instead of
+ * failing the whole answered message.
+ *
+ * @returns The written report paths, or `null` when the write failed.
+ */
+export declare function writeAgentMessageRunReport(options: {
+    readonly finishedMessageAbsolutePath: string;
+    readonly finishedMessageRelativePath: string;
+    readonly report: AgentMessageRunReport;
+}): Promise<WrittenAgentMessageRunReport | null>;

package/umd/scripts/run-agent-messages/ui/buildAgentRunUiFrame.d.ts

@@ -1,5 +1,10 @@
 import type { BuildCoderRunUiFrameOptions } from '../../run-codex-prompts/ui/buildCoderRunUiFrame';
+/**
+ * Snapshot consumed by the pure agent-run frame builder.
+ */
+type BuildAgentRunUiFrameOptions = Omit<BuildCoderRunUiFrameOptions, 'agentVisual' | 'agentVisualLines' | 'isEndAfterCurrentPromptRequested'>;
 /**
  * Builds the complete boxed terminal frame for the rich `ptbk agent-folder run` UI.
  */
-export declare function buildAgentRunUiFrame(options: BuildCoderRunUiFrameOptions): string[];
+export declare function buildAgentRunUiFrame(options: BuildAgentRunUiFrameOptions): string[];
+export {};

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

@@ -24,4 +24,4 @@ export type CoderRunProgressSnapshot = {
  * 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, cachedAveragePromptDurationMs?: number): CoderRunProgressSnapshot;
+export declare function buildCoderRunProgressSnapshot(stats: PromptStats, elapsedDuration: moment.Duration, initialDone: number, cachedAveragePromptDurationMs?: number, runLimit?: number): CoderRunProgressSnapshot;

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

@@ -1,10 +1,12 @@
 import moment from 'moment';
+import { type PriorityFilter } from '../prompts/priorityFilter';
 import type { PromptStats } from '../prompts/types/PromptStats';
 /**
  * Compact CLI progress display that stays pinned at the top of the terminal.
  */
 export declare class CliProgressDisplay {
-    private readonly minimumPriority;
+    private readonly priorityFilter;
+    private readonly runLimit?;
     private stats;
     /**
      * Initial number of completed prompts when the session started.
@@ -19,7 +21,7 @@ export declare class CliProgressDisplay {
     /**
      * Creates a new display that uses the provided start time when computing estimates.
      */
-    constructor(startTime: moment.Moment, minimumPriority: number);
+    constructor(startTime: moment.Moment, priorityFilter?: PriorityFilter, runLimit?: number | undefined);
     /**
      * Sets the cached average prompt duration (in milliseconds) loaded from the temp-folder estimate cache.
      *

package/umd/scripts/run-codex-prompts/common/formatUnknownErrorMessage.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Formats one unknown error-like value into its readable message without the stack trace.
+ *
+ * Use this instead of `formatUnknownErrorDetails` whenever the text is shown to the user, for example
+ * inside a branded error, where the stack of the wrapped error would only bury the actual cause.
+ */
+export declare function formatUnknownErrorMessage(error: unknown): string;

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

@@ -21,6 +21,7 @@ export declare function describeCoderRunWait(waitKind: CoderRunWaitKind, remaini
  */
 export declare function sleepWithCountdown(options: {
     durationMs: number;
+    deadlineTimeMs?: number;
     waitKind: CoderRunWaitKind;
     isRichUiEnabled: boolean;
     uiHandle?: CoderRunUiHandle;

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

@@ -6,12 +6,60 @@ export type CoderRunPauseState = 'RUNNING' | 'PAUSING' | 'PAUSED';
  * Result of toggling the pause hotkey state.
  */
 export type CoderRunPauseToggleResult = 'REQUESTED_PAUSE' | 'CANCELLED_PAUSE' | 'RESUMED';
+/**
+ * Result of requesting a timed wait skip.
+ */
+export type CoderRunSkipCurrentWaitResult = 'REQUESTED_SKIP' | 'NO_ACTIVE_WAIT';
+/**
+ * Result of toggling the dynamic end-after-current-prompt state.
+ */
+export type CoderRunEndAfterCurrentPromptToggleResult = 'REQUESTED_END' | 'CANCELLED_END';
+/**
+ * Token that identifies one active timed wait which can be skipped by the user.
+ */
+export type CoderRunSkippableWaitToken = symbol;
 /**
  * Applies the same three-state toggle used by the `P` hotkey.
  */
 export declare function togglePauseState(): CoderRunPauseToggleResult;
 /**
- * Listens for the "p" key to pause and resume.
+ * Applies the two-state toggle used by the `X` hotkey.
+ */
+export declare function toggleEndAfterCurrentPromptState(): CoderRunEndAfterCurrentPromptToggleResult;
+/**
+ * Returns whether the dynamic end-after-current-prompt control is active.
+ */
+export declare function getEndAfterCurrentPromptState(): boolean;
+/**
+ * Starts one timed wait which can be skipped by the `S` hotkey.
+ */
+export declare function beginSkippableWait(): CoderRunSkippableWaitToken;
+/**
+ * Finishes one timed wait and clears any skip request that belonged to it.
+ */
+export declare function finishSkippableWait(waitToken: CoderRunSkippableWaitToken): void;
+/**
+ * Requests that the currently active timed wait ends immediately.
+ */
+export declare function requestSkipCurrentWait(): CoderRunSkipCurrentWaitResult;
+/**
+ * Returns whether one timed wait should end early.
+ */
+export declare function shouldSkipCurrentWait(waitToken: CoderRunSkippableWaitToken): boolean;
+/**
+ * Waits for either a timeout or an `S` hotkey skip request.
+ */
+export declare function waitForSkippableMilliseconds(waitToken: CoderRunSkippableWaitToken, durationMs: number): Promise<void>;
+/**
+ * Restores all shared terminal controls to their default state.
+ */
+export declare function resetCoderRunControls(): void;
+/**
+ * Listens for the terminal control keys.
+ */
+export declare function listenForCoderRunControls(): void;
+/**
+ * Backwards-compatible alias for the shared terminal controls listener.
  */
 export declare function listenForPause(): void;
 /**

package/umd/scripts/run-codex-prompts/common/waitUntilWorldTimeDeadline.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Callback called before each short sleep while waiting for a wall-clock deadline.
+ */
+export type WorldTimeDeadlineTick = (remainingDurationMs: number) => void | Promise<void>;
+/**
+ * Callback used to perform one wait segment.
+ */
+export type WorldTimeDeadlineWait = (durationMs: number) => Promise<void>;
+/**
+ * Callback that can stop the deadline wait before the wall-clock deadline is reached.
+ */
+export type WorldTimeDeadlineStopCheck = () => boolean;
+/**
+ * Waits until one wall-clock deadline has passed.
+ *
+ * The remaining time is recalculated from `Date.now()` after every poll and after every tick callback.
+ * This makes waits elapse while the process is paused at a checkpoint or the computer is asleep.
+ *
+ * @private internal utility of `ptbk coder` wait handling
+ */
+export declare function waitUntilWorldTimeDeadline(options: {
+    readonly deadlineTimeMs: number;
+    readonly pollIntervalMs: number;
+    readonly onTick?: WorldTimeDeadlineTick;
+    readonly shouldStopWaiting?: WorldTimeDeadlineStopCheck;
+    readonly waitForMilliseconds?: WorldTimeDeadlineWait;
+}): Promise<void>;

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

@@ -2,7 +2,8 @@
  * 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, `options.onlyPaths` can restrict the commit pathspec,
- * and `options.excludePaths` can keep temporary artifacts out of the created commit.
+ * `options.excludePaths` can keep temporary artifacts out of the created commit and
+ * `options.isEmptyCommitAllowed` keeps a round without any file change from failing.
  */
 export declare function commitChanges(message: string, options?: {
     autoPush?: boolean;
@@ -10,4 +11,5 @@ export declare function commitChanges(message: string, options?: {
     onlyPaths?: ReadonlyArray<string>;
     excludePaths?: ReadonlyArray<string>;
     projectPath?: string;
+    isEmptyCommitAllowed?: boolean;
 }): Promise<void>;

package/umd/scripts/run-codex-prompts/git/gitBranchContext.d.ts

@@ -6,6 +6,10 @@ export declare function hasUpstreamBranch(projectPath: string, env?: Record<stri
  * Reads the current local branch name.
  */
 export declare function readCurrentBranchName(projectPath: string, env?: Record<string, string>): Promise<string>;
+/**
+ * Checks whether one local branch already exists in the repository.
+ */
+export declare function hasLocalBranch(branchName: string, projectPath: string, env?: Record<string, string>): Promise<boolean>;
 /**
  * Reads optional git config value; returns undefined when the key is missing.
  */

package/umd/scripts/run-codex-prompts/git/gitLongPathsSupport.d.ts

@@ -0,0 +1,17 @@
+import type { $side_effect } from '../../../src/utils/organization/$side_effect';
+/**
+ * Builds the environment variables which add `core.longpaths=true` to every Git process started with them.
+ *
+ * Git configuration passed through `GIT_CONFIG_COUNT` is inherited by child processes, so one single
+ * environment covers the Git commands of the coder, of the coding agent and of the verification command alike.
+ *
+ * Returns an empty record when the given environment already configures `core.longpaths`, which keeps an
+ * explicit user setting untouched and keeps repeated calls from stacking duplicate entries.
+ */
+export declare function buildGitLongPathsEnvironmentVariables(baseEnvironment: Readonly<Record<string, string | undefined>>): Record<string, string>;
+/**
+ * Enables Git long path support for every process started from the current one.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it mutates `process.env`
+ */
+export declare function $enableGitLongPathsSupport(): $side_effect;

package/umd/scripts/run-codex-prompts/isolation/coderIsolationCheckoutFailureReport.d.ts

@@ -0,0 +1,9 @@
+import { EnvironmentMismatchError } from '../../../src/errors/EnvironmentMismatchError';
+import type { CoderIsolationWorktree } from './CoderIsolationWorktree';
+/**
+ * Builds the branded error describing why one isolated worktree could not be checked out.
+ *
+ * A failed checkout leaves nothing behind that could be inspected, so the raw git output is condensed
+ * down to the lines which name the actual reason and is paired with hints resolving it.
+ */
+export declare function buildCoderIsolationCheckoutFailureError(worktree: CoderIsolationWorktree, failureDetails: string): EnvironmentMismatchError;

package/umd/scripts/run-codex-prompts/isolation/coderIsolationMergeFailureReport.d.ts

@@ -0,0 +1,17 @@
+import { ConflictError } from '../../../src/errors/ConflictError';
+import type { CoderIsolationWorktree } from './CoderIsolationWorktree';
+/**
+ * Builds the single-line note appended to the prompt status line of a task which could not be merged.
+ *
+ * Status lines must stay on one line, so the full recovery instructions live in the commit message
+ * and in the error log next to the prompt file.
+ */
+export declare function buildCoderIsolationMergeFailureStatusNote(worktree: CoderIsolationWorktree): string;
+/**
+ * Builds the commit message of the commit which records a failed isolation merge in the original project.
+ */
+export declare function buildCoderIsolationMergeFailureCommitMessage(worktree: CoderIsolationWorktree): string;
+/**
+ * Builds the branded error describing one failed isolation merge, written into the prompt error log.
+ */
+export declare function buildCoderIsolationMergeFailureError(worktree: CoderIsolationWorktree, failureDetails: string): ConflictError;

package/umd/scripts/run-codex-prompts/isolation/coderIsolationNaming.d.ts

@@ -0,0 +1,26 @@
+import type { PromptFile } from '../prompts/types/PromptFile';
+import type { PromptSection } from '../prompts/types/PromptSection';
+/**
+ * Temporary subdirectory holding every worktree created by `ptbk coder run --isolate`.
+ */
+export declare const CODER_ISOLATION_WORKTREES_DIRECTORY_NAME = "coder-isolation-worktrees";
+/**
+ * Prefix of every git branch created by `ptbk coder run --isolate`.
+ */
+export declare const CODER_ISOLATION_BRANCH_PREFIX = "ptbk-coder-isolation";
+/**
+ * Builds the isolation task name of one prompt section, for example `2026-07-0700-ptbk-coder-timing`.
+ */
+export declare function buildCoderIsolationTaskName(file: PromptFile, section: PromptSection): string;
+/**
+ * Builds the git branch name used for one isolated task.
+ */
+export declare function buildCoderIsolationBranchName(taskName: string): string;
+/**
+ * Builds the absolute worktree path used for one isolated task.
+ */
+export declare function buildCoderIsolationWorktreePath(projectPath: string, taskName: string): string;
+/**
+ * Builds the project-relative worktree path of one isolated task, used in human-facing messages.
+ */
+export declare function buildCoderIsolationWorktreeDisplayPath(taskName: string): string;

package/umd/scripts/run-codex-prompts/isolation/copyCoderIsolationEnvironment.d.ts

@@ -0,0 +1,8 @@
+import type { CoderIsolationWorktree } from './CoderIsolationWorktree';
+/**
+ * Gives the isolated worktree its own copy of the project environment.
+ *
+ * The copy is intentionally a snapshot: changing the environment inside the worktree never leaks
+ * back into the project the coder was started from.
+ */
+export declare function copyCoderIsolationEnvironment(worktree: CoderIsolationWorktree): Promise<void>;

package/umd/scripts/run-codex-prompts/isolation/createCoderIsolationWorktree.d.ts

@@ -0,0 +1,22 @@
+import type { CoderIsolationWorktree } from './CoderIsolationWorktree';
+/**
+ * Options for creating one isolation worktree.
+ */
+type CreateCoderIsolationWorktreeOptions = {
+    /**
+     * Absolute path of the project the coder was started from.
+     */
+    readonly projectPath: string;
+    /**
+     * Name of the isolated task, for example `2026-07-0700-ptbk-coder-timing`.
+     */
+    readonly taskName: string;
+};
+/**
+ * Creates one temporary git worktree with its own branch and its own copy of the project environment.
+ *
+ * Leftovers of an earlier run of the same task are removed first so that a repeated task never fails
+ * on an already existing worktree directory or branch.
+ */
+export declare function createCoderIsolationWorktree(options: CreateCoderIsolationWorktreeOptions): Promise<CoderIsolationWorktree>;
+export {};

package/umd/scripts/run-codex-prompts/isolation/markPromptIsolationMergeFailed.d.ts

@@ -0,0 +1,10 @@
+import type { PromptFile } from '../prompts/types/PromptFile';
+import type { PromptSection } from '../prompts/types/PromptSection';
+import type { CoderIsolationWorktree } from './CoderIsolationWorktree';
+/**
+ * Rewrites the status of one prompt whose isolated implementation could not be merged back.
+ *
+ * The prompt has already been marked as done by the isolated round, so the recorded runner metadata is
+ * kept and only the status box turns from `[x]` into `[!]`, followed by the manual merge instructions.
+ */
+export declare function markPromptIsolationMergeFailed(file: PromptFile, section: PromptSection, worktree: CoderIsolationWorktree): void;