@promptbook/cli 0.114.0-5 → 0.114.0-50

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

@@ -0,0 +1,14 @@
+import type { CoderRunControlFeedback } from './CoderRunControlFeedback';
+/**
+ * Applies the terminal control bound to one pressed key and describes what that key press did.
+ *
+ * This is the single place where the `P`, `S` and `X` keys are turned into runner actions, so the
+ * plain console listener and the rich terminal UI always perform the same action and always answer
+ * the user, even when the pressed control changed nothing.
+ *
+ * @param keyName Name of the pressed key as reported by the `keypress` event.
+ * @returns The answer shown to the user, or `undefined` when the key is not a control key.
+ *
+ * @private internal utility of `ptbk coder` terminal controls
+ */
+export declare function applyCoderRunControlKey(keyName: string | undefined): CoderRunControlFeedback | undefined;

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

@@ -0,0 +1,7 @@
+import type { CoderRunControlKey } from './CoderRunControlFeedback';
+/**
+ * Builds the colored badge of one control key, for example ` S `.
+ *
+ * @private internal utility of `ptbk coder` terminal controls
+ */
+export declare function buildCoderRunControlKeyBadge(controlKey: CoderRunControlKey, isBracketed?: boolean): string;

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

@@ -0,0 +1,28 @@
+import type { FreeDiskSpaceStatus } from '../../../src/cli/cli-commands/common/disk-space/FreeDiskSpaceStatus';
+/**
+ * Measures the free disk space of a run which is already in progress and requests a pause when it became critical.
+ *
+ * @private internal utility of `ptbk coder` free disk space handling
+ */
+export type FreeDiskSpaceGuard = () => Promise<void>;
+/**
+ * Creates the guard which watches the free disk space while one `ptbk coder` run is in progress.
+ *
+ * The guard runs at every pause checkpoint of the run. When the disk became critically full it reports the
+ * warning and requests a pause, so the run stops at that checkpoint instead of failing in the middle of a
+ * coding round, and continues once the user has freed some space and pressed `P`.
+ *
+ * @private internal utility of `ptbk coder` free disk space handling
+ */
+export declare function createFreeDiskSpaceGuard(options: {
+    /**
+     * Path whose filesystem is watched, usually the project the coder runs in.
+     */
+    readonly inspectedPath: string;
+    /**
+     * Whether the run may stop and wait for somebody to free the disk space, disabled by `--no-questions`.
+     */
+    readonly isAskingQuestionsEnabled: boolean;
+    /** Finite jobs can stop through their own lifecycle instead of entering the global queue pause state. */
+    readonly onCriticalDiskSpace?: (status: FreeDiskSpaceStatus) => Promise<void>;
+}): FreeDiskSpaceGuard;

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

@@ -0,0 +1,13 @@
+import type { CoderRunControlFeedback } from './CoderRunControlFeedback';
+/**
+ * Formats one control answer as a single colored terminal line.
+ *
+ * The same line is printed by the plain console listener and rendered inside the `Controls` box of the
+ * rich terminal UI, so both modes answer a pressed control key identically.
+ *
+ * @param feedback Answer of the runner to the pressed control key.
+ * @param repeatCount How many times this exact answer was given in a row, rendered from the second time on.
+ *
+ * @private internal utility of `ptbk coder` terminal controls
+ */
+export declare function formatCoderRunControlFeedback(feedback: CoderRunControlFeedback, repeatCount?: number): string;

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

@@ -1,4 +1,8 @@
 /**
  * Formats one unknown error-like value into readable text for logs and feedback.
+ *
+ * An `AuthenticationError` is reported without its stack, because its message is written for the user - it
+ * says which harness has to be signed in again and how - and the frames of a failure nobody can debug would
+ * only push those instructions out of sight.
  */
 export declare function formatUnknownErrorDetails(error: unknown): string;

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

