@promptbook/cli 0.114.0-5 → 0.114.0-50

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

@@ -1,3 +1,5 @@
+import { type WorkspaceRepositoryContext } from '../../../src/cli/cli-commands/common/workspaceRepository';
+import type { CoderCommitScope } from './coderCommitScope';
 /**
  * Automatic git synchronization of the project changes made by one `ptbk coder` command.
  *
@@ -24,20 +26,36 @@ export type CoderGitSyncOptions = {
  * Note: This is the default for every command and helper which supports the git synchronization.
  */
 export declare const DISABLED_CODER_GIT_SYNC_OPTIONS: CoderGitSyncOptions;
+/**
+ * Pulls the latest repository changes and captures the working tree state before a `ptbk coder` command
+ * changes the project.
+ *
+ * The returned scope is handed over to `$commitCoderChanges` of the very same command, which then commits
+ * exactly the files this command has changed.
+ */
+export declare function $startCoderGitSync(options: {
+    readonly gitSync: CoderGitSyncOptions;
+    readonly projectPath?: string;
+    readonly workspace?: WorkspaceRepositoryContext;
+}): Promise<CoderCommitScope>;
 /**
  * Pulls the latest repository changes before a `ptbk coder` command changes the project.
  */
 export declare function $pullCoderChanges(options: {
     readonly gitSync: CoderGitSyncOptions;
     readonly projectPath?: string;
+    readonly workspace?: WorkspaceRepositoryContext;
 }): Promise<void>;
 /**
  * Commits - and when requested also pushes - the changes one `ptbk coder` command has just made.
  *
- * Note: A repository without any change is left alone instead of creating an empty commit.
+ * Note: Only the files this very command has changed are committed, everything else is left in the working tree.
+ * Note: A command which changed nothing is left alone instead of creating an empty commit.
  */
 export declare function $commitCoderChanges(options: {
     readonly gitSync: CoderGitSyncOptions;
     readonly commitMessage: string;
-    readonly projectPath?: string;
+    readonly commitScope: CoderCommitScope;
+    /** Optional explicit write set, used by long-running authoring sessions to exclude concurrent user edits. */
+    readonly relevantPaths?: ReadonlyArray<string>;
 }): Promise<void>;

package/esm/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/esm/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/esm/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/esm/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/esm/scripts/run-codex-prompts/git/commitChanges.d.ts

