@promptbook/cli 0.114.0-49 → 0.114.0-50

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/createCheckBeforeRepairPrompt.d.ts

@@ -1,9 +1,11 @@
 import type { PromptSelection } from '../prompts/types/PromptSelection';
 /**
- * Creates the one queue prompt used to repair a pre-existing project check failure.
+ * 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/runCheckBefore.d.ts

@@ -1,5 +1,6 @@
 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.
  */
@@ -23,4 +24,8 @@ export declare function runCheckBefore(options: {
     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/runPromptWithCheckFeedback.d.ts

@@ -4,6 +4,7 @@ import type { PromptRunOptions } from '../runners/types/PromptRunOptions';
 import type { PromptRunResult } from '../runners/types/PromptRunResult';
 import type { PromptRunner } from '../runners/types/PromptRunner';
 import { runPromptCheckCommand } from './runPromptCheckCommand';
+import type { CoderPhasePersistence } from '../git/CoderPhasePersistence';
 /**
  * Options for running one prompt with optional check feedback retries.
  */
@@ -12,12 +13,16 @@ type RunPromptWithCheckFeedbackOptions = PromptRunOptions & {
     promptLabel: 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, checking and fixing step starts, so the caller can
      * record the in-progress state of the prompt.
      */
     onStepStarted?: OnCoderRunStepStarted;
     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.

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

@@ -1,3 +1,4 @@
+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.
  *
@@ -22,4 +23,6 @@ export declare function createFreeDiskSpaceGuard(options: {
      * 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/resolveCoderProjectContext.d.ts

@@ -14,4 +14,6 @@ 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/runGoScript/$spawnLoggedBashScript.d.ts

@@ -10,6 +10,8 @@ type SpawnLoggedBashScriptOptions = {
     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.
      */

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/scriptExecutionLog.d.ts

@@ -18,7 +18,7 @@ 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/waitForSkippableWorldTimeDeadline.d.ts

@@ -12,4 +12,5 @@ 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

@@ -1,5 +1,6 @@
 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.
  *
@@ -17,6 +18,10 @@ export type CoderCommitScope = {
      * 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.
@@ -24,7 +29,15 @@ export type CoderCommitScope = {
  * 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): Promise<CoderCommitScope>;
+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.
  *

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>;

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

@@ -0,0 +1,11 @@
+import { type CoderTreeEntry } from './coderRepositorySnapshot';
+/** Git's real index lease, independent of the private index used by normal commit hooks/signing. */
+export type CoderIndexLease = {
+    /** Publishes exact owned entries while retaining every other staging entry and its flags. */
+    publish(entries: ReadonlyMap<string, CoderTreeEntry>, paths: ReadonlyArray<string>): Promise<void>;
+};
+/**
+ * Holds Git's standard index.lock across capture, hooks, signing and publication. A post-hoc comparison
+ * followed by update-index has a race: another git add could be overwritten between those two operations.
+ */
+export declare function withCoderIndexLease<T>(repositoryRoot: string, operation: (lease: CoderIndexLease) => Promise<T>): Promise<T>;

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

@@ -0,0 +1,6 @@
+import { type CoderTreeEntry } from './coderRepositorySnapshot';
+/**
+ * Imports an already attributed raw leaf delta into a checkout. Callers validate source quiescence and
+ * destination ownership before calling, then verify retained bytes afterward using the shared snapshot service.
+ */
+export declare function applyCoderRepositoryFileDelta(sourceRoot: string, repositoryRoot: string, entries: ReadonlyMap<string, CoderTreeEntry>, paths: ReadonlyArray<string>): Promise<void>;

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

@@ -0,0 +1,62 @@
+/** Full filesystem permissions copied from a private check result without widening access to its files. */
+export declare const CODER_FILE_PERMISSIONS_MASK = 511;
+/** Retained execution checkouts are separate repositories, including those below a selected nested project. */
+export declare const CODER_ISOLATION_WORKTREE_PATH_PATTERN: RegExp;
+/** Content and mode of one leaf of a Git tree (including symlinks and binary blobs). */
+export type CoderTreeEntry = {
+    readonly mode: string;
+    readonly objectId: string;
+};
+/** Non-destructive content/index boundary of a serialized Coder phase. */
+export type CoderRepositorySnapshot = {
+    readonly repositoryRoot: string;
+    readonly head?: string;
+    readonly tree: string;
+    readonly entries: ReadonlyMap<string, CoderTreeEntry>;
+    readonly indexEntries: ReadonlyMap<string, CoderTreeEntry>;
+    /** Includes skip-worktree/assume-unchanged flags, which can hide pre-existing content from status. */
+    readonly indexFlags: ReadonlyMap<string, string>;
+    readonly indexFingerprint: string;
+    /** Raw bytes and filesystem modes, also detecting changes hidden by Git attributes/filters. */
+    readonly workingFileHashes: ReadonlyMap<string, string>;
+    /** Git's actual initial dirtiness, independent of clean-checkout smudge/line-ending transformations. */
+    readonly dirtyPaths: ReadonlyArray<string>;
+};
+/** Literal filenames must not inherit globbing settings from the user's environment. */
+export declare const CODER_LITERAL_GIT_ENV: {
+    GIT_LITERAL_PATHSPECS: string;
+    GIT_GLOB_PATHSPECS: string;
+    GIT_NOGLOB_PATHSPECS: string;
+    GIT_ICASE_PATHSPECS: string;
+};
+/** Reads a tree using raw NUL-delimited filenames instead of Git's display quoting. */
+export declare function readCoderTree(repositoryRoot: string, tree: string, env?: Record<string, string>): Promise<Map<string, CoderTreeEntry>>;
+/** Parses either ls-tree or stage-zero ls-files output; unresolved merges cannot be persisted safely. */
+export declare function parseCoderTreeEntries(output: string): Map<string, CoderTreeEntry>;
+/** Reads an optional HEAD without treating arbitrary Git errors as an unborn branch. */
+export declare function readCoderHead(repositoryRoot: string, env?: Record<string, string>): Promise<string | undefined>;
+/** Builds a private index outside the working tree; the user's staging area is never used for snapshots. */
+export declare function withCoderSnapshotIndex<T>(repositoryRoot: string, operation: (indexPath: string) => Promise<T>, gitEnvironment?: Record<string, string>): Promise<T>;
+/** Captures retained bytes, a staged tree and the real index after the phase's owned writers have stopped. */
+export declare function captureCoderRepositorySnapshot(repositoryRoot: string, excludePaths?: ReadonlyArray<string>, gitEnvironment?: Record<string, string>): Promise<CoderRepositorySnapshot>;
+/** Hashes bytes, symlink targets and executable modes without following symlinks out of the checkout. */
+export declare function readCoderWorkingFileHashes(repositoryRoot: string, paths: ReadonlyArray<string>, objectFormat: string): Promise<Map<string, string>>;
+/**
+ * Captures ignored files for check-view retention, using the same raw byte/mode hashing as eligible content.
+ * These hashes never make ignored files eligible for an automatic Git commit.
+ */
+export declare function captureCoderIgnoredFileHashes(repositoryRoot: string, excludePaths: ReadonlyArray<string>): Promise<Map<string, string>>;
+/** Keeps explicitly ignored new Coder artifacts out of the private commit index, just as ordinary staging does. */
+export declare function isCoderGitPathIgnored(repositoryRoot: string, path: string): Promise<boolean>;
+/** Compares raw retained content, including deletions. */
+export declare function areCoderFileHashesEqual(left: ReadonlyMap<string, string>, right: ReadonlyMap<string, string>): boolean;
+/** Lists the actual content/mode delta, even when a check reverts an earlier edit back to HEAD. */
+export declare function listCoderTreeDelta(before: ReadonlyMap<string, CoderTreeEntry>, after: ReadonlyMap<string, CoderTreeEntry>): string[];
+/** Writes exact blob/mode entries, including removals, into an explicit index. */
+export declare function updateCoderIndex(repositoryRoot: string, entries: ReadonlyMap<string, CoderTreeEntry>, paths: ReadonlyArray<string>, env?: Record<string, string>): Promise<void>;
+/** Includes original user working bytes, staging entries, hidden index flags and executable-bit changes. */
+export declare function getCoderProtectedPaths(operation: CoderRepositorySnapshot, headEntries: ReadonlyMap<string, CoderTreeEntry>): ReadonlySet<string>;
+/** Refuses overlapping user work, including staged content which differs from the working file. */
+export declare function assertCoderDeltaIsOwned(operation: CoderRepositorySnapshot, paths: ReadonlyArray<string>, headEntries: ReadonlyMap<string, CoderTreeEntry>): void;
+/** Materializes immutable staged entries in a private index so recovery references also retain staged blobs. */
+export declare function captureCoderIndexTree(snapshot: CoderRepositorySnapshot): Promise<string>;

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

@@ -0,0 +1,30 @@
+import { type CoderRepositorySnapshot } from './coderRepositorySnapshot';
+/** Private content view owned exclusively by one check, sharing the snapshot/commit service's Git objects. */
+export type CoderRepositoryView = {
+    readonly directory: string;
+    readonly repositoryRoot: string;
+    readonly projectPath: string;
+    readonly isLinkedWorktree: boolean;
+    readonly before: CoderRepositorySnapshot;
+    readonly beforeIgnoredFileHashes: ReadonlyMap<string, string>;
+};
+/**
+ * Copies the selected content into a private check checkout. A lease cannot exclude an unrelated editor from
+ * the live checkout; running checks here makes attribution independent of that editor's writes. Ignored
+ * dependencies/environment files are copied too, never hard-linked to writable user files.
+ */
+export declare function createCoderRepositoryView(before: CoderRepositorySnapshot, projectPath: string, excludedPaths: ReadonlyArray<string>): Promise<CoderRepositoryView>;
+/**
+ * Imports only the private command's content/mode delta after checking the live boundary and original user
+ * ownership. The real staging area is left intact; the shared commit service persists the phase's exact tree.
+ */
+export declare function applyCoderRepositoryView(view: CoderRepositoryView, after: CoderRepositorySnapshot, operation: CoderRepositorySnapshot, retained: CoderRepositorySnapshot, excludedPaths: ReadonlyArray<string>, afterIgnoredFileHashes: ReadonlyMap<string, string>): Promise<void>;
+/**
+ * Linked check views already share objects. An unborn branch uses a shared clone whose newly written objects
+ * must be transferred before recovery refs or phase commits can reference them in the execution repository.
+ */
+export declare function retainCoderRepositoryViewSnapshot(view: CoderRepositoryView, snapshot: CoderRepositorySnapshot, repositoryRoot: string): Promise<void>;
+/** Detects unrelated live edits while the check has exclusive ownership of its private copy. */
+export declare function assertLiveCheckBoundary(before: CoderRepositorySnapshot, excludedPaths: ReadonlyArray<string>, ignoredFileHashes?: ReadonlyMap<string, string>): Promise<void>;
+/** Removes only an imported disposable copy; failed/ambiguous/interrupted views are kept for recovery. */
+export declare function removeCoderRepositoryView(view: CoderRepositoryView, originalRoot: string): Promise<void>;

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

@@ -1,3 +1,23 @@
+import { type CoderRepositorySnapshot, type CoderTreeEntry } from './coderRepositorySnapshot';
+/** Captured content to commit without checking out an earlier version or disturbing the user's index. */
+export type CoderSnapshotCommit = {
+    readonly operation: CoderRepositorySnapshot;
+    readonly before: CoderRepositorySnapshot;
+    readonly after: CoderRepositorySnapshot;
+    /** The retained working tree can already contain the following check's transformation. */
+    readonly retained: CoderRepositorySnapshot;
+    readonly excludedPaths?: ReadonlyArray<string>;
+    /** Expected live Git boundary, refreshed only by this operation's preceding local commit. */
+    readonly expectedHead?: string;
+    readonly expectedIndex?: ReadonlyMap<string, CoderTreeEntry>;
+    readonly expectedIndexFlags?: ReadonlyMap<string, string>;
+};
+/** Exact local persistence identity; callers never infer a successful commit from an arbitrary later HEAD. */
+export type CoderCommitResult = {
+    readonly commit: string;
+    readonly tree: string;
+    readonly paths: ReadonlyArray<string>;
+};
 /**
  * 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`,
@@ -14,11 +34,24 @@ export declare function commitChanges(message: string, options?: {
      * Repository-relative paths which are relevant for the current operation.
      *
      * Only these paths are staged and only they end up in the created commit, so unrelated changes of the
-     * project are left in the working tree. Everything is committed when the paths are not provided at all,
-     * while an empty list commits nothing but the file changes already staged before.
+     * project are left in the working tree. Everything is committed when the paths are not provided at all.
+     * An empty scope is a no-op; an explicitly allowed empty commit never absorbs the user's index.
      */
     relevantPaths?: ReadonlyArray<string>;
     excludePaths?: ReadonlyArray<string>;
     projectPath?: string;
     isEmptyCommitAllowed?: boolean;
-}): Promise<void>;
+    /** Cancels only this job's Git commands, hooks and remote subprocesses. */
+    signal?: AbortSignal;
+    /** Phase content, rather than the current working files, is authoritative for this commit. */
+    snapshot?: CoderSnapshotCommit;
+}): Promise<CoderCommitResult | undefined>;
+/**
+ * Pushes the current branch after a successful commit.
+ *
+ * Behavior:
+ * - Uses `git push` when upstream exists.
+ * - Uses `git push --set-upstream` on first push when upstream is missing.
+ * - Skips pushing when upstream exists and there is nothing to push.
+ */
+export declare function pushCommittedChanges(projectPath: string, agentEnv?: Record<string, string>, signal?: AbortSignal): Promise<void>;

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

@@ -3,7 +3,7 @@ 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.
+ * environment covers the Git commands of the coder, of the coding agent and of the check 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.

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

@@ -1,4 +1,6 @@
 /**
  * Pulls the latest repository changes before the next prompt starts.
  */
-export declare function pullLatestChanges(projectPath?: string): Promise<void>;
+export declare function pullLatestChanges(projectPath?: string, options?: {
+    readonly signal?: AbortSignal;
+}): Promise<void>;