@promptbook/cli 0.114.0-5 → 0.114.0-50

package/umd/scripts/find-fresh-emoji-tags/find-fresh-emoji-tags.d.ts

@@ -3,4 +3,4 @@
  *
  * @public exported from `@promptbook/cli`
  */
-export declare function findFreshEmojiTag(): Promise<void>;
+export declare function findFreshEmojiTag(projectPath?: string): Promise<void>;

package/umd/scripts/find-refactor-candidates/find-refactor-candidates.d.ts

@@ -11,6 +11,8 @@ export declare function findRefactorCandidates(options?: FindRefactorCandidatesO
  * @public exported from `@promptbook/cli`
  */
 export type FindRefactorCandidatesOptions = {
+    /** Explicit project directory retained separately from any enclosing repository. */
+    readonly projectPath?: string;
     /**
      * Aggressiveness level used to score candidate files.
      */

package/umd/scripts/find-refactor-candidates/resolveRefactorCandidateProject.d.ts

@@ -20,4 +20,6 @@ export type ResolvedRefactorCandidateProject = {
  *
  * @private function of findRefactorCandidates
  */
-export declare function resolveRefactorCandidateProject(startDir: string): Promise<ResolvedRefactorCandidateProject>;
+export declare function resolveRefactorCandidateProject(startDir: string, options?: {
+    readonly isPreservingProjectDirectory?: boolean;
+}): Promise<ResolvedRefactorCandidateProject>;

package/umd/scripts/run-agent-messages/git/commitAgentProjectChanges.d.ts

@@ -0,0 +1,15 @@
+import type { AgentMessageProjectChange } from '../../../src/utils/agent-message-runtime/AgentMessageProjectChange';
+/**
+ * Commits everything one answered message changed inside one agent project.
+ *
+ * The project is turned into a git repository first when it is not one yet, so the work of every
+ * answer stays recoverable and reviewable as a normal commit history.
+ *
+ * @param options - Project identity and the commit message describing the answered message.
+ * @returns What was committed, or `null` when the project changed nothing or cannot be committed.
+ */
+export declare function commitAgentProjectChanges(options: {
+    readonly projectPath: string;
+    readonly projectName: string;
+    readonly commitMessage: string;
+}): Promise<AgentMessageProjectChange | null>;

package/umd/scripts/run-agent-messages/git/commitAnsweredMessageProjectChanges.d.ts

@@ -0,0 +1,24 @@
+import type { AgentMessageProjectChange } from '../../../src/utils/agent-message-runtime/AgentMessageProjectChange';
+/**
+ * Commits what one answered message changed in every project of one agent.
+ *
+ * Every project of an agent is its own git repository, so each answer which modified one becomes a
+ * commit there. The projects are committed one after another because they share the git executable
+ * and because an agent works with a handful of projects at most.
+ *
+ * Committing is best-effort bookkeeping around an answer the agent already produced: a project
+ * whose commit fails is reported to the console and skipped instead of failing the message.
+ *
+ * @param options - Agent folder and the commit message describing the answered message.
+ * @returns What was committed, one entry per project the message really changed.
+ */
+export declare function commitAnsweredMessageProjectChanges(options: {
+    /**
+     * Absolute path of the local agent folder owning the projects.
+     */
+    readonly agentFolderPath: string;
+    /**
+     * Commit message shared by every project commit of this message.
+     */
+    readonly commitMessage: string;
+}): Promise<ReadonlyArray<AgentMessageProjectChange>>;

package/umd/scripts/run-agent-messages/git/ensureAgentProjectGitRepository.d.ts

@@ -0,0 +1,20 @@
+/**
+ * How one agent project directory relates to git.
+ *
+ * -   `own-repository` is a project whose own history the runner can commit into.
+ * -   `tracked-elsewhere` is a project belonging to a repository around the agent folder, whose
+ *     history is already kept by whoever owns that repository.
+ * -   `unavailable` is a project which cannot be committed, for example because git is missing.
+ */
+export type AgentProjectGitRepositoryState = 'own-repository' | 'tracked-elsewhere' | 'unavailable';
+/**
+ * Makes sure one agent project is a git repository of its own.
+ *
+ * A project which is already tracked by a repository around the agent folder is deliberately left
+ * alone: initializing a repository inside it would turn it into an embedded repository and break
+ * the history that already covers it.
+ *
+ * @param projectPath - Absolute path of the project directory.
+ * @returns How the project relates to git after this call.
+ */
+export declare function ensureAgentProjectGitRepository(projectPath: string): Promise<AgentProjectGitRepositoryState>;

package/umd/scripts/run-agent-messages/git/readAgentProjectCommitChange.d.ts

@@ -0,0 +1,11 @@
+import type { AgentMessageProjectChange } from '../../../src/utils/agent-message-runtime/AgentMessageProjectChange';
+/**
+ * Describes the latest commit of one agent project repository.
+ *
+ * @param options - Project directory and the project name the description is reported under.
+ * @returns Description of the commit, or `null` when git could not describe it.
+ */
+export declare function readAgentProjectCommitChange(options: {
+    readonly projectPath: string;
+    readonly projectName: string;
+}): Promise<AgentMessageProjectChange | null>;

package/umd/scripts/run-agent-messages/git/runAgentProjectGitCommand.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Result of one git command executed inside one agent project.
+ */
+export type AgentProjectGitCommandResult = {
+    /**
+     * Whether git reported success.
+     */
+    readonly isSuccessful: boolean;
+    /**
+     * Standard output of the command, with the trailing newline removed.
+     */
+    readonly output: string;
+};
+/**
+ * Runs one git command inside one agent project directory.
+ *
+ * Commands are executed without a shell and with an explicit argument list, so a project name or
+ * a file path can never be interpreted as a shell fragment. A failing command is reported through
+ * `isSuccessful` instead of throwing, because git uses the exit code to answer questions such as
+ * "is there anything staged" and because auto-committing a project must never fail an answer the
+ * agent already produced.
+ *
+ * @param options - Project directory and the git arguments to run there.
+ * @returns Outcome of the command.
+ */
+export declare function runAgentProjectGitCommand(options: {
+    readonly projectPath: string;
+    readonly args: ReadonlyArray<string>;
+}): Promise<AgentProjectGitCommandResult>;

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

@@ -0,0 +1,26 @@
+import type { AgentPlannedMessageSnapshot } from '../../../src/book-3.0/AgentPlannedMessagesSidecar';
+/**
+ * Planned-message sidecar information made visible to one coding-harness prompt.
+ */
+export type AgentPlannedMessagesPromptSidecar = {
+    /**
+     * Portable path of the sidecar inside the agent folder.
+     */
+    readonly relativeSidecarPath: string;
+    /**
+     * Planned messages that are already waiting to wake the agent.
+     */
+    readonly currentPlannedMessages: ReadonlyArray<AgentPlannedMessageSnapshot>;
+};
+/**
+ * Builds the planned-message instructions available to an Agents Server-managed coding agent.
+ *
+ * Planned messages always target the agent's singleton goal chat, regardless of the chat in which the
+ * wake-up is planned, and each of them keeps repeating until its schedule is over or it is cancelled.
+ * The sidecar file is the only channel that changes them, so an answer that merely claims a follow-up
+ * was planned changes nothing — and an answer that changes nothing keeps the current plan running.
+ *
+ * @param sidecar - Sidecar prepared by the Agents Server for the answered message.
+ * @returns Prompt section, or an empty string outside Agents Server-managed runs.
+ */
+export declare function buildAgentGoalChatPromptSection(sidecar: AgentPlannedMessagesPromptSidecar | undefined): string;

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

@@ -1,8 +1,19 @@
 import { type AgentProjectsPromptSectionOptions } from './buildAgentProjectsPromptSection';
+import { type AgentPlannedMessagesPromptSidecar } from './buildAgentGoalChatPromptSection';
+import { type AgentTeamPromptWorkspace } from './buildAgentTeamPromptSection';
 /**
  * Options adjusting the generated agent message prompt.
  */
-export type BuildAgentMessagePromptOptions = AgentProjectsPromptSectionOptions;
+export type BuildAgentMessagePromptOptions = AgentProjectsPromptSectionOptions & {
+    /**
+     * Optional local TEAM roster prepared by the Agents Server for this user turn.
+     */
+    teamWorkspace?: AgentTeamPromptWorkspace;
+    /**
+     * Planned-message sidecar prepared by the Agents Server for the agent's singleton goal chat.
+     */
+    plannedMessagesSidecar?: AgentPlannedMessagesPromptSidecar;
+};
 /**
  * Builds the prompt sent to the selected coding runner for one queued user-thread book.
  */

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

@@ -1,20 +1,8 @@
+import type { AgentServerRuntimePromptApi } from './AgentServerRuntimePromptApi';
 /**
  * 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;
-};
+export type AgentProjectRuntimePromptApi = AgentServerRuntimePromptApi;
 /**
  * Options of the projects prompt section shared by every coding harness.
  */

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

@@ -0,0 +1,12 @@
+import { type AgentTeamConversationWorkspaceManifest } from '../../../src/book-3.0/AgentTeamConversationWorkspace';
+/**
+ * TEAM workspace information made visible to one coding-harness prompt.
+ */
+export type AgentTeamPromptWorkspace = {
+    readonly relativeWorkspacePath: string;
+    readonly manifest: AgentTeamConversationWorkspaceManifest;
+};
+/**
+ * Builds the optional single-run TEAM consultation instructions for a coding harness.
+ */
+export declare function buildAgentTeamPromptSection(workspace: AgentTeamPromptWorkspace | undefined): string;

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

@@ -1,9 +1,10 @@
 import type { AgentModelRequirements } from '../../../src/book-2.0/agent-source/AgentModelRequirements';
+import type { CreateAgentModelRequirementsOptions } from '../../../src/book-2.0/agent-source/CreateAgentModelRequirementsOptions';
 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>;
+export declare function createAgentRunnerSystemMessage(agentSource: string_book, options?: CreateAgentModelRequirementsOptions): Promise<string>;
 /**
  * Formats prepared model requirements for a text-only CLI harness prompt.
  */

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

@@ -0,0 +1,16 @@
+import type { AgentMessageFile } from './AgentMessageFile';
+import type { AgentTeamPromptWorkspace } from './buildAgentTeamPromptSection';
+/**
+ * TEAM transcript files retained next to the finished user message.
+ */
+export type FinishedAgentTeamConversationWorkspace = {
+    readonly relativePaths: ReadonlyArray<string>;
+};
+/**
+ * Moves harness-created TEAM conversation transcripts into the finished-message history.
+ */
+export declare function finalizeAgentTeamConversationWorkspace(options: {
+    readonly projectPath: string;
+    readonly queuedMessage: AgentMessageFile;
+    readonly workspace: AgentTeamPromptWorkspace | null;
+}): Promise<FinishedAgentTeamConversationWorkspace | null>;

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

@@ -0,0 +1,7 @@
+/**
+ * Lists the direct project directories of one agent folder.
+ *
+ * @param agentFolderPath - Absolute path of the local agent folder.
+ * @returns Project directory names, or an empty list when the agent has no projects folder.
+ */
+export declare function listAgentProjectDirectoryNames(agentFolderPath: string): Promise<ReadonlyArray<string>>;

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

@@ -0,0 +1,10 @@
+import type { AgentMessageFile } from './AgentMessageFile';
+import type { AgentPlannedMessagesPromptSidecar } from './buildAgentGoalChatPromptSection';
+/**
+ * Loads the planned-message sidecar the Agents Server prepared for one queued message.
+ *
+ * @param projectPath - Absolute path of the current agent runner folder.
+ * @param queuedMessage - Queued message currently being answered.
+ * @returns Sidecar details for the prompt, or `null` outside Agents Server-managed runs.
+ */
+export declare function loadAgentPlannedMessagesSidecar(projectPath: string, queuedMessage: AgentMessageFile): Promise<AgentPlannedMessagesPromptSidecar | null>;

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

@@ -0,0 +1,6 @@
+import type { AgentMessageFile } from './AgentMessageFile';
+import type { AgentTeamPromptWorkspace } from './buildAgentTeamPromptSection';
+/**
+ * Loads the optional TEAM roster snapshot for one queued message.
+ */
+export declare function loadAgentTeamConversationWorkspace(projectPath: string, queuedMessage: AgentMessageFile): Promise<AgentTeamPromptWorkspace | null>;

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

@@ -0,0 +1,29 @@
+import type { AgentMessageTouchedExternalSource } from '../../../src/utils/agent-message-runtime/AgentMessageTouchedExternalSource';
+/**
+ * Everything one answered message worked with, both inside and outside the agent.
+ */
+export type AnsweredMessageTouches = {
+    /**
+     * Directory names of the agent projects the answer viewed or edited.
+     */
+    readonly touchedProjectNames: ReadonlyArray<string>;
+    /**
+     * Sources outside the agent the answer reached.
+     */
+    readonly touchedExternalSources: ReadonlyArray<AgentMessageTouchedExternalSource>;
+};
+/**
+ * Resolves which agent projects and which external sources one answered message touched.
+ *
+ * The runtime log is deleted as soon as the harness run finishes, so this must be called while
+ * the log still exists — the Agents Server later shows everything reported here as chips below
+ * the answer. Reporting touches is best-effort telemetry: an unreadable log or projects folder
+ * simply yields nothing instead of failing the already answered message.
+ *
+ * @param options - Agent folder path and the live runtime log path of the answered message.
+ * @returns Touched projects and external sources, ordered by first appearance in the run.
+ */
+export declare function resolveAnsweredMessageTouches(options: {
+    readonly projectPath: string;
+    readonly runtimeLogPath: string;
+}): Promise<AnsweredMessageTouches>;

package/umd/scripts/run-codex-prompts/checks/CheckBeforeMode.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Modes supported by `ptbk coder run --check-before`.
+ */
+export declare const CHECK_BEFORE_MODE_VALUES: readonly ["no", "yes-and-fail", "yes-and-fix"];
+/**
+ * Behavior requested for the pre-coding check run.
+ */
+export type CheckBeforeMode = (typeof CHECK_BEFORE_MODE_VALUES)[number];
+/**
+ * Default check command used when a pre-coding mode is enabled without an explicit `--check` command.
+ */
+export declare const DEFAULT_CODER_CHECK_COMMAND = "npm run check";
+/**
+ * Resolves the shared command without enabling checks when both command and preflight mode are absent.
+ */
+export declare function resolveCoderCheckCommand(checkCommand?: string, checkBefore?: CheckBeforeMode): string | undefined;
+/**
+ * Checks whether a value is a supported `--check-before` mode.
+ */
+export declare function isCheckBeforeMode(value: string): value is CheckBeforeMode;

package/umd/scripts/run-codex-prompts/checks/CoderCheckExecutionError.d.ts

@@ -0,0 +1,6 @@
+import { NotAllowed } from '../../../src/errors/NotAllowed';
+/** A command which could not execute/finish is different from completed validation reporting a failure. */
+export declare class CoderCheckExecutionError extends NotAllowed {
+    /** Retains the real execution error; this category never requests a paid check repair. */
+    constructor(command: string, details: string);
+}

package/umd/scripts/run-codex-prompts/checks/CoderCheckFailedError.d.ts

@@ -0,0 +1,6 @@
+import { NotAllowed } from '../../../src/errors/NotAllowed';
+/** A real check failure after the bounded feedback policy, which must not start another round of retries. */
+export declare class CoderCheckFailedError extends NotAllowed {
+    /** Creates a check failure with the selected command's diagnostic output. */
+    constructor(message: string);
+}

package/umd/scripts/run-codex-prompts/checks/buildCheckBeforeScriptPath.d.ts

@@ -0,0 +1,2 @@
+/** Names the shared initial check artifact for execution and scoped-commit exclusion. */
+export declare function buildCheckBeforeScriptPath(projectPath: string): string;

package/umd/scripts/run-codex-prompts/checks/checkRepairInstructions.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Shared constraints for initial repair PRDs and post-prompt check feedback.
+ */
+export declare const CHECK_REPAIR_INSTRUCTIONS: string;

package/umd/scripts/run-codex-prompts/checks/createCheckBeforeRepairPrompt.d.ts

@@ -0,0 +1,11 @@
+import type { PromptSelection } from '../prompts/types/PromptSelection';
+/**
+ * Creates one explicitly selected PRD to repair a pre-existing project check failure.
+ */
+export declare function createCheckBeforeRepairPrompt(options: {
+    readonly projectPath: string;
+    readonly checkCommand: string;
+    readonly checkOutput: string;
+    /** Run may return to its queue after this repair; fix must exit after repairing only these failures. */
+    readonly intent?: 'run' | 'fix';
+}): Promise<PromptSelection>;

package/umd/scripts/run-codex-prompts/checks/limitCheckOutput.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Limits check output while keeping the end of the output, where check tools usually print the failure summary.
+ */
+export declare function limitCheckOutput(checkOutput: string): string;

package/umd/scripts/run-codex-prompts/checks/projectCheck.d.ts

@@ -0,0 +1,26 @@
+import { NotAllowed } from '../../../src/errors/NotAllowed';
+/**
+ * Failing setup placeholder used only when initialization finds no usable project validation scripts.
+ */
+export declare const CHECK_SETUP_PLACEHOLDER_COMMAND = "node -e \"console.error('Configure package.json scripts.check with project validation commands before running Coder.'); process.exit(1)\"";
+/**
+ * A missing or unconfigured project check needs project-owner setup, rather than model repair retries.
+ */
+export declare class CoderCheckSetupError extends NotAllowed {
+    /** Creates an actionable project check setup error. */
+    constructor(details: string);
+}
+/**
+ * Detects the generated setup placeholder and the conventional npm unconfigured-test placeholder.
+ */
+export declare function isCheckSetupRequired(command: string): boolean;
+/**
+ * Inspects root project check references before an initial check or repair loop can start.
+ * Flags and shell composition do not bypass setup validation; execution still uses the existing shell runner.
+ */
+export declare function assertProjectCheckIsConfigured(command: string | undefined, projectPath: string): Promise<void>;
+/**
+ * Validates the project-owned check definition without running commands or changing its scope.
+ * Initialization and execution use this same setup diagnostic for missing leaves and recursive callers.
+ */
+export declare function assertProjectCheckScriptsAreConfigured(scripts: Readonly<Record<string, unknown>>, name?: string): void;

package/umd/scripts/run-codex-prompts/checks/projectScriptReferences.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Reads conventional npm/pnpm/yarn script references for configuration inspection.
+ * Commands are still executed verbatim by the existing shell runner; this helper neither parses nor rewrites shells.
+ * Options selecting other workspaces remain opaque so their scripts are not mistaken for root validation.
+ * Inspection stops at the first directory change; quoted examples do not change the inspected workspace.
+ */
+export declare function projectScriptReferences(command: string): string[];

package/umd/scripts/run-codex-prompts/checks/runCheckBefore.d.ts

@@ -0,0 +1,31 @@
+import type { WaitForCoderRunPauseCheckpoint } from '../common/CoderRunPauseCheckpoint';
+import { runPromptCheckCommand } from './runPromptCheckCommand';
+import type { CoderPhasePersistence } from '../git/CoderPhasePersistence';
+/**
+ * Result of the check command executed before coding starts.
+ */
+export type CheckBeforeResult = {
+    /**
+     * Whether the check command completed successfully.
+     */
+    readonly isPassed: boolean;
+    /**
+     * Combined output produced by the check command.
+     */
+    readonly checkOutput: string;
+};
+/**
+ * Runs the configured check command before the first coding prompt.
+ */
+export declare function runCheckBefore(options: {
+    readonly checkCommand: string;
+    readonly projectPath: string;
+    readonly waitForPauseCheckpoint?: WaitForCoderRunPauseCheckpoint;
+    readonly runPromptCheckCommandExecutor?: typeof runPromptCheckCommand;
+    /** Optional cancellation forwarded to the shared command runner. */
+    readonly signal?: AbortSignal;
+    /** Preserve the initial check's successful script under the same artifact policy as repair checks. */
+    readonly preserveLogs?: boolean;
+    /** Shared phase ownership/persistence, independent of check reporting. */
+    readonly persistence?: CoderPhasePersistence;
+}): Promise<CheckBeforeResult>;

package/umd/scripts/run-codex-prompts/checks/runCoderCheck.d.ts

@@ -0,0 +1,17 @@
+import type { CoderPhasePersistence } from '../git/CoderPhasePersistence';
+import type { CoderCheckOutcome } from './CoderCheckOutcome';
+import { runPromptCheckCommand, type RunPromptCheckCommandOptions } from './runPromptCheckCommand';
+/** Typed execution result separate from persistence, usable by initial checks and bounded check feedback. */
+export type CoderCheckResult = {
+    readonly outcome: CoderCheckOutcome;
+};
+/**
+ * Executes one selected command, captures its content/index boundaries and persists its actual transformation.
+ * Persistence errors escape this service and must never be mistaken for check failures or model feedback.
+ */
+export declare function runCoderCheck(options: RunPromptCheckCommandOptions & {
+    readonly phase: 'pre-coding' | 'post-implementation';
+    readonly attempt?: number;
+    readonly persistence?: CoderPhasePersistence;
+    readonly executor?: typeof runPromptCheckCommand;
+}): Promise<CoderCheckResult>;

package/umd/scripts/run-codex-prompts/checks/runCoderCheckRepair.d.ts

@@ -0,0 +1,40 @@
+import type { WorkspaceRepositoryContext } from '../../../src/cli/cli-commands/common/workspaceRepository';
+import type { WaitForCoderRunPauseCheckpoint } from '../common/CoderRunPauseCheckpoint';
+import { type CoderCommitScope } from '../git/coderCommitScope';
+import type { PromptSelection } from '../prompts/types/PromptSelection';
+import type { CheckBeforeMode } from './CheckBeforeMode';
+/** Explicit outcome of a check/repair job, independent of any ordinary prompt queue or terminal. */
+export type CoderCheckRepairResult = {
+    readonly kind: 'skipped' | 'passed-without-repair' | 'repaired-and-verified' | 'checks-failed' | 'setup-error' | 'execution-error' | 'interrupted' | 'persistence-error';
+    readonly isCheckPassed: boolean;
+    readonly repairPrompt?: PromptSelection;
+    readonly error?: unknown;
+};
+/**
+ * Inputs to the shared check/repair phase. The caller owns the workspace mutation lock for its entire lifecycle.
+ * Execution is prepared lazily and receives the exact authored selection, never a scheduler result.
+ */
+export type CoderCheckRepairOptions = {
+    readonly projectPath: string;
+    readonly workspace?: WorkspaceRepositoryContext;
+    readonly checkCommand: string;
+    readonly mode: CheckBeforeMode;
+    readonly intent: 'run' | 'fix';
+    readonly isCommitEnabled: boolean;
+    readonly isAutoPushEnabled: boolean;
+    readonly isWorkingTreeCleanRequired: boolean;
+    readonly preserveLogs?: boolean;
+    readonly signal?: AbortSignal;
+    readonly ownershipScope?: CoderCommitScope;
+    readonly onScopeRetained?: (scope: CoderCommitScope) => void;
+    readonly waitForPauseCheckpoint?: WaitForCoderRunPauseCheckpoint;
+    readonly onInitialCheckStarted?: () => void;
+    readonly onInitialCheckFinished?: () => void;
+    readonly onRepairCreated?: (selection: PromptSelection) => Promise<void>;
+    readonly prepareRepair: () => Promise<(selection: PromptSelection, commitScope?: CoderCommitScope) => Promise<void>>;
+};
+/**
+ * Runs the initial check, records its scoped changes and optionally executes one repair with shared feedback.
+ * Run may continue its queue after this returns; fix always exits. This service never loads or selects queued work.
+ */
+export declare function runCoderCheckRepair(options: CoderCheckRepairOptions): Promise<CoderCheckRepairResult>;

package/umd/scripts/run-codex-prompts/checks/runPromptCheckCommand.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Options for running one check command after a coding attempt.
+ */
+export type RunPromptCheckCommandOptions = {
+    command: string;
+    projectPath: string;
+    scriptPath: string;
+    logPath?: string;
+    preserveArtifactsOnSuccess?: boolean;
+    /** Cancels the same shared shell runner used for other Coder processes. */
+    signal?: AbortSignal;
+};
+/**
+ * Runs the configured check command inside the project root and returns its output.
+ */
+export declare function runPromptCheckCommand(options: RunPromptCheckCommandOptions): Promise<string>;

package/umd/scripts/run-codex-prompts/{testing/runPromptWithTestFeedback.d.ts → checks/runPromptWithCheckFeedback.d.ts}

@@ -3,29 +3,34 @@ import { type OnCoderRunStepStarted } from '../common/createCoderRunStepTracker'
 import type { PromptRunOptions } from '../runners/types/PromptRunOptions';
 import type { PromptRunResult } from '../runners/types/PromptRunResult';
 import type { PromptRunner } from '../runners/types/PromptRunner';
-import { runPromptTestCommand } from './runPromptTestCommand';
+import { runPromptCheckCommand } from './runPromptCheckCommand';
+import type { CoderPhasePersistence } from '../git/CoderPhasePersistence';
 /**
- * Options for running one prompt with optional verification feedback retries.
+ * Options for running one prompt with optional check feedback retries.
  */
-type RunPromptWithTestFeedbackOptions = PromptRunOptions & {
+type RunPromptWithCheckFeedbackOptions = PromptRunOptions & {
     runner: PromptRunner;
     promptLabel: string;
-    testCommand?: string;
+    checkCommand?: string;
     onAttemptStarted?: (attemptCount: number) => void;
+    /** Completes scoped transformations before verification inspects the content to be persisted. */
+    onBeforeCheck?: () => Promise<void>;
     /**
-     * Notified right before each implementation, testing and fixing step starts, so the caller can
+     * Notified right before each implementation, checking and fixing step starts, so the caller can
      * record the in-progress state of the prompt.
      */
     onStepStarted?: OnCoderRunStepStarted;
-    runPromptTestCommandExecutor?: typeof runPromptTestCommand;
+    runPromptCheckCommandExecutor?: typeof runPromptCheckCommand;
+    /** Shares exact phase attribution with pre-coding checks, server runs and repair-only jobs. */
+    persistence?: CoderPhasePersistence;
 };
 /**
  * Successful prompt execution result enriched with the number of attempts it took and its per-step usage breakdown.
  */
-export type RunPromptWithTestFeedbackResult = PromptRunResult & {
+export type RunPromptWithCheckFeedbackResult = PromptRunResult & {
     attemptCount: number;
     /**
-     * Ordered steps performed while producing this result (implementation, testing and fixing), each carrying
+     * Ordered steps performed while producing this result (implementation, checking and fixing), each carrying
      * its own price and duration so the finished prompt can report usage step by step.
      */
     steps: ReadonlyArray<CoderRunStep>;
@@ -33,5 +38,5 @@ export type RunPromptWithTestFeedbackResult = PromptRunResult & {
 /**
  * Runs one coding prompt and, when configured, verifies it with a shell command that can feed failures back.
  */
-export declare function runPromptWithTestFeedback(options: RunPromptWithTestFeedbackOptions): Promise<RunPromptWithTestFeedbackResult>;
+export declare function runPromptWithCheckFeedback(options: RunPromptWithCheckFeedbackOptions): Promise<RunPromptWithCheckFeedbackResult>;
 export {};

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

@@ -0,0 +1,54 @@
+/**
+ * Terminal control key of `ptbk coder run` which the user can press during a run.
+ *
+ * @private internal type of `ptbk coder` terminal controls
+ */
+export type CoderRunControlKey = 'P' | 'S' | 'X' | 'O';
+/**
+ * Meaning of one control answer, which decides how it is colored in the terminal.
+ *
+ * @private internal type of `ptbk coder` terminal controls
+ */
+export type CoderRunControlFeedbackTone = 'success' | 'info' | 'warning';
+/**
+ * Answer of the runner to one pressed control key.
+ *
+ * Every single key press produces one of these, including presses which change nothing, so the user
+ * always sees that the key was received.
+ *
+ * @private internal type of `ptbk coder` terminal controls
+ */
+export type CoderRunControlFeedback = {
+    /**
+     * Control key the answer belongs to.
+     */
+    readonly controlKey: CoderRunControlKey;
+    /**
+     * Human-readable description of what the key press did.
+     */
+    readonly message: string;
+    /**
+     * Meaning of the answer, used to color it.
+     */
+    readonly tone: CoderRunControlFeedbackTone;
+};
+/**
+ * One control answer together with how many times the very same answer was repeated in a row.
+ *
+ * Pressing one control twice can produce the identical answer, so the repeat count is what makes the
+ * second press change the rendered frame as well.
+ *
+ * @private internal type of `ptbk coder` terminal controls
+ */
+export type CoderRunControlFeedbackNotice = CoderRunControlFeedback & {
+    /**
+     * How many times this exact answer was given in a row, starting at `1`.
+     */
+    readonly repeatCount: number;
+};
+/**
+ * How long one control answer stays visible in the rich terminal UI.
+ *
+ * @private internal constant of `ptbk coder` terminal controls
+ */
+export declare const CODER_RUN_CONTROL_FEEDBACK_DURATION_MS = 5000;