@@ -0,0 +1,18 @@
+/**
+ * Listens for the terminal control keys while the plain console output is used.
+ *
+ * Every recognized key press is answered with one printed line when stdout is a terminal. Redirecting
+ * stdout keeps existing stdin controls working without mixing control feedback into logs.
+ * The rich terminal UI installs its own listener in
+ * [`renderCoderRunUi`](../ui/renderCoderRunUi.ts) and shares the very same key handling through
+ * [`applyCoderRunControlKey`](./applyCoderRunControlKey.ts).
+ *
+ * @private internal utility of `ptbk coder` terminal controls
+ */
+export declare function listenForCoderRunControls(): void;
+/**
+ * Backwards-compatible alias for the shared terminal controls listener.
+ *
+ * @private internal utility of `ptbk coder` terminal controls
+ */
+export declare function listenForPause(): void;

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

@@ -1,9 +1,8 @@
+import type { WorkingTreeChangesSnapshot } from '../git/workingTreeChanges';
 /**
  * Snapshot of file hashes for files that were already dirty before a coding round started.
  */
-export type ChangedFilesSnapshot = {
-    readonly changedFileHashes: ReadonlyMap<string, string>;
-};
+export type ChangedFilesSnapshot = WorkingTreeChangesSnapshot;
 /**
  * Options for normalizing line endings in files changed during one coding round.
  */

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

@@ -1,20 +1,59 @@
 import type { string_book } from '../../../src/book-2.0/agent-source/string_book';
+import { type CoderAgentRole } from '../../../src/cli/cli-commands/coder/coderAgentRole';
+import type { CoderTeamAgent } from '../team/CoderTeamAgent';
 /**
- * Agent data resolved from the optional `--agent` book file.
+ * Source and prompt-routing references resolved from an optional `--agent` book file.
  */