@@ -1,7 +1,27 @@
+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`,
- * `options.includePaths` can restrict staging, `options.onlyPaths` can restrict the commit pathspec,
+ * `options.relevantPaths` restricts both the staging and the commit to the files of the current operation,
  * `options.excludePaths` can keep temporary artifacts out of the created commit and
  * `options.isEmptyCommitAllowed` keeps a round without any file change from failing.
  *
@@ -10,9 +30,28 @@
  */
 export declare function commitChanges(message: string, options?: {
     autoPush?: boolean;
-    includePaths?: ReadonlyArray<string>;
-    onlyPaths?: ReadonlyArray<string>;
+    /**
+     * 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.
+     * 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/esm/scripts/run-codex-prompts/git/commitInitializedAgentBooks.d.ts

@@ -0,0 +1,6 @@
+import type { WorkspaceRepositoryContext } from '../../../src/cli/cli-commands/common/workspaceRepository';
+/**
+ * Commits newly initialized, non-ignored agent books before the coder's clean-tree checkpoint.
+ * Only books created by this run are eligible; existing books and unrelated changes remain outside the commit.
+ */
+export declare function commitInitializedAgentBooks(projectPath: string, createdAgentBookPaths: ReadonlyArray<string>, workspace?: WorkspaceRepositoryContext): Promise<void>;

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

@@ -1,4 +1,4 @@
 /**
  * Ensures the git working tree is clean before running the prompt.
  */
-export declare function ensureWorkingTreeClean(): Promise<void>;
+export declare function ensureWorkingTreeClean(repositoryRoot?: string): Promise<void>;

package/esm/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/esm/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>;

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

@@ -0,0 +1,5 @@
+/**
+ * Quotes one literal Git argument for its selected shell. Finite jobs use the shared Bash process-tree runner
+ * on every platform; legacy Windows callers use their existing native command shell.
+ */
+export declare function quoteGitArgument(value: string, isBashShell?: boolean): string;

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

@@ -6,6 +6,10 @@ type RunGitCommandOptions = {
     readonly cwd?: string;
     readonly env?: Record<string, string>;
     readonly isVerbose?: boolean;
+    /** A finite job cancels the same owned shell tree as its checks and harness. */
+    readonly signal?: AbortSignal;
+    /** Phase persistence must not retry a hook which may already have created a local commit. */
+    readonly isIndexLockRetryEnabled?: boolean;
 };
 /**
  * Runs one Git command and retries when the repository index is still temporarily locked.

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

@@ -0,0 +1,7 @@
+import { $runWorkspaceGit } from '../../../src/cli/cli-commands/common/workspaceRepository';
+/**
+ * Uses the shared Git service, retrying only a Windows index-open permission failure during a read-only inspection.
+ * Persistent access errors and every mutation still fail normally. Snapshot callers retain their before/after
+ * comparisons, so a retry cannot publish content which changed during capture.
+ */
+export declare function runWorkspaceGitWithIndexReadRetry(projectPath: string, argumentsList: ReadonlyArray<string>, options?: Parameters<typeof $runWorkspaceGit>[2]): Promise<string>;

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

@@ -0,0 +1,40 @@
+/**
+ * Snapshot of file hashes for files that were already dirty before one operation started.
+ *
+ * Note: This is the single source of truth about which files one `ptbk coder` operation has really changed,
+ *       used both for normalizing line endings and for committing only the relevant files.
+ */
+export type WorkingTreeChangesSnapshot = {
+    /**
+     * Hash of every dirty file at the moment the snapshot was taken.
+     *
+     * A file which was dirty but could not be hashed (a deleted file or a non-regular file) is stored as `null`,
+     * so it can be told apart from a file which was not dirty at all.
+     */
+    readonly changedFileHashes: ReadonlyMap<string, string | null>;
+};
+/**
+ * Captures hashes for files that are dirty before one operation starts.
+ */
+export declare function captureWorkingTreeChangesSnapshot(projectPath: string): Promise<WorkingTreeChangesSnapshot>;
+/**
+ * Lists the repository-relative paths which really changed since the snapshot was taken.
+ *
+ * A file which was already dirty before and was not touched afterwards is not listed, so the result contains
+ * exactly the files changed by the operation which the snapshot wraps.
+ */
+export declare function listFilesChangedSinceSnapshot(projectPath: string, snapshot: WorkingTreeChangesSnapshot): Promise<ReadonlyArray<string>>;
+/**
+ * Lists dirty tracked files and untracked files in the working tree.
+ */
+export declare function listWorkingTreeChangedFiles(projectPath: string, env?: Record<string, string>): Promise<ReadonlyArray<string>>;
+/**
+ * Reads the content hash of one repository-relative working tree file.
+ *
+ * @returns Hash of a regular file, otherwise `null` for a deleted or non-regular file.
+ */
+export declare function readWorkingTreeFileHash(projectPath: string, relativePath: string): Promise<string | null>;
+/**
+ * Normalizes Git output paths for internal matching.
+ */
+export declare function normalizeGitFilePath(filePath: string): string;

package/esm/scripts/run-codex-prompts/isolation/coderIsolationArtifacts.d.ts

@@ -0,0 +1,16 @@
+import type { CoderCommitScope } from '../git/coderCommitScope';
+import type { PromptSelection } from '../prompts/types/PromptSelection';
+/** Original artifact content, checked before isolated writers run or publish into supported durable locations. */
+export type CoderIsolationArtifactBoundary = {
+    readonly repositoryRoot: string;
+    readonly objectFormat: string;
+    readonly paths: ReadonlyArray<string>;
+    readonly hashes: ReadonlyMap<string, string>;
+};
+/** Captures even ignored original logs and refuses pre-existing staged/unstaged artifacts before execution. */
+export declare function captureCoderIsolationArtifacts(scope: CoderCommitScope, selection: PromptSelection): Promise<CoderIsolationArtifactBoundary | undefined>;
+/**
+ * Eligible artifacts travel in the execution commits and integration. Ignored or failed-round artifacts are
+ * copied back into their existing durable locations before cleanup; unexpected original edits are retained.
+ */
+export declare function preserveCoderIsolationArtifacts(boundary: CoderIsolationArtifactBoundary | undefined, executionRoot: string): Promise<void>;

package/esm/scripts/run-codex-prompts/isolation/coderIsolationIgnoredFiles.d.ts

@@ -0,0 +1,18 @@
+import type { CoderCommitScope } from '../git/coderCommitScope';
+/** Ignored execution output is retained without making it eligible for an automatic commit. */
+export type CoderIsolationIgnoredBoundary = {
+    readonly repositoryRoot: string;
+    readonly objectFormat: string;
+    readonly original: ReadonlyMap<string, string>;
+    readonly executionBefore?: ReadonlyMap<string, string>;
+    readonly excludedPaths: ReadonlyArray<string>;
+};
+/** Captures the original ignored result before creating a worktree or running any owned writer. */
+export declare function captureCoderIsolationIgnoredFiles(scope: CoderCommitScope, excludedPaths: ReadonlyArray<string>): Promise<CoderIsolationIgnoredBoundary | undefined>;
+/** Establishes the actual execution baseline; original-only ignored files are never inferred as deletions. */
+export declare function beginCoderIsolationIgnoredFiles(boundary: CoderIsolationIgnoredBoundary | undefined, executionRoot: string): Promise<CoderIsolationIgnoredBoundary | undefined>;
+/**
+ * Retains only proven execution changes to ignored output before worktree removal. The existing isolation
+ * environment policy and known artifact retention stay separate, and concurrent original edits stop cleanup.
+ */
+export declare function preserveCoderIsolationIgnoredFiles(boundary: CoderIsolationIgnoredBoundary | undefined, executionRoot: string): Promise<void>;

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

@@ -5,4 +5,4 @@ import type { CoderIsolationWorktree } from './CoderIsolationWorktree';
  * The copy is intentionally a snapshot: changing the environment inside the worktree never leaks
  * back into the project the coder was started from.
  */
-export declare function copyCoderIsolationEnvironment(worktree: CoderIsolationWorktree): Promise<void>;
+export declare function copyCoderIsolationEnvironment(worktree: CoderIsolationWorktree, isolatedProjectPath?: string): Promise<void>;

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

@@ -7,6 +7,8 @@ type CreateCoderIsolationWorktreeOptions = {
      * Absolute path of the project the coder was started from.
      */
     readonly projectPath: string;
+    /** Enclosing Git root, which can differ from the requested project directory. */
+    readonly repositoryRoot?: string;
     /**
      * Name of the isolated task, for example `2026-07-0700-ptbk-coder-timing`.
      */
@@ -15,8 +17,7 @@ type CreateCoderIsolationWorktreeOptions = {
 /**
  * Creates one temporary git worktree with its own branch and its own copy of the project environment.
  *
- * Leftovers of an earlier run of the same task are removed first so that a repeated task never fails
- * on an already existing worktree directory or branch.
+ * Existing recoverable branches/worktrees require explicit recovery and are never erased on a repeated task.
  */
 export declare function createCoderIsolationWorktree(options: CreateCoderIsolationWorktreeOptions): Promise<CoderIsolationWorktree>;
 export {};

package/esm/scripts/run-codex-prompts/isolation/mapProjectReferenceToWorktree.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Rebinds an absolute reference inside a project/repository to its worktree copy. Relative references
+ * already resolve against the execution project; explicit references outside that checkout remain explicit.
+ */
+export declare function mapProjectReferenceToWorktree(reference: string | undefined, originalProjectPath: string, worktreeProjectPath: string): string | undefined;

package/esm/scripts/run-codex-prompts/isolation/mergeCoderIsolationWorktree.d.ts

@@ -1,4 +1,5 @@
 import type { CoderIsolationWorktree } from './CoderIsolationWorktree';
+import { type CoderRepositorySnapshot } from '../git/coderRepositorySnapshot';
 /**
  * Outcome of merging one isolated task back into the branch the coder runs on.
  */
@@ -14,11 +15,10 @@ export type CoderIsolationMergeResult = {
 /**
  * Merges the isolated task back into the branch the coder runs on.
  *
- * The merge is squashed so that the isolated task produces exactly one commit on the original branch,
- * exactly like a task processed without `--isolate`. The changes are only staged here; the caller
- * creates the commit so that the prompt status update becomes part of the very same commit.
+ * Fast-forward integration preserves implementation/check/finalization history exactly as verified in
+ * the execution checkout. Diverged or overlapping work is retained for manual integration.
  *
- * A failed merge never leaves the original working tree in a conflicted state and is reported back
+ * A refused fast-forward leaves the original working tree untouched and is reported back
  * instead of thrown, because a merge failure must not stop the coder from processing the next task.
  */
-export declare function mergeCoderIsolationWorktree(worktree: CoderIsolationWorktree): Promise<CoderIsolationMergeResult>;
+export declare function mergeCoderIsolationWorktree(worktree: CoderIsolationWorktree, original?: CoderRepositorySnapshot, signal?: AbortSignal): Promise<CoderIsolationMergeResult>;

package/esm/scripts/run-codex-prompts/isolation/preserveCoderIsolationRecovery.d.ts

@@ -0,0 +1,3 @@
+import type { CoderIsolationWorktree } from './CoderIsolationWorktree';
+/** Keeps durable phase/persistence records before Git removes an integrated worktree's private Git directory. */
+export declare function preserveCoderIsolationRecovery(worktree: CoderIsolationWorktree): Promise<void>;

package/esm/scripts/run-codex-prompts/isolation/runIsolatedPromptRound.d.ts

@@ -3,8 +3,8 @@ import type { RunPromptRoundOptions } from '../main/runPromptRound';
  * Runs one prompt round inside a temporary git worktree and merges the result back afterwards.
  *
  * This is the `--isolate` counterpart of `runPromptRound`, so it accepts exactly the same input:
- * - The coding agent, its verification command and the round commit all happen inside the worktree.
- * - A verified task is squash-merged back into the branch the coder runs on and the worktree is deleted.
+ * - The coding agent, its check command and the round commit all happen inside the worktree.
+ * - Verified phase commits are fast-forwarded back into the caller's branch and the worktree is deleted.
  * - A task which cannot be merged is recorded as failed in the original project and its worktree is kept,
  *   without stopping the coder from processing the next task.
  * - A task whose round fails keeps its worktree too, so the work of the failed round can still be inspected.

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

@@ -7,6 +7,8 @@ export type FindUnwrittenPromptsOptions = {
      * @default 0
      */
     readonly priority?: number;
+    /** Resolved project directory supplied by the CLI. */
+    readonly projectPath?: string;
 };
 /**
  * Lists and prints all prompt sections that still need to be authored (contain `@@@` placeholder).

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

@@ -0,0 +1,22 @@
+import { type PriorityFilterInput } from '../prompts/priorityFilter';
+import type { PromptRunnerIdentity } from '../prompts/isPromptCompatibleWithRunner';
+/**
+ * Options which select the ready prompts listed by `ptbk coder list`.
+ *
+ * @public exported from `@promptbook/cli`
+ */
+export type ListCoderPromptsOptions = PriorityFilterInput & {
+    /** Resolved project directory supplied by the CLI. */
+    readonly projectPath?: string;
+    /**
+     * Optional harness, model and Book-agent selection used to omit prompts routed to other runners.
+     */
+    readonly promptRunnerIdentity?: PromptRunnerIdentity;
+};
+/**
+ * Lists ready, fully authored coding prompts in descending priority groups without starting a coding harness.
+ *
+ * @returns The number of prompts printed.
+ * @public exported from `@promptbook/cli`
+ */
+export declare function listCoderPrompts(options?: ListCoderPromptsOptions): Promise<number>;

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

@@ -0,0 +1,18 @@
+import type { RunOptions } from '../cli/RunOptions';
+import { type PromptRunnerSelectionOptions } from './resolvePromptRunner';
+/** Resolves the same Book, harness, team bridge and attribution for queued and check-repair rounds. */
+export declare function prepareCoderPromptExecution(options: Pick<RunOptions, 'agent' | 'noCommit' | 'dryRun' | 'workspace'> & PromptRunnerSelectionOptions & {
+    readonly projectPath: string;
+}, preparation?: {
+    readonly isCommittingInitializedBooks?: boolean;
+    readonly signal?: AbortSignal;
+}): Promise<{
+    runner: import("../runners/types/PromptRunner").PromptRunner;
+    resolvedCoderAgent: import("../common/resolveCoderAgent").ResolvedCoderAgent | undefined;
+    runnerMetadata: {
+        agentName: string | undefined;
+        runnerName: string;
+        modelName?: string | undefined;
+    };
+    actualRunnerModel?: string | undefined;
+}>;

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

@@ -1,12 +1,7 @@
+import type { PromptRunnerHarnessName } from '../../../src/cli/cli-commands/common/promptRunnerCliOptions';
 import type { RunOptions } from '../cli/RunOptions';
+import type { PromptRunnerMetadata } from '../common/PromptRunnerMetadata';
 import type { PromptRunner } from '../runners/types/PromptRunner';
-/**
- * Runner metadata used in prompt status lines.
- */
-type RunnerMetadata = {
-    runnerName: string;
-    modelName?: string;
-};
 /**
  * Subset of `RunOptions` which decides which prompt runner is created and how it is labeled.
  *
@@ -20,7 +15,10 @@ export type PromptRunnerSelectionOptions = Pick<RunOptions, 'agentName' | 'model
 type PromptRunnerResolution = {
     runner: PromptRunner;
     actualRunnerModel?: string;
-    runnerMetadata: RunnerMetadata;
+    /**
+     * Harness half of the run metadata; the optional Book agent is added by the caller which resolves it.
+     */
+    runnerMetadata: PromptRunnerMetadata;
 };
 /**
  * Resolves the configured prompt runner together with status-line metadata.
@@ -28,4 +26,14 @@ type PromptRunnerResolution = {
  * @private function of runCodexPrompts
  */
 export declare function resolvePromptRunner(options: PromptRunnerSelectionOptions): PromptRunnerResolution;
+/**
+ * Uses the current flagship when no model is selected, while preserving explicit overrides.
+ *
+ * `--model default` keeps the harness's own configured model where supported. Gemini, Qwen and Cline
+ * require a concrete model in their adapters, so the sentinel selects their shared default instead.
+ * Read-only previews use the same policy without constructing a harness runner.
+ *
+ * @private internal utility of Coder execution and previews
+ */
+export declare function resolveRunnerModel(agentName: PromptRunnerHarnessName, providedModel?: string): string | undefined;
 export {};

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

@@ -0,0 +1,24 @@
+import type { WorkspaceRepositoryContext } from '../../../src/cli/cli-commands/common/workspaceRepository';
+import type { NormalizedQuestionsCliOptions } from '../../../src/cli/cli-commands/common/questionsCliOptions';
+import type { NormalizedPromptRunnerCliOptions } from '../../../src/cli/cli-commands/common/promptRunnerCliOptions';
+import type { ResolvedCoderProjectContext } from '../common/resolveCoderProjectContext';
+import { type CoderCheckRepairResult } from '../checks/runCoderCheckRepair';
+/** Resolved finite check-repair inputs. Queue limits, filters and keep-alive state are intentionally absent. */
+export type CoderFixOptions = NormalizedPromptRunnerCliOptions & NormalizedQuestionsCliOptions & {
+    readonly workspace: WorkspaceRepositoryContext;
+    readonly projectContext: ResolvedCoderProjectContext;
+    readonly dryRun: boolean;
+    readonly checkCommand: string;
+    readonly agent?: string;
+    readonly context?: string;
+    readonly preserveLogs: boolean;
+    readonly waitAfterError: number;
+    readonly signal?: AbortSignal;
+};
+/** Validates fix's shared execution policy without exposing a queue-mode or interrupted-backlog escape hatch. */
+export declare function validateCoderFixOptions(options: Omit<CoderFixOptions, 'workspace' | 'projectContext'>): void;
+/**
+ * Checks and repairs one project, then returns an explicit outcome. No ordinary queue module is loaded or called.
+ * Both initial verification and repair use the very same service used by run's check-before phase.
+ */
+export declare function runCoderFix(providedOptions: CoderFixOptions): Promise<CoderCheckRepairResult>;

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

@@ -1,19 +1,20 @@
 import type { RunOptions } from '../cli/RunOptions';
 import type { CliProgressDisplay } from '../common/cliProgressDisplay';
 import type { WaitForCoderRunPauseCheckpoint } from '../common/CoderRunPauseCheckpoint';
+import type { PromptRunnerMetadata } from '../common/PromptRunnerMetadata';
+import type { CoderCommitScope } from '../git/coderCommitScope';
 import type { PromptSelection } from '../prompts/types/PromptSelection';
 import type { PromptRunner } from '../runners/types/PromptRunner';
 import type { CoderRunUiHandle } from '../ui/renderCoderRunUi';
+/** Execution policy for one selected task; no queue, watcher or priority state is required. */
+export type PromptRoundExecutionOptions = Pick<RunOptions, 'workspace' | 'projectPath' | 'checkCommand' | 'preserveLogs' | 'thinkingLevel' | 'waitForUser' | 'waitAfterError' | 'noCommit' | 'normalizeLineEndings' | 'autoMigrate' | 'allowDestructiveAutoMigrate' | 'autoPush' | 'isIsolated' | 'agentName' | 'model' | 'agent' | 'context' | 'projectContext'>;
 /**
  * Input required to execute one prompt-processing round.
  */
 export type RunPromptRoundOptions = {
-    options: RunOptions;
+    options: PromptRoundExecutionOptions;
     runner: PromptRunner;
-    runnerMetadata: {
-        runnerName: string;
-        modelName?: string;
-    };
+    runnerMetadata: PromptRunnerMetadata;
     nextPrompt: PromptSelection;
     promptLabel: string;
     resolvedCoderContext?: string;
@@ -29,10 +30,19 @@ export type RunPromptRoundOptions = {
      * when the round is isolated through `--isolate`.
      */
     projectPath?: string;
+    /** Explicit durable artifact location when a temporary execution worktree will be deleted. */
+    artifactsProjectPath?: string;
+    /** Scope captured before check-repair authoring and lazy Book initialization. */
+    commitScope?: CoderCommitScope;
+    /** Last retained no-commit phase of this same job, never an unrelated worker's dirty-file list. */
+    ownershipScope?: CoderCommitScope;
+    onScopeRetained?: (scope: CoderCommitScope) => void;
+    /** Cancels only this round's owned subprocesses and retry waits. */
+    signal?: AbortSignal;
 };
 /**
  * Runs one prompt round from prompt construction through commit or failure logging.
  *
  * @private function of runCodexPrompts
  */
-export declare function runPromptRound({ options, runner, runnerMetadata, nextPrompt, promptLabel, resolvedCoderContext, resolvedAgentSystemMessage, isRichUiEnabled, progressDisplay, uiHandle, waitForRequestedPause, projectPath, }: RunPromptRoundOptions): Promise<void>;
+export declare function runPromptRound(options: RunPromptRoundOptions): Promise<void>;