-export type ResolvedCoderAgent = {
+export type ResolvedCoderAgentBook = {
     /**
      * Raw source of the agent `.book` file.
      */
     readonly agentSource: string_book;
+    /**
+     * Human-readable name of the agent, as it is reported in prompt status lines and run traces.
+     *
+     * Comes from the `META FULLNAME` of the Book, or from the plain title on its first line, so it is the
+     * display name of the agent and not its normalized identifier.
+     */
+    readonly agentName: string;
+    /**
+     * Equivalent references by which a prompt may target this agent.
+     *
+     * Includes the configured path, relative path, filename, filename without `.book`, and the
+     * normalized Book title from its first line.
+     */
+    readonly agentReferences: ReadonlyArray<string>;
+};
+/**
+ * Agent data resolved from the optional `--agent` book file.
+ */
+export type ResolvedCoderAgent = ResolvedCoderAgentBook & {
+    /** Compiled TEAM schemas and a session-scoped loader for each adviser's own effective Book. */
+    readonly teamAgent: CoderTeamAgent;
+    /** Source with inheritance and imports applied, also used for the coder's agent visual. */
+    readonly agentSource: string_book;
     /**
      * Compiled system message injected into each coding prompt.
      */
     readonly systemMessage: string;
+    /** Books created during resolution, committed according to the coder's normal commit setting. */
+    readonly createdAgentBookPaths: ReadonlyArray<string>;
 };
 /**
- * Reads an optional agent `.book` file and compiles its system message for injection into coder prompts.
+ * Reads an optional agent `.book` file and prepares the references that route prompts to it.
+ *
+ * Returns `undefined` when neither an explicit path nor an execution role is provided (list has no default).
+ */
+export declare function resolveCoderAgentBook(agentBookReference: string | undefined, currentWorkingDirectory: string, options?: {
+    readonly defaultRole?: CoderAgentRole;
+}): Promise<ResolvedCoderAgentBook | undefined>;
+/**
+ * Reads the explicitly selected or command-default agent Book and compiles its system message for coder prompts.
  *
- * Returns `undefined` when no agent path is provided.
+ * Returns `undefined` when neither an explicit path nor a command default is provided.
  */
-export declare function resolveCoderAgent(agentPath: string | undefined, currentWorkingDirectory: string): Promise<ResolvedCoderAgent | undefined>;
+export declare function resolveCoderAgent(agentBookReference: string | undefined, currentWorkingDirectory: string, options?: {
+    readonly defaultRole?: CoderAgentRole;
+    readonly isInitializationAllowed?: boolean;
+    readonly signal?: AbortSignal;
+}): Promise<ResolvedCoderAgent | undefined>;

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

@@ -1,4 +1,4 @@
 /**
- * Resolves optional coding context provided inline or via a file path.
+ * Resolves project AGENTS.md on omission; explicit text, files and intentional empty values replace it.
  */
 export declare function resolveCoderContext(contextReference: string | undefined, currentWorkingDirectory: string): Promise<string | undefined>;

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

@@ -0,0 +1,19 @@
+import { type ResolvedCoderAgentBook } from './resolveCoderAgent';
+/** Read-only inputs resolved once before installations, Book initialization or execution. */
+export type ResolvedCoderProjectContext = {
+    readonly projectPath: string;
+    readonly agentBook?: ResolvedCoderAgentBook;
+    readonly context?: string;
+};
+/**
+ * Resolves single-agent execution/authoring defaults without compiling Books or creating artifacts.
+ * Execution previews use the same identity and routing. Utilities and all-agent discovery resolve
+ * only the project directory and must not call this service to manufacture a primary-agent filter.
+ */
+export declare function resolveCoderProjectContext(options: {
+    readonly projectPath: string;
+    readonly agent?: string;
+    readonly context?: string;
+    /** Fix can defer the default Book until a failed check actually needs a coding agent. */
+    readonly isDefaultAgentDeferred?: boolean;
+}): Promise<ResolvedCoderProjectContext>;

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

@@ -6,6 +6,8 @@ type ResolveInlineOrFileTextOptions = {
     readonly currentWorkingDirectory: string;
     readonly contextLabel: string;
     readonly optionName: string;
+    /** Reject missing values that unambiguously look like paths instead of sending them as prose. */
+    readonly isMissingFileAnError?: boolean;
 };
 /**
  * Resolves optional CLI text provided inline or via a file path.

package/umd/scripts/run-codex-prompts/common/runGoScript/$spawnLoggedBashScript.d.ts

@@ -0,0 +1,29 @@
+/// <reference types="node" />
+import { type ChildProcessWithoutNullStreams } from 'child_process';
+/**
+ * Input used to start one temporary logged Bash script.
+ *
+ * @private internal type of `$spawnLoggedBashScript`
+ */
+type SpawnLoggedBashScriptOptions = {
+    /** Per-invocation cwd, shared by the primary harness and its advisers. */
+    readonly projectPath?: string;
+    readonly scriptPath: string;
+    readonly logPath?: string;
+    /** Whether shell startup loads login profiles; harnesses retain the default login shell. */
+    readonly isLoginShell?: boolean;
+    /**
+     * Process which owns the temporary harness shell. Defaults to the current coder process.
+     */
+    readonly parentProcessId?: number;
+};
+/**
+ * Starts one temporary Bash script in a process tree owned by the current Node process.
+ *
+ * The wrapper watches the supplied owning process ID. When that process exits abruptly, the wrapper terminates every
+ * nested shell and harness process instead of leaving it orphaned.
+ *
+ * @private internal utility of the coding prompt runner
+ */
+export declare function $spawnLoggedBashScript(options: SpawnLoggedBashScriptOptions): ChildProcessWithoutNullStreams;
+export {};

package/umd/scripts/run-codex-prompts/common/runGoScript/$terminateLoggedBashProcessTree.d.ts

@@ -0,0 +1,11 @@
+/// <reference types="node" />
+import { type ChildProcess } from 'child_process';
+/**
+ * Stops one active temporary Bash shell together with the harness process tree it owns.
+ *
+ * Unix sends `SIGTERM` to the wrapper so its shell trap terminates the separately grouped harness job. Windows does
+ * not reliably deliver that signal to Bash, so the native `taskkill` command terminates the direct shell tree instead.
+ *
+ * @private internal utility of the coding prompt runner
+ */
+export declare function $terminateLoggedBashProcessTree(commandProcess: ChildProcess): void;

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

@@ -0,0 +1,2 @@
+/** Known wrapper/check/log artifacts shared by a round's ownership, finalization and isolated recovery. */
+export declare function buildCoderExecutionArtifactPaths(scriptPath: string): ReadonlyArray<string>;

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

@@ -0,0 +1,9 @@
+/** Original stream identity, retained independently of the dashboard projection. */
+export type LiveScriptOutputSource = 'stdout' | 'stderr' | 'team';
+/** A presentation observer returns true only while it owns terminal output. */
+type LiveScriptOutputCapture = (chunk: string, source: LiveScriptOutputSource) => boolean;
+/** Installs the dashboard's optional presentation sink and returns its disposer. */
+export declare function subscribeToLiveScriptOutput(capture: LiveScriptOutputCapture): () => void;
+/** Offers an already produced chunk to the dashboard. A display failure cannot fail a script. */
+export declare function captureLiveScriptOutput(chunk: string | (() => string), source: LiveScriptOutputSource): boolean;
+export {};

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

@@ -0,0 +1,26 @@
+/**
+ * Turns the arbitrarily chopped chunks of one shell output stream into completed lines.
+ *
+ * @private internal type of the script runners
+ */
+export type ScriptOutputLineReader = {
+    /**
+     * Returns every line which the given chunk has completed, keeping the unterminated rest for the next chunk.
+     */
+    readCompletedLines(chunk: string): readonly string[];
+    /** Reads the pending fragment without treating it as a complete protocol record. */
+    getPendingLine(): string;
+    /** Drains a final unterminated line when a presentation capture ends. */
+    flush(): string;
+};
+/**
+ * Creates a line reader for one shell output stream.
+ *
+ * A chunk boundary can fall into the middle of a line, so the unterminated rest is remembered until the next chunk
+ * completes it. Every observer of the live output therefore sees whole lines only, exactly as the finished output
+ * would contain them. One reader belongs to one stream, because interleaving `stdout` and `stderr` into a single
+ * buffer would splice two unrelated halves into one nonexistent line.
+ *
+ * @private internal utility of the script runners
+ */
+export declare function createScriptOutputLineReader(): ScriptOutputLineReader;

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

@@ -0,0 +1,2 @@
+/** Quotes one literal argument, including spaces and shell metacharacters, for a generated Bash script. */
+export declare function quoteBashArgument(value: string): string;

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

@@ -0,0 +1,2 @@
+/** Chooses a delimiter absent from Book text so untrusted instructions stay stdin data, never shell code. */
+export declare function resolveShellHereDocumentDelimiter(baseDelimiter: string, content: string): string;

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

@@ -9,10 +9,16 @@ export declare const PTBK_CODER_LOG_FILE_ENV_NAME = "PTBK_CODER_LOG_FILE";
  * without the generated script and the prompt it embeds.
  */
 export declare const SCRIPT_EXECUTION_LOG_RAW_OUTPUT_MARKER = "--- raw output ---";
+/**
+ * Environment variable that identifies the Node process responsible for a temporary harness shell.
+ */
+export declare const PTBK_CODER_PARENT_PROCESS_ID_ENV_NAME = "PTBK_CODER_PARENT_PROCESS_ID";
+/** Private stdin command asks the owning wrapper to stop its actual harness job before exiting. */
+export declare const PTBK_CODER_CANCEL_COMMAND = "PTBK_CANCEL_OWNED_HARNESS";
 /**
  * Shapes one bash invocation that optionally mirrors live script output into a temporary log file.
  */
-export declare function buildLoggedBashExecution(scriptPath: string, logPath?: string): {
+export declare function buildLoggedBashExecution(scriptPath: string, logPath?: string, isLoginShell?: boolean): {
     args: string[];
     env?: Record<string, string>;
 };

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

@@ -25,4 +25,6 @@ export declare function sleepWithCountdown(options: {
     waitKind: CoderRunWaitKind;
     isRichUiEnabled: boolean;
     uiHandle?: CoderRunUiHandle;
+    /** Stops a finite repair's retry delay immediately when it is cancelled. */
+    signal?: AbortSignal;
 }): Promise<void>;

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

@@ -54,14 +54,6 @@ export declare function waitForSkippableMilliseconds(waitToken: CoderRunSkippabl
  * 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;
 /**
  * If the execution is paused, it will wait until it is resumed.
  *

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

@@ -0,0 +1,16 @@
+import { type WorldTimeDeadlineTick } from './waitUntilWorldTimeDeadline';
+/**
+ * Waits until one wall-clock deadline has passed, or until the user skips the wait with the `S` control.
+ *
+ * This is the single way `ptbk coder` waits for a deadline the user is allowed to cut short, so every
+ * wait which shows the `S  Skip current waiting` control really reacts to it: the pacing waits between
+ * prompts, the cool-down after an error, the harness session-limit waits and the server keep-alive poll.
+ *
+ * @private internal utility of `ptbk coder` wait handling
+ */
+export declare function waitForSkippableWorldTimeDeadline(options: {
+    readonly deadlineTimeMs: number;
+    readonly pollIntervalMs: number;
+    readonly onTick?: WorldTimeDeadlineTick;
+    readonly signal?: AbortSignal;
+}): Promise<void>;

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

@@ -0,0 +1,9 @@
+import { type WorkspaceRepositoryContext } from '../../../src/cli/cli-commands/common/workspaceRepository';
+/**
+ * Owns checks, task creation, execution and persistence as one workspace job for run, server and fix.
+ * The baseline's `[^]` status excludes interrupted tasks but is not an atomic cross-process claim. This lease
+ * closes the creation/claim race without rewriting any backlog status. A stale lease needs explicit recovery.
+ */
+export declare function withCoderWorkspaceLock<T>(project: WorkspaceRepositoryContext | string, operation: () => Promise<T>, options?: {
+    readonly isNestedOwnershipAllowed?: boolean;
+}): Promise<T>;

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

@@ -0,0 +1,9 @@
+import { NotAllowed } from '../../../src/errors/NotAllowed';
+/** Persistence failures are terminal and must never cause another paid implementation attempt. */
+export declare class CoderGitOperationError extends NotAllowed {
+    readonly operation: 'commit' | 'push' | 'pull' | 'record';
+    /** Genuine validation outcome when persistence failed after the command completed. */
+    checkOutcome?: 'passed' | 'failed' | 'execution-error' | 'interrupted';
+    /** Creates a diagnostic that distinguishes an uncommitted result from a commit awaiting push. */
+    constructor(operation: 'commit' | 'push' | 'pull' | 'record', details: string);
+}

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

@@ -0,0 +1,105 @@
+import type { CoderCheckOutcome } from '../checks/CoderCheckOutcome';
+import type { CoderCommitScope } from './coderCommitScope';
+import { type CoderFinalizationFile } from './coderFinalizationFiles';
+import { type CoderRepositorySnapshot } from './coderRepositorySnapshot';
+/** Durable provenance of a locally persisted phase; Git failures never retry implementation. */
+export type CoderPhaseCommitResult = {
+    readonly phase: 'implementation' | 'repair' | 'checks' | 'finalization';
+    readonly paths: ReadonlyArray<string>;
+    readonly commit?: string;
+    readonly checkOutcome?: CoderCheckOutcome['kind'];
+    readonly attempt?: number;
+};
+/** Repository and selected-project policy, passed explicitly by finite run, server and check repair. */
+export type CoderPhasePersistenceOptions = {
+    readonly scope: CoderCommitScope;
+    readonly isCommitEnabled: boolean;
+    readonly isAutoPushEnabled: boolean;
+    readonly implementationMessage?: string;
+    readonly task?: string;
+    readonly excludedPaths?: ReadonlyArray<string>;
+    readonly signal?: AbortSignal;
+    readonly onPersisted?: (result: CoderPhaseCommitResult) => void;
+    /** Carries exact uncommitted ownership through the same finite/server/repair job. */
+    readonly onRetained?: (scope: CoderCommitScope) => void;
+    /** Existing interactive commit confirmation runs before the first actual phase commit. */
+    readonly beforePersist?: () => Promise<void>;
+};
+/**
+ * Serializes phase ownership and persists captured versions, never the dirty filenames at finalization.
+ * The caller holds the shared workspace lease. Boundary checks detect edits outside owned activity, HEAD/index
+ * drift and collisions with pre-existing user content; ambiguity stops persistence with all bytes retained.
+ */
+export declare class CoderPhasePersistence {
+    private readonly options;
+    readonly commits: CoderPhaseCommitResult[];
+    private boundary;
+    private persistedBoundary;
+    private isMutationActive;
+    private isCommitConfirmationCompleted;
+    private readonly operation;
+    private implementationBoundary?;
+    private readonly recovery;
+    private readonly excludedPaths;
+    private readonly ownedPaths;
+    private persistenceHead?;
+    private persistenceIndex;
+    private persistenceIndexFlags;
+    /** Starts before implementation (or repair PRD creation), while holding workspace ownership. */
+    constructor(options: CoderPhasePersistenceOptions);
+    /** Adopts repair authoring/Book setup performed by the same lease owner since its pre-authoring scope. */
+    adoptPreparation(): Promise<void>;
+    /** Captures a quiescent content/index boundary in the execution checkout, including nested projects. */
+    private capture;
+    /** Detects unexpected writers before handing ownership to another subprocess or status writer. */
+    assertRetained(): Promise<void>;
+    /** Refuses known Coder status/artifact writes before they can overwrite pre-existing user content. */
+    assertWritablePaths(absolutePaths: ReadonlyArray<string>): Promise<void>;
+    /** Performs boundary validation within an already owned serialized activity. */
+    private assertRetainedContent;
+    /** Owns one agent, check or Coder bookkeeping mutation, and waits for all of its writes before snapshotting. */
+    mutate<T>(operation: () => Promise<T>, phase?: CoderPhaseCommitResult['phase']): Promise<T>;
+    /**
+     * Owns a check's private content view instead of assuming every live edit during its runtime belongs to it.
+     * Execution returns a typed real outcome; boundary/import/persistence errors bypass the repair retry loop.
+     */
+    mutateCheck(execute: (projectPath: string) => Promise<CoderCheckOutcome>): Promise<CoderCheckOutcome>;
+    /** Retains partial activity output before validating ownership, even when the owned subprocess failed. */
+    private captureOwnedMutationBoundary;
+    /** Boundary immediately before a check, after status writes, normalization and the harness have finished. */
+    beforeCheck(): Promise<CoderRepositorySnapshot>;
+    /** Freezes the harness-authored version before Coder normalization/status writes and the check command. */
+    freezeImplementation(): void;
+    /** Includes known execution artifacts in Coder finalization, rather than attributing wrapper/log writes to checks. */
+    includeDurableArtifacts(paths?: ReadonlyArray<string>): Promise<void>;
+    /** Persists implementation/repair then the command delta, including a completed failing check. */
+    afterCheck(options: {
+        readonly before: CoderRepositorySnapshot;
+        readonly phase: 'pre-coding' | 'post-implementation';
+        readonly command: string;
+        readonly outcome: CoderCheckOutcome;
+        readonly attempt?: number;
+    }): Promise<ReadonlyArray<CoderPhaseCommitResult>>;
+    /** Records only Coder status/trace/normalization writes after genuinely passing checks and phase persistence. */
+    finalize(message?: string, files?: ReadonlyArray<CoderFinalizationFile>): Promise<void>;
+    /** Pushes existing local history only; a remote rejection cannot create duplicate commits. */
+    push(): Promise<void>;
+    /** Stops completion before publishing done when already persisted raw content is still dirty to Git. */
+    private assertPersistedPathsAreClean;
+    /** Reports retained operation-owned changes under no-commit without claiming unrelated user work is clean. */
+    outstandingPaths(): ReadonlyArray<string>;
+    /** Keeps failure details beside phase trees without overwriting potentially concurrent user artifacts. */
+    recordFailure(error: unknown): Promise<string | undefined>;
+    /** Original protected user boundary, supplied to the private check view before any result is applied. */
+    get operationSnapshot(): CoderRepositorySnapshot;
+    /** Current retained content together with the protected original user boundary. */
+    get currentCommitScope(): CoderCommitScope;
+    /** Known Coder wrapper/log paths never belong to a check command's transformation. */
+    get excludedArtifactPaths(): ReadonlyArray<string>;
+    /** Reserves ownership synchronously before the first await, including snapshots and Git persistence. */
+    private withOwnership;
+    /** Writes one exact phase delta using the shared commit execution and configured identity/signing. */
+    private persist;
+    /** A successful private commit updates only owned real-index entries; refresh that intentional boundary. */
+    private refreshIndexBoundary;
+}

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

@@ -0,0 +1,43 @@
+import type { CoderCommitScope } from './coderCommitScope';
+import { type CoderRepositorySnapshot } from './coderRepositorySnapshot';
+import type { CoderPhaseCommitResult } from './CoderPhasePersistence';
+/** Exact persistence plan retained before Git can fail partway through the phase chronology. */
+export type CoderPhasePersistenceRecord = {
+    readonly phase: CoderPhaseCommitResult['phase'];
+    readonly beforeTree: string;
+    readonly afterTree: string;
+    readonly retainedTree: string;
+    readonly message: string;
+    readonly paths: ReadonlyArray<string>;
+    readonly checkOutcome?: CoderPhaseCommitResult['checkOutcome'];
+    readonly attempt?: number;
+    readonly isCommitEnabled: boolean;
+};
+/** Durable original bytes/index and successive phase trees, outside the user's working tree. */
+export declare class CoderPhaseRecovery {
+    private readonly scope;
+    private readonly id;
+    private directory?;
+    private sequence;
+    /** Records content from exactly the same explicit operation scope as commit persistence. */
+    constructor(scope: CoderCommitScope);
+    /** Saves originals before any owned writer can touch them, preserving raw bytes as well as staged blobs. */
+    initialize(snapshot: CoderRepositorySnapshot): Promise<void>;
+    /** Writes original raw files and immutable staging references before the first owned process starts. */
+    private initializeFiles;
+    /** Retains immutable trees through GC and names each boundary for interruption/manual persistence recovery. */
+    record(snapshot: CoderRepositorySnapshot, phase: string, details?: {
+        readonly viewPath: string;
+        readonly checkOutcome: string;
+        readonly output: string;
+        readonly ignoredFileHashes?: ReadonlyArray<readonly [string, string]>;
+    }): Promise<void>;
+    /** Records which version belongs to which authoring phase before any local commit is attempted. */
+    planPersistence(record: CoderPhasePersistenceRecord): Promise<string | undefined>;
+    /** Updates the same plan after successful local persistence, without claiming remote synchronization. */
+    finishPersistence(path: string | undefined, result: CoderPhaseCommitResult): Promise<void>;
+    /** Preserves a failure diagnostic in a unique supported recovery location without replacing user files. */
+    recordFailure(error: unknown, commits: ReadonlyArray<CoderPhaseCommitResult>): Promise<string | undefined>;
+    /** Location included in diagnostics, without dumping private user file contents into terminal output. */
+    get path(): string | undefined;
+}

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

@@ -0,0 +1,11 @@
+import type { CoderCheckOutcome } from '../checks/CoderCheckOutcome';
+/** Subject shared by pre-coding checks and every post-implementation/recheck attempt. */
+export declare const AUTOMATIC_CHECK_CHANGES_COMMIT_MESSAGE = "chore: Automatically commit changes made by checks";
+/** Builds truthful phase/check/task metadata without promoting failed verification to a pass. */
+export declare function buildCoderCheckCommitMessage(options: {
+    readonly phase: 'pre-coding' | 'post-implementation';
+    readonly command: string;
+    readonly outcome: CoderCheckOutcome;
+    readonly task?: string;
+    readonly attempt?: number;
+}): string;

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

@@ -0,0 +1,47 @@
+import { type WorkspaceRepositoryContext } from '../../../src/cli/cli-commands/common/workspaceRepository';
+import type { WorkingTreeChangesSnapshot } from './workingTreeChanges';
+import { type CoderRepositorySnapshot } from './coderRepositorySnapshot';
+/**
+ * Working tree state captured right before one `ptbk coder` operation starts changing the project.
+ *
+ * Note: This is the single mechanism which every `ptbk coder` command uses to commit only the files relevant
+ *       for the operation it has just performed, instead of everything which happens to be changed in the project.
+ */
+export type CoderCommitScope = {
+    /**
+     * Project the operation runs in.
+     */
+    readonly projectPath: string;
+    /** Enclosing Git root used for repository-relative snapshots and pathspecs. */
+    readonly repositoryRoot?: string;
+    /**
+     * Files which were already changed before the operation started.
+     */
+    readonly snapshotBeforeOperation: WorkingTreeChangesSnapshot;
+    /** Content/index ownership boundary needed to persist successive versions of the same path. */
+    readonly repositorySnapshot?: CoderRepositorySnapshot;
+    /** Protected user boundary carried through uncommitted check/repair/queue phases of the same job. */
+    readonly ownershipSnapshot?: CoderRepositorySnapshot;
+};
+/**
+ * Captures the working tree state before one `ptbk coder` operation changes anything.
+ *
+ * The captured scope is passed to the commit of the very same operation, which then commits exactly the files
+ * this operation has created, changed, moved or deleted.
+ */
+export declare function captureCoderCommitScope(project: string | WorkspaceRepositoryContext, options?: {
+    readonly isContentSnapshotRequired?: boolean;
+    readonly excludePaths?: ReadonlyArray<string>;
+}): Promise<CoderCommitScope>;
+/**
+ * Carries proven Coder-owned content into the next no-commit phase. An unchanged filename is insufficient:
+ * new user bytes, staging entries or flags since the last retained boundary become protected user work.
+ */
+export declare function continueCoderCommitScopeOwnership(scope: CoderCommitScope, previous?: CoderCommitScope, ownedPreparationPaths?: ReadonlyArray<string>): CoderCommitScope;
+/**
+ * Resolves the repository-relative paths which one `ptbk coder` operation has really changed.
+ *
+ * Files which were already changed before the operation started and which the operation did not touch are
+ * never part of the result, so they stay in the working tree instead of being swept into the commit.
+ */
+export declare function resolveCoderCommitScopePaths(scope: CoderCommitScope): Promise<ReadonlyArray<string>>;

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

@@ -0,0 +1,14 @@
+/// <reference types="node" />
+/// <reference types="node" />
+import { type CoderRepositorySnapshot } from './coderRepositorySnapshot';
+/** A Coder status/trace candidate which is persisted before it becomes visible to queue readers. */
+export type CoderFinalizationFile = {
+    readonly path: string;
+    readonly content: Buffer;
+};
+/** Builds a candidate tree through the shared private-index service without rewriting the live task status. */
+export declare function buildCoderFinalizationSnapshot(retained: CoderRepositorySnapshot, files: ReadonlyArray<CoderFinalizationFile>): Promise<CoderRepositorySnapshot>;
+/** Publishes already persisted candidates in caller order, with the selected task status last. */
+export declare function publishCoderFinalizationFiles(retained: CoderRepositorySnapshot, files: ReadonlyArray<CoderFinalizationFile>): Promise<void>;
+/** Refuses known status/script/log writers before they can follow a user symlink or replace a special file. */
+export declare function assertCoderRegularWriterPath(repositoryRoot: string, absolutePath: string): Promise<void